DeepSeek Harness 的 AGENTS.md 分组清单：两个目录不存在、漏 17 个

2026-08-16

读别人的仓库，最省事的入口通常是根目录那份写给 agent 看的说明文件——它一般会给一段目录树，告诉你哪块代码在哪。deepseek-ai/deepseek-harness 的根 AGENTS.md 里就有这么一段 Repository layout。

我们按 2026-08-16 采集的快照 47f9438 把这段清单逐行和 packages/ 下的真实目录对了一遍，结果是：清单里有两个组名在 packages/ 下找不到同名目录，另有 17 个真实存在的组目录没有出现在清单里。下面把每一处的位置标出来，只陈述差异。

先交代仓库的状态：这个仓库建立于 2026-08-13，我们采集时是 2026-08-16，前后差三天；根 package.json 的版本是 0.1.0-rc.5，GitHub 上一个 Release 都没有；README.md:9-11 自述处于 developer preview，并用大写写着「THERE WILL BE COMPATIBILITY-BREAKING CHANGES」。截至同一天，GitHub API 返回的 star / fork / open issues 是 132,054 / 13,235 / 0——star 这个数字在我们采集当天的几十分钟内就从 131,928 变到了 132,054，引用时请以仓库当前显示为准，也不必由这些数字推导任何质量结论。所以本文写到的每一处结构、行号、目录名，都可能在你读到时已经变了。

数之前先把口径定死：49 不是包数

pnpm-workspace.yaml 的 packages: 列表里，那一条 glob 写的是 packages/*/*——两层，不是 packages/*。这意味着 packages/ 下那 49 个目录都是组目录，它们自己没有 package.json；真正的 npm 包在第二层。我们数出来：packages/*/* 共 219 个目录，219 个全部有 package.json，一个不缺；219 个包的 version 全部是 0.1.0-rc.5，name 全部以 @deepseek-ai/dsh- 开头。

这条口径写在根 AGENTS.md:13 那一行里：packages/ @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/；packages/README.md:9 也写「Groups hold packages/<group>/<pkg>/; names stay @deepseek-ai/dsh-<pkg>.」

所以下文说的「组」都是第一层的那 49 个目录，说「包」都是第二层的那 219 个。把「49 个包」写出去就是错的。

差异一：两个组名在 `packages/` 下没有对应目录

AGENTS.md:11-55 是一段 ```text 围栏，其中缩进两格的组名共 34 个。逐个比对后有两条对不上：

AGENTS.md:35 写 self-modification/ the agent inspects/mounts its own plugins，但 packages/ 下没有 self-modification 目录。承担这段描述的真实目录是 packages/extensions/——packages/extensions/README.md:1 的标题是「# extensions/ — the agent modifies its own runtime」，packages/README.md:43 也把 extensions/ 描述为「Agent runtime self-modification」。
AGENTS.md:46 写 support/ dev/test infrastructure，但 packages/ 下没有 support 目录。真实目录是 packages/test-support/——packages/README.md:58 写它是「Support infrastructure (testkits, invariants, replay, Loader smokes)」。

两处都是「清单里的名字」与「磁盘上的目录」不一致。以我们实读的快照 47f9438 为准，就是这个状态；至于哪边算「对的」、为什么会这样，我们不推断，也不拿它去评价这个项目。

差异二：17 个真实组不在这段清单里

34 个组名里有 2 个对不上目录，剩下 32 个能和真实组目录对上。49 减 32，还有 17 个真实组没出现在这段清单里：

attachment、client、code-runtime、extensions、feedback、goal、host、jobs、mcp、runtime-diagnostics、sandbox、schedule、session-query、spill、storage、test-support、workspace。

两点值得单独说。

一是 extensions 和 test-support 就在这 17 个里面——也就是说，差异一里那两个「写了但不存在」的名字，它们各自对应的真实目录名同样没有出现在清单中。

二是这 17 个不都是边角料。按我们对 .ts/.tsx 文件的统计（递归，排除 node_modules/dist/lib/.turbo），client 是 49 个组里体量最大的一个：39 个子包、785 个文件、137,889 行；host 是 8 个子包、101 个文件、22,412 行。web GUI 的浏览器一半和 host 一半，都在这段清单之外。

清单末尾 AGENTS.md:57 有一行：「Package groups: packages/README.md.」——完整分组被指向了另一份文件。

差异三：被指过去的那份表也少两个组

顺着这行指路过去看 packages/README.md:11-59 的「Group | Role | Release expectation」表：共 47 行数据行。和 49 个真实组目录比对，表内那 47 个组名全部对应真实目录、没有多余项，缺的是 mcp/ 与 runtime-diagnostics/ 两组。

同一份文件 :61 写着：「New packages join existing groups; new groups update their README and this table.」

还有一处相关的实况：runtime-diagnostics/ 是 49 个组里唯一没有组 README.md 的目录（我们逐个检查过 49 个组，缺失列表只有它一个；219 个子包则全部有 README.md）。它的唯一子包是 invariants，package.json 的 description 写「Registry service for package-owned DeepSeek Harness runtime invariants」。而 packages/README.md:9 那句是「Group READMEs own package/ctx-key maps.」

说到这里就停。这几处差异各自的位置都标出来了，剩下的判断留给读源码的人自己做。

同一类差异不止发生在组清单上

如果你打算靠某一份文档当索引，下面两处同样值得先知道：

packages/core/ 目录下有 8 个子包（agent、agent-default-model、agent-loop、agent-tool-presentation、scope、session、system-prompt、tools），而 packages/core/README.md:7-15 的「Package | Role | ctx key」表只有 7 行，agent-tool-presentation/ 不在表内。该包确实存在：packages/core/agent-tool-presentation/package.json 的 name 是 @deepseek-ai/dsh-agent-tool-presentation，其 README.md:5 说它是 agent preset 携带的一行、用来说明模型看到哪种工具形态（native / code / both）；docs/module-graph.md 的 219 个节点里也包含它。
docs/subsystems/core.md:9 的首句是「A turn flows through the six packages in one loop」，其后 :11-19 的表列出 6 个包。作为对照，docs/architecture.md:41 的引导句带了限定词：「Here are some core packages that contribute to the Cordis tree.」，其表是 7 行。三处的口径各不相同。

想自己复核，先跑这两步

第一步，把两个基数确认下来。这是我们数 49 与 219 时用的脚本（在仓库根目录下执行）：

python -c "
import os,glob
pkgs=[p for p in sorted(os.listdir('packages')) if os.path.isdir(os.path.join('packages',p))]
print('dir count:',len(pkgs))                      # → 49
subs=[s for s in sorted(glob.glob('packages/*/*')) if os.path.isdir(s)]
print('packages/*/* dir count:',len(subs))         # → 219
withpj=[s for s in subs if os.path.exists(os.path.join(s,'package.json'))]
print('with package.json:',len(withpj))            # → 219，missing: []
"

Windows 侧提醒一句：PowerShell 与 cmd 里写这种带换行的 python -c 很容易被引号规则坑到，直接存成一个 .py 文件再跑更省事；Linux/macOS 的 shell 下按上面原样贴即可。这属于通用的命令行经验，不是该项目文档里的内容。

第二步，把 AGENTS.md:11-55 那段围栏里缩进两格的组名抠出来，和 os.listdir('packages') 求两个方向的差集：清单有而目录没有的，就是差异一那两个；目录有而清单没有的，就是差异二那 17 个。求差集比人眼扫一遍靠谱得多——34 对 49，肉眼很难数准。

如果你的差集结果和本文不一致，最可能的原因是你的仓库不是 47f9438 这个快照。先在仓库根目录跑一句 git log --oneline -1 对一下再说。

这条差异改变你什么做法

一句话：别把 AGENTS.md 的那段 layout 当成目录索引来用，它自己在末尾已经把完整分组指向了 packages/README.md。

而仓库里另有一批生成物可以当索引。docs/graph-atlas.md 是文档图索引，把 9 张图各自标了 Mode——module-graph.md 与 tool-catalog.md 标 generated，capability-seams.md 等 5 张标 hybrid generated，agent-lifecycle.md 与 tool-execution-pipeline.md 标 curated。docs/module-graph.md 首行的注释是「Generated by scripts/gen-module-graph.ts — do not edit by hand.」，:6 说明它的边来自各包的 peerDependencies；我们数过，里面有 49 个 subgraph group_* 和 219 个包节点，和磁盘上的 49 / 219 对得上，且 219 个节点名去掉 @deepseek-ai/dsh- 前缀后全部命中真实包名，不匹配数为 0。docs/config-catalog.md（首行同样带「Generated by」注释）里，108 个二级标题中有 105 个是包名小节，其余 3 个是分类小节。

那段 layout 清单不在这份图索引里，packages/README.md 的分组表也不在。

还有一层索引比组清单齐整：包级 README。219 个子包全部有 README.md；packages/README.md:69 要求包 README 必须带 ## Known Limitations and Deferred Work 小节，否则要走一份 allowlist（位置写的是 scripts/verify-package-readme-limitations.ts）。我们对 219 份包 README 逐个查了这个标题，218 份有，缺的是 packages/util/brand/README.md 一份——至于它是不是已经在那份 allowlist 里，我们没有去读 allowlist 的内容，所以说不出结论。也就是说，要弄清某个能力具体落在哪个包，从第二层的包 README 往上看，比从第一层的组清单往下找更容易对得上。

最后把仓库自述的处境原样放在这里，不做因果延伸：根 AGENTS.md:5-7 的小节标题是「Pre-release stance: foundation over blast radius」，首句写「Remove this section at the first tagged release.」，并写「rename or repackage freely and update every reference together」；packages/README.md:61 写新增组要同时更新它的 README 和那张表。这两条和上面几处差异，是并列摆在一起的事实。

延伸阅读

从头读起：DeepSeek Harness 是什么：建仓三天、13 万 star 的 Agent 框架
本专题共 45 篇，完整分组目录见专题页
DeepSeek Harness 的 219 个包版本全是 0.1.0-rc.5：发布口径怎么读
DeepSeek Harness 能力接缝图：四个包名在 packages 下找不到

本文依据 DeepSeek Harness 官方仓库（github.com/deepseek-ai/deepseek-harness）的 README、docs/ 下的架构与子系统文档、以及 packages/ 下的源码整理，核对日 2026-08-16，对应仓库快照 47f9438（版本 0.1.0-rc.5）。本文内容为仓库源码与文档口径，我们没有安装、也没有运行过这个项目，因此不涉及界面外观、操作手感与运行速度的任何描述。该仓库建立于 2026-08-13，README 自述处于开发者预览阶段并明确说明未来会有破坏兼容性的变更，文中出现的命令、配置与默认值随时可能变动，请以仓库最新内容为准。