工程化交付引擎 使用手册

1. 工作原理

开发者在「工程化开发引擎」会话里提出开发请求后，统一由 dev_task 工具接管，再由编排技能 eng-delivery 读任务状态、按当前阶段推进，一个阶段一个阶段地走。

开发请求
  → dev_task（统一入口，硬约束在代码里执行）
  → eng-delivery（编排：读状态 → 选阶段 → 推进）
      → 需求评审 · requirement-analysis
      → 设计     · solution-design
      → 开发     · code-implement
      → 交付     · code-verify
      → 代码审核 · code-review + code-commit

三样东西分工明确：流程预设决定「走哪条流水线、有哪些守卫」，Skill 决定「这一站做什么」，Rule 决定「这一站守什么」。任务状态单独落盘，负责「跨会话恢复到哪一步」。

2. 安装与启用

2.1 前置：Node.js ≥ 22 + pnpm

npm install -g pnpm   # dsh 的 plugin 子命令底层转发给 pnpm，必须先装

2.2 先装 DSH（三选一）

# 方式 A：npm 装 CLI（非源码，推荐给使用者）
npm install -g @deepseek-ai/dsh
dsh web

# 方式 B：npx 免安装直接跑
npx @deepseek-ai/dsh web

# 方式 C：从源码 clone（开发者）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install && pnpm run build && pnpm dsh web

2.3 把引擎插件装进 profile

dsh plugin --profile web add @godv61/dsh-task-engine

dsh plugin --profile <name> add <package> 会在 $DSH_HOME/profiles/<name>/ 里执行 pnpm add，并自动识别插件声明的 dsh.bundle.patch，把它挂进该 profile 的插件层栈——不要手写 npm i 装到别处，那样不会挂载。

装完重启 dsh web 生效，自动完成两件事：侧边栏多出「工程流程」工作台；预设列表多出「工程化开发引擎」。

2.4 启用

新建会话 → 预设选「工程化开发引擎」。这个会话就挂上 dev_task + 内置技能 + 工程人设，开始按流程走。

3. 文件与目录

D:\workspace\
├─ AGENTS.md       ← init 生成的项目描述（DSH 每会话自动注入）
├─ .dsh\
│  ├─ eng.json       ← 流程预设 + 节点挂载（团队共享，可进 git）
│  ├─ skills\        ← 项目级 skill
│  ├─ rules\         ← 项目级 rule
│  └─ task-*.json    ← 每个任务的状态快照
└─ $DSH_HOME\
   ├─ skills\        ← 用户级 skill（个人所有项目通用）
   └─ rules\         ← 用户级 rule

4. 三套流程预设

阶段图、守卫、提交规则都随预设固化好，团队只选一套，不改流程图。

5. Skills：这一步做什么

每个内置 Skill 尺寸很小、只做一件事。挂到对应节点后，走到那一步才加载，不会一次性全塞给模型。

6. Rules：这一步守什么

Rule 是纯正文的约束，只有挂在节点上、且走到那一步时才读。内置三条：

最重要的轻量原则：团队想改「提交消息格式」「交付要自测」这类约定，新建一个项目级规则 / 技能（用新名字）再挂到对应节点，而不是改一堆参数；内置 skill / rule 的正文不可被同名覆盖。

当前版本支持三个内置流程及追加阶段资源。可视化自定义流程处于规划阶段，尚未发布。

7. 配置流程与挂载

侧边栏点「工程流程」打开工作台，五个标签页：项目初始化 / 流程配置 / 任务 / 技能 skill / 规则 rule，默认落在「项目初始化」（详见第 8 节）。日常配流程只需在「流程配置」页做两件事：

1. 选流程预设：standard / agile / minimal 点一下即切。
2. 给节点挂 skill / rule：先选一个节点（如「开发」），再勾选它用什么 skill、守哪条 rule，保存。

「技能」和「规则」页提供搜索、来源筛选、新建、安装、查看、编辑与删除。内置资源只读。点「安装技能」直接打开系统文件选择器，选择含 SKILL.md 的文件夹；点「安装规则」选择一个 .md 文件。选择后先显示预览：名称、正文、文件数、体积、目标路径和同名冲突。确认项目或个人范围后点击「确认安装」；预览本身不写入文件，改变范围后需要重新预览。

项目资源写入工作区 .dsh/skills 或 .dsh/rules；个人资源写入 $DSH_HOME 对应目录。浏览器选择的是浏览器所在电脑的文件；高级目录模式读取 Harness 主机的目录。技能保留脚本、references、模板和二进制资源，排除常见缓存；上限 1000 文件、100 MB、单文件 20 MB、20 层目录，SKILL.md 和规则正文上限 1 MB。拒绝覆盖同名资源；主机扫描拒绝符号链接和 junction。浏览器上传不提供源链接元数据。

资源删除前会显示名称与实际目标路径，确认后永久删除；可点击「保留」取消。任务台账支持搜索、风险与阶段筛选，并显示验证、审核和更新时间。流程配置读取与保存失败时显示错误，损坏任务记录不会被静默视为没有任务。

// .dsh/eng.json 等价内容
{
  "flow": "standard",
  "stage_bindings": {
    "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
    "开发":     { "skills": ["code-implement"],        "rules": ["coding-conventions"] }
  }
}

三层来源与优先级：同名 skill / rule，内置 > 用户 > 项目——内置不可被同名覆盖（新建同名会被拒，解析同名只读内置版）。要加团队约定，新建一个不同名的项目级 / 用户级资源再挂到节点上。

8. 项目初始化（init）

二开 / 遗留项目没有文档时，先给项目建一份「描述文件」——项目根的 AGENTS.md。DSH 平台会把它自动注入到每个会话，生成一次，之后每个任务开工 AI 都自带这份项目认知（项目是什么 → 怎么跑 → 结构 → 约定 → 坑）。

工作台初始化（推荐）

1. 侧边栏点「工程流程」，工作台默认落在「项目初始化」标签页。
2. 先看已有文档：顶部显示「未初始化」或「已初始化 · N 行（上限 200）」。工作区根没有 AGENTS.md 时，会自动向下找唯一子项目、向上找父目录，并把实际定位路径标出来（如 已定位到 D:\qdmai\qms\AGENTS.md）。
3. 让 AI 初始化：点按钮，AI 扫描项目（目录结构、关键文件、技术栈、构建 / 运行命令、约定与红线）生成草稿——只预览、不落盘，硬校验行数 ≤ 200 行，超了精简到「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」，只留骨架不塞长文。运行中实时显示「已耗时 X 秒」，最长 150 秒超时，超时提示重试即可。
4. 保存 / 保存并覆盖：预览满意点「保存」——首次创建直接写入；已有 AGENTS.md 会标「保存并覆盖」，必须人工点确认才覆盖，保护项目已有治理文件不被裸覆盖。
5. 也可点「手动编辑」直接改正文后保存。

对话式 init

1. inspect：对 AI 说「帮我初始化这个项目」；AI 读现有 AGENTS.md（若有）返回，没有则扫目录结构、技术栈、构建 / 运行命令、约定与红线。同时报告：项目根（自动从 workspace 向上发现）、语言栈（Node / Java / Python / Go / Rust）与默认验证命令、其它治理文件（CLAUDE.md、.cursorrules——init 只管理 AGENTS.md，不覆盖它们）、项目级 skill/rule 目录（.dsh/rules/*.md、.dsh/skills/<name>/SKILL.md）。
2. propose：AI 写成 AGENTS.md 草稿，此步只预览、不落盘，同样硬校验行数 ≤ 200 行，并返回内容 hash。
3. apply：落盘。必须传回 propose 返回的 expected_hash（缺失或与内容不一致一律拒绝，防止预览与落盘之间内容被换）；覆盖已有 AGENTS.md 时还必须传回 existing_hash（证明审批期间现有文件未被他人改动）并带 overwrite 且经人工批准。写入目标必须在项目根内。

项目根/
├─ AGENTS.md          ← init 生成，DSH 每会话自动注入
└─ .dsh/
   ├─ eng.json        ← flow + verify_command（可覆盖语言默认验证命令）
   ├─ skills/ · rules/
   └─ task-*.json

9. 如何开始一个任务

1. 新建会话，预设选「工程化开发引擎」。
2. 直接描述需求（加功能 / 修 bug）。
3. AI 建任务、判 work_size 与 risk_level，停在起始阶段（标准流程是「需求评审」）。
4. AI 落需求说明，需要拍板处发起审批，你点「允许」才进入下一步。
5. 之后一个阶段一个阶段推进，直到「完成」。

10. 流程如何逐阶段执行

新任务离开阶段前检查绑定技能是否通过 skill 工具成功加载；附加技能需通过 skill_result 记录执行场景与真实验收命令；状态中的 command_receipts_required 列出这些技能，七个内置技能无需重复登记。挂在“完成”的技能在前一阶段执行。命令成功只证明该命令通过，不证明测试覆盖完整。审核改动后须重跑验证。旧任务继续使用冻结快照。

贯穿全程的硬规则

• 阶段是硬状态：status 说你在哪，就只做那一步，绝不倒带重走、绝不跳。
• 确认只能人来做：需求确认、方案确认由 AI 发起审批，你在页面点「允许」；AI 不能自己通过、不能绕过。
• 渐进披露：走到哪个阶段，才加载那一段的 skill / rule。

11. 任务状态如何记录进度

每个任务一份 .dsh/task-*.json，只保存当前有效状态，不保存聊天全文和流水日志。

会话断了没关系：重新开会话，AI 读 stage、确认态、验证与评审字段，就能从断点继续，不依赖上一轮聊天。

12. 验证、评审与提交

验证为什么不该总那么慢

• 实施中优先受影响模块的编译、目标测试与静态检查。
• 差异没变时复用有效证据，不重复跑相同命令。
• 无法联调外部系统时必须如实写「未联调」，不能把编译成功说成功能通过。
• high_risk 任务过验证门必须跑真实命令回执（引擎运行命令、取退出码，非自报通过）。
• verify 不带 command 时引擎自动选命令：.dsh/eng.json 的 verify_command 优先，其次按项目语言用默认（node → npm test、java → mvn -q test、python → python -m pytest、go → go test ./...、rust → cargo test）；识别不出语言且未配置时保留自报路径。跑命令依赖宿主 shell 服务，未挂载会明确报错。
• 验证命令始终在任务记录的项目根运行（任务创建时自动发现并固化 root），不是会话当前目录——monorepo 里会话停在子目录时，npm test 等也会在放清单文件的项目根执行；回执记录的 root 与任务根强校验，不一致直接拒绝。

评审

开发阶段每项做「规格 + 质量」两阶段评审，都 pass 才标 done；缺评审或任一阶段 fail 会挡住「开发 → 交付」。

提交策略

提交消息要求 【模块】【TASK】做了什么，且只提交任务 files 范围内的文件。要彻底封死模型绕过 dev_task 直接 git commit，给仓库装一道机械钩子：

dev_task operation=install_hook   # 装入 .git/hooks/commit-msg，装上后任何 git commit 都被同一套规则校验
dev_task operation=verify_hook    # 随时比对安装钩子与内置门禁的 hash，被替换/篡改立即报错

钩子的额外硬校验（0.21/0.22）：① 任务记录的流程快照带 SHA-256 hash，被手改过的快照一律拒绝提交；② 触及敏感路径（.env、credentials、secrets、.git；.dsh 的任务记录与流程配置由快照 hash 与豁免保护，项目级 rules/skills 属常规内容）的提交，要求任务为 high_risk 且验证有真实命令回执，否则拒绝；③ 删除、类型变换、重命名的旧·新路径都受范围检查。

风险降级（0.22）：set_risk 把 high_risk 降为 standard 必须人工批准，并写入任务的 risk_downgrades 审计记录；降级后高风险回执门不再适用，请谨慎。

13. 一个标准任务的完整走查

假设需求是「给现有查询接口加一个权限校验」。标准流程下，关键决策点应接近下面这样：

flow: standard          // 项目预设
work_size: standard     // 数个文件 + 权限判断
risk_level: high_risk   // 涉及鉴权，验证要加证据

① 需求评审
   - 目标：无权限返回 403；有权限正常返回。
   - 验收、非目标写清 → 【人确认需求】

② 设计
   - 最小方案：Controller 加校验、Service 复用现有鉴权方法。
   - 不新建接口 / DTO / 异常包装 → 【人确认方案】

③ 开发
   - T1：接口加校验 + 编写无权限 / 有权限用例。
   - 规格 ✓ 质量 ✓ → done

④ 交付
   - 验证：跑鉴权用例，`verify` 传真实命令（high_risk 由引擎取退出码判定）。
   - 文件改动后必须重新验证，旧回执失效。

⑤ 代码审核
   - 结论：通过 · 问题：无
   - 执行挂在完成阶段的附加技能，再提交并回写真实 hash。

⑥ 完成

这类任务不应因为「以后可能复用」扩展成多层架构，也不应把推荐项自动当成验收条件。

14. 边界与常见问题

状态查询中的 evidence_blockers 列出过期验证和附加技能回执；commit.allowed 同时检查这些阻塞及技能执行义务。legal_next 是流程定义的候选去向，不表示所有门禁已通过。

版本 0.23.1 · 流程执行与真实回执修复 · 最后更新：2026-09-16