@godv61/dsh-task-engine 0.27.1 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/.acceptance.mjs +11 -11
  2. package/.adaptive-test.mjs +189 -0
  3. package/.assessment-batch1.mjs +14 -14
  4. package/.codex-project-test.mjs +80 -80
  5. package/.enforce-test.mjs +12 -12
  6. package/.evidence-test.mjs +8 -8
  7. package/.filter-test.mjs +6 -6
  8. package/.freeze-test.mjs +44 -44
  9. package/.hook-test.mjs +19 -2
  10. package/.p0-test.mjs +21 -21
  11. package/.preset-test.mjs +11 -1
  12. package/.revision-test.mjs +16 -16
  13. package/.roundtrip-test.mjs +247 -247
  14. package/.workflow-test.mjs +122 -120
  15. package/README.md +33 -27
  16. package/cordis.patch.yml +158 -9
  17. package/docs/CHANGELOG.md +44 -30
  18. package/docs/README.md +6 -5
  19. package/docs/adaptive-workflows.md +72 -0
  20. package/docs/configuration.md +25 -25
  21. package/docs/development.md +1 -1
  22. package/docs/faq.md +14 -6
  23. package/docs/getting-started.md +8 -5
  24. package/docs/manual-legacy.html +380 -0
  25. package/docs/manual.html +124 -378
  26. package/docs/resource-install.md +5 -5
  27. package/docs/roadmap.md +8 -9
  28. package/hooks/commit-msg +39 -22
  29. package/lib/adaptive.d.ts +15 -0
  30. package/lib/adaptive.js +54 -0
  31. package/lib/adaptive.js.map +1 -0
  32. package/lib/client.js +719 -433
  33. package/lib/client.js.map +3 -3
  34. package/lib/controller.d.ts +50 -0
  35. package/lib/controller.js +132 -0
  36. package/lib/controller.js.map +1 -1
  37. package/lib/dev-task.js +413 -18
  38. package/lib/dev-task.js.map +1 -1
  39. package/lib/engine.d.ts +20 -0
  40. package/lib/engine.js +4 -1
  41. package/lib/engine.js.map +1 -1
  42. package/lib/hook.js +50 -29
  43. package/lib/hook.js.map +1 -1
  44. package/lib/project-init.d.ts +23 -0
  45. package/lib/project-init.js +94 -0
  46. package/lib/project-init.js.map +1 -0
  47. package/lib/skill-audit.js +8 -7
  48. package/lib/skill-audit.js.map +1 -1
  49. package/lib/sonar.d.ts +33 -0
  50. package/lib/sonar.js +80 -0
  51. package/lib/sonar.js.map +1 -0
  52. package/package.json +15 -16
  53. package/preset/agent.cordis.yml +3 -3
  54. package/preset/enable.mjs +2 -2
  55. package/preset/persona.md +4 -2
  56. package/scripts/verify-package.mjs +9 -5
  57. package/skills/architecture-design/SKILL.md +11 -0
  58. package/skills/code-development/SKILL.md +11 -0
  59. package/skills/code-review/SKILL.md +11 -0
  60. package/skills/eng-delivery/SKILL.md +19 -15
  61. package/skills/requirements-analysis/SKILL.md +11 -0
  62. package/skills/task-orchestration/SKILL.md +11 -0
  63. package/skills/test-validation/SKILL.md +11 -0
@@ -0,0 +1,380 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>工程化交付引擎 使用手册</title>
7
+ <style>
8
+ :root {
9
+ --ink:#16232d; --muted:#5f6f78; --paper:#f5f7fa; --card:#fff;
10
+ --line:#dce3ee; --brand:#1d4ed8; --dark:#1e3a8a; --soft:#e7edfb;
11
+ --amber:#9a5a00; --amber-soft:#fff2d8; --red:#9d302f; --red-soft:#fbe7e5;
12
+ --shadow:0 16px 42px rgba(20,40,80,.08);
13
+ }
14
+ *{box-sizing:border-box} html{scroll-behavior:smooth}
15
+ 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}
16
+ a{color:var(--brand);text-decoration-thickness:1px;text-underline-offset:3px}
17
+ code,pre{font-family:Consolas,"Cascadia Code",monospace} code{padding:.1rem .35rem;border-radius:.35rem;background:#edf1f6;color:#24415c}
18
+ 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}
19
+ h1,h2,h3{line-height:1.3} h2{margin-top:0;font-size:1.6rem} h3{margin-top:1.5rem;color:var(--dark)}
20
+ .hero{color:#fff;background:linear-gradient(125deg,#0f2f66,#1d4ed8 58%,#3b82f6);padding:3.5rem max(1.25rem,calc((100vw - 1180px)/2))}
21
+ .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}
22
+ .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}
23
+ .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}
24
+ 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)}
25
+ 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)}
26
+ .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)}
27
+ .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)}
28
+ .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}
29
+ .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}
30
+ 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}
31
+ @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}}
32
+ </style>
33
+ </head>
34
+ <body>
35
+ <header class="hero">
36
+ <p class="eyebrow">DSH · ENGINEERING DELIVERY ENGINE</p>
37
+ <h1>工程化交付引擎 使用手册</h1>
38
+ <p class="lead">历史手册:本页保留旧版三流程的操作说明。四档任务流程、元技能和可选 SonarQube 说明请阅读 <a href="manual.html" style="color:#fff">现行 HTML 手册</a>。</p>
39
+ <div class="badges">
40
+ <span class="badge">流程与工作方法分离</span>
41
+ <span class="badge">standard / agile / minimal</span>
42
+ <span class="badge">需求、方案人工确认</span>
43
+ <span class="badge">范围受控本地提交</span>
44
+ <span class="badge">按预设激活</span>
45
+ </div>
46
+ </header>
47
+
48
+ <div class="layout">
49
+ <nav aria-label="目录">
50
+ <strong>目录</strong>
51
+ <a href="https://github.com/godv61/dsh-task-engine#readme">项目首页 ↗</a>
52
+ <a href="#overview">1. 工作原理</a>
53
+ <a href="#install">2. 安装与启用</a>
54
+ <a href="#structure">3. 文件与目录</a>
55
+ <a href="#flows">4. 三套流程预设</a>
56
+ <a href="#skills">5. Skills</a>
57
+ <a href="#rules">6. Rules</a>
58
+ <a href="#configure">7. 配置流程与挂载</a>
59
+ <a href="#init">8. 项目初始化(init)</a>
60
+ <a href="#start">9. 如何开始一个任务</a>
61
+ <a href="#run">10. 流程如何逐阶段执行</a>
62
+ <a href="#state">11. 任务状态如何记录进度</a>
63
+ <a href="#verify">12. 验证、评审与提交</a>
64
+ <a href="#example">13. 一个标准任务的完整走查</a>
65
+ <a href="#boundaries">14. 边界与常见问题</a>
66
+ </nav>
67
+
68
+ <main>
69
+ <section id="overview">
70
+ <h2>1. 工作原理</h2>
71
+ <p>开发者在「工程化开发引擎」会话里提出开发请求后,统一由 <code>dev_task</code> 工具接管,再由编排技能 <code>eng-delivery</code> 读任务状态、按当前阶段推进,一个阶段一个阶段地走。</p>
72
+ <pre><code>开发请求
73
+ → dev_task(统一入口,硬约束在代码里执行)
74
+ → eng-delivery(编排:读状态 → 选阶段 → 推进)
75
+ → 按所选流程进入当前阶段
76
+ → 读取该阶段由使用者绑定的技能和规则
77
+ → 检查门禁并推进到下一阶段</code></pre>
78
+ <div class="callout">
79
+ <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时,才触发 <code>dev_task</code> 和这套门禁;换到别的预设,流程完全不介入。</p>
80
+ </div>
81
+ <p>三样东西分工明确:<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」,<strong>Skill</strong> 决定「这一站做什么」,<strong>Rule</strong> 归属技能,决定该技能遵守什么。任务状态单独落盘,负责「跨会话恢复到哪一步」。推荐配置需要显式采用;采用后完全由使用者增删修改。</p>
82
+ <div class="callout warn">
83
+ <p><strong>诚实边界:</strong>阶段流转、文件范围、任务绑定、流程快照 hash、钩子完整性、敏感路径风险策略是<b>代码硬校验</b>;提交格式仅在用户配置后校验。高风险任务的验证依据真实命令回执。审核结论、实施项完成及回执命令的覆盖面仍需人工或 CI 判断;需求确认、方案确认和风险降级由人工批准。</p>
84
+ </div>
85
+ </section>
86
+
87
+ <section id="install">
88
+ <h2>2. 安装与启用</h2>
89
+ <h3>2.1 前置:Node.js ≥ 22 + pnpm</h3>
90
+ <pre><code>npm install -g pnpm # dsh 的 plugin 子命令底层转发给 pnpm,必须先装</code></pre>
91
+ <h3>2.2 先装 DSH(三选一)</h3>
92
+ <pre><code># 方式 A:npm 装 CLI(非源码,推荐给使用者)
93
+ npm install -g @deepseek-ai/dsh
94
+ dsh web
95
+
96
+ # 方式 B:npx 免安装直接跑
97
+ npx @deepseek-ai/dsh web
98
+
99
+ # 方式 C:从源码 clone(开发者)
100
+ git clone https://github.com/deepseek-ai/deepseek-harness.git
101
+ cd deepseek-harness
102
+ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
103
+ <h3>2.3 把引擎插件装进 profile</h3>
104
+ <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
105
+ <p><code>dsh plugin --profile &lt;name&gt; add &lt;package&gt;</code> 会在 <code>$DSH_HOME/profiles/&lt;name&gt;/</code> 里执行 <code>pnpm add</code>,并自动识别插件声明的 <code>dsh.bundle.patch</code>,把它挂进该 profile 的插件层栈——<b>不要</b>手写 <code>npm i</code> 装到别处,那样不会挂载。</p>
106
+ <p>装完<b>重启 <code>dsh web</code></b> 生效,自动完成两件事:侧边栏多出「工程流程」工作台;预设列表多出「工程化开发引擎」。</p>
107
+ <h3>2.4 启用</h3>
108
+ <p>新建会话 → 预设选「工程化开发引擎」。这个会话会启用 <code>dev_task</code> 与编排技能 <code>eng-delivery</code>,按配置的流程走。</p>
109
+ <div class="callout"><p>想「正式开发」就选它;想「让 AI 自由探索」就选 <code>standard</code>。切换预设本身就是开关,零配置。</p></div>
110
+ </section>
111
+
112
+ <section id="structure">
113
+ <h2>3. 文件与目录</h2>
114
+ <pre><code>D:\workspace\
115
+ ├─ AGENTS.md ← init 生成的项目描述(DSH 每会话自动注入)
116
+ ├─ .dsh\
117
+ │ ├─ eng.json ← 流程预设 + 节点技能 + 技能规则(团队共享,可进 git)
118
+ │ ├─ skills\ ← 项目级 skill
119
+ │ ├─ rules\ ← 项目级 rule
120
+ │ └─ task-*.json ← 每个任务的状态快照
121
+ └─ $DSH_HOME\
122
+ ├─ skills\ ← 用户级 skill(个人所有项目通用)
123
+ └─ rules\ ← 用户级 rule</code></pre>
124
+ <div class="table-wrap">
125
+ <table>
126
+ <thead><tr><th>路径</th><th>作用</th><th>何时读取或修改</th></tr></thead>
127
+ <tbody>
128
+ <tr><td><code>.dsh/eng.json</code></td><td>流程、阶段技能引用及技能规则配置</td><td>新任务创建时读取并冻结;工作台保存时写入</td></tr>
129
+ <tr><td><code>.dsh/skills/</code></td><td>项目级 DSH skill(团队共享)</td><td>新建默认写入这里;节点挂载命中时按需读取</td></tr>
130
+ <tr><td><code>.agents/skills/</code></td><td>项目级 Codex skill(团队共享)</td><td>工作台自动发现;通过 dev_task load_skill 读取技能与所挂规则</td></tr>
131
+ <tr><td><code>.dsh/rules/</code></td><td>项目级 rule(团队共享)</td><td>节点挂载命中时按需读取</td></tr>
132
+ <tr><td><code>.dsh/task-*.json</code></td><td>当前任务的有效状态快照</td><td>确认、实施、验证、评审、切换阶段时更新</td></tr>
133
+ <tr><td><code>$DSH_HOME/skills/ · rules/</code></td><td>用户级 skill / rule</td><td>引用显式记录来源,同名资源互不混淆</td></tr>
134
+ </tbody>
135
+ </table>
136
+ </div>
137
+ </section>
138
+
139
+ <section id="flows">
140
+ <h2>4. 三套流程预设</h2>
141
+ <p>阶段图和流转门禁随预设固化;提交消息格式、产物字段及技能规则由使用者配置。需要一份起点时,可显式「采用推荐配置」。</p>
142
+ <div class="table-wrap">
143
+ <table>
144
+ <thead><tr><th>预设</th><th>阶段顺序</th><th>适用</th><th>守卫强度</th></tr></thead>
145
+ <tbody>
146
+ <tr><td><code>standard</code> 完整研发</td><td>需求评审 → 设计 → 开发 → 交付 → 代码审核 → 完成</td><td>新功能、跨模块及高风险任务</td><td>人工确认 + 验证门 + 评审门</td></tr>
147
+ <tr><td><code>agile</code> 日常迭代</td><td>需求 → 开发 → 交付 → 审查</td><td>常规功能与缺陷修复</td><td>四阶段,终态需审查通过</td></tr>
148
+ <tr><td><code>minimal</code> 快速修改</td><td>开发 → 交付</td><td>局部低风险改动</td><td>实施项与交付门禁</td></tr>
149
+ </tbody>
150
+ </table>
151
+ </div>
152
+ <div class="callout warn">
153
+ <p>预设之外,单个任务还有两个模型自动判断的字段:<code>work_size</code>(tiny / standard / complex,决定拆多细)和 <code>risk_level</code>(standard / high_risk,决定验证强度)。它们不是流程档位,是单个任务的规模与风险标签。</p>
154
+ <p><strong>高风险任务只能在 <code>standard</code> 流程建</strong>——引擎要求高风险任务具备「验证门 + 文件范围 + 评审门」,<code>agile</code>/<code>minimal</code> 没有验证门和评审门,建 <code>high_risk</code> 任务会被直接拒绝。要跑高风险就选标准研发,或把风险降到 standard。</p>
155
+ <p>任务创建时会把所选流程<b>固化成快照</b>——之后在途任务一直按创建时的门禁走,中途改 <code>.dsh/eng.json</code> 只影响新任务,不影响已建任务。</p>
156
+ </div>
157
+ </section>
158
+
159
+ <section id="skills">
160
+ <h2>5. Skills:这一步做什么</h2>
161
+ <p>插件仅内置 <code>eng-delivery</code>,用于会话编排。项目级与用户级业务技能由使用者自行创建或安装;工作台也可发现当前项目 <code>.agents/skills</code> 中已有的 Codex 技能。挂到节点后,走到那一步才加载。</p>
162
+ <div class="table-wrap">
163
+ <table>
164
+ <thead><tr><th>Skill</th><th>职责</th><th>不负责</th></tr></thead>
165
+ <tbody>
166
+ <tr><td><code>eng-delivery</code></td><td>读任务状态、按阶段推进、确保不越轨</td><td>代替各阶段 Skill 的专业工作</td></tr>
167
+ </tbody>
168
+ </table>
169
+ </div>
170
+ </section>
171
+
172
+ <section id="rules">
173
+ <h2>6. Rules:这一步守什么</h2>
174
+ <p>Rule 是纯正文的约束,配置在技能下。节点引用技能,任务走到该节点时才读取技能及其规则的最新正文;预设不会自动绑定它们。插件不内置业务规则。团队可创建自己的技能和共享规则,再决定哪些节点使用技能;提交消息格式在项目配置中设置。</p>
175
+ </section>
176
+
177
+ <section id="configure">
178
+ <p>当前版本支持三个内置流程,阶段可选择技能,技能可绑定规则。可视化自定义流程不在当前计划内。</p>
179
+ <h2>7. 配置流程与挂载</h2>
180
+ <p>侧边栏点「工程流程」打开工作台,五个标签页:<strong>项目初始化 / 流程配置 / 任务 / 技能 skill / 规则 rule</strong>,默认落在「项目初始化」(详见第 8 节)。日常配流程只需在「流程配置」页做两件事:</p>
181
+ <ol>
182
+ <li><strong>选流程预设</strong>:standard / agile / minimal;如需现成起点,可单独点击「采用推荐配置」。</li>
183
+ <li><strong>给节点选技能</strong>:先选节点,再用双栏选择器挑选技能;点技能的规则配置,在右侧栏绑定规则与证据类型,最后保存。</li>
184
+ </ol>
185
+ <p>「技能」和「规则」页提供搜索、来源筛选、新建、安装、查看、编辑与删除。点「安装技能」选择含 <code>SKILL.md</code> 的文件夹;点「安装规则」选择一个 <code>.md</code> 文件。选择后先显示预览:名称、正文、文件数、体积、目标路径和同名冲突。确认项目或个人范围后点击「确认安装」;预览本身不写入文件,改变范围后需要重新预览。</p>
186
+ <p>新建项目资源默认写入工作区 <code>.dsh/skills</code> 或 <code>.dsh/rules</code>;个人资源写入 <code>$DSH_HOME</code> 对应目录。当前项目 <code>.agents/skills</code> 中已有的 Codex 技能也会显示,其正文在工作台只读,可编辑原文件;规则仍配置在该技能下,规则正文可引用项目 <code>.dsh/rules</code>。浏览器选择的是浏览器所在电脑的文件;高级目录模式读取 Harness 主机的目录。技能保留脚本、references、模板和二进制资源,排除常见缓存;上限 1000 文件、100 MB、单文件 20 MB、20 层目录,<code>SKILL.md</code> 和规则正文上限 1 MB。拒绝覆盖同名资源;主机扫描拒绝符号链接和 junction。浏览器上传不提供源链接元数据。</p>
187
+ <p>资源删除前会显示名称与实际目标路径,确认后永久删除;可点击「保留」取消。任务台账支持搜索、风险与阶段筛选,并显示验证、审核和更新时间。流程配置读取与保存失败时显示错误,损坏任务记录不会被静默视为没有任务。</p>
188
+ <pre><code>// .dsh/eng.json 等价内容
189
+ {
190
+ "flow": "standard",
191
+ "stage_bindings": {
192
+ "开发": { "skill_refs": [{ "source": "project", "name": "my-implementation" }] }
193
+ },
194
+ "skill_profiles": {
195
+ "project:my-implementation": {
196
+ "rules": [{ "source": "project", "name": "my-coding-rule" }],
197
+ "evidence": "none"
198
+ }
199
+ }
200
+ }</code></pre>
201
+ <div class="callout warn"><p>页面实时校验:挂到不存在的阶段、空名等会红字提示并置灰保存;保存前主机再校验一遍。错误的配置存不进去。</p></div>
202
+ <p>技能和规则引用包含 <code>source</code> 与 <code>name</code>;内置、项目、用户目录中的同名资源可以区分。旧版节点级规则迁移时会保留为待分配规则并继续生效,建议逐条归到对应技能。</p>
203
+ </section>
204
+
205
+ <section id="init">
206
+ <h2>8. 项目初始化(init)</h2>
207
+ <p>二开 / 遗留项目没有文档时,先给项目建一份「描述文件」——项目根的 <code>AGENTS.md</code>。DSH 平台会把它<b>自动注入到每个会话</b>,生成一次,之后每个任务开工 AI 都自带这份项目认知(项目是什么 → 怎么跑 → 结构 → 约定 → 坑)。</p>
208
+ <div class="callout"><p><strong>两种入口,推荐工作台:</strong>① 工作台「项目初始化」标签页(点按钮,可视化预览 + 保存,0.19.0 起,默认第一个标签页);② 对话式 init(对 AI 说「帮我初始化这个项目」,AI 调 <code>dev_task</code> 走 inspect → propose → apply)。</p></div>
209
+
210
+ <h3>工作台初始化(推荐)</h3>
211
+ <ol>
212
+ <li>侧边栏点「工程流程」,工作台<b>默认落在「项目初始化」标签页</b>。</li>
213
+ <li><b>先看已有文档</b>:顶部显示「未初始化」或「已初始化 · N 行(上限 200)」。工作区根没有 <code>AGENTS.md</code> 时,会自动向下找唯一子项目、向上找父目录,并把实际定位路径标出来(如 <code>已定位到 D:\qdmai\qms\AGENTS.md</code>)。</li>
214
+ <li><b>让 AI 初始化</b>:点按钮,AI 扫描项目(目录结构、关键文件、技术栈、构建 / 运行命令、约定与红线)生成草稿——<b>只预览、不落盘</b>,硬校验<b>行数 ≤ 200 行</b>,超了精简到「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」,只留骨架不塞长文。运行中实时显示「已耗时 X 秒」,最长 150 秒超时,超时提示重试即可。</li>
215
+ <li><b>保存 / 保存并覆盖</b>:预览满意点「保存」——首次创建直接写入;已有 <code>AGENTS.md</code> 会标「保存并覆盖」,必须人工点确认才覆盖,保护项目已有治理文件不被裸覆盖。</li>
216
+ <li>也可点「手动编辑」直接改正文后保存。</li>
217
+ </ol>
218
+
219
+ <h3>对话式 init</h3>
220
+ <ol>
221
+ <li><b>inspect</b>:对 AI 说「帮我初始化这个项目」;AI 读现有 <code>AGENTS.md</code>(若有)返回,没有则扫目录结构、技术栈、构建 / 运行命令、约定与红线。同时报告:项目根(自动从 workspace 向上发现)、语言栈(Node / Java / Python / Go / Rust)与默认验证命令、其它治理文件(<code>CLAUDE.md</code>、<code>.cursorrules</code>——init 只管理 AGENTS.md,不覆盖它们)、项目级 skill/rule 目录(<code>.dsh/rules/*.md</code>、<code>.dsh/skills/&lt;name&gt;/SKILL.md</code>)。</li>
222
+ <li><b>propose</b>:AI 写成 <code>AGENTS.md</code> 草稿,此步<b>只预览、不落盘</b>,同样硬校验<b>行数 ≤ 200 行</b>,并返回内容 hash。</li>
223
+ <li><b>apply</b>:落盘。<b>必须传回 propose 返回的 <code>expected_hash</code></b>(缺失或与内容不一致一律拒绝,防止预览与落盘之间内容被换);覆盖已有 <code>AGENTS.md</code> 时<b>还必须传回 <code>existing_hash</code></b>(证明审批期间现有文件未被他人改动)并带 <code>overwrite</code> 且<b>经人工批准</b>。写入目标必须在项目根内。</li>
224
+ </ol>
225
+ <pre><code>项目根/
226
+ ├─ AGENTS.md ← init 生成,DSH 每会话自动注入
227
+ └─ .dsh/
228
+ ├─ eng.json ← flow + verify_command(可覆盖语言默认验证命令)
229
+ ├─ skills/ · rules/
230
+ └─ task-*.json</code></pre>
231
+ </section>
232
+
233
+ <section id="start">
234
+ <h2>9. 如何开始一个任务</h2>
235
+ <ol>
236
+ <li>新建会话,预设选「工程化开发引擎」。</li>
237
+ <li>直接描述需求(加功能 / 修 bug)。</li>
238
+ <li>AI 建任务、判 <code>work_size</code> 与 <code>risk_level</code>,停在起始阶段(标准流程是「需求评审」)。</li>
239
+ <li>AI 落需求说明,需要拍板处发起审批,你点「允许」才进入下一步。</li>
240
+ <li>之后一个阶段一个阶段推进,直到「完成」。</li>
241
+ </ol>
242
+ <div class="flow">
243
+ <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>
244
+ </div>
245
+ </section>
246
+
247
+ <section id="run">
248
+ <h2>10. 流程如何逐阶段执行</h2>
249
+ <div class="table-wrap">
250
+ <table>
251
+ <thead><tr><th>阶段</th><th>AI 在这一站做什么</th><th>过关条件(不满足不让走)</th></tr></thead>
252
+ <tbody>
253
+ <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全,且<b>人点「允许」确认需求</b></td></tr>
254
+ <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全,且<b>人点「允许」确认方案</b></td></tr>
255
+ <tr><td>开发</td><td>独立交付可派子代理,小修正可由主代理实施;每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done(每项带两阶段评审);已有项可省略标题,改已审核标题须显式重开</td></tr>
256
+ <tr><td>交付</td><td>执行验证、记录证据</td><td>新任务必须真实命令回执,退出码 0,未超时、取消或被沙箱拒绝</td></tr>
257
+ <tr><td>代码审核</td><td>评审变更,执行终态技能,受控提交</td><td>结论通过、字段填全、技能义务完成且真实 Git 提交已回写</td></tr>
258
+ <tr><td>完成</td><td>收尾</td><td>—</td></tr>
259
+ </tbody>
260
+ </table>
261
+ </div>
262
+ <p>新任务离开阶段前检查绑定技能是否成功加载;Codex 项目技能通过 <code>dev_task load_skill</code> 加载其正文及所挂规则。技能可以声明 <code>command</code>、<code>artifact</code>、<code>review</code>、<code>manual</code> 或 <code>none</code> 证据类型。只有需要命令回执的技能才出现在 <code>command_receipts_required</code> 中。挂在终态的技能在进入终态前执行。命令成功只证明该命令通过,不证明覆盖完整;文件变动后须重新验证。任务的流程配置按创建时的快照执行,Skill/Rule 正文在下一次交互读取最新版本。</p>
263
+ <h3>贯穿全程的硬规则</h3>
264
+ <ul>
265
+ <li>阶段是硬状态:status 说你在哪,就只做那一步,绝不倒带重走、绝不跳。</li>
266
+ <li>确认只能人来做:需求确认、方案确认由 AI 发起审批,你在页面点「允许」;AI 不能自己通过、不能绕过。</li>
267
+ <li>渐进披露:走到哪个阶段,才加载那一段的 skill / rule。</li>
268
+ </ul>
269
+ </section>
270
+
271
+ <section id="state">
272
+ <h2>11. 任务状态如何记录进度</h2>
273
+ <p>每个任务一份 <code>.dsh/task-*.json</code>,只保存当前有效状态,不保存聊天全文和流水日志。</p>
274
+ <div class="table-wrap">
275
+ <table>
276
+ <thead><tr><th>字段</th><th>含义</th></tr></thead>
277
+ <tbody>
278
+ <tr><td><code>id / title</code></td><td>任务标识与标题</td></tr>
279
+ <tr><td><code>branch</code></td><td>所属功能分支;恢复时以真实当前分支为准</td></tr>
280
+ <tr><td><code>stage</code></td><td>当前阶段(决定下一步做什么、能往哪走)</td></tr>
281
+ <tr><td><code>work_size</code></td><td>tiny / standard / complex,决定拆多细</td></tr>
282
+ <tr><td><code>risk_level</code></td><td>standard / high_risk,决定验证强度</td></tr>
283
+ <tr><td><code>requirement_confirmed</code></td><td>需求是否已由人确认</td></tr>
284
+ <tr><td><code>solution_confirmed</code></td><td>方案是否已由人确认</td></tr>
285
+ <tr><td><code>verification</code></td><td>验证是否通过 + 证据(高风险附真实命令回执)</td></tr>
286
+ <tr><td><code>review</code></td><td>评审结论(通过 / 未过 + 问题)</td></tr>
287
+ <tr><td><code>files</code></td><td>本任务允许修改的文件范围</td></tr>
288
+ <tr><td><code>commits</code></td><td>已创建的提交记录</td></tr>
289
+ </tbody>
290
+ </table>
291
+ </div>
292
+ <p>会话断了没关系:重新开会话,AI 读 <code>stage</code>、确认态、验证与评审字段,就能从断点继续,不依赖上一轮聊天。</p>
293
+ </section>
294
+
295
+ <section id="verify">
296
+ <h2>12. 验证、评审与提交</h2>
297
+ <h3>验证为什么不该总那么慢</h3>
298
+ <ul>
299
+ <li>实施中优先受影响模块的编译、目标测试与静态检查。</li>
300
+ <li>差异没变时复用有效证据,不重复跑相同命令。</li>
301
+ <li>无法联调外部系统时必须如实写「未联调」,不能把编译成功说成功能通过。</li>
302
+ <li><code>high_risk</code> 任务过验证门必须跑真实命令回执(引擎运行命令、取退出码,非自报通过)。</li>
303
+ <li><code>verify</code> 不带 <code>command</code> 时引擎自动选命令:<code>.dsh/eng.json</code> 的 <code>verify_command</code> 优先,其次按项目语言用默认(node → <code>npm test</code>、java → <code>mvn -q test</code>、python → <code>python -m pytest</code>、go → <code>go test ./...</code>、rust → <code>cargo test</code>);新任务若没有可用默认命令,须显式提供真实命令。跑命令依赖宿主 shell 服务,未挂载会明确报错。</li>
304
+ <li><b>验证命令始终在任务记录的项目根运行</b>(任务创建时自动发现并固化 <code>root</code>),不是会话当前目录——monorepo 里会话停在子目录时,<code>npm test</code> 等也会在放清单文件的项目根执行;回执记录的 <code>root</code> 与任务根强校验,不一致直接拒绝。</li>
305
+ </ul>
306
+ <h3>评审</h3>
307
+ <p>开发阶段每项做「规格 + 质量」两阶段评审,都 pass 才标 done;缺评审或任一阶段 fail 会挡住「开发 → 交付」。</p>
308
+ <h3>提交策略</h3>
309
+ <div class="table-wrap">
310
+ <table>
311
+ <thead><tr><th>策略</th><th>何时提交</th><th>标识</th></tr></thead>
312
+ <tbody>
313
+ <tr><td><code>task</code></td><td>整项验证、评审通过后一次提交</td><td><code>TASK</code></td></tr>
314
+ <tr><td><code>item</code></td><td>每个独立项验证后提交;整项完成再提最终状态</td><td><code>Tn</code>,最终 <code>TASK</code></td></tr>
315
+ <tr><td><code>manual</code></td><td>等用户明确要求才提交</td><td>用户指定</td></tr>
316
+ </tbody>
317
+ </table>
318
+ </div>
319
+ <p>流程骨架不规定提交消息格式;若采用推荐配置,会写入 <code>【任务 id】【TASK】结果说明</code> 等文本约定,之后可修改或删除。文件范围门禁按所选流程与任务配置检查。可安装本地提交钩子,让普通 <code>git commit</code> 经过相同的门禁:</p>
320
+ <pre><code>dev_task operation=install_hook # 装入 .git/hooks/commit-msg,装上后任何 git commit 都被同一套规则校验
321
+ dev_task operation=verify_hook # 随时比对安装钩子与内置门禁的 hash,被替换/篡改立即报错</code></pre>
322
+ <p><strong>钩子的额外硬校验(0.21/0.22):</strong>① 任务记录的流程快照带 SHA-256 hash,被手改过的快照一律拒绝提交;② 触及敏感路径(<code>.env</code>、credentials、secrets、<code>.git</code>;<code>.dsh</code> 的任务记录与流程配置由快照 hash 与豁免保护,项目级 rules/skills 属常规内容)的提交,要求任务为 <code>high_risk</code> 且验证有真实命令回执,否则拒绝;③ 删除、类型变换、重命名的旧·新路径都受范围检查。</p>
323
+ <p><strong>风险降级(0.22):</strong><code>set_risk</code> 把 <code>high_risk</code> 降为 <code>standard</code> 必须人工批准,并写入任务的 <code>risk_downgrades</code> 审计记录;降级后高风险回执门不再适用,请谨慎。</p>
324
+ </section>
325
+
326
+ <section id="example">
327
+ <h2>13. 一个标准任务的完整走查</h2>
328
+ <p>假设需求是「给现有查询接口加一个权限校验」。标准流程下,关键决策点应接近下面这样:</p>
329
+ <pre><code>flow: standard // 项目预设
330
+ work_size: standard // 数个文件 + 权限判断
331
+ risk_level: high_risk // 涉及鉴权,验证要加证据
332
+
333
+ ① 需求评审
334
+ - 目标:无权限返回 403;有权限正常返回。
335
+ - 验收、非目标写清 → 【人确认需求】
336
+
337
+ ② 设计
338
+ - 最小方案:Controller 加校验、Service 复用现有鉴权方法。
339
+ - 不新建接口 / DTO / 异常包装 → 【人确认方案】
340
+
341
+ ③ 开发
342
+ - T1:接口加校验 + 编写无权限 / 有权限用例。
343
+ - 规格 ✓ 质量 ✓ → done
344
+
345
+ ④ 交付
346
+ - 验证:跑鉴权用例,`verify` 传真实命令(high_risk 由引擎取退出码判定)。
347
+ - 文件改动后必须重新验证,旧回执失效。
348
+
349
+ ⑤ 代码审核
350
+ - 结论:通过 · 问题:无
351
+ - 执行挂在完成阶段的附加技能,再提交并回写真实 hash。
352
+
353
+ ⑥ 完成</code></pre>
354
+ <p>这类任务不应因为「以后可能复用」扩展成多层架构,也不应把推荐项自动当成验收条件。</p>
355
+ </section>
356
+
357
+ <section id="boundaries">
358
+ <h2>14. 边界与常见问题</h2>
359
+ <div class="callout danger">
360
+ <p>引擎只允许:读取仓库事实、修改<b>已确认任务范围内</b>的文件、按策略创建<b>范围受控的本地提交</b>。远程 push / 合并 / 发布、数据库写入,需人单独决定。</p>
361
+ </div>
362
+ <details open><summary>切换预设就是开关吗?</summary><div>是。选「工程化开发引擎」才启用 <code>dev_task</code> 与编排技能;工作台中的 <code>standard</code>、<code>agile</code>、<code>minimal</code> 则选择该工具使用的流程骨架。</div></details>
363
+ <details><summary>技能和规则由谁提供?</summary><div>插件只内置用于会话编排的 <code>eng-delivery</code>。项目或个人技能与规则由你创建或安装;规则挂在技能下,再把技能挂到节点。空绑定时流程门禁照常运行。</div></details>
364
+ <details><summary>任务文档要不要提交?</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实,随分支提交——引擎已豁免 <code>.dsh/task-*.json</code> 与 <code>.dsh/eng.json</code>,不受文件范围门拦截;忽略它别人只能看到代码,看不到确认内容和进度。</div></details>
365
+ <details><summary>一个会话能同时做两个需求吗?</summary><div>一个任务对应一份状态文档、一个分支。新需求保存当前进度后切新分支,切回原分支即可恢复。</div></details>
366
+ <details><summary>提交被拒是怎么回事?</summary><div>通常是四类:没建 dev_task 任务、阶段没到提交检查点、消息格式不符、提交文件不在任务范围内。按拒绝原因修正即可。</div></details>
367
+ <details><summary>git 钩子能防住所有绕过吗?</summary><div>不能。<code>.git/hooks/commit-msg</code> 提供<b>本地即时反馈</b>,拦常规 <code>git commit</code>(校验任务、阶段、范围、消息、快照 hash、敏感路径),但挡不住 <code>git commit --no-verify</code>、<code>core.hooksPath</code> 替换或直接手改任务记录。若项目需要强制约束,应在自己的受保护分支和 CI 中配置独立检查;插件本身不会自动为使用者仓库安装远程 CI 门禁。</div></details>
368
+ <details><summary>任务记录被手改会怎样?</summary><div>流程快照内容与保存的 SHA-256 不一致时会被拒绝;任务记录本身没有签名,能同时修改内容与 hash 的本地用户仍可伪造。文件版本与 <code>revision</code> 检查用于阻止并发覆盖,不提供身份认证。0.23.0 在读取内容前取得文件版本,使读取期间发生的并发写入也被拒绝。多用户隔离和可信状态签名需要 Harness 支持。</div></details>
369
+ <details><summary>Remote 如何限制工作区?</summary><div>有 <code>workspaceRegistry.resolveByPath</code> 的 Harness 使用主机注册目录;未注册路径拒绝。旧主机保留绝对路径和系统目录检查,并提供严格注册 API。工作区注册不等于当前会话授权;共享多用户部署仍需要调用上下文和主机权限边界。</div></details>
370
+ <details><summary>dev_task 写文件被沙箱拒绝(file access denied)怎么办?</summary><div>沙箱按调用策略放行写入,偶发的越界误判可用一次性升级重试:同一操作加 <code>sandbox_permissions: "workspace-write"(或 "danger-full-access")</code> 并配 <code>justification</code>(一句话说明原因),升级需要<b>人工批准</b>;无审批服务时直接拒绝。日常任务记录写入默认已在会话工作区内放行,通常无需升级。</div></details>
371
+ <details><summary>「完成」等于上线了吗?</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过;上线、合并、发布需人另行决定。</div></details>
372
+ <p>状态查询中的 <code>evidence_blockers</code> 列出过期验证和附加技能回执;<code>commit.allowed</code> 同时检查这些阻塞及技能执行义务。<code>legal_next</code> 是流程定义的候选去向,不表示所有门禁已通过。</p>
373
+ <details><summary>记录需求时提示字段不存在怎么办?</summary><div>先读取 <code>status.artifact_requirements</code>,按当前阶段列出的字段填写。标准需求为 <code>scope</code> 和 <code>acceptance_criteria</code>,敏捷流程只有 <code>scope</code>。疑问、假设或待确认取舍写入字段正文,不新增字段名。错误输入整次不保存,修正后再提交;不需要修改流程配置或历史任务记录。</div></details>
374
+ <details><summary>验证命令被沙箱阻止怎么办?</summary><div><code>verify</code> 与 <code>skill_result</code> 默认使用会话权限。原命令被沙箱阻止后,用相同命令和 <code>sandbox_permissions: "danger-full-access"</code>、<code>justification</code> 申请单次重试。审批显示命令,批准后才执行;拒绝、取消或审批不可用时不执行、不写回执。授权只对本次调用生效,不改变会话权限。以本次回执的实际模式和退出码判断结果。</div></details>
375
+ <p class="stamp">适用于当前研发版 · 最后更新:2026-09-26</p>
376
+ </section>
377
+ </main>
378
+ </div>
379
+ </body>
380
+ </html>