DeepSeek Harness 怎样让 Agent 交付更可靠?拆解 AGENTS.md 与 16 个 Skill

Nexmoe 2026年10月14日

先说结论。

DeepSeek Harness(下称 DSH)要解决的问题很朴素:Agent 动手之前,怎样知道该守哪些规则、该交什么证据、旧设计为什么这样定。

它的答案是分工:

  • AGENTS.md 只放长期约束,细节链接出去;
  • 16 个 Skill 组织具体任务,各管一类判断;
  • 能机械判断的要求交给脚本和 CI,判断不了的留给评审;
  • 决策理由写进 Agent Notes,并且有完整的生命周期。

只看技能名,很容易把它读成一份提示词清单。真正值得学的,是这几层怎样互相引用。

下文固定研究 2026 年 10 月 9 日的提交 d743267,只谈开发规程和验证设施,不涉及产品功能。

一、只给 Agent 一份规范,为什么不够

给人一份代码规范,人会自己补上下文:这次改动碰到哪些规则,要跑哪些测试,某个奇怪的设计背后有什么历史。

Agent 未必补得上。没写进仓库的上下文,它很可能拿不到。规范写得太长,它找不到这次真正适用的几条;写得太短,又会漏掉证据要求和历史决定。

于是问题变成三个:

  1. 规则放在哪里,Agent 才能按需找到?
  2. 一类任务要做哪些判断、交哪些证据?
  3. 哪些要求能自动检查,哪些必须留给人?

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。挑一个反复出错的任务,按下面五步建立最小闭环:

  1. 定规则归属。 全仓库约束放根指令,局部要求放子目录。每条只写要求,细节链接出去。
  2. 拆任务流程。 让 Skill 写清何时使用、怎样判断、交付什么证据。共享标准只引用,不复制。
  3. 给真实失败补检查。 固定一条能复现问题的路径,确认错误版本会失败,再接进日常流程。
  4. 保留语义评审。 搜索帮你找线索,快照帮你比输出,判断仍要人来做。
  5. 管好决策状态。 写清当前决定、放弃的方案和验证要求。新方案落地时,顺手处理被取代的旧记录。

回到开头的问题。DSH 提高 Agent 交付可靠性的思路,可以归结为三件事:每个任务找得到规则,每项交付拿得出证据,下一次会话读得到仍然有效的决定。

相关阅读

Magpie Loop 研究:三条 /loop 指令,怎样撑起一个自动维护的项目 把视角从一次交付扩展到持续运行:Agent 怎样定期处理反馈、验证结果,再把复盘写回项目。