前言¶
DeepSeek Harness（简称 DSH）是 DeepSeek AI 开源的智能体运行框架，核心理念是「一切皆插件」：模型适配器、会话、工具、审批、持久化和网页界面，都通过 Cordis 插件树组合起来。官方仓库目前仍处于 developer preview，文档写明会有破坏性变更。在这种节奏下做长期二次开发，常见麻烦不是找不到源码，而是上下文太大：产品边界、模块归属、扩展点和质量约束散落在上游 docs/、生成目录和源码注释里；把整仓丢给 Codex 或 Claude Code，既容易读偏，也容易把文档声明当成已经实现的行为。
dsh-specs 针对的就是这件事。它不提供新的运行时工具，而是把某一固定上游提交上的产品、架构、运行流程、扩展点与质量约束，整理成适合智能编码工具按需读取的规格库。下面按社区目录页、仓库 README、AGENTS.md、来源锁文件和上游官方仓库交叉核对后说明：它是什么、覆盖哪些文档、怎么装、以及落地前必须守住的证据边界。
这是什么¶
dsh-specs 的仓库标题是「DSH 智能开发规格库」，由 showjiangnan 维护，采用 MIT 许可证（版权声明沿用上游 DeepSeek）。社区插件目录把它归在「工具与能力」。GitHub 仓库当前星标为 8（目录页仍显示 6，以仓库页面为准）。package.json 中的版本号是 0.1.0。
它服务两类工作：
- 基于 DSH 做长期二次开发
- 为 DSH 开发新的插件、能力提供方和集成服务
仓库明确写出能力边界：这里不包含 DSH 产品源码，也不能单独构建或运行 DSH。文档是从上游源码仓库的固定 commit 提取并复核的规格快照；开始实现前，编码工具仍须在匹配的源码 checkout 中核对代码、测试和配置。
当前来源基线记录在 source-lock.json 和《来源与同步》中：
| 项目 | 值 |
|---|---|
| 上游仓库 | deepseek-ai/deepseek-harness |
| 公开上游基线 | 47f943859bef60e4160492346772ded9b24f765a |
| 文档整理提交 | e72527180a3ccde6378944b021b9440572ab17e4 |
| 提取日期 | 2026-08-14 |
需要区分两件事：DeepSeek Harness 本体由 DeepSeek AI 维护；deepseek-harness-plugin.com 是独立的社区插件目录，与 DeepSeek / 幻方没有官方从属关系，不能把它当成官方应用商店。
核心功能¶
给编码工具准备的最短接管路径¶
仓库把「先读什么」写成固定顺序，避免一次灌入全部文档。建议把规格库与源码仓库放在同一个工作区：
工作区/
├── deepseek-harness/ # DSH 源码
└── dsh-specs/ # 本规格库
然后让工具依次读取：
AGENTS.md：本仓库的读取、证据和维护规则docs/开发/智能编码工具接管指南.zh.md：按任务控制上下文范围ARCHITECTURE.md：系统级短入口docs/文档导航.zh.md：进入产品、前端、后端、质量或具体子系统
Claude Code 会通过根目录的 CLAUDE.md 读取同一份代理说明（该文件内容是指向 AGENTS.md）；支持 AGENTS.md 的工具可以直接从根目录建立上下文。
给 Codex 或 Claude Code 的首条指令，仓库给出的原文是：
先阅读 dsh-specs/AGENTS.md 和 dsh-specs/docs/开发/智能编码工具接管指南.zh.md。
本次任务是：<任务>。
以 dsh-specs 作为导航和约束，以 deepseek-harness 当前源码与测试作为实现事实；
区分已验证事实、文档声明和推断，并引用具体文件与符号。
按区域划分的文档地图¶
文档文件使用中文语义名；无 .zh 后缀的文件保存英文内容，.zh.md 保存简体中文，配套 .i18n.yaml 记录两种语言最后一次确认一致时的内容哈希。
| 区域 | 回答的问题 |
|---|---|
docs/产品/ |
DSH 为谁解决什么问题，当前承诺和假设是什么 |
docs/架构/ |
系统如何组合，模块如何依赖，运行时怎样流动 |
docs/前端/ |
浏览器端如何启动、管理状态、扩展和渲染 |
docs/后端/ |
Host 如何启动、处理请求、持久化并隔离执行 |
docs/开发/ |
如何搭建源码、理解框架并开发插件 |
docs/参考/ |
服务、事件、类型、工具和配置的查阅材料 |
docs/质量/ |
测试、安全、可靠性和变更证据要求 |
docs/规划/ |
有边界的进行中计划与仍有价值的完成记录 |
AGENTS.md 还规定：每项事实只有一个归属文档；其他页面只保留摘要和链接。不要把教程、参考目录、计划和决策理由混在同一页面。
规格与源码的证据边界¶
这是这份仓库最关键的约束，也写进了 AGENTS.md 和《来源与同步》：
- 规格固定到上述公开上游 commit，提供方向、术语、归属和约束，但不替代目标 checkout
- 源码、测试、配置、生成器和完整决策历史仍归上游仓库；本仓库未收录的内容用固定到该 commit 的 GitHub 链接引用
- 对当前基线：源码与已检入配置确定已实现行为，测试确定已执行的案例，生成目录提供由源码推导的清单，当前状态文档解释这些事实如何组合
- 若实际开发用的是另一个上游 commit，必须把差异列为待验证项，不能把本仓库文档当作比当前代码更高的事实来源
- 构建、测试、类型检查、生成 freshness（生成结果是否仍与源码一致）和运行验证，必须在上游源码 checkout 中完成；本仓库的绿色文档检查不能替代它们
插件开发时要先定位的三条接缝¶
接管指南把能力接缝写成「抽象服务、具体实现和消费代码」的完整连接。新增插件或能力方时，应先定位三种角色：
- Service Definition：定义能力接口
- Service Provider：实现能力
- Consumer：使用能力
应复用公共服务方法和事件，不要直接导入具体 provider，也不要修改智能体循环。对每个插件，指南要求确定：Cordis 插件入口和经过验证的配置；它依赖或贡献的服务与事件；注册、释放和失败行为；模型／工具 JSON、文件、进程、队列和远程调用的信任边界；模型可见数据是否记录为会话事件；以及用来证明组合后行为的包测试、可运行示例、无密钥快照和文档。
ARCHITECTURE.md 对运行时的概括是：CLI 根据 profile（具名运行组合）叠加 bundle（可安装的配置层），Cordis 再把这些配置加载为插件树。新增能力通常应挂接既有服务或事件。
文档自身的离线校验¶
本仓库的校验器只使用 Node.js 标准库，不需要安装依赖：
npm run docs:check
git diff --check
它检查中文语义路径、Markdown 本地链接与锚点、双语配对结构、配对哈希和文本结尾。package.json 里对应的脚本是 node scripts/校验文档.mjs。
安装与启用¶
社区目录页给出的安装命令如下，在 DeepSeek Harness 终端中运行：
dsh plugin add github:showjiangnan/dsh-specs
如需可复现安装，目录页说明可以固定 commit 哈希：
dsh plugin add github:showjiangnan/dsh-specs#commit
把 #commit 换成实际的 Git 提交哈希即可。
需要同时看到的是：当前仓库是文档工程。根目录能看到 AGENTS.md、ARCHITECTURE.md、docs/、source-lock.json 和校验脚本，未见常见的 plugin.json 清单文件；README 描述的用法是把规格库放到源码旁边，供 Codex、Claude Code 等工具读取，而不是给正在运行的 dsh 进程增加一套新工具。目录页仍提供上面的 dsh plugin add 命令，但没有另作运行时能力说明。若目标是二次开发时的规格导航，更贴近仓库原文的做法是克隆到工作区，并让编码工具从 AGENTS.md 起步。
典型用法示例¶
下面几类任务，接管指南给出了「主要上下文」和「应检查的源码证据」。规格库只负责导航，证据仍在 deepseek-harness 里。
| 任务 | 主要上下文 | 应检查的源码证据 |
|---|---|---|
| 修改 DSH 核心行为 | 架构总览、运行机制、后端流程 | 所属核心包、agent loop、会话事件、聚焦测试 |
| 新增 provider 或 adapter | 能力边界、后端执行、子系统参考 | Service Definition、已有 provider、配置 schema、生命周期测试 |
| 新增工具或插件 | 框架基础、扩展手册、工具参考 | Consumer 插件、注册 effect、渲染意图、可运行示例和快照 |
| 扩展 Web 界面 | 前端架构、会话与渲染、界面扩展 | Client 插件入口、远程方法、共享状态、渲染测试 |
| 修改持久化或协议 | 状态与持久化、接口网关、可靠性与安全 | 版本常量、解析器、迁移、wire 测试、回滚行为 |
| 修改文档 | 文档维护规则、来源与同步 | 所属实现、生成器、双语配对、文档门禁 |
一个可复现的起步方式：
- 检出与快照匹配的上游源码，或至少记录当前 checkout 的 commit
- 把
dsh-specs放在旁边 - 把上一节的首条指令发给编码工具，把
<任务>换成具体目标，例如「为 DSH 增加一个新的工具插件」 - 工具按接管指南进入
docs/开发/和相关子系统，再在源码中核对符号与测试 - 实现与验证只在
deepseek-harness中进行；dsh-specs这边最多跑npm run docs:check
仓库还提醒：不要预先加载全部生成目录。入口文档说明事实归属；只有任务确定了所属服务、事件、类型、工具或配置字段后，详细参考才应进入上下文。
适用场景与注意事项¶
适合使用 dsh-specs 的情况大致是：
- 要在 DSH 源码上做持续二次开发，需要一份按模块切开的规格入口
- 要写插件、能力提供方或集成服务，需要先弄清 Service Definition / Provider / Consumer 的接缝
- 使用 Codex、Claude Code 等编码工具，希望它们按任务加载最小上下文，而不是整仓扫描
不适合把它当成：
- 可运行的 DSH 发行版或替代源码 checkout 的安装包
- 会随上游默认分支自动更新的「最新文档」
- 比当前代码更高的事实来源
使用时还有几条已经写进仓库或目录页的约束：
- 插件以当前 dsh 进程的权限运行，安装时可能执行代码。安装前应检查源代码仓库和许可证；需要可复现安装时，固定 commit 哈希。
- 快照不会自动跟随上游默认分支。上游仍在 developer preview，官方 README 写明会有兼容性破坏变更。实现时若源码 commit 与
47f943859bef60e4160492346772ded9b24f765a不同，先把差异记为未知项。 - 生成页必须先在匹配的上游 checkout 中运行生成器，再同步到本仓库；禁止在
dsh-specs里手工改生成内容。 - 本仓库不安装运行时依赖，也不声称替代上游的构建、测试、类型检查、生成 freshness 或 VitePress 门禁。
小结¶
dsh-specs 把某一固定上游提交上的 DSH 产品、架构、扩展点和质量约束，收成一份给智能编码工具按需读取的规格库。它不包含源码，也不能单独跑起 DSH；价值在于把「先读哪一页、事实归谁、证据在源码的哪里」写成可执行的规则。对要在 DSH 上做长期二次开发或写插件的人，可以把它和 deepseek-harness 放在同一工作区，从 AGENTS.md 和接管指南开始，再以当前源码与测试为准做实现。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-specs/
GitHub：https://github.com/showjiangnan/dsh-specs
