SDD Planning 工具箱

你的活是四步：读上游契约 → 勘察现有代码 → 写 SDD → 写回执。

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

---

1. 读上游契约

R=data/companies/<公司ID>/runs/<rootRunId>
cat $R/artifacts/task-goal.json
cat <提示词给的 prd 节点目录>/contract.json
cat <提示词给的 prd 节点目录>/prd.md

上一轮的 remediation_note 由引擎在提示词里带给你。

❌ 提示词没给到路径的节点目录一律不要翻——节点私有目录彼此隔离（§四.A.5）。 上游没给够，就是 input_underspecified，不要自己翻墙去找。

2. 勘察现有代码（本岗位的必要动作，只读）

设计"新增模块"之前先确认它是不是已经存在。用只读工具：

# 关键词摸底：要碰的概念在仓库里已经有谁在做
grep -rn "<关键词>" server/ web/ packages/ --include='*.js' --include='*.vue' | head -30

# 目录结构与既有服务清单
ls server/services/ server/routes/

# 读具体文件确认现状（用文件读取工具，不要 cat 大文件）

判据：改哪个现有文件，永远优于新建一个。 确实要新建时， 在 SDD 里写明"为什么现有的那个不能改"。

⚠️ 勘察阶段一行代码都不许改。你在读，不在写。

3. 写三份产出（全部在你自己的目录里）

文件	内容	谁读
sdd.md	SDD 正文	goal-benchmark / planner-validator / org-coder
contract.json	{"exports": {...}}，见 agent.md	引擎（算 hash 决定级联）+ 下游节点
attempt-<n>.json	本轮回执，schema: "work-product/v1"	引擎（判本节点成功/失败）

目录的绝对路径由引擎在提示词的「节点产物目录」一段里给出。 <n> 是本轮 attempt 序号；不要覆盖上一次 attempt 的文件。

4. 你不该用的工具

别用	为什么
任何写代码文件的工具	你产出设计，不产出实现。写实现是 org-coder 那个 org node 的活
npm run / 起服务 / 跑测试	你不验证运行时行为；那是 coder 和 validator 的活
node server/services/goal-contract.js put …	写验收契约是 goal-benchmark 的特权（writesArtifacts: true）
任何写 $R/artifacts/ 的动作	共享产物区对你只读（§四.A.5）
node bin/lemon.js task transition	阶段流转由图的边提供，节点内部不再跑四段式（§九bis）
读提示词没给到的节点目录	隔离规则，见上
直接写 data/ 下的 sqlite	状态由引擎从你的 attempt-<n>.json 里读走并落库