我的实战
真实项目中的 Harness 落地经验——踩过的坑、验证过的结论。 案例索引 → 05-企业实战案例 | 工具选型 → 06-工具链与生态
实战一：AI Text Humanizer — 从零到上线的 Context Engineering
项目概况
- 技术栈：Next.js + Cloudflare Pages + D1 + NextAuth
- 时间：2026.03 启动，03-21 上线
- 角色：独立开发者，Claude Code + 喵喵（OpenClaw）辅助
- 地址：https://miaomiao.uk
Context Engineering 怎么做的
AGENTS.md / CLAUDE.md 的演化：
- 第一版只有项目结构和技术栈说明，AI 经常跑偏——生成的代码风格不一致、路径引用错误
- 后来加了架构分层约束（pages → components → lib → api 的调用方向），AI 产出质量明显提升
- 再后来把品牌设计规范（颜色、字体、间距）也写进去，前端 UI 从"每个页面一个风格"变成视觉统一
- 学到：AGENTS.md 不是写一次就完的文档，是随项目迭代的活文档——每次 AI 犯错就回去加一条规则
踩过的坑
坑 1：环境变量的噩梦
- 一开始用
.env管理所有配置（LemonSqueezy key、NextAuth secret、D1 连接信息） - 本地开发没问题，部署到 Cloudflare Pages 后环境变量丢失，服务直接挂
- 反复修了 3 次才意识到根本问题：环境变量不适合管理多环境、多服务的配置
- 最终方案：把配置全部迁到 D1 的
app_config表，彻底告别环境变量 - 对应 Harness 组件：Persistent Memory — 配置持久化在数据库而非临时环境
坑 2：支付集成的边界条件
- LemonSqueezy webhook 签名验证在 Test Mode 下跑通，但 edge case 很多：
- 用户取消订阅后的状态同步
- 重复 webhook 的幂等处理
- 测试模式和生产环境的切换
- 教训：Spec 写得越细，AI 的首次通过率越高。模糊的需求 = 反复修
管理后台的开发
- 用户管理模块（搜索、统计卡片、Top10 用量排行、积分调整）全用 Claude Code 写
- 发现 AI 写 CRUD 很快，但权限控制和边界条件容易漏——需要人工 review 这部分
- 日志/反馈长文本展开功能：AI 默认不做截断处理，超过 80 字的文本需要手动加展开逻辑
对应 Harness 组件
| Harness 组件 | 我的实践 | |-------------|---------| | Context Architecture | AGENTS.md 从"项目说明"演化为"架构约束 + 设计规范" | | Spec & Rules | 支付集成的边界条件 Spec → 首次通过率 | | Persistent Memory | 环境变量 → D1 app_config，配置持久化 | | Feedback Loops | 每次部署后看错误日志 → 回去修 AGENTS.md |
实战二：小程序矩阵 — Agent 编排的踩坑与重构
项目概况
- 技术栈：Python + CrewAI + GLM-4.5-Air + Tavily
- 目标：自动化发现小程序选题 → 调研 → PRD → UI 方案 → 开发计划
- Pipeline：Phase 0（Discovery）→ Phase 1（Research）→ Phase 2（PRD）→ Phase 3（UI）→ Phase 3.5（Code Review）→ Phase 4（Dev Plan）
最大的坑：CrewAI + GLM 模型不兼容
- 现象：CrewAI ReAct Agent 无限循环——LLM 反复输出 JSON 数组（多个工具调用）而非单个工具调用对象
- 根因：GLM 模型对 ReAct 的 JSON 解析能力是结构性问题，调参无法解决
- Token 浪费：3 轮失败 = 上千次 LLM 调用，0% 产出
- 最终方案：绕过 CrewAI 框架，直接调 API — Python 脚本 → LLM 一次直调
- 对应 Harness 洞察："Harness > Framework" — 框架是别人写好的 Harness，但不一定适合你的模型
Agent 角色专精的实践
- Discovery Agent：只负责用 Tavily 搜索热点话题，输出 Top 5 选题
- Research Agent：对单个选题深度调研（竞品分析、技术可行性）
- Review Agent v2：独立的二审 Agent，不接收前面 Agent 的上下文，纯审查
- Fix Agent：根据 Review 反馈修复问题
- 教训：每个 Agent 的职责越单一、上下文越干净，产出越稳定
- 和 Anthropic 的发现一致：Initializer / Coding / Evaluator 分角色比一个大 Agent 什么都干强
Spec 驱动的实践
- 约束写进 Prompt："纯计算 → 本地打包 1-2 天"、"需要后端 → 云开发 ≤3 天"、"超过 3 天砍功能"
- 这些约束防止 AI 每次都生成"完美但做不了"的方案
- 蓝海/红海判断：让 Agent 用 Tavily 搜竞品数量，≥5 个小程序名 → 标记红海
对应 Harness 组件
| Harness 组件 | 我的实践 | |-------------|---------| | Agent Specialization | Discovery/Research/Review/Fix 分角色，单一职责 | | Structured Execution | Phase 0→4 线性流水线，每阶段有明确输入输出 | | Feedback Loops | Phase 3.5 独立 Code Review Agent（和 Anthropic Evaluator 思路一致） | | Architectural Guardrails | 开发排期约束、零后端/纯前端优先策略 |
实战三：OpenClaw + MemMachine — Persistent Memory 的日常使用
项目概况
- OpenClaw：AI 助手平台，多渠道（飞书/微信）、多 Agent、Skills 系统
- MemMachine：语义记忆系统，GLM-4.5-Air + embedding-3，PostgreSQL + Neo4j 双存储
- 使用方式：日常所有对话、技术决策、项目进度都经过 OpenClaw
Skills 的实际价值
- 最常用的 Skills：obsidian-cli（笔记操作）、agent-reach（网络搜索）、a-share-pro（投资）
- Skills 的价值不是"让 AI 更聪明"，而是减少每次重复解释的成本
- 比如 obsidian-cli skill 定义了 vault 路径、模板格式、操作规范，AI 不用每次问"你的 Obsidian 在哪"
MemMachine 记忆系统
- 有用的场景：跨 session 的项目上下文——"上次我们做到哪了？""这个项目的决策是什么？"
- 没用的场景：简单的事实查询——"今天天气怎么样" 不需要语义记忆
- 踩坑：一开始把所有对话都存进去，噪声太多。后来改为只存"决策、偏好、教训"三类
- 对应 Harness 洞察：记忆不是越多越好，是越精准越好 — Context Architecture 的核心问题
MCP 生态的实际体验
- CookieCloud：自动同步微信读书 cookie → MCP server 读取 → 拉书摘，省去手动复制
- Agent Reach：6/15 渠道激活，Jina Reader 读网页、yt-dlp 抓视频、Tavily 搜索
- Git 提交追踪：61 个仓库的 post-commit hook，自动记录每次提交到
~/.git-commits.log - MCP 的本质：把"AI 能调用什么"标准化 — 和 API 的区别是 MCP 是给 AI 消费的，API 是给人消费的
对应 Harness 组件
| Harness 组件 | 我的实践 | |-------------|---------| | Persistent Memory | MemMachine 跨 session 记忆 + memory/*.md 文件级记忆 | | Skills | OpenClaw Skills 系统——按需加载、不污染上下文 | | MCP / Tool Protocol | CookieCloud / Agent Reach / Git hooks | | Context Architecture | 记忆分类（决策/偏好/教训）而非全量存储 |
实战四：本项目（Harness 分享）— 知识工程的 Harness
项目概况
- 目标：把 15 个"收藏夹"文件变成结构化的知识库，学会并分享
- 工具：OpenClaw 主 Agent + Sub-agent 协作，web_search（Tavily）搜索
- 过程：诊断问题 → 改造学习结构 → 搜索补充资料 → 重构目录 → 英文资料补充
Sub-agent 编排的真实经验
- 启动 sub-agent 做重构工作（创建 00-08 文件），但 9 分 55 秒后超时
- 只完成了 00-05，06-08 需要主 agent 接手
- 教训：Sub-agent 的任务粒度要小——一次做 3 个文件比一次做 9 个靠谱
- 和 OpenAI 的发现一致：任务分解（decomposition）是 Harness 的核心能力
上下文质量自我修正
- 第一版用了我自己起的"八支柱"命名
- 用户指出"要跟官方权威资料保持一致"
- 搜索 Anthropic/OpenAI/Alex Lavaee 原文，改为直接引用原文术语
- 这是 Feedback Loop 的典型案例：用户反馈 → 搜索验证 → 修正产出
112 篇资料的处理流程
- 中文资料：微信文章 → Camoufox/Jina 抓取 → 提取要点 → 归类到对应主题文件
- 英文资料：web_search 搜索 → web_fetch 提取 → 筛选高价值 → 写入文件 + 资料整理索引
- 两次失败：纯图片文章和验证码拦截文章无法处理——工具的边界 = 能力边界
对应 Harness 组件
| Harness 组件 | 我的实践 | |-------------|---------| | Context Architecture | 15 个收藏夹 → 8 个主题文件，渐进式披露 | | Agent Specialization | 主 agent + sub-agent 分工，sub-agent 超时后主 agent 接手 | | Feedback Loops | 用户反馈"术语不对" → 搜索验证 → 修正 | | Structured Execution | 诊断 → 改造 → 搜索 → 重构 → 补充，线性流水线 |
总结：我的 Harness 心得
三个最深的体感
-
框架是别人写好的 Harness，不一定是你的 Harness — CrewAI 对 GLM 不兼容，绕过框架直接调 API 反而更好。不要迷信框架，理解原理后自己搭
-
Spec 写多细，AI 就跑多稳 — 支付集成的边界条件、开发排期的约束、UI 设计规范，这些"限制"反而是 AI 产出质量的保障。对应 OpenAI 的"architectural guardrails"
-
记忆不是越多越好，是越精准越好 — 从全量存储 MemMachine 到只存决策/偏好/教训，从 15 个收藏夹到 8 个主题文件，上下文的质量 > 数量
独立开发者 vs 企业团队的差异
| 维度 | 企业 | 我 | |------|------|-----| | Agent 数量 | 数十到数百 | 1-5 个 | | Context 来源 | 知识库 + 团队规范 + CI/CD | AGENTS.md + memory 文件 | | Feedback | CI 测试 + Code Review + 监控 | 部署后看日志 + 人工 review | | 最大的优势 | 规模化 | 灵活快速迭代 | | 最大的劣势 | 协调成本 | 一个人忙不过来 |
下一步要做的
- [ ] 把 Humanizer 的 AGENTS.md 整理成可分享的模板
- [ ] 小程序 pipeline 从 CrewAI 完全迁移到直接 API 调用
- [ ] 尝试 Claude Code 的 Hooks 机制做自动化质量检查
- [ ] 本分享项目的费曼输出——3 分钟给同事讲清楚 Harness