为什么写这个 blog
一个开场问题
Section titled “一个开场问题”如果一个 agent 不是为了回答一次问询，而是要在一个孩子的口袋里陪伴半年——你会怎么造它的骨架？
这是 TeachClaw 在过去六个月里反复被这个问题逼着改架构、删代码、重写 prompt 的来源。我们做的是 K12 的 AI 伙伴：每个孩子有一个 agent，它陪聊、上课、出题、记住他们昨天没看完的奥特曼剧情。
它不是一次性 chatbot。它必须一直在场。
为什么 “agent harness” 是一个真问题
Section titled “为什么 “agent harness” 是一个真问题”我们用 “harness” 特指让一个 LLM 在真实世界里稳定运转的工程骨架：容器编排、上下文构造、prompt cache、工具调用、可观测、评估、记忆。
它不是 prompt engineering。它也不是 “用 LangChain 接一下”。
举一个具体例子。我们 agent 的 system prompt 静态前缀目前是 74,093 bytes。如果这个前缀每个 turn 都因为 “当前时间 / git status / 工作目录” 这种 dynamic 段破掉一个字节，MiniMax 的 prefix cache 就命中不了——一个学习者每天 50 个 turn × 一个月就是 1500 次没命中。
这是 harness 在做的事：把 LLM 输入侧的稳定性当成一等架构问题。 不是后期优化，是承重墙。
类似的问题还有：
- 工具调用超时怎么办？让 turn 卡 5 分钟还是 60 秒就 timeout？timeout 之后 partial output 怎么留在 trace 里？
- 容器睡了 30 分钟，用户突然发消息——从 IM webhook 到 workspace ready 应该多久？用户能不能感知到？
- agent 看到 100 条已经处理过的消息，怎么知道哪些 “该回应” 哪些 “已读过”？
- 我们怎么知道 agent 这一周变笨了？
每一个都不是一行代码能解决，每一个都会牵动整个 harness 的层次划分。
三轴：评估、行为校准、进化
Section titled “三轴：评估、行为校准、进化”我们把当下在 harness 上的努力归到三轴。
评估（Evaluation）
Section titled “评估（Evaluation）”怎么知道 agent 做了对的事？
不是 “用户给了五星”。是把 “什么是好的 agent” 翻译成可执行的检查。
2026-05-11，我们拍板了 Substrate + Evaluator 架构：
- Substrate：四层 system prompt——constitution（行为宪法，靠架构强制不可改）、identity、memory、runtime context
- Evaluator：7 个评分维度（safety / engagement / accuracy / dau / output_quality / idle_distillation / plan_update）每 10 分钟从 Langfuse 拉一次，注入回 agent 自己的 system prompt 让它自省
- 反 Goodhart 的硬约束：DB 级 CHECK 约束——任何正向打分必须附 evidence。agent 想刷分，必须留下证据
那条 SQL CHECK 是 evaluator 的脊梁。没有它，所有 “AI 自我评分” 都是文学创作。
行为校准（Behavior Calibration）
Section titled “行为校准（Behavior Calibration）”怎么塑造 agent 在场的方式？
我们把 “请求-响应” 范式（用户问 → agent 答 → 结束）改成了 旁听陪伴：agent 能看到所有发给孩子的消息（老师群、家长、好友），可以给自己设 alarm 提醒关心，可以在心跳里翻 .learner/todo.md 找事做。
但我们停止强制它每次都开口。
2026-04-27 测试 M2.7，模型连续推荐了几部电影后，在 thinking 块里写 “不要太密集地打扰”，然后输出 “（静默）“——这是合理的社交判断，比硬规则更对。我们随后把整个 “必须每次 speak” 的规则从 substrate 删掉，substrate 从 809 行压到 565 行（-30%）。
行为校准的核心矛盾：什么时候相信模型的判断，什么时候用工程兜底？ 我们的答案在不断左右摇摆。
进化（Evolution）
Section titled “进化（Evolution）”怎么让 harness 跟着模型一起长大？
每一代新模型出来，都要重新问：之前要靠工程兜底的，现在能不能交给模型？
最近一个例子：我们的 IRON_LAW_5 曾经强制 agent “每回合检查并维护 alarm 队列”。30 天数据：总共 323 条 alarm 里，317 条是 lifecycle workflow 自动种的 [dream] seed，只有 2 条是 agent 自发设的内容 alarm。这条规则是空跑指令。删。
每一次 “删一条规则” 都是一次进化——harness 在变薄。这是好事：harness 越薄，模型本身的判断力被释放得越多。
我们写什么、不写什么
Section titled “我们写什么、不写什么”会写：
- 我们尝试过什么、放弃过什么、当前的选择是什么
- 有数据的地方贴数据：cache 命中率（修复后 95%）、静态前缀 74,093 bytes、turn timeout 5 min、30 天 323 条 alarm 数据
- 没数据的地方明确写
TODO: 待验证——不掩饰
不会写：
- 产品 UI、移动端形态、视觉品牌——那是另一个故事
- “我们踩了 X 坑然后修了” 的 bug 流水账——那在 GitHub Issues 里
我们想讨论的是 构建上的尝试和方案，不是事后总结。读者预期看到当下的判断 + 仍未解决的问题，而不是 “成功经验”。
序章（这一篇）+ 七篇起步文：
| # | 标题 | 系列 |
|---|---|---|
| 1 | 为什么选 Claude Agent SDK 作 runtime | I. Runtime |
| 2 | 容器外 vs 容器内：三层切分 | I. Runtime |
| 3 | bg-worker：重 IO 从主 turn 剥离 | I. Runtime |
| 4 | 旁听陪伴 | II. 行为校准 |
| 5 | 让模型自己判静默 | II. 行为校准 |
| 6 | Substrate + Evaluator：Agent 产品宪法 | III. 评估 |
| 7 | Langfuse trace 是 agent 行为的回放器 | III. 评估 |
四个系列每个至少 1 篇打头阵。系列 IV（进化）和后续 8-10 篇按节奏补——路线图 在那里。
Z.Q. Zhang，TeachClaw 工程负责人。博客和产品源码在不同的公开仓库——产品源码在 mrzch03/clawbox（仓库名沿用了内部项目代号 clawbox，产品本身叫 TeachClaw），博客在 mrzch03/teachclaw-blog。欢迎在 GitHub Issue / PR 修正、补数据、提反例。
我们的 harness 还在剧烈演进。一年后回看，今天写的应该有一半是错的——希望那一半被读者打脸打得越快越好。