DeepSeek Harness 加功能该挂哪个扩展点？DSH plugin 功能到机制映射手册
DSH plugin 的功能不是随便挂的：官方给出一张功能→机制映射表，把每一个产品功能都对应到一个文档化扩展点上的监听器，以此证明微内核声明可验证——没有任何一行修改 agent loop 循环本身（来源）。 本文把这张表整理成每个 DSH插件 作者都能反查的「我想加 X → 挂哪个扩展点」手册，并讲清三类归属的选型判据；扩展点本身的三类定义（core / seam / bundle）已写在站内 DSH plugin 核心服务与能力 Seam，这里不重复。
为什么 DeepSeek Harness 的功能→机制映射让微内核可验证
官方把微内核说法落成一条可验证的声明：每个产品功能都映射到一个文档化扩展点上的监听器，因此可以按功能逐条核对，而不必信任任何「循环里改了一行」的说法（来源）。 官方实操手册进一步把扩展归纳为四种参考模式：
- 工具插件 — 在
ctx.tools上注册，defineTool是类型化辅助函数，也接受原始 JSON Schema（MCP 来源的工具就是这样到达的）。 - 钩子插件 — 在拦截点上运行，以权限门禁为例（
tools/pre-execute返回{ kind: 'deny', reason }或next()），沙箱、权限与 plan-mode 插件都复用该扩展点。 - UI 插件 — 从
session/event事件流渲染，并通过agent.followup()/agent.steer()把输入驱动回去。 - 外部协议驱动 — 把协议对端接入
ctx.agents，可服务 UI 或自动化客户端。
这四种形态本身就是选型答案：你的插件属于哪一类，就说明它主要挂在哪个扩展点上。
DeepSeek Harness 功能→机制对照表
官方对照表把产品功能与插件机制一一对齐，覆盖从钩子系统到插件热重载的绝大多数功能（来源）。 节选整理如下：
| 产品功能 | 插件机制 |
|---|---|
| 钩子系统（用户级 + 项目级） | agent/session-start、agent/pre-step、agent/request、tools/pre-execute、tools/post-execute、agent/turn-stopping 上的监听器；agent/turn-stopping 可用 steering 触发下一步 |
/goal | ctx.goals 管理持久状态，dsh-goal-round-driver 通过公共 Agent 调度同会话 Round |
/loop | 在 turn/end 会话事件上 followup() 下一次迭代，或强制继续 |
| 排队消息 + steering | 核心 Agent.followup() / Agent.steer() |
| 上下文压缩（自动 + 手动） | ctx.compaction seam + dsh-compaction-basic；压力检查在串行 agent/pre-step，溢出恢复在 agent/request-error |
| 系统提示词可配置性 | ctx.systemPrompt.section()，支持排序与作用域局部覆盖 |
| AGENTS.md（根目录） | 一个读取该文件的 section 提供方 |
| 内置工具 | ctx.tools.register()，schema 自动流入装配（dsh-tool-* 系列） |
| ToolSearch / 渐进式披露 | 可见集变化时替换一个作用域化的 ctx.tools.restrict() 注册 |
| 工具截止时间 / 重试 / 指标 | 用 tools/execute 包裹核心分发（仅 exec.signal 可替换） |
| 最终工具结果审计 / 捕获 | 用 tools/result 观察不可变结果；需要变换时才用 tools/post-execute |
| 单调终端轮次策略 | 从成功的终端工具调用 ToolExecution.concludeTurn() |
| 子进程沙箱 | ctx.sandbox 后端；能力级拒绝用 tools/pre-execute |
| 权限系统 / AskUserQuestion | 从 tools/pre-execute 返回 ask 并通过 ctx.approval 应答；为普通用户提问注册独立的面向模型的 ask 工具 |
| Plan mode | 落日志的 plan/mode 状态、plan:policy 引导段、/plan [message] 入口与经用户评审的 exit_plan_mode 出口 |
| subagent 委派 | ctx.subagents 提供方注册表 + dsh-tool-subagent 向模型暴露一个已配置的提供方 |
| MCP | 每个服务器一个插件：发现工具 → ctx.tools.register() |
| skill（技能） | section + 工具注册；调用时通过 inject() 注入 skill 内容 |
| 记忆 | section 提供方 + 工具 |
| 定时任务（cron） | 插件注册面向模型的调度工具；空闲时 followup(…, { source: { kind: 'cron', … } })、忙碌时 inject() 通知 |
| UI（GUI；CLI 输出 JSONL） | 监听 session/event（助手分片、边界、工具活动）；输入 → followup() |
| Web Client Chat 业务节点 | 注册 ConversationNodeDefinition 与 conversation.chat.node keyed renderer |
| 遥测 / 可回放 trace | session/event → JSONL；回放 = sessions.create(id, { seed }) |
| 模型适配器 | 通过 registerAdapter 注册 LlmAdapter 子类 |
| 插件热重载 | 每个注册都是一个 ctx.effect，随仓库提供的 HMR 直接生效 |
用法是反查：先写出你要的功能名，在表里找到对应的插件机制，再去看该机制的细节文档；查不到时，说明你正在做的是「独立的内聚领域服务」，而不是在既有扩展点上挂监听器。
DSH plugin 扩展点归属：三类判据与收尾自检
选扩展点的判据只有一条——「你要换的是什么」（来源）。 落到操作上分四步：
- 换某个能力的实现 — 接入既有服务 Seam，例如
ctx.llm、ctx.fs、ctx.shell、ctx.compaction、ctx.sessionPersistence。预期：上层工具零改动。 - 扩展流水线环节 — 挂事件监听，waterfall 返回类型化决策；不要替换主干服务。预期：扩展可逆、可卸载，事件写法见 DSH plugin 事件系统。
- 做产品形态装配 — 用组合包与 bundle point 在配置层选定 Provider。预期：换实现只改组合。
- 都不属于以上三类 — 作为独立的内聚领域服务实现，例如按领域划分的 registry。预期：不与主干或 Seam 混淆。
两个官方特别提示不能忽略：其一，system-prompt/assemble 是专家协作式的整体装配变换，其返回结果具有权威性，因此监听器作者有责任保留活跃的 Code Mode 与结构化输出协议的贡献；其二，需要在展示、查找与执行之间保持对齐的工具过滤，优先使用 ctx.tools.restrict()，而不是自己维护可见集。写完自检三项：功能是否确实映射到了某个扩展点；是否误把「扩流程」当成「换实现」；注册与订阅是否都留在 apply 内随 fiber 回滚。想按同一扩展点对照社区实现，可在 DSH Plugin Hub 检索；扩展点的三类边界见 核心服务与能力 Seam，工具契约细节见 工具编写参考。
常见问题
DSH plugin 新增功能时先问「要换的是什么」：换某个能力的实现就接入既有服务 Seam，扩展流水线环节就挂事件监听，做产品形态装配就走组合包与 bundle point，三者都不属于才做独立的内聚领域服务。官方把每个产品功能都映射到一个文档化扩展点上的监听器，正是这套判据可验证的原因。
DeepSeek Harness 的功能→机制映射表说明微内核声明是可验证的：每一个产品功能——钩子系统、/goal、/loop、上下文压缩、MCP、skill、定时任务、遥测回放等——都对应一个文档化扩展点上的监听器，没有任何一行修改 agent loop 循环本身。
DSH plugin 按功能类型选扩展点：/goal 走 ctx.goals 加公共 Agent 调度的 Round 驱动，/loop 在 turn/end 会话事件上 followup() 下一次迭代，定时任务由插件注册面向模型的调度工具并在空闲时 followup()、忙碌时 inject() 通知，subagent 委派走 ctx.subagents 提供方注册表加 dsh-tool-subagent 暴露给模型。
DSH plugin 做工具过滤时优先用 ctx.tools.restrict()，让展示、查找与执行三者保持对齐；做系统提示词装配时要知道 system-prompt/assemble 是专家协作式的整体装配变换，返回的装配结果具有权威性，因此监听器作者有责任保留活跃的 Code Mode 与结构化输出协议的贡献。
对照功能→机制映射表选好扩展点后，可以到 DSH Plugin Hub 检索落在同一扩展点的社区插件，对照它们的监听器与 provider 写法。扩展点本身的 core / seam / bundle 分类见站内的能力 Seam 文章，事件分发写法见事件系统文章。
相关术语
- 功能→机制映射（feature-to-mechanism mapping）
- 功能→机制映射是 DeepSeek Harness 官方给出的一张对照表，把每个产品功能对应到一个文档化扩展点上的监听器，用于证明微内核声明可验证——没有任何一行修改 agent loop 循环本身。— https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook
- 微内核（microkernel）
- 微内核是 DeepSeek Harness 的架构声明：内核只保留 agent loop，所有产品功能都作为插件在文档化扩展点上监听，因此可以按功能逐条核对扩展点，而不必改动循环本身。— https://deepseek-harness.github.io/deepseek-harness/reference/
- 参考模式（extension pattern）
- 参考模式是官方实操手册归纳出的插件形态——工具插件、钩子插件、UI 插件与外部协议驱动，每种形态对应一类典型扩展点组合，代码片段省略 import 与辅助实现，不能直接复制运行。— https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook
- 类型化决策（typed decision）
- 类型化决策是 waterfall 钩子在拦截点上返回的结果对象，例如 tools/pre-execute 返回 deny 或调用 next() 放行，让策略层可重排，而单调的最终拒绝要用 ctx.tools.guard()。— https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook
来源
- DeepSeek Harness 官方文档 - 实操手册：扩展插件形态· deepseek-ai
- DeepSeek Harness 官方文档 - 架构总览· deepseek-ai
- DeepSeek Harness 官方文档 - 工具编写参考· deepseek-ai