DeepSeek Harness 扩展手册：四类插件形态

DeepSeek Harness（简称 dsh）是 DeepSeek 在 GitHub 上开源的智能体框架，MIT 协议，目前处于开发者预览阶段，一条 npx @deepseek-ai/dsh web 就能在本地跑起 Web 界面。它基于 Cordis 微内核，设计口号是"一切皆插件"：从内置的 bash、文件系统工具，到计划模式、子代理、定时任务，全部以插件形式挂在统一的扩展点上。项目文档里的扩展手册（extension cookbook）专门整理了插件的标准形态与选型规则，是理解这套架构最直接的一份材料，本文带你过一遍要点。

每个功能都是一个监听器

Harness 的内核只管生命周期与事件分发，能力全部由插件注入。每个插件是一个普通的 Cordis 模块：导出名称和 apply 函数，通过依赖注入拿到 ctx 上下文，再在 ctx 上注册工具、监听事件或挂载服务。手册里有一条可验证的硬结论：每一个产品功能都对应某个文档化扩展点上的监听器，没有任何一行代码绕开循环去修改内核。

为此手册给出一张功能到机制的映射表。比如 /goal 命令对应 ctx.goals 的持久状态加同会话轮次驱动；/loop 是在 turn/end 事件上调用 followup 续跑下一轮；上下文压缩对应 ctx.compaction 接缝，压力触发的自动压缩、溢出恢复与手动压缩走同一个服务；MCP 支持则是每个服务器一个插件，发现工具后调用 ctx.tools.register()。系统提示词装配、AGENTS.md 注入、定时任务、模型适配器，也都能在这张表里找到明确的挂点。

四类插件形态

手册把常见扩展归为四类，各自遵守不同的约定。

第一类是工具插件，注册在 ctx.tools 上。官方提供类型化的 defineTool 辅助函数：execute 参数带类型，结果有构造规范，还支持 run_in_background 的后台执行模式；来自 MCP 的工具则直接以原始 JSON Schema 的定义注册。两条通道汇入同一个注册表，工具的呈现、检索与执行保持对齐。

第二类是钩子插件，典型例子是权限门：插件在 tools/pre-execute 瀑布上返回类型化决策，决定放行还是拒绝一次工具调用。

export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next) => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()
  })
}

这个瀑布就是可重排的策略层，手册给了明确的选型规则：需要单调终审的不变量用 ctx.tools.guard()；要包装真实调度生命周期（超时、重试、指标）用 tools/execute，包装器只能替换 exec.signal；要显式转换结果用 tools/post-execute；只读观测最终不可变结果用 tools/result。沙箱、权限、计划模式跑在同一批扩展点上，所谓原生钩子就是一个普通插件，不需要任何外部协议。

第三类是界面插件，从 session/event 事件流渲染：里面既有 assistant/chunk 文本增量，也有回合与步骤边界、工具活动；用户输入通过 agent.followup() 与 agent.steer() 回注给智能体。想在内置 Web 客户端里贡献业务消息节点，则注册会话节点定义和带键的聊天渲染器。

第四类是协议驱动，把一个线上协议对端适配到 ctx.agents，既能服务界面也能服务自动化客户端。stdio 驱动独占标准输出，通过工厂创建或恢复智能体，把协议请求映射为 followup() 或 cancel()。这里有个容易踩的设计点：低层的 prompt 请求只返回持久化的入队回执，不要靠消息 ID 关联 turn/end 来等结果，智能体整体状态单独推送；收尾用 AgentHandle.dispose()，让停机真正到达静止状态。仓库里的 ACP 包是自动化场景的完整范例：通过 JSON-RPC stdio 暴露全新会话，提交助手文本，并为自有智能体注册一次性机器权限应答器。

怎么上手

手册把 examples 目录下的 cordis.yml 当作插件装配清单的权威来源，根目录的 demo 脚本可以直接拉起各种形态：dsh 启动器负责 Web 与一次性无头执行，另有 ACP、JSON-RPC 与无头快照三个示例目录，各自挂载不同的插件树。

想动手的话，路径不复杂：装好 Node.js 后用 npx @deepseek-ai/dsh web 起一个本地实例，先从工具插件或钩子插件写起最直观，再按需进入界面层与协议驱动。如果你正在调研智能体框架的扩展性设计，这张功能到机制的映射表值得逐行读：它把"微内核"的架构宣称，变成了可以逐条核对的清单。