dsh-matt-flow
把 Matt Pocock Agent Skills 套件编成一条带前置条件的开发工作流，作为 DSH 的一个 agent 预设。技能从 ~/.agents/skills 读取，缺了会自动安装。
它不复制、不改写任何技能；npx skills update 之后行为自动跟随上游。
它提供什么
一个 bundle，三层内容：
| 组成 | 作用 |
|---|
preset-matt | 新增一个 agent 预设 matt-flow，插件集即官方 standard 预设 + 本包的 matt-flow 插件。在新建会话的预设选择器里出现。 |
系统提示词段落 matt-flow | 告诉模型：哪些技能它能自己 skill 加载（grilling/tdd/code-review/diagnosing-bugs…），哪些只能由你 /命令 触发（/to-spec、/to-tickets…），以及 拷问 → 规范 → 任务 → 实现 → 评审 → 收尾 的顺序、每阶段该做什么。 |
工具 flow_stage | 记录并推进某个 feature 的阶段，落盘到 .scratch/<feature>/flow.json。前进必须逐级、且要满足前置条件；回退（返工）允许。 |
工具 flow_ask + 决策卡（client.js） | 拷问阶段把决策做成对话里的卡片：每题一组选项加一个补充输入框，一次最多三题。点「提交选择」后，答案作为你的下一条消息发出，模型接着往下走。卡片由本包自己的浏览器模块渲染，不依赖 dsh-genui。 |
阶段胶囊（client.js） | 输入框工具行左侧的小胶囊：当前阶段、进度、下一阶段的前置条件。点开浮层看完整流程。只在 Matt 预设的会话里出现。 |
一个包，两行挂载
浏览器侧代码只能从顶层 Loader 条目聚合，而宿主行为必须留在预设子树里（否则会污染所有会话）。同一个包因此挂两次：
- 顶层
matt-flow-ui 行：只为让浏览器扫描到 dsh.client，它的 config 是 uiOnly: true，apply() 立刻返回，不注册任何东西
- 预设里
matt-flow 行：真正的工作（提示词、三个工具、投影）
这就是插件页只显示一个条目的原因。
模式说明
它是什么
一条带前置条件的开发工作流。每个 feature 走同一条路：拷问 → 规范 → 任务 → 实现 → 评审 → 收尾。每一步做完，才能进下一步；跳级会被 flow_stage 拒绝。
它不是新的 AI 能力，而是把 Matt Pocock 那套技能串成有顺序、有产出的流程——技能本身仍然从 ~/.agents/skills 读取，插件只负责编排。
什么时候用它
- 有一个要落地的需求，且希望能留下可复查的决策与规范
- 做多人协作，需要别人接手时能看懂「为什么这么做」
- 想强制自己先想清楚再写代码（拷问阶段不允许写代码）
不适合：一次性小脚本、纯问答、紧急线上排障（那种直接修，事后补记录）。
怎么用
- 新建会话，预设选「Matt 工程流」
- 直接说需求。它会先拷问：把决策做成卡片（选项 + 补充输入框），一次最多三题
- 谈定后写规范、拆任务单、按单实现、评审、收尾
- 全程可以用输入框左侧的胶囊看进度；点开浮层能看到每一步要做什么
三条命令按需使用：
| 命令 | 用途 |
|---|
/grill-with-docs | 用户手动触发拷问（模型在预设里会自己加载同样两个技能） |
/to-spec | 只想要规范、不想走完整流程时 |
/code-review | 只想评审某个分支或 PR |
它会留下什么
.scratch/<feature>/decisions.md — 这次变更的决策.scratch/<feature>/spec.md — 规范.scratch/<feature>/issues/*.md — 任务单，含阻塞关系CONTEXT.md / docs/adr/ — 术语与难以撤销的决定，按需创建（没有就不写）
第一次用之前
如果仓库还没定过 issue 放在哪，第一次进规范阶段前会要求写 docs/agents/issue-tracker.md。默认本地 markdown（.scratch/）即可；想要完整布局（triage 标签、域文档、## Agent skills 块）就自己跑一次 /setup-matt-pocock-skills。
阶段与前置条件
拷问 → 规范 → 任务 → 实现 → 评审 → 收尾
进入下一阶段前要满足什么：
| 进入 | 前置条件 |
|---|
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 里看到它。
为什么 spec 要求先记下 issue tracker
Matt 的套件有一条前置：/setup-matt-pocock-skills，用来定下 issue 放哪（GitHub / GitLab / 本地 markdown）、triage 标签词表、以及 CONTEXT.md 与 ADR 的目录布局，产出写进 docs/agents/*.md 并在 CLAUDE.md/AGENTS.md 里留一个 ## Agent skills 块。
那一整套是用户命令，模型跑不了；但它的结论是下游技能的前提——/to-spec、/to-tickets、/triage 的正文里都写着"若未配置，让用户先跑 /setup-matt-pocock-skills"。
所以这里只强制最小的一步：把 issue tracker 的结论落进 docs/agents/issue-tracker.md 才允许写 spec。默认值是本地 markdown（.scratch/<feature>/），因为流程本来就写在那里；想要完整的标签词表与域文档布局，再让用户跑一次 /setup-matt-pocock-skills。
安装
从 GitHub 装：
dsh plugin add git+https://github.com/yuwang/dsh-matt-flow
或在 DSH 的 Plugins 页面填这个地址。装完重启一次，再新建会话，在预设置换器里选「Matt 工程流 / Matt Flow」。
也可以在本地开发时用目录安装：
dsh plugin --profile desktop add /path/to/dsh-matt-flow
已存在的会话不受影响：预设只在新建会话时装入。
装好之后
第一次进规范阶段前，仓库里需要有一份 docs/agents/issue-tracker.md 说明 issue 放在哪。没配过就跑一次 /setup-matt-pocock-skills，或者直接让模型按本地 markdown 写一份。
技能套件（37 个）会在预设首次激活时自动安装到 ~/.agents/skills，前提是机器上有 node 和 npx。装了什么、成没成功，让模型调 flow_skills 就能看到。
在哪里选
- 新建会话的空白页：底部输入区的工具行里，工作区选择器旁边有预设芯片（默认显示「标准 / Standard」），点开就是预设菜单，选「Matt 工程流」。
- 设置 → Agent 预设（
settings.agentPreset）：按「内置 / 自定义」分组列出卡片，「Matt 工程流」在自定义组；卡片可「查看配置」（只读 YAML），也可设为新建会话的默认。
装好后若菜单里还没出现，刷新页面一次——预设名单在连接重置时刷新；当前已存在的会话不会切过去，必须新建。
用起来是什么样
- 新建会话，选
Matt Flow，把你的想法说出来。
- 模型会拉
grilling 跟你把设计问清楚，而不是直接改代码。
- 它调
flow_stage({action:"advance", to:"spec"}) 前进时，前置条件要求它先把决策写进 evidence。
- 规范写进
.scratch/<feature>/spec.md，任务单写进 .scratch/<feature>/issues/，实现阶段逐张任务单走 tdd，最后 code-review。
- 随时
flow_stage({action:"status", feature:"..."}) 看进度和下一阶段的前置条件。
本地开发
改完代码后：
index.js 改动：必须重启 DSH。预设子树持有的模块在 Node 的 ESM 缓存里，install_bundle 会返回 restart-required（原因 unmanaged-plugin），热重载换不掉已加载的代码。重启后看系统临时目录的 dsh-matt-flow-load.log 确认版本号（macOS/Linux 在 /tmp，Windows 在 %TEMP%）。client.js 改动：先 node --check client.js，再刷新页面。浏览器侧模块由 dsh.client 清单扫描后加载，不刷新拿不到新模块；注册成功后可在 tool.call.toolview 的 occupant 里看到 flow_ask。- 改完先跑一遍：
npm test（约 0.2 秒，43 条断言，不依赖网络）。
外部依赖与权限
运行时依赖
没有任何 npm 依赖。 插件只使用 Node 内置模块（fs、path、os、child_process），浏览器侧只用宿主提供的 React。
它会启动子进程
flow_skills 工具和预设激活时的自动准备会执行：
npx -y skills@latest add mattpocock/skills -g -s '*' -y
这会把 mattpocock/skills 装进 ~/.agents/skills，影响这台机器上所有读该目录的 agent（Claude Code 等）。
触发条件很窄：
- 只在 7 个必需技能缺失时才执行
- 失败后 24 小时内不再自动重试
- 可用
flow_skills 查看状态、或手动重试
- 不想让它执行，就别用这个预设；插件不会在预设之外运行
前提：机器上要有 node 和 npx，且能访问 npm registry 与 GitHub。缺失时不会崩溃，只会把状态记为 failed。
它写哪些文件
| 路径 | 内容 |
|---|
.scratch/<feature>/flow.json | 阶段状态 |
.scratch/<feature>/decisions.md、spec.md、issues/*.md | 流程产物（由模型写，不是你手动维护） |
docs/agents/issue-tracker.md | 首次进规范阶段前要求存在的 tracker 说明 |
~/.dsh/matt-flow-bootstrap.json | 技能安装状态 |
系统临时目录下的 dsh-matt-flow-*.log | 启动打点与安装日志 |
权限范围
插件不申请额外权限，不读取凭据，不发起除上述 npx 之外的网络请求。
已知边界
- 不接管模型行为：提示词是强约束、不是硬约束。真正的强制只有
flow_stage 的前置条件——模型完全可以绕过它直接改代码。要更强的约束，得再加 ctx.tools.guard()。
- 预设即快照：插件集复制自官方
standard 预设。DSH 升级后 standard 若增删插件，这个预设不会自动跟随；升级后建议对照 @deepseek-ai/dsh-web-app/presets/standard.patch.yml 同步一次。
- UI 有限：只有一个状态胶囊（输入框工具行）+ 决策卡，没有任务看板。
- 工具定义用普通 JSON Schema：没有用
defineTool()，因为插件从工作区链接安装时解析不到 @deepseek-ai/*。发布为 npm 包后可以改回。
- 未在 Windows 上实测：已按平台适配日志目录、
npx.cmd、cmd.exe 兜底和 --copy，但没有真机验证。
许可证
MIT，见 LICENSE。
排障
apply 会往系统临时目录的 dsh-matt-flow-load.log 与 dsh-matt-flow-apply.log 各写一行启动打点（macOS/Linux 在 /tmp，Windows 在 %TEMP%）：前者证明模块被导入，后者证明 apply 执行、各注册项成功。出现任何"预设加载失败"时先看这两个文件——没有 load 行是导入问题，有 load 无 apply 是注入问题。确认稳定后可以删掉这两处打点。
卸载
dsh plugin --profile desktop remove dsh-matt-flow
.scratch/ 下的数据是你的，不会被清理。
