@godv61/dsh-task-engine 0.22.6 → 0.23.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.
package/docs/manual.html CHANGED
@@ -1,383 +1,386 @@
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 里的工程流程约束。它把「需求评审 → 设计 → 开发 → 交付 → 代码审核」做成硬门槛:阶段不能跳、关键节点必须人来拍板、验证和提交都被机械检查。团队只选一套流程,再给每个节点挂上合适的 skill 和 rule。</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="#overview">1. 工作原理</a>
52
- <a href="#install">2. 安装与启用</a>
53
- <a href="#structure">3. 文件与目录</a>
54
- <a href="#flows">4. 三套流程预设</a>
55
- <a href="#skills">5. Skills</a>
56
- <a href="#rules">6. Rules</a>
57
- <a href="#configure">7. 配置流程与挂载</a>
58
- <a href="#init">8. 项目初始化(init)</a>
59
- <a href="#start">9. 如何开始一个任务</a>
60
- <a href="#run">10. 流程如何逐阶段执行</a>
61
- <a href="#state">11. 任务状态如何记录进度</a>
62
- <a href="#verify">12. 验证、评审与提交</a>
63
- <a href="#example">13. 一个标准任务的完整走查</a>
64
- <a href="#boundaries">14. 边界与常见问题</a>
65
- </nav>
66
-
67
- <main>
68
- <section id="overview">
69
- <h2>1. 工作原理</h2>
70
- <p>开发者在「工程化开发引擎」会话里提出开发请求后,统一由 <code>dev_task</code> 工具接管,再由编排技能 <code>eng-delivery</code> 读任务状态、按当前阶段推进,一个阶段一个阶段地走。</p>
71
- <pre><code>开发请求
72
- → dev_task(统一入口,硬约束在代码里执行)
73
- → eng-delivery(编排:读状态 → 选阶段 → 推进)
74
- → 需求评审 · requirement-analysis
75
- → 设计 · solution-design
76
- → 开发 · code-implement
77
- → 交付 · code-verify + code-commit
78
- → 代码审核 · code-review</code></pre>
79
- <div class="callout">
80
- <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时,才触发 <code>dev_task</code> 和这套门禁;换到别的预设,流程完全不介入。</p>
81
- </div>
82
- <p>三样东西分工明确:<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」,<strong>Skill</strong> 决定「这一站做什么」,<strong>Rule</strong> 决定「这一站守什么」。任务状态单独落盘,负责「跨会话恢复到哪一步」。</p>
83
- <div class="callout warn">
84
- <p><strong>诚实边界:</strong>阶段流转、提交格式、文件范围、消息里的任务绑定、流程快照 hash、钩子完整性、敏感路径风险策略是<b>代码硬校验</b>(不匹配直接拒绝);<b>高风险任务的「验证通过」也是真实命令回执</b>——引擎实际运行 <code>verify</code> 命令、取退出码(<code>exit_code === 0</code> 且非超时/中止)才放行,不是模型自报。仍属模型自报、需人工或 CI 兜底的是:常规风险的验证声明、「评审通过」「实施项完成」,以及回执命令本身的覆盖面。只有「需求确认」「方案确认」两扇门由人工批准点亮,风险降级(high_risk → standard)也由人工批准。</p>
85
- </div>
86
- </section>
87
-
88
- <section id="install">
89
- <h2>2. 安装与启用</h2>
90
- <h3>2.1 前置:Node.js ≥ 22 + pnpm</h3>
91
- <pre><code>npm install -g pnpm # dsh 的 plugin 子命令底层转发给 pnpm,必须先装</code></pre>
92
- <h3>2.2 先装 DSH(三选一)</h3>
93
- <pre><code># 方式 A:npm 装 CLI(非源码,推荐给使用者)
94
- npm install -g @deepseek-ai/dsh
95
- dsh web
96
-
97
- # 方式 B:npx 免安装直接跑
98
- npx @deepseek-ai/dsh web
99
-
100
- # 方式 C:从源码 clone(开发者)
101
- git clone https://github.com/deepseek-ai/deepseek-harness.git
102
- cd deepseek-harness
103
- pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
104
- <h3>2.3 把引擎插件装进 profile</h3>
105
- <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
106
- <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>
107
- <p>装完<b>重启 <code>dsh web</code></b> 生效,自动完成两件事:侧边栏多出「工程流程」工作台;预设列表多出「工程化开发引擎」。</p>
108
- <h3>2.4 启用</h3>
109
- <p>新建会话 → 预设选「工程化开发引擎」。这个会话就挂上 <code>dev_task</code> + 内置技能 + 工程人设,开始按流程走。</p>
110
- <div class="callout"><p>想「正式开发」就选它;想「让 AI 自由探索」就选 <code>standard</code>。切换预设本身就是开关,零配置。</p></div>
111
- </section>
112
-
113
- <section id="structure">
114
- <h2>3. 文件与目录</h2>
115
- <pre><code>D:\workspace\
116
- ├─ AGENTS.md ← init 生成的项目描述(DSH 每会话自动注入)
117
- ├─ .dsh\
118
- │ ├─ eng.json ← 流程预设 + 节点挂载(团队共享,可进 git)
119
- │ ├─ skills\ ← 项目级 skill
120
- │ ├─ rules\ ← 项目级 rule
121
- │ └─ task-*.json ← 每个任务的状态快照
122
- └─ $DSH_HOME\
123
- ├─ skills\ ← 用户级 skill(个人所有项目通用)
124
- └─ rules\ ← 用户级 rule</code></pre>
125
- <div class="table-wrap">
126
- <table>
127
- <thead><tr><th>路径</th><th>作用</th><th>何时读取或修改</th></tr></thead>
128
- <tbody>
129
- <tr><td><code>.dsh/eng.json</code></td><td>声明用哪套流程 + 每个节点挂哪些 skill / rule</td><td>任务推进前读取;工作台保存时写入</td></tr>
130
- <tr><td><code>.dsh/skills/</code></td><td>项目级 skill(团队共享)</td><td>节点挂载命中时按需读取</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>同名时让位于内置(内置 &gt; 用户 &gt; 项目)</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>每个内置 Skill 尺寸很小、只做一件事。挂到对应节点后,走到那一步才加载,不会一次性全塞给模型。</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
- <tr><td><code>requirement-analysis</code></td><td>目标、验收、非目标,落需求说明,等人确认</td><td>编码</td></tr>
168
- <tr><td><code>solution-design</code></td><td>最小方案、技术基线、改动点,落设计文档</td><td>实现</td></tr>
169
- <tr><td><code>code-implement</code></td><td>实现、做「规格 + 质量」两阶段评审,都过才标完成</td><td>无关重构</td></tr>
170
- <tr><td><code>code-verify</code></td><td>按验收与风险验证、记录结果(高风险必须跑真实命令回执)</td><td>掩盖失败或自动修复</td></tr>
171
- <tr><td><code>code-commit</code></td><td>校验阶段、范围、消息格式后提交</td><td>远程 push / 合并 / 发布</td></tr>
172
- <tr><td><code>code-review</code></td><td>评审变更,落结论与问题清单</td><td>代替实现或验证</td></tr>
173
- </tbody>
174
- </table>
175
- </div>
176
- </section>
177
-
178
- <section id="rules">
179
- <h2>6. Rules:这一步守什么</h2>
180
- <p>Rule 是纯正文的约束,只有挂在节点上、且走到那一步时才读。内置三条:</p>
181
- <div class="table-wrap">
182
- <table>
183
- <thead><tr><th>Rule</th><th>约束内容</th><th>典型触发</th></tr></thead>
184
- <tbody>
185
- <tr><td><code>coding-conventions</code></td><td>编码规范:复用优先、禁空 catch、禁全表更新等</td><td>写代码</td></tr>
186
- <tr><td><code>commit-conventions</code></td><td>提交消息格式、只提交任务内文件、禁止 push / 合并 / 发布</td><td>本地提交</td></tr>
187
- <tr><td><code>security-redlines</code></td><td>敏感数据、危险动作和权限边界</td><td>所有写操作</td></tr>
188
- </tbody>
189
- </table>
190
- </div>
191
- <p>最重要的轻量原则:团队想改「提交消息格式」「交付要自测」这类约定,新建一个项目级规则 / 技能(用<b>新名字</b>)再挂到对应节点,而不是改一堆参数;内置 skill / rule 的正文<b>不可被同名覆盖</b>。</p>
192
- </section>
193
-
194
- <section id="configure">
195
- <h2>7. 配置流程与挂载</h2>
196
- <p>侧边栏点「工程流程」打开工作台,五个标签页:<strong>项目初始化 / 流程配置 / 任务 / 技能 skill / 规则 rule</strong>,默认落在「项目初始化」(详见第 8 节)。日常配流程只需在「流程配置」页做两件事:</p>
197
- <ol>
198
- <li><strong>选流程预设</strong>:standard / agile / minimal 点一下即切。</li>
199
- <li><strong>给节点挂 skill / rule</strong>:先选一个节点(如「开发」),再勾选它用什么 skill、守哪条 rule,保存。</li>
200
- </ol>
201
- <p>「技能」页支持新建 / <b>安装</b> / 查看 / 编辑 / 删除:内置资源只读(正文以 markdown 富文本渲染);项目级 / 用户级资源可编辑、可删除(两步确认)。「安装 skill」把本机已有的<b>目录型 skill</b>(含 <code>SKILL.md</code>,可带 references / scripts 等文件)一键装到项目级(工作区 <code>.dsh/skills</code>,团队共享)或用户级(<code>$DSH_HOME/skills</code>,个人所有项目可用);自动排除 node_modules / <code>.git</code> / <code>__pycache__</code> 等缓存,同名内置或已装技能拒绝覆盖。</p>
202
- <pre><code>// .dsh/eng.json 等价内容
203
- {
204
- "flow": "standard",
205
- "stage_bindings": {
206
- "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
207
- "开发": { "skills": ["code-implement"], "rules": ["coding-conventions"] }
208
- }
209
- }</code></pre>
210
- <div class="callout warn"><p>页面实时校验:挂到不存在的阶段、空名等会红字提示并置灰保存;保存前主机再校验一遍。错误的配置存不进去。</p></div>
211
- <p>三层来源与优先级:同名 skill / rule,<strong>内置 &gt; 用户 &gt; 项目</strong>——内置不可被同名覆盖(新建同名会被拒,解析同名只读内置版)。要加团队约定,新建一个<b>不同名</b>的项目级 / 用户级资源再挂到节点上。</p>
212
- </section>
213
-
214
- <section id="init">
215
- <h2>8. 项目初始化(init)</h2>
216
- <p>二开 / 遗留项目没有文档时,先给项目建一份「描述文件」——项目根的 <code>AGENTS.md</code>。DSH 平台会把它<b>自动注入到每个会话</b>,生成一次,之后每个任务开工 AI 都自带这份项目认知(项目是什么 → 怎么跑 → 结构 → 约定 → 坑)。</p>
217
- <div class="callout"><p><strong>两种入口,推荐工作台:</strong>① 工作台「项目初始化」标签页(点按钮,可视化预览 + 保存,0.19.0 起,默认第一个标签页);② 对话式 init(对 AI 说「帮我初始化这个项目」,AI 调 <code>dev_task</code> 走 inspect → propose → apply)。</p></div>
218
-
219
- <h3>工作台初始化(推荐)</h3>
220
- <ol>
221
- <li>侧边栏点「工程流程」,工作台<b>默认落在「项目初始化」标签页</b>。</li>
222
- <li><b>先看已有文档</b>:顶部显示「未初始化」或「已初始化 · N 行(上限 200)」。工作区根没有 <code>AGENTS.md</code> 时,会自动向下找唯一子项目、向上找父目录,并把实际定位路径标出来(如 <code>已定位到 D:\qdmai\qms\AGENTS.md</code>)。</li>
223
- <li><b>让 AI 初始化</b>:点按钮,AI 扫描项目(目录结构、关键文件、技术栈、构建 / 运行命令、约定与红线)生成草稿——<b>只预览、不落盘</b>,硬校验<b>行数 ≤ 200 行</b>,超了精简到「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」,只留骨架不塞长文。运行中实时显示「已耗时 X 秒」,最长 150 秒超时,超时提示重试即可。</li>
224
- <li><b>保存 / 保存并覆盖</b>:预览满意点「保存」——首次创建直接写入;已有 <code>AGENTS.md</code> 会标「保存并覆盖」,必须人工点确认才覆盖,保护项目已有治理文件不被裸覆盖。</li>
225
- <li>也可点「手动编辑」直接改正文后保存。</li>
226
- </ol>
227
-
228
- <h3>对话式 init</h3>
229
- <ol>
230
- <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>
231
- <li><b>propose</b>:AI 写成 <code>AGENTS.md</code> 草稿,此步<b>只预览、不落盘</b>,同样硬校验<b>行数 ≤ 200 行</b>,并返回内容 hash。</li>
232
- <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>
233
- </ol>
234
- <pre><code>项目根/
235
- ├─ AGENTS.md ← init 生成,DSH 每会话自动注入
236
- └─ .dsh/
237
- ├─ eng.json ← flow + verify_command(可覆盖语言默认验证命令)
238
- ├─ skills/ · rules/
239
- └─ task-*.json</code></pre>
240
- </section>
241
-
242
- <section id="start">
243
- <h2>9. 如何开始一个任务</h2>
244
- <ol>
245
- <li>新建会话,预设选「工程化开发引擎」。</li>
246
- <li>直接描述需求(加功能 / 修 bug)。</li>
247
- <li>AI 建任务、判 <code>work_size</code> 与 <code>risk_level</code>,停在起始阶段(标准流程是「需求评审」)。</li>
248
- <li>AI 落需求说明,需要拍板处发起审批,你点「允许」才进入下一步。</li>
249
- <li>之后一个阶段一个阶段推进,直到「完成」。</li>
250
- </ol>
251
- <div class="flow">
252
- <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>
253
- </div>
254
- </section>
255
-
256
- <section id="run">
257
- <h2>10. 流程如何逐阶段执行</h2>
258
- <div class="table-wrap">
259
- <table>
260
- <thead><tr><th>阶段</th><th>AI 在这一站做什么</th><th>过关条件(不满足不让走)</th></tr></thead>
261
- <tbody>
262
- <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全,且<b>人点「允许」确认需求</b></td></tr>
263
- <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全,且<b>人点「允许」确认方案</b></td></tr>
264
- <tr><td>开发</td><td>逐项实现,每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done(每项带两阶段评审)</td></tr>
265
- <tr><td>交付</td><td>验证、记证据,按门禁提交</td><td>验证通过(高风险必须真实命令回执,退出码 0)</td></tr>
266
- <tr><td>代码审核</td><td>评审变更,落「评审记录」</td><td>结论通过且字段填全</td></tr>
267
- <tr><td>完成</td><td>收尾</td><td>—</td></tr>
268
- </tbody>
269
- </table>
270
- </div>
271
- <h3>贯穿全程的硬规则</h3>
272
- <ul>
273
- <li>阶段是硬状态:status 说你在哪,就只做那一步,绝不倒带重走、绝不跳。</li>
274
- <li>确认只能人来做:需求确认、方案确认由 AI 发起审批,你在页面点「允许」;AI 不能自己通过、不能绕过。</li>
275
- <li>渐进披露:走到哪个阶段,才加载那一段的 skill / rule。</li>
276
- </ul>
277
- </section>
278
-
279
- <section id="state">
280
- <h2>11. 任务状态如何记录进度</h2>
281
- <p>每个任务一份 <code>.dsh/task-*.json</code>,只保存当前有效状态,不保存聊天全文和流水日志。</p>
282
- <div class="table-wrap">
283
- <table>
284
- <thead><tr><th>字段</th><th>含义</th></tr></thead>
285
- <tbody>
286
- <tr><td><code>id / title</code></td><td>任务标识与标题</td></tr>
287
- <tr><td><code>branch</code></td><td>所属功能分支;恢复时以真实当前分支为准</td></tr>
288
- <tr><td><code>stage</code></td><td>当前阶段(决定下一步做什么、能往哪走)</td></tr>
289
- <tr><td><code>work_size</code></td><td>tiny / standard / complex,决定拆多细</td></tr>
290
- <tr><td><code>risk_level</code></td><td>standard / high_risk,决定验证强度</td></tr>
291
- <tr><td><code>requirement_confirmed</code></td><td>需求是否已由人确认</td></tr>
292
- <tr><td><code>solution_confirmed</code></td><td>方案是否已由人确认</td></tr>
293
- <tr><td><code>verification</code></td><td>验证是否通过 + 证据(高风险附真实命令回执)</td></tr>
294
- <tr><td><code>review</code></td><td>评审结论(通过 / 未过 + 问题)</td></tr>
295
- <tr><td><code>files</code></td><td>本任务允许修改的文件范围</td></tr>
296
- <tr><td><code>commits</code></td><td>已创建的提交记录</td></tr>
297
- </tbody>
298
- </table>
299
- </div>
300
- <p>会话断了没关系:重新开会话,AI 读 <code>stage</code>、确认态、验证与评审字段,就能从断点继续,不依赖上一轮聊天。</p>
301
- </section>
302
-
303
- <section id="verify">
304
- <h2>12. 验证、评审与提交</h2>
305
- <h3>验证为什么不该总那么慢</h3>
306
- <ul>
307
- <li>实施中优先受影响模块的编译、目标测试与静态检查。</li>
308
- <li>差异没变时复用有效证据,不重复跑相同命令。</li>
309
- <li>无法联调外部系统时必须如实写「未联调」,不能把编译成功说成功能通过。</li>
310
- <li><code>high_risk</code> 任务过验证门必须跑真实命令回执(引擎运行命令、取退出码,非自报通过)。</li>
311
- <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>
312
- <li><b>验证命令始终在任务记录的项目根运行</b>(任务创建时自动发现并固化 <code>root</code>),不是会话当前目录——monorepo 里会话停在子目录时,<code>npm test</code> 等也会在放清单文件的项目根执行;回执记录的 <code>root</code> 与任务根强校验,不一致直接拒绝。</li>
313
- </ul>
314
- <h3>评审</h3>
315
- <p>开发阶段每项做「规格 + 质量」两阶段评审,都 pass 才标 done;缺评审或任一阶段 fail 会挡住「开发 → 交付」。</p>
316
- <h3>提交策略</h3>
317
- <div class="table-wrap">
318
- <table>
319
- <thead><tr><th>策略</th><th>何时提交</th><th>标识</th></tr></thead>
320
- <tbody>
321
- <tr><td><code>task</code></td><td>整项验证、评审通过后一次提交</td><td><code>TASK</code></td></tr>
322
- <tr><td><code>item</code></td><td>每个独立项验证后提交;整项完成再提最终状态</td><td><code>Tn</code>,最终 <code>TASK</code></td></tr>
323
- <tr><td><code>manual</code></td><td>等用户明确要求才提交</td><td>用户指定</td></tr>
324
- </tbody>
325
- </table>
326
- </div>
327
- <p>提交消息要求 <code>【模块】【TASK】做了什么</code>,且只提交任务 <code>files</code> 范围内的文件。要彻底封死模型绕过 <code>dev_task</code> 直接 <code>git commit</code>,给仓库装一道机械钩子:</p>
328
- <pre><code>dev_task operation=install_hook # 装入 .git/hooks/commit-msg,装上后任何 git commit 都被同一套规则校验
329
- dev_task operation=verify_hook # 随时比对安装钩子与内置门禁的 hash,被替换/篡改立即报错</code></pre>
330
- <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>
331
- <p><strong>风险降级(0.22):</strong><code>set_risk</code> 把 <code>high_risk</code> 降为 <code>standard</code> 必须人工批准,并写入任务的 <code>risk_downgrades</code> 审计记录;降级后高风险回执门不再适用,请谨慎。</p>
332
- </section>
333
-
334
- <section id="example">
335
- <h2>13. 一个标准任务的完整走查</h2>
336
- <p>假设需求是「给现有查询接口加一个权限校验」。标准流程下,关键决策点应接近下面这样:</p>
337
- <pre><code>flow: standard // 项目预设
338
- work_size: standard // 数个文件 + 权限判断
339
- risk_level: high_risk // 涉及鉴权,验证要加证据
340
-
341
- ① 需求评审
342
- - 目标:无权限返回 403;有权限正常返回。
343
- - 验收、非目标写清 → 【人确认需求】
344
-
345
- ② 设计
346
- - 最小方案:Controller 加校验、Service 复用现有鉴权方法。
347
- - 不新建接口 / DTO / 异常包装 → 【人确认方案】
348
-
349
- ③ 开发
350
- - T1:接口加校验 + 编写无权限 / 有权限用例。
351
- - 规格 ✓ 质量 ✓ → done
352
-
353
- ④ 交付
354
- - 验证:跑鉴权用例,`verify` 传真实命令(high_risk 由引擎取退出码判定)。
355
- - 提交:【模块】【TASK】查询接口增加权限校验(只含本任务文件)
356
-
357
- ⑤ 代码审核
358
- - 结论:通过 · 问题:无
359
-
360
- ⑥ 完成</code></pre>
361
- <p>这类任务不应因为「以后可能复用」扩展成多层架构,也不应把推荐项自动当成验收条件。</p>
362
- </section>
363
-
364
- <section id="boundaries">
365
- <h2>14. 边界与常见问题</h2>
366
- <div class="callout danger">
367
- <p>引擎只允许:读取仓库事实、修改<b>已确认任务范围内</b>的文件、按策略创建<b>范围受控的本地提交</b>。远程 push / 合并 / 发布、数据库写入,需人单独决定。</p>
368
- </div>
369
- <details open><summary>切换预设就是开关吗?</summary><div>是。选「工程化开发引擎」才挂 <code>dev_task</code> 和内置技能;选 <code>standard</code> 等其它预设则完全不介入。</div></details>
370
- <details><summary>想改内置 skill / rule 怎么办?</summary><div>内置正文不可被同名覆盖(同名新建会被拒)。要加团队约定,新建一个<b>不同名</b>的项目级 skill / rule 再挂到对应节点,与内置并存。</div></details>
371
- <details><summary>任务文档要不要提交?</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实,随分支提交——引擎已豁免 <code>.dsh/task-*.json</code> 与 <code>.dsh/eng.json</code>,不受文件范围门拦截;忽略它别人只能看到代码,看不到确认内容和进度。</div></details>
372
- <details><summary>一个会话能同时做两个需求吗?</summary><div>一个任务对应一份状态文档、一个分支。新需求保存当前进度后切新分支,切回原分支即可恢复。</div></details>
373
- <details><summary>提交被拒是怎么回事?</summary><div>通常是四类:没建 dev_task 任务、阶段没到提交检查点、消息格式不符、提交文件不在任务范围内。按拒绝原因修正即可。</div></details>
374
- <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> 替换或直接手改 task 记录。<b>最终可信门禁在 CI</b>:CI 里重新校验 task id、快照 hash、staged 范围、提交消息、真实验证退出码、高风险回执,并检测钩子是否被绕过。三层分工:钩子 = 本地反馈,host 工具流 = 正常路径强约束,CI = 最终验证。</div></details>
375
- <details><summary>任务记录被手改会怎样?</summary><div>引擎会拒绝:任务创建时把流程配置固化成 SHA-256 快照,工具和钩子每次读任务记录都校验——<b>被改过的快照一律拒绝继续</b>(提示修复或重建任务)。另外每次写入带 <code>revision</code> 版本号做 compare-and-swap,多个会话同时改同一任务会报「changed concurrently」而不是静默互相覆盖。</div></details>
376
- <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>
377
- <details><summary>「完成」等于上线了吗?</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过;上线、合并、发布需人另行决定。</div></details>
378
- <p class="stamp">当前结构基线:三套流程预设 · 工作台项目初始化(0.19.0)· 通用项目适配(0.21.0)· 审计与发布质量(0.22.0)· 可信边界加固(0.22.3)· 并发与发布闭环(0.22.4)· 最后更新:2026-09-14</p>
379
- </section>
380
- </main>
381
- </div>
382
- </body>
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 里的工程流程约束。它把「需求评审 → 设计 → 开发 → 交付 → 代码审核」做成硬门槛:阶段不能跳、关键节点必须人来拍板、验证和提交都被机械检查。团队只选一套流程,再给每个节点挂上合适的 skill 和 rule。</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="#overview">1. 工作原理</a>
52
+ <a href="#install">2. 安装与启用</a>
53
+ <a href="#structure">3. 文件与目录</a>
54
+ <a href="#flows">4. 三套流程预设</a>
55
+ <a href="#skills">5. Skills</a>
56
+ <a href="#rules">6. Rules</a>
57
+ <a href="#configure">7. 配置流程与挂载</a>
58
+ <a href="#init">8. 项目初始化(init)</a>
59
+ <a href="#start">9. 如何开始一个任务</a>
60
+ <a href="#run">10. 流程如何逐阶段执行</a>
61
+ <a href="#state">11. 任务状态如何记录进度</a>
62
+ <a href="#verify">12. 验证、评审与提交</a>
63
+ <a href="#example">13. 一个标准任务的完整走查</a>
64
+ <a href="#boundaries">14. 边界与常见问题</a>
65
+ </nav>
66
+
67
+ <main>
68
+ <section id="overview">
69
+ <h2>1. 工作原理</h2>
70
+ <p>开发者在「工程化开发引擎」会话里提出开发请求后,统一由 <code>dev_task</code> 工具接管,再由编排技能 <code>eng-delivery</code> 读任务状态、按当前阶段推进,一个阶段一个阶段地走。</p>
71
+ <pre><code>开发请求
72
+ → dev_task(统一入口,硬约束在代码里执行)
73
+ → eng-delivery(编排:读状态 → 选阶段 → 推进)
74
+ → 需求评审 · requirement-analysis
75
+ → 设计 · solution-design
76
+ → 开发 · code-implement
77
+ → 交付 · code-verify + code-commit
78
+ → 代码审核 · code-review</code></pre>
79
+ <div class="callout">
80
+ <p><strong>它不是常驻程序。</strong>只有你在「工程化开发引擎」预设的会话里提出开发请求时,才触发 <code>dev_task</code> 和这套门禁;换到别的预设,流程完全不介入。</p>
81
+ </div>
82
+ <p>三样东西分工明确:<strong>流程预设</strong>决定「走哪条流水线、有哪些守卫」,<strong>Skill</strong> 决定「这一站做什么」,<strong>Rule</strong> 决定「这一站守什么」。任务状态单独落盘,负责「跨会话恢复到哪一步」。</p>
83
+ <div class="callout warn">
84
+ <p><strong>诚实边界:</strong>阶段流转、提交格式、文件范围、消息里的任务绑定、流程快照 hash、钩子完整性、敏感路径风险策略是<b>代码硬校验</b>(不匹配直接拒绝);<b>高风险任务的「验证通过」也是真实命令回执</b>——引擎实际运行 <code>verify</code> 命令、取退出码(<code>exit_code === 0</code> 且非超时/中止)才放行,不是模型自报。仍属模型自报、需人工或 CI 兜底的是:常规风险的验证声明、「评审通过」「实施项完成」,以及回执命令本身的覆盖面。只有「需求确认」「方案确认」两扇门由人工批准点亮,风险降级(high_risk → standard)也由人工批准。</p>
85
+ </div>
86
+ </section>
87
+
88
+ <section id="install">
89
+ <h2>2. 安装与启用</h2>
90
+ <h3>2.1 前置:Node.js ≥ 22 + pnpm</h3>
91
+ <pre><code>npm install -g pnpm # dsh 的 plugin 子命令底层转发给 pnpm,必须先装</code></pre>
92
+ <h3>2.2 先装 DSH(三选一)</h3>
93
+ <pre><code># 方式 A:npm 装 CLI(非源码,推荐给使用者)
94
+ npm install -g @deepseek-ai/dsh
95
+ dsh web
96
+
97
+ # 方式 B:npx 免安装直接跑
98
+ npx @deepseek-ai/dsh web
99
+
100
+ # 方式 C:从源码 clone(开发者)
101
+ git clone https://github.com/deepseek-ai/deepseek-harness.git
102
+ cd deepseek-harness
103
+ pnpm install &amp;&amp; pnpm run build &amp;&amp; pnpm dsh web</code></pre>
104
+ <h3>2.3 把引擎插件装进 profile</h3>
105
+ <pre><code>dsh plugin --profile web add @godv61/dsh-task-engine</code></pre>
106
+ <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>
107
+ <p>装完<b>重启 <code>dsh web</code></b> 生效,自动完成两件事:侧边栏多出「工程流程」工作台;预设列表多出「工程化开发引擎」。</p>
108
+ <h3>2.4 启用</h3>
109
+ <p>新建会话 → 预设选「工程化开发引擎」。这个会话就挂上 <code>dev_task</code> + 内置技能 + 工程人设,开始按流程走。</p>
110
+ <div class="callout"><p>想「正式开发」就选它;想「让 AI 自由探索」就选 <code>standard</code>。切换预设本身就是开关,零配置。</p></div>
111
+ </section>
112
+
113
+ <section id="structure">
114
+ <h2>3. 文件与目录</h2>
115
+ <pre><code>D:\workspace\
116
+ ├─ AGENTS.md ← init 生成的项目描述(DSH 每会话自动注入)
117
+ ├─ .dsh\
118
+ │ ├─ eng.json ← 流程预设 + 节点挂载(团队共享,可进 git)
119
+ │ ├─ skills\ ← 项目级 skill
120
+ │ ├─ rules\ ← 项目级 rule
121
+ │ └─ task-*.json ← 每个任务的状态快照
122
+ └─ $DSH_HOME\
123
+ ├─ skills\ ← 用户级 skill(个人所有项目通用)
124
+ └─ rules\ ← 用户级 rule</code></pre>
125
+ <div class="table-wrap">
126
+ <table>
127
+ <thead><tr><th>路径</th><th>作用</th><th>何时读取或修改</th></tr></thead>
128
+ <tbody>
129
+ <tr><td><code>.dsh/eng.json</code></td><td>声明用哪套流程 + 每个节点挂哪些 skill / rule</td><td>任务推进前读取;工作台保存时写入</td></tr>
130
+ <tr><td><code>.dsh/skills/</code></td><td>项目级 skill(团队共享)</td><td>节点挂载命中时按需读取</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>同名时让位于内置(内置 &gt; 用户 &gt; 项目)</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>每个内置 Skill 尺寸很小、只做一件事。挂到对应节点后,走到那一步才加载,不会一次性全塞给模型。</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
+ <tr><td><code>requirement-analysis</code></td><td>目标、验收、非目标,落需求说明,等人确认</td><td>编码</td></tr>
168
+ <tr><td><code>solution-design</code></td><td>最小方案、技术基线、改动点,落设计文档</td><td>实现</td></tr>
169
+ <tr><td><code>code-implement</code></td><td>实现、做「规格 + 质量」两阶段评审,都过才标完成</td><td>无关重构</td></tr>
170
+ <tr><td><code>code-verify</code></td><td>按验收与风险验证、记录结果(高风险必须跑真实命令回执)</td><td>掩盖失败或自动修复</td></tr>
171
+ <tr><td><code>code-commit</code></td><td>校验阶段、范围、消息格式后提交</td><td>远程 push / 合并 / 发布</td></tr>
172
+ <tr><td><code>code-review</code></td><td>评审变更,落结论与问题清单</td><td>代替实现或验证</td></tr>
173
+ </tbody>
174
+ </table>
175
+ </div>
176
+ </section>
177
+
178
+ <section id="rules">
179
+ <h2>6. Rules:这一步守什么</h2>
180
+ <p>Rule 是纯正文的约束,只有挂在节点上、且走到那一步时才读。内置三条:</p>
181
+ <div class="table-wrap">
182
+ <table>
183
+ <thead><tr><th>Rule</th><th>约束内容</th><th>典型触发</th></tr></thead>
184
+ <tbody>
185
+ <tr><td><code>coding-conventions</code></td><td>编码规范:复用优先、禁空 catch、禁全表更新等</td><td>写代码</td></tr>
186
+ <tr><td><code>commit-conventions</code></td><td>提交消息格式、只提交任务内文件、禁止 push / 合并 / 发布</td><td>本地提交</td></tr>
187
+ <tr><td><code>security-redlines</code></td><td>敏感数据、危险动作和权限边界</td><td>所有写操作</td></tr>
188
+ </tbody>
189
+ </table>
190
+ </div>
191
+ <p>最重要的轻量原则:团队想改「提交消息格式」「交付要自测」这类约定,新建一个项目级规则 / 技能(用<b>新名字</b>)再挂到对应节点,而不是改一堆参数;内置 skill / rule 的正文<b>不可被同名覆盖</b>。</p>
192
+ </section>
193
+
194
+ <section id="configure">
195
+ <h2>7. 配置流程与挂载</h2>
196
+ <p>侧边栏点「工程流程」打开工作台,五个标签页:<strong>项目初始化 / 流程配置 / 任务 / 技能 skill / 规则 rule</strong>,默认落在「项目初始化」(详见第 8 节)。日常配流程只需在「流程配置」页做两件事:</p>
197
+ <ol>
198
+ <li><strong>选流程预设</strong>:standard / agile / minimal 点一下即切。</li>
199
+ <li><strong>给节点挂 skill / rule</strong>:先选一个节点(如「开发」),再勾选它用什么 skill、守哪条 rule,保存。</li>
200
+ </ol>
201
+ <p>「技能」和「规则」页提供搜索、来源筛选、新建、安装、查看、编辑与删除。内置资源只读。点「安装技能」直接打开系统文件选择器,选择含 <code>SKILL.md</code> 的文件夹;点「安装规则」选择一个 <code>.md</code> 文件。选择后先显示预览:名称、正文、文件数、体积、目标路径和同名冲突。确认项目或个人范围后点击「确认安装」;预览本身不写入文件,改变范围后需要重新预览。</p>
202
+ <p>项目资源写入工作区 <code>.dsh/skills</code> 或 <code>.dsh/rules</code>;个人资源写入 <code>$DSH_HOME</code> 对应目录。浏览器选择的是浏览器所在电脑的文件;高级目录模式读取 Harness 主机的目录。技能保留脚本、references、模板和二进制资源,排除常见缓存;上限 1000 文件、100 MB、单文件 20 MB、20 层目录,<code>SKILL.md</code> 和规则正文上限 1 MB。拒绝覆盖同名资源;主机扫描拒绝符号链接和 junction。浏览器上传不提供源链接元数据。</p>
203
+ <p>资源删除前会显示名称与实际目标路径,确认后永久删除;可点击「保留」取消。任务台账支持搜索、风险与阶段筛选,并显示验证、审核和更新时间。流程配置读取与保存失败时显示错误,损坏任务记录不会被静默视为没有任务。</p>
204
+ <pre><code>// .dsh/eng.json 等价内容
205
+ {
206
+ "flow": "standard",
207
+ "stage_bindings": {
208
+ "需求评审": { "skills": ["requirement-analysis"], "rules": ["security-redlines"] },
209
+ "开发": { "skills": ["code-implement"], "rules": ["coding-conventions"] }
210
+ }
211
+ }</code></pre>
212
+ <div class="callout warn"><p>页面实时校验:挂到不存在的阶段、空名等会红字提示并置灰保存;保存前主机再校验一遍。错误的配置存不进去。</p></div>
213
+ <p>三层来源与优先级:同名 skill / rule,<strong>内置 &gt; 用户 &gt; 项目</strong>——内置不可被同名覆盖(新建同名会被拒,解析同名只读内置版)。要加团队约定,新建一个<b>不同名</b>的项目级 / 用户级资源再挂到节点上。</p>
214
+ </section>
215
+
216
+ <section id="init">
217
+ <h2>8. 项目初始化(init)</h2>
218
+ <p>二开 / 遗留项目没有文档时,先给项目建一份「描述文件」——项目根的 <code>AGENTS.md</code>。DSH 平台会把它<b>自动注入到每个会话</b>,生成一次,之后每个任务开工 AI 都自带这份项目认知(项目是什么 → 怎么跑 → 结构 → 约定 → 坑)。</p>
219
+ <div class="callout"><p><strong>两种入口,推荐工作台:</strong>① 工作台「项目初始化」标签页(点按钮,可视化预览 + 保存,0.19.0 起,默认第一个标签页);② 对话式 init(对 AI 说「帮我初始化这个项目」,AI 调 <code>dev_task</code> 走 inspect → propose → apply)。</p></div>
220
+
221
+ <h3>工作台初始化(推荐)</h3>
222
+ <ol>
223
+ <li>侧边栏点「工程流程」,工作台<b>默认落在「项目初始化」标签页</b>。</li>
224
+ <li><b>先看已有文档</b>:顶部显示「未初始化」或「已初始化 · N 行(上限 200)」。工作区根没有 <code>AGENTS.md</code> 时,会自动向下找唯一子项目、向上找父目录,并把实际定位路径标出来(如 <code>已定位到 D:\qdmai\qms\AGENTS.md</code>)。</li>
225
+ <li><b>让 AI 初始化</b>:点按钮,AI 扫描项目(目录结构、关键文件、技术栈、构建 / 运行命令、约定与红线)生成草稿——<b>只预览、不落盘</b>,硬校验<b>行数 ≤ 200 行</b>,超了精简到「项目是什么 → 怎么跑 → 结构 → 约定 → 坑」,只留骨架不塞长文。运行中实时显示「已耗时 X 秒」,最长 150 秒超时,超时提示重试即可。</li>
226
+ <li><b>保存 / 保存并覆盖</b>:预览满意点「保存」——首次创建直接写入;已有 <code>AGENTS.md</code> 会标「保存并覆盖」,必须人工点确认才覆盖,保护项目已有治理文件不被裸覆盖。</li>
227
+ <li>也可点「手动编辑」直接改正文后保存。</li>
228
+ </ol>
229
+
230
+ <h3>对话式 init</h3>
231
+ <ol>
232
+ <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>
233
+ <li><b>propose</b>:AI 写成 <code>AGENTS.md</code> 草稿,此步<b>只预览、不落盘</b>,同样硬校验<b>行数 ≤ 200 行</b>,并返回内容 hash。</li>
234
+ <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>
235
+ </ol>
236
+ <pre><code>项目根/
237
+ ├─ AGENTS.md ← init 生成,DSH 每会话自动注入
238
+ └─ .dsh/
239
+ ├─ eng.json ← flow + verify_command(可覆盖语言默认验证命令)
240
+ ├─ skills/ · rules/
241
+ └─ task-*.json</code></pre>
242
+ </section>
243
+
244
+ <section id="start">
245
+ <h2>9. 如何开始一个任务</h2>
246
+ <ol>
247
+ <li>新建会话,预设选「工程化开发引擎」。</li>
248
+ <li>直接描述需求(加功能 / 修 bug)。</li>
249
+ <li>AI 建任务、判 <code>work_size</code> 与 <code>risk_level</code>,停在起始阶段(标准流程是「需求评审」)。</li>
250
+ <li>AI 落需求说明,需要拍板处发起审批,你点「允许」才进入下一步。</li>
251
+ <li>之后一个阶段一个阶段推进,直到「完成」。</li>
252
+ </ol>
253
+ <div class="flow">
254
+ <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>
255
+ </div>
256
+ </section>
257
+
258
+ <section id="run">
259
+ <h2>10. 流程如何逐阶段执行</h2>
260
+ <div class="table-wrap">
261
+ <table>
262
+ <thead><tr><th>阶段</th><th>AI 在这一站做什么</th><th>过关条件(不满足不让走)</th></tr></thead>
263
+ <tbody>
264
+ <tr><td>需求评审</td><td>拆需求、落「需求说明」</td><td>字段填全,且<b>人点「允许」确认需求</b></td></tr>
265
+ <tr><td>设计</td><td>出最小方案、落「设计文档」</td><td>字段填全,且<b>人点「允许」确认方案</b></td></tr>
266
+ <tr><td>开发</td><td>逐项实现,每项做规格 + 质量两阶段评审</td><td>实施项非空且全部 done(每项带两阶段评审)</td></tr>
267
+ <tr><td>交付</td><td>验证、记证据,按门禁提交</td><td>验证通过(高风险必须真实命令回执,退出码 0)</td></tr>
268
+ <tr><td>代码审核</td><td>评审变更,落「评审记录」</td><td>结论通过且字段填全</td></tr>
269
+ <tr><td>完成</td><td>收尾</td><td>—</td></tr>
270
+ </tbody>
271
+ </table>
272
+ </div>
273
+ <h3>贯穿全程的硬规则</h3>
274
+ <ul>
275
+ <li>阶段是硬状态:status 说你在哪,就只做那一步,绝不倒带重走、绝不跳。</li>
276
+ <li>确认只能人来做:需求确认、方案确认由 AI 发起审批,你在页面点「允许」;AI 不能自己通过、不能绕过。</li>
277
+ <li>渐进披露:走到哪个阶段,才加载那一段的 skill / rule。</li>
278
+ </ul>
279
+ </section>
280
+
281
+ <section id="state">
282
+ <h2>11. 任务状态如何记录进度</h2>
283
+ <p>每个任务一份 <code>.dsh/task-*.json</code>,只保存当前有效状态,不保存聊天全文和流水日志。</p>
284
+ <div class="table-wrap">
285
+ <table>
286
+ <thead><tr><th>字段</th><th>含义</th></tr></thead>
287
+ <tbody>
288
+ <tr><td><code>id / title</code></td><td>任务标识与标题</td></tr>
289
+ <tr><td><code>branch</code></td><td>所属功能分支;恢复时以真实当前分支为准</td></tr>
290
+ <tr><td><code>stage</code></td><td>当前阶段(决定下一步做什么、能往哪走)</td></tr>
291
+ <tr><td><code>work_size</code></td><td>tiny / standard / complex,决定拆多细</td></tr>
292
+ <tr><td><code>risk_level</code></td><td>standard / high_risk,决定验证强度</td></tr>
293
+ <tr><td><code>requirement_confirmed</code></td><td>需求是否已由人确认</td></tr>
294
+ <tr><td><code>solution_confirmed</code></td><td>方案是否已由人确认</td></tr>
295
+ <tr><td><code>verification</code></td><td>验证是否通过 + 证据(高风险附真实命令回执)</td></tr>
296
+ <tr><td><code>review</code></td><td>评审结论(通过 / 未过 + 问题)</td></tr>
297
+ <tr><td><code>files</code></td><td>本任务允许修改的文件范围</td></tr>
298
+ <tr><td><code>commits</code></td><td>已创建的提交记录</td></tr>
299
+ </tbody>
300
+ </table>
301
+ </div>
302
+ <p>会话断了没关系:重新开会话,AI 读 <code>stage</code>、确认态、验证与评审字段,就能从断点继续,不依赖上一轮聊天。</p>
303
+ </section>
304
+
305
+ <section id="verify">
306
+ <h2>12. 验证、评审与提交</h2>
307
+ <h3>验证为什么不该总那么慢</h3>
308
+ <ul>
309
+ <li>实施中优先受影响模块的编译、目标测试与静态检查。</li>
310
+ <li>差异没变时复用有效证据,不重复跑相同命令。</li>
311
+ <li>无法联调外部系统时必须如实写「未联调」,不能把编译成功说成功能通过。</li>
312
+ <li><code>high_risk</code> 任务过验证门必须跑真实命令回执(引擎运行命令、取退出码,非自报通过)。</li>
313
+ <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>
314
+ <li><b>验证命令始终在任务记录的项目根运行</b>(任务创建时自动发现并固化 <code>root</code>),不是会话当前目录——monorepo 里会话停在子目录时,<code>npm test</code> 等也会在放清单文件的项目根执行;回执记录的 <code>root</code> 与任务根强校验,不一致直接拒绝。</li>
315
+ </ul>
316
+ <h3>评审</h3>
317
+ <p>开发阶段每项做「规格 + 质量」两阶段评审,都 pass 才标 done;缺评审或任一阶段 fail 会挡住「开发 → 交付」。</p>
318
+ <h3>提交策略</h3>
319
+ <div class="table-wrap">
320
+ <table>
321
+ <thead><tr><th>策略</th><th>何时提交</th><th>标识</th></tr></thead>
322
+ <tbody>
323
+ <tr><td><code>task</code></td><td>整项验证、评审通过后一次提交</td><td><code>TASK</code></td></tr>
324
+ <tr><td><code>item</code></td><td>每个独立项验证后提交;整项完成再提最终状态</td><td><code>Tn</code>,最终 <code>TASK</code></td></tr>
325
+ <tr><td><code>manual</code></td><td>等用户明确要求才提交</td><td>用户指定</td></tr>
326
+ </tbody>
327
+ </table>
328
+ </div>
329
+ <p>提交消息要求 <code>【模块】【TASK】做了什么</code>,且只提交任务 <code>files</code> 范围内的文件。要彻底封死模型绕过 <code>dev_task</code> 直接 <code>git commit</code>,给仓库装一道机械钩子:</p>
330
+ <pre><code>dev_task operation=install_hook # 装入 .git/hooks/commit-msg,装上后任何 git commit 都被同一套规则校验
331
+ dev_task operation=verify_hook # 随时比对安装钩子与内置门禁的 hash,被替换/篡改立即报错</code></pre>
332
+ <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>
333
+ <p><strong>风险降级(0.22):</strong><code>set_risk</code> 把 <code>high_risk</code> 降为 <code>standard</code> 必须人工批准,并写入任务的 <code>risk_downgrades</code> 审计记录;降级后高风险回执门不再适用,请谨慎。</p>
334
+ </section>
335
+
336
+ <section id="example">
337
+ <h2>13. 一个标准任务的完整走查</h2>
338
+ <p>假设需求是「给现有查询接口加一个权限校验」。标准流程下,关键决策点应接近下面这样:</p>
339
+ <pre><code>flow: standard // 项目预设
340
+ work_size: standard // 数个文件 + 权限判断
341
+ risk_level: high_risk // 涉及鉴权,验证要加证据
342
+
343
+ ① 需求评审
344
+ - 目标:无权限返回 403;有权限正常返回。
345
+ - 验收、非目标写清 → 【人确认需求】
346
+
347
+ ② 设计
348
+ - 最小方案:Controller 加校验、Service 复用现有鉴权方法。
349
+ - 不新建接口 / DTO / 异常包装 → 【人确认方案】
350
+
351
+ ③ 开发
352
+ - T1:接口加校验 + 编写无权限 / 有权限用例。
353
+ - 规格 ✓ 质量 ✓ → done
354
+
355
+ ④ 交付
356
+ - 验证:跑鉴权用例,`verify` 传真实命令(high_risk 由引擎取退出码判定)。
357
+ - 提交:【模块】【TASK】查询接口增加权限校验(只含本任务文件)
358
+
359
+ ⑤ 代码审核
360
+ - 结论:通过 · 问题:无
361
+
362
+ ⑥ 完成</code></pre>
363
+ <p>这类任务不应因为「以后可能复用」扩展成多层架构,也不应把推荐项自动当成验收条件。</p>
364
+ </section>
365
+
366
+ <section id="boundaries">
367
+ <h2>14. 边界与常见问题</h2>
368
+ <div class="callout danger">
369
+ <p>引擎只允许:读取仓库事实、修改<b>已确认任务范围内</b>的文件、按策略创建<b>范围受控的本地提交</b>。远程 push / 合并 / 发布、数据库写入,需人单独决定。</p>
370
+ </div>
371
+ <details open><summary>切换预设就是开关吗?</summary><div>是。选「工程化开发引擎」才挂 <code>dev_task</code> 和内置技能;选 <code>standard</code> 等其它预设则完全不介入。</div></details>
372
+ <details><summary>想改内置 skill / rule 怎么办?</summary><div>内置正文不可被同名覆盖(同名新建会被拒)。要加团队约定,新建一个<b>不同名</b>的项目级 skill / rule 再挂到对应节点,与内置并存。</div></details>
373
+ <details><summary>任务文档要不要提交?</summary><div>要。<code>.dsh/task-*.json</code> 是团队共享、跨会话恢复的任务事实,随分支提交——引擎已豁免 <code>.dsh/task-*.json</code> 与 <code>.dsh/eng.json</code>,不受文件范围门拦截;忽略它别人只能看到代码,看不到确认内容和进度。</div></details>
374
+ <details><summary>一个会话能同时做两个需求吗?</summary><div>一个任务对应一份状态文档、一个分支。新需求保存当前进度后切新分支,切回原分支即可恢复。</div></details>
375
+ <details><summary>提交被拒是怎么回事?</summary><div>通常是四类:没建 dev_task 任务、阶段没到提交检查点、消息格式不符、提交文件不在任务范围内。按拒绝原因修正即可。</div></details>
376
+ <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> 替换或直接手改 task 记录。<b>最终可信门禁在 CI</b>:CI 里重新校验 task id、快照 hash、staged 范围、提交消息、真实验证退出码、高风险回执,并检测钩子是否被绕过。三层分工:钩子 = 本地反馈,host 工具流 = 正常路径强约束,CI = 最终验证。</div></details>
377
+ <details><summary>任务记录被手改会怎样?</summary><div>流程快照内容与保存的 SHA-256 不一致时会被拒绝;任务记录本身没有签名,能同时修改内容与 hash 的本地用户仍可伪造。文件版本与 <code>revision</code> 检查用于阻止并发覆盖,不提供身份认证。0.23.0 在读取内容前取得文件版本,使读取期间发生的并发写入也被拒绝。多用户隔离和可信状态签名需要 Harness 支持。</div></details>
378
+ <details><summary>Remote 如何限制工作区?</summary><div>有 <code>workspaceRegistry.resolveByPath</code> 的 Harness 使用主机注册目录;未注册路径拒绝。旧主机保留绝对路径和系统目录检查,并提供严格注册 API。工作区注册不等于当前会话授权;共享多用户部署仍需要调用上下文和主机权限边界。</div></details>
379
+ <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>
380
+ <details><summary>「完成」等于上线了吗?</summary><div>不等于。<code>done</code> 只表示本地验证与必要评审通过;上线、合并、发布需人另行决定。</div></details>
381
+ <p class="stamp">版本 0.23.0 · 系统文件选择与安装预览 · 工作台交互改进 · 最后更新:2026-09-15</p>
382
+ </section>
383
+ </main>
384
+ </div>
385
+ </body>
383
386
  </html>