@godv61/dsh-task-engine 0.14.0 → 0.17.0

package/README.md

@@ -4,20 +4,21 @@
 
 核心是一个 `dev_task` 工具 + 内置技能。工具的硬约束在代码里执行，不是"提醒模型"：
 
-- **阶段流转**：只能沿 `.dsh/eng.json` 配的阶段图走；非法流转直接报错拒绝。
+- **阶段流转**：只能沿所选流程预设的阶段图走（`standard` / `agile` / `minimal`）；非法流转直接报错拒绝。
 - **确认/验证门**：需求/方案未确认 → 进不了设计/开发；实施项没完 → 不能交付；高风险没验证证据 → 不能过评审。
-- **产物门**：每个阶段可声明必交产物 + 必填字段（需求说明 / 设计文档 / 评审记录…），字段没填全 → 不让流转。
-- **提交门禁**：到检查点才能提交，消息必须匹配 `message_pattern`，`manual` 策略永不自动提交。
+- **产物门**：每个阶段要交的产物 + 必填字段（需求说明 / 设计文档 / 评审记录…已固化在预设里），字段没填全 → 不让流转。
+- **提交门禁**：到检查点才能提交，消息必须匹配预设的提交格式，`manual` 策略永不自动提交。
 - **文件范围**：任务声明 `files`（本任务该改的文件），提交碰了范围外的文件 → 工具和 git 钩子都拒绝。
-- **skill / rule 挂载（0.6.0）**：每个阶段可挂「这个阶段用什么 skill」+「守哪条 rule」；模型走到该阶段时，`dev_task` 只**渐进披露**这阶段挂载的内容，不一次性全给。内置一套通用库，也能在网页里新建自己的 skill/rule。
+- **skill / rule 挂载**：流程预设里每个阶段默认挂了「这个阶段用什么 skill」+「守哪条 rule」；项目可覆盖挂载，模型走到该阶段时，`dev_task` 只**渐进披露**这阶段挂载的内容，不一次性全给。内置一套通用库，也能在网页里新建自己的 skill/rule。
 
 ## 目录
 
 ```
 cordis.patch.yml        bundle 声明 + host 组合 patch（一行，只挂 host 半：Remote 控制器 + 工作台 UI）
-defaults/eng.json       内置默认工作流（可被项目 .dsh/eng.json 覆盖）
+defaults/eng.json       标准预设的默认声明示例（flow + stage_bindings）
 hooks/commit-msg        git 提交门禁钩子（install_hook 装进 .git/hooks/）
 src/engine.ts           纯函数状态机 + 配置校验（无 harness 依赖，双端复用）
+src/workflows.ts        内置 3 套流程预设（阶段图/守卫/产物/提交规则/默认绑定全部固化）
 src/index.ts            host 入口：挂 task-engine Remote 控制器 + 首次启动自动 seed「工程化开发引擎」预设
 src/seed-preset.ts      对齐当前 standard 复制出 eng 预设（换人设 + 加 agent 行，幂等）
 src/agent.ts            agent 入口（./agent 出品）：在调用它的预设 scope 里注册 dev_task + 内置技能
@@ -60,7 +61,7 @@ dsh plugin --profile <name> add .
 
 - **用**：新建会话（或设置 → agent 预设）选「工程化开发引擎」，这个会话就挂上 `dev_task` + 内置技能 + 工程人设，按流程走。
 - **不用**：选 `standard` / `minimal` / 其它预设，就没有 `dev_task`、没有内置技能、没有工程人设，流程完全不介入。
-- 侧边栏「工程流程」工作台不受影响，随时供人配置 `.dsh/eng.json` 和 skill/rule。
+- 侧边栏「工程流程」工作台不受影响，随时供人选流程预设、给节点挂 skill / rule、在线编辑 skill / rule 正文。
 
 这一层对称由 DSH 的工具/技能 scope 机制保证：host 半从不把 `dev_task` 注册进全局工具层，agent 半（`@godv61/dsh-task-engine/agent` 行）只在命名它的预设里注册——所以切换预设本身就是开关。
 
@@ -75,30 +76,34 @@ dsh plugin --profile <name> add .
 
 也可重跑 `dsh-task-engine-enable` 强制重建默认的 `eng`。
 
-## 项目配置（让流程贴合你的项目）
+## 项目配置（选流程 + 挂 skill/rule）
 
-在项目根放 `.dsh/eng.json`（复制 `defaults/eng.json` 改字段即可）：
+在项目根放 `.dsh/eng.json`（没有就用 `standard` 预设）。收敛后只需写两件事：
 
-- `stages` / `start_stage` / `transitions`：阶段与流转图；每条边的 `requires` 用引擎原生 guard。
-- `artifacts`：每个阶段要交的产物（`stage` + `id` + `name` + `fields`）。给某条边加 `artifacts_present` guard，就能让「该阶段产物字段没填全」挡住流转。
-- `commit.policy`（`task|item|manual`）、`commit.message_pattern`/`message_hint`、`commit.checkpoints`、`commit.file_scope`（是否强制"只提交任务内文件"，默认 true）。
-- `high_risk_requires_verification`。
-
-原生 guard：`requirement_confirmation`、`solution_confirmation`、`todos_done`、`verified`、`review_passed`、`artifacts_present`。
+```json
+{
+  "flow": "standard",
+  "stage_bindings": {
+    "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
+    "开发":     { "skills": ["code-implement"], "rules": ["coding-conventions"] }
+  }
+}
+```
 
-产物落库用 `dev_task`（operation=record, artifact=..., fields=...）：字段不合法会拒绝，没填全会提示 still missing；被 `artifacts_present` 挡住的 `advance` 会报「guards unmet: artifacts_present」。
+- `flow`：选一套内置流程预设 —— `standard`（需求评审→设计→开发→交付→代码审核，含产物门+确认门）/ `agile`（需求→开发→交付→审查，四阶段少产物）/ `minimal`（开发→交付，只留提交门禁）。
+- `stage_bindings`：每个节点挂哪些 skill / rule（可整体省略，省略即用该预设自带的默认绑定）。
 
-文件范围用 `dev_task`（operation=scope, files=[...]）声明，或建任务时 `create files=[...]` 直接给；提交时 `dev_task`（operation=commit, files=[...]）也要带同一批文件。
+**阶段图、流转守卫、产物字段、提交规则、验证证据开关全部固化在预设里，不再手工配置**。团队要改「提交消息格式」「交付要自测」这些约定，就覆盖内置的 `code-commit`/`code-verify` skill 和 `commit-conventions` rule（正文即规范），而不是改一堆参数。
 
-**配置写错会报错，不再悄悄退回默认**：结构校验（阶段重复/缺失、流转指向未知阶段、guard 拼错、坏正则等）逐条列出。用 `dev_task`（operation=config）随时查看「当前生效配置 + 哪里配错了」。
+`dev_task`（operation=config）随时查看当前生效配置；配置写错（未知 flow / 绑定到不存在的阶段 / 空名）会报错，不悄悄退回默认。
 
-## 网页配置界面（0.5.0 起）
+## 网页配置界面
 
-不用手写 `.dsh/eng.json`。装在带 Web 的 profile 里后，打开 Web GUI → 设置 → 多出一个「工程流程配置」页：
+不用手写 `.dsh/eng.json`。装在带 Web 的 profile 里后，打开 Web GUI → 侧边栏「工程流程」工作台 →「流程配置」标签页：
 
-- 顶部选工作区，页面读出该工作区的 `.dsh/eng.json`（没有就用内置默认并提示「当前使用内置默认配置」）。
-- 阶段、流转（含守卫）、产物、提交规则、高风险验证据开关都能可视化编辑。
-- 编辑时**实时**跑 `validateWorkflow`：有问题就红字列出、保存按钮置灰；主机保存前再校验一遍，有问题的配置永不落盘。
+- 顶部选工作区，页面读出该工作区的 `.dsh/eng.json`（没有就用 `standard` 预设）。
+- 只有两件事可配：**选流程预设**（standard / agile / minimal）+ **给每个节点挂 skill / rule**。阶段流转、守卫、产物、提交规则、验证证据开关都是预设固化的，页面只读展示「流程节点」，不再开放编辑。
+- 编辑时实时跑 `validateWorkflow`：有问题红字列出、保存按钮置灰；主机保存前再校验一遍，有问题的配置永不落盘。
 - 保存写入所选工作区的 `.dsh/eng.json`，和 `dev_task` 用的是**同一套**校验（单一事实来源）。
 
 > 纯 headless 装机不受影响（只是没有这个页）；Web profile 需要包含 `@deepseek-ai/dsh-web-app`。
@@ -109,6 +114,7 @@ dsh plugin --profile <name> add .
 
 ```json
 {
+  "flow": "standard",
   "stage_bindings": {
     "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
     "开发":     { "skills": ["code-implement"], "rules": ["coding-conventions"] }
@@ -118,7 +124,7 @@ dsh plugin --profile <name> add .
 
 - **渐进披露**：模型走到某阶段时，`dev_task`（`status` / `advance`）只返回**这个阶段**挂载的 skill 名 + rule 内容；skill 用 DSH 的 `skill` 工具按名加载，rule 直接把正文给出。阶段推进到哪，才给哪。
 - **三层来源**：技能和规则都来自「内置 + 项目 + 用户」三层——内置（本包 `skills/`、`rules/`）、项目（`.dsh/skills/`、`.dsh/rules/`）、用户（`$DSH_HOME/skills/`、`$DSH_HOME/rules/`），同名时项目优先于用户优先于内置。
-- **网页新建**：设置页「新建 skill / rule」填 name + description + 正文，即可写进项目 `.dsh/`（团队共享）或用户 `$DSH_HOME/`（个人全局），写好后自动出现在挂载清单里。
+- **网页新建 / 查看 / 编辑 / 删除**：工作台「技能 / 规则」标签页里可新建、查看、编辑、删除项目级/用户级 skill 和 rule（内置只能查看、不可删改）。查看时正文以 markdown **富文本**渲染在宽弹窗里；编辑时正文保持纯文本。项目级写进 `.dsh/skills|rules/`（团队共享），用户级写进 `$DSH_HOME/skills|rules/`（个人全局），写好后自动出现在挂载清单里。
 - **内置库**：6 个节点技能（`requirement-analysis` / `solution-design` / `code-implement` / `code-verify` / `code-review` / `code-commit`）+ 3 条规则（`coding-conventions` / `commit-conventions` / `security-redlines`），开箱即用；想加项目专属的，用 DSH 原生技能机制或网页新建即可。
 
 ## git 提交门禁（防止绕过）
@@ -126,10 +132,21 @@ dsh plugin --profile <name> add .
 默认提交是「工具校验 + 模型执行 git」，模型理论上能绕过 `dev_task` 直接 `git commit`。装个机械钩子彻底封死：
 
 1. 用 `dev_task`（operation=install_hook）装进 `.git/hooks/commit-msg`（每个克隆本机装一次）。
-2. 之后任何 `git commit`，钩子都用和引擎**同一套规则**检查：没有 dev_task 任务、阶段没到提交检查点、消息不匹配 `message_pattern`、提交文件不在任务 `files` 内——一律拒绝并打印原因。
+2. 之后任何 `git commit`，钩子都用和引擎**同一套规则**检查：没有 dev_task 任务、阶段没到提交检查点、消息不匹配预设的提交格式、提交文件不在任务 `files` 内——一律拒绝并打印原因。
 
 > 钩子读 `.dsh/eng.json` + `.dsh/task-*.json`，跨仓库零依赖、自包含。
 
+## 项目初始化（init）
+
+二开 / 遗留项目常常没有文档，AI 接手前需要先「认识」这个项目。`dev_task`（operation=init）生成项目根的 `AGENTS.md` 描述文件：
+
+1. `dev_task`（operation=init，不带 content）——读取现有 `AGENTS.md`（若有），返回给模型合并。
+2. 模型扫描项目（目录结构、技术栈、构建/运行命令、约定、红线），写成 `AGENTS.md` 全文。
+3. `dev_task`（operation=init，content=全文）——落盘前做**行数硬校验**（上限 200 行），超限拒绝并要求精简；若已存在 `AGENTS.md`，必须带 `overwrite: true` 才覆盖，防止裸覆盖手写约定。
+
+- **为什么是 `AGENTS.md`**：DSH 平台会把项目根的 `AGENTS.md` **自动注入到每个会话**——生成一次，之后每个任务开工 AI 都自带这份项目认知，引擎无需额外的注入逻辑。
+- **行数上限**：`AGENTS.md` 每次都进上下文，200 行（约 4–6K token）是硬约束，逼着只写「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」，而不是塞长篇文档。
+
 ## 状态与待办
 
 - **脚本级已验证**：strict `tsc` typecheck/build 零错误；`dsh plugin add` 装进独立实例、`--dump-config` 确认 `task-engine` 进组合树；`validateWorkflow`（配置校验）、`artifacts_present`（产物门）、`file_scope`（文件范围门）、`hooks/commit-msg`（机械门禁）单测/冒烟全过——非法配置逐条报错、产物没填全挡流转、范围外文件挡提交、钩子该放放该拦拦。
@@ -141,4 +158,12 @@ dsh plugin --profile <name> add .
 - **按预设激活（0.8.0）**：`dev_task` 工具与内置技能从 host 全局层拆到 agent 层。host 入口只挂 `task-engine` Remote 控制器 + 工作台 UI（`src/index.ts`）；新增 `src/agent.ts`（`./agent` 出品）、`src/dev-task.ts`、`src/shipped-skills.ts`，由预设的 `agent.cordis.yml` 命名后，在**该预设的 scope** 里注册工具与技能。实机 boot 验证：`standard` 会话工具目录不含 `dev_task`（26 个工具），加了 `@godv61/dsh-task-engine/agent` 行的 `eng` 会话含 `dev_task`（27 个工具）且描述正确，换回 `standard` 再次不含——切换预设即切换流程激活状态。
 - **一键激活（0.8.1）**：新增 `preset/enable.mjs`（bin: `dsh-task-engine-enable`），一条命令自动复制 `standard` → `eng`、把 persona 换成工程人设、追加 agent 行、写 `preset.yml`。persona 从「必须换」降级为「可选」——`eng-delivery` 技能自带 `whenToUse`，即使不加人设，模型遇到开发请求也自己加载技能走 `dev_task`；最简激活只剩「复制预设 + 追加一行 agent 行」。实机验证：脚本生成的 `eng` 预设挂载后 `dev_task` 可见、persona 以工程人设（含「铁律」）渲染、`standard` 仍无 `dev_task`。
 - **点选即用（0.9.0）**：host 入口新增 `src/seed-preset.ts`——首次启动自动把当前 `standard` 复制成 `eng` 预设（换工程人设 + 追加 agent 行，幂等、不覆盖手改）。装 bundle 重启后预设列表直接出现「工程化开发引擎」，点选即激活、切走即不激活，零复制/零编辑/零脚本。实机 boot 验证：boot 后 `.agent-presets/eng` 自动生成（agent 行 + 工程人设齐全）、roster 列出 `eng`（user）、`eng` 会话有 `dev_task` 且 persona 含「铁律」、`standard` 会话无 `dev_task`。
-- **工作台可用性（0.9.1）**：修复「新建 skill / 新建 rule」按钮点击不弹出表单（`formOpen` 只认编辑态，新建态缺少显式标志）；给六个守卫补 hover 说明、把「产物齐全」改名「产物字段已填全」并讲清「产物 = 阶段要写清楚的记录、字段 = 这份记录里必填的空」，「节点挂载」改名「阶段技能 / 规则」。
+- **工作台可用性（0.9.1）**：修复「新建 skill / 新建 rule」按钮点击不弹出表单（`formOpen` 只认编辑态，新建态缺少显式标志）；给六个守卫补 hover 说明、把「产物齐全」改名「产物字段已填全」并讲清「产物 = 阶段要写清楚的记录、字段 = 这份记录里必填的空」，「节点挂载」改名「阶段技能 / 规则」。
+- **需求/方案人工确认门（0.10.0）**：`requirement_confirmation` / `solution_confirmation` 两个守卫从「模型自己标记」升级为「人来批准」。走 `advance` 撞上确认门时，`dev_task` 用 `@deepseek-ai/dsh-user-approval` 发起审批；人在页面点「允许」才放行，模型不能自己确认、也不能绕过。headless e2e 验证真模型全流程时两个确认都会触发。
+- **派工 / 审核审计（0.11.0）**：`TaskItem` 新增 `dispatch`（子代理派工留痕）与 `review`（spec / quality 两阶段评审）字段；`dev_task` 新增 `dispatch`、`review_item` 操作；工作台新增「任务台账」视图展示逐项审计。派工留痕是软约束——模型可自己实现小项而不强制派子代理。
+- **台账硬门 + 软约束修复（0.12.0）**：`todos_done` 守卫改为「实施项非空且全部 done」；`code-implement` 技能里写清「两阶段都 pass 才标 done」。
+- **两阶段评审硬门（0.13.0）**：`todos_done` 进一步收紧——每个 done 的 item 必须带 spec + quality 都 pass 的评审记录，缺评审或任一阶段 fail 都会挡住「开发 → 交付」，并以具体 item 报出阻塞原因（`todosBlockers`）。派工审计保持软约束。
+- **skill / rule 查看 + 删除（0.14.0）**：内置 skill/rule 从「只读不可见」改为「可查看正文」；自建（项目/用户）skill/rule 新增删除（两步确认）。删改在类型层即把 `bundled` 排除，内置资源永不误删。
+- **弹窗 + markdown 查看（0.15.0）**：skill/rule 的查看与编辑从内联卡片改为居中宽弹窗；查看时正文用 DSH 自带的 `MarkdownText` 渲染成 markdown 富文本（不引入任何新依赖），编辑时正文保持纯文本。
+- **流程预设收敛（0.16.0）**：把「自由编辑阶段图/守卫/产物/提交规则/验证开关」收敛为「选一套内置流程预设 + 给节点挂 skill/rule」。新增 `src/workflows.ts` 内置 `standard` / `agile` / `minimal` 三套流程（阶段图、守卫、产物字段、提交规则、验证证据开关全部固化）；`.dsh/eng.json` 从完整配置精简为 `{ flow, stage_bindings }`；工作台删掉流转/产物/提交规则/验证开关编辑 UI，只剩「流程预设 + 流程节点（只读）+ 阶段技能/规则」；git 提交钩子同步按 `flow` 选预设。
+- **项目初始化 + 语言无关内置规则（0.17.0）**：`dev_task` 新增 `init` 操作，生成项目根 `AGENTS.md`（DSH 每会话自动注入），落盘前做 200 行硬校验、已存在需 `overwrite` 才覆盖；内置 `solution-design` / `coding-conventions` / `security-redlines` 去掉 Java 专属概念（Impl / DTO / VO、Controller / Mapper），改成语言中立骨架，语言特定规范交给项目自建 rule。

package/defaults/eng.json

@@ -1,26 +1,5 @@
 {
-  "stages": ["需求评审", "设计", "开发", "交付", "代码审核", "完成"],
-  "start_stage": "需求评审",
-  "transitions": [
-    { "from": "需求评审", "to": "设计", "requires": ["requirement_confirmation", "artifacts_present"] },
-    { "from": "设计", "to": "开发", "requires": ["solution_confirmation", "artifacts_present"] },
-    { "from": "开发", "to": "交付", "requires": ["todos_done"] },
-    { "from": "交付", "to": "代码审核", "requires": ["verified"] },
-    { "from": "代码审核", "to": "完成", "requires": ["review_passed", "artifacts_present"] }
-  ],
-  "artifacts": [
-    { "stage": "需求评审", "id": "requirement", "name": "需求说明", "fields": ["scope", "acceptance_criteria"] },
-    { "stage": "设计", "id": "design", "name": "设计文档", "fields": ["approach", "risks", "impact"] },
-    { "stage": "代码审核", "id": "review", "name": "评审记录", "fields": ["conclusion", "issues"] }
-  ],
-  "commit": {
-    "policy": "task",
-    "message_pattern": "^【(\\S+)】【(?:TASK|T\\d+)】.+",
-    "message_hint": "【<module>】【TASK/T1】说明 —— 写结果，不写空泛动作",
-    "checkpoints": ["交付"],
-    "file_scope": true
-  },
-  "high_risk_requires_verification": true,
+  "flow": "standard",
   "stage_bindings": {
     "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
     "设计": { "skills": ["solution-design"] },

package/docs/manual.html

@@ -0,0 +1,353 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>工程化交付引擎 使用手册</title>
+  <style>
+    :root {
+      --ink:#16232d; --muted:#5f6f78; --paper:#f5f7fa; --card:#fff;
+      --line:#dce3ee; --brand:#1d4ed8; --dark:#1e3a8a; --soft:#e7edfb;
+      --amber:#9a5a00; --amber-soft:#fff2d8; --red:#9d302f; --red-soft:#fbe7e5;
+      --shadow:0 16px 42px rgba(20,40,80,.08);
+    }
+    *{box-sizing:border-box} html{scroll-behavior:smooth}
+    body{margin:0;color:var(--ink);background:radial-gradient(circle at 90% 0,rgba(59,130,246,.10),transparent 30rem),var(--paper);font-family:"Microsoft YaHei","PingFang SC",system-ui,sans-serif;line-height:1.75}
+    a{color:var(--brand);text-decoration-thickness:1px;text-underline-offset:3px}
+    code,pre{font-family:Consolas,"Cascadia Code",monospace} code{padding:.1rem .35rem;border-radius:.35rem;background:#edf1f6;color:#24415c}
+    pre{margin:1rem 0;padding:1rem 1.1rem;overflow:auto;color:#ecf3ff;background:#12233f;border-radius:.75rem;line-height:1.6} pre code{padding:0;color:inherit;background:transparent}
+    h1,h2,h3{line-height:1.3} h2{margin-top:0;font-size:1.6rem} h3{margin-top:1.5rem;color:var(--dark)}
+    .hero{color:#fff;background:linear-gradient(125deg,#0f2f66,#1d4ed8 58%,#3b82f6);padding:3.5rem max(1.25rem,calc((100vw - 1180px)/2))}
+    .hero .eyebrow{margin:0 0 .5rem;letter-spacing:.14em;opacity:.72}.hero h1{margin:0;font-size:clamp(2rem,5vw,3.2rem)}.hero .lead{max-width:880px;margin:1rem 0;font-size:1.08rem;opacity:.92}
+    .badges,.flow{display:flex;flex-wrap:wrap;gap:.55rem;align-items:center}.badge{padding:.25rem .7rem;border:1px solid rgba(255,255,255,.3);border-radius:999px;background:rgba(255,255,255,.1);font-size:.88rem}
+    .layout{display:grid;grid-template-columns:250px minmax(0,900px);gap:2rem;width:min(1180px,calc(100% - 2rem));margin:2rem auto 4rem;align-items:start}
+    nav{position:sticky;top:1rem;padding:1rem;border:1px solid var(--line);border-radius:1rem;background:rgba(255,255,255,.92);box-shadow:var(--shadow)}nav strong{display:block;margin-bottom:.55rem;color:var(--dark)}nav a{display:block;padding:.35rem .45rem;border-radius:.45rem;text-decoration:none}nav a:hover{background:var(--soft)}
+    main{min-width:0}section{margin-bottom:1.35rem;padding:clamp(1.2rem,3vw,2rem);border:1px solid var(--line);border-radius:1rem;background:var(--card);box-shadow:var(--shadow)}
+    .cards{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:1rem}.card{padding:1rem;border:1px solid var(--line);border-radius:.75rem;background:#fbfcfe}.card h3{margin:0 0 .35rem;font-size:1rem}.card p{margin:.25rem 0;color:var(--muted)}
+    .callout{margin:1rem 0;padding:.9rem 1rem;border-left:.3rem solid var(--brand);border-radius:.3rem .7rem .7rem .3rem;background:var(--soft)}.callout.warn{border-color:var(--amber);background:var(--amber-soft)}.callout.danger{border-color:var(--red);background:var(--red-soft)}
+    .flow span{padding:.4rem .65rem;border-radius:.55rem;background:var(--soft);color:var(--dark);font-weight:700}.flow i{color:var(--muted);font-style:normal}
+    .table-wrap{overflow-x:auto}table{width:100%;border-collapse:collapse;font-size:.94rem}th,td{padding:.7rem .75rem;border:1px solid var(--line);vertical-align:top;text-align:left}th{color:var(--dark);background:#edf2fb}tbody tr:nth-child(even){background:#fafbfe}
+    ul,ol{padding-left:1.35rem}li+li{margin-top:.3rem}details{margin:.65rem 0;border:1px solid var(--line);border-radius:.65rem;background:#fbfcfe}summary{cursor:pointer;padding:.8rem 1rem;color:var(--dark);font-weight:700}details>div{padding:0 1rem 1rem}.stamp{margin-top:2rem;color:var(--muted);font-size:.9rem}
+    @media(max-width:850px){.layout{display:block}nav{position:static;margin-bottom:1rem;columns:2}nav strong{column-span:all}}@media(max-width:620px){.cards{grid-template-columns:1fr}nav{columns:1}.hero{padding-top:2.5rem;padding-bottom:2.5rem}}@media print{body{background:#fff}.hero{padding:1.5rem;print-color-adjust:exact}.layout{display:block;width:100%;margin:1rem 0}nav{display:none}section{box-shadow:none;break-inside:avoid}}
+  </style>
+</head>
+<body>
+  <header class="hero">
+    <p class="eyebrow">DSH · ENGINEERING DELIVERY ENGINE</p>
+    <h1>工程化交付引擎 使用手册</h1>
+    <p class="lead">这是一套装在 DeepSeek Harness 里的工程流程约束。它把「需求评审 → 设计 → 开发 → 交付 → 代码审核」做成硬门槛：阶段不能跳、关键节点必须人来拍板、验证和提交都被机械检查。团队只选一套流程，再给每个节点挂上合适的 skill 和 rule。</p>
+    <div class="badges">
+      <span class="badge">选流程预设即可</span>
+      <span class="badge">standard / agile / minimal</span>
+      <span class="badge">需求、方案人工确认</span>
+      <span class="badge">范围受控本地提交</span>
+      <span class="badge">按预设激活</span>
+    </div>
+  </header>
+
+  <div class="layout">
+    <nav aria-label="目录">
+      <strong>目录</strong>
+      <a href="#overview">1. 工作原理</a>
+      <a href="#install">2. 安装与启用</a>
+      <a href="#structure">3. 文件与目录</a>
+      <a href="#flows">4. 三套流程预设</a>
+      <a href="#skills">5. Skills</a>
+      <a href="#rules">6. Rules</a>
+      <a href="#configure">7. 配置流程与挂载</a>
+      <a href="#init">8. 项目初始化（init）</a>
+      <a href="#start">9. 如何开始一个任务</a>
+      <a href="#run">10. 流程如何逐阶段执行</a>
+      <a href="#state">11. 任务状态如何记录进度</a>
+      <a href="#verify">12. 验证、评审与提交</a>
+      <a href="#example">13. 一个标准任务的完整走查</a>
+      <a href="#boundaries">14. 边界与常见问题</a>
+    </nav>
+
+    <main>
+      <section id="overview">
+        <h2>1. 工作原理</h2>
+        <p>开发者在「工程化开发引擎」会话里提出开发请求后，统一由 <code>dev_task</code> 工具接管，再由编排技能 <code>eng-delivery</code> 读任务状态、按当前阶段推进，一个阶段一个阶段地走。</p>
+        <pre><code>开发请求
+  → dev_task（统一入口，硬约束在代码里执行）
+  → eng-delivery（编排：读状态 → 选阶段 → 推进）
+      → 需求评审 · requirement-analysis
+      → 设计     · solution-design
+      → 开发     · code-implement
+      → 交付     · code-verify + code-commit
+      → 代码审核 · code-review</code></pre>
+        <div class="callout">
+          <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时，才触发 <code>dev_task</code> 和这套门禁；换到别的预设，流程完全不介入。</p>
+        </div>
+        <p>三样东西分工明确：<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」，<strong>Skill</strong> 决定「这一站做什么」，<strong>Rule</strong> 决定「这一站守什么」。任务状态单独落盘，负责「跨会话恢复到哪一步」。</p>
+      </section>
+
+      <section id="install">
+        <h2>2. 安装与启用</h2>
+        <h3>先装 DSH（二选一）</h3>
+        <pre><code># 方式 A：npm 一条命令（需要 Node.js ≥ 22）
+npx @deepseek-ai/dsh web
+
+# 方式 B：从源码 clone
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
+        <h3>再装引擎插件</h3>
+        <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
+        <p>重启 Web 后自动完成两件事：侧边栏多出「工程流程」工作台；预设列表多出「工程化开发引擎」。</p>
+        <h3>启用</h3>
+        <p>新建会话 → 预设选「工程化开发引擎」。这个会话就挂上 <code>dev_task</code> + 内置技能 + 工程人设，开始按流程走。</p>
+        <div class="callout"><p>想「正式开发」就选它；想「让 AI 自由探索」就选 <code>standard</code>。切换预设本身就是开关，零配置。</p></div>
+      </section>
+
+      <section id="structure">
+        <h2>3. 文件与目录</h2>
+        <pre><code>D:\workspace\
+├─ AGENTS.md       ← init 生成的项目描述（DSH 每会话自动注入）
+├─ .dsh\
+│  ├─ eng.json       ← 流程预设 + 节点挂载（团队共享，可进 git）
+│  ├─ skills\        ← 项目级 skill
+│  ├─ rules\         ← 项目级 rule
+│  └─ task-*.json    ← 每个任务的状态快照
+└─ $DSH_HOME\
+   ├─ skills\        ← 用户级 skill（个人所有项目通用）
+   └─ rules\         ← 用户级 rule</code></pre>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>路径</th><th>作用</th><th>何时读取或修改</th></tr></thead>
+            <tbody>
+              <tr><td><code>.dsh/eng.json</code></td><td>声明用哪套流程 + 每个节点挂哪些 skill / rule</td><td>任务推进前读取；工作台保存时写入</td></tr>
+              <tr><td><code>.dsh/skills/</code></td><td>项目级 skill（团队共享）</td><td>节点挂载命中时按需读取</td></tr>
+              <tr><td><code>.dsh/rules/</code></td><td>项目级 rule（团队共享）</td><td>节点挂载命中时按需读取</td></tr>
+              <tr><td><code>.dsh/task-*.json</code></td><td>当前任务的有效状态快照</td><td>确认、实施、验证、评审、切换阶段时更新</td></tr>
+              <tr><td><code>$DSH_HOME/skills/ · rules/</code></td><td>用户级 skill / rule</td><td>同名时优先于项目级、内置</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section id="flows">
+        <h2>4. 三套流程预设</h2>
+        <p>阶段图、守卫、提交规则都随预设固化好，团队只选一套，不改流程图。</p>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>预设</th><th>阶段顺序</th><th>适用</th><th>守卫强度</th></tr></thead>
+            <tbody>
+              <tr><td><code>standard</code> 标准研发</td><td>需求评审 → 设计 → 开发 → 交付 → 代码审核 → 完成</td><td>默认；流程最完整</td><td>含产物门 + 人工确认 + 评审门</td></tr>
+              <tr><td><code>agile</code> 敏捷轻量</td><td>需求 → 开发 → 交付 → 审查</td><td>快速迭代、少产物</td><td>四阶段，产物要求更轻</td></tr>
+              <tr><td><code>minimal</code> 纯代码</td><td>开发 → 交付</td><td>只有代码、无评审流程</td><td>只留提交门禁</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div class="callout warn">
+          <p>预设之外，单个任务还有两个模型自动判断的字段：<code>work_size</code>（tiny / standard / complex，决定拆多细）和 <code>risk_level</code>（standard / high_risk，决定验证强度）。它们不是流程档位，是单个任务的规模与风险标签。</p>
+        </div>
+      </section>
+
+      <section id="skills">
+        <h2>5. Skills：这一步做什么</h2>
+        <p>每个内置 Skill 尺寸很小、只做一件事。挂到对应节点后，走到那一步才加载，不会一次性全塞给模型。</p>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>Skill</th><th>职责</th><th>不负责</th></tr></thead>
+            <tbody>
+              <tr><td><code>eng-delivery</code></td><td>读任务状态、按阶段推进、确保不越轨</td><td>代替各阶段 Skill 的专业工作</td></tr>
+              <tr><td><code>requirement-analysis</code></td><td>目标、验收、非目标，落需求说明，等人确认</td><td>编码</td></tr>
+              <tr><td><code>solution-design</code></td><td>最小方案、技术基线、改动点，落设计文档</td><td>实现</td></tr>
+              <tr><td><code>code-implement</code></td><td>实现、做「规格 + 质量」两阶段评审，都过才标完成</td><td>无关重构</td></tr>
+              <tr><td><code>code-verify</code></td><td>按验收与风险验证、记录证据（高风险必须带证据）</td><td>掩盖失败或自动修复</td></tr>
+              <tr><td><code>code-commit</code></td><td>校验阶段、范围、消息格式后提交</td><td>远程 push / 合并 / 发布</td></tr>
+              <tr><td><code>code-review</code></td><td>评审变更，落结论与问题清单</td><td>代替实现或验证</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section id="rules">
+        <h2>6. Rules：这一步守什么</h2>
+        <p>Rule 是纯正文的约束，只有挂在节点上、且走到那一步时才读。内置三条：</p>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>Rule</th><th>约束内容</th><th>典型触发</th></tr></thead>
+            <tbody>
+              <tr><td><code>coding-conventions</code></td><td>编码规范：复用优先、禁空 catch、禁全表更新等</td><td>写代码</td></tr>
+              <tr><td><code>commit-conventions</code></td><td>提交消息格式、只提交任务内文件、禁止 push / 合并 / 发布</td><td>本地提交</td></tr>
+              <tr><td><code>security-redlines</code></td><td>敏感数据、危险动作和权限边界</td><td>所有写操作</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p>最重要的轻量原则：团队想改「提交消息格式」「交付要自测」这类约定，直接覆盖对应 rule / skill 的正文，而不是改一堆参数。</p>
+      </section>
+
+      <section id="configure">
+        <h2>7. 配置流程与挂载</h2>
+        <p>侧边栏点「工程流程」打开工作台，三个标签页：<strong>流程配置 / 技能 skill / 规则 rule</strong>。日常只需在「流程配置」页做两件事：</p>
+        <ol>
+          <li><strong>选流程预设</strong>：standard / agile / minimal 点一下即切。</li>
+          <li><strong>给节点挂 skill / rule</strong>：先选一个节点（如「开发」），再勾选它用什么 skill、守哪条 rule，保存。</li>
+        </ol>
+        <p>「技能」「规则」页支持新建 / 查看 / 编辑 / 删除：内置资源只读（正文以 markdown 富文本渲染）；项目级 / 用户级资源可编辑、可删除（两步确认）。</p>
+        <pre><code>// .dsh/eng.json 等价内容
+{
+  "flow": "standard",
+  "stage_bindings": {
+    "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
+    "开发":     { "skills": ["code-implement"],        "rules": ["coding-conventions"] }
+  }
+}</code></pre>
+        <div class="callout warn"><p>页面实时校验：挂到不存在的阶段、空名等会红字提示并置灰保存；保存前主机再校验一遍。错误的配置存不进去。</p></div>
+        <p>三层来源与优先级：同名 skill / rule，<strong>项目级 &gt; 用户级 &gt; 内置</strong>。想改内置某条，新建同名项目级版本即可顶替，内置留着兜底。</p>
+      </section>
+
+      <section id="init">
+        <h2>8. 项目初始化（init）</h2>
+        <p>二开 / 遗留项目没有文档时，先让 AI 给项目建一份「描述文件」——项目根的 <code>AGENTS.md</code>。DSH 平台会把它<b>自动注入到每个会话</b>，生成一次，之后每个任务开工 AI 都自带这份项目认知。</p>
+        <div class="callout"><p><strong>什么时候用：</strong>接手一个 AI 还不认识的项目（尤其二次开发的遗留代码）时，先跑一次 init 摸底；全新项目或 AI 已熟悉时可跳过。</p></div>
+        <ol>
+          <li>对 AI 说「帮我初始化这个项目」；AI 扫目录结构、技术栈、构建 / 运行命令、约定与红线。</li>
+          <li>AI 写成 <code>AGENTS.md</code>，通过 <code>dev_task</code>（operation=init）落盘。</li>
+          <li>落盘前硬校验<b>行数 ≤ 200 行</b>——超了必须精简到「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」，只留骨架不塞长文。</li>
+          <li>已有 <code>AGENTS.md</code> 时，引擎拒绝裸覆盖，必须先读回、合并后再带 <code>overwrite</code> 重写，保护手写约定。</li>
+        </ol>
+        <pre><code>项目根/
+├─ AGENTS.md          ← init 生成，DSH 每会话自动注入
+└─ .dsh/
+   ├─ eng.json
+   ├─ skills/ · rules/
+   └─ task-*.json</code></pre>
+      </section>
+
+      <section id="start">
+        <h2>9. 如何开始一个任务</h2>
+        <ol>
+          <li>新建会话，预设选「工程化开发引擎」。</li>
+          <li>直接描述需求（加功能 / 修 bug）。</li>
+          <li>AI 建任务、判 <code>work_size</code> 与 <code>risk_level</code>，停在起始阶段（标准流程是「需求评审」）。</li>
+          <li>AI 落需求说明，需要拍板处发起审批，你点「允许」才进入下一步。</li>
+          <li>之后一个阶段一个阶段推进，直到「完成」。</li>
+        </ol>
+        <div class="flow">
+          <span>说需求</span><i>→</i><span>建任务</span><i>→</i><span>需求评审</span><i>→</i><span>设计</span><i>→</i><span>开发</span><i>→</i><span>交付</span><i>→</i><span>代码审核</span><i>→</i><span>完成</span>
+        </div>
+      </section>
+
+      <section id="run">
+        <h2>10. 流程如何逐阶段执行</h2>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>阶段</th><th>AI 在这一站做什么</th><th>过关条件（不满足不让走）</th></tr></thead>
+            <tbody>
+              <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全，且<b>人点「允许」确认需求</b></td></tr>
+              <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全，且<b>人点「允许」确认方案</b></td></tr>
+              <tr><td>开发</td><td>逐项实现，每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done（每项带两阶段评审）</td></tr>
+              <tr><td>交付</td><td>验证、记证据，按门禁提交</td><td>验证通过（高风险必须带证据）</td></tr>
+              <tr><td>代码审核</td><td>评审变更，落「评审记录」</td><td>结论通过且字段填全</td></tr>
+              <tr><td>完成</td><td>收尾</td><td>—</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <h3>贯穿全程的硬规则</h3>
+        <ul>
+          <li>阶段是硬状态：status 说你在哪，就只做那一步，绝不倒带重走、绝不跳。</li>
+          <li>确认只能人来做：需求确认、方案确认由 AI 发起审批，你在页面点「允许」；AI 不能自己通过、不能绕过。</li>
+          <li>渐进披露：走到哪个阶段，才加载那一段的 skill / rule。</li>
+        </ul>
+      </section>
+
+      <section id="state">
+        <h2>11. 任务状态如何记录进度</h2>
+        <p>每个任务一份 <code>.dsh/task-*.json</code>，只保存当前有效状态，不保存聊天全文和流水日志。</p>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>字段</th><th>含义</th></tr></thead>
+            <tbody>
+              <tr><td><code>id / title</code></td><td>任务标识与标题</td></tr>
+              <tr><td><code>branch</code></td><td>所属功能分支；恢复时以真实当前分支为准</td></tr>
+              <tr><td><code>stage</code></td><td>当前阶段（决定下一步做什么、能往哪走）</td></tr>
+              <tr><td><code>work_size</code></td><td>tiny / standard / complex，决定拆多细</td></tr>
+              <tr><td><code>risk_level</code></td><td>standard / high_risk，决定验证强度</td></tr>
+              <tr><td><code>requirement_confirmed</code></td><td>需求是否已由人确认</td></tr>
+              <tr><td><code>solution_confirmed</code></td><td>方案是否已由人确认</td></tr>
+              <tr><td><code>verification</code></td><td>验证是否通过 + 证据</td></tr>
+              <tr><td><code>review</code></td><td>评审结论（通过 / 未过 + 问题）</td></tr>
+              <tr><td><code>files</code></td><td>本任务允许修改的文件范围</td></tr>
+              <tr><td><code>commits</code></td><td>已创建的提交记录</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p>会话断了没关系：重新开会话，AI 读 <code>stage</code>、确认态、验证与评审字段，就能从断点继续，不依赖上一轮聊天。</p>
+      </section>
+
+      <section id="verify">
+        <h2>12. 验证、评审与提交</h2>
+        <h3>验证为什么不该总那么慢</h3>
+        <ul>
+          <li>实施中优先受影响模块的编译、目标测试与静态检查。</li>
+          <li>差异没变时复用有效证据，不重复跑相同命令。</li>
+          <li>无法联调外部系统时必须如实写「未联调」，不能把编译成功说成功能通过。</li>
+          <li><code>high_risk</code> 任务过验证门必须附证据。</li>
+        </ul>
+        <h3>评审</h3>
+        <p>开发阶段每项做「规格 + 质量」两阶段评审，都 pass 才标 done；缺评审或任一阶段 fail 会挡住「开发 → 交付」。</p>
+        <h3>提交策略</h3>
+        <div class="table-wrap">
+          <table>
+            <thead><tr><th>策略</th><th>何时提交</th><th>标识</th></tr></thead>
+            <tbody>
+              <tr><td><code>task</code></td><td>整项验证、评审通过后一次提交</td><td><code>TASK</code></td></tr>
+              <tr><td><code>item</code></td><td>每个独立项验证后提交；整项完成再提最终状态</td><td><code>Tn</code>，最终 <code>TASK</code></td></tr>
+              <tr><td><code>manual</code></td><td>等用户明确要求才提交</td><td>用户指定</td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p>提交消息要求 <code>【模块】【TASK】做了什么</code>，且只提交任务 <code>files</code> 范围内的文件。要彻底封死模型绕过 <code>dev_task</code> 直接 <code>git commit</code>，给仓库装一道机械钩子：</p>
+        <pre><code>dev_task operation=install_hook   # 装入 .git/hooks/commit-msg，装上后任何 git commit 都被同一套规则校验</code></pre>
+      </section>
+
+      <section id="example">
+        <h2>13. 一个标准任务的完整走查</h2>
+        <p>假设需求是「给现有查询接口加一个权限校验」。标准流程下，关键决策点应接近下面这样：</p>
+        <pre><code>flow: standard          // 项目预设
+work_size: standard     // 数个文件 + 权限判断
+risk_level: high_risk   // 涉及鉴权，验证要加证据
+
+① 需求评审
+   - 目标：无权限返回 403；有权限正常返回。
+   - 验收、非目标写清 → 【人确认需求】
+
+② 设计
+   - 最小方案：Controller 加校验、Service 复用现有鉴权方法。
+   - 不新建接口 / DTO / 异常包装 → 【人确认方案】
+
+③ 开发
+   - T1：接口加校验 + 编写无权限 / 有权限用例。
+   - 规格 ✓ 质量 ✓ → done
+
+④ 交付
+   - 验证：跑鉴权用例，记录通过证据（high_risk 必须）。
+   - 提交：【模块】【TASK】查询接口增加权限校验（只含本任务文件）
+
+⑤ 代码审核
+   - 结论：通过 · 问题：无
+
+⑥ 完成</code></pre>
+        <p>这类任务不应因为「以后可能复用」扩展成多层架构，也不应把推荐项自动当成验收条件。</p>
+      </section>
+
+      <section id="boundaries">
+        <h2>14. 边界与常见问题</h2>
+        <div class="callout danger">
+          <p>引擎只允许：读取仓库事实、修改<b>已确认任务范围内</b>的文件、按策略创建<b>范围受控的本地提交</b>。远程 push / 合并 / 发布、数据库写入，需人单独决定。</p>
+        </div>
+        <details open><summary>切换预设就是开关吗？</summary><div>是。选「工程化开发引擎」才挂 <code>dev_task</code> 和内置技能；选 <code>standard</code> 等其它预设则完全不介入。</div></details>
+        <details><summary>想改内置 skill / rule 怎么办？</summary><div>不删内置（升级又回来）。新建一个<b>同名</b>的项目级 skill / rule，系统自动用你这份，内置留着兜底。</div></details>
+        <details><summary>任务文档要不要提交？</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实，随分支提交；忽略它别人只能看到代码，看不到确认内容和进度。</div></details>
+        <details><summary>一个会话能同时做两个需求吗？</summary><div>一个任务对应一份状态文档、一个分支。新需求保存当前进度后切新分支，切回原分支即可恢复。</div></details>
+        <details><summary>提交被拒是怎么回事？</summary><div>通常是四类：没建 dev_task 任务、阶段没到提交检查点、消息格式不符、提交文件不在任务范围内。按拒绝原因修正即可。</div></details>
+        <details><summary>「完成」等于上线了吗？</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过；上线、合并、发布需人另行决定。</div></details>
+        <p class="stamp">当前结构基线：三套流程预设 · 最后更新：2026-08-26</p>
+      </section>
+    </main>
+  </div>
+</body>
+</html>