dsh-BMAD-Method
把 BMAD-Method 整套装进 dsh 里。装完插件就能用，不用自己跑 npx bmad-method install。
两份 README 并存：这份是简体中文，英文版见 README.en.md。
这是什么
BMAD-Method 是一套「先想清楚，再写代码」的开发方法。它把工作拆给不同角色：分析师做调研、产品经理写 PRD、架构师定方案、开发写代码、测试把关，一路产出从需求到实现的文档。
原版要你自己装、自己选模块、自己管一堆散落的文件。这个插件把整套东西打包带进来了：
- 7 个模块全在插件包里，你机器上不用另外装 BMAD
- 90 个角色和流程，从「帮我头脑风暴」到「审一遍这段代码」
- 第一次打开就铺好，46 毫秒，不跑安装器、不联网
- 不用的模块关掉，它的 skill 就不再出现，文件一个都不删
- 更新插件就是更新 BMAD，不用再单独管 BMAD 的版本
装完之后能干什么
直接用中文说你要做什么，对得上就用对应的 skill：
| 你说 | 它做什么 |
|---|
| 「帮我写个 PRD」 | 走 bmad-prd，产出结构化需求文档 |
| 「让 Winston 看看这个架构」 | 切到架构师角色 bmad-agent-architect |
| 「跑一遍代码审查」 | 走 bmad-code-review，多个视角并行审 |
| 「把需求拆成故事」 | 走 bmad-create-epics-and-stories |
| 「这功能怎么做测试」 | 走 bmad-testarch-test-design |
| 「我有个想法，帮我掂量掂量」 | 走 bmad-forge-idea |
也可以敲 /bmad- 看补全，90 个都在。
安装
dsh plugin add github:ph1996-cn/dsh-BMAD-Method
桌面版更简单：设置 → 插件 → 从 GitHub 安装，填 ph1996-cn/dsh-BMAD-Method；或者在插件市场里搜 BMAD。
包名和显示名不是同一个东西：npm 包名是 dsh-bmad-method（npm 只收小写），仓库和界面上显示的是 dsh-BMAD-Method。从 0.1.x 升上来的要先把旧包卸掉——dsh-BMAD-Method 和 dsh-bmad-method 在 dsh 眼里是两个插件，两个都装着会同时加载两次。
装完重启一次 dsh，插件才会被加载。
// 想钉住某个版本，防止以后意外更新
"dsh-bmad-method": "github:ph1996-cn/dsh-BMAD-Method#v0.2.0"
第一次打开
重启后打开 设置 → 插件 → dsh-BMAD-Method，会看到三块。
一、设置
| 项 | 说明 |
|---|
| 用户名 | 写进 BMAD 配置的 user_name，它跟你对话时用这个名字 |
| 语言 | 沟通和文档输出用哪种语言，默认「简体中文」 |
| 工作区输出目录 | 产出的文件放哪，默认 _bmad-output（相对你的工作区） |
改完点保存，立即生效。
二、模块开关
七个模块一行一个，右边一个开关。详见下面「模块开关」那节。
三、包含的组件
这里只有一行，就是插件自己。这是 dsh 插件页的固定结构 —— 模块开关在上面那块，不在这里。
第一次打开卡片时，插件会自动把 BMAD 运行时铺到 ~/.dsh/bmad-method（46 毫秒，不联网）。你不用点任何按钮，也不用跑任何命令。
模块开关
开关只决定这个模块参不参与，不动任何文件。
- 关掉
bmm → 它的 21 个 skill 立刻从 skill 清单消失，模型再也看不到
- 重新打开 → 又回来
- 模块文件一个都不删，随时能开回来
状态写在 dsh 的 profile 配置（cordis.patch.yml）里，用的就是 dsh 原生插件开关那个 disabled: true 字段。所以重启 dsh 后状态还在，也不会有第二份状态表。
core 是地基模块，没有开关 —— 关掉它，别的模块的脚本就找不到公共配置了。
停用模块后不用重启 dsh，skill 清单每次构建都现读补丁。但如果你改的是插件代码本身，还是要重启。
90 个 skill 都是什么
全部随插件包提供，不落你的任何目录（~/.dsh/skills 里应该是 0 个 bmad/gds skill）。
| 模块 | skill 数 | 都是些什么 |
|---|
bmm | 21 | 主力：PRD、架构、故事、代码审查、回顾、头脑风暴 |
gds | 33 | 游戏开发：GDD、游戏架构、试玩计划、游戏测试 |
cis | 10 | 创意：设计思维、创新策略、故事叙述、问题解决 |
tea | 10 | 测试架构：测试设计、ATDD、CI 流水线、可追溯矩阵 |
core | 8 | 公共：帮助、头脑风暴、定制、深度调研、评审 |
bmb | 5 | 造模块用：造 agent、造工作流、造模块 |
bmad-loop | 3 | 无人值守开发循环 |
更新
更新插件 = 更新 BMAD，一条命令：
dsh plugin --profile desktop update dsh-bmad-method
--profile 换成你实际在用的那个（桌面版是 desktop）。更新完重启 dsh。
不用卸载重装 —— dsh 的「安装」对已装插件会直接拒绝（already-installed），只能走包管理器更新。
卸载
在插件页点「卸载」即可。dsh 会删掉 npm 包和 profile 里的声明，但不会动这一处：
| 位置 | 是什么 | 卸载后 |
|---|
~/.dsh/bmad-method/ | BMAD 运行时 + 你的 custom/ 定制 | 留着（约 34 KB） |
这是故意不删的：里面有你自己的 custom/ 覆盖文件，删插件顺手删掉它，重装就全丢了。而且 dsh 的卸载流程不执行插件代码（只 pnpm remove + 改 profile），插件没有机会自己去清。
想彻底干净，手动删：
Remove-Item -Recurse -Force "$env:USERPROFILE\.dsh\bmad-method"
卸载前想留定制，先把它拷出来：
Copy-Item -Recurse "$env:USERPROFILE\.dsh\bmad-method\_bmad\custom" "$env:USERPROFILE\Desktop\bmad-custom-backup"
那 34 KB 里只有会被写入的配置（config.toml、7 个模块的 config.yaml、custom/、render/）。scripts/ 与 _config/ 这两大块（合计 309 KB）是指向插件包内的目录联接，不占你的空间，插件升级时会自动跟到新版；删掉 ~/.dsh/bmad-method 时也只删链接，不会碰到插件包里的文件。
极少数情况下建不了链接（插件装在别的盘、非 NTFS、组策略禁用重解析点），会自动退回复制那 309 KB —— 功能一样，只是多占点空间。
兼容的 dsh 版本
| 项 | 值 |
|---|
| dsh | >=0.2.0-rc.1 <0.2.1 || >=0.2.1-rc.1 <0.3.0-0（整个 0.2.x，含预发布） |
| 实测跑通 | 0.2.1-rc.3、0.2.1-rc.5 |
| Node | ^22.19.0 || >=24 |
声明在 package.json 的 engines 里：
"engines": { "node": "^22.19.0 || >=24", "dsh": ">=0.2.0-rc.1 <0.2.1 || >=0.2.1-rc.1 <0.3.0-0" }
为什么写得这么绕：node-semver 有个坑 —— 预发布版本（0.2.1-rc.5）只有范围里存在一个元组完全相同且带预发布标签的比较符时才被放行。看起来更简洁的 >=0.2.0-rc.1 <0.3.0 里只有 0.2.0 和 0.3.0 两个元组，匹配不到 0.2.1-rc.5。所以必须显式列出 0.2.1 这一段。
插件只依赖 dsh 的公开契约，不碰私有内部模块，也不 pin 任何 @deepseek-ai/dsh-* 依赖：
| 用到的能力 | 怎么用 |
|---|
| 注册工具 | ctx.tools.register() |
| 提供 skill | ctx.skills.registerProvider() |
| 设置表单 | export const Config（Schemastery schema） |
| 浏览器半端 | dsh.client + ctx.slots.inject() |
| 卡片接口 | ctx.webServer.register({ kind: 'prefix' }) |
这五处都在 0.2.1-rc.5 的发布包里逐条核对过，签名没变。所以 0.2.x 内的小版本升级不需要跟着改版本号。
三个工具（模型也能主动调）
| 工具 | 参数 | 作用 |
|---|
bmad_modules_list | projectRoot? registryPath? | 列出已装 / 可装模块、版本、开关状态 |
bmad_module_toggle | module enabled | 开关一个模块（只写状态，不装卸文件） |
bmad_update | userName? modules? channel? language? | 跑官方安装器更新或补装模块 |
平时用不上 bmad_update —— 运行时随插件走。只有两种情况需要它：上游发了新版本，或者要补装被降级跳过的外部模块。
出问题了
| 现象 | 原因 | 怎么办 |
|---|
| 插件页看不到 BMAD 设置卡片 | 插件没加载 | 确认 设置 → 插件 里它是启用状态，然后重启 dsh |
| 模块全显示「未安装」 | 首次打开还没铺运行时 | 刷新一下卡片（打开即自举），或跑一次 bmad_modules_list |
| 模块开关点了没反应 | 找不到 profile 补丁 | 卡片底部会写清原因；确认插件挂在某个 profile 上 |
| 产出文件跑到系统临时目录 | 旧版本 bug | 更新到 0.1.1 及以上 |
skill 里报 TOML file not found | 旧版本占位符没展开 | 更新到 0.1.1 及以上 |
| 更新完还是旧代码 | dsh plugin add 不更新已装包 | 用 dsh plugin --profile desktop update dsh-bmad-method |
| 外部模块装不上 | 安装器要 git clone 各模块仓库 | 确认能访问 GitHub；装不上会自动降级为内置模块，BMAD 仍可用 |
还有个常见误会：BMAD 装在 ~/.dsh/bmad-method（全局），不会在你的项目里建 _bmad/。你的项目里只会多出 _bmad-output/ 这个产物目录。
给维护者
目录
index.js 插件入口：三个工具 + 卡片接口
client.js 浏览器半端：设置卡片 + 模块开关
cordis.patch.yml 包内补丁，只挂一行控制面
bmad-home/_bmad/ BMAD 运行时模板（345 KB / 31 文件）：配置拷出去，scripts/_config 建链接
skills/ 90 个 skill + manifest.json（skill → 模块归属表）
lib/bmad.js BMAD 发现、安装器调用、运行时铺装
lib/patch.js profile 补丁的按行读写（不吃掉用户注释）
lib/skills.js SkillProvider 实现
lib/template.js 模板铺装（junction + 配置改写）、跨模块同名键消歧
lib/registry/ bmad-modules.yaml 内置快照（依赖没落地时的离线兜底）
换 BMAD 版本
node scripts/sync-bmad.mjs # 检查三方版本：0=已最新，10=有更新
node scripts/sync-bmad.mjs --apply # 有更新则重建 bmad-home/ 与 skills/
node scripts/sync-bmad.mjs --publish # 重建并自动发版（npm test 通过才发）
脚本做四件事：升 bmad-method 依赖 → 跑官方安装器铺临时目录 → 搬回旧快照的项目名 / 语言 / 用户名并覆盖两个快照目录 → 从 skill-manifest.csv 重生成 skills/manifest.json，最后 npm test 当门禁。
模板版本和 node_modules/bmad-method 对不上时，插件会自动退回跑安装器，不会把旧结构铺到新版本上。
补丁写入的安全性
cordis.patch.yml 一律按行定点编辑，不做 YAML 往返序列化 —— 你自己写的注释和条目原样保留（有测试守着）- 写盘走「临时文件 + rename」，写完立刻回读校验；校验失败把原内容写回并返回
write-failed
- 工具不缓存内存态，
enabled 每次从补丁文件现读
测试
npm test # 17 个用例，1.5 秒
用假 ctx 真跑 apply()，覆盖：工具注册、模块发现、开关读写、重复停用幂等、用户注释不被破坏、core 不可停用、写盘失败回滚、命令组装、全局安装不落工作区、全新环境自举、模板 46ms 铺好 7 个模块、模块停用后 skill 消失、卡片接口（含跨站 403）、Config 三个字段全部 .volatile()、engines.dsh 覆盖预发布段。
.volatile() 是必须的：dsh 的 volatileForm() 只把标了 .volatile() 的字段放进设置页，一个都没有的话整个条目会被丢掉，界面上就不会出现这张卡片。
发版
npm version 0.1.3 --no-git-tag-version
git commit -am "chore: 发布 v0.1.3"
git tag v0.1.3 # ← 不要加 -a
git push origin main v0.1.3
tag 必须是 lightweight（别用 git tag -a）。annotated tag 在 refs/tags/ 里的 SHA 是 tag 对象自己的哈希，不等于它指向的 commit；插件市场按 SHA 匹配 commit，annotated tag 永远配不上，会把版本显示成 v<40位commit哈希> 而不是 v0.1.3。
v0.1.0 ~ v0.1.2 历史上是 annotated tag（所以市场里显示成 v64339e3dad... 那样），不追改；从下一个版本起用 lightweight。
License
本仓库自身的代码以 MIT 发布，见 LICENSE。
随包分发的 BMAD-Method 内容（bmad-home/、skills/）版权归 BMad Code, LLC，同样按 MIT 分发——版权行、上游仓库清单、以及我们改了什么，全部列在 THIRD-PARTY-NOTICES.md。
本插件是非官方社区项目，与 BMad Code, LLC 无隶属或背书关系。
