前言¶
用 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 / 幻方没有官方从属关系。）
