@rowansenne/workflow-run 0.29.0 → 0.30.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 (36) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +45 -841
  3. package/dev/SKILL.md.tpl +8 -7
  4. package/dev/references/bug.md +1 -0
  5. package/dev/references/clarification-template.md +40 -0
  6. package/dev/references/clarify.md +40 -36
  7. package/dev/references/delivery.md +1 -1
  8. package/dev/references/planning.md +14 -14
  9. package/dev/references/preflight.md +1 -1
  10. package/dev/references/requirement-template.md +2 -2
  11. package/dev/skill.json +6 -0
  12. package/docs/architecture.html +628 -0
  13. package/docs/development.md +221 -0
  14. package/docs/docnexus-integration-plan.md +56 -0
  15. package/docs/full-install.html +491 -0
  16. package/docs/installation.md +211 -0
  17. package/docs/integrations.md +160 -0
  18. package/docs/team-guide.md +166 -0
  19. package/docs/workflows.md +129 -0
  20. package/package.json +4 -2
  21. package/workflow/SKILL.md.tpl +1 -1
  22. package/workflow/lib/artifact-finalize.mjs +20 -11
  23. package/workflow/lib/artifact-model.mjs +2 -2
  24. package/workflow/lib/code-snapshot.mjs +8 -2
  25. package/workflow/lib/run-gates.mjs +20 -20
  26. package/workflow/lib/runs.mjs +5 -4
  27. package/workflow/references/architecture.md +1 -1
  28. package/workflow/references/execution.md +10 -2
  29. package/workflow/references/requirements.md +3 -2
  30. package/workflow/references/runs.md +5 -5
  31. package/workflow/references/templates.md +2 -2
  32. package/workflow/scripts/artifact.mjs +1 -1
  33. package/workflow/scripts/pr-desc.mjs +2 -2
  34. package/workflow/scripts/requirement.mjs +2 -2
  35. package/workflow/scripts/review-handoff.mjs +4 -3
  36. package/workflow/scripts/template.mjs +3 -2
@@ -0,0 +1,628 @@
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, viewport-fit=cover">
6
+ <title>workflow-run 架构</title>
7
+ <meta name="claude:viewport-fit-sides" content="cover">
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@500;600;700&family=Noto+Sans+SC:wght@400;500;700&family=JetBrains+Mono:wght@400;500&display=swap">
11
+ <style>
12
+ /* Layout: 单栏长页(正文约 68ch,图示放宽到 1040px);与 full-install.html 同一套色板和字体 */
13
+ :root {
14
+ --bg: #f5f7f6;
15
+ --surface: #ffffff;
16
+ --ink: #18221f;
17
+ --muted: #5b6965;
18
+ --line: #d9e1de;
19
+ --accent: #0d6b62;
20
+ --accent-soft: #e0efec;
21
+ --warn: #9a5b00;
22
+ --warn-soft: #fbf0dc;
23
+ --code-bg: #eef2f1;
24
+ --term-bg: #14201d;
25
+ --term-fg: #d6e6e1;
26
+ --term-dim: #7f9a93;
27
+ --term-ok: #7fd1b9;
28
+ --f-display: "Instrument Sans", "Noto Sans SC", system-ui, sans-serif;
29
+ --f-body: "Noto Sans SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
30
+ --f-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
31
+ }
32
+ @media (prefers-color-scheme: dark) {
33
+ :root:not([data-theme="light"]) {
34
+ --bg: #101715; --surface: #172220; --ink: #e2ebe8; --muted: #93a6a0; --line: #2a3835;
35
+ --accent: #5cc4b2; --accent-soft: #19332f; --warn: #e3a64a; --warn-soft: #2e2414;
36
+ --code-bg: #1d2a27; --term-bg: #0a100e; --term-fg: #d6e6e1; --term-dim: #6f8a83; --term-ok: #7fd1b9;
37
+ color-scheme: dark;
38
+ }
39
+ }
40
+ :root[data-theme="dark"] {
41
+ --bg: #101715; --surface: #172220; --ink: #e2ebe8; --muted: #93a6a0; --line: #2a3835;
42
+ --accent: #5cc4b2; --accent-soft: #19332f; --warn: #e3a64a; --warn-soft: #2e2414;
43
+ --code-bg: #1d2a27; --term-bg: #0a100e; --term-fg: #d6e6e1; --term-dim: #6f8a83; --term-ok: #7fd1b9;
44
+ color-scheme: dark;
45
+ }
46
+
47
+ * { box-sizing: border-box; }
48
+ body {
49
+ margin: 0;
50
+ background: var(--bg); color: var(--ink);
51
+ font-family: var(--f-body); font-size: 15.5px; line-height: 1.75;
52
+ padding-left: max(16px, env(safe-area-inset-left, 0px));
53
+ padding-right: max(16px, env(safe-area-inset-right, 0px));
54
+ }
55
+ .wrap { max-width: 1040px; margin: 0 auto; padding-block: 56px 96px; }
56
+ .prose { max-width: 700px; }
57
+ a { color: var(--accent); }
58
+ code { font-family: var(--f-mono); font-size: .86em; background: var(--code-bg); padding: 1px 5px; border-radius: 4px; overflow-wrap: anywhere; }
59
+ p { margin: 0 0 12px; }
60
+ strong { font-weight: 700; }
61
+ ul { margin: 0 0 12px; padding-left: 1.3em; }
62
+ li { margin: 3px 0; }
63
+
64
+ /* Hero */
65
+ header.hero { display: grid; grid-template-columns: minmax(0, 1.25fr) minmax(0, 1fr); gap: 48px; align-items: end; padding-bottom: 40px; border-bottom: 1px solid var(--line); }
66
+ .eyebrow { font-family: var(--f-mono); font-size: 12.5px; color: var(--accent); margin-bottom: 14px; }
67
+ h1 { font-family: var(--f-display); font-size: clamp(32px, 5.4vw, 50px); line-height: 1.12; margin: 0 0 18px; letter-spacing: -.015em; text-wrap: balance; }
68
+ .lede { color: var(--muted); font-size: 17px; margin: 0; max-width: 34em; }
69
+ .term { background: var(--term-bg); color: var(--term-fg); border-radius: 10px; padding: 18px 20px; font-family: var(--f-mono); font-size: 13px; line-height: 1.7; overflow-x: auto; min-width: 0; }
70
+ .term .p { color: var(--term-dim); user-select: none; }
71
+ .term .ok { color: var(--term-ok); }
72
+ .term .dim { color: var(--term-dim); }
73
+ .term pre { margin: 0; white-space: pre; }
74
+ .facts { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 22px; }
75
+ .fact { font-family: var(--f-mono); font-size: 12.5px; padding: 3px 10px; border: 1px solid var(--line); border-radius: 999px; background: var(--surface); }
76
+
77
+ /* Sections */
78
+ section { padding-top: 64px; }
79
+ .kicker { font-family: var(--f-mono); font-size: 12px; letter-spacing: .06em; text-transform: uppercase; color: var(--accent); margin-bottom: 8px; }
80
+ h2 { font-family: var(--f-display); font-size: clamp(23px, 3.2vw, 30px); line-height: 1.25; margin: 0 0 14px; text-wrap: balance; letter-spacing: -.01em; }
81
+ h3 { font-size: 16px; margin: 0 0 6px; }
82
+ .sub { color: var(--muted); }
83
+
84
+ /* 痛点对照 */
85
+ .contrast { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 1px; background: var(--line); border: 1px solid var(--line); border-radius: 10px; overflow: hidden; margin-top: 24px; }
86
+ .contrast > div { background: var(--surface); padding: 20px 20px 18px; min-width: 0; }
87
+ .contrast .was { color: var(--muted); font-size: 14px; margin-bottom: 10px; }
88
+ .contrast .was::before { content: "以前 · "; font-family: var(--f-mono); font-size: 12px; color: var(--warn); }
89
+ .contrast .now { font-size: 14.5px; }
90
+ .contrast .now::before { content: "现在 · "; font-family: var(--f-mono); font-size: 12px; color: var(--accent); }
91
+
92
+ /* 架构图 */
93
+ .arch { margin-top: 28px; display: grid; grid-template-columns: minmax(0, 1fr) 210px; gap: 16px; }
94
+ .stack { display: grid; gap: 10px; min-width: 0; }
95
+ .layer { display: grid; grid-template-columns: 112px minmax(0, 1fr); gap: 16px; align-items: stretch; }
96
+ .layer .tag { font-family: var(--f-display); font-weight: 600; font-size: 14px; padding-top: 12px; }
97
+ .layer .tag small { display: block; font-family: var(--f-body); font-weight: 400; font-size: 12.5px; color: var(--muted); line-height: 1.5; margin-top: 2px; }
98
+ .cells { display: flex; flex-wrap: wrap; gap: 8px; padding: 12px; border: 1px solid var(--line); border-radius: 10px; background: var(--surface); min-width: 0; }
99
+ .cell { font-size: 13.5px; padding: 7px 11px; border-radius: 7px; background: var(--code-bg); line-height: 1.4; }
100
+ .cell b { font-family: var(--f-mono); font-weight: 500; font-size: 12.5px; display: block; }
101
+ .cell span { color: var(--muted); font-size: 12.5px; }
102
+ .layer.agent .cells { background: transparent; border-style: dashed; }
103
+ .layer.agent .cell { background: transparent; border: 1px solid var(--line); }
104
+ .layer.core .cells { border-color: var(--accent); background: var(--accent-soft); }
105
+ .layer.core .cell { background: var(--surface); }
106
+ .layer.flow .cells { border-color: var(--accent); background: var(--accent-soft); }
107
+ .layer.flow .cell { background: var(--surface); }
108
+ .layer.view .cells { border-color: var(--line); background: var(--surface); }
109
+ .layer.view .cell { background: var(--warn-soft); }
110
+ .layer.out .cells { background: var(--term-bg); border-color: var(--term-bg); }
111
+ .layer.out .cell { background: transparent; color: var(--term-fg); font-family: var(--f-mono); font-size: 12.5px; padding: 4px 6px; }
112
+ .layer.out .cell span { color: var(--term-dim); font-family: var(--f-body); }
113
+ .side { border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; background: var(--surface); font-size: 13.5px; align-self: stretch; display: grid; align-content: start; gap: 10px; min-width: 0; }
114
+ .side h3 { font-family: var(--f-display); font-size: 14px; margin: 0; }
115
+ .side p { margin: 0; color: var(--muted); }
116
+ .side code { font-size: 12px; }
117
+
118
+ /* dev 流程 */
119
+ .flow { margin-top: 26px; overflow-x: auto; padding-bottom: 6px; }
120
+ .flow ol { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(9, minmax(104px, 1fr)); gap: 0; min-width: 940px; counter-reset: none; }
121
+ .flow li { margin: 0; padding: 0 10px 0 0; position: relative; }
122
+ .flow li::after { content: ""; position: absolute; left: 34px; right: 0; top: 13px; border-top: 1px solid var(--line); }
123
+ .flow li:last-child::after { display: none; }
124
+ .flow .code { position: relative; z-index: 1; display: inline-block; font-family: var(--f-mono); font-size: 12px; font-weight: 500; padding: 3px 7px; border-radius: 6px; background: var(--surface); border: 1px solid var(--line); }
125
+ .flow li.gate .code { background: var(--accent); border-color: var(--accent); color: var(--bg); }
126
+ .flow .name { font-weight: 700; font-size: 14px; margin-top: 10px; }
127
+ .flow .what { color: var(--muted); font-size: 12.5px; line-height: 1.55; margin-top: 4px; }
128
+ .flow .art { display: inline-block; margin-top: 5px; font-family: var(--f-mono); font-size: 10.5px; padding: 1px 5px; border-radius: 5px; background: var(--accent-soft); color: var(--accent); }
129
+ .legend { display: flex; flex-wrap: wrap; gap: 16px; font-size: 13px; color: var(--muted); margin-top: 14px; }
130
+ .legend i { display: inline-block; width: 10px; height: 10px; border-radius: 3px; background: var(--accent); margin-right: 6px; vertical-align: -1px; }
131
+ .sizes { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; margin-top: 22px; }
132
+ .size { border-top: 2px solid var(--line); padding-top: 10px; min-width: 0; }
133
+ .size .s { font-family: var(--f-mono); font-size: 13px; color: var(--accent); }
134
+ .size p { font-size: 14px; margin: 4px 0 0; }
135
+
136
+ /* 设计原则 */
137
+ .principles { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 28px 40px; margin-top: 26px; }
138
+ .principles > div { min-width: 0; }
139
+ .principles h3 { font-family: var(--f-display); font-size: 16.5px; }
140
+ .principles p { color: var(--muted); font-size: 14.5px; margin: 0; }
141
+
142
+ /* 表格 */
143
+ .tbl { overflow-x: auto; margin-top: 22px; border: 1px solid var(--line); border-radius: 10px; background: var(--surface); }
144
+ table { border-collapse: collapse; width: 100%; font-size: 14px; min-width: 620px; }
145
+ th, td { text-align: left; padding: 10px 14px; border-bottom: 1px solid var(--line); vertical-align: top; }
146
+ th { font-family: var(--f-display); font-weight: 600; font-size: 13px; color: var(--muted); }
147
+ tr:last-child td { border-bottom: 0; }
148
+ td:first-child { font-family: var(--f-mono); font-size: 13px; white-space: nowrap; }
149
+ .pill { display: inline-block; font-family: var(--f-mono); font-size: 11.5px; padding: 1px 7px; border-radius: 999px; border: 1px solid var(--line); color: var(--muted); white-space: nowrap; }
150
+ .pill.req { border-color: var(--accent); color: var(--accent); }
151
+
152
+ /* 产物 + 闭环 */
153
+ .two { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 32px; margin-top: 24px; align-items: start; }
154
+ .two > div { min-width: 0; }
155
+ .tree { background: var(--term-bg); color: var(--term-fg); border-radius: 10px; padding: 16px 18px; font-family: var(--f-mono); font-size: 12.5px; line-height: 1.75; overflow-x: auto; }
156
+ .tree pre { margin: 0; white-space: pre; }
157
+ .tree .c { color: var(--term-dim); }
158
+ .loop { display: grid; gap: 0; }
159
+ .loop .step { display: grid; grid-template-columns: 26px minmax(0, 1fr); gap: 12px; padding-bottom: 16px; position: relative; }
160
+ .loop .step::before { content: ""; position: absolute; left: 12px; top: 26px; bottom: 0; border-left: 1px solid var(--line); }
161
+ .loop .step:last-child::before { display: none; }
162
+ .loop .dot { width: 26px; height: 26px; border-radius: 50%; border: 1px solid var(--accent); color: var(--accent); font-family: var(--f-mono); font-size: 12px; display: grid; place-items: center; background: var(--bg); position: relative; }
163
+ .loop .step p { margin: 2px 0 0; font-size: 14px; color: var(--muted); }
164
+ .loop .step b { font-size: 14.5px; }
165
+ .callout { border-left: 3px solid var(--warn); background: var(--warn-soft); padding: 12px 16px; border-radius: 0 8px 8px 0; font-size: 14.5px; margin-top: 18px; }
166
+
167
+ /* 收尾 */
168
+ .cta { margin-top: 72px; padding: 32px; border-radius: 14px; background: var(--accent-soft); display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 28px; align-items: center; }
169
+ .cta h2 { margin-bottom: 8px; }
170
+ .cta p { margin: 0; color: var(--muted); }
171
+ .copy { font-family: var(--f-body); font-size: 12.5px; border: 1px solid var(--term-dim); background: transparent; color: var(--term-fg); border-radius: 6px; padding: 3px 10px; cursor: pointer; margin-top: 10px; }
172
+ .copy:focus-visible, a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
173
+ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
174
+
175
+ @media (max-width: 820px) {
176
+ header.hero, .two, .cta { grid-template-columns: minmax(0, 1fr); gap: 28px; }
177
+ .arch { grid-template-columns: minmax(0, 1fr); }
178
+ .contrast { grid-template-columns: minmax(0, 1fr); }
179
+ .principles { grid-template-columns: minmax(0, 1fr); }
180
+ .sizes { grid-template-columns: minmax(0, 1fr); }
181
+ .layer { grid-template-columns: minmax(0, 1fr); gap: 6px; }
182
+ .layer .tag { padding-top: 0; }
183
+ .layer .tag small { display: inline; margin-left: 8px; }
184
+ .cta { padding: 22px; }
185
+ }
186
+ @media (prefers-reduced-motion: no-preference) {
187
+ .copy { transition: background .15s; }
188
+ }
189
+ </style>
190
+ </head>
191
+ <body>
192
+ <div class="wrap">
193
+
194
+ <header class="hero">
195
+ <div>
196
+ <div class="eyebrow">@rowansenne/workflow-run · 0.30.0 · 2026-10-30</div>
197
+ <h1>让 AI 编程代理按团队的规矩干活</h1>
198
+ <p class="lede">一套装进项目里的 Agent Skills:从需求澄清、开发、测试、自审到技术方案和上线方案,每一步怎么做、做到什么程度、哪些事必须先问人,都写成团队共享的规则和脚本,随代码一起提交。</p>
199
+ <div class="facts">
200
+ <span class="fact">9 个 skill</span>
201
+ <span class="fact">5 种代理环境</span>
202
+ <span class="fact">一条命令安装</span>
203
+ <span class="fact">产物与状态在本地</span>
204
+ </div>
205
+ </div>
206
+ <div class="term" aria-label="安装示例">
207
+ <pre><span class="p">$ </span>npx @rowansenne/workflow-run --with-docnexus --with-codegraph
208
+ <span class="dim">? 选择环境(回车 = 全部)</span>
209
+ <span class="ok">✔</span> .agents/skills/ <span class="dim">单一来源</span>
210
+ <span class="ok">✔</span> .claude/skills/ → 软链接
211
+ <span class="ok">✔</span> DocNexus 运行环境 <span class="dim">.docnexus/</span> · 知识输出 <span class="dim">workflow-run/docnexus/</span>
212
+ <span class="ok">✔</span> CodeGraph 索引 <span class="dim">.codegraph/</span>
213
+ <span class="dim"># 然后在代理里:</span>
214
+ <span class="p">› </span>/workflow profile
215
+ <span class="p">› </span>/dev 给订单列表加导出接口</pre>
216
+ </div>
217
+ </header>
218
+
219
+ <section>
220
+ <div class="kicker">为什么做</div>
221
+ <h2>同一个代理,换个人用、换个模型,结果就不一样</h2>
222
+ <div class="prose">
223
+ <p>代理很会写代码,但它不知道你们的主分支叫什么、构建命令是什么、哪些改动上线前要列配置清单,也不知道团队上次在哪里踩过坑。每个人各写各的提示词,产出的格式和质量就各不相同。workflow-run 把这些放进项目里,所有人、所有代理读的是同一份。</p>
224
+ </div>
225
+ <div class="contrast">
226
+ <div>
227
+ <div class="was">每人一套提示词,交付格式靠自觉</div>
228
+ <div class="now">dev、审查、文档各有固定流程和模板,产物落在同一个需求目录</div>
229
+ </div>
230
+ <div>
231
+ <div class="was">代理自己猜构建命令、凭类名猜表结构</div>
232
+ <div class="now">项目画像记录构建与测试命令;表结构以只读查库的结果为准</div>
233
+ </div>
234
+ <div>
235
+ <div class="was">改完说「测试通过」,没人知道跑没跑</div>
236
+ <div class="now">每条验收标准对应到测试或操作;没验证的写明原因</div>
237
+ </div>
238
+ </div>
239
+ </section>
240
+
241
+ <section>
242
+ <div class="kicker">整体架构</div>
243
+ <h2>安装分发独立,流程、命令、共享核心与能力工具协作</h2>
244
+ <div class="prose">
245
+ <p>宿主代理读取 skill 规则、判断任务并调用脚本;workflow-run 不提供常驻的 Agent 调度服务。工作流命令将共享的路径、数据模型、读取和状态写入交给 <code>workflow/lib</code>,数据库、wiki、Nacos 等能力的执行留在各自目录。</p>
246
+ <p>下图按职责分区,每次请求只经过需要的部分。dev 仅在实际调用 <code>/dev</code> / <code>$dev</code>、点选 skill 或明确要求完整开发工作流时启动;普通分析、修改、测试、提交和推送直接处理。<code>nacos-config</code> 可独立查询,也可在开发或审查中提供配置证据。</p>
247
+ </div>
248
+ <div class="arch">
249
+ <div class="stack">
250
+ <div class="layer agent">
251
+ <div class="tag">代理 · 用户<small>你在用的工具</small></div>
252
+ <div class="cells">
253
+ <div class="cell">Claude Code</div><div class="cell">Codex CLI</div><div class="cell">Qwen Code</div><div class="cell">豆包办公</div><div class="cell">WorkBuddy</div>
254
+ </div>
255
+ </div>
256
+ <div class="layer view">
257
+ <div class="tag">用户 view<small>只读页面,回看下面的数据</small></div>
258
+ <div class="cells">
259
+ <div class="cell"><b>view.mjs</b><span>按需求浏览产物,生成静态页面(/workflow view)</span></div>
260
+ <div class="cell"><b>docnexus view</b><span>本地只读浏览知识库,Ctrl+C 停止</span></div>
261
+ <div class="cell"><b>report.mjs</b><span>效果报告,只读统计产物</span></div>
262
+ </div>
263
+ </div>
264
+ <div class="layer flow">
265
+ <div class="tag">流程型 skill<small>SKILL.md + references:按阶段读取规则</small></div>
266
+ <div class="cells">
267
+ <div class="cell"><b>workflow</b><span>入口路由、能力探测</span></div>
268
+ <div class="cell"><b>dev</b><span>需求 → 交付</span></div>
269
+ <div class="cell"><b>project-review</b><span>代码审查</span></div>
270
+ <div class="cell"><b>create-tech-md-doc</b><span>技术方案</span></div>
271
+ <div class="cell"><b>create-release-md-doc</b><span>上线方案</span></div>
272
+ </div>
273
+ </div>
274
+ <div class="layer">
275
+ <div class="tag">命令脚本<small>workflow/scripts · 确定性命令</small></div>
276
+ <div class="cells">
277
+ <div class="cell"><b>resolve.mjs</b><span>模板来源、能力状态</span></div>
278
+ <div class="cell"><b>requirement.mjs</b><span>需求绑定、产物路径</span></div>
279
+ <div class="cell"><b>run.mjs</b><span>运行状态与恢复</span></div>
280
+ <div class="cell"><b>artifact.mjs</b><span>产物收尾、中断恢复与安全取消</span></div>
281
+ <div class="cell"><b>review-handoff.mjs</b><span>审查交接与结构化结果</span></div>
282
+ <div class="cell"><b>review-scope.mjs</b><span>审查范围与分批</span></div>
283
+ <div class="cell"><b>tables.mjs</b><span>改动涉及的表</span></div>
284
+ <div class="cell"><b>lint-doc.mjs</b><span>文档自检</span></div>
285
+ <div class="cell"><b>pr-desc.mjs</b><span>PR 描述汇总</span></div>
286
+ <div class="cell"><b>feedback.mjs</b><span>运行反馈</span></div>
287
+ <div class="cell"><b>template · locate · knowledge · …</b><span>模板、样例定位、知识检索等</span></div>
288
+ </div>
289
+ </div>
290
+ <div class="layer core">
291
+ <div class="tag">共享核心<small>workflow/lib · 一份定义,读快照、写带锁</small></div>
292
+ <div class="cells">
293
+ <div class="cell"><b>capabilities</b><span>必装组件门槛、可选增强通道</span></div>
294
+ <div class="cell"><b>project</b><span>布局、路径、画像、环境</span></div>
295
+ <div class="cell"><b>document-model</b><span>标题、章节、表格解析(纯模型,无 I/O)</span></div>
296
+ <div class="cell"><b>artifact-model</b><span>产物类型与元信息解析(纯模型,无 I/O)</span></div>
297
+ <div class="cell"><b>requirement-read</b><span>需求目录与元信息读取</span></div>
298
+ <div class="cell"><b>workspace-read</b><span>工作区/Git 统一快照,一次命令读一遍</span></div>
299
+ <div class="cell"><b>requirements</b><span>绑定、版本、归档、sync</span></div>
300
+ <div class="cell"><b>runs</b><span>运行阶段、revision、完成校验</span></div>
301
+ <div class="cell"><b>run-gates</b><span>方案、验证、审查与交付门禁</span></div>
302
+ <div class="cell"><b>code-snapshot</b><span>代码内容摘要与证据有效性</span></div>
303
+ <div class="cell"><b>artifact-finalize</b><span>发布、归档、索引与可恢复收尾</span></div>
304
+ <div class="cell"><b>path-match</b><span>审查与代码证据共用的范围匹配</span></div>
305
+ <div class="cell"><b>meta-store</b><span>写锁与原子替换</span></div>
306
+ </div>
307
+ </div>
308
+ <div class="layer">
309
+ <div class="tag">能力型 skill<small>按任务调用;执行与凭据在各自目录</small></div>
310
+ <div class="cells">
311
+ <div class="cell"><b>code-graph</b><span>影响面、调用入口、MQ、定时任务</span></div>
312
+ <div class="cell"><b>database-query</b><span>只读查库、脱敏</span></div>
313
+ <div class="cell"><b>md-to-wiki</b><span>发布到 Confluence</span></div>
314
+ <div class="cell"><b>nacos-config</b><span>独立只读远程配置、参数与开关</span></div>
315
+ </div>
316
+ </div>
317
+ <div class="layer out">
318
+ <div class="tag">数据与运行环境<small>产物、状态、知识与工具内部文件分开</small></div>
319
+ <div class="cells">
320
+ <div class="cell">workflow/profile.json <span>项目事实;本机覆盖在 profile.local.json</span></div>
321
+ <div class="cell">.docnexus/ · .codegraph/ <span>DocNexus 运行环境 · 本机代码索引</span></div>
322
+ <div class="cell">workflow-run/docs/requirements/ <span>需求产物 + meta.json(分支、运行状态、版本)</span></div>
323
+ <div class="cell">workflow-run/docnexus/ <span>团队知识库</span></div>
324
+ <div class="cell">workflow-run/feedback/ <span>运行反馈</span></div>
325
+ <div class="cell">workflow-run/other/ <span>聊天辅助产物,不进正式需求统计</span></div>
326
+ <div class="cell">workflow-run/tmp/ <span>写锁与临时文件,git 忽略</span></div>
327
+ </div>
328
+ </div>
329
+ </div>
330
+ <aside class="side">
331
+ <h3>安装器 <code>bin/</code></h3>
332
+ <p>和运行流程分开:负责安装、升级、卸载、自检,不参与开发。</p>
333
+ <p><code>bin/skills.mjs</code> 从各目录的 <code>skill.json</code> 自动发现 skills,读取依赖、用户文件、模板和知识分类;<code>package.json.files</code> 控制 npm 包内容。<code>workflow/lib</code> 随 workflow skill 安装。</p>
334
+ <p>共享核心不反向依赖命令脚本、纯模型不做 I/O——这条边界写进了测试,违反会直接跑挂。安装器自己的环境探测也用 <code>lib/project</code>,不另写一份。</p>
335
+ <p>升级只换分发文件;项目画像、数据库、wiki 和 Nacos 本机配置保留不动,手改过的文件先备份。默认单一来源 + 相对软链接,也支持 <code>--copy</code>。</p>
336
+ <p>DocNexus 在安装环节必装,哪怕只选 Nacos;Nacos 读取脚本没有 workflow / DocNexus 运行依赖。DocNexus 自带 skills 不计入本包的 9 个。</p>
337
+ <p><code>npx @rowansenne/workflow-run doctor</code> 检查链接、画像、凭据是否被忽略、数据库能否只读连上。</p>
338
+ </aside>
339
+ </div>
340
+ </section>
341
+
342
+ <section id="calls">
343
+ <div class="kicker">调用与状态</div>
344
+ <h2>完整流程记录证据,独立查询按需读取</h2>
345
+ <div class="two">
346
+ <div>
347
+ <h3>开发 / 审查路径</h3>
348
+ <div class="tree"><pre>宿主代理 → dev / project-review
349
+ → workflow/scripts 命令
350
+ → workflow/lib:门禁、代码证据、状态
351
+ → workflow-run:Markdown + meta.json
352
+ ↳ 按需调用图谱、数据库、wiki、Nacos</pre></div>
353
+ <p class="sub" style="margin-top:12px">完整 dev 的方案批准绑定正文版本,验证和审查绑定执行前代码快照,交付选择绑定本轮报告。artifact 收尾登记待办后发布、归档、更新索引;中断可 resume 或 abort。S 快速通道不绑定需求、不建运行、不落盘。</p>
354
+ </div>
355
+ <div>
356
+ <h3>Nacos 独立路径</h3>
357
+ <div class="tree"><pre>宿主代理 → nacos-config
358
+ → inspect:仅查看本地配置候选
359
+ → 明确环境、Namespace / Group / Data ID
360
+ → get:鉴权 + 只读 HTTP 获取
361
+ → 脱敏属性 + 来源、读取时间、摘要</pre></div>
362
+ <p class="sub" style="margin-top:12px">不创建需求、运行或原文缓存,不改数据库连接。仅配置 GET 与登录 POST;多个环境不猜选。结果是单个配置快照,不代表 Spring 合并、灰度与刷新后的运行时最终值。</p>
363
+ </div>
364
+ </div>
365
+ <div class="callout"><code>meta.json</code> 保存绑定、版本索引、runs 与收尾待办,Markdown 保存正文和发布 / 沉淀引用。<code>view</code> / <code>report</code> 只读取快照;文件存在不等于运行完成。<code>lib</code> 不反向依赖 <code>scripts</code>,纯模型不做 I/O。实现细节见 <a href="../workflow/references/architecture.md">内部模块边界</a>。</div>
366
+ </section>
367
+
368
+ <section>
369
+ <div class="kicker">主线:dev</div>
370
+ <h2>一个需求从描述到交付,人只在关键处拍板</h2>
371
+ <div class="prose">
372
+ <p>用户实际调用 <code>/dev &lt;需求&gt;</code>、<code>/dev --bug &lt;现象&gt;</code>、<code>$dev</code>,或明确要求 dev / 完整开发工作流后才进入。事实代理自己查(代码、表结构、远程配置、PRD、历史沉淀),决定交给人(业务规则、取舍、范围)。</p>
373
+ <p>Codex 元数据关闭隐式调用;其他环境也由入口规则和项目说明约束。讨论命令、发现旧运行、要求分析或提交代码都不启动新流程。已授权任务可按保存阶段续接,当前独立操作不重做前置步骤或自行推进阶段。</p>
374
+ </div>
375
+ <div class="flow">
376
+ <ol>
377
+ <li><span class="code">Step 0</span><div class="name">前置检查</div><div class="what">读画像,先确定工作分支,再问清需求名(给不出就不开始)与工作区里已有的改动归谁,跑一次基线</div></li>
378
+ <li><span class="code">F1</span><div class="name">理解需求</div><div class="what">拉 PRD,召回以往的约定和坑,列初版验收标准</div></li>
379
+ <li class="gate"><span class="code">F2</span><div class="name">业务核对与调研</div><div class="what">先落业务场景清单,与产品逐轮核对;明确后结合场景调研代码与数据<br><span class="art">clarification.md</span></div></li>
380
+ <li class="gate"><span class="code">F3</span><div class="name">需求澄清</div><div class="what">基于已确认场景澄清可行性、接口兼容、数据与权限等技术约束;确认理解一致后收尾需求文档<br><span class="art">requirement.md</span></div></li>
381
+ <li class="gate"><span class="code">F4</span><div class="name">方案</div><div class="what">需求明确后引用需求版本,写实现设计、实施和验证计划(S / M 简版);M / L 确认方案后实现<br><span class="art">plan.md</span></div></li>
382
+ <li><span class="code">F5</span><div class="name">实现</div><div class="what">贴合现有写法,不顺手重构;SQL 只写脚本不执行</div></li>
383
+ <li><span class="code">F6</span><div class="name">验证</div><div class="what">先相关测试再全量;完整流程绑定执行前代码快照,验收项逐条对应到证据</div></li>
384
+ <li class="gate"><span class="code">F7</span><div class="name">审查</div><div class="what">完整流程自动生成交接材料,优先独立子 agent 审查;返回草稿与结构化结果,由主 agent 收尾 review.md,再等用户选择修复或交付<br><span class="art">review.md</span></div></li>
385
+ <li class="gate"><span class="code">F8</span><div class="name">交付</div><div class="what">用户选择交付后才生成交付说明;提交、PR 先问,沉淀有值得记的内容才问<br><span class="art">delivery.md</span></div></li>
386
+ </ol>
387
+ </div>
388
+ <div class="legend"><span><i></i>需要人确认的节点</span><span><b>正式产物落盘</b>:F2 <code>clarification.md</code>(业务核对)→ F3 <code>requirement.md</code> → F4 <code>plan.md</code> → F7 <code>review.md</code> → F8 <code>delivery.md</code>(选择交付后);S 快速通道不落任何产物</span><span>缺陷修复走 B1 收集现象 → B2 复现 → B3 定位根因并生成 <code>requirement.md</code> → B4 追加 <code>plan.md</code> → B5 审查与交付(<code>review.md</code> / <code>delivery.md</code>)</span></div>
389
+ <div class="callout">
390
+ <b>F3 前先核对业务场景,再澄清技术约束</b>
391
+ <p>输出待确认清单 → 用户与产品核对、完善 PRD → 带回答复或新版 PRD → 更新原清单并追加新问题。每轮保留 Q 编号与已确认项,汇总「已确认 / 仍待确认 / 本轮新增」和 PRD 调整建议;仍有未定业务项就留在 F2,继续这个循环。</p>
392
+ <p>业务场景明确后,完成 F2 现状调研,再进入 F3 核对系统能力、接口、数据、兼容性等技术约束;技术限制改变业务场景时回 F2 找产品确认。业务与技术均明确后,收尾 <code>requirement.md</code>、进入 F4 写实现方案。没有业务待确认项且用户未要求清单时可省清单,沿用快速通道判定。</p>
393
+ <span class="sub">清单按 <code>clarification-template.md</code> 生成,经 finalize 发布到同一需求目录;每轮归档旧版,等待时保存 waiting_user,新会话恢复同一运行继续。清单发布不代表 F2 调研或 F3 技术澄清已完成;清单关注角色、操作场景、业务规则、范围和验收。</span>
394
+ </div>
395
+ <div class="sizes">
396
+ <div class="size"><div class="s">S · 快速通道</div><p>≤3 个文件,不碰接口、表、配置、权限、资金,无 F2 / F3 已确认的业务决定,本次未发布正式清单且未创建完整运行。已有清单或运行继续完整流程;符合资格时走不走由用户选:同意则编译、测试照常,审查在当前会话做;不绑定需求、不落产物文件(连方案也不写),一次对话交付并注明「未询问」。</p></div>
397
+ <div class="size"><div class="s">M</div><p>改接口、配置项、少量字段,或涉及权限、资金。先确认需求理解,再确认落盘的简要方案。</p></div>
398
+ <div class="size"><div class="s">L</div><p>新模块、跨服务、数据迁移。写完整方案文档落盘,确认后再写代码,之后可生成正式技术方案。</p></div>
399
+ </div>
400
+ </section>
401
+
402
+ <section>
403
+ <div class="kicker">设计取舍</div>
404
+ <h2>几条贯穿所有 skill 的约定</h2>
405
+ <div class="principles">
406
+ <div>
407
+ <h3>项目事实只写一处</h3>
408
+ <p>主分支、构建和测试命令、配置中心、发布平台、开发环境配置(<code>toolchain</code>:JDK / Maven / Node 的位置)都在 <code>workflow/profile.json</code>。模板里不写死任何公司或项目的约定,换个项目只改画像;个人机器不同的部分写进不提交的 <code>profile.local.json</code> 覆盖。</p>
409
+ </div>
410
+ <div>
411
+ <h3>能用脚本就不靠模型</h3>
412
+ <p>模板该取哪份、产物写到哪、改动涉及哪些表、文档缺了哪节,都由脚本给出 JSON 结果。命令在 bash、zsh、PowerShell 里写法一样。</p>
413
+ </div>
414
+ <div>
415
+ <h3>开工统一选择能力</h3>
416
+ <p>工作流开工快照检查必装 DocNexus,并选择 CodeGraph、数据库和 wiki 通道。Nacos 由独立 skill 按需读取,尚未纳入集中状态探测;<code>config_center: nacos</code> 只说明项目类型,不代表连接已验证。</p>
417
+ </div>
418
+ <div>
419
+ <h3>按任务授权执行写操作</h3>
420
+ <p>提交、推送、发布 wiki、写知识库按流程取得授权;数据库默认只读,可写连接也须明确同意后执行写语句。Nacos skill 仅提供读取;安装器按安装请求接入所需依赖。</p>
421
+ </div>
422
+ <div>
423
+ <h3>一份文件,五个环境</h3>
424
+ <p>默认在 <code>.agents/skills/</code> 装一份,其他环境逐 skill 建相对链接;<code>--copy</code> 可改为各装一份。规则可共享,连接和本机依赖不提交;生效模板保存在 DocNexus。</p>
425
+ </div>
426
+ <div>
427
+ <h3>结论要有出处</h3>
428
+ <p>关于现有代码的结论指向真实文件和行号;审查发现要写出触发条件,严重级别的发现交给独立的子代理复核,减少误报。</p>
429
+ </div>
430
+ </div>
431
+ </section>
432
+
433
+ <section>
434
+ <div class="kicker">9 个 skill</div>
435
+ <h2>按需安装,依赖自动带上</h2>
436
+ <div class="prose"><p><code>--skills dev</code> 会一起装上它必需的 <code>workflow</code> 和 <code>project-review</code>;可选协作没装时跳过对应增强。<code>--skills nacos-config</code> 无其他 skill 依赖;安装器仍接入必装 DocNexus。</p></div>
437
+ <div class="tbl">
438
+ <table>
439
+ <thead><tr><th>skill</th><th>做什么</th><th>依赖</th></tr></thead>
440
+ <tbody>
441
+ <tr><td>workflow</td><td>入口:按请求路由到对应 skill;维护项目画像;<code>status</code> 检查各能力是否可用</td><td><span class="pill">无</span></td></tr>
442
+ <tr><td>dev</td><td>功能开发与缺陷修复,从需求澄清到交付说明</td><td><span class="pill req">workflow</span> <span class="pill req">project-review</span></td></tr>
443
+ <tr><td>project-review</td><td>审分支或未提交改动:14 维度清单、影响面、发现复核、复审对比</td><td><span class="pill req">workflow</span></td></tr>
444
+ <tr><td>code-graph</td><td>基于 CodeGraph:改动影响到的接口、MQ 消费者、定时任务、测试、SQL 和表</td><td><span class="pill req">workflow</span></td></tr>
445
+ <tr><td>database-query</td><td>会话级只读查询,拦截写语句、自动 LIMIT、敏感字段脱敏</td><td><span class="pill req">workflow</span></td></tr>
446
+ <tr><td>nacos-config</td><td>从 application / bootstrap 定位连接,按需只读获取配置、参数与开关;可被 dev / project-review 调用</td><td><span class="pill">无</span></td></tr>
447
+ <tr><td>create-tech-md-doc</td><td>从分支 diff 按团队模板生成技术方案</td><td><span class="pill req">workflow</span></td></tr>
448
+ <tr><td>create-release-md-doc</td><td>从分支 diff 生成上线方案,自动引用同分支的技术方案和交付说明</td><td><span class="pill req">workflow</span></td></tr>
449
+ <tr><td>md-to-wiki</td><td>把 md 转成 Confluence 格式并发布;未配置时不启动</td><td><span class="pill req">workflow</span></td></tr>
450
+ </tbody>
451
+ </table>
452
+ </div>
453
+ </section>
454
+
455
+ <section>
456
+ <div class="kicker">常用命令</div>
457
+ <h2>日常就两类输入:代理里说需求,终端里管安装</h2>
458
+ <div class="prose">
459
+ <p>开发、审查、出文档在装好 skills 的代理会话里完成;安装、升级、自检在项目根的终端执行,命令前缀统一是 <code>npx @rowansenne/workflow-run</code>,下表写全。</p>
460
+ </div>
461
+ <div class="tbl">
462
+ <table>
463
+ <thead><tr><th>代理里输入</th><th>做什么</th></tr></thead>
464
+ <tbody>
465
+ <tr><td>/dev &lt;需求描述&gt;</td><td>功能开发全流程:确定工作分支 → 定需求名 → F2 业务场景清单与产品核对(多轮更新)→ F3 技术澄清 → 需求明确 → 方案 → 实现 → 测试 → 独立子 agent 审查与报告(无则当前会话自查)→ 用户选择修复或交付(完整交付才生成交付说明)</td></tr>
466
+ <tr><td>/dev --bug &lt;现象&gt;</td><td>缺陷修复全流程:复现 → 定位根因 → 最小修复 → 验证 → 审查报告 → 用户选择修复或交付</td></tr>
467
+ <tr><td>/workflow</td><td>按明确请求路由独立能力;dev 须有显式流程授权。普通修改或提交不进入 dev;不带请求时输出能力地图和状态</td></tr>
468
+ <tr><td>/workflow profile</td><td>填写或更新项目画像(主分支、构建测试命令、toolchain)</td></tr>
469
+ <tr><td>/workflow status</td><td>开工快照:DocNexus 必装门槛、CodeGraph 通道、数据库与 wiki 配置</td></tr>
470
+ <tr><td>读取测试环境 Nacos 的 order.yaml,查看 order.timeout</td><td>进入 nacos-config:定位本地连接,选择环境和 Data ID,再只读获取脱敏结果</td></tr>
471
+ <tr><td>/workflow template &lt;模板&gt; [怎么改]</td><td>修改或创建文档模板:clarification、requirement、tech、release、plan、delivery、review、checklist</td></tr>
472
+ <tr><td>/create-tech-md-doc &lt;dev分支&gt; &lt;主分支&gt;</td><td>从分支 diff 按团队模板生成技术方案</td></tr>
473
+ <tr><td>/create-release-md-doc &lt;dev分支&gt; &lt;主分支&gt;</td><td>生成上线方案,自动引用同分支的技术方案和交付说明</td></tr>
474
+ <tr><td>/workflow report</td><td>效果报告:审查发现与修复率、需求澄清、DocNexus 沉淀与复用</td></tr>
475
+ <tr><td>/workflow view</td><td>按需求浏览全部产物的本地页面(加 --open 直接打开)</td></tr>
476
+ <tr><td>/md-to-wiki &lt;md&gt; [pageId]</td><td>发布到 Confluence;发布过的文档省略 pageId 直接更新</td></tr>
477
+ </tbody>
478
+ </table>
479
+ </div>
480
+ <p class="sub" style="margin-top:10px">project-review 和 database-query 没有斜杠命令:直接说「审一下这次改动」「查一下 order 表有哪些索引」就会触发。</p>
481
+ <div class="tbl">
482
+ <table>
483
+ <thead><tr><th>终端里执行(项目根)</th><th>做什么</th></tr></thead>
484
+ <tbody>
485
+ <tr><td>npx @rowansenne/workflow-run init --with-docnexus --with-codegraph</td><td>首次安装 / 重装;<code>--skills dev</code> 只装子集,<code>--copy</code> 不建软链接</td></tr>
486
+ <tr><td>npx @rowansenne/workflow-run upgrade</td><td>升级到当前版本:用户配置保留,手改过的文件先备份</td></tr>
487
+ <tr><td>npx @rowansenne/workflow-run doctor</td><td>自检:版本、软链接、项目画像、DocNexus 模板、数据库连通、.gitignore</td></tr>
488
+ <tr><td>npx @rowansenne/workflow-run seed-templates</td><td>把自带的文档模板导入 DocNexus(已有的不覆盖)</td></tr>
489
+ <tr><td>npx @rowansenne/workflow-run view --open</td><td>生成并打开项目文档视图(同 /workflow view)</td></tr>
490
+ <tr><td>npx @rowansenne/workflow-run docnexus view</td><td>打开 DocNexus 知识库的本地只读浏览页面(前台常驻,Ctrl+C 停止)</td></tr>
491
+ <tr><td>npx @rowansenne/workflow-run report --since 2026-10-01</td><td>效果报告(同 /workflow report),只读统计产物</td></tr>
492
+ <tr><td>npx @rowansenne/workflow-run feedback --json</td><td>运行反馈汇总:提问轮数、跳过的步骤、读不懂的规则,精简 skill 的依据</td></tr>
493
+ <tr><td>npx @rowansenne/workflow-run docs-repo &lt;仓库地址&gt;</td><td>改用团队独立文档仓库;不带地址显示当前状态</td></tr>
494
+ <tr><td>npx @rowansenne/workflow-run uninstall</td><td>按安装清单卸载,用户配置备份到 workflow-run/tmp/</td></tr>
495
+ </tbody>
496
+ </table>
497
+ </div>
498
+ <p class="sub" style="margin-top:10px">skill 内部还有一批脚本命令(<code>resolve.mjs</code>、<code>requirement.mjs</code>、<code>review-scope.mjs</code>、<code>template.mjs</code>、<code>locate.mjs</code>、<code>tables.mjs</code>、<code>knowledge.mjs</code> 等),由各流程自动调用,不用记。</p>
499
+ </section>
500
+
501
+ <section>
502
+ <div class="kicker">连接配置</div>
503
+ <h2>各能力维护连接,配置检查与远端验证分开</h2>
504
+ <div class="prose">
505
+ <p>默认在 <code>.agents/skills/</code> 维护连接,其他环境通过相对软链接复用;<code>--copy</code> 时各份独立。数据库、wiki 与可选 Nacos 本机连接均已加入 <code>.gitignore</code>,重装保留。配置存在只说明可以尝试连接,网络与鉴权仍由实际请求验证。</p>
506
+ </div>
507
+ <div class="two">
508
+ <div>
509
+ <h3>数据库连接 · <code>database-query/config.json</code></h3>
510
+ <p>安装时交互生成第一个连接,之后直接编辑文件增加连接(安装时用 <code>--skip-db</code> 跳过的,重跑补配即可;已有的 <code>.codex/database-query/config.json</code> 会自动迁移)。驱动支持 MySQL / MariaDB / PostgreSQL(走本机 <code>mysql</code> / <code>psql</code> 客户端):</p>
511
+ <div class="tree" aria-label="数据库配置示例">
512
+ <pre>{
513
+ "default_connection": "dev",
514
+ "connections": {
515
+ "dev": {
516
+ "driver": "mysql",
517
+ "host": "127.0.0.1", "port": 3306,
518
+ "database": "app",
519
+ "user": "app_ro",
520
+ "password_env": "APP_DEV_DB_PASSWORD",
521
+ "readonly": true
522
+ }
523
+ },
524
+ "mask_columns": ["id_card", "phone"]
525
+ }</pre>
526
+ </div>
527
+ <ul>
528
+ <li><strong>只读是默认</strong>:<code>readonly</code> 为 true 或缺省都按只读处理,写语句在会话层直接拦截;只有显式 <code>"readonly": false</code> 的连接才允许写,而且要你点名用那个连接。</li>
529
+ <li><strong>密码不进对话</strong>:按 <code>password_env</code> 指向的环境变量 → <code>DB_PASSWORD</code> → <code>password</code> 字段的顺序取,推荐用环境变量。</li>
530
+ <li><code>mask_columns</code>(顶层或单连接,正则数组)追加脱敏列;手机号、证件号、银行卡等默认已打码。</li>
531
+ <li><code>npx @rowansenne/workflow-run doctor</code> 会试连一次验证配置(<code>--offline</code> 跳过连通性测试)。</li>
532
+ </ul>
533
+ </div>
534
+ <div>
535
+ <h3>wiki 连接 · <code>md-to-wiki/wiki-config.json</code></h3>
536
+ <p>安装后默认 <code>enabled: false</code>,不配置就不启动。按环境分两种情况:</p>
537
+ <p><strong>没装 wiki MCP</strong> —— 填 <code>enabled: true</code> + <code>base_url</code> + <code>api_token</code>(Confluence 的个人访问令牌)和 <code>username</code>,发布与 PRD 拉取走 REST 通道:</p>
538
+ <div class="tree" aria-label="wiki 配置示例">
539
+ <pre>{
540
+ "enabled": true,
541
+ "wiki": {
542
+ "base_url": "https://wiki.example.com",
543
+ "username": "me@example.com",
544
+ "api_token": "‹Confluence PAT›",
545
+ "remote_url": ""
546
+ }
547
+ }</pre>
548
+ </div>
549
+ <ul>
550
+ <li><strong>已装 wiki MCP</strong>(如 Claude Code 里配了 <code>wiki-mcp</code>,工具名形如 <code>mcp__wiki-mcp__get_page</code>):skill 自动优先走 MCP 通道,REST 字段可以不填;<code>mcp_server</code> 默认 <code>wiki-mcp</code>,<code>remote_url</code> 可选记录远程 MCP 地址。</li>
551
+ <li>两种都配了:有 MCP 工具就用 MCP,没有再走 REST。</li>
552
+ </ul>
553
+ <div class="callout">wiki 未配置时 md-to-wiki 直接不启动;技术 / 上线方案的 <code>--prd</code> 增强自动回退纯 diff 流程,文档生成主流程不受影响。dev 拉 PRD 用同一套判定。</div>
554
+ </div>
555
+ </div>
556
+ <h3 style="margin-top:28px">Nacos · 优先复用 application / bootstrap</h3>
557
+ <p>不强制填写第二份连接。<code>inspect</code> 列出本地候选,明确环境后,<code>get</code> 从所选文件解析 Nacos 参数与占位符。也可自行创建 <code>nacos-config/config.json</code>,用 <code>--conn test</code> 选择命名连接,密码 / token 仅通过环境变量引用。详情见 <a href="../nacos-config/references/connection.md">连接格式与协议</a>。</p>
558
+ <div class="tree"><pre>node .agents/skills/nacos-config/scripts/config.mjs inspect
559
+ 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></div>
560
+ <p class="sub" style="margin-top:12px">支持 JSON / YAML / properties;首次解析 YAML 若缺依赖,在该 skill 目录运行 npm 安装。默认使用 Nacos 1.x / 2.x 的兼容 API,也可显式选择 2.x API 或 3.x Client API。<code>/workflow status</code> 与 <code>doctor</code> 均不测试 Nacos 远端连通性;doctor 会检查本机连接文件的忽略规则。</p>
561
+ <div class="callout">本页对应 0.30.0,包含 F2 业务核对与 F3 技术澄清流程;dev 工作流仅在用户显式要求时启动。</div>
562
+ </section>
563
+
564
+ <section>
565
+ <div class="kicker">产物与知识</div>
566
+ <h2>正式文档按需求归档,好的经验会回到下一次开发</h2>
567
+ <div class="two">
568
+ <div>
569
+ <div class="tree" aria-label="需求目录结构">
570
+ <pre>workflow-run/docs/requirements/
571
+ └── 订单导出/ <span class="c"># 需求名由你定</span>
572
+ └── order-service/ <span class="c"># 项目名,跨服务各占一层</span>
573
+ ├── meta.json <span class="c"># 分支、运行状态、版本、wiki、沉淀记录</span>
574
+ ├── clarification.md <span class="c"># 业务场景清单(F2 / B3,多轮反馈、版本归档)</span>
575
+ ├── requirement.md <span class="c"># 需求文档(F3 / B3;目标、范围、AC 验收与澄清决定)</span>
576
+ ├── plan.md <span class="c"># 方案(F4;非快速通道都写。缺陷修复在 B4 追加「修复方案」节)</span>
577
+ ├── delivery.md <span class="c"># 交付说明(F8 / B5,选择交付后)</span>
578
+ ├── review.md <span class="c"># 审查报告(F7 / B5,每轮)</span>
579
+ ├── tech-doc.md <span class="c"># 技术方案(create-tech-md-doc)</span>
580
+ └── release-doc.md <span class="c"># 上线方案(create-release-md-doc)</span></pre>
581
+ </div>
582
+ <p class="sub" style="margin-top:12px;font-size:14px">可以随代码提交,也可以把 <code>workflow-run/</code> 整个换成团队的独立文档仓库,多个服务共用,目录结构不变。<code>npx @rowansenne/workflow-run view</code> 生成本地页面按需求浏览。</p>
583
+ <p class="sub" style="margin-top:12px;font-size:14px">业务场景清单与需求文档是两个独立正式产物。需要清单时,在 F2 / B3 初判规模、选择完整流程并 bind、start;每轮从草稿 finalize 为 <code>clarification.md</code>,更新原问题答复和状态、追加新问题与反馈记录,保留编号并归档旧版,纳入视图、统计与 PR 引用。F3 / B3 完成技术澄清后,<code>requirement.md</code> 引用清单及版本,汇总有效业务决定与技术约束。</p>
584
+ </div>
585
+ <div class="loop">
586
+ <div class="step"><div class="dot">1</div><div><b>开工前召回</b><p>dev 和审查先查 DocNexus 里以往的开发约定、技术方案和反复出现的审查问题。</p></div></div>
587
+ <div class="step"><div class="dot">2</div><div><b>过程中引用</b><p>用上的知识在产物里写明出处 <code>workflow-run/docnexus/library/&lt;path&gt;</code>。</p></div></div>
588
+ <div class="step"><div class="dot">3</div><div><b>交付时沉淀</b><p>交付里有值得记的内容才问:已确认的决定、新约定、缺陷根因;没有就跳过,元信息行写「无需沉淀」。同主题的更新原文,不重复新建。</p></div></div>
589
+ <div class="step"><div class="dot">4</div><div><b>下次被召回</b><p>审查沉淀的问题模式,会在下一次 dev 开工时被列出来。</p></div></div>
590
+ <div class="callout">写入知识库每次都要你同意;没有值得沉淀的内容时不问。DocNexus 是必装组件,不可用时先修复,不降级。</div>
591
+ <p class="sub" style="margin-top:12px;font-size:14px">想直接翻知识库:在项目根运行 <code>npx @rowansenne/workflow-run docnexus view</code>,会起一个本地只读的文档浏览服务并打印访问地址,<code>Ctrl+C</code> 停止。加 <code>--port 8080</code> 可指定端口,不加则随机。</p>
592
+ </div>
593
+ </div>
594
+ </section>
595
+
596
+ <section>
597
+ <div class="kicker">持续改进</div>
598
+ <h2>skill 自己也按数据迭代</h2>
599
+ <div class="prose">
600
+ <p>dev 和 project-review 每跑完一次,静默记一行过程数据到 <code>workflow-run/feedback/&lt;用户&gt;.jsonl</code>:提问了几轮、用户纠正过几次理解、跳过了哪些步骤、哪条规则读不懂或做不到。只记过程,不记代码和业务名词,也不额外打扰用户。</p>
601
+ <p>团队用两三周后,<code>npx @rowansenne/workflow-run feedback</code> 按 skill 和章节汇总,据此精简或修正规则、发新版本;各项目升级时清掉旧版本的记录,从新版本重新收集。结果类数据(审查发现、修复率、沉淀率)则由 <code>npx @rowansenne/workflow-run report</code> 命令从产物里统计。</p>
602
+ </div>
603
+ </section>
604
+
605
+ <div class="cta">
606
+ <div>
607
+ <h2>在项目根试一下</h2>
608
+ <p>推荐全量安装,同时接入 DocNexus 文档库和 CodeGraph 代码图谱,需要 Node.js 22.13 及以上。装完运行 <code>/workflow profile</code> 填项目画像,再用 <code>/dev</code> 提一个小需求。分步说明见 <a href="full-install.html">图文教程</a>。</p>
609
+ </div>
610
+ <div class="term">
611
+ <pre id="cmd"><span class="p">$ </span>npx @rowansenne/workflow-run --with-docnexus --with-codegraph</pre>
612
+ <button class="copy" id="copy-btn" type="button">复制命令</button>
613
+ </div>
614
+ </div>
615
+
616
+ <footer>workflow-run · 支持 Codex CLI、Claude Code、Qwen Code、豆包办公、腾讯 WorkBuddy</footer>
617
+ </div>
618
+ <script>
619
+ document.getElementById('copy-btn').addEventListener('click', (e) => {
620
+ const btn = e.currentTarget;
621
+ const text = 'npx @rowansenne/workflow-run --with-docnexus --with-codegraph';
622
+ const done = () => { btn.textContent = '已复制'; setTimeout(() => { btn.textContent = '复制命令'; }, 1600); };
623
+ const fallback = () => { const r = document.createRange(); r.selectNodeContents(document.getElementById('cmd')); const s = getSelection(); s.removeAllRanges(); s.addRange(r); btn.textContent = '已选中,按 ⌘C / Ctrl+C 复制'; };
624
+ try { navigator.clipboard.writeText(text).then(done, fallback); } catch { fallback(); }
625
+ });
626
+ </script>
627
+ </body>
628
+ </html>