ano-kodokushi/dsh-tiered-collab

dsh-tiered-collab

把编码 Agent 的成本压到线性：分层模型路由 + 上下文隔离 + 可执行验收。

四个档位的子代理钉死在工具上（规划 / 单点逻辑 / 机械活 / 独立复核），
配套一套可复用的验收执行器，外加一份真实的失败记录。

⚠️ 先说清楚边界：这是为一款具体的 Agent 宿主（DSH）写的配置与脚本体。
里面的思路与踩坑对任何支持子代理的 Agent 框架都适用，但配置文件本身不通用。
如果你只想要治理文档那套（与产品无关），去看
agent-project-kit。

两分钟看懂它值不值

先看一条我们真实踩过的坑，你就知道这个仓库的成色：

想让规划层「只拆不写」，于是 deny 掉写文件的工具
toolFilter:
deny: [write, edit]

看起来「只拆不写」已经成立了。实测：三个负向测试全部"意外成功"，且全程无报错。

规划层用 shell 的 Set-Content 把文件写出来了，复核层把被测代码真的改掉了。

根因：deny 只拦工具名，拦不住能力。
只要 shell 可用，就等于有写权限——node foo.mjs 既是"执行验收"，
也是"运行一个可能写盘的进程"。「只读 shell」这件事在语义上不成立，任何命令白名单都堵不死。

完整 6 条踩坑与修法见下文「我们真实踩过的坑」。
docs/BOARD-archive.md 里是逐轮的原始证据。

值不值，取决于你想解决哪个问题

| 你想解决的 | 这套东西能帮上吗 |
|---|---|
| agent 说"已完成"其实没验 | ✅ verify-runner.mjs 在一次性副本里执行验收，回传真实退出码 + 真工作区 SHA1 核对 |
| 约束靠提示词，模型想绕就绕 | ✅ 四个档位的工具面在 preset 里钉死，不是写在提示词里求它遵守 |
| 一次跑偏要重跑整段长上下文 | ✅ 子代理独立上下文，Planner 只看目标、Worker 只看一张卡 |
| 就是想让 token 更省 | ⚠️ 先看下面的实测数据——在这个尺度上它没省，详见下节 |
| 项目只有几个文件 | ❌ 别用。没多少上下文可隔离，却多了拆卡/派发/复核的开销 |

实测数据（不美化）

同一个任务，单体模式 vs 分层模式各跑一遍：

| 指标 | 单体 | 分层 | 差 |
|---|---|---|---|
| 模型消息数 | 9 | 9 | 平 |
| 总用量 | 330,043 | 296,073 | −10.3% |
| 未缓存输入 | 9,063 | 10,896 | +20% |
| 等效全价 | 47,342 | 45,549 | −3.8% |

我的判读：这是平局，不是胜利。3.8% 落在单次运行的噪声里；
主会话消息数一个都没少；未缓存输入反而 +20%（每个子代理开局都要重读约束，
这些前缀互相独立、缓存复用不了）。而且这个数字不是完整账——子代理用量没算进去，
其中规划层走的是更贵的模型。

结论：在这个尺度上，分层买到的是"可能的更少返工"，不是"更省 token"。
它值不值，取决于你的任务会不会第一次就做错。

亲手验证（一分钟，不需要装宿主）

git clone https://github.com/ano-kodokushi/dsh-tiered-collab
cd dsh-tiered-collab
node scripts/validate-preset.mjs preset/agent.cordis.yml

期望输出里含 "problems": [] 与 "ok": true，退出码 0（脚本会打印完整 JSON：

{
"file": "preset\\agent.cordis.yml",
"lines": 342,
"registryRows": 34,
"denyLines": ["L192: deny: [write, edit, pwsh]", "L257: deny: [write, edit]"],
"forkHasExplicitMaxDepth": true,
"problems": [],
"ok": true
}

）。这个校验器会断言：

- 两处 deny 的不对称设计（plan_t0 含 pwsh、verify_t1 不含）
- subagent_fork 有显式 maxDepth
- 组成文件的 YAML 形状合法、没有 TAB

别跳过这步：一个组成文件写坏会让每个新会话都挂不起来——
而它是静默的，你只会看到"新模式用不了"。

它主张什么

90% 的成本优化来自「喂给模型什么」，只有 10% 来自「用哪个模型」。

所以这套东西同时做两件事：

1. 模型分层 —— 贵的 token 只花在真正的决策点上；机械活用便宜的非思考档位
2. 上下文隔离 —— 每个子代理只看它必须看的，不背整段聊天记录

边界条件（很重要）：收益来自"隔离"，所以 项目越小越不划算——
没多少上下文可隔离，却多了拆卡、派发、复核的开销。它面向的是大代码库 / 长任务。

四个档位

| 档位 | 工具名 | 做什么 | 路由 | 工具面约束 |
|---|---|---|---|---|
| T0 | plan_t0 | 只拆任务、做架构取舍，不写代码 | 强模型 + 高思考 | deny: [write, edit, pwsh] |
| T1 | work_t1 | 单点逻辑实现、单点 bug 修复 | 中档 + 高思考 | 全量 |
| T2 | work_t2 | 格式化、重命名、样板代码等机械活 | 中档 + 非思考 | 全量 |
| T1 | verify_t1 | 只看 diff 与验收标准独立判定，只看不改 | 中档 + 高思考 | deny: [write, edit] |

三条铁律

1. Planner 不写代码 —— 一旦它开始写实现，输出 token 爆炸且污染下游
2. Worker 不做规划 —— 它收到的是已定范围的原子任务，禁止"顺便"扩展
3. Verifier 不看推理过程 —— 只看最终 diff 与验收标准。看过程既费 token，又容易被流畅的推理论证说服

为什么 verify_t1 与 plan_t0 的约束不一样（这是踩坑后改的，详见下节）：
规划层不需要执行命令，所以连 shell 一起禁掉；复核层的职责就是执行验收，
禁掉 shell 等于取消这个角色。写入风险改由「副本执行协议」兜底。

可选：给机械档加一个本地档（preset-local/）

仓库里另有一个五档变体 preset-local/，它不改前四档，只把 T2 机械活拆成
「本地优先 + 云端回落」两层：

| 档位 | 工具名 | 路由 | 回落 |
|---|---|---|---|
| T2-L | work_t2_local | 本机 Ollama（如 mellum2-t2-16k，12B · 16K 上下文 · 无推理档） | 本地离线或该卡失败 → work_t2 |
| T2 | work_t2 | deepseek-v4-flash 非思考 | — |

它为什么值得单独存在：机械活失败后果最轻，且文件不出机器。
质量要求高的三档（规划 / 单点逻辑 / 复核）留在云端不动。

装它比前四档多两个约束，都是踩出来的：

1. 必须裁工具面。子代理默认带 ~58 个工具，光工具定义就约 14,629 token——
对 16K 上下文的 12B 模型是致命的，既撑爆预算也让工具选择极不可靠。
所以用 toolFilter.allow 白名单裁到 6 个：
toolFilter:
allow: [read, write, edit, grep, glob, pwsh]

（pwsh 保留是对的：这是 Worker 档，可以写文件。
deny: [pwsh] 只施加给 plan_t0 与 verify_t1。）

2. 不能写 reasoningEffort——连 "off" 都不行。
本机模型在 settings 里声明为 reasoningEfforts: false（无推理档），
而 LLM 门面层规定：推理能力为 undefined 时请求里不得出现任何档位，
否则抛 UNSUPPORTED_REASONING_EFFORT。省略即取 provider 默认。

安装

1. 装入 preset

把 preset/ 下的文件放到宿主的 agent-preset 目录（DSH 是 /.agent-presets//）：

/.agent-presets/tiered-collab/
├── preset.yml            # 名称与描述
├── agent.cordis.yml      # 组成文件：注册四个分层工具
└── skills/
└── tiered-collab/
└── SKILL.md      # 随 preset 走的协议说明

2. 设为默认（可选）

/settings.yaml
agent-presets:
default: tiered-collab
modeSelectionEnabled: true

3. 校验再启动

node scripts/validate-preset.mjs "/.agent-presets/tiered-collab/agent.cordis.yml"
期望：{"problems": [], "ok": true}

别跳过这步：一个组成文件写坏会让每个新会话都挂不起来。
这个校验器会断言四件事：

- 两处 deny 的不对称设计（plan_t0 含 pwsh、verify_t1 不含）
- subagent_fork 有显式 maxDepth
- 缩进/形状在 preset 用到的 YAML 子集内合法
- 没有 TAB（YAML 非法缩进）

我们真实踩过的坑（本仓库最有价值的部分）

下面每一条都是实测出来的，不是推演。每条都记录了现象、根因、修法。

坑 1 · deny 只拦工具名，拦不住能力 ★

写了 toolFilter: deny: [write, edit]，以为「只拆不写」已经成立。
实测：三个负向测试全部"意外成功" —— plan_t0 / verify_t1 都用 pwsh 的
Set-Content 把文件写出来了，且全程无报错。

根因：shell 是合法工具。只要它可用，就等于有写权限。
「只读 shell」这件事在语义上不成立——node foo.mjs 既是"执行验收"也是"运行一个可能写盘的进程"，
任何命令白名单都堵不死。

修法：分角色处理。规划层连 pwsh 一起 deny（它确实不需要 shell）；
复核层保留 shell，但一切执行必须走隔离执行器（见坑 6 与 scripts/verify-runner.mjs）。

坑 2 · maxDepth 不写 ≠ 无限，默认是 3

subagent_fork 那一行没写 maxDepth，preset 注释里却声称"该子代理不能再派生"。
实测：fork 链能递归到深度 3。

根因：工具 schema 里 maxDepth 的默认值是 3，不是"无限"。
不写就是放任它递归三层，与四个分层工具显式写的 maxDepth: 1 不一致。

修法：subagent_fork 补上显式 maxDepth: 1。
（顺带确认了 fork provider 声明 depthLimit: true，所以数值 maxDepth 能被真正执行，
不会在挂载时失败。）

坑 3 · 验收命令"只打印不 assert" → 缺陷全绿通过 ★

一张卡的验收命令长这样：

node script.mjs --help; Write-Host "exit=$LASTEXITCODE"

它只打印退出码，不做判定。于是 --help 根本没实现（退出码 2、stdout 零输出），
却记录为通过。

同时另一条命令用 | 把输出接成字符串再匹配——而帮助文本写在 stderr，| 只接 stdout，
所以那个变量恒为空串，"不含裸 node"恒真。

教训：没有断言的验收命令，等于没验收。
每一条验收都必须有可判定的通过标准（退出码 / 行数 / 精确字符串），不能只打印。

坑 4 · 度量口径不定义 → 三个数字都对

任务卡验收标准写「LINES=111」，没给度量命令。结果同一个文件：

| 口径 | 结果 |
|---|---|
| 某 CLI 工具按 CRLF 计行 | 119 |
| LF 计数 | 124 |
| split(/\r?\n/)（含末尾空段） | 125 |

三个都说得通，验收无法判定。

教训：数字型验收标准必须自带度量命令。本项目后来定为唯一口径 = LF 计数，
并实测确认 Get-Content .Count 比 LF 计数少 4，属不可靠口径，禁用。

坑 5 · 子代理自报不可采信

Worker 自报改动后文件 108 行；队长与复核层双口径实测 124 行。
正是这一条导致判 reject。（重试时该 Worker 主动认账并给出改动前后双口径证据。）

教训：自报数字一律独立复测。 这不是不信任模型，是流程必须这样设计。

坑 6 · 复核层没 shell → 角色取消

为了堵坑 1，把 verify_t1 的 pwsh 一起 deny 了。
副作用：复核层再也无法执行验收命令，而它的职责定义就是执行验收。

结果两张卡的复核都只能给出"拿不到 exitCode"的程序性 reject——
不是产物缺陷，而是环境让这个角色无法履职。

修法：见 scripts/verify-runner.mjs（下节）。

坑 7 · 验收命令因环境失败，而不是因产物失败

写 examples/acceptance-spec.json 时用了 node scripts/xxx.mjs —— 看着最自然不过。
实测：全部命令 CommandNotFoundException。

根因：执行器的子进程继承了宿主环境，而宿主 PATH 是空字符串（AGENTS.md §2 的那条约束）。
于是 node 不可用——验收因为环境而失败，这是最没价值的失败。

修法：执行器把自己所在的 node 目录注入子进程 PATH。
执行器本来就是用那个 node 跑起来的，把它加到 PATH 安全、无副作用：

const childPath = [dirname(process.execPath), process.env.PATH ?? ''].join(';');
spawnSync(shell, [...], { env: { ...process.env, PATH: childPath } });

这条坑的教训比修法更重要：注入 PATH 之后错误"变了" ——
从"找不到 node"变成"副本里没有 preset/agent.cordis.yml"。
这才暴露出第二个问题：执行器复制副本时漏了 preset/ 目录。
如果当时草率地把断言改成"允许失败"，就永远看不到真问题。

可跑示例：证明「校验器不是摆设」

examples/ 里有一个能真跑的示例。它挑出不需要宿主就能验证的两件事：

git clone https://github.com/ano-kodokushi/dsh-tiered-collab
cd dsh-tiered-collab
node examples/run-example.mjs

① 对照实验：坏例必须被抓住

坏例是从真文件复制再改生成的（只改 deny 的内容），所以它永远与真文件同源、不会腐烂。
示例断言三件事：

| 断言 | 证明什么 |
|---|---|
| 坏例（plan_t0 缺 pwsh、verify_t1 多了 pwsh）→ exit 1 | 校验器真能抓到坑 1 |
| 坏例 2（subagent_fork 删掉 maxDepth）→ exit 1 | 校验器真能抓到坑 2 |
| 真文件 → exit 0、problems: [] | 「坏了」的标准有意义——真文件必须过 |

没有最后一条，前两条毫无价值：一个永远报错的校验器也能"抓到"任何问题。

② 隔离验收执行器：证明它在副本里跑

示例用 examples/acceptance-spec.json 真跑一次 verify-runner.mjs，断言：

- commandCount=2 且 allPassed=true
- workspaceUnchanged=true —— 真工作区 SHA1 前后一致
- 每条结果的 ranInCopy 都指向 verify-sandbox-* —— 确实跑在副本里

它不覆盖什么（诚实声明）

负向测试跑不了 —— 那需要一遍分层会话（plan_t0 是否真的没有 write/edit/pwsh）。
别人 clone 下来没有宿主，所以示例不假装能代跑，只打印步骤指引：

INFO  本示例不覆盖：负向测试（plan_t0 是否真的没有 write/edit/pwsh）——
INFO    那需要一遍分层会话。步骤见 orchestrate/RUNBOOK-tiered.md §A。

复用的两个工具

scripts/verify-runner.mjs —— 隔离验收执行器

在一次性副本里执行验收命令，回传结构化报告：

| 字段 | 含义 |
|---|---|
| results[].exitCode | 每条命令的真实退出码 |
| results[].stdout / stderr | 原样回传（超长截断） |
| results[].ranInCopy | 证明跑在副本里 |
| workspaceUnchanged | 真工作区执行前后 SHA1 全量比对 |
| changedPaths | 若真工作区被改，列出具体文件 |

为什么命令走 JSON 文件而不是命令行参数：带空格的绝对路径在 argv 上会被按空白切碎
（实测 & "C:\Program Files\nodejs\node.exe" ... 被切成 4 个 token，
命令静默拆坏却依然"跑完"）。JSON 对引号与空格免疫。

参数缺失必须非零退出：第一版在无参数时返回空命令数组，
So allPassed: true, exit code 0 — equivalent to a false green from "zero commands all passed." Fixed.

It will add node to the subprocess PATH for you (see pitfall 7): so you can safely write node xxx.mjs in the spec,
without needing to write machine-specific absolute paths. If node is already on PATH in your environment, this step has no side effects.

The copy includes these directories: scripts/ fixtures/ docs/ orchestrate/ preset/ examples/.
(preset/ and examples/ were initially missed — the acceptance check needs to validate the constituent files themselves, so the copy must include them first.)

node scripts/verify-runner.mjs "" --spec
spec.json: {"commands":["",""]}

scripts/tree-sha1.mjs — File tree SHA1 snapshot

snapshotTree / diffSnapshots, covering all three categories: added / modified / deleted.
Its purpose is to compare any tree before and after execution — the typical scenario is "after acceptance runs, prove the real workspace was not touched"
(verify-runner.mjs uses it). One implementation, reused in many places.

Measured data: layered vs monolithic

The same task (a small project fixing 4 bugs, about 10 KB), run once in monolithic mode and once in layered mode:

| Metric | Monolithic | Layered | Diff |
|---|---|---|---|
| Model messages | 9 | 9 | Tie |
| Tool calls | 20 | 19 | −1 |
| Time | 49 s | 41 s | −16% |
| Total usage | 330,043 | 296,073 | −10.3% |
| Cache hit | 97.2% | 96.2% | −1.0 pt |
| Uncached input | 9,063 | 10,896 | +20% |
| Equivalent full price | 47,342 | 45,549 | −3.8% |

My interpretation (no sugarcoating):

- This is a tie, not a victory. 3.8% falls within the noise of a single run; to draw a conclusion you need at least 3–5 runs each.
- The main session's message count did not decrease at all (both are 9). Layering did not reduce interaction overhead, it just delegated the work.
- Uncached input actually went up +20% — each subagent has to re-read the constraints at the start, and these prefixes are independent of each other and cannot reuse the cache.
This is a fixed cost: the larger the task, the more it gets amortized; the smaller the task, the more it loses.
- This number is not the full accounting: it is the main session's usage, and the subagents' usage is not included,
and the planning layer among them uses a more expensive model. So the true total cost of layering is very likely higher.

My two initial predictions, one right and one wrong:

| Prediction | Result |
|---|---|
| Layered output would increase (need to write task cards and judgments) | ❌ Wrong, it actually dropped 7% |
| Layered uncached input would increase (subagents each read constraints) | ✅ Right, +20% |

Conclusion: At this scale, what layering buys is "possibly less rework," not "fewer tokens."
Whether it is worth it depends on whether your task will get it wrong the first time — and this 10 KB test failed to test that point
(both modes got it right on the first try).

Incidentally, a more useful finding: A 97.2% cache hit rate makes 330,000 tokens actually worth only about 47,000.
Keeping the prompt prefix stable and the cache always hitting is more effective than switching models or adding layering.

Measured data: Can the local tier replace cloud T2

Ten mechanical task cards (rename / add import / add JSDoc / unify quotes / convert to JSON / extract logs /
field migration / add error handling / test skeleton / switch to lookup table), the same set of cards run against cloud and local respectively:

| endpoint | Model | Passed | Total time | Input | Output |
|---|---|---|---|---|---|
| cloud | deepseek-flash | 10/10 | 13,762 ms | 850 | 510 |
| cloud | deepseek-flash | 9/10 | 8,006 ms | 850 | 510 |
| local | Local 12B MoE (mellum2-instruct-mxfp4_moe) | 8/10 | 20,111 ms | 1,026 | 591 |

The two local failures are both semantic errors, not format errors — the output structure is intact (JSON when it should be JSON), the error is in the content:

| Failed card | What it output | Problem |
|---|---|---|
| Add import | from "fs" | Should be node:fs/promises (used the old-style bare module name) |
| Extract log ERROR lines | ["disk full","disk full","write failed"] | Extracted the wrong content (should extract specific fields of ERROR lines) |

Evidence already filled in by an independent re-test

The hard flaw ① above (the benchmark ran the original model, not the deployed self-built variant) — I directly re-tested the same card (variable rename) against the deployed mellum2-t2-16k:

{"model":"mellum2-t2-16k","stream":false,"options":{"temperature":0},
"messages":[{"role":"user","content":"Rename all variable names user in the following JS to userName. Output only the modified code, no explanation.…"}]}

The output is verbatim identical to expected: userName appears 4 times, residual bare user 0 times,
the template string  hello ${userName}  is fully preserved. Time about 1 second, prompt 76 tok / out 40 tok.

So "the deployed model can also do mechanical work" holds (at least on this card).
But this is a single-card re-test, not equivalent to the 8/10 on those 10 cards — full acceptance still needs to be re-run against the deployed model.

⚠ Two other hard flaws remain unresolved

1. There is also a ghost 0/10 control in the same record: that was the q4_k_m variant, not installed on this machine at all,
raw entirely empty, time 0 ms. That is "model missing," not "model bad," and cannot be used to draw any conclusion.
2. The cloud baseline is itself unstable: the same set of cards ran 9/10 and 10/10 on two runs.

So the honest statement is: The local tier and cloud are roughly tied on mechanical work, not "20% lower."
The gap between 8/10 and 9–10/10 falls within the cloud's own fluctuation band; a single run score is not enough to distinguish the two.

What the local tier really saves
不是钱。 云端按 token 计费，本地按时间和显存计费——本地跑 20 秒的“钱”是你的电费
加上显卡被占用 20 秒（期间跑不了别的）。而机械活那点 token（850 in / 510 out）
按 flash 价格几乎是零头。

它省的是隐私：文件不出机器。这是站得住的卖点；
把它包装成“省成本”在这个量级上会被数据打脸。

还没有测的、也是最大的未知：contextWindow: 16384 在真实机械活输入下的表现。
上面每张卡的输入只有 ~100 token，而“把 200 行文件整体改名”这种卡可能是几千到上万 token。
本地档的适用范围很可能被这条边界决定，而不是被跑分决定。

目录结构

dsh-tiered-collab/
├── preset/
│   ├── preset.yml
│   ├── agent.cordis.yml              # 组成文件：四个分层工具 + 隔离约束
│   └── skills/tiered-collab/SKILL.md # 协议说明（随 preset 走）
├── preset-local/                     # 五档变体：T2 拆成本地优先 + 云端回落
│   ├── preset.yml
│   ├── agent.cordis.yml              # 多一个 work_t2_local（provider: local-ollama）
│   └── skills/tiered-collab/SKILL.md
├── scripts/
│   ├── verify-runner.mjs             # 隔离验收执行器
│   ├── tree-sha1.mjs                 # 文件树快照
│   └── validate-preset.mjs           # 组成文件结构校验
├── orchestrate/
│   ├── RUNBOOK-tiered.md             # 执行手册：负向测试 + 一轮闭环
│   └── phase1.mjs                    # 编排脚本体（⚠️ 见下方说明）
└── docs/
├── TASK_BRIEF.md                 # 任务书
├── PLAN.md                       # 计划书
├── BOARD.md                      # 协调板（当前状态）
└── BOARD-archive.md              # 完整逐轮记录与失败证据

⚠️ orchestrate/phase1.mjs 用的是宿主通用子代理接口，不吃 preset 里钉死的档位与工具面。
拿它跑会得到「模型像 T0、但约束全没有」的假分层。保留它是作为反面教材，
正确做法见 RUNBOOK-tiered.md §0：直调四个分层工具。

已知限制（不粉饰）

1. 不是机器级红线。 verify_t1 保留 shell 意味着「只看不改」是协议 + 核对保证，
不是能力面强制。真正的调用级拦截需要宿主提供 hook 机制——本项目的开发环境没装，
所以没做，也没假装做了。
2. 收益依赖项目规模。 小项目上分层是净亏（见上方实测）。
3. 配置不通用。 组成文件是为 DSH 写的；思路可以搬，文件不能。
4. 升档重试没在脚本内实测过。 真实发生过一次「判失败 → 带结论重试 → 通过」，
但那是手工走的，不是编排脚本跑出来的。
5. 本地档（preset-local/）尚未按“部署的那个模型”实测。
已有的跑分打的是原版模型，而 preset 里配的是自建 16K 变体——
被实测的没被部署，被部署的没被实测。而且云端基线自身有 9/10~10/10 的波动，
所以“本地低 20%”这个说法不成立，只能说“大致打平、待复测”。
6. 本地档的 16K 上下文边界未测。 已知跑分每卡输入仅约 100 token；
真实机械活输入可能大一到两个数量级。这条边界比跑分更能决定它能不能用。

License

MIT