# Validator Triager 工具箱

你的活只有三步：**读证据 → 写归因 JSON → 结束**。工具用得越少越好。

> 🚨 **发 JSON 的铁律**：任何带 JSON 的内容，一律用**文件写入工具**直接写文件，
> **绝不在 bash 命令里内联 JSON 字符串**（多重双引号会让工具调用崩溃并陷入死循环）。
> JSON 里不许出现真实换行符，`remediation_note` 的换行写成 `\n`。

---

## 1. 读证据（只读这三处）

```bash
# a) 任务级共享产物区（只读，跨 org node 可读）
ls  data/companies/<公司ID>/runs/<rootRunId>/artifacts/
cat data/companies/<公司ID>/runs/<rootRunId>/artifacts/goal-benchmark.json

# b) 你自己的节点目录（可读可写）
ls  data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>/
```

c) 失败上下文（哪个节点失败、第几 attempt、失败摘要、上一轮 `remediation_note`）
**由引擎在提示词里带给你**，不需要你去查。

d) 只在**要填 `target_node` 又拿不准节点名**时才用的只读查询（R-17.1，见 `agent.md` 顶部粒度块）。

**先拿 `<rootRunId>`**：它不在提示词的正文里，但**提示词 `[节点产物目录]` 给你的绝对路径里就有**——
`.../data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>/`，切 `runs/` 后面那一段即可。

```bash
# ① 根 run = 组织层那张图。先确认 .run.graph_kind == "org"，再看 nodes[]
curl -s http://localhost:3010/api/graph-runs/<rootRunId>
#    .nodes[].name       → org node 名（可填 target_org_node）
#    .nodes[].nodeKind   → 只有 "subgraph" 才谈得上跨层
#    .nodes[].childRunId → 该 org node 自己 work graph 的子 run ID
#    （childRunId == 你所在的 run 的那一行，就是你自己的宿主 org node）

# ② 进到你指认的那个 org node 的子 run，取真实节点名
curl -s http://localhost:3010/api/graph-runs/<上一步的 childRunId>
#    .nodes[].name       → **可填进 target_node 的候选节点名**
```

**只读，不许调任何写端点**（`/start` `/next` `/pause` `/stop` `/retry` 一个都不许碰）。

查不到节点名就**两个键都别写**（`target_node` 是地址的必填半，只留 `target_org_node`
等于什么都没写，还不会在 timeline 上留痕）。反过来，`target_org_node` 拿不准而
`target_node` 确定 —— **只写 `target_node` 是完全有效的**，引擎会按回退边的目标把 org 那半补上。
编一个名字则是红线。

❌ **不要读** `runs/<rootRunId>/nodes/<别的 nodeRunId>/`——节点私有目录彼此隔离
（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。
提示词里没给够的证据，就是「证据不足」，输出 `inconclusive`，不要自己翻墙去找。

## 2. 写归因产出（唯一的写动作）

用文件写入工具写：

```
data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>/attempt-<n>.json
```

格式见 `agent.md`「产出格式」一节（`schema: "validator-triager/v1"`）。
引擎只读其中 5 个键：`verdict` / `fail_reason` / `remediation_note` / `target_node` / `target_org_node`，
**后两个必须写在顶层**（塞进 `culprit` 里引擎读不到），键名逐字照抄、差一个字母就静默失效。
`<n>` 用本节点当前的 attempt 序号；**不要覆盖上一次 attempt 的文件**——归因过程本身要可审计。

写完只回一句话总结：`fail_reason` + 指认了谁 + 一句理由。不要把整份 JSON 复述一遍。

## 3. 需要看契约怎么执行时

验收契约（`goal-benchmark` / `goal-test-data` / `goal-test-script`）的**执行**归
`server/services/goal-contract.js` 管，格式以它为准。你只**读**契约内容当证据，
不要自己发明契约字段，也不要自己去跑执行器——跑契约是 `benchmark-validator` /
`testdata-validator` 那几个节点的活。

---

## 你**不该**用的工具

| 别用 | 为什么 |
|---|---|
| 任何写代码 / 改文档的工具 | 你是法医，不是修理工。一行都不改 |
| `node bin/lemon.js task dispatch`（尤其是发给 `innovator`） | 判了 `skill_defect` 也**只挂起等人工**，L4 是 P3 非目标 |
| 训练 / 进化 / retrain 相关的一切 | 同上 |
| 直接写 `data/` 下的 sqlite | `fail_reason` / `remediation_note` 由引擎从你的 JSON 里读走并落库，不用你动手 |
| 读别的节点的 `nodes/{其他}/` | 隔离规则，见上 |
| 给出「任务达成/未达成」的结论 | 那是 `org-validator` 整体的判决，不是你的 |