前言¶
用 DSH 做功能開發時一個常見的問題是：模型具備寫代碼、評審、拆任務的能力，但這些動作之間沒有順序約束。你可以在需求還沒談清楚時就看到它開始改文件，也可以在規範沒落地時就看到它拆任務；過程產物散落在對話裏，事後很難複查「當時的決策是什麼、爲什麼這樣做」。
dsh-matt-flow 就是針對這個問題的插件。它由 yuwang 維護，屬於「工作流」類別，做法不是發明一套新的 AI 能力，而是把 Matt Pocock 的 Agent Skills 套件編排成一條帶前置條件的開發流程，並把這個流程固化成一個 DSH agent 預設。下面我們介紹它的組成、安裝方式和使用時需要注意的地方。
這是什麼¶
一句話定位：給 DSH 增加一個名爲 matt-flow 的 agent 預設，把「拷問 → 規範 → 任務 → 實現 → 評審 → 收尾」六個階段串起來，階段推進由 flow_stage 工具校驗前置條件。
它解決什麼問題：
- 強制先想清楚再寫代碼。拷問階段不允許寫代碼，決策落進
.scratch/<feature>/decisions.md。 - 強制留下可複查的產物。規範、任務單、評審結論各自落到固定路徑。
- 用一個 preset 把多個技能按順序串起來，而不是每次手動想起該用哪個技能。
需要說明的是，這個插件只負責編排。它不復制、不改寫任何技能；技能本身從 ~/.agents/skills 讀取，上游 mattpocock/skills 更新後（npx skills update）行爲自動跟隨。
配置基本信息：版本 0.7.3，許可證 MIT，GitHub 星標 1，維護者 yuwang。它不含任何 npm 依賴，只使用 Node 內置模塊（fs、path、os、child_process），瀏覽器側只用宿主提供的 React。
核心功能¶
下面介紹這個包的三層內容。它以 bundle 形式安裝，三層同時生效：
| 組成 | 作用 |
|---|---|
preset-matt |
新增 agent 預設 matt-flow，插件集是官方 standard 預設加上本包的 matt-flow 插件。預設會在新建會話的預設選擇器裏出現。 |
| 系統提示詞段落 | 告訴模型哪些技能能自己用 skill 加載（grilling、tdd、code-review、diagnosing-bugs 等），哪些只能由用戶 /命令 觸發（/to-spec、/to-tickets 等），以及六個階段的順序和每階段該做什麼。 |
flow_stage、flow_ask、flow_skills 三個工具 |
階段狀態落盤與推進、決策卡片、技能安裝狀態查詢。 |
客戶端代碼 client.js |
渲染決策卡片和輸入框工具行的階段膠囊，不依賴 dsh-genui。 |
三個工具的職責：
1、flow_stage：記錄並推進某個 feature 的階段，狀態寫入 .scratch/<feature>/flow.json。前進必須逐級，且要滿足前置條件；回退（返工）是允許的。
2、flow_ask：在拷問階段把決策做成對話裏的卡片，每題一組選項加一個補充輸入框，一次最多三題。點「提交選擇」後，答案作爲下一條消息發出，模型接着往下走。
3、flow_skills：查看技能安裝狀態，或在安裝失敗後手動重試。
爲什麼插件頁只顯示一個條目：瀏覽器側代碼只能從頂層 Loader 條目聚合，而宿主行爲必須留在預設子樹裏（否則會污染所有會話）。同一個包因此掛兩次：頂層 matt-flow-ui 行 config 爲 uiOnly: true，apply() 立刻返回；預設裏的 matt-flow 行負責真正的註冊。這是插件頁只顯示一個入口的原因。
安裝與啓用¶
從 GitHub 安裝，命令來自插件 README：
dsh plugin add git+https://github.com/yuwang/dsh-matt-flow
也可以在 DSH 的 Plugins 頁面填上面這個地址。裝完需要重啓一次 DSH，然後新建會話，在預設選擇器裏選「Matt 工程流 / Matt Flow」。已存在的會話不受影響，預設只在新建會話時裝入。
本地開發時用目錄安裝：
dsh plugin --profile desktop add /path/to/dsh-matt-flow
卸載：
dsh plugin --profile desktop remove dsh-matt-flow
.scratch/ 下的流程數據不會被卸載清理。
裝好之後還有一個前置條件。第一次進規範階段前，倉庫裏需要有一份 docs/agents/issue-tracker.md，說明 issue 放在哪（GitHub、GitLab 或本地 markdown）、triage 標籤詞表等。如果之前沒跑過 Matt 套件的 /setup-matt-pocock-skills，可以讓模型按本地 markdown 直接寫一份，默認路徑是 .scratch/<feature>/。
技能套件（37 個）會在預設首次激活時自動安裝到 ~/.agents/skills，前提是機器上有 node 和 npx，並且能訪問 npm registry 與 GitHub。安裝失敗不會崩潰，狀態會記爲 failed，之後 24 小時內不再自動重試。安裝狀態可以用 flow_skills 查看。
預設在哪裏選：
1、新建會話空白頁，底部輸入區工具行裏工作區選擇器旁邊的預設芯片（默認顯示「標準 / Standard」），點開就是預設菜單，選「Matt 工程流」。
2、設置 → Agent 預設（settings.agentPreset），按「內置 / 自定義」分組列出卡片，「Matt 工程流」在自定義組，可以「查看配置」（只讀 YAML），也可以設爲新建會話的默認。
如果菜單裏還沒出現，刷新頁面一次。預設名單在連接重置時刷新，當前已存在的會話不會自動切換。
階段與前置條件¶
六個階段的順序是固定的：拷問(grill) → 規範(spec) → 任務(tickets) → 實現(implement) → 評審(review) → 收尾(done)。
進入下一階段前要滿足的條件：
| 進入 | 前置條件 |
|---|---|
grill |
無，直接開始拷問 |
spec |
evidence 寫明拷問收口了什麼決策；且 docs/agents/issue-tracker.md 存在 |
tickets |
.scratch/<feature>/spec.md 存在且不少於 200 字符 |
implement |
.scratch/<feature>/issues/ 下至少有 1 個 .md |
review |
evidence 寫明跑過的 typecheck 與測試 |
done |
說明評審結論與提交 |
前置條件只校驗能校驗的部分：文件是否存在、內容是否夠量、evidence 是否非空。插件不假裝驗證「測試真跑過了」，那句證據由模型自己寫，你可以在 flow.json 的 history 裏看到它。
三條命令按需使用：
| 命令 | 用途 |
|---|---|
/grill-with-docs |
用戶手動觸發拷問 |
/to-spec |
只想要規範、不想走完整流程時 |
/code-review |
只想評審某個分支或 PR |
典型用法¶
1、新建會話，預設選「Matt 工程流」，把你的想法說出來。
2、模型會拉 grilling 技能跟你把設計問清楚，而不是直接改代碼。決策做成卡片（選項加補充輸入框），一次最多三題。
3、談定後寫規範、拆任務單、按單實現、評審、收尾。
4、全程用輸入框左側的膠囊看當前階段、進度和下一階段的前置條件，點開浮層能看到完整流程和每一步要做什麼。
它會留下這些產物：
1、.scratch/<feature>/decisions.md — 這次變更的決策。
2、.scratch/<feature>/spec.md — 規範。
3、.scratch/<feature>/issues/*.md — 任務單，含阻塞關係。
4、CONTEXT.md / docs/adr/ — 術語與難以撤銷的決定，按需創建，沒有就不寫。
模型調用 flow_stage({action:"advance", to:"spec"}) 前進時，前置條件要求它先把決策寫進 evidence；隨時用 flow_stage({action:"status", feature:"..."}) 看進度和下一階段的前置條件。
適用範圍與注意¶
適合的場景：
1、有一個要落地的需求，且希望留下可複查的決策與規範。
2、多人協作，需要別人接手時能看懂「爲什麼這麼做」。
3、想強制自己先想清楚再寫代碼。
不適合的場景：一次性小腳本、純問答、緊急線上排障。這些應該直接做，事後補記錄。
需要注意的幾點：
1、插件以當前 dsh 進程的權限運行。它會啓動子進程 npx -y skills@latest add mattpocock/skills -g -s '*' -y，把技能裝進 ~/.agents/skills，這會影響本機上所有讀該目錄的 agent，不只是 DSH。觸發條件很窄：只在 7 個必需技能缺失時執行，失敗後 24 小時內不自動重試；不想讓它執行就別用這個預設。安裝前建議先檢查插件源碼與許可證（MIT）。
2、插件不申請額外權限，不讀取憑據，不發起上述 npx 之外的網絡請求。它會寫的文件限於 .scratch/<feature>/ 下的流程產物、docs/agents/issue-tracker.md、~/.dsh/matt-flow-bootstrap.json 和系統臨時目錄下的日誌。
3、它不接管模型行爲。提示詞是強約束而非硬約束，真正的強制只有 flow_stage 的前置條件；模型理論上完全可以繞過它直接改代碼。要更強的約束需要再加 ctx.tools.guard()。
4、預設是快照。插件集複製自官方 standard 預設，DSH 升級後 standard 若增刪插件，這個預設不會自動跟隨，建議升級後對照 @deepseek-ai/dsh-web-app/presets/standard.patch.yml 同步一次。
5、UI 有限，只有狀態膠囊和決策卡，沒有任務看板。
6、未在 Windows 上實測，代碼裏已做日誌目錄、npx.cmd、cmd.exe 兜底和 --copy 適配，但沒有真機驗證。
7、排障時先看系統臨時目錄的 dsh-matt-flow-load.log 和 dsh-matt-flow-apply.log。沒有 load 行說明模塊沒被導入，有 load 無 apply 說明是注入問題。macOS/Linux 下日誌在 /tmp，Windows 下在 %TEMP%。
結尾¶
dsh-matt-flow 的價值在於把「先拷問、再規範、再實現」這條紀律變成預設裏的默認路徑，同時把階段狀態、決策和產物落到可複查的本地文件。如果你已經在用 Matt Pocock 的技能套件，它相當於給這些技能補上一層編排和門禁。
目錄頁：https://www.skillhub.cn/plugins/yuwang/dsh-matt-flow
GitHub：https://github.com/yuwang/dsh-matt-flow
（社區目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係。）
