工程流程套件 kovey/dsh-engineering-suite

dsh-engineering-suite

v0.2.3 · 兼容基线 @deepseek-ai/dsh- >=0.2.0-rc.1 <0.2.1-0（cordis ~4.0.4；已在 0.2.0-rc.2 上验证）
· 变更记录 · 升级指南 · 验证证据

把 docs.md 描述的「Agent 时代软件工程落地方案」实现为一组可独立挂载的 DeepSeek Harness（dsh）插件：角色 → 规格 → 测试设计 → 实现 → 质量 → 证据 → 审计 → 编排，每个关注点一个插件，全部通过官方插件契约接入，不改 dsh 核心。

规格澄清 ─ 测试设计评审 ─ 规格审批 ─ 实现 ─ 质量验证 ─ 交付审计 │ │ │ │ │ │ spec-gate test-design- spec-gate role- quality- evidence-gate gate guard gate audit-trail │ │ 规范/影响/覆盖率/供应链（四个新增门禁） └──────── orchestrator（顶层编排）────────┘

11 个插件各自回答一个可判定的问题：做的是不是对的（spec-gate / test-design-gate）、 谁在做、权限对不对（role-guard）、能不能跑（quality-gate）、还可维护吗（standards-gate）、 这次改动碰了什么（impact-gate）、测试有没有用（coverage-gate）、能不能上生产 （supply-chain-gate）、能不能证明（evidence-gate / audit-trail）、按不按流程走（orchestrator）。

六阶段视图

套件按 规划 → 实现 → 测试 → 交互 → 交付 → 部署 组织；每个阶段都有插件承担、有产物留下、有门禁收口，所以「缺了哪一段」是看得见的，而不是没人注意到的空白：

| 阶段 | 承担者 | 收口门禁 |
| 规划 | spec-gate（需求/验收标准/边界/负面约束/增改删/里程碑/跨 mission 台账/ADR/非功能预算）、test-design-gate、impact-gate | spec-approved、test-design |
| 实现 | role-guard（权限/模型/派发）、standards-gate（规范棘轮）、quality-gate（写后 lint）、supply-chain-gate、audit-trail | standards-pass（可选） |
| 测试 | quality-gate（跑命令 + 指标预算 + 契约冒烟）、coverage-gate（覆盖率/增量/flaky/变异）、impact-gate（最小回归集 + flaky 隔离计划）、test-design-gate | quality-pass |
| 交互 | interaction-gate（ask/notify/progress + 通道注册 + 决定台账）、宿主的 approval 接缝 | 横切，无阶段门禁 |
| 交付 | evidence-gate（证据→门禁→回执/发布台账）、audit-trail、orchestrator（回执门禁） | receipt |
| 部署 | deploy-gate（环境清单 → go/no-go → 人工批准 → 执行 → 上线后验证 → 回滚） | deploy-go、deploy-verified |

非功能预算（p95、包体积、迁移耗时）写在规格里：随规格一起审批、能追溯到需求 ID、由 budget_check 测量；宿主配置与规格声明同 id 时宿主生效但差异会被报告，requireSpecBudgets 打开后「声明了却没验证」的预算会拦住交付。

先问「我们在哪、缺什么」：bash scripts/doctor.sh（人/CI，必需项缺失时退出码 1）或会话里的 suite_status（同一份判定，另加运行时事实：哪些插件挂载、当前阶段、待审批、通道能力）。
每条发现都带下一步的确切命令。

包一览

| 包 | 插件 id | 职责 | 关键工具 |
| dsh-eng-core | —（库） | 共享运行时：mission 工件、确定性命令执行、git 指纹、审计 JSONL、日志、扫描器、代码度量、变更影响、审批契约、fake host 测试夹具 | — |
| dsh-role-guard | role-guard | 角色文件（persona/模型/工具/技能白名单）+ 最小权限派发 + 只读评审服务 | team_delegate、role_list |
| dsh-spec-gate | spec-gate | 结构化规格 + 人工审批 + 写操作前置拦截 + 需求增改删 + 非功能预算（p95/体积/迁移耗时） + 跨 mission 规划台账 + 里程碑 + ADR | spec_create、spec_approve、spec_amend、spec_status、spec_bootstrap、plan_status、adr_record、adr_list |
| dsh-test-design-gate | test-design-gate | 把测试设计嵌进规格并自动评审（覆盖度/场景完整性/可执行性） | test_design_review、test_design_template |
| dsh-quality-gate | quality-gate | 宿主配置命令的三态门禁 + 写后 lint 回路 + 收尾阻断 + 指标预算与契约冒烟 | quality_gate_run、quality_gate_status、budget_check、contract_check |
| dsh-evidence-gate | evidence-gate | Mission → Evidence → Gate → Receipt，缺失证据 fail closed | evidence_record、evidence_status、mission_complete |
| dsh-audit-trail | audit-trail | 全量工具调用 JSONL 审计 + 写前快照 + 按轮次回滚 | audit_report、audit_rewind |
| dsh-orchestrator | orchestrator | 阶段流水线、入口/出口门禁、回退、熔断、断点恢复、按难度选模型、阶段自主派发 | orchestrate |
| dsh-interaction-gate | interaction-gate | 交互层：统一 ask / notify / progress，多通道注册、一次性 token、决定台账、fail-closed 超时 | interaction_ask、interaction_notify、interaction_progress、interaction_status |
| dsh-suite-doctor | suite-doctor | 统一入口与自检：阶段、门禁配置、缺失项、待审批、台账规模（离线判定 + 运行时事实） | suite_status |
| dsh-deploy-gate | deploy-gate | 部署层：环境清单、go/no-go、人工批准、灰度/回滚、上线后验证、部署台账 | deploy_plan、deploy_run、deploy_verify、deploy_rollback、deploy_status |
| dsh-standards-gate | standards-gate | 代码规范门禁：仓库自有阈值、基线棘轮、只读结构评审 | standards_check、standards_bootstrap、standards_review、standards_status |
| dsh-impact-gate | impact-gate | 变更影响分析：反向依赖闭包、最小回归测试集、风险分级、flaky 隔离计划（带 owner 与到期） | impact_analyze、impact_tests、impact_status、flaky_plan、flaky_status |
| dsh-coverage-gate | coverage-gate | 测试有效性：覆盖率（含增量）、flaky 检测、变异测试（存活变异体逐条列出） | coverage_check、flaky_check、coverage_status、mutation_check |
| dsh-supply-chain-gate | supply-chain-gate | 密钥扫描（分级+脱敏）、新增依赖人工审批、依赖审计 | secret_scan、dependency_audit、supply_chain_status |

快速开始

1. 本地依赖（npm registry 不可用时用软链指向已安装的 harness） bash scripts/link-deps.sh

2. 构建 + 全量测试 bash scripts/test-all.sh

3. 挂载到本地 dsh profile（默认 headless + nvim-tui，绝不碰生产 profile tui） bash scripts/install-into-dsh.sh --dry-run # 先看要改什么 bash scripts/install-into-dsh.sh

4. 重启会话，在 TUI 里 /plugins 应能看到 14 个 bundle

正常有 npm registry 时，也可以在每个包的目录里 pnpm install 后用 dsh plugin --profile <name> add <包路径> 挂载（脚本做的是同一件事）。

一条 mission 的完整生命周期

1. spec_create 写 .dsh/specs/<mission-id>.md（验收标准 AC-00x / 文件边界 / 负面约束 / 测试设计）
2. test_design_review 解析规格里的测试设计，检查覆盖度 / 三类场景 / 可执行性 → mission.testDesign.passed
3. spec_approve 通过 approval seam 请人审批 → mission.spec.approvedAt 落章（在拿到审批之前，任何 write/edit 调用都会被 spec-gate 直接拒绝）
4. team_delegate(role) 按角色派发实现/审查：子 Agent 的工具白名单由宿主强制（白名单外不可见、不可调用）
5. evidence_record 把命令输出摘要、git diff 指纹、测试报告登记为证据
6. quality_gate_run 执行宿主配置的 pnpm test / typecheck / lint → PASS | WARN | BLOCK （门禁必须不早于最新的 command/test 证据，否则算证据陈旧并阻断；重跑门禁即可自愈）
7. mission_complete 规格已审批 + 门禁 PASS + 必需证据齐备，才签发不可变回执（receipts/<id>.json），mission → delivered
8. audit_report/rewind 随时审计“谁在什么上下文下改了什么”，必要时按轮次回滚工作区

编排插件把上面每一步变成一个阶段，并用 orchestrate 推进；门禁不通过时回退到上一个合适阶段（超过 maxAttempts 则熔断并把 mission 标为 blocked，绝不无限循环）。

工件布局（全部落在被治理的仓库里，可 commit、可 diff、可审计）

.dsh/
specs/<mission-id>.md 规格工件（docs.md §3.2 规定路径） missions/<mission-id>/ mission.json 版本化的 mission 状态（跨插件共享契约） evidence.jsonl 只追加的证据账本 gates/<gate-id>.json 每次门禁的裁决与命令输出摘要 receipts/<receipt-id>.json 不可变交付回执 stages/<stage-id>.json 编排阶段结果（断点恢复依据）
test-design-review.{json,md} 测试设计评审报告
audit/<session-id>.jsonl 工具调用审计（含参数/结果摘要与指纹） audit/snapshots/… 写前快照（rewind 用） state/sessions/<session-id>.json 会话 → mission 绑定 roles/.md 工作区自定义角色

按项目配置（一个进程服务多个仓库）

profile 的 loader 行是上限，每个仓库可用自己仓库里的文件细化（人类提交、可 review）：

| 文件 | 典型用途 |
| .dsh/quality-gate.json | 这个仓库跑哪条测试/lint 命令、改动预算、收尾阻断次数 |
| .dsh/spec-gate.json | 这个仓库被管多严（{"enforce": false} = 试验仓库不拦写） |
| .dsh/evidence-gate.json | 必填证据类型、门禁来源、是否核对工作区指纹 |
| .dsh/test-design-gate.json | 测试设计评审口径（minTextLength/strict/allowDanglingCase/requireAllScenarios） |
| .dsh/audit-trail.json | 是否快照、快照上限、哪些工具不进审计 |

// <仓库>/.dsh/quality-gate.json { "commands": [{ "id": "test", "command": "cargo test", "required": true, "phase": "gate" }] }

不确定写什么？让脚本按项目类型生成（先 dry-run 看内容，再 --write）：

bash scripts/project-config.sh # 打印将写入的 JSON（不改文件） bash scripts/project-config.sh --write # 写 <仓库>/.dsh/quality-gate.json bash scripts/project-config.sh --write --spec off # 试验仓库：再写 spec-gate.json 关闭写拦截 bash scripts/project-config.sh --write --test "pnpm vitest run" --lint "pnpm eslint ." 识别 Cargo.toml / go.mod / pyproject.toml·tests/ / package.json（pnpm·yarn·npm）/ Makefile:test； lint 命令一律标成非必需（缺脚本只 WARN，不阻断交付）；已存在的文件不加 --force 不会覆盖。

日志按项目分文件

一个进程服务多个仓库时，默认单文件会在行内标注项目名（[repo]）以便 grep；要让每个项目写自己的文件：

- id: quality-gate
config:
{projectPath} 完全可读（推荐）：~/workspace/deepseek/dsh-project → workspace-deepseek-dsh-project logFileTemplate: '~/.dsh/logs/{projectPath}/quality-gate.log'
或者更短、仍唯一：{project} = deepseek-dsh-project-44002d（末两段 + 6 位短哈希）
或者只按目录名：{basename} = dsh-project（同名目录会共用文件）
未绑定工作区的行（装配日志等）仍写进 logFile，不会丢。
logFile 与 logFileTemplate 都是 host-only：项目文件改不了它们（否则一个仓库能把自己的日志藏起来）。

规则：可覆盖键白名单（写别的键会被忽略并记日志，绝不静默生效）；文件损坏 → 回退 profile 配置；配置文件在信任根里（.dsh/** 对写类工具关闭），所以模型无法把自己的门禁调松；每个 status 工具都会显示"配置来源：项目级 …/profile"。细节见 docs/ARCHITECTURE.md §5.2。

设计红线

1. 门禁的确定性来源是宿主配置：命令、白名单、上限都来自插件 Config；模型不能临时编造门禁命令。
2. fail closed：证据缺失 / 门禁未跑 / 状态不确定 → 阻断，并给出可执行的下一步。
3. 不可见优于被拦截：角色白名单通过宿主 toolFilter 生效，越权工具在子 Agent 的工具列表里根本不存在。
4. 防死循环：所有“阻断并要求修复”的路径都有次数上限 + 状态指纹去重。
5. 不改 dsh 核心：只用 ctx.tools.register()、ctx.tools.guard()、ctx.on()、ctx.effect()、
ctx.systemPrompt.section()、ctx.get() 等官方契约。

细节见 docs/ARCHITECTURE.md（分层与协作契约）、 docs/PLUGIN-CONVENTIONS.md（新增插件的接口约定）、 docs/VERIFICATION.md（验证记录与复现步骤）、 docs/KNOWN-LIMITS.md（七项已知边界的现状、启用方式与验证方法）。

开发

bash
bash scripts/doctor.sh # 自检：这个仓库还缺哪些门禁配置（必需项缺失时退出码 1） bash scripts/verify.sh # 全量验收：typecheck + 各包单测 + 跨包集成测试 bash scripts/e2e-mission.sh # 端到端：脚本化 stub 模型驱动真实 harness 跑完一条 mission（无需 API key） bash scripts/typecheck-all.sh # 仅类型检查 bash scripts/build-all.sh # 只编译指定包：build-all.sh dsh-spec-gate bash scripts/test-all.sh dsh-spec-gate # 单包测试 bash scripts/archive-missions.sh --dry-run # 台账只增不减：把旧的已交付 mission 归档（先 dry-run）
DSH_ENG_DEBUG=1 <启动 dsh> # 让插件的文件日志同时镜像到 stderr

各包的 README 说明自己的配置项、工具参数与协作面；docs/PLUGIN-CONVENTIONS.md 是新增插件时必须遵守的接口契约； docs/VERIFICATION.md 记录验证证据与复现步骤，docs/KNOWN-LIMITS.md 逐条列出机制测不到的边界（这比「全都支持」更有用），UPGRADE.md 是升级指南。

当前规模：12 个包（11 个插件 + 1 个共享库）、102 个源文件约 34k 行、17 个测试文件约 14k 行， 498 个测试（497 通过 / 0 失败 / 1 如实跳过）；端到端在真实 harness 上验证—— 11 个插件全部 applied 并跑完一条 mission（scripts/e2e-mission.sh，脚本化模型，无需 API key）。