前言¶
在 DeepSeek Harness（DSH）裏讓智能體寫代碼、寫文檔，常見摩擦不是「模型不懂話」，而是需求裏缺幾個只有你知道的答案。模型會按默認值猜，成品不對再改一版——來回比開工前問清楚貴得多。社區插件 dsh-clarify（澄清模式）把「問」挪到動手之前：打開開關後，模型先複述要求，再用自帶的訪談面板逐題確認，最後給出一張需求卡，你點「確認開工」之後纔開始改文件。維護者是 pyc123720，倉庫 pyc123720/dsh-clarify，當前版本 0.4.0，許可證 MIT；在 SkillHub 插件目錄 中分類爲「工作流」。
下面按「它是什麼 → 能做什麼 → 怎麼裝 → 怎麼用 → 注意邊界」介紹，事實均來自項目 README 與 package.json。
這是什麼¶
一句話：Ask first, build once——可選的澄清模式，讓智能體在開工前訪談你，再按你批准的需求卡執行。
插件通過 Cordis 補丁掛進 DSH，向模型注入「問題優先」的提示詞，並提供 clarify_ask、clarify_brief 等工具；Web 客戶端在輸入框上方渲染訪談面板，狀態落在宿主 $DSH_HOME/clarify/state.json，不依賴瀏覽器本地存儲。TUI 或 headless 環境沒有面板時，會自動退回內置問答，且一次只問一題，不會把多題塞進一個回答框。
運行環境要求（見 package.json）：Node >= 22.19.0，DSH >= 0.2.0-rc.1 且 < 0.3.0。
核心功能¶
訪談面板（0.2 起由插件自渲染）¶
打開澄清開關後，提問出現在輸入框上方的面板裏，而不是擠在一個聊天回覆框裏：
- 每題獨立一塊：題號、標題、問題、說明；
- 每題 2–4 個具體選項，第一項爲推薦值且默認選中；另有獨立輸入框，手寫會覆蓋選項；
- 頂部進度可摺疊；底部有「全部按推薦」「提交答案」；可「跳過」讓模型用默認值繼續，或用「×」關掉面板交還對話；
- 面板狀態存在宿主，刷新或切換會話再回來，題目與答案仍在；模型在等待時不會自行往下執行。
快問 / 完整：mode=quick 只展示第一題；mode=full 爲完整批次（默認）。部署級默認由配置項 interviewMode 決定，工具參數裏的 mode 優先。
focus：模型可把 focus: '格式' 等傳給 clarify_ask，面板顯示「只問：…」標籤，供人閱讀，不改變過濾邏輯。
需求卡確認與任務邊界¶
問完後模型通過 clarify_brief 寫出需求卡，同一塊面板請你選擇：確認開工 / 還要再問 / 我自己改，並可附自由修改說明。批准後卡片寫入 state.json，並在後續每輪提示詞中作爲錨；輸入框右側膠囊在「已確認」狀態下可點「卡」查看。
批准後的卡還會落盤爲 Markdown（默認路徑 <會話 cwd>/.dsh/clarify/card-YYYYMMDD-HHMM-<標題>.md），便於進版本庫、換會話或換 agent 時查閱。可通過 cardFile: false 關閉寫文件，或用 cardFileDir 指定目錄；寫文件失敗只記 warning，不影響批准本身。
新任務邊界：換對象、換交付物或說「下一個」視爲新任務，須重新澄清；對上一結果的局部修改（如「第 2 節改成…」）可直接做。面板底部「開始新任務」可清卡。
驗收清單¶
clarify_brief 可附帶 checklist（最多 6 條，建議 3–5 條），追加在卡片末尾，例如：
**驗收清單**
- [ ] PDF 能打開
- [ ] 頁數正確
清單在確認面板中先展示；批准後進入狀態、提示詞錨、cards.json 與落盤 .md。已批准會話的錨會要求模型開工後按清單逐條自查並在回覆中說明是否做到。
記憶複查¶
同目錄 cards.json 保留最近 8 張已批准卡。新一輪未批准會話的提示詞中，除訪談腳本外還會帶上最近 3 張卡的標題、批准日期與前 300 字——僅作參考，舊卡不會被當成當前需求；已定事項不必重複問，推薦值可優先沿用。
信息類型與「已開工」過濾¶
每題可聲明 kind：goal（目標與成功標準，只在動手前問）、input（默認）、constraint、context。插件通過 session/event 觀察寫文件類工具調用（如 write、edit、apply_patch 等，見 lib/work-tracker.js）；一旦會話「已開工」，同會話的 goal 題會被丟棄。只讀工具不算開工；追蹤僅在進程內存中，重啓後重新判斷。
側欄待答提示與其它會話¶
若模型在另一個會話裏提問，當前會話側欄底部會出現待答計數（如 ⏳ 1），便於切過去作答。該指示只讀聚合接口，不參與面板心跳。
指標（本地）¶
每次訪談與確認會向 $DSH_HOME/clarify/metrics.json 追加記錄（最多 500 條）。可用倉庫內腳本查看彙總：
node tools/stats.mjs
node tools/stats.mjs --file D:/my/metrics.json
node tools/stats.mjs --json
GET /api/clarify/health 可返回版本、待答數、卡片檔案條數、訪談記錄條數及各面是否掛載正常。
安裝與啓用¶
官方安裝方式爲倉庫內的 PowerShell 腳本（不是 dsh plugin add github:… 這類拼接命令）。步驟如下：
- 完全退出 DeepSeek Harness；
- 在插件源碼目錄執行：
.\install.ps1 -DryRun # 只看會做什麼
.\install.ps1 # 拷貝到默認目標並 link 進 profile，補全 dsh.profile.bundles
- 重新打開 DSH，輸入框右側應出現「澄清」膠囊。
常用參數：-Profile 指定 profile；-Target 指定拷貝目標（默認示例爲 E:\dsh-env\plugins-local\dsh-clarify）；-Uninstall 從 profile 移除（保留源碼）。升級已有安裝：重跑 .\install.ps1 覆蓋 lib/ 後重啓應用。
安裝後可在本機自檢（端口以實際 DSH 爲準）：
Invoke-RestMethod http://127.0.0.1:<端口>/api/clarify/health
期望 JSON 中含 ok: true、version: "0.4.0" 以及 surfaces 等各面狀態。
在 profile 的 cordis.patch.yml 中，行 id 爲 clarify 的配置示例：
- id: clarify
config:
sectionOrder: 3050
storePath: ''
guidance: true
defaultEnabled: false
interviewTimeoutMs: 1200000
cardFile: true
cardFileDir: ''
interviewMode: full
整行禁用：同一 id 下加 disabled: true。guidance: false 時只保留開關與工具，不注入提示詞；defaultEnabled: true 則新會話默認開啓澄清。
典型用法¶
界面開關與命令¶
輸入框右側膠囊四種狀態：關（「澄清」灰點）、開（「澄清中」）、有待答（「先答 N 個問題」）、已確認（「已確認」+「卡」）。也可在聊天中使用：
/clarify
/clarify on|off|status
模型側流程（提示詞約定）¶
開啓後，模型被引導爲：
- 先複述「要做 X、用來 Y、交付成 Z」，能自行查的先查；
- 用
clarify_ask提問，默認 1 個最關鍵題；僅當多件事彼此獨立且都卡住下一步時一次給 2–3 個，不超過 3； - 澄清階段只讀不寫；用戶說「別問了直接做」則停止追問；
- 最多兩輪訪談，之後須交需求卡，帶着寫明的假設開工。
小任務可用快問模式或只問一個點；需求卡須非空且配清單時條目應可勾選、可驗收，避免空泛口號。
無面板環境¶
TUI / headless 下宿主檢測不到客戶端輪詢時，退回內置問答且一次一題；子 Agent 中確認需求卡會得到 no_client，不會永久卡住。
適用場景與注意¶
適合：交付物形態、範圍、約束、驗收標準經常在第一輪描述裏說不清的任務；希望需求卡落盤、換 agent 仍能續上的項目；需要在開工前結構化對齊、減少返工的團隊或個人工作流。
務必知曉：
- 插件以當前 DSH 進程權限運行；安裝前請自行閱讀源碼與 MIT 許可證，確認信任維護者與代碼行爲。
- 「澄清階段只讀不寫」是提示詞與確認門，不是沙箱：插件不會攔截
write/bash等工具。 - API 經宿主連接圍欄與本機 loopback 規則保護；同機無 cookie 的
curl等仍可能訪問——設計上是方便自檢，局域網/公網無有效瀏覽器會話的請求會被拒絕。 - 面板依賴客戶端輪詢心跳（約 15 秒內無輪詢則視爲無面板）；面板 20 分鐘無人答（
interviewTimeoutMs）會超時，問題改在聊天正文裏繼續。 - 狀態按 session id 存儲；fork 或新 id 不會自動帶上澄清狀態，需重新點開關。
- SkillHub 目錄爲社區生態站點，與 DeepSeek / 幻方無官方從屬關係；星標等元數據以目錄頁爲準（當前線索爲 GitHub 2 stars）。
結尾¶
dsh-clarify 把「返工三次」換成「問三個問題」：訪談面板、需求卡確認與驗收清單落在 DSH 工作流裏，而不是散落在長對話裏。若要進一步瞭解或提交 issue，見 GitHub 倉庫 與 SkillHub 目錄頁。
