@godv61/dsh-task-engine 0.28.0 → 0.29.1

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 (49) hide show
  1. package/.adaptive-test.mjs +189 -0
  2. package/.hook-test.mjs +19 -2
  3. package/.workflow-test.mjs +6 -4
  4. package/README.md +22 -16
  5. package/docs/CHANGELOG.md +14 -1
  6. package/docs/README.md +6 -5
  7. package/docs/adaptive-workflows.md +72 -0
  8. package/docs/configuration.md +4 -4
  9. package/docs/faq.md +15 -7
  10. package/docs/getting-started.md +8 -5
  11. package/docs/manual-legacy.html +380 -0
  12. package/docs/manual.html +126 -380
  13. package/docs/roadmap.md +7 -8
  14. package/hooks/commit-msg +39 -22
  15. package/lib/adaptive.d.ts +15 -0
  16. package/lib/adaptive.js +54 -0
  17. package/lib/adaptive.js.map +1 -0
  18. package/lib/client.js +800 -433
  19. package/lib/client.js.map +3 -3
  20. package/lib/controller.d.ts +50 -0
  21. package/lib/controller.js +132 -0
  22. package/lib/controller.js.map +1 -1
  23. package/lib/dev-task.js +413 -18
  24. package/lib/dev-task.js.map +1 -1
  25. package/lib/engine.d.ts +20 -0
  26. package/lib/engine.js +4 -1
  27. package/lib/engine.js.map +1 -1
  28. package/lib/hook.js +50 -29
  29. package/lib/hook.js.map +1 -1
  30. package/lib/project-init.d.ts +23 -0
  31. package/lib/project-init.js +94 -0
  32. package/lib/project-init.js.map +1 -0
  33. package/lib/skill-audit.js +8 -7
  34. package/lib/skill-audit.js.map +1 -1
  35. package/lib/sonar.d.ts +33 -0
  36. package/lib/sonar.js +80 -0
  37. package/lib/sonar.js.map +1 -0
  38. package/package.json +5 -4
  39. package/preset/enable.mjs +2 -2
  40. package/preset/persona.md +4 -2
  41. package/scripts/verify-dsh-compat.mjs +14 -3
  42. package/scripts/verify-package.mjs +7 -3
  43. package/skills/architecture-design/SKILL.md +11 -0
  44. package/skills/code-development/SKILL.md +11 -0
  45. package/skills/code-review/SKILL.md +11 -0
  46. package/skills/eng-delivery/SKILL.md +6 -2
  47. package/skills/requirements-analysis/SKILL.md +11 -0
  48. package/skills/task-orchestration/SKILL.md +11 -0
  49. package/skills/test-validation/SKILL.md +11 -0
package/docs/manual.html CHANGED
@@ -1,380 +1,126 @@
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">这是一套装在 DeepSeek Harness 里的工程流程约束。流程预设规定阶段与门禁;技能、规则、提交文本和产物字段由使用者配置。在个人工作台里选择流程,把规则配置在技能下,再把技能挂到相应阶段。</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>
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>DSH Task Engine 使用手册</title>
7
+ <style>
8
+ :root{--ink:#172535;--muted:#526477;--line:#d8e1eb;--blue:#2155b4;--pale:#edf4ff;--paper:#f5f7fa;--white:#fff}
9
+ *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--paper);color:var(--ink);font:16px/1.75 "Microsoft YaHei","PingFang SC",system-ui,sans-serif}
10
+ a{color:var(--blue)}code,pre{font-family:Consolas,"Cascadia Code",monospace}code{background:#eef2f6;padding:.1em .35em;border-radius:.25em}pre{overflow:auto;padding:1rem;background:#14243c;color:#fff;border-radius:.6rem}pre code{padding:0;background:none}
11
+ header{padding:2.5rem max(1rem,calc((100vw - 1120px)/2));background:linear-gradient(120deg,#143775,#2760bc);color:#fff}header h1{margin:.1rem 0;font-size:2.3rem}header p{max-width:850px;margin:.4rem 0}
12
+ .layout{width:min(1120px,calc(100% - 2rem));margin:2rem auto;display:grid;grid-template-columns:230px minmax(0,1fr);gap:1.5rem}nav{position:sticky;top:1rem;align-self:start;background:var(--white);border:1px solid var(--line);border-radius:.7rem;padding:1rem}nav a{display:block;padding:.25rem 0}
13
+ main{min-width:0}section{background:var(--white);border:1px solid var(--line);border-radius:.8rem;padding:1.4rem;margin-bottom:1rem}h2{margin:0 0 .8rem}h3{margin:1.35rem 0 .35rem}p{margin:.5rem 0 1rem}.note{background:var(--pale);border-left:4px solid var(--blue);padding:.75rem 1rem;border-radius:.3rem}.warn{background:#fff2dc;border-left-color:#bc7821}
14
+ table{border-collapse:collapse;width:100%;font-size:.94rem}th,td{border:1px solid var(--line);padding:.55rem;text-align:left;vertical-align:top}th{background:#edf4ff}ul,ol{padding-left:1.45rem}li+li{margin-top:.3rem}.scroll{overflow-x:auto}
15
+ @media(max-width:760px){.layout{display:block}nav{position:static;margin-bottom:1rem}nav a{display:inline-block;margin-right:.8rem}header{padding:1.5rem 1rem}}@media print{nav{display:none}.layout{display:block;width:100%}section{break-inside:avoid}}
16
+ </style>
17
+ </head>
18
+ <body>
19
+ <header>
20
+ <p>DeepSeek Harness · 0.29.1</p>
21
+ <h1>DSH Task Engine 使用手册</h1>
22
+ <p>按每个需求选择工程路径,用项目 Skill 和 Rule 复用团队规范;SonarQube 审核由项目自行选择。</p>
23
+ </header>
24
+ <div class="layout">
25
+ <nav aria-label="目录">
26
+ <strong>目录</strong>
27
+ <a href="#status">版本状态</a>
28
+ <a href="#start">开始使用</a>
29
+ <a href="#flows">四档任务流程</a>
30
+ <a href="#skills">元技能与规则</a>
31
+ <a href="#init">项目初始化</a>
32
+ <a href="#sonar">可选 SonarQube</a>
33
+ <a href="#commit">为什么当前要提交</a>
34
+ <a href="#legacy">旧版流程</a>
35
+ <a href="#limits">验证边界</a>
36
+ </nav>
37
+ <main>
38
+ <section id="status">
39
+ <h2>版本状态</h2>
40
+ <div class="note">本手册描述 <code>0.29.1</code> 的自适应流程、项目 Skill/Rule 初始化与可选 SonarQube CI 接入。Sonar 审核当前需要先提交并完成 CI 扫描,尚不支持未提交代码的本地 Sonar 审核。</div>
41
+ <p>本手册替换了旧版 HTML 说明。旧版三流程的详细操作保存在<a href="manual-legacy.html">历史手册</a>,现行新功能的技术细节见<a href="adaptive-workflows.md">自适应流程说明</a>。</p>
42
+ </section>
43
+ <section id="start">
44
+ <h2>开始使用</h2>
45
+ <ol>
46
+ <li>在使用的 Web profile 中启用插件,重启 Harness Web。</li>
47
+ <li>进入「工程任务」工作台并选择项目工作区。「自适应流程」用于查看四档路径、给元技能挂载项目 Skill,以及设置可选 SonarQube。</li>
48
+ <li>新建「工程化开发引擎」会话并描述需求。模型先分析复杂度,用 <code>dev_task assess</code> 预览,再在创建任务时给出 <code>complexity</code> 和理由。</li>
49
+ <li>在「任务台账」查看阶段、验证、审核及 Sonar 记录。每个任务独立选择流程;同一项目里的其他会话不会被统一推入同一流程。</li>
50
+ </ol>
51
+ <p>工作台的「项目初始化」仍可维护 <code>AGENTS.md</code>;生成项目 Skill/Rule 使用会话中的 <code>dev_task init_project</code>。</p>
52
+ </section>
53
+ <section id="flows">
54
+ <h2>四档任务流程</h2>
55
+ <div class="scroll"><table>
56
+ <thead><tr><th>档次</th><th>适用情况</th><th>阶段顺序</th></tr></thead>
57
+ <tbody>
58
+ <tr><td>低</td><td>边界明确的局部修改</td><td>代码开发 → 测试 → 代码审核 → 完成</td></tr>
59
+ <tr><td>中</td><td>常规功能或缺陷修复</td><td>需求分析 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
60
+ <tr><td>高</td><td>跨模块且存在实现先后依赖</td><td>需求分析 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
61
+ <tr><td>超高</td><td>完整新模块或大范围重构</td><td>需求分析 → 架构设计 → 任务编排 → 代码开发 → 测试 → 代码审核 → 完成</td></tr>
62
+ </tbody>
63
+ </table></div>
64
+ <p>高档的任务编排按实现先后拆解,记录依赖和交接产物,不按人员分工。风险级别与复杂度分开判断。阶段顺序和门禁在任务创建时冻结,Skill/Rule 正文更新后会在下一次读取时生效并提示漂移。</p>
65
+ </section>
66
+ <section id="skills">
67
+ <h2>元技能、Skill 与 Rule</h2>
68
+ <p>内置六个通用元技能:需求分析、架构设计、任务编排、代码开发、测试、代码审核。每个阶段加载同名核心 Skill;使用者可为阶段增加项目 Skill。每个 Skill 的 <code>profile.json</code> 保存它引用的 Rule 和证据要求。</p>
69
+ <p>同名 Skill 的选择顺序是 <code>.dsh/skills</code> → <code>.agents/skills</code> → 用户目录 → 插件内置。项目同名 Skill 采用自己的 Rule,不混合用户级同名 Skill 的规则。工作台可编辑项目 Skill 的 Rule 绑定。</p>
70
+ <pre><code>{
71
+ "meta_bindings": {
72
+ "requirements-analysis": ["my-project-map"],
73
+ "code-development": ["my-project-map", "my-code-backend"]
74
+ }
75
+ }</code></pre>
76
+ <p>这个配置位于项目根目录 <code>.dsh/meta.json</code>,只增加技能挂载;四档流程由每个任务自己的复杂度决定。</p>
77
+ </section>
78
+ <section id="init">
79
+ <h2>项目初始化</h2>
80
+ <p>在项目工作区用 <code>dev_task init_project phase=inspect</code> 扫描目录和常见构建清单,取得项目结构、技术栈及可证实版本。模型再检查代表性源码,拟定项目地图、技术栈、后端或前端开发等 Skill 与 Rule。</p>
81
+ <ol>
82
+ <li><code>phase=inspect</code>:只读扫描并返回建议。</li>
83
+ <li><code>phase=propose</code>:预览拟写入的资源及挂载关系。</li>
84
+ <li><code>phase=apply</code>:使用相同草稿与哈希写入项目目录;已有同名文件不会被覆盖。</li>
85
+ </ol>
86
+ </section>
87
+ <section id="sonar">
88
+ <h2>可选 SonarQube 审核</h2>
89
+ <p><strong>不使用:</strong>「自适应流程」中的 SonarQube 开关保持关闭,或不在 <code>.dsh/meta.json</code> 写 <code>sonar</code>。不需要 Sonar 服务、Token 或扫描任务;代码审核仍按审核元技能及项目 Rule 进行。</p>
90
+ <p><strong>使用当前 CI 接入:</strong>打开开关,填写 SonarQube 地址、项目 Key、分析对象(分支或合并请求)和 Token 环境变量名,保存配置。把 Token 只放在运行插件的服务进程环境变量中。新建任务会冻结该选项,已建任务不会被自动修改。</p>
91
+ <pre><code>{
92
+ "sonar": {
93
+ "enabled": true,
94
+ "host_url": "https://sonarqube.example.com",
95
+ "project_key": "my-project",
96
+ "mode": "branch",
97
+ "token_env": "SONAR_TOKEN"
98
+ }
99
+ }</code></pre>
100
+ <p>功能验证通过后,当前实现要求在「测试」阶段提交并推送,再等待现有 CI 的 Sonar 扫描完成。从该次扫描的 <code>report-task.txt</code> 取得 <code>ceTaskId</code>;到「代码审核」阶段调用 <code>dev_task sonar_check</code>。合并请求模式还需提供请求编号。插件查询该次分析的 Quality Gate 与目标分支或请求的新代码问题;Gate 不通过或存在中高等级问题时阻止审核通过。修复后重新测试、扫描和审核。</p>
101
+ <p>失败问题可用 <code>dev_task learn_rule phase=propose</code> 生成项目 Rule 草稿,人工核对可复用原因后再用 <code>phase=apply</code> 挂到项目代码 Skill。一次问题不会自动变成永久团队规范。</p>
102
+ </section>
103
+ <section id="commit">
104
+ <h2>为什么当前实现与分支、提交有关?</h2>
105
+ <p>SonarQube 服务端按项目以及分支或合并请求保存分析结果,所以插件需要用分析对象查询正确的结果。<strong>分支是服务端结果的定位信息,并不意味着审核本身必须先提交。</strong></p>
106
+ <p>当前插件采用「复用 CI 扫描」的实现:CI 通常扫描已推送的提交,所以当前流程先提交后读取结果。这是本版接入方式的限制。SonarQube for IDE 的 Connected Mode 可以在本地未提交代码上应用服务端 Quality Profile 的部分规则,但它的本地分析不等于完整服务端 Quality Gate;本插件当前没有接入这种本地分析。</p>
107
+ <div class="note warn">如果团队要求「功能通过 → 未提交代码审核 → 修复 → 审核通过 → 再提交」,当前 Sonar 接入还不满足这一顺序。不要把本版 CI 检查描述为提交前 Sonar 审核。</div>
108
+ <p>参考:<a href="https://docs.sonarsource.com/sonarqube-for-intellij/using/rules">SonarQube for IntelliJ 规则与 Connected Mode</a>、<a href="https://docs.sonarsource.com/sonarqube-server/2025.4/user-guide/connected-mode">SonarQube Server 的本地分析说明</a>。</p>
109
+ </section>
110
+ <section id="legacy">
111
+ <h2>旧版流程兼容</h2>
112
+ <p>已有 <code>.dsh/eng.json</code> 的项目仍可在「旧版流程」管理 <code>standard</code>、<code>agile</code>、<code>minimal</code>。未带 <code>complexity</code> 的旧调用继续按旧配置运行;旧任务继续使用创建时的快照。细节见<a href="configuration.md">旧流程配置</a>和<a href="manual-legacy.html">历史 HTML 手册</a>。</p>
113
+ </section>
114
+ <section id="limits">
115
+ <h2>验证边界</h2>
116
+ <ul>
117
+ <li>本版已通过构建、自动化测试和安装包黑盒验证;尚未在真实 SonarQube 实例上完成端到端联调。</li>
118
+ <li>服务端扫描的新代码问题列表取自查询时的目标分支或请求;同一目标并发扫描时,应使用当前扫描的 <code>ceTaskId</code> 重新核对。</li>
119
+ <li>本地钩子与任务门禁只约束受控操作;远程合并、发布以及组织级 CI 策略由项目自行管理。</li>
120
+ </ul>
121
+ <p>详细的字段、交接契约和状态说明见<a href="adaptive-workflows.md">自适应工程任务</a>。最后更新:2026-09-30。</p>
122
+ </section>
123
+ </main>
124
+ </div>
125
+ </body>
126
+ </html>
package/docs/roadmap.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [← 文档导航](README.md)
4
4
 
5
- 本页记录**讨论中的方向,不代表已发布功能**;是否实现、何时实现都在开始编码前单独确认。
5
+ 本页记录已发布能力与后续方向;任务级流程见[自适应工程任务](adaptive-workflows.md)。
6
6
  已发布的能力与版本变化见[更新日志](CHANGELOG.md)。
7
7
 
8
8
  ## 当前能力边界
@@ -12,14 +12,14 @@
12
12
  | 三个内置流程(`standard`、`agile`、`minimal`) | ✅ 已发布,开箱即用 |
13
13
  | 阶段选择技能、规则归属技能 | ✅ 已发布 |
14
14
  | 任务台账、验证与审核回执、提交门禁 | ✅ 已发布 |
15
- | 项目级与个人级资源安装、来源保留 | ✅ 已发布 |
16
- | **自由编辑流程阶段与条件** | ❌ **不在计划内** |
15
+ | 项目级与个人级资源安装、来源保留 | ✅ 已发布 |
16
+ | 四档任务级流程、元技能、项目扫描 init、可选审核期 SonarQube CI 接入 | ✅ 0.29.0 |
17
+ | **自由编辑流程阶段与条件** | ❌ **不在计划内** |
17
18
 
18
19
  **关于自定义流程**:让使用者自行设计阶段、条件与提交流程曾被评估,结论是**不列入计划**——
19
- 它把流程设计的负担转嫁给使用者,而三个内置流程已覆盖个人项目的常见需要。代码中不存在该能力的
20
- 实现;相关尝试保留在非发布分支,不在 `main` 上。
20
+ 任务级四档流程覆盖常见开发复杂度,用户可挂载项目技能;自由编辑状态机仍不在当前范围。
21
21
 
22
- 需要调整时,可修改项目根目录的 `.dsh/eng.json` 改变阶段资源绑定,或直接在三个内置流程中选择。
22
+ 旧任务继续读取 `.dsh/eng.json`;新任务用 `.dsh/meta.json` 管理元技能挂载,复杂度在任务创建时确定。
23
23
 
24
24
  ## 后续体验方向
25
25
 
@@ -30,5 +30,4 @@
30
30
 
31
31
  ## 产品范围
32
32
 
33
- 本项目服务本机个人开发工作台。多用户服务器的会话权限架构不列为当前版本的必修项。日常改进优先
34
- 解决工作区目标清晰、文件误操作、任务连续性和操作反馈。
33
+ 本项目服务本机与团队分支开发中的个人会话。多用户服务器的会话权限架构不列为当前版本的必修项。日常改进优先解决工作区目标清晰、文件误操作、任务连续性和操作反馈。