DeepSeek Harness 工具目录全解析

DeepSeek 在 GitHub 上开源了自家的 agent harness（智能体框架）DeepSeek Harness，采用 MIT 协议，口号是「一切皆插件」，底层由 Cordis 插件框架驱动，目前处于开发者预览阶段。对这类框架来说，模型能做什么，取决于系统提示词里注入了哪些工具：每个工具以 name、description 和 JSON Schema 格式的 parameters 三件套进入模型视野。仓库文档里的工具目录一页，把这层「模型可见表面」完整摊开，是理解现代 agent 框架工具层的一份好教材。

模型眼中的工具是什么

工具由插件向统一的工具注册表提供，模型通过系统提示词拿到全部工具的名称、描述与参数 schema。这份目录只覆盖仓库里以 tool- 开头、随产品发布的工具包，每个工具都以默认配置启动后记录，范围约定与配套的服务目录保持一致，示例代码里的演示工具不在其中。

有一个细节很能说明设计取向：工具的注册名可以由加载时的配置决定。以 subagent 包为例，toolName 是配置项，因此同一个包在不同部署里可能以不同名称出现；随产品发布的组合还会为 fork 后端额外注册一个 subagent_fork，两者 schema 并不相同：subagent 是可继续模式，省略参数时默认后台运行，运行时会在结束时自动投递结果；subagent_fork 则是一次性模式，默认前台运行，跑完即止。

目录本身是被门禁看守的生成物

这份文档最有趣的地方在于它不是手写文档，而是生成物，且配有完整的防漂移机制。英文源文件由仓库脚本生成，生成器不做静态分析，而是真实启动每个工具插件，读取工具注册表在运行时暴露的 schema 结果。原因文档里写得很直白：工具 schema 无法靠静态分析完全确定，存在运行时才展开的枚举、拼接出来的描述、由配置决定的名称，以及使用原始 JSON Schema 的 MCP 工具。

配套的完整性守卫会匹配全部 tool- 前缀的包，生成器的启动清单只要遗漏任何一个包，检查就直接失败，新工具不可能在无人察觉的情况下缺少文档。中文版则作为经评审的对侧，通过双语配对机制维护，校验脚本会检查两侧的新鲜度。这套「文档即测试」的纪律，比多数开源项目 README 式的维护方式严格得多。

六大类工具速览

把二十多个工具包按职能归拢，可以分成六组。

人机交互只有两个工具，但都很有代表性。ask_user_question 允许模型在继续之前向用户提出带稳定 id 的问题，支持选项列表与多选，调用会暂停到界面提供方返回人类答案为止。exit_plan_mode 服务于规划模式：提交完整的 Markdown 计划，用户可以批准执行，也可以要求继续规划。值得注意的是，规划未激活时它仍保留在面向模型的 schema 里，只是执行路径会拒绝目录外的调用，这样规划策略的开关不会连带造成工具目录变动。

命令执行覆盖 bash 与 pwsh 两种方言：每次调用都在全新 shell 中运行，不保留任何状态，文档明确要求传 workdir 而不是用 cd；长输出截断保留尾部，超长内容落盘并报告路径；长任务设置后台标记后立即返回 job id，交给后台工具收集或停止。此外还有按所有者隔离的持久 bash，跨调用保留当前目录与环境变量；以及需要显式启用的六个终端工具，负责打开、读取、发送、关闭、列出持久终端和投递信号，用于维持 REPL 这类长会话。

代码模式是目录里最激进的设计：run_code 让模型写一段 TypeScript 异步函数体，以 await 加工具名的方式批量调用工具，只有打印或返回的内容会传回模型。并发安全的子调用最多重叠执行到配置的并发上限，且每个嵌套调用都会重新进入完整、受守卫保护的工具流水线。在纯代码模式下，它是注册表对协议格式的唯一贡献，其余可见能力通过生成的 SDK 章节声明。

文件系统有两条路线：一组提供 read、write、edit、read_image 四个工具，另由独立的事件门禁插件强制先读后写策略，没有附件接缝时 read_image 干脆不注册；另一条路线是 str_replace_editor，提供查看、创建、唯一字面量替换和按行插入四个命令，要求替换目标在文件中唯一匹配。发现类工具 glob 和 grep 直接调用随包分发的 ripgrep 二进制，不依赖宿主机安装 rg，也不经过 shell 层；glob 结果超过上限时会抽样返回并报告完整列表的保存位置。

任务与状态把长程工作拆成四套正交机制：todo_write 管理检查清单，每次调用全量替换，是否允许并行进行中的条目是必填配置；goal 三件套管理跨多轮自动延续的持久目标，创建、编辑、暂停和恢复要求直接来自人类的授权，标记受阻还有最少轮数下限，防止模型轻易放弃；schedule 三件套提供会话级提醒，只有会话处于活跃状态才准时触发；job 三件套则是与任务种类无关的后台控制器，后台 bash、终端发送和 subagent 共用同一套列出、读取、终止接口。

多智能体编排最庞大：subagent 与 subagent_fork 负责委派任务；send_message、interrupt_agent、list_agents 负责控制后台子级，新消息会排进子级当前轮次之后，无法改变已经开始的工作方向；report 只在可继续的进程内子级内部可见，用于向父级交付自包含的结果。更上层还有两个编排工具：ralph 围绕不可变目标运行前台循环，每一轮都启动全新子级，共享工作区充当长期记忆；workflow 则让模型用纯 JavaScript 函数体编写编排脚本，提供 agent、pipeline、parallel、phase 等钩子，其中 pipeline 阶段之间没有屏障，parallel 会等待全部完成，误用钩子会直接报错终止脚本，并发与子级总数都有硬上限。

外围能力与可借鉴的设计

web_search、web_fetch 和 lsp 属于「接缝后置」的典范：提供方的选择藏在统一接缝后面，更换后端时模型可见的 schema 保持稳定；没有可用的语言服务器时，lsp 返回结构化的不可用错误，而不是改动 schema。skill 工具按名称加载技能说明；会话查询五件套提供只读的事件检索与谱系追踪；cordis 动态工具集需要显式启用，允许运行中的插件在虚拟机沙箱里注册额外的模型可见工具。

对想设计自己 agent 框架的人来说，这份目录至少有四点可以直接借鉴：第一，schema 即契约，文档由运行时实跑生成，代码与文档不可能漂移；第二，稳定性优先，凡是能藏进接缝的可变项都藏起来，避免目录抖动；第三，配置直接反映在 schema 上，例如关闭后台运行开关后，run_in_background 参数会被整个移除，而不是留下一个无效参数；第四，后台任务统一抽象，无论命令、终端还是子智能体，收集与终止都走同一组 job 工具。

仓库采用 MIT 协议，装好 Node.js 后用 npx @deepseek-ai/dsh web 一条命令即可在本地跑起完整框架。想研究 agent 工具层设计的读者，建议直接从这份工具目录读起，再对照源码看每个 schema 背后的接缝设计。