工程流程套件 SHADOW-LI0327/dsh-process-kit

dsh-process-kit

多角色 + 多智能体并行开发插件，用工程化手段提升产出质量

English: see README.en.md. 本插件支持中文 / 英文两种流程语言（process_init({ lang })），见下节「双语支持」。

简介

给 DSH 加一套文件驱动的工程化开发流程。需求包的状态、门禁签署、流程与 bug 记录都写在目标仓库的 docs/process/* 里；插件只负责读取、渲染、安全追加和脚手架落地，不另外保存状态。

同时内置 9 个角色子代理，彼此有硬边界：写实现的不写测试，写测试的不做验收；产品与架构的借鉴调研在 Gate0 前按需并行，候选只进核对件、不直接进 AC。

特性

- 文件状态机：进度存在 docs/process/ 的 frontmatter 中。每轮唤醒调用 process_status 即可恢复上下文，不依赖聊天记录。
- Gate 门禁：只在 Gate0/1/2/4（需求核对，设计，开发，验收环节）停下确认，每次输出两段式摘要（✅ 已完成 / ❓ 待裁定）。
- 防篡改 journal：链式指纹（任意一行被改 / 删行 / 换行都能发现），读取侧重算并如实报红；状态位与批准来源都可事后核验。
- 角色分离：角色技能随插件注册，项目内 .dsh/skills/ 的同名技能可覆盖。
- 需求借鉴调研（按需）：用户说不清目的时，Gate0 前并行派 product-manager + architect 查 GitHub / 公开文档，把隐性需求 / 技术约束变成核对件的候选 Q；并行必须汇合，候选不直接进 AC，fast 路径不做，不默认对所有 full 包做。
- 零依赖：不导入插件外库，无构建步骤。
- 只增不改：process_init 默认只创建、不覆盖；已有仓库用 process_init(upgrade: true) 升级 —— 框架自有文件覆盖前先备份，PROJECT.md 与令牌类项目可定制文件永不覆盖、只报告差异。

双语支持（中文 / English）

同一套流程、两种语言。语言只影响文字，不影响落点与判据：

- 选语言：process_init({ lang: "en" }) 落英文骨架、zh 落中文；auto（默认）依次看 .process-kit.json 的 lang → 仓库 AGENTS.md / README.md 的语言 → 回退 zh。环境变量 PROCESS_KIT_LANG=zh|en 可一次性覆盖。换语言 = process_init({ upgrade: true, lang: "en" })（框架自有文件按新语言覆盖并先备份，PROJECT.md / 令牌类文件不覆盖、只报告差异）。
- 门禁与工具跟着仓库走：门禁脚本的运行期消息、process_status / gate_summary 的报告、9 个角色技能正文都按仓库语言输出/取用（英文仓库拿英文，中文仓库行为不变）。
- 机器认标记，人读文字：模板在关键小节上方放 HTML 注释标记（ / ），门禁优先按标记定位，缺失才回退中英标题别名；§4 / §5 的配置键中英都认（如 台账目录 / Rules dir）；核对件中英两种文件名都认，权威判据是 frontmatter kind: requirement-check。
- 完整契约：docs/I18N.md（解析优先级、标记清单、26 个配置键对照表、维护纪律）；test/i18n.test.mjs 会核对两套骨架一致、零残留，并在英文仓库里跑到绿。

安装

| 方式 | target | 说明 |
| npm（推荐） | dsh-process-kit | 从 npm 安装，升级只需改版本号（具体版本以 registry 为准） |
| GitHub | github:SHADOW-LI0327/dsh-process-kit | 免 npm；锁版本用 #<tag> 或 #<commit> |
| 本地目录 | 绝对路径，如 /Users/<you>/dsh-plugins/dsh-process-kit | 需要改插件源码时用，先 clone 到本地 |

安装即生效；若界面没刷新，再重启客户端

装不到最新版？不是安装故障。 pnpm 默认带 24 小时供应链保护（minimumReleaseAge = 1440）：发布不满 24 小时的版本不会被 ^范围 / latest 选中。等 24 小时，或钉确切版本（dsh-process-kit@0.9.0，显式钉版本按设计绕开该策略）；不建议把 minimumReleaseAge 置 0（等于关掉这道保护）。

快速开始

1. 安装插件（安装即生效，一般无需重启）
2. 直接说想做什么（"做个网站"/"做个 app"）
3. AI 调 process_init 初始化当前仓库的流程
4. 按流程推进；第一个包建议走快速路径试水：核对件写 flow: fast，人签 Gate0 后直派 dev + 存量回归 process_init 生成：docs/process/（总纲、调度手册、PROJECT.md、模板）、docs/process/.process-kit.json（卸载清单：创建过什么 + 哈希，供精确清理）、scripts/process/（门禁与 journal 脚本）、AGENTS.md（仅在缺失时创建，绝不改写；agents: false 可跳过）。

实例项目（独立仓库）

dsh-process-kit-example —— 全新空仓库里从「做一个电商 app」跑到交付的端到端实例（成果、流程产物与 journal 证据都在那个仓库里）。开跑步骤与核验检查单见 docs/ACCEPTANCE.md（含一段不装插件就能复算 journal 链式指纹的脚本）。

升级已有仓库

process_init({ upgrade: true, dryRun: true }) // 先看会动哪些文件
process_init({ upgrade: true }) // 再落地

| 文件 | 升级行为 |
| 框架自有：README.md（总纲）、orchestrator.md、四份模板、tools/README.md、scripts/process/.mjs | 内容有变才覆盖，旧版备份为 <文件>.bak-<时间戳> |
| 项目可定制：PROJECT.md、ui/tokens.md、ui/recipe.md | 永不覆盖，只列入「需人工比对」并给出包内模板路径 |
| 数据：input/、prd/<ID>、bugs/、reports/ 等 | 从不触碰 |

PROJECT.md 的 processVersion 落后时，报告会提示对照包内模板手工合并。

卸载（不想继续用）

流程内容全部落在仓库里，不是插件私有状态，所以可以完整清走；但删除不可逆，默认只预览：

process_uninstall({ dryRun: true }) // 默认就是 dry-run，先看会删什么
process_uninstall({ confirm: true, dryRun: false }) // 人明确确认后才真正删除

| 处理 | 内容 |
| 确认后删除 | docs/process/（全部过程件）与 scripts/process/（或 init 时自定义的 scriptsDir），卸载清单随目录一起删 |
| 仅删 init 创建且未改过的 | AGENTS.md、.dsh/skills/<角色>/SKILL.md（按清单哈希判断；与模板逐字一致也算；改过的默认保留，force: true 才删） |
| 永不删除 | 含自定义内容的 AGENTS.md / 同名技能、产品源码与测试、git 历史、package.json（只报告仍指向已删脚本的命令） |

- 默认先备份到系统临时目录，备份失败就不删；删除是工作区改动，不会改写 git 历史，确认后自己提交。
- 先卸流程、再卸插件：process_uninstall 由插件提供，插件先卸掉就没人替你清仓库了。
- 旧安装没有卸载清单时走保守清理（目录照删；AGENTS.md / 技能副本只删与模板逐字一致的），报告会点名保留项。老仓库先跑一次 process_init({ upgrade: true }) 同步脚本。

工具

| 工具 | 说明 |
| process_status | 扫描 docs/process，返回每个包的状态、Gate 四灯、journal 尾部、未关闭的 bug 与下一步动作 |
| gate_summary | 生成指定包的 Gate 两段式摘要骨架，依据自动填充，✅ / ❓ 留空待填 |
| process_journal | 安全追加 journal：锁 + 指纹校验 + 原子替换，时间取机器时间 |
| process_init | 将流程骨架与脚本初始化到当前仓库：默认只创建不覆盖；upgrade: true 升级已有仓库（框架自有文件覆盖前备份，项目文件永不覆盖）；同时写 docs/process/.process-kit.json 卸载清单 |
| process_uninstall | 确认后清理插件落进仓库的流程内容：默认 dry-run，confirm: true + dryRun: false 才删；默认备份；只删 init 创建且未改过（或与模板逐字一致）的 AGENTS.md / 技能副本，不删含自定义内容的用户文件、产品源码或 git 历史 |

角色

角色由插件自带技能提供，安装即注册，无需配置。技能在所有工作区可用，与仓库是否已初始化流程无关；项目内 .dsh/skills/ 的同名技能优先级更高。设置环境变量 PROCESS_KIT_SKILLS=off 可关闭。

角色清单（9 个）

| 角色 | 职责 | 自 |
| product-manager | PRD、接口契约、《设计与说明》；UAT 后做验收完备性审核；Gate0 前可做需求借鉴调研（input/<ID>-prior-art.md） | 0.1.0 |
| architect | Gate0 前与 pm 并行做技术借鉴与约束扫描（input/<ID>-tech-scan.md，只出约束 / 代价 / 许可证）；Gate0 后按需出架构设计与取舍（prd/<ID>-arch.md） | 0.6.0 |
| test-agent | 按 PRD 出验收测试（红），并独立复跑 verify（裁判运动员分离） | 0.1.0 |
| dev-agent | 按 PRD + 契约把测试实现到绿，只改源码、禁改测试 | 0.1.0 |
| uat-agent | 真机黑盒验收：只判「用起来对不对得上预期」 | 0.1.0 |
| code-review-agent | 源码 diff 的正确性 / 回归 / 边界 / 可维护性评审 | 0.1.0 |
| security-review-agent | 评审源码 diff 的鉴权 / 越权 / 注入 / 密钥 / 敏感数据 | 0.1.0 |
| logic-review-agent | 对规则表与源码做对抗式逻辑评审：规则→分支映射、未覆盖分支、具体反例 | 0.1.0 |
| ui-designer | 把《设计与说明》里触及 UI 的条目翻译成可验收的 UI 规格（组件判定 / 状态矩阵 / 文案定稿 / 字面数值），产出可打开的 HTML/CSS 原型 + handoff.md 交接表；dev 实现后、UAT 前做 UI 还原核对。是否派单由人在 Gate0 用 uiDesign: required / not-needed 显式决定；不产出 PNG/PSD | 0.2.0 |

完整版本沿革见 CHANGELOG；npm 上的具体版本以 registry 为准。

ui-designer 的边界：只翻译不发明（上游没写的进「未定口径」清单交人裁）；项目令牌优先（PROJECT.md §4 配了项目令牌就必须照抄，不得自创配色/字号/间距）；HTML 是交付主件（index.html + styles.css + handoff.md，不产出 PNG/PSD）；UI 还原核对在 dev 后、UAT 前（逐条 UI-NN 出 reports/ui-review/<ID>.md，pass 才进 UAT）；审美留给 Gate（check-ui-prototype 只判交接完整性）。

三个评审角色什么时候会跑到

9 个角色不是平权的：product-manager / architect / ui-designer / test-agent / dev-agent / uat-agent 在单包流程里按状态机派；code-review-agent / security-review-agent / logic-review-agent 只在「发布前整体回归」被派，而该环节由人显式发起 —— 没发起过发布回归，就等于这三个角色一次都没跑过（process_status 会如实报 reports/release/* 有没有报告，没有就是没跑）。

两个例外会让它们提前上场：① 人在任一 Gate 上点名；② 包触及 RBAC / 金额·分摊 / schema / 新增对外接口，主控会在 Gate 摘要里给出「是否提前跑评审」这一条。

配置

需要配置的只有 docs/process/PROJECT.md。流程文档不硬编码任何具体项目的路径与命令，全部引用该文件，因此插件升级不会覆盖已填写的内容，切换项目也只需重填此文件。

七个小节：§1 端与目录、§2 命令槽、§3 产物属主表、§4 项目配置、§5 UAT 前置自检、§6 环境与凭据、§7 通知（已废弃，编号占位）。

最小可用只填三节：§1 + §2（至少「快速验证」与「journal 追加」两行）+ §3。§4 每个键都有默认值、可先用着；§5 / §6 等到要跑 UAT 再填；§7 整节写「不适用」。§3 是硬门槛：不填会让落点门禁直接 exit 1（刻意不静默放行），不属于"以后再配也行"的那类可选项。

模板中所有 <...> 均为占位符，会被脚本忽略，不会成为有效配置。详见 docs/CONFIGURATION.md。

文档

英文版：README.en.md · docs/CONFIGURATION.en.md · docs/CONTRACT.en.md · docs/DESIGN.en.md · docs/ACCEPTANCE.en.md · docs/ECOSYSTEM.en.md（docs/I18N.md 本身中英混排，无需另译）。

| 文档 | 内容 |
| docs/I18N.md | 双语契约：语言解析优先级、机器标记、26 个配置键中英对照、维护纪律 |
| docs/CONFIGURATION.md · EN | PROJECT.md 七个小节、语言设定、占位符规则、门禁脚本 |
| docs/CONTRACT.md · EN | 机器可消费契约：frontmatter / journal / 链式指纹算法 / 卸载清单 / 退出码，CI 不装插件即可消费 |
| docs/DESIGN.md · EN | 设计红线、六处必须同步的改动、可卸载性、已知陷阱 |
| docs/ECOSYSTEM.md · EN | DSH 插件生态的准入门槛、上架清单与现状 |
| docs/ACCEPTANCE.md · EN | 插件验收：全新项目里跑通一个电商 app 的端到端场景、AI 托管 Gate、可机器核验的检查单 |
| CONTRIBUTING.md | 开发环境、测试、双语纪律、提交与发布 |

开发

零运行时依赖，无需安装依赖或构建：

npm test

四项冒烟测试：test/host.test.mjs、test/skill-registry.test.mjs、test/scripts.test.mjs、test/i18n.test.mjs。

License

MIT