前言¶
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
