前言¶
用智能體寫功能時，常見情況是：一句話需求丟進對話，模型直接改代碼。規格只活在聊天記錄裏，下一輪上下文一擠，當時答應過的邊界、驗收條件和不改動的範圍就對不上了。人要回頭覈對「到底做成了什麼」，只能翻軌跡、對 diff，沒有一份可以過門的書面約定。
規格驅動開發（Spec-driven development）把這件事反過來：先把「爲什麼改、改什麼、怎麼算做完」寫成倉庫裏的 Markdown，人批准之後再實現，實現完再對照場景逐條驗收。OpenSpec 把這一套落成 openspec/ 目錄：進行中的變更放在 changes/，歸檔後合併進 specs/。DeepSeek Harness（dsh）本身是「一切皆插件」的運行時，模型、工具、會話、UI 都可以裝卸；社區維護者 tianji-qingtian 做的 dsh-spec-loop，就是把這套閉環接到 Harness 的 /spec 命令上。
本文按插件目錄頁、GitHub 倉庫 README / package.json / 發佈標籤交叉覈對後整理：它是什麼、命令怎麼走、如何安裝，以及使用時要注意的邊界。DeepSeek Harness 仍處於 developer preview，插件 API 可能出現不兼容變更；文中版本以倉庫當前發佈的 v0.1.2 爲準。
這是什麼¶
dsh-spec-loop 是一款面向 DeepSeek Harness 的開發與運行時插件，由 tianji-qingtian 維護，許可證爲 MIT。目錄頁與 GitHub 倉庫均顯示 5 星（以打開頁面時的數字爲準）。主要語言是 JavaScript，package.json 裏的版本號是 0.1.2，與 GitHub Release / tag v0.1.2 一致。
它解決的問題可以寫成一句話：用 /spec 命令族驅動「生成規格 → 批准 → 按任務實現 → 對照規格逐條驗收 → 歸檔」，變更目錄與 OpenSpec 的佈局兼容，落在工作區的 openspec/ 下。
需要分清兩件事：
- 它採用 OpenSpec 的目錄格式和階段劃分，校驗規則按 OpenSpec CLI 的核心條目自實現；不依賴單獨安裝 OpenSpec CLI。
- 它是社區插件，收錄在獨立站點 DeepSeek Harness 插件庫。該目錄自稱與 DeepSeek / 幻方無官方從屬關係，不是官方應用商店。
package.json 的 dsh.client.platform 聲明爲 web：瀏覽器半邊掛在 Web UI 上，輸入框上方會多一張規格變更卡。倉庫 README 也按 web profile 來寫安裝步驟。
核心功能¶
/spec 命令族¶
插件註冊一個 /spec 命令，再按子命令路由。命令 handler 只做流程編排和文件系統操作；提案正文、任務清單、規格增量和實現代碼，都交給當前會話的 agent 主模型，通過 agent.steer 注入任務、使用完整工具集生成。
README 列出的子命令如下：
| 子命令 | 作用 |
|---|---|
init |
創建 openspec/project.md 和目錄結構 |
new <目標> |
澄清後生成提案 / 任務 / 規格增量，並自動校驗 |
status |
只讀：當前 change-id、階段、任務進度 x/y |
list |
列出活躍變更和能力規格 |
show <id> |
查看提案全文（有 design.md 時一併展示） |
approve <id> |
批准，打開實現門 |
implement <id> |
按 tasks.md 逐項實現並勾選 |
verify <id> [--deep] |
按 Scenario 驗收；--deep 改用主模型 |
archive <id> |
合併增量到 specs/，目錄移入歸檔 |
validate [id] |
OpenSpec 格式校驗（new 之後會自動跑） |
edit <id> |
修訂提案，狀態回到 proposed |
/spec new 最多提 3 個內置選擇題，分別覆蓋範圍、約束、驗收方式，語言跟隨目標描述，走 Harness 的問答 UI。子代理會話或缺少 UI provider 時，會跳過澄清，直接往下生成。
OpenSpec 兼容目錄¶
初始化之後，工作區裏是這樣一套佈局（與 OpenSpec 的 openspec/ 形狀對齊）：
<工作區>/openspec/
├── project.md
├── specs/<能力>/spec.md
└── changes/
├── <change-id>/
│ ├── proposal.md
│ ├── tasks.md
│ ├── design.md # 可選
│ ├── verify.md # 驗收後由插件寫出
│ └── specs/<能力>/spec.md
└── archive/YYYY-MM-DD-<change-id>/
規格增量用 ## ADDED|MODIFIED|REMOVED Requirements 分段，每條 Requirement 至少要有一個 #### Scenario:。這是 OpenSpec 的校驗規則，插件內置了同款檢查：提案生成後自動跑；失敗會把修正請求再 steer 回 agent（有重試上限）。approve 會拒絕未通過校驗的變更，archive 會拒絕目錄裏不存在的變更。
歸檔時按 Requirement 逐條合併進 specs/<能力>/spec.md：ADDED 追加，MODIFIED 按名稱替換（沒有同名則追加），REMOVED 刪掉對應塊，然後用一次 mv 把變更目錄挪到 changes/archive/。
批准門和持久狀態機¶
狀態按這條鏈走：
proposed → approved → implemented → verified → archived
任意階段都可以 /spec edit 回到 proposed，改完需要重新批准。implement 拒絕狀態還不是 approved（或實現鏈更後面階段）的變更。門禁讀的是面板渲染用的同一份會話投影，顯示態和行爲態共用一份數據。
狀態不是另寫一套自定義會話事件。外置插件不能安全往 SessionEventMap 里加新類型（持久化讀路徑會拒絕未知的非 ignorable 事件），所以轉移只摺疊標準事件：command/run / command/done 成功對，再加上 agent 回覆裏的機器標記（如 SPEC_CHANGE_ID:、SPEC_IMPLEMENTED）。重啓之後變更卡、階段和門禁還在；把插件卸掉，會話日誌也仍然可讀。
有一條使用上的限制：批准狀態按會話摺疊。在一個會話裏 approve，不會自動對另一個會話生效。
逐條驗收和輸入框上方的變更卡¶
/spec verify 會按每條 Requirement 的每個 Scenario 做一次受限裁判調用：默認用 flash、關掉 thinking；加 --deep 則換成主模型。proposal.md 裏用 bash 代碼塊聲明的驗證命令會先經 ctx.shell 執行，輸出再進入裁判提示。結果寫入 verify.md，帶 ✅/❌ 表格和原始判定文本。
Web UI 裏，輸入框上方的 dock 會顯示一張全寬變更卡（README 寫成 📐 Spec）：當前 change-id、階段、任務進度 x/y，以及下一步該跑的命令。進度來自 Harness 自帶的 todos 投影——實現階段的提示詞會讓 agent 把 tasks.md 鏡像進 todo_write，面板不額外打 RPC。文案走 locale 服務，支持中英。
安裝與啓用¶
插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。裝之前應檢查源代碼倉庫和許可證；需要可復現安裝時，應固定 commit 哈希或 release tag。
目錄頁給出的安裝命令是：
dsh plugin add github:tianji-qingtian/dsh-spec-loop
倉庫 README 的前置條件：dsh CLI 必須在 PATH 上。如果平時只用 npx 啓動 Harness，本機沒有全局 dsh，會報 command not found。可以先全局安裝：
npm install -g @deepseek-ai/dsh
pnpm add -g @deepseek-ai/dsh 也可以，前提是 pnpm 的全局 bin 目錄已在 PATH 裏；或者不裝全局，給後續命令加上 npx @deepseek-ai/dsh 前綴。
README 建議把 bundle 加進 web profile，並優先釘死 release tag（文檔寫的是 #v0.1.2；#main 會跟最新提交）。lib/ 產物已經提交在倉庫裏，安裝時不跑構建：
dsh plugin --profile web add "github:tianji-qingtian/dsh-spec-loop#v0.1.2"
dsh --profile web
add 只改 profile 文件，正在跑的實例不會熱加載，需要用對應 profile 重啓。重啓後輸入框上方應出現規格變更卡，host 端加載完成後 /spec 纔會註冊。可在 Settings → Plugins 裏確認列表中有 dsh-spec-loop。
目錄頁補充了固定 commit 的寫法，形式爲：
dsh plugin add github:tianji-qingtian/dsh-spec-loop#commit
把 commit 換成實際哈希即可。當前 tag v0.1.2 對應的 commit 是 0783a43190d43accb93238f85d06d231e373bd81（以 GitHub tags API 爲準）。
package.json 聲明的 Node 引擎是 ^22.19.0 || >=24.0.0，peer 依賴指向 @deepseek-ai/dsh-* 的 ^0.1.0-rc.6 以及 @deepseek-ai/cordis ^4.0.1。Harness 還在快速迭代，裝之前應對一下本機 dsh 版本是否匹配。
典型用法¶
下面命令來自倉庫 README 的示例，change-id 以 add-user-login 爲例（/spec new 生成提案後，以 agent 回報和 /spec list 裏的實際 id 爲準）。
先初始化目錄：
/spec init
用一句話目標開一個變更。插件會先澄清，再讓 agent 寫 proposal.md、tasks.md 和規格增量，然後自動校驗：
/spec new 用戶登錄功能
查看當前卡片、列出活躍變更、打開提案：
/spec status
/spec list
/spec show add-user-login
人審閱通過後再批准。沒批准之前，implement 會被拒絕：
/spec approve add-user-login
/spec implement add-user-login
實現完成後對照 Scenario 驗收。默認 flash；需要主模型時加 --deep：
/spec verify add-user-login
/spec verify add-user-login --deep
驗收通過再歸檔，增量合併進 specs/，目錄進入 changes/archive/：
/spec archive add-user-login
中途要改提案：
/spec edit add-user-login
狀態會回到 proposed，需要重新 approve 才能再實現。輸入框上方的變更卡會同步 change-id、階段、x/y 進度和下一步命令；只想看、不想改狀態時用 /spec status。
適用場景與注意事項¶
比較適合這些情況：
- 在 DeepSeek Harness 的 Web UI 裏做功能開發，希望規格、任務、實現、驗收留在倉庫文件裏，而不是隻存在於一輪對話。
- 已經或準備採用 OpenSpec 的
openspec/佈局，希望 Harness 側的變更目錄可以直接被 OpenSpec 那套工具識別。 - 需要「不批准不實現」的門禁，以及按 Scenario 產出
verify.md的書面驗收。
使用前值得記住這些邊界（均來自倉庫 README / 需求文檔，不是額外推斷）：
- 權限與安全。插件以當前
dsh進程權限運行；verify還會執行proposal.md裏聲明的 bash 驗證命令。安裝前應閱讀源碼和 MIT 許可證，不要對不信任的倉庫執行dsh plugin add。 - 平臺。客戶端聲明爲 web，變更卡掛在 Web UI 的 composer dock。README 的安裝路徑也是
--profile web。 - 會話維度的批准。A 會話裏批准過的變更，B 會話不會自動視爲已批准。
- 不監聽寫文件來強制門禁。v1 只做命令級門：未
approve時拒絕/spec implement，並不會攔截 agent 用普通工具直接改實現文件。 - 不兼容 GitHub spec-kit 目錄格式。需求文檔寫明 v1 只兼容 OpenSpec；spec-kit 留作後續擴展。
- Harness 預覽版。官方說明 DeepSeek Harness 仍在 developer preview，核心插件和 API 會繼續變。README 也提醒可能出現破壞性變更。
- 同名項目不要裝錯。社區裏還有
dsh-specflow、ds-spec-loop等規格相關項目，機制和安裝源都不同。本文只對應github:tianji-qingtian/dsh-spec-loop。
小結¶
dsh-spec-loop 把規格驅動開發接到 DeepSeek Harness 上：/spec 負責開門和落盤，agent 負責寫提案和改代碼，OpenSpec 形狀的 openspec/ 作爲可審查的事實來源。批准門、格式校驗、逐 Scenario 驗收和輸入框上的變更卡，都是爲了讓「先約定、再實現、再對照」在一次會話裏跑得完。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-spec-loop/
GitHub：https://github.com/tianji-qingtian/dsh-spec-loop
