参考资源与能力地图
这是本教程的收尾章节。前面各章带你写过一个插件、注册过服务与事件；这一章回答三个问题：接下来去哪查文档、DSH 的能力分布在哪里、想实现某个目标该动哪个扩展点。全文术语保留英文原词，中文仅作解释。
官方文档导航
DSH 官方文档站（中英双语，源码在仓库 docs/ 下，同目录 .zh.md 为经评审的中文对侧）位于：
https://deepseek-harness.github.io/deepseek-harness/
站点按 guide（入门）→ develop（开发）→ reference（参考） 组织，与仓库 docs/ 的对应关系如下：
| 站点模块 | 站点路径 | 仓库源（docs/） |
|---|---|---|
| 入门 Guide | /guide/quickstart、/guide/providers | user/guide/（Web UI 使用、模型配置） |
| SDK | /guide/python-sdk | user/guide/python-sdk.md |
| 开发 · 基础 Basics | /develop/basic/ | user/develop/basic/（第一个插件、开发 Tool、配置、打包） |
| 开发 · 框架能力 Framework | /develop/framework/ | user/develop/framework/（生命周期、服务与依赖、事件系统） |
| 开发 · 实战 Practice | /develop/practice/ | user/develop/practice/（能力三层拆分、LLM 适配器） |
| Cordis 框架教程 | /develop/cordis-tutorial/ | cordis-tutorial/（7 章动手实践） |
| 参考 · 概念 Concepts | /reference/（index=架构）、/reference/cordis-primer、/reference/capability-seams、/reference/agent-lifecycle、/reference/tool-execution-pipeline | architecture.md、cordis-primer.md、capability-seams.md、agent-lifecycle.md、tool-execution-pipeline.md |
| 参考 · 生成参考 Generated reference | /reference/config-catalog、/reference/tool-catalog、/reference/persistence-catalog | 三份 catalog（见下文） |
| 参考 · Cordis API | /reference/cordis-api/ | cordis-api/（Context / Events / Fiber / Registry / Service） |
| 参考 · 开发手册 Cookbook | /reference/cookbook/ | cookbook/（新增 Package、Tool、LLM Adapter、Conversation Node、扩展模式） |
| 参考 · 子系统 Subsystems | /reference/subsystems/ | subsystems/（每个子系统一页，含生成的 Cordis API 小节） |
另有部分仓库内部文档未发布到站点，但对贡献者重要：development.md（开发指南）、testing.md（测试策略）、defensive-patterns.md（防御性模式）、event-producer-consumer.md（事件生产方/消费方矩阵）。
能力地图
能力 seam（seam）是一个可替换能力，含三种角色：Service Definition（声明接口）、Service Provider（实现）、Consumer（通常是面向模型的工具）。core 是只有一份实现的核心主干服务；bundle 是组合包（如唯一的具体循环插件 ctx.agentLoop）。替换一个 seam 的后端即可改变整个产品行为。下表按域列出主要服务及其可替换后端（完整图与全部 60+ 服务见 capability-seams.md）：
| 域 | ctx 键（角色） | 可替换后端 / 说明 |
|---|---|---|
| 会话与持久化 | ctx.sessions（core） | 仅追加的 SessionEvent 日志；ctx.sessionPersistence（seam）→ session-persistence-jsonl / session-persistence-sqlite；ctx.sessionQuery（seam）→ session-query-sqlite（全文检索）；ctx.sessionTitle（seam）→ session-title-first-prompt-llm / session-title-all-prompts-llm；ctx.sessionProjections / ctx.sessionProjectionCache（core）；ctx.sessionTelemetry（seam）→ session-telemetry-otel |
| 模型与提示词 | ctx.llm（seam） | llm-deepseek / llm-pi-ai / llm-replay；ctx.compaction（seam）→ compaction-basic；ctx.systemPrompt、ctx.tokenMeter、ctx.toolResultPruner、ctx.agentDefaultModel、ctx.agentPresets（core） |
| 工具与 Agent | ctx.tools、ctx.agents、ctx.commands、ctx.planMode、ctx.goals（core）；ctx.agentLoop（bundle） | ctx.subagents（seam）→ subagent-spawn-in-process / subagent-fork-in-process / subagent-acp / subagent-codex / subagent-claude-code / subagent-dsh-sdk；ctx.workflowEngine（seam）→ workflow-worker-thread；ctx.codeRuntime（seam）→ code-runtime-worker；ctx.skills（seam）→ skill-filesystem / skill-badge；ctx.userQuestions（seam，UI 前端提供回答方） |
| 执行与沙箱 | ctx.sandboxPolicy、ctx.shellEnv、ctx.e2b（core） | ctx.fs（seam）→ fs-local / fs-sandbox / fs-e2b；ctx.shell（seam）→ bash-local / bash-sandbox / pwsh-local；ctx.subprocess（seam）→ subprocess-local / subprocess-e2b；ctx.sandbox（seam）→ sandbox-local；ctx.terminals（seam）→ terminal-bash；ctx.jobs（seam）→ jobs-local；ctx.spillStore（seam）→ spill-local；ctx.lsp（seam）→ lsp-local |
| Web 与宿主 | ctx.webServer、ctx.clientModules、ctx.apiProxy、ctx.typert / ctx.typertGateway、ctx.dynamicCordisRunner / ctx.cordisInspect、ctx.workspaceRegistry、ctx.messageFeedback（core） | ctx.web（seam）→ web-search-exa / web-search-perplexity / web-search-deepseek / web-fetch-http；ctx.directoryPicker（seam）→ directory-picker-native / directory-picker-browse；ctx.attachments（seam）→ attachment-local |
| 配置与安全 | ctx.storageDomain、ctx.permissionPresets、ctx.invariants（core） | ctx.settings（seam）→ settings-file；ctx.credentials（seam）→ credentials-local；ctx.storage（seam）→ storage-json / storage-sqlite；ctx.approval（seam）→ acp（桥接）等回答方 |
几个关键替换示例：ctx.fs 指向远程沙箱时，Bash、PTY 与 LSP 一并搬过去（共享同一个执行世界）；ctx.subagents 同一接口后既能新建进程内子 agent，也能把轮次委派给 ACP、Codex、Claude Code 或 dsh-sdk 子进程。
生成式参考三目录
仓库把三类信息做成了生成 + 门禁的权威参考（中文版经双语配对维护，pnpm run doc-sync 校验新鲜度）：
- config-catalog（插件配置目录）：以部署为轴，逐个列出可加载包的
config:块声明与Requires:注入；由scripts/gen-config-catalog.ts生成，并与运行时 schemastery schema 交叉核对，粘贴内容无法隐藏 loader 接受的字段。 - tool-catalog（Tool Schema 目录）：以模型为轴，列出所有面向模型的工具的
name/description/ JSON Schema 原文；由gen-tool-catalog.ts启动式生成（挂载每个工具包、调用ctx.tools.schemas()读取真实 schema），并带完整性守卫——新增工具包未登记即失败。 - persistence-catalog（持久化事件目录）：以记录为轴，是完整
SessionEventMap词汇的权威参考（含 surface 徽章与 JSDoc）；由gen-persistence-catalog.ts做 AST 遍历生成，强制每条事件有描述。
三者分别是部署配置面、模型工具面、持久化事件面；与 subsystems/（词汇）、cordis-api/（接线）互补，构成「如何配置、模型看到什么、磁盘记录什么」的三维坐标。
常见扩展点速查表
想实现什么，先找对扩展点（选自 architecture.md 的归属表）：
| 目标 | 扩展点 |
|---|---|
| 添加模型提供方 | 在 ctx.llm 上注册适配器 |
| 添加面向模型的能力 | 在 ctx.tools 上注册；其 schema 自动加入提示词组装 |
| 让会话拥有不同能力集合 | 组装一个 agent preset（服务行需要 isolate realm） |
| 添加 shell 执行 | 注册 ctx.shell 后端；本地后端经 ctx.subprocess spawn |
| 添加持久化终端执行 | 注册 ctx.terminals 后端和 tool-terminal |
| 添加用户命令 | 在 ctx.commands 上注册；无需模型轮次即可分派 |
| 添加后台工作 | 在 ctx.jobs 上注册；job_* 工具负责收集或停止 |
| 添加文件系统访问或策略 | 注册 ctx.fs 提供方，或监听 fs/* 事件 |
| 限制所启动的进程 | 使用 ctx.sandbox 后端；消费方在 spawn 前包装 argv |
| 拦截请求、工具或轮次 | 使用相应 agent/* 或 tools/* 事件；agent/turn-stopping 可停止轮次 |
| 添加模型可见上下文 | 调用 agent.inject()；落入下一次获准的请求 |
| 添加 UI 或编辑器集成 | 驱动 ctx.agents 并从 session/event 渲染 |
| 添加 Web Chat 节点 | 注册 ConversationNodeDefinition + keyed renderer |
| 添加持久会话状态 | 扩展 SessionEventMap；从日志渲染和回放 |
| 生成会话标题 | 注册唯一的 ctx.sessionTitle 提供方 |
| 管理同会话目标 | 使用 ctx.goals；经 agent/* 续跑 |
| fork 活跃会话 | ctx.sessions.fork(source, boundary?, childSessionId?) |
| 限定注册到单个 agent | 使用该 agent 的 agent.ctx |
下一步建议
- 动手改造：从
packages/里挑一个与你目标最接近的tool-*包复制改造，按cookbook/adding-a-tool.md与adding-a-package.md的步骤走一遍，再对照subsystems/tools.md的ToolDefinition字段。 - 先读概念再写代码：开工前通读
cordis-primer.md与defensive-patterns.md（写生命周期、并发、子进程、清理代码前必读），能避开仓库踩过的绝大多数坑。 - 遵守仓库纪律：注册是 effect、每个注册都要有 disposer；面向模型/邻近模型的包 README 要有 Model Experience 章节；改动文档后跑
pnpm run doc-sync。 - 查表定位：遇到新能力需求，先回到本页「常见扩展点速查表」，再从
capability-seams.md找对应 seam 的三个角色和已有实现，最后读该子系统的参考页确认类型与事件签名。
至此，你已经拥有 DSH 插件开发的完整地图——祝改造愉快。