DeepSeek Harness 怎样让 Agent 交付更可靠?拆解 AGENTS.md 与 16 个 Skill
先说结论。
DeepSeek Harness(下称 DSH)要解决的问题很朴素:Agent 动手之前,怎样知道该守哪些规则、该交什么证据、旧设计为什么这样定。
它的答案是分工:
AGENTS.md只放长期约束,细节链接出去;- 16 个 Skill 组织具体任务,各管一类判断;
- 能机械判断的要求交给脚本和 CI,判断不了的留给评审;
- 决策理由写进 Agent Notes,并且有完整的生命周期。
只看技能名,很容易把它读成一份提示词清单。真正值得学的,是这几层怎样互相引用。
下文固定研究 2026 年 10 月 9 日的提交 d743267,只谈开发规程和验证设施,不涉及产品功能。
一、只给 Agent 一份规范,为什么不够
给人一份代码规范,人会自己补上下文:这次改动碰到哪些规则,要跑哪些测试,某个奇怪的设计背后有什么历史。
Agent 未必补得上。没写进仓库的上下文,它很可能拿不到。规范写得太长,它找不到这次真正适用的几条;写得太短,又会漏掉证据要求和历史决定。
于是问题变成三个:
- 规则放在哪里,Agent 才能按需找到?
- 一类任务要做哪些判断、交哪些证据?
- 哪些要求能自动检查,哪些必须留给人?
DSH 的开发架构,基本就是对这三个问题的回答。下面逐层拆开。
二、规则分层:每条规则只有一个归属
DSH 在 文档规范 里规定了各类文件的职责:
| 位置 | 负责什么 |
|---|---|
根 AGENTS.md | 每次开发都要遵守的规则,简述要求并链接细则 |
子目录 AGENTS.md | 当前子树的额外约束 |
.agents/skills/ | 可复用的工作流程与专项判断标准 |
docs/ 与代码旁的说明 | 测试政策、当前行为、接口约定及操作方法 |
.agents/notes/ | 设计理由、放弃的方案、后果及验证要求 |
scripts/ 与 .github/workflows/ | 检查程序及其执行安排 |
原则只有一句:每条规则只在一处定义,其他地方引用它。
以“推送前该做什么”为例。相关要求分散在四处,各有侧重。共享细则以引用为主,必要的局部约定才重复:
- 根规则要求推送前运行与改动相关的检查;
- 包级规则补充真实装配测试和资源清理;
- 测试政策说明单测、快照、真实 API 测试各自能证明什么;
dsh-pre-push-checks把上面这些组织成推送前的操作步骤。
文档规范也这样拆。docs/AGENTS.md 管结构与预算,dsh-doc 管放置和验证,dsh-prose-standard 管信息是否完整,dsh-trim-cot-leakage 专门清理会话残留。哪个 Skill 都不必重写整套文档规范。
整体关系如下:
flowchart TD A["根规则与子目录规则"] --> B["按任务选用 Skills"] C["测试政策与专业标准"] --> B D["当前决策记录"] --> B B --> E["代码 文档与验证证据"] E --> F["脚本与 CI 检查"] E --> G["评审中的语义判断"] F --> G
图里画的是引用和验证的分工。仓库只要求 Agent 读取适用的指令;具体工具怎样发现、加载、继承这些文件,由工具自己负责。
三、16 个 Skill:按问题分组,按任务组合
该提交的 技能目录 有 16 个入口。按它们回答的问题,可以分成五组:
| 回答的问题 | Skill | 各自负责 |
|---|---|---|
| 模型怎样获取信息 | agent-experience | 工具定义、信息发现、上下文加载、总工作量 |
| 代码是否可靠、值得维护 | dsh-code-review、dsh-error-handling、dsh-ci-test-reliability、dsh-find-simplifications、dsh-speed-up-perf | 评审、失败责任、测试隔离、减少维护负担、实测性能 |
| 文档是否准确、可维护 | dsh-doc、dsh-prose-standard、dsh-trim-cot-leakage、dsh-translate-docs、dsh-create-upgrade-guide | 结构、完整表达、会话残留、扩展翻译、破坏性变更 |
| 界面是否可用、可核查 | dsh-client-ui-ux、record-browser-gif | 交互判断、真实运行演示 |
| 改动怎样交付和留存 | dsh-pre-push-checks、dsh-merging-stacked-prs、dsh-archive-agent-notes | 选择验证、处理依赖 PR、维护决策记录 |
一个 PR 往往同时碰到错误处理、并发测试、界面反馈和文档表达。所以 Skill 主要按问题组合调用,只有部分流程规定了先后,比如先把测试设计修好,再选验证范围。
边界划在哪里
分组之外,更值得看的是相邻 Skill 之间的边界。有三组很典型。
测试怎么设计,和推送前跑什么,分开管。 dsh-ci-test-reliability 判断资源分配、状态恢复、同步和清理是否可靠;dsh-pre-push-checks 根据改动挑命令。后者明确要求:测试设计有问题,先修设计,再谈验证范围。
文档放哪里,和文档写什么,分开管。 dsh-prose-standard 要求保留行为、失败、时序、责任、例外和后果。清理会话残留时,先把有用的事实改写成独立成立的陈述,再删叙事,缺的信息还要补回来。字数变少,本身不算改进。
界面怎么设计,和怎么证明它能用,分开管。 dsh-client-ui-ux 判断反馈放哪、组件怎样复用、窗口边缘怎样处理。record-browser-gif 要求:凡是改变用户可见 GUI 行为的 PR,都要附一段从真实服务和模型流程录下的 GIF。演示让改动可见,交互合不合理,仍由评审判断。
一个细节:agent-experience 为什么是软链接
16 个入口里,15 份 SKILL.md 是普通文件。只有 agent-experience/SKILL.md 是软链接,指向:
../../../packages/preset/agent-preset/skills/agent-experience/SKILL.md
包内说明写得很清楚:正文随包发布,仓库里的路径只是给开发工具发现用的别名,编辑一律在包内进行。测试也专门验证它是别名,并分别检查两种发现入口。
道理很简单:发布给用户的规范和仓库自己用的规范共用一份正文,就不会出现两份文件各自改动、逐渐走样。
四、一次 PR 走一遍:各层怎样配合
抽象说分工不够直观。假设有这样一个 PR:给某个工具加超时参数,超时后要清理子进程,并在界面上显示失败原因。
沿着它走一遍,可以拆成五个环节。这是讲解顺序,并非严格工序:升级指南在发现破坏性变更时就要写,文档和验证贯穿整个改动。
1. 先确认改动范围
dsh-code-review 和 dsh-pre-push-checks 都要求先确认真实的 PR base 或依赖分支,再运行 change-scope。
这份报告会区分已提交、已暂存、未暂存和未跟踪的路径。它不猜基准分支,也不替你选测试。依赖 PR 如果直接和 main 比,会把下层 PR 的改动也算进来,范围就错了。
报告只负责定位。哪些行为受影响,还得沿调用关系自己判断。
2. 再想清楚信息怎么给、失败谁负责
agent-experience 关心模型看到什么。参数的默认值、范围和使用条件,要写在参数定义上,别在工具说明和系统提示词里再抄一遍。改了工具定义,要对比首轮提示词的 Token 数。
它衡量的是完成任务的总工作量。省下一段上下文,如果换来模型反复检索、读错,并不划算。
dsh-error-handling 关心超时之后的状态:操作是没执行、执行了一半,还是结果未知?谁负责终止子进程、恢复状态、报告结果?只有状态的所有者能保证安全继续。捕获异常、打条日志,不等于恢复。
3. 用测试证明资源真的收回了
dsh-ci-test-reliability 把资源竞争分成四层:同一文件内、不同 worker 间、同一 job 的独立进程间、共享宿主的不同 job 间。进程隔离挡不住端口冲突、固定路径和外部服务。
所以它要求三件事:原子地分配资源,等待明确的就绪信号,清理时等进程真正退出、服务真正关闭。调完 kill() 立刻结束测试,证明不了资源已经收回。
竞态问题要用屏障或可控的 Promise,把交错固定在确定的位置。压力测试只算补充证据。
它反对用没诊断过的延时、重试或整体串行来掩盖失败,但也留了口子:外部服务的瞬时错误、实测到的文件句柄争用、恢复 CI 原有的超时预算,可以例外。判断标准是说得清在等什么、为什么重试、谁负责截止和清理。
4. 按影响范围挑证据
dsh-pre-push-checks 的原则是:选能抓住这次回归的最窄验证。
- 改了模型或用户可见的输出,跑对应的无密钥快照或可运行示例;快照不适用,要说明原因;
- 动了发布入口或构建产物,要构建并验证产物;
- 改了文档,跑文档检查。
测试选择和覆盖率统计也分开处理。只跑一个测试文件,不一定缩小了覆盖率统计范围;缩小统计范围,也不能借此藏起受影响却没覆盖的代码。
本地 Git hook 的 pre-push 只跑类型检查。行为层面的证据由作者补齐,更广的检查交给 CI。完整的本地全量演练,只在明确要求、诊断 CI 问题,或实在无法缩小范围时才做。
5. 同步交付说明
再看“给别人看的东西”:
- 界面改动,附真实演示;
- 外部能感知的破坏性变更,一发现就写升级指南。仓库内部、所有调用方已一并更新的预稳定 API 变化,不需要;
- 日常文档改动顺手维护双语。
dsh-translate-docs是用户点名才启动的扩展流程,平时走轻量翻译规则就够了。
评审收尾,检查这些证据是否覆盖了真实入口、失败状态和外部结果。dsh-code-review 自己也说得明白:它只是指导,替代不了完整的语义判断。
五、自动检查:能管什么,管不了什么
DSH 的规则要求把能机械判断的要求下沉成脚本和测试,其中许多已经落地。run-gates.ts 把检查组织成一张带依赖的执行图,再由 CI 工作流 调用。
依赖顺序有具体原因。比如 HMR 测试会重写共享构建目录,执行图就让它等所有依赖这些产物的检查跑完。测试可靠性的要求,落到了检查程序自己的调度上。
但每项检查都有边界:
| 自动检查 | 能验证什么 | 仍要人判断什么 |
|---|---|---|
verify-doc-budgets | 常驻文档是否超出预算 | 信息是否完整、放得是否合理 |
verify-translation-pairing | 配对记录与结构是否合规 | 两种语言的意思是否一致 |
verify-agent-note-format | 决策状态与正文结构是否匹配 | 标为已实施的决定是否真的落地 |
verify-archived-agent-notes | 归档文件、哈希与封存记录是否合规 | 这份决策该不该归档 |
| 测试与快照 | 断言是否成立、输出是否符合期望 | 断言和期望值本身对不对 |
人工触发的策略也一样。dsh-translate-docs 声明了 disable-model-invocation: true,正文要求用户点名才用。该提交的 元数据检查器 只检查带 agents/openai.yaml 的 Skill,而被跟踪的技能目录里一个都没有,跨工具的配对检查实际没有检查对象。这条策略能否生效,还取决于各个开发工具,不能凭一个标记就认定处处受限。
案例:检查全绿,结果是错的
表格最后一行最容易被低估。事故记录 0002 正好说明了这一点。
当时,一些文件操作场景调用了未注册的工具,返回 UNKNOWN_TOOL。有人刷新快照,把这个错误结果写成了新的期望值。之后单测、覆盖率、快照、文档、构建、包检查全部通过。直到有人人工审阅期望值,才发现问题。
快照忠实地重放了错误。
修复方式是加一道独立断言。快照测试框架 在两个位置拒绝结构化的 UNKNOWN_TOOL:读取已提交的 Session fixture 时,和检查新运行日志时。这道检查不看输出是否与快照一致,已接入本仓库的 node-24-consumers CI 任务。
这个案例把整套规程的运转方式串了起来:评审发现语义漏洞,事故记录留下原因,能明确判断的错误再沉淀成持续检查。
评审资格也有检查
review ownership 把评审者资格、权重和 CHANGES_REQUESTED 状态纳入检查。它按分数判断:通过阈值是 2 分,一般评审者计 1 分,指定评审者计 2 分,拥有较多旧生产代码行的评审者另有加权;有效的 CHANGES_REQUESTED 会直接阻止通过。所以它没法简化成“两人批准即可”。
它能检查谁有资格批、分数够不够。批准的内容靠不靠谱,仍由评审者负责。
六、决策记录:别让 Agent 重做被否掉的方案
Agent 读到一份过时的决策,可能把早已放弃的方案再做一遍。DSH 用 Agent Notes 生命周期 管这个风险。
从提案到实施
proposed/ 存问题、方案、替代项、验收条件和风险。implemented/ 描述已实施的决定和后果。方案落地时,要把“计划做什么”改写成“现在是什么”,而且可以核实。
已实施记录的规则 还区分两种变化:
- 路径、符号、默认值这类事实变了,随代码更新原记录;
- 决定或理由反转了,另立一份新记录,两份互相链接。
这样既保证事实准确,也保住了“为什么改主意”的线索。
什么时候删,什么时候留
dsh-archive-agent-notes 按未来价值分类:
- 仍能指导设计的理由、替代项、兼容性和安全要求,保留;
- 部分被取代的记录,保留并互链;
- 要整合删除,新记录必须先接住全部独有的理由、替代项、后果、验证要求和覆盖缺口;
- 只记录小幅 UI 调整或纯机械变化的已实施笔记,直接删除并修复引用;
- 决策已完成、理由不再指导后续工作但有历史价值的,归档;
- 过时的提案改为拒绝;拒绝记录只有在还能防止一个诱人的错误时才保留。
每份新 Note 都会触发一次同主题审核,确认的替代关系要在同一个 PR 里处理。 记录旧、篇幅长、“已经做完了”,都不足以成为删除理由。
归档之后
归档会改变记录的检索和校验方式。.rgignore 排除了归档目录,遵循它的默认 ripgrep 搜索会跳过归档;显式读取和其他检索方式仍能访问。中英文和配对记录一起封存,由追加式哈希清单保护。历史留着,当前工作只引用现行依据。
规程本身也要维护。评审 Skill 维护手册 描述了一套协议:从人类反馈和最终采纳的改动里提炼候选规则,经两个适配器交叉审查,再由维护者核对证据、决定是否提交。公开的只有协议和部分运行记录,工具在维护者的私有基础设施上,对应的 Agent Note 仍是 proposed 状态。
七、想搬进自己的项目,从哪开始
不用一次照搬 16 个 Skill。挑一个反复出错的任务,按下面五步建立最小闭环:
- 定规则归属。 全仓库约束放根指令,局部要求放子目录。每条只写要求,细节链接出去。
- 拆任务流程。 让 Skill 写清何时使用、怎样判断、交付什么证据。共享标准只引用,不复制。
- 给真实失败补检查。 固定一条能复现问题的路径,确认错误版本会失败,再接进日常流程。
- 保留语义评审。 搜索帮你找线索,快照帮你比输出,判断仍要人来做。
- 管好决策状态。 写清当前决定、放弃的方案和验证要求。新方案落地时,顺手处理被取代的旧记录。
回到开头的问题。DSH 提高 Agent 交付可靠性的思路,可以归结为三件事:每个任务找得到规则,每项交付拿得出证据,下一次会话读得到仍然有效的决定。
相关阅读
Magpie Loop 研究:三条 /loop 指令,怎样撑起一个自动维护的项目 把视角从一次交付扩展到持续运行:Agent 怎样定期处理反馈、验证结果,再把复盘写回项目。