指标树与 North Star

阶段: B5 · tool/context engineering + 指标树（Day 41-50） 标签: #metric-tree #north-star #nsm #eval-fields

今日导引（由浅入深）

B5 前两天（Day 41-42）从两个角度量化了 agent：输入面的 token 信噪比、动作面的工具反模式。

但这些散点度量需要一个组织框架，否则评审会问「你这么多数字，到底哪个代表产品价值？」今天就建这个框架——指标树：把目标分层成 输入→过程→结果，根是唯一的 North Star Metric（NSM）。在 B1→B18 曲线上，这是把「会测各种字段」升级为「有指标体系」的一步。

它直接复用 Day 36-40 的 eval harness 已产出的字段（pass/partial/unknown、step count、cost、kappa），让每个叶子都有真实代码来源。明天（Day 44）会拿其中的 context-token 叶子做预算表。

今天的「最小可判定产出」：docs/aipa/metric-tree.md——1 个 NSM + ≥8 个叶子，每叶子标注其在代码里的来源字段（离线可出，无需 key）。

1. 机理精读

定义。 指标树（metric tree）把一个产品目标自上而下分解为三层：

• 结果层（用户最终拿到的价值）、
• 过程层（产生结果的中间行为）、
• 输入层（喂进系统的资源）。

叶子是可测字段（能从日志/eval 直接读出的数），根是 North Star Metric（NSM）——单一最能代表产品价值的指标。参考 Amplitude / Reforge 的 North Star framework（成熟方法论）与 Anthropic《Demystifying evals》（2026-01）对 eval 字段的定义。

为什么是「单一」NSM。 NSM 的设计哲学是「一个组织对齐到同一个数字上」。

如果有多个并列的"北极星"，团队就会在指标间互相甩锅、局部优化（提升 A 牺牲 B）。唯一根指标强制把所有努力翻译成「它涨了多少」，其余指标全部降级为它的可分解驱动项。

对一个 agent 产品，NSM 选 task 自主完成率（无 HITL 介入下成功完成任务的占比）——它直接对应「这个 agent 能不能替人干活」，是产品价值的最浓缩表达。

为什么分三层。 三层提供了因果可操作性：结果层指标（如完成率）滞后且难直接干预；过程层（工具调用正确率、步数、重试率）是可干预的杠杆；输入层（context token 占用、工具数）是可直接配置的旋钮。

当 NSM 掉了，你顺着树往下看是哪层的叶子先动——这就是指标树相对「一堆并列 KPI」的核心价值：它编码了驱动关系。

关键权衡。 叶子的「可测」与「贴近价值」常冲突：越贴近最终价值的指标（完成率）越滞后、样本越贵；越易测的（token 数）离价值越远。

指标树的解法不是二选一，而是让易测的输入层叶子预测滞后的结果层根。所以建树时要保证每条边是「可信的驱动假设」，而非凑数。

与相邻概念的边界。 NSM 不是「最重要的一个 KPI」那么随意——它必须能被下层叶子分解和解释。

本仓把这套树落成代码（dashboard.ts），让根与叶子都绑定到 eval 报告的真实字段，而不是 PPT 上的概念框。这与 Day 44 的 context-budget 表互补：指标树管「测什么 / 怎么分层」，预算表管「输入层某个叶子（token）的配额与裁剪」。

2. 推导 / 手算 / 代码走读

代码日：走读 docs/aipa/metric-tree.md 配套的真实实现 src/agent/eval/dashboard.ts 与字段源 src/agent/eval/agentEval.ts。

• NSM 来源（根）：
  • agentEval.ts 的 TaskEvalReport.completionRate（n ? passes / n : 0，passes = judge.label==='pass' 的任务数）；
  • → 映射为 metric-tree.md 里的根「task autonomous completion」→ dashboard.ts 的 nsm.value；
  • 这条链是 seed 要求「每叶子标注来源字段」的范本。
• 结果层叶子（全部来自 agentEval.ts）：
  • partialCreditMean：部分得分均值，judge.score 的 clamp01 均值；
  • codePassRate：声明了 codeCheck 的任务的确定性通过率，无则 null；
  • unknownRate：judge 判 'unknown' 占比 = 信号不足。
• 过程层叶子：
  • judgeHumanKappa.kappa：LLM-judge 与人标的 Cohen's κ，<2 个人标时为 null；
  • 这是「判分本身可信吗」的过程指标，对应 Day 47 的判分校准。
• 输入层叶子：
  • totalCostUsd：单 run 成本 = 单位经济；
  • context-token / tool：来自 src/agent/mcp/contextAudit.ts 的 auditToolContext（Day 44 主角）。
• buildDashboard(reports) 关键行为：
  • 读 agent-evals/reports/*.json 真实报告聚合；
  • 缺数据时 value=null + note 诚实降级，绝不用占位数字冒充实测（dashboard.test.ts 有 graceful-degradation 用例）；
  • 这保证「指标树落地」是可验证的，而不是硬编码。

指标树形状（今天要写进 metric-tree.md 的结构）：

NSM: task 自主完成率 (completionRate)
├── 结果层
│   ├── partial-credit mean   ← partialCreditMean
│   ├── code-check pass        ← codePassRate
│   └── unknown rate           ← unknownRate
├── 过程层
│   ├── judge-human kappa      ← judgeHumanKappa.kappa
│   ├── 工具调用正确率          ← (per-task code/judge)
│   └── 步数 / 重试率           ← perTask 派生
└── 输入层
    ├── cost (USD/run)         ← totalCostUsd
    ├── context tokens / tool  ← auditToolContext
    └── 工具数                  ← registry.list().length

手算示例（NSM 计算）：若一次 run 跑 29 个任务，judge=pass 的有 23 个，则 completionRate = 23/29 ≈ 0.793。这正是把抽象「自主完成率」落成可算字段的样子——注意这里 23 是举例占位，真实数字需 key 跑 pnpm eval:agent 才有。

3. 今日实战

1. 把 agent 关心的指标画成 3 层树：根 = task 自主完成率；过程层 = 工具调用正确率 / 步数 / 重试率；输入层 = context token 占用 / 工具数。
2. 每个叶子映射到 eval harness（src/agent/eval/agentEval.ts）已产出的字段——按上面走读里的字段名逐一对应（partialCreditMean / codePassRate / unknownRate / judgeHumanKappa.kappa / totalCostUsd / auditToolContext）。
3. 写入 docs/aipa/metric-tree.md：一张「层 | 指标 | 含义 | 来源字段」表 + 唯一 NSM 表 + 设计原则段。
4. 全程离线——指标树是文档 + 字段映射，不调模型。

4. 今日实测 / 产出

• 离线可产出。
• docs/aipa/metric-tree.md：1 NSM + ≥8 叶子指标，每叶子标注其在 agentEval.ts 的来源字段。
• 无需 key。

（诚实状态：指标树文档与字段映射已可定稿；树上根指标的真实数值需 pnpm eval:agent 真跑才有，无 key 时 dashboard 显示 null，绝不占位。）

5. 常见误区 / 陷阱

1. 多个并列指标都叫 NSM：NSM 必须唯一，否则失去对齐作用——其余指标都是它的可分解驱动项。
2. 叶子选了不可测的概念：每个叶子必须能从代码字段直接读出（如 completionRate），否则树无法落地为 dashboard。
3. 用占位数字冒充实测：缺数据时应 value=null + note，而非编一个好看的数糊弄（dashboard.test.ts 专门测这条）。
4. 把过程/输入叶子当目标本身：降 token、提工具正确率是手段，NSM（自主完成率）才是目的；别为优化叶子牺牲根。

6. 学习资源（每条带 YYYY-MM）

• Amplitude / Reforge, North Star Framework / metric tree（经典方法论，长期有效）——指标分层与唯一 NSM 的方法论来源。
• Anthropic, Demystifying evals（2026-01）——eval 字段（pass/fail/unknown、partial credit、judge）的定义，叶子指标的语义依据。
• 本仓代码：src/agent/eval/agentEval.ts（TaskEvalReport 全部字段）、src/agent/eval/dashboard.ts（buildDashboard 聚合 + 诚实降级）、docs/aipa/metric-tree.md（产出文件）。

SOTA检查 (2026-06 更新)

• 当前主流方案：North Star + 三层指标树是成熟稳定方法论，2026 仍为产品/平台度量的默认框架；与 eval-as-experiment（Day 46）配合，根指标用受控对比来证伪。
• 是否仍 SOTA：是，无过时风险（方法论级，不依赖某模型/平台版本）。
• 过时黑名单（AVOID）：把多个并列指标都自称 NSM（破坏唯一性）；用虚荣指标（如「调用次数」）当根而非「价值代理」；缺数据时编占位数。
• 下次复查点：本方法论无版本时效问题；但其叶子绑定的 eval 字段（agentEval.ts）若新增/改名，需同步更新 metric-tree.md 的来源字段列。

衔接

• 昨天：Day 42 — tool 设计反模式（动作面质量诉求，今天抽象成叶子指标）。
• 今天：指标树 输入→过程→结果，根是唯一 NSM = task 自主完成率，每叶子绑定真实 eval 字段。
• 明天：Day 44 — context-budget 表（拿输入层的 context-token 叶子，做四类配额 + 裁剪）。