前言¶
在 DeepSeek Harness（DSH）里做多步开发时，常见做法是主会话负责理解需求，再派子代理去改代码、跑命令。廉价模型执行快、成本低，但容易幻觉；若让模型互相评价「做得对不对」，成本与不确定性都会上去。Nwflower 的 dsh-pilot 走另一条路：主代理只起草契约，子代理按契约执行，插件用确定性规则裁决（验收命令 exit code、git diff 与白名单、回执交叉核验），主代理最终只读一份紧凑的 verdict JSON。README 里用一句话对比：agent-teams 给你一支团队，dsh-pilot 给你一份合同。
这是什么¶
- 名称：dsh-pilot（仓库 Nwflower/dsh-pilot）
- 维护者：Nwflower
- 分类：工作流（社区目录：SkillHub 插件页）
- 许可：MIT（README 与 package.json 一致）
- 当前 package 版本：0.2.0（以 package.json 为准）
- 状态（README）：M1.6 完成，全链路可用；设计见仓库内 DESIGN.md
插件面向 DSH 的 Host 插件形态：契约派发 → 白名单守卫 → 门禁执行 → 裁决回传。README 称 62/62 自动化测试通过，并经真实子代理派发会话验收（PASS）。
核心机制¶
下面介绍主代理、插件与子代理各自做什么。
主代理（旗舰模型） dsh-pilot 插件（Host，纯代码裁决）
───────────────── ──────────────────────────────
理解需求 · 摸清工程状况 ① 组装子代理 prompt = 契约 + 内联上下文
起草契约 · 不亲手写代码 ──契约──▶ ② subagents.start(outputSchema, toolFilter)
③ 文件白名单守卫（tools.guard）
▲ ④ 门禁：shell 跑 acceptance_cmd → 真实 exit code
└────── verdict ◀────────── ⑤ 核验：git diff vs 白名单 & 回执真实性
（紧凑 JSON，<200 token） ⑥ 失败：确定性反馈重试（≤max_retries）
README 强调的「幻觉防御」要点包括：
- 契约 schema 刻意没有 code 字段，主代理物理上不能通过契约塞代码。
- 门禁 exit code 由插件亲自执行验收命令取得，不信回执自报。
- 任务前后
git status快照差集与回执files_changed交叉核验；虚报即 FAIL，并把真实 diff 喂回重试。 - 白名单守卫：子代理对
allowed_files之外的写入会被拒绝（tools.guard，同步、fail-open 表述见 README）。 - 失败重试只喂确定性内容（如 stderr 尾部、越界清单）；耗尽后 verdict 为
ESCALATED，交给人类。
verdict 取值：PASS、FAIL、BLOCKED、ESCALATED。非 PASS 时 README 说明会附 workspace_delta 等现场信息，便于先验收或回滚再派新契约。
契约与裁决示例¶
主代理通过工具 pilot_dispatch 提交契约（schema 强校验）。典型入参如下：
{
"goal": "一句话目标",
"detail": "需求细节、接口签名约定、边界条件",
"context": [
{ "path": "src/auth.ts", "note": "TokenService 在此；签发签名 sign(uid: string): string" }
],
"allowed_files": ["src/auth.ts", "tests/auth.test.ts"],
"acceptance_cmd": "pnpm vitest run tests/auth.test.ts",
"tier": "standard",
"max_retries": 2
}
插件回给主代理的裁决示例（主代理只看这个）：
{
"verdict": "PASS",
"files_changed": ["src/auth.ts", "tests/auth.test.ts"],
"gate": { "cmd": "pnpm vitest run tests/auth.test.ts", "exit_code": 0 },
"attempts": 1,
"child": { "model": "deepseek-v4.1-flash", "tokens": 12345 }
}
安装与启用¶
README 写明：尚未发布 npm。开发期可本地挂载；发布后可用第二条命令。
dsh plugin --profile web add -w link:D:\Build\dsh-pilot # 本地开发
dsh plugin --profile web add dsh-pilot # npm 发布后
本地开发示例路径来自 README（Windows 路径）；Linux /macOS 用户需把 link: 指向本机 clone 或下载后的插件目录，命令形式仍以 README 为准。
在 cordis.patch.yml 组合行中可插入如下配置（字段名与 README 一致）：
- insert:
- id: dsh-pilot
name: dsh-pilot
config:
provider: spawn # 子代理 provider（subagents.list() 可查）
model: deepseek-v4.1-flash # 钉死子代理模型
exposure: pointer # pointer=一行 persona 指针；silent=上下文零占用
guard: true
maxRetries: 2
gateTimeoutMs: 300000
feedbackMaxChars: 2000
README 还提到上下文纪律：P0 只注册 pilot_dispatch 一个工具；详细手册在 pilot-playbook skill 里按需载入；exposure: silent 时 persona 段不注入、skill 仅用户显式调用。设计细节见仓库 DESIGN.md §2.3。
运行环境：package.json 要求 Node >= 18。
典型用法思路¶
- 主代理在会话里摸清工程状况，把目标、细节、相关文件说明写进契约的
goal、detail、context。 - 用
allowed_files限定子代理可写路径，用acceptance_cmd写可重复的验收命令（例如单测一条命令）。 - 调用
pilot_dispatch；等待插件派发子代理、跑守卫与门禁。 - 根据返回的
verdict决定继续规划、改契约重派，或在ESCALATED时人工介入。
子代理模型与 provider 由插件 config 固定（示例为 spawn + deepseek-v4.1-flash），与「贵模型规划、廉价模型执行」的分工一致。
适用场景与注意¶
适合谁
- 已在 DSH 中使用子代理，希望把「是否完成、改了哪些文件、测试是否过」从 LLM 自评改为可脚本复现的裁决。
- 愿意用契约约束范围：白名单文件 + 明确 acceptance 命令 + 有限次重试。
务必注意
- DSH 插件在当前 dsh 进程权限下运行；安装前请自行阅读源码与 MIT 许可证，确认验收命令与白名单符合你的安全预期。
acceptance_cmd会在工作区由插件执行；应使用你信任且可重复的命令，避免破坏性操作。- 社区目录 SkillHub 与 DeepSeek / 幻方无 README 所暗示的官方从属关系；DSH 生态理念是「一切皆插件」，本文事实均来自上述仓库 README 与 package.json。
同作者其它 DSH 插件（README Ecosystem 节）：dsh-chat-import、dsh-file-claim、dsh-perf-lens、dsh-claude-style，可与本插件组合使用，具体能力以各仓库文档为准。
结尾¶
dsh-pilot 把多代理协作收成「契约 + 代码裁决」：主代理少读长日志，子代理越界与虚报由插件拦截。若要进一步看契约/回执/裁决规格与生态对照，请读仓库 DESIGN.md。
