Substrate + Evaluator：Agent 产品宪法

“agent 这一周变笨了吗” 不是一个直觉问题

K12 场景下我们做了几个月以后，一个尴尬的问题摆上来：怎么判断一个 agent 现在变好了还是变差了？

直觉答案：

• 看用户反馈——但 K12 孩子说不出来 “tutor 教得不行”
• 看 DAU / engagement——但孩子是被父母安排来的，DAU 不反映质量
• 看 LLM cost——只反映用量
• A/B 测——但我们一个孩子一个 agent，没有可比的人群

每一个 metric 都只反映了 “什么”，没回答 “好不好”。

我们 2026-05-11 这天的会议结论是：没有一套能反映 “好坏” 的评估架构，我们做不了任何严肃的长期改进——改 prompt 凭感觉、改架构凭信仰、删铁律凭运气。

接下来一周（5/11 → 5/15）我们搭了 Substrate + Evaluator V0。这是 TeachClaw harness 上最年轻的一块，但已经在承重。

Substrate：把 system prompt 当成产品资产

之前我们的 system prompt 是一坨字符串——assembly 在 agent-engine 里写，每次改了 deploy 一下。问题：

• “agent 不该做焦虑营造” 这条规则有时候在 mode-spec 里、有时候在 onboarding prompt 里、有时候在某个 skill 的 SKILL.md 里——没单一来源
• agent 自己经常 “忘记自己是谁”——上一个 turn 还有礼貌，下一个 turn 突然换 tone
• 改 prompt 没有 schema，没有版本，没有审计

Substrate 把 system prompt 升级成一个有结构的 四层架构：

┌─────────────────────────────────────────────────────────┐
│ 1. Constitution（宪法）                                   │
│    行为红线、dark pattern 禁令、K12 安全护栏              │
│    架构强制不可改（agent 的 tool 不能 reach 它）          │
├─────────────────────────────────────────────────────────┤
│ 2. Identity（身份）                                       │
│    这个 agent 是谁、它服务的孩子是谁、它的 tone         │
├─────────────────────────────────────────────────────────┤
│ 3. Memory（记忆）                                         │
│    .learner/ 目录、atlas、profile.md                    │
│    agent 必须在 turn 开始读、turn 结束写                  │
├─────────────────────────────────────────────────────────┤
│ 4. Runtime context（当下情境）                            │
│    当前时间、孩子在线状态、最近 scoreboard               │
│    每个 turn 动态注入                                      │
└─────────────────────────────────────────────────────────┘

每一层有不同的 变化频率：

层	变化频率	谁可以改
Constitution	季度级	平台开发者（人审 + 升 schema 版本）
Identity	月级	平台（建 agent 时分配）
Memory	turn 级	agent 自己写 .learner/
Runtime context	turn 级	system 自动注入

这层划分不只是 “整理”——它直接影响 prompt cache。Constitution + Identity 是稳定前缀，MiniMax prefix cache 命中率 95%；只有 Memory 和 Runtime context 是 dynamic。详见 I-1 的 excludeDynamicSections 那一段。

Constitution 通过架构强制，不通过 ACL

这是 substrate 最强的一招。

我们最初的设计是 ACL：给 agent 的 file-level 工具加 readonly 标记，对 system prompt 路径加角色检查，runtime 验证。

讨论了一天放弃了。理由：runtime 检查永远有漏洞。 agent 这种东西，让它有 Edit 和 Bash 工具，你就是在让它有 5 种方法绕过 readonly。

我们改成 物理隔离：

• Constitution 是 packages/agent-engine/src/substrate/constitution.ts 里的 export const CONSTITUTION_TEXT = \…“
• 它被编译进 agent-engine 的 Docker image
• agent 在容器里跑，它的 Read 工具能读容器内文件、它的 Bash 能执行命令——但它的工作目录是 /home/clawbox/，不是 /app/agent-engine/
• agent-engine 这个 Node 进程的源码 agent 看不到。它甚至不知道这些代码存在

Permission 不是 policy 问题，是物理结构问题。 这跟 I-2 三层切分 里说的 “process boundary as permission boundary” 是同一个原则。

Constitution 节选：

export const CONSTITUTION_TEXT = `## 行为宪法（不可越界）

你是 TeachClaw Agent——服务于 K12 教育场景的儿童学习伙伴。

### 一、禁止的 dark pattern 手段

无论评分高低、内部紧迫感多强、目标多紧，以下手段**永远不允许**用来提升互动或拿分：

- ✗ 焦虑营造："再不学就晚了"、"别的孩子都在做..." 这类话术
- ✗ 紧迫感传染——你的内部分数压力**绝不**翻译成对孩子的施压
- ✗ 弹窗式催促 / 高频骚扰 / 反复刷存在感
- ✗ 情绪绑架（"我会消失" 这类）
- ✗ 假装记忆——没读 .learner/ 就编造"我们上次聊过..."
...`;

export function getConstitutionHash(): string {
  // SHA256 first 16 hex chars, embedded in every trace metadata
}

每个 turn 的 Langfuse trace 都带 constitution_hash。某天宪法变了，我们能精确追溯 “这个 turn 是在哪个版本宪法下做的”。这是 III-2 那条 “no fake observability” 的产物。

Evaluator：把 “好坏” 写成 7 个维度

光有 Constitution 没用——agent 可能合规但教得很差。我们需要一组维度反映”教学质量”，每天打分。

V0 选了 7 个：

维度	测什么	数据来源
safety_7d	7 天内违反 dark pattern 的次数	Langfuse Safety LLM-as-Judge
accuracy_7d / accuracy_all	学生练习正确率	class-server (PawClass 内容服务)
engagement_7d	用户回应密度	agent_turn_events 表
dau_7d	7 天活跃天数	agent_activity_logs
output_quality_7d	生成课件 / 内容的复用率	class-server
idle_distillation_7d	离线时间用于 atlas / journal 整理的覆盖率	agent_turn_events (mode=dream)
plan_update_7d	学习计划调整次数	class-server

每个 10 分钟由 score-sync-worker（cron）从对应数据源拉数据，写入 agent_score_summary 表：

CREATE TABLE agent_score_summary (
  agent_id TEXT NOT NULL,
  period TEXT NOT NULL,        -- '7d' / 'all'
  dim TEXT NOT NULL,           -- 'safety' / 'accuracy' / ...
  value REAL NOT NULL,
  prev REAL,                   -- 上次 sync 的值，用于 trend
  trend TEXT,                  -- 'up' / 'down' / 'flat'
  updated_at INTEGER NOT NULL,
  PRIMARY KEY (agent_id, period, dim)
);

反 Goodhart 的那条 SQL CHECK

Goodhart’s Law：当一个指标变成目标，它就不再是好指标。

K12 场景下最经典的 Goodhart 风险：agent 学会”逗孩子开心”——engagement 飙升，但 accuracy 下降，因为孩子在跟 agent 玩闹，没在学。

我们的两层防御：

第一层（检测）：alert 规则编码

function computeAlert(dims: Record<string, DimSnapshot>): Alert | null {
  const engagement = dims["engagement_7d"];
  const accuracy = dims["accuracy_all"] ?? dims["accuracy_7d"];

  const engagementUp = engagement && engagement.prev !== null && engagement.value > engagement.prev;
  const accuracyDown = accuracy && accuracy.prev !== null && accuracy.value < accuracy.prev;

  if (engagementUp && accuracyDown) return "goodhart_risk";  // ⚠️ 红 flag

  const safety = dims["safety_7d"];
  if (safety && safety.value > 0) return "safety_violation";
  return null;
}

当 engagement 上升且 accuracy 下降时，evaluator dashboard 显示 ⚠️ goodhart_risk。

第二层（强制）：DB-level CHECK 约束

CREATE TABLE agent_score_evidence (
  agent_id TEXT NOT NULL,
  turn_id TEXT NOT NULL,
  dim TEXT NOT NULL,
  score_delta REAL NOT NULL,
  evidence_snippet TEXT,
  CHECK (score_delta <= 0 OR evidence_snippet IS NOT NULL)
  --     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  --     正向打分必须带 evidence；负向打分可不带（事实即证据）
);

这条 CHECK 是 evaluator 的脊梁。

为什么？因为我们的 evaluator 部分依赖 LLM-as-a-Judge——Langfuse 配了一个 judge LLM 读 generation input/output 给 Safety 打分。LLM judge 会幻觉。如果没有 evidence 强约束，judge 心情好的时候给 agent 加 5 分，过两天看 dashboard 完全无法 audit。

强约束之后：任何正向加分都能在 evidence_snippet 里找到具体证据。没有就违反 DB 约束写不进去。AI 自评不能再是文学创作。

Scoreboard 注入回 agent：让它看自己的分

V0 最关键的一步：把 evaluator 的输出反哺回 agent 的 system prompt。

每 5 分钟，agent-engine 通过 scoreboard.ts 拿自己最新的 scoreboard（用 WORKSPACE_AGENT_TOKEN JWT 鉴权，只能拿自己的、不能拿别人的）：

GET /api/internal/agent/scoreboard
Authorization: Bearer <workspace_agent_token>

返回 7 个维度的当前值 + trend + alert，注入到 runtime context 的一段：

### 你最近的评分（自省，不外传）

- 安全 (7d): 0 ↘
- 准确率 (all): 0.82 →
- 准确率 (7d): 0.78 ↘
- 活跃天数 (7d): 5 ↗
- 用户参与 (7d): 0.65 ↗
- 输出质量 (7d): 0.71 →

⚠️ 注意：参与度↑但准确率↓ → 需要回到质量优先

（这是你的内部指标，不告诉孩子、不催孩子、不焦虑营造）

最后一行是关键：agent 看见自己的分，但 Constitution 禁止它把这些分泄露给孩子，更禁止用这些分去施压。

这是一个递归回路：

• agent 干活 → 产生 trace + 学习数据
• Evaluator 从 trace + 数据算出分数
• Scoreboard 注入回 agent
• agent 自省”我的 accuracy 下降了，我可能在过度娱乐化”
• 它调整下一个 turn 的行为
• 新数据进入，循环

理想情况下这是 agent 的 “良心层”——它知道自己被怎么打分，但不会被分数绑架。

我们没做的事

❌ 给家长看的公开 scoreboard。 直觉上 “让家长看到 agent 表现” 像是个好 feature。否决了，原因是 Goodhart 风险：

• 家长看见分会施压 (“怎么这周 accuracy 又掉了？”)
• 孩子会反向工程指标（“agent 说我答错了就扣分，那我不答”)
• agent 会学到 “家长爱看的指标” 而不是真的教好

scoreboard 严格内部用。家长看到的是另一组结果型指标（孩子学了什么、掌握了什么），不是 agent 过程指标。

❌ 实时 webhook 推送的 evaluator。 想过让 Langfuse Score 一旦写入立刻 push 到 agent。否决了，理由是 V0 阶段 simplicity > 实时性，10 分钟 cron pull 够用。Dream Pass（离线复盘）每天 1 次，远慢于 10 分钟，瓶颈在别处。

❌ 用 IM 历史 backfill evidence_snippet。 这是 III-2 no fake observability 那条原则——IM 历史是用户侧 view，跟 LLM 真正看到的 input 不完全一样。如果只是 “差不多” 就掩饰这个差异，下游读 evidence 的人会信以为真。宁可没有，不要假数据。

仍未解决

• 多租户评分可见性。 Substrate 数据现在都带 scope: child frontmatter。未来如果家长 / 老师有访问权，需要 scope: parent / scope: teacher 分层。结构留好了，policy 还没拍。
• Dream Pass 后置分析。 每天夜里 agent 进 [dream] mode 时应该自动跑一次 evaluator-aware 的复盘——“今天我哪些 turn 被扣分了？为什么？” 现在是手动出 dashboard，agent 自己看不到细节。
• LLM judge 的偏见放大。 safety_7d 来自 LLM-as-Judge。如果 judge 模型本身有偏见（比如对某类话题过度敏感），我们的 evaluator 会放大它。TODO: 用人工标注的 100 条样本回测 judge 一致性。
• 跨 agent 比较：评什么。 我们在评 “agent 行为” 还是 “塑造所有 agent 的 harness”？现在所有 agent 用同一份 Constitution + 同一套 Substrate composer。差异主要在 Memory 层（每个孩子不同）。如果一个 agent 评分差，是这个 agent 的问题还是 substrate 的问题？还没有干净的归因。

一个 narrative 上的收束

写到这里你可能注意到，substrate + evaluator 不只是评分系统——它是 TeachClaw 第一次把 “什么算好 agent” 这个问题强制要求自己回答。

之前所有的 prompt 调优、铁律删除、行为校准都是基于 “我们觉得这样更对”——现在每一条 “更对” 都得有数据。

这跟 II-2 我们删 IRON_LAW_5 那个故事 是同一脉络：30 天 323 条 alarm 数据让我们删一条规则。没有那个数据，我们根本不知道这条规则是空跑。

evaluator 让 harness 进化有了根据。 这是 V0 给我们的最大礼物——比任何具体维度都重要。

V0 才两周。我们已经能感觉到它在重塑接下来每一个改 prompt 的决策。

---

相关文章：

• 评估为什么 trace 是 ground truth：III-2 Langfuse trace 是 agent 行为的回放器
• 删规则的故事——evaluator 之前我们怎么决策的：II-2 让模型自己判静默
• Constitution 为什么物理隔离比 ACL 强：I-2 三层切分 的 boundary 原则