@rowansenne/workflow-run 0.34.0 → 0.36.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 (57) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/README.md +2 -0
  3. package/bin/lib/artifact-context.mjs +1 -1
  4. package/bin/lib/docsrepo.mjs +4 -6
  5. package/bin/lib/doctor.mjs +0 -3
  6. package/bin/lib/install.mjs +15 -15
  7. package/bin/lib/uninstall.mjs +2 -0
  8. package/bin/lib/workbuddy.mjs +37 -0
  9. package/bin/workbuddy/dev.md +10 -0
  10. package/bin/workflow-run.mjs +3 -0
  11. package/create-release-md-doc/SKILL.md.tpl +1 -1
  12. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  13. package/dev/SKILL.md.tpl +5 -4
  14. package/dev/references/bug.md +2 -2
  15. package/dev/references/clarify.md +1 -1
  16. package/dev/references/delivery.md +3 -3
  17. package/dev/references/planning.md +2 -2
  18. package/docs/architecture.html +3 -2
  19. package/docs/development.md +10 -4
  20. package/docs/full-install.html +90 -125
  21. package/docs/installation.md +2 -2
  22. package/docs/loan-service-install.html +90 -0
  23. package/docs/team-guide.md +3 -2
  24. package/docs/workflow-control-roadmap.md +144 -0
  25. package/docs/workflow-core-phase-one-report.md +41 -0
  26. package/docs/workflow-core-phase-one.md +317 -0
  27. package/docs/workflows.md +2 -2
  28. package/examples/workflow-core.mjs +26 -0
  29. package/package.json +2 -1
  30. package/project-review/SKILL.md.tpl +1 -1
  31. package/project-review/references/checklist.md.tpl +1 -1
  32. package/project-review/references/reporting.md +2 -2
  33. package/workflow/core/errors.mjs +61 -0
  34. package/workflow/core/index.mjs +286 -0
  35. package/workflow/core/review-handoff.mjs +101 -0
  36. package/workflow/integrations/skill-document-policy.mjs +28 -0
  37. package/workflow/lib/artifact-finalize.mjs +73 -20
  38. package/workflow/lib/code-snapshot.mjs +5 -0
  39. package/workflow/lib/document-review.mjs +53 -0
  40. package/workflow/lib/meta-store.mjs +12 -1
  41. package/workflow/lib/project.mjs +165 -14
  42. package/workflow/lib/requirements.mjs +57 -100
  43. package/workflow/lib/review-scope.mjs +262 -0
  44. package/workflow/lib/run-gates.mjs +13 -2
  45. package/workflow/lib/runs.mjs +13 -2
  46. package/workflow/lib/workspace-read.mjs +13 -4
  47. package/workflow/references/architecture.md +10 -5
  48. package/workflow/references/core-api.md +196 -0
  49. package/workflow/references/execution.md +21 -4
  50. package/workflow/references/profile.md +20 -0
  51. package/workflow/references/requirements.md +12 -12
  52. package/workflow/scripts/artifact.mjs +36 -14
  53. package/workflow/scripts/requirement.mjs +36 -40
  54. package/workflow/scripts/resolve.mjs +2 -2
  55. package/workflow/scripts/review-handoff.mjs +51 -44
  56. package/workflow/scripts/review-scope.mjs +78 -294
  57. package/workflow/scripts/run.mjs +21 -9
@@ -100,18 +100,6 @@ td code { white-space: nowrap; }
100
100
  .note.warn b.tag { color: var(--warn); }
101
101
  .note p:last-child, .note ul:last-child { margin-bottom: 0; }
102
102
 
103
- /* builder */
104
- .builder { border: 1px solid var(--line); background: var(--surface); border-radius: 10px; padding: 18px; display: grid; gap: 16px; margin: 14px 0; }
105
- .row { display: grid; gap: 8px; }
106
- .row .k { font-size: 13px; color: var(--muted); font-weight: 500; }
107
- .chips { display: flex; flex-wrap: wrap; gap: 8px; }
108
- .chip { position: relative; }
109
- .chip input { position: absolute; opacity: 0; inset: 0; margin: 0; cursor: pointer; }
110
- .chip span { display: inline-block; font-size: 13.5px; padding: 5px 12px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); cursor: pointer; user-select: none; }
111
- .chip input:checked + span { border-color: var(--accent); background: var(--accent-soft); color: var(--accent); font-weight: 500; }
112
- .builder .cmd { margin: 0; }
113
- .builder .hint { font-size: 13px; color: var(--muted); margin: 0; }
114
-
115
103
  /* steps */
116
104
  .steps { list-style: none; margin: 14px 0; padding: 0; counter-reset: s; display: grid; gap: 0; }
117
105
  .steps > li { counter-increment: s; display: grid; grid-template-columns: 34px minmax(0, 1fr); gap: 14px; padding: 12px 0; border-top: 1px dashed var(--line); margin: 0; }
@@ -152,15 +140,15 @@ footer { margin-top: 56px; padding-top: 18px; border-top: 1px solid var(--line);
152
140
  <div class="label">目录</div>
153
141
  <ol>
154
142
  <li><a href="#prep">1 准备</a></li>
155
- <li><a href="#run">2 生成安装命令</a></li>
143
+ <li><a href="#run">2 安装命令</a></li>
156
144
  <li><a href="#flow">3 安装器做了什么</a></li>
157
145
  <li><a href="#result">4 装完的目录</a></li>
158
146
  <li><a href="#verify">5 验证</a></li>
159
- <li><a href="#first">6 第一次使用</a></li>
160
- <li><a href="#team">7 团队成员接入</a></li>
161
- <li><a href="#docsrepo">8 独立文档仓库</a></li>
162
- <li><a href="#upgrade">9 升级与卸载</a></li>
163
- <li><a href="#faq">10 常见问题</a></li>
147
+ <li><a href="#docsrepo">6 独立文档仓库</a></li>
148
+ <li><a href="#first">7 第一次使用</a></li>
149
+ <li><a href="#upgrade">8 升级与卸载</a></li>
150
+ <li><a href="#faq">9 常见问题</a></li>
151
+ <li><a href="#team">10 随代码提交的团队接入</a></li>
164
152
  </ol>
165
153
  </nav>
166
154
 
@@ -194,31 +182,13 @@ codegraph --version<span class="c"> # 没装也没关系,安装器会装</sp
194
182
  </section>
195
183
 
196
184
  <section id="run">
197
- <h2><span class="n">02</span>生成安装命令</h2>
198
- <p>选好要装的环境和数据库处理方式,下面的命令会跟着变。命令在 bash、zsh、PowerShell 里写法一样。</p>
199
-
200
- <div class="builder" id="builder">
201
- <div class="row">
202
- <div class="k">环境(可多选)</div>
203
- <div class="chips" id="envs">
204
- <label class="chip"><input type="checkbox" id="env-claude" value="claude" checked><span>Claude Code</span></label>
205
- <label class="chip"><input type="checkbox" id="env-codex" value="codex" checked><span>Codex CLI</span></label>
206
- <label class="chip"><input type="checkbox" id="env-doubao" value="doubao"><span>豆包办公</span></label>
207
- <label class="chip"><input type="checkbox" id="env-qwen" value="qwen"><span>Qwen Code</span></label>
208
- <label class="chip"><input type="checkbox" id="env-workbuddy" value="workbuddy"><span>WorkBuddy</span></label>
209
- </div>
210
- </div>
211
- <div class="row">
212
- <div class="k">数据库连接</div>
213
- <div class="chips">
214
- <label class="chip"><input type="radio" name="db" id="db-skip" value="skip" checked><span>先跳过</span></label>
215
- <label class="chip"><input type="radio" name="db" id="db-existing" value="yes"><span>用已有配置(非交互)</span></label>
216
- <label class="chip"><input type="radio" name="db" id="db-ask" value="ask"><span>安装时按提示填写</span></label>
217
- </div>
218
- </div>
219
- <div class="cmd"><pre id="out"></pre><button class="copy" type="button">复制</button></div>
220
- <p class="hint" id="hint"></p>
221
- </div>
185
+ <h2><span class="n">02</span>安装命令</h2>
186
+ <div class="note"><b class="tag">已有独立文档仓库</b>请先按<a href="#docsrepo">独立文档仓库接入步骤</a>克隆文档仓库,再执行项目初始化,避免产生同名文件冲突。</div>
187
+ <p>在业务项目根目录执行。两条命令都会安装全部环境的 skills,并接入 DocNexus 和 CodeGraph;根据是否需要现在配置数据库选择一条。</p>
188
+ <h3>全部安装,并按提示配置数据库</h3>
189
+ <div class="cmd"><pre>npx @rowansenne/workflow-run --envs all --with-docnexus --with-codegraph</pre><button class="copy" type="button">复制</button></div>
190
+ <h3>全部安装,数据库先跳过</h3>
191
+ <div class="cmd"><pre>npx @rowansenne/workflow-run --envs all --skip-db --yes --with-docnexus --with-codegraph</pre><button class="copy" type="button">复制</button></div>
222
192
 
223
193
  <p>直接运行不带参数的 <code>npx @rowansenne/workflow-run</code> 也行,按提示选环境、填数据库,DocNexus 必装且缺失时自动接入;CodeGraph 需要 --with-codegraph,--with-docnexus 用于强制更新 DocNexus:</p>
224
194
  <div class="tblwrap"><table>
@@ -232,7 +202,8 @@ codegraph --version<span class="c"> # 没装也没关系,安装器会装</sp
232
202
  </section>
233
203
 
234
204
  <section id="flow">
235
- <h2><span class="n">03</span>安装器做了什么</h2>
205
+ <details>
206
+ <summary><span class="n">03</span> 安装器做了什么</summary>
236
207
  <p>按执行顺序列出。前面的步骤失败会停下;必装组件 DocNexus 或模板导入失败时,安装不算完成;CodeGraph 为可选增强。</p>
237
208
  <ol class="steps">
238
209
  <li><div><strong>检查 Node ≥ 22.13 和 npm</strong><span class="phase">DocNexus</span><p>不满足就报错退出,此时还没有写任何文件。</p></div></li>
@@ -249,6 +220,7 @@ codegraph --version<span class="c"> # 没装也没关系,安装器会装</sp
249
220
  <li><div><strong>导入文档模板到 DocNexus</strong><span class="phase">DocNexus</span><p>包内开发 / 审查模板导入 <code>workflow-run/docnexus/library/templates/&lt;skill&gt;/</code>,已有的不覆盖。独立需求文档也有可导入模板;技术 / 上线方案模板不随包提供,首次按用户样例创建;运行时只从知识库取生效模板。</p></div></li>
250
221
  </ol>
251
222
  <div class="note warn"><b class="tag">注意</b>CodeGraph 默认上报匿名使用统计(不含代码、路径、符号名),<code>--yes</code> 不会询问。本工具调用 codegraph 时都带 <code>DO_NOT_TRACK=1</code>,但 agent 通过 MCP 使用时不受这个控制。要关闭就运行 <code>codegraph telemetry off</code>。</div>
223
+ </details>
252
224
  </section>
253
225
 
254
226
  <section id="result">
@@ -299,48 +271,36 @@ codegraph --version<span class="c"> # 没装也没关系,安装器会装</sp
299
271
  <p>Nacos 的本地候选用 <code>config.mjs inspect</code> 查看;只有 <code>get</code> 会访问远端。<code>/workflow status</code> 和 doctor 不测试 Nacos 连通性,doctor 只检查其本机连接的忽略规则。</p>
300
272
  </section>
301
273
 
302
- <section id="first">
303
- <h2><span class="n">06</span>第一次使用</h2>
304
- <p>dev 仅在实际调用 <code>/dev</code> / <code>$dev</code>、点选 dev skill,或明确要求 dev / 完整开发工作流时启动。普通分析、改代码、修复、测试和提交 / 推送直接执行,不自动进入开发流程;旧需求目录与运行记录也不代表恢复授权。升级后新建会话加载最新规则。</p>
305
- <ol class="plain">
306
- <li><strong>重启 agent</strong>:MCP 配置要重启后才生效。Codex 只在受信任的项目里加载项目级配置,第一次打开时选择信任这个项目。</li>
307
- <li><strong>填项目画像</strong>:在 agent 里运行 <code>/workflow profile</code>,填主分支、构建 / 测试命令、配置中心、发布平台,以及开发环境配置(<code>toolchain</code>:JDK / Maven / Node 的位置,脚本会先推断草稿并给出依据)。画像存在 <code>.agents/skills/workflow/profile.json</code>,不含凭据,可以提交;写入前用 <code>resolve.mjs env --check</code> 核对路径在本机存在,个人机器不同的写进不提交的 <code>profile.local.json</code>。</li>
308
- <li><strong>试一次代码图谱</strong>:让 agent 用 code-graph 看当前分支的影响面,或者自己运行:</li>
274
+ <section id="docsrepo">
275
+ <h2><span class="n">06</span>独立文档仓库</h2>
276
+ <h3>新成员加入已有的文档仓库</h3>
277
+ <p>先向团队获取业务代码和文档仓库的地址,确认有访问权限,并确保团队已提交并推送文档仓库及业务项目的配置。下面以已有的 <code>order-service</code> 为例;将地址和环境选项换成团队实际使用的值。文档仓库已有 DocNexus 时,务必<strong>先接入文档仓库,再初始化本机环境</strong>,避免本地新建的同名知识库与远端冲突。</p>
278
+ <ol class="steps">
279
+ <li><div><strong>全局安装命令程序(本机只需一次)</strong><p>团队有指定版本时,将版本号换成团队指定的版本。之后运行命令不会自动更新全局安装的包。</p><div class="cmd"><pre>npm install -g @rowansenne/workflow-run@0.33.0
280
+ workflow-run --version</pre><button class="copy" type="button">复制</button></div></div></li>
281
+ <li><div><strong>克隆业务代码并接入文档仓库</strong><p>在业务项目根目录执行;文档仓库会克隆到该项目的 <code>workflow-run/</code>,不是全局安装目录。如果本地已有内容,请先检查并保留它们,接入时同路径冲突会停止。</p><div class="cmd"><pre>git clone &lt;业务代码仓库地址&gt;
282
+ cd order-service
283
+ workflow-run docs-repo git@git.example.com:team/team-docs.git</pre><button class="copy" type="button">复制</button></div></div></li>
284
+ <li><div><strong>初始化这个项目的本机环境</strong><p>全局命令无需在每个项目重新安装,但 DocNexus 本机依赖、所选环境的 skills 链接及可选 CodeGraph 索引仍需在项目中准备。下面跳过数据库配置;需要数据库时去掉 <code>--skip-db</code>,不需要 CodeGraph 时去掉 <code>--with-codegraph</code>。缺少 DocNexus 时安装器会自动安装,无需用 <code>--with-docnexus</code> 强制更新。</p><div class="cmd"><pre>workflow-run --envs claude,codex --skip-db --with-codegraph</pre><button class="copy" type="button">复制</button></div></div></li>
285
+ <li><div><strong>验证接入</strong><p>状态应显示团队文档仓库地址和本项目名;同一服务的项目名通常已随代码中的 <code>profile.json</code> 提交,不要为每个成员另起项目名。</p><div class="cmd"><pre>workflow-run docs-repo
286
+ workflow-run doctor --offline
287
+ workflow-run view --open</pre><button class="copy" type="button">复制</button></div></div></li>
309
288
  </ol>
310
- <div class="cmd"><pre>node .agents/skills/code-graph/scripts/cg.mjs status
311
- node .agents/skills/code-graph/scripts/cg.mjs impact --base main</pre><button class="copy" type="button">复制</button></div>
312
- <h3>按需读取 Nacos</h3>
313
- <p>直接请求「读取测试环境 Nacos 的 order-test.yaml,查看 order.timeout」。skill 先定位 application / bootstrap,明确本次环境、Namespace、Group 与 Data ID,再读取配置。多环境不猜选;<code>--file</code> 可重复,后面的文件覆盖前面的属性。</p>
314
- <div class="cmd"><pre>node .agents/skills/nacos-config/scripts/config.mjs inspect
315
- node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resources/bootstrap.yml --file src/main/resources/application-test.yml --data-id order-test.yaml --key order.timeout</pre><button class="copy" type="button">复制</button></div>
316
- <p>若首次解析 YAML 提示缺少依赖,只在该 skill 目录安装,不改业务项目 package.json:</p>
317
- <div class="cmd"><pre>npm install --prefix .agents/skills/nacos-config --ignore-scripts --no-package-lock</pre><button class="copy" type="button">复制</button></div>
318
- <p>也可用本机 <code>nacos-config/config.json</code> 配置命名连接,再传 <code>--conn test</code>;密码 / token 使用环境变量。配置原文不落盘,输出脱敏属性与读取来源。默认兼容 Nacos 1.x / 2.x;3.x 须显式传 <code>--api-version 3</code>。它不模拟 Spring 最终生效值,也不自动写入数据库连接。字段见 <a href="../nacos-config/references/connection.md">连接说明</a>,调用关系见 <a href="architecture.html#calls">架构图解</a>。</p>
319
- <p>接入后 skills 会自动用上这两样:</p>
289
+ <p>日常使用前可在确认本地文档改动状态后运行 <code>git -C workflow-run pull</code> 获取团队更新。需求文档位于 <code>workflow-run/docs/requirements/&lt;需求名&gt;/&lt;项目名&gt;/</code>,视图默认生成在 <code>workflow-run/tmp/view/index.html</code>。全局程序需要更新时再手动运行 <code>npm update -g @rowansenne/workflow-run</code>。</p>
290
+
291
+ <h3>日常使用</h3>
320
292
  <div class="tblwrap"><table>
321
- <tr><th>skill</th><th>DocNexus</th><th>CodeGraph</th></tr>
322
- <tr><td><code>dev</code></td><td>开始前用 <code>docnexus-recall</code> 查项目约定;完整交付有值得记的内容才问沉淀,快速通道不问;内部审查报告记「未询问」,由 dev 交付统一处理</td><td>改公共方法前看入口,先跑受影响的测试,交付说明写受影响的接口、表、配置</td></tr>
323
- <tr><td><code>project-review</code></td><td>独立运行时有值得记的才问,沉淀后报告记库内路径;dev 子 agent 审查不单独问</td><td>「影响面」按入口归纳</td></tr>
324
- <tr><td>技术 / 上线方案</td><td>从知识库取模板;有值得记的内容时提议沉淀</td><td>影响范围、中间件上线、回归验证参考 <code>impact</code></td></tr>
293
+ <tr><th>场景</th><th>做法</th></tr>
294
+ <tr><td>写完产物</td><td>skill 会列出文档仓库里没提交的文件,并给出建议的提交信息。你确认后它才提交,推送另外问。查看未提交的产物:<code>node .agents/skills/workflow/scripts/requirement.mjs pending</code></td></tr>
295
+ <tr><td>加入其他服务的需求</td><td>先 <code>git -C workflow-run pull</code>,绑定需求时就能看到别的服务建的需求,用同一个名字绑定</td></tr>
296
+ <tr><td>引用产物</td><td>写成「文档仓库名:路径」,例如 <code>team-docs:docs/requirements/订单导出/order-service/review.md</code>。在哪个服务、哪个人的克隆里都一样</td></tr>
297
+ <tr><td>浏览</td><td><code>/workflow view</code> 显示文档仓库里所有项目的需求</td></tr>
298
+ <tr><td>查看当前状态</td><td><code>npx @rowansenne/workflow-run docs-repo</code>(不带地址),显示仓库地址、引用前缀和本项目的项目名</td></tr>
299
+ <tr><td>改项目名</td><td><code>npx @rowansenne/workflow-run docs-repo --project &lt;项目名&gt;</code>,然后提交 <code>profile.json</code></td></tr>
300
+ <tr><td>不想被提示提交</td><td><code>node .agents/skills/workflow/scripts/requirement.mjs config --commit-prompt off --local</code>,只写进个人的 <code>profile.local.json</code></td></tr>
325
301
  </table></div>
326
- <div class="note"><b class="tag">授权</b>任何写入 DocNexus 的操作都要你同意。没有 <code>.codegraph/</code> 时 skills 不会自己建索引,只在交付或报告里注明「未使用代码图谱」。</div>
327
- </section>
328
-
329
- <section id="team">
330
- <h2><span class="n">07</span>团队成员接入</h2>
331
- <p>skills、软链接、项目画像、DocNexus 知识库可随仓库提交;DocNexus 依赖和检索库、CodeGraph CLI 与索引、数据库 / wiki 凭据、Nacos 本机连接与依赖各人在本机准备。所以其他人 clone 之后也要跑一次同样的命令:</p>
332
- <div class="cmd"><pre>git clone &lt;仓库地址&gt; &amp;&amp; cd &lt;项目&gt;
333
- npx @rowansenne/workflow-run --envs claude,codex --skip-db --with-docnexus --with-codegraph</pre><button class="copy" type="button">复制</button></div>
334
- <ul>
335
- <li>本次为破坏性更新:安装前强制删除旧版 DocNexus 数据和旧重复备份,不迁移、不备份;新版接入后,重跑保留项目画像、表结构和知识库里的模板。<code>docnexus init</code> 可以重复执行,不影响已有记忆。</li>
336
- <li>Windows 上 clone 含软链接的仓库前先执行 <code>git config --global core.symlinks true</code>,并用管理员终端。</li>
337
- <li>需要查数据库的人去掉 <code>--skip-db</code>,按提示填自己的连接;这个文件已被忽略,不会提交。</li>
338
- <li>用了独立文档仓库时,安装顺序不一样,见下一节。</li>
339
- </ul>
340
- </section>
341
-
342
- <section id="docsrepo">
343
- <h2><span class="n">08</span>独立文档仓库</h2>
302
+ <details>
303
+ <summary>了解文档仓库及其他接入方式</summary>
344
304
  <p>默认情况下 <code>workflow-run/</code> 随代码提交。下面两种情况适合换成团队共用的文档仓库:不想让需求产物进代码仓库,或者一个需求横跨多个服务。换了之后 <code>workflow-run/</code> 本身就是文档仓库:</p>
345
305
  <ul>
346
306
  <li>代码仓库的 <code>.gitignore</code> 加上 <code>/workflow-run/</code>,不再管理它。</li>
@@ -356,7 +316,7 @@ npx @rowansenne/workflow-run --envs claude,codex --skip-db --with-docnexus --wit
356
316
  │ ├── .gitignore <span class="c"># DocNexus 自带</span>
357
317
  │ ├── <span class="ig">node_modules/</span> <span class="ig">store/</span> <span class="c"># 每人本机一份</span>
358
318
  └── <span class="ig">tmp/</span> <span class="c"># 写在 .git/info/exclude,不进文档仓库</span></div>
359
- <div class="note"><b class="tag">原地切换</b>因为结构相同,切换只是换一个 git 仓库来跟踪 <code>workflow-run/</code>,文件不用挪。<code>docs-repo</code> 看到 <code>workflow-run/</code> 里已有产物和 DocNexus 时,会原地 <code>git init</code> 并接上远端;里面是空的就直接克隆。所以先全量安装再切换也可以,不用讲究顺序。</div>
319
+ <div class="note"><b class="tag">原地切换</b>因为结构相同,切换只是换一个 git 仓库来跟踪 <code>workflow-run/</code>,文件不用挪。<code>docs-repo</code> 看到 <code>workflow-run/</code> 里已有产物和 DocNexus 时,会原地 <code>git init</code> 并接上远端;里面是空的就直接克隆。接入已有知识库时,按上面的步骤先接入文档仓库。</div>
360
320
 
361
321
  <h3>第一次搭建(全团队只做一次)</h3>
362
322
  <p>先在 git 服务器上建一个空仓库,例如 <code>team-docs</code>,然后在第一个服务的项目根执行:</p>
@@ -370,12 +330,9 @@ git -C workflow-run push -u origin main</pre><button class="copy" type="button">
370
330
  git add -A &amp;&amp; git commit -m "chore: move workflow-run to team docs repo"</pre><button class="copy" type="button">复制</button></div></div></li>
371
331
  </ol>
372
332
 
373
- <h3>其他服务、其他成员接入</h3>
374
- <p>文档仓库里已经有 DocNexus 了,这时要<strong>先克隆、再安装</strong>。如果反过来,安装时会在本地新建一个 DocNexus 工作区,和文档仓库里的同名文件冲突,<code>docs-repo</code> 会停下。</p>
375
- <div class="cmd"><pre>npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git<span class="c"> # 克隆到 workflow-run/</span>
376
- npx @rowansenne/workflow-run --envs claude,codex --skip-db --with-docnexus --with-codegraph
377
- npx @rowansenne/workflow-run docs-repo --project report-service<span class="c"> # 只有新服务需要,给它起名</span></pre><button class="copy" type="button">复制</button></div>
378
- <p>同一个服务的其他成员不用第三条命令,项目名已经随代码提交在 <code>profile.json</code> 里。<code>--with-docnexus</code> 在已有的工作区上只装本机依赖,<code>docnexus init</code> 可以重复执行,不影响已有记忆。</p>
333
+ <h3>其他服务接入</h3>
334
+ <p>其他服务也按上面的顺序先接入文档仓库、再初始化项目。初始化后为该服务配置团队约定的项目名,并将配置提交到该服务的代码仓库:</p>
335
+ <div class="cmd"><pre>workflow-run docs-repo --project report-service</pre><button class="copy" type="button">复制</button></div>
379
336
 
380
337
  <h3>已经用了一段时间,要改用文档仓库</h3>
381
338
  <p>做法和第一次搭建一样,不用手动迁移。旧版本随代码提交时,需求目录下没有项目名这一层,先运行 <code>upgrade</code>,它会把这些文件迁到 <code>&lt;需求名&gt;/&lt;项目名&gt;/</code> 下(被 git 跟踪的用 <code>git mv</code>,保留历史):</p>
@@ -383,21 +340,38 @@ npx @rowansenne/workflow-run docs-repo --project report-service<span class="c">
383
340
  npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git --project order-service</pre><button class="copy" type="button">复制</button></div>
384
341
  <p>然后按「第一次搭建」的第 3、4 步提交两个仓库。如果文档仓库里已经有别的服务的内容,各服务的产物在各自的项目子目录下,不会冲突。冲突只会出在 DocNexus:两边都有知识库时,<code>docs-repo</code> 会退回原状,并列出冲突的文件。这时先按 DocNexus 自己的写入流程,把本项目沉淀的内容写进共用知识库,再把本地的 <code>workflow-run/docnexus/</code> 挪走后重跑。</p>
385
342
 
386
- <h3>日常使用</h3>
343
+ </details>
344
+ </section>
345
+
346
+ <section id="first">
347
+ <h2><span class="n">07</span>第一次使用</h2>
348
+ <p>dev 仅在实际调用 <code>/dev</code> / <code>$dev</code>、点选 dev skill,或明确要求 dev / 完整开发工作流时启动。普通分析、改代码、修复、测试和提交 / 推送直接执行,不自动进入开发流程;旧需求目录与运行记录也不代表恢复授权。升级后新建会话加载最新规则。</p>
349
+ <ol class="plain">
350
+ <li><strong>重启 agent</strong>:MCP 配置要重启后才生效。Codex 只在受信任的项目里加载项目级配置,第一次打开时选择信任这个项目。</li>
351
+ <li><strong>填项目画像</strong>:在 agent 里运行 <code>/workflow profile</code>,填主分支、构建 / 测试命令、配置中心、发布平台,以及开发环境配置(<code>toolchain</code>:JDK / Maven / Node 的位置,脚本会先推断草稿并给出依据)。画像存在 <code>.agents/skills/workflow/profile.json</code>,不含凭据,可以提交;写入前用 <code>resolve.mjs env --check</code> 核对路径在本机存在,个人机器不同的写进不提交的 <code>profile.local.json</code>。</li>
352
+ <li><strong>试一次代码图谱</strong>:让 agent 用 code-graph 看当前分支的影响面,或者自己运行:</li>
353
+ </ol>
354
+ <div class="cmd"><pre>node .agents/skills/code-graph/scripts/cg.mjs status
355
+ node .agents/skills/code-graph/scripts/cg.mjs impact --base main</pre><button class="copy" type="button">复制</button></div>
356
+ <h3>按需读取 Nacos</h3>
357
+ <p>直接请求「读取测试环境 Nacos 的 order-test.yaml,查看 order.timeout」。skill 先定位 application / bootstrap,明确本次环境、Namespace、Group 与 Data ID,再读取配置。多环境不猜选;<code>--file</code> 可重复,后面的文件覆盖前面的属性。</p>
358
+ <div class="cmd"><pre>node .agents/skills/nacos-config/scripts/config.mjs inspect
359
+ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resources/bootstrap.yml --file src/main/resources/application-test.yml --data-id order-test.yaml --key order.timeout</pre><button class="copy" type="button">复制</button></div>
360
+ <p>若首次解析 YAML 提示缺少依赖,只在该 skill 目录安装,不改业务项目 package.json:</p>
361
+ <div class="cmd"><pre>npm install --prefix .agents/skills/nacos-config --ignore-scripts --no-package-lock</pre><button class="copy" type="button">复制</button></div>
362
+ <p>也可用本机 <code>nacos-config/config.json</code> 配置命名连接,再传 <code>--conn test</code>;密码 / token 使用环境变量。配置原文不落盘,输出脱敏属性与读取来源。默认兼容 Nacos 1.x / 2.x;3.x 须显式传 <code>--api-version 3</code>。它不模拟 Spring 最终生效值,也不自动写入数据库连接。字段见 <a href="../nacos-config/references/connection.md">连接说明</a>,调用关系见 <a href="architecture.html#calls">架构图解</a>。</p>
363
+ <p>接入后 skills 会自动用上这两样:</p>
387
364
  <div class="tblwrap"><table>
388
- <tr><th>场景</th><th>做法</th></tr>
389
- <tr><td>写完产物</td><td>skill 会列出文档仓库里没提交的文件,并给出建议的提交信息。你确认后它才提交,推送另外问。查看未提交的产物:<code>node .agents/skills/workflow/scripts/requirement.mjs pending</code></td></tr>
390
- <tr><td>加入其他服务的需求</td><td>先 <code>git -C workflow-run pull</code>,绑定需求时就能看到别的服务建的需求,用同一个名字绑定</td></tr>
391
- <tr><td>引用产物</td><td>写成「文档仓库名:路径」,例如 <code>team-docs:docs/requirements/订单导出/order-service/review.md</code>。在哪个服务、哪个人的克隆里都一样</td></tr>
392
- <tr><td>浏览</td><td><code>/workflow view</code> 显示文档仓库里所有项目的需求</td></tr>
393
- <tr><td>查看当前状态</td><td><code>npx @rowansenne/workflow-run docs-repo</code>(不带地址),显示仓库地址、引用前缀和本项目的项目名</td></tr>
394
- <tr><td>改项目名</td><td><code>npx @rowansenne/workflow-run docs-repo --project &lt;项目名&gt;</code>,然后提交 <code>profile.json</code></td></tr>
395
- <tr><td>不想被提示提交</td><td><code>node .agents/skills/workflow/scripts/requirement.mjs config --commit-prompt off --local</code>,只写进个人的 <code>profile.local.json</code></td></tr>
365
+ <tr><th>skill</th><th>DocNexus</th><th>CodeGraph</th></tr>
366
+ <tr><td><code>dev</code></td><td>开始前用 <code>docnexus-recall</code> 查项目约定;完整交付有值得记的内容才问沉淀,快速通道不问;内部审查报告记「未询问」,由 dev 交付统一处理</td><td>改公共方法前看入口,先跑受影响的测试,交付说明写受影响的接口、表、配置</td></tr>
367
+ <tr><td><code>project-review</code></td><td>独立运行时有值得记的才问,沉淀后报告记库内路径;dev 子 agent 审查不单独问</td><td>「影响面」按入口归纳</td></tr>
368
+ <tr><td>技术 / 上线方案</td><td>从知识库取模板;有值得记的内容时提议沉淀</td><td>影响范围、中间件上线、回归验证参考 <code>impact</code></td></tr>
396
369
  </table></div>
370
+ <div class="note"><b class="tag">授权</b>任何写入 DocNexus 的操作都要你同意。没有 <code>.codegraph/</code> 时 skills 不会自己建索引,只在交付或报告里注明「未使用代码图谱」。</div>
397
371
  </section>
398
372
 
399
373
  <section id="upgrade">
400
- <h2><span class="n">09</span>升级与卸载</h2>
374
+ <h2><span class="n">08</span>升级与卸载</h2>
401
375
  <h3>升级 workflow-run</h3>
402
376
  <div class="cmd"><pre>npx @rowansenne/workflow-run upgrade</pre><button class="copy" type="button">复制</button></div>
403
377
  <p>读安装清单里记录的环境,非交互升级 skills;手改过的文件先备份到 <code>workflow-run/tmp/upgrade-backup/</code>。</p>
@@ -417,7 +391,7 @@ codegraph uninstall<span class="c"> # 移除 agent 配置
417
391
  </section>
418
392
 
419
393
  <section id="faq">
420
- <h2><span class="n">10</span>常见问题</h2>
394
+ <h2><span class="n">09</span>常见问题</h2>
421
395
  <details><summary>退出码是 1,但部分 skills 已落盘</summary><div>DocNexus 接入或必需模板导入失败时安装立即停止,不报告完成;修好输出提示的网络、npm 权限或模板问题后重跑。CodeGraph 是可选增强,接入失败会提示并保留其他已安装能力,随后可带 <code>--with-codegraph</code> 重试。</div></details>
422
396
  <details><summary>全局安装 CodeGraph 报权限错误</summary><div>先用你平时的方式全局装好 <code>@colbymchenry/codegraph@1</code>(例如改用 nvm 管理的 Node),确认 <code>codegraph --version</code> 能运行,再重跑带 <code>--with-codegraph</code> 的命令。</div></details>
423
397
  <details><summary>codegraph init 失败或太慢</summary><div>安装器会跳过建索引并提示。之后可以在项目根手动执行 <code>codegraph init</code>。索引建好后 agent 使用期间自动增量同步,<code>cg.mjs</code> 发现索引落后于工作区时也会先 <code>codegraph sync</code>。</div></details>
@@ -428,36 +402,27 @@ codegraph uninstall<span class="c"> # 移除 agent 配置
428
402
  <details><summary>图谱里一个方法「没有调用方」,可以删吗</summary><div>不一定。静态分析看不到 Spring 多实现的选择、AOP、反射和配置驱动的路由,「没有调用方」不等于没人用。</div></details>
429
403
  </section>
430
404
 
405
+ <section id="team">
406
+ <details>
407
+ <summary><span class="n">10</span> 随代码提交的团队接入</summary>
408
+ <p>以下适用于文档随代码仓库提交的项目。skills、软链接、项目画像、DocNexus 知识库可随仓库提交;DocNexus 依赖和检索库、CodeGraph CLI 与索引、数据库 / wiki 凭据、Nacos 本机连接与依赖各人在本机准备。所以其他人 clone 之后也要跑一次同样的命令:</p>
409
+ <div class="cmd"><pre>git clone &lt;仓库地址&gt; &amp;&amp; cd &lt;项目&gt;
410
+ npx @rowansenne/workflow-run --envs claude,codex --skip-db --with-docnexus --with-codegraph</pre><button class="copy" type="button">复制</button></div>
411
+ <ul>
412
+ <li>本次为破坏性更新:安装前强制删除旧版 DocNexus 数据和旧重复备份,不迁移、不备份;新版接入后,重跑保留项目画像、表结构和知识库里的模板。<code>docnexus init</code> 可以重复执行,不影响已有记忆。</li>
413
+ <li>Windows 上 clone 含软链接的仓库前先执行 <code>git config --global core.symlinks true</code>,并用管理员终端。</li>
414
+ <li>需要查数据库的人去掉 <code>--skip-db</code>,按提示填自己的连接;这个文件已被忽略,不会提交。</li>
415
+ <li>用了独立文档仓库时,按<a href="#docsrepo">独立文档仓库接入步骤</a>操作。</li>
416
+ </ul>
417
+ </details>
418
+ </section>
419
+
431
420
  <footer>依据 0.29.0(2026-10-28)的 README、skill.json 与安装器源码更新。</footer>
432
421
  </main>
433
422
  </div>
434
423
 
435
424
  <script>
436
425
  (function () {
437
- var out = document.getElementById('out');
438
- var hint = document.getElementById('hint');
439
- function build() {
440
- var envs = Array.prototype.slice.call(document.querySelectorAll('#envs input:checked')).map(function (i) { return i.value; });
441
- var db = document.querySelector('input[name="db"]:checked').value;
442
- var envArg = envs.length === 5 ? 'all' : envs.join(',');
443
- var parts = ['npx @rowansenne/workflow-run'];
444
- if (envs.length) parts.push('--envs ' + envArg);
445
- if (db === 'skip') parts.push('--skip-db');
446
- if (db === 'yes') parts.push('--yes');
447
- parts.push('--with-docnexus', '--with-codegraph');
448
- out.textContent = parts.join(' ');
449
- var notes = [];
450
- if (!envs.length) notes.push('没选环境时会交互询问(回车 = 全部)。');
451
- if (envs.length && envs.indexOf('claude') < 0 && envs.indexOf('codex') < 0) notes.push('没选 claude / codex:不会写 CodeGraph 的 MCP 配置,skills 直接调用 codegraph CLI。');
452
- if (envs.indexOf('qwen') >= 0) notes.push('qwen 的 DocNexus 说明自动写入 QWEN.md。');
453
- if (db === 'yes') notes.push('--yes 要求已有数据库配置,找不到会报错退出。');
454
- if (db === 'ask') notes.push('安装时会提示填写数据库连接。');
455
- hint.textContent = notes.join(' ');
456
- hint.hidden = !notes.length;
457
- }
458
- document.getElementById('builder').addEventListener('change', build);
459
- build();
460
-
461
426
  document.querySelectorAll('.copy').forEach(function (btn) {
462
427
  btn.addEventListener('click', function () {
463
428
  var pre = btn.parentNode.querySelector('pre');
@@ -87,7 +87,7 @@ npx @rowansenne/workflow-run@latest --version
87
87
  * 按 skill 建链接而不是链接整个目录,这样 `.claude/skills/` 里还能放其他 skill(例如 DocNexus 的链接)。
88
88
  * 之前用 `--copy`(或建不了链接时)装的独立拷贝,再不带 `--copy` 安装时会换成链接:拷贝里填过的用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)先并入 `.agents/skills/`,原目录移到 `workflow-run/tmp/backup/<时间>/<环境>/`;两份都填过且内容不同时不会自动合并,会保留那个目录并提示手动处理。
89
89
  * Windows:安装与升级(`init` / `upgrade`)**必须在管理员终端执行**(建目录软链接需要该权限);在普通终端运行会直接停下、不做任何改动,并提示改用「以管理员身份运行」的终端。`doctor`、`seed-templates`、`uninstall` 不要求管理员。少数文件系统仍建不了软链接时,该环境自动退回独立拷贝。在 Windows 上 clone 含软链接的仓库需要 `git config core.symlinks true`。
90
- * 不想用软链接:加 `--copy`,每个环境各装一份完整文件。
90
+ * 不想用软链接:加 `--copy`,每个环境各装一份完整文件。多份 `profile.json` / `profile.local.json` 初次安装时内容相同,配置会自动视为同一来源;只改其中一份后出现歧义,运行 `requirement.mjs config --profile-source <claude|qwen|workbuddy|路径>` 明确选择,`--profile-source auto` 恢复自动解析。选择记录在 `workflow-run/profile-source.json`。
91
91
 
92
92
  ### 在 Windows 的 WorkBuddy 中使用
93
93
 
@@ -100,7 +100,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
100
100
 
101
101
  这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`,便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝,保留已填配置,再更新技能文件;共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时,全新安装不会生成 `.qwen/skills/`。
102
102
 
103
- 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,重新打开项目并新建会话,再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数,不是额外的独立技能。
103
+ 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,再新建任务。选择安装 `dev` 时,安装器会同时写入 `.codebuddy/commands/dev.md`,在输入框输入 `/` 可找到 `/dev`,也可输入 `/dev --bug <现象>`。已有同名命令原样保留。其他技能可在任务里显式指定,例如「使用 project-review 技能审查当前分支」。
104
104
 
105
105
  如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
106
106
 
@@ -0,0 +1,90 @@
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>loan-service 接入 workflow-run</title>
7
+ <style>
8
+ :root { color-scheme: light dark; --bg: #f5f7f6; --surface: #fff; --ink: #18221f; --muted: #5b6965; --accent: #0d6b62; --line: #d9e1de; --code: #14201d; --code-ink: #d6e6e1; }
9
+ @media (prefers-color-scheme: dark) { :root { --bg: #101715; --surface: #172220; --ink: #e2ebe8; --muted: #93a6a0; --accent: #5cc4b2; --line: #2a3835; --code: #0a100e; } }
10
+ * { box-sizing: border-box; }
11
+ body { margin: 0; background: var(--bg); color: var(--ink); font: 16px/1.75 system-ui, -apple-system, "Microsoft YaHei", sans-serif; }
12
+ main { max-width: 760px; margin: auto; padding: 48px 20px 80px; }
13
+ header { border-bottom: 1px solid var(--line); padding-bottom: 22px; }
14
+ .label { color: var(--accent); font: 13px ui-monospace, monospace; }
15
+ h1 { font-size: clamp(28px, 5vw, 40px); line-height: 1.25; margin: 10px 0; }
16
+ h2 { font-size: 21px; margin: 32px 0 8px; }
17
+ p { margin: 8px 0; }
18
+ .muted { color: var(--muted); }
19
+ .note { background: var(--surface); border: 1px solid var(--line); border-left: 3px solid var(--accent); border-radius: 6px; padding: 12px 16px; margin: 16px 0; }
20
+ code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
21
+ code { overflow-wrap: anywhere; }
22
+ .cmd { position: relative; background: var(--code); color: var(--code-ink); border-radius: 8px; margin: 12px 0; }
23
+ pre { margin: 0; padding: 16px 84px 16px 16px; overflow-x: auto; font-size: 14px; line-height: 1.65; }
24
+ button { position: absolute; top: 9px; right: 9px; border: 1px solid #526a63; border-radius: 6px; background: transparent; color: var(--code-ink); padding: 5px 10px; cursor: pointer; }
25
+ button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
26
+ </style>
27
+ </head>
28
+ <body>
29
+ <main>
30
+ <header>
31
+ <div class="label">WORKFLOW-RUN / LOAN-SERVICE</div>
32
+ <h1>接入已有文档仓库</h1>
33
+ <p class="muted">适用于 loan-service 已下载到本地、团队独立文档仓库已有数据的情况。已有文档仓库中的项目名为 loan-service。</p>
34
+ </header>
35
+ <div class="note">以下步骤假设本地 <code>loan-service/workflow-run/</code> 没有需要保留的数据。把示例路径和仓库地址替换为实际值,并确认有仓库访问权限。</div>
36
+
37
+ <section>
38
+ <h2>1. 接入仓库</h2>
39
+ <p><strong>安装命令程序</strong></p>
40
+ <p>本机已经全局安装过 <code>workflow-run</code> 时,跳过安装命令。</p>
41
+ <div class="cmd"><pre>npm install -g @rowansenne/workflow-run
42
+ workflow-run --version</pre><button type="button">复制</button></div>
43
+ <p><strong>进入业务项目</strong></p>
44
+ <p>将路径替换为本机的项目路径。</p>
45
+ <div class="cmd"><pre>cd /path/to/loan-service</pre><button type="button">复制</button></div>
46
+ <p><strong>接入已有文档仓库</strong></p>
47
+ <p>将地址替换为团队的文档仓库地址。仓库会接入到项目下的 <code>workflow-run/</code>。</p>
48
+ <div class="cmd"><pre>workflow-run docs-repo &lt;文档仓库地址&gt;</pre><button type="button">复制</button></div>
49
+ <div class="note">如果提示本地文件冲突,先保留并检查这些文件,处理冲突后再重新接入。</div>
50
+ </section>
51
+ <section>
52
+ <h2>2. 项目初始化</h2>
53
+ <p><strong>初始化项目环境</strong></p>
54
+ <p>安装所有环境的 skills、接入 CodeGraph,数据库暂时跳过。</p>
55
+ <div class="cmd"><pre>workflow-run --envs all --skip-db --yes --with-codegraph</pre><button type="button">复制</button></div>
56
+ <p><strong>检查项目名</strong></p>
57
+ <div class="cmd"><pre>workflow-run docs-repo</pre><button type="button">复制</button></div>
58
+ <p>已有文档仓库中的项目名是 <code>loan-service</code>。如果输出的项目名已经是 <code>loan-service</code>,无需修改;如果未配置,执行:</p>
59
+ <div class="cmd"><pre>workflow-run docs-repo --project loan-service</pre><button type="button">复制</button></div>
60
+ <p><strong>验证并查看文档</strong></p>
61
+ <div class="cmd"><pre>workflow-run doctor --offline
62
+ workflow-run view --open</pre><button type="button">复制</button></div>
63
+ </section>
64
+ <section>
65
+ <h2>日常同步团队文档</h2>
66
+ <p>在项目根目录执行,先检查本地改动,再拉取更新。</p>
67
+ <div class="cmd"><pre>git -C workflow-run status
68
+ git -C workflow-run pull</pre><button type="button">复制</button></div>
69
+ </section>
70
+ </main>
71
+ <script>
72
+ document.querySelectorAll('.cmd button').forEach(function (button) {
73
+ button.addEventListener('click', async function () {
74
+ try {
75
+ await navigator.clipboard.writeText(button.parentElement.querySelector('pre').textContent);
76
+ button.textContent = '已复制';
77
+ } catch (_) {
78
+ var range = document.createRange();
79
+ range.selectNodeContents(button.parentElement.querySelector('pre'));
80
+ var selection = window.getSelection();
81
+ selection.removeAllRanges();
82
+ selection.addRange(range);
83
+ button.textContent = '已选中';
84
+ }
85
+ setTimeout(function () { button.textContent = '复制'; }, 1600);
86
+ });
87
+ });
88
+ </script>
89
+ </body>
90
+ </html>
@@ -13,6 +13,7 @@
13
13
  | `.agents/skills/` | skills 单一来源,含安装清单 `.workflow-run.json` |
14
14
  | `.claude/skills/`、`.qwen/skills/`、`.codebuddy/skills/` | 指向 `.agents/skills/` 的相对软链接(Windows 上 clone 需 `git config core.symlinks true`) |
15
15
  | `.agents/skills/workflow/profile.json` | 项目画像(无凭据),产物目录用的项目名也在这里 |
16
+ | `workflow-run/profile-source.json` | 多环境 `--copy` 且 profile 内容不同时,记录项目选用的 profile 目录;`config --profile-source` 维护 |
16
17
  | `.agents/skills/database-query/references/schema.md` | 表结构速查,补齐后提交 |
17
18
  | `workflow-run/docs/requirements/` | 需求产物;独立文档仓库模式下提交到文档仓库 |
18
19
  | `workflow-run/other/` | 普通聊天生成的报告、方案、草稿、导出等辅助文件(按需创建,可按主题分目录);不进入需求索引、运行状态、需求统计与文档视图,按需提交 |
@@ -85,7 +86,7 @@ workflow-run/docs/requirements/<需求名>/<项目名>/
85
86
  * **随代码提交和独立文档仓库两种用法的结构完全一样**,切换时文件不用挪。一个需求横跨多个服务时,各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`:随代码提交时不用配置,取 git 远端仓库名(没有远端用目录名),第一次落盘时自动写进去;独立文档仓库时由 `docs-repo` 配置。
86
87
  * 旧版本随代码提交时没有 `<项目名>/` 这一层;`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`(被 git 跟踪的用 `git mv`,保留历史),结尾列出迁移了哪些需求,改动由你提交。目标里已有同名文件的需求不动,并提示手动处理;`doctor` 也会提示还没迁移的需求。
87
88
  * **需求名由你定**:dev 在 Step 0 先确定工作分支,再查询绑定并确认需求名,给不出名字或说不清这次要做什么时不会进入开发流程(默认值按分支名生成;也可以选已有的需求,例如修 bug 的新分支挂到原需求下)。从 `/workflow` 完整链路开始时同样先问(只问名字,第一次落盘时才 `bind`);S 快速通道也问,但不绑定、不落盘。确定后,同一分支上的各 skill 都写到这个目录,不再问。一个需求可以绑定多个分支。
88
- * 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。底层 requirement path / sync 仍保留,新的正式流程统一走 finalize。
89
+ * 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。旧 path / sync 写入链已删除;只刷新派生索引时使用 `requirement.mjs reindex`,正文、版本和证据仍由 finalize 管理。
89
90
  * 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
90
91
 
91
92
  完整 dev 的关键阶段由程序校验:M / L 方案确认绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;需要产品核对清单时,在首版清单前创建运行、等待反馈时保存状态;快速通道仍不创建运行。协议见 [execution.md](../workflow/references/execution.md)。
@@ -98,7 +99,7 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
98
99
 
99
100
  它会:
100
101
  - `workflow-run/` 里没有内容(或只有 `tmp/`)时,把文档仓库克隆到这里(`tmp/` 先挪开再放回);
101
- - 已有随项目提交的产物、DocNexus 时,原地 `git init` 并接上远端,文件不用挪(旧结构的产物先迁到 `<需求>/<项目名>/`)。远端是空仓库时,本地内容就是文档仓库的第一批内容;远端已有内容时检出远端,本地文件和远端同路径冲突(多半是两边都有 DocNexus 知识库)就退回原状并列出冲突的文件,不合并;代码仓库还跟踪着 `workflow-run/` 时提示 `git rm -r --cached workflow-run`;
102
+ - 已有随项目提交的产物、DocNexus 时,原地 `git init` 并接上远端,文件不用挪。新版不再自动迁移旧结构;用户区里的历史目录保持原样。远端是空仓库时,本地内容就是文档仓库的第一批内容;远端已有内容时检出远端,本地文件和远端同路径冲突(多半是两边都有 DocNexus 知识库)就退回原状并列出冲突的文件,不合并;代码仓库还跟踪着 `workflow-run/` 时提示 `git rm -r --cached workflow-run`;
102
103
  - 然后代码仓库的 `.gitignore` 加 `/workflow-run/`,文档仓库的 `.git/info/exclude` 加 `/tmp/`;把项目名写进 `workflow/profile.json`(默认沿用已配置的,其次 git 远端仓库名;`profile.json` 随代码提交,记得提交它);文档仓库里有 DocNexus 时接上本项目的链接和段落,本机还没装它的依赖时提示运行 `upgrade --with-docnexus`。不带地址运行显示当前状态;只改项目名:`docs-repo --project <项目名>`。
103
104
 
104
105
  `workflow-run/` 自己是 git 仓库就是这个模式:目录结构不变,各服务在同一个需求目录下各占一个子目录,DocNexus 知识库也在这个仓库里各服务共用。项目名写在 `workflow/profile.json` 的 `artifacts.project`,只配一次(`docs-repo` 会配好;没配时 skill 会问你一次)。文档里引用产物写成「文档仓库名:路径」,各服务、各人的克隆里都一样。