@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.
- package/CHANGELOG.md +17 -0
- package/README.md +45 -841
- package/dev/SKILL.md.tpl +8 -7
- package/dev/references/bug.md +1 -0
- package/dev/references/clarification-template.md +40 -0
- package/dev/references/clarify.md +40 -36
- package/dev/references/delivery.md +1 -1
- package/dev/references/planning.md +14 -14
- package/dev/references/preflight.md +1 -1
- package/dev/references/requirement-template.md +2 -2
- package/dev/skill.json +6 -0
- package/docs/architecture.html +628 -0
- package/docs/development.md +221 -0
- package/docs/docnexus-integration-plan.md +56 -0
- package/docs/full-install.html +491 -0
- package/docs/installation.md +211 -0
- package/docs/integrations.md +160 -0
- package/docs/team-guide.md +166 -0
- package/docs/workflows.md +129 -0
- package/package.json +4 -2
- package/workflow/SKILL.md.tpl +1 -1
- package/workflow/lib/artifact-finalize.mjs +20 -11
- package/workflow/lib/artifact-model.mjs +2 -2
- package/workflow/lib/code-snapshot.mjs +8 -2
- package/workflow/lib/run-gates.mjs +20 -20
- package/workflow/lib/runs.mjs +5 -4
- package/workflow/references/architecture.md +1 -1
- package/workflow/references/execution.md +10 -2
- package/workflow/references/requirements.md +3 -2
- package/workflow/references/runs.md +5 -5
- package/workflow/references/templates.md +2 -2
- package/workflow/scripts/artifact.mjs +1 -1
- package/workflow/scripts/pr-desc.mjs +2 -2
- package/workflow/scripts/requirement.mjs +2 -2
- package/workflow/scripts/review-handoff.mjs +4 -3
- package/workflow/scripts/template.mjs +3 -2
|
@@ -0,0 +1,491 @@
|
|
|
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
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
8
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
9
|
+
<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">
|
|
10
|
+
<style>
|
|
11
|
+
/* Layout: 左侧固定目录 + 右侧单栏正文(约 68ch);窄屏目录收到顶部 */
|
|
12
|
+
:root {
|
|
13
|
+
--bg: #f5f7f6;
|
|
14
|
+
--surface: #ffffff;
|
|
15
|
+
--ink: #18221f;
|
|
16
|
+
--muted: #5b6965;
|
|
17
|
+
--line: #d9e1de;
|
|
18
|
+
--accent: #0d6b62;
|
|
19
|
+
--accent-soft: #e0efec;
|
|
20
|
+
--warn: #9a5b00;
|
|
21
|
+
--warn-soft: #fbf0dc;
|
|
22
|
+
--code-bg: #eef2f1;
|
|
23
|
+
--term-bg: #14201d;
|
|
24
|
+
--term-fg: #d6e6e1;
|
|
25
|
+
--term-dim: #7f9a93;
|
|
26
|
+
--term-ok: #7fd1b9;
|
|
27
|
+
--f-display: "Instrument Sans", "Noto Sans SC", system-ui, sans-serif;
|
|
28
|
+
--f-body: "Noto Sans SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif;
|
|
29
|
+
--f-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, Consolas, monospace;
|
|
30
|
+
}
|
|
31
|
+
@media (prefers-color-scheme: dark) {
|
|
32
|
+
:root:not([data-theme="light"]) {
|
|
33
|
+
--bg: #101715; --surface: #172220; --ink: #e2ebe8; --muted: #93a6a0; --line: #2a3835;
|
|
34
|
+
--accent: #5cc4b2; --accent-soft: #19332f; --warn: #e3a64a; --warn-soft: #2e2414;
|
|
35
|
+
--code-bg: #1d2a27; --term-bg: #0a100e; --term-fg: #d6e6e1; --term-dim: #6f8a83; --term-ok: #7fd1b9;
|
|
36
|
+
color-scheme: dark;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
:root[data-theme="dark"] {
|
|
40
|
+
--bg: #101715; --surface: #172220; --ink: #e2ebe8; --muted: #93a6a0; --line: #2a3835;
|
|
41
|
+
--accent: #5cc4b2; --accent-soft: #19332f; --warn: #e3a64a; --warn-soft: #2e2414;
|
|
42
|
+
--code-bg: #1d2a27; --term-bg: #0a100e; --term-fg: #d6e6e1; --term-dim: #6f8a83; --term-ok: #7fd1b9;
|
|
43
|
+
color-scheme: dark;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
* { box-sizing: border-box; }
|
|
47
|
+
body {
|
|
48
|
+
margin: 0;
|
|
49
|
+
background: var(--bg); color: var(--ink);
|
|
50
|
+
font-family: var(--f-body); font-size: 15.5px; line-height: 1.75;
|
|
51
|
+
padding-left: max(16px, env(safe-area-inset-left, 0px));
|
|
52
|
+
padding-right: max(16px, env(safe-area-inset-right, 0px));
|
|
53
|
+
}
|
|
54
|
+
.shell { max-width: 1120px; margin: 0 auto; display: grid; grid-template-columns: 210px minmax(0, 1fr); gap: 56px; padding-block: 48px 96px; }
|
|
55
|
+
nav.toc { position: sticky; top: calc(env(safe-area-inset-top, 0px) + 32px); align-self: start; font-size: 13.5px; }
|
|
56
|
+
nav.toc .label { font-family: var(--f-display); text-transform: uppercase; letter-spacing: .08em; font-size: 11.5px; color: var(--muted); margin-bottom: 10px; }
|
|
57
|
+
nav.toc ol { list-style: none; margin: 0; padding: 0; display: grid; gap: 2px; border-left: 1px solid var(--line); }
|
|
58
|
+
nav.toc a { display: block; padding: 4px 0 4px 14px; margin-left: -1px; border-left: 2px solid transparent; color: var(--muted); text-decoration: none; }
|
|
59
|
+
nav.toc a:hover { color: var(--ink); }
|
|
60
|
+
nav.toc a.on { color: var(--accent); border-left-color: var(--accent); }
|
|
61
|
+
main { min-width: 0; max-width: 720px; }
|
|
62
|
+
|
|
63
|
+
header.top { display: grid; gap: 14px; padding-bottom: 32px; border-bottom: 1px solid var(--line); margin-bottom: 8px; }
|
|
64
|
+
.eyebrow { font-family: var(--f-mono); font-size: 12.5px; color: var(--accent); }
|
|
65
|
+
h1 { font-family: var(--f-display); font-size: clamp(30px, 5vw, 42px); line-height: 1.15; margin: 0; letter-spacing: -.01em; text-wrap: balance; }
|
|
66
|
+
h1 .pkg { font-family: var(--f-mono); font-weight: 500; font-size: .62em; color: var(--muted); display: block; margin-top: 8px; letter-spacing: 0; }
|
|
67
|
+
.lede { margin: 0; color: var(--muted); max-width: 62ch; }
|
|
68
|
+
.facts { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 4px; }
|
|
69
|
+
.fact { font-family: var(--f-mono); font-size: 12.5px; padding: 3px 10px; border: 1px solid var(--line); border-radius: 999px; background: var(--surface); }
|
|
70
|
+
|
|
71
|
+
section { padding-top: 44px; scroll-margin-top: 24px; }
|
|
72
|
+
h2 { font-family: var(--f-display); font-size: 23px; line-height: 1.3; margin: 0 0 14px; text-wrap: balance; display: flex; gap: 12px; align-items: baseline; }
|
|
73
|
+
h2 .n { font-family: var(--f-mono); font-size: 13px; font-weight: 500; color: var(--accent); }
|
|
74
|
+
h3 { font-size: 16px; margin: 26px 0 8px; }
|
|
75
|
+
p { margin: 0 0 12px; }
|
|
76
|
+
ul, ol.plain { margin: 0 0 12px; padding-left: 1.3em; }
|
|
77
|
+
li { margin: 3px 0; }
|
|
78
|
+
a { color: var(--accent); }
|
|
79
|
+
code { font-family: var(--f-mono); font-size: .86em; background: var(--code-bg); padding: 1px 5px; border-radius: 4px; overflow-wrap: anywhere; }
|
|
80
|
+
strong { font-weight: 700; }
|
|
81
|
+
|
|
82
|
+
.cmd { position: relative; background: var(--term-bg); color: var(--term-fg); border-radius: 8px; margin: 12px 0 16px; }
|
|
83
|
+
.cmd pre { margin: 0; padding: 14px 92px 14px 16px; overflow-x: auto; font-family: var(--f-mono); font-size: 13.5px; line-height: 1.65; }
|
|
84
|
+
.cmd pre .c { color: var(--term-dim); }
|
|
85
|
+
.cmd pre .ok { color: var(--term-ok); }
|
|
86
|
+
.copy { position: absolute; top: 9px; right: 9px; font: 500 12px var(--f-body); color: var(--term-fg); background: transparent; border: 1px solid #3b4f4a; border-radius: 6px; padding: 4px 10px; cursor: pointer; }
|
|
87
|
+
.copy:hover { border-color: var(--term-ok); }
|
|
88
|
+
.copy:focus-visible, button:focus-visible, input:focus-visible + span, a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
|
89
|
+
|
|
90
|
+
.tblwrap { overflow-x: auto; margin: 12px 0 16px; border: 1px solid var(--line); border-radius: 8px; background: var(--surface); }
|
|
91
|
+
table { border-collapse: collapse; width: 100%; font-size: 14px; }
|
|
92
|
+
th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--line); vertical-align: top; }
|
|
93
|
+
th { font-weight: 700; font-size: 12.5px; color: var(--muted); letter-spacing: .03em; background: var(--code-bg); }
|
|
94
|
+
tr:last-child td { border-bottom: 0; }
|
|
95
|
+
td code { white-space: nowrap; }
|
|
96
|
+
|
|
97
|
+
.note { border-radius: 8px; padding: 12px 16px; margin: 14px 0; font-size: 14.5px; background: var(--accent-soft); }
|
|
98
|
+
.note.warn { background: var(--warn-soft); }
|
|
99
|
+
.note b.tag { font-family: var(--f-display); font-size: 12px; text-transform: uppercase; letter-spacing: .08em; color: var(--accent); margin-right: 8px; }
|
|
100
|
+
.note.warn b.tag { color: var(--warn); }
|
|
101
|
+
.note p:last-child, .note ul:last-child { margin-bottom: 0; }
|
|
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
|
+
/* steps */
|
|
116
|
+
.steps { list-style: none; margin: 14px 0; padding: 0; counter-reset: s; display: grid; gap: 0; }
|
|
117
|
+
.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; }
|
|
118
|
+
.steps > li:first-child { border-top: 0; }
|
|
119
|
+
.steps > li::before { content: counter(s); font-family: var(--f-mono); font-size: 12.5px; width: 26px; height: 26px; border-radius: 50%; border: 1px solid var(--accent); color: var(--accent); display: grid; place-items: center; margin-top: 1px; }
|
|
120
|
+
.steps .phase { font-family: var(--f-mono); font-size: 11.5px; color: var(--muted); margin-left: 6px; }
|
|
121
|
+
.steps p { margin: 2px 0 0; color: var(--muted); font-size: 14px; }
|
|
122
|
+
|
|
123
|
+
.tree { background: var(--surface); border: 1px solid var(--line); border-radius: 8px; padding: 14px 16px; overflow-x: auto; font-family: var(--f-mono); font-size: 13px; line-height: 1.7; margin: 12px 0 16px; white-space: pre; }
|
|
124
|
+
.tree .c { color: var(--muted); }
|
|
125
|
+
.tree .ig { color: var(--warn); }
|
|
126
|
+
|
|
127
|
+
.check { list-style: none; padding: 0; margin: 12px 0; display: grid; gap: 6px; }
|
|
128
|
+
.check li { display: grid; grid-template-columns: 22px minmax(0, 1fr); gap: 8px; margin: 0; }
|
|
129
|
+
.check li::before { content: "□"; color: var(--accent); font-family: var(--f-mono); }
|
|
130
|
+
|
|
131
|
+
details { border-top: 1px solid var(--line); padding: 10px 0; }
|
|
132
|
+
details:last-of-type { border-bottom: 1px solid var(--line); }
|
|
133
|
+
summary { cursor: pointer; font-weight: 500; }
|
|
134
|
+
details > div { padding-top: 8px; color: var(--ink); font-size: 14.5px; }
|
|
135
|
+
|
|
136
|
+
footer { margin-top: 56px; padding-top: 18px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
|
|
137
|
+
|
|
138
|
+
@media (max-width: 860px) {
|
|
139
|
+
.shell { grid-template-columns: minmax(0, 1fr); gap: 20px; padding-block: 28px 64px; }
|
|
140
|
+
nav.toc { position: static; }
|
|
141
|
+
nav.toc ol { display: flex; flex-wrap: wrap; gap: 6px; border-left: 0; }
|
|
142
|
+
nav.toc a { padding: 3px 10px; border: 1px solid var(--line); border-radius: 999px; margin: 0; font-size: 12.5px; }
|
|
143
|
+
nav.toc a.on { border-color: var(--accent); }
|
|
144
|
+
}
|
|
145
|
+
@media (prefers-reduced-motion: no-preference) { html { scroll-behavior: smooth; } }
|
|
146
|
+
</style>
|
|
147
|
+
</head>
|
|
148
|
+
<body>
|
|
149
|
+
|
|
150
|
+
<div class="shell">
|
|
151
|
+
<nav class="toc" aria-label="目录">
|
|
152
|
+
<div class="label">目录</div>
|
|
153
|
+
<ol>
|
|
154
|
+
<li><a href="#prep">1 准备</a></li>
|
|
155
|
+
<li><a href="#run">2 生成安装命令</a></li>
|
|
156
|
+
<li><a href="#flow">3 安装器做了什么</a></li>
|
|
157
|
+
<li><a href="#result">4 装完的目录</a></li>
|
|
158
|
+
<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>
|
|
164
|
+
</ol>
|
|
165
|
+
</nav>
|
|
166
|
+
|
|
167
|
+
<main>
|
|
168
|
+
<header class="top">
|
|
169
|
+
<div class="eyebrow">npx @rowansenne/workflow-run --with-docnexus --with-codegraph</div>
|
|
170
|
+
<h1>全量安装教程<span class="pkg">workflow-run · DocNexus 文档库 · CodeGraph 代码图谱</span></h1>
|
|
171
|
+
<p class="lede">在项目根执行一条命令,装好项目级 skills,同时接入 DocNexus 项目记忆和可选的 CodeGraph 代码图谱。本页按 0.29.0(2026-10-28)说明 9 个 skills 的安装、验证与团队接入,包括独立 nacos-config 和 dev 显式触发规则。</p>
|
|
172
|
+
<div class="facts">
|
|
173
|
+
<span class="fact">Node ≥ 22.13</span>
|
|
174
|
+
<span class="fact">npm</span>
|
|
175
|
+
<span class="fact">git</span>
|
|
176
|
+
<span class="fact">CodeGraph 约 300MB(全局一份)</span>
|
|
177
|
+
<span class="fact">Windows:管理员终端</span>
|
|
178
|
+
</div>
|
|
179
|
+
</header>
|
|
180
|
+
|
|
181
|
+
<section id="prep">
|
|
182
|
+
<h2><span class="n">01</span>准备</h2>
|
|
183
|
+
<ul class="check">
|
|
184
|
+
<li><span><strong>Node.js ≥ 22.13</strong>:DocNexus 的要求,也满足 code-graph 的 <code>impact</code> / <code>entry</code>(≥ 22.5)。版本不够时安装器会在写任何文件之前报错退出。用 <code>node -v</code> 查看。</span></li>
|
|
185
|
+
<li><span><strong>npm</strong> 可用:DocNexus 用 npm 装进项目,CodeGraph 用 npm 全局安装。</span></li>
|
|
186
|
+
<li><span><strong>全局 npm 有写权限</strong>:CodeGraph 执行 <code>npm i -g @colbymchenry/codegraph@1</code>。如果平时 <code>npm i -g</code> 需要 sudo,先自己装好 CodeGraph,安装器发现已有 <code>codegraph</code> 命令就不会再装。</span></li>
|
|
187
|
+
<li><span><strong>在项目根执行</strong>:当前目录就是项目根,也可以用 <code>--project-root</code> 指定。</span></li>
|
|
188
|
+
<li><span><strong>Windows</strong>:必须在「以管理员身份运行」的终端里执行(建目录软链接需要这个权限)。普通终端里安装器会直接停下,不做任何改动。</span></li>
|
|
189
|
+
<li><span><strong>数据库连接</strong>(可选):有 <code>.codex/database-query/config.json</code> 时会自动迁移。没有或者暂时不配就加 <code>--skip-db</code>,以后重跑补上。</span></li>
|
|
190
|
+
</ul>
|
|
191
|
+
<div class="cmd"><pre>node -v<span class="c"> # v22.13.0 或更高</span>
|
|
192
|
+
npm -v
|
|
193
|
+
codegraph --version<span class="c"> # 没装也没关系,安装器会装</span></pre><button class="copy" type="button">复制</button></div>
|
|
194
|
+
</section>
|
|
195
|
+
|
|
196
|
+
<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>
|
|
222
|
+
|
|
223
|
+
<p>直接运行不带参数的 <code>npx @rowansenne/workflow-run</code> 也行,按提示选环境、填数据库,DocNexus 必装且缺失时自动接入;CodeGraph 需要 --with-codegraph,--with-docnexus 用于强制更新 DocNexus:</p>
|
|
224
|
+
<div class="tblwrap"><table>
|
|
225
|
+
<tr><th>参数</th><th>作用</th></tr>
|
|
226
|
+
<tr><td><code>--with-docnexus</code></td><td>强制更新必装的 DocNexus;默认缺失即安装、已有则复用。运行环境在 <code>.docnexus/</code>,知识输出到 <code>workflow-run/docnexus/</code></td></tr>
|
|
227
|
+
<tr><td><code>--with-codegraph</code></td><td>没有 <code>codegraph</code> 命令就全局安装,给 claude / codex 写项目级 MCP 配置,建本项目索引 <code>.codegraph/</code></td></tr>
|
|
228
|
+
<tr><td><code>--envs</code></td><td><code>codex,claude,doubao,qwen,workbuddy</code>,<code>all</code> 是全部</td></tr>
|
|
229
|
+
<tr><td><code>--skip-db</code></td><td>不配置数据库连接(database-query 不生成 <code>config.json</code>)</td></tr>
|
|
230
|
+
<tr><td><code>--yes</code></td><td>非交互,自动使用已有的数据库配置;找不到又没加 <code>--skip-db</code> 时报错退出</td></tr>
|
|
231
|
+
</table></div>
|
|
232
|
+
</section>
|
|
233
|
+
|
|
234
|
+
<section id="flow">
|
|
235
|
+
<h2><span class="n">03</span>安装器做了什么</h2>
|
|
236
|
+
<p>按执行顺序列出。前面的步骤失败会停下;必装组件 DocNexus 或模板导入失败时,安装不算完成;CodeGraph 为可选增强。</p>
|
|
237
|
+
<ol class="steps">
|
|
238
|
+
<li><div><strong>检查 Node ≥ 22.13 和 npm</strong><span class="phase">DocNexus</span><p>不满足就报错退出,此时还没有写任何文件。</p></div></li>
|
|
239
|
+
<li><div><strong>确定环境、数据库连接</strong><p>来自 <code>--envs</code> 或交互选择;<code>--skip-db</code> 时跳过数据库。</p></div></li>
|
|
240
|
+
<li><div><strong>安装 skills 到 <code>.agents/skills/</code></strong><p>从各目录 <code>skill.json</code> 自动发现当前 9 个 skills;<code>--skills</code> 子集自动补齐 requires。默认在这里保留完整文件,并写入安装清单 <code>.workflow-run.json</code>;<code>--copy</code> 时按所选环境分别安装。</p></div></li>
|
|
241
|
+
<li><div><strong>为其他环境建软链接</strong><p><code>.claude/skills/<skill></code>、<code>.qwen/skills/</code>、<code>.codebuddy/skills/</code> 按 skill 链接到 <code>.agents/skills/</code>。加 <code>--copy</code> 时改为各装一份。</p></div></li>
|
|
242
|
+
<li><div><strong>补齐 <code>.gitignore</code></strong><p>只追加缺失的行:数据库 / wiki / Nacos 本机配置、Nacos skill 的 <code>node_modules/</code>、个人设置、<code>/workflow-run/tmp/</code>,以及本教程选择的 <code>.codegraph/</code>。DocNexus 的依赖和检索库由 <code>.docnexus/.gitignore</code> 忽略。</p></div></li>
|
|
243
|
+
<li><div><strong>安装 DocNexus</strong><span class="phase">DocNexus</span><p>在业务项目根执行 <code>npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus</code>。npm 清单、锁文件和依赖都不进宿主项目的 <code>package.json</code>。</p></div></li>
|
|
244
|
+
<li><div><strong>初始化 DocNexus 工作区</strong><span class="phase">DocNexus</span><p><code>docnexus init --output-dir workflow-run --agent none</code>:创建 <code>workflow-run/docnexus/</code>,把 DocNexus 的 skills 同步到 <code>.docnexus/skills/</code>。</p></div></li>
|
|
245
|
+
<li><div><strong>把 DocNexus 接到本项目</strong><span class="phase">DocNexus</span><p>把 DocNexus 自带 skills 链接到所选环境,说明按 Claude → <code>CLAUDE.md</code>、Qwen → <code>QWEN.md</code>、Codex / 豆包 / WorkBuddy → <code>AGENTS.md</code> 写入;有自己的标记,不碰手写内容。这些 skills 不计入本包的 9 个。</p></div></li>
|
|
246
|
+
<li><div><strong>安装 CodeGraph</strong><span class="phase">CodeGraph</span><p>找不到 <code>codegraph</code> 命令时执行 <code>npm i -g @colbymchenry/codegraph@1</code>。</p></div></li>
|
|
247
|
+
<li><div><strong>写 MCP 配置</strong><span class="phase">CodeGraph</span><p>选了 claude / codex 时执行 <code>codegraph install --target=claude,codex --location=local --yes</code>。doubao、qwen、workbuddy 不支持 MCP 配置,在这些环境里 skill 直接调用 <code>codegraph</code> CLI。</p></div></li>
|
|
248
|
+
<li><div><strong>建代码图谱索引</strong><span class="phase">CodeGraph</span><p><code>codegraph init <项目根> --yes</code> 生成 <code>.codegraph/</code>(本地 SQLite)。大项目需要几分钟。</p></div></li>
|
|
249
|
+
<li><div><strong>导入文档模板到 DocNexus</strong><span class="phase">DocNexus</span><p>包内开发 / 审查模板导入 <code>workflow-run/docnexus/library/templates/<skill>/</code>,已有的不覆盖。独立需求文档也有可导入模板;技术 / 上线方案模板不随包提供,首次按用户样例创建;运行时只从知识库取生效模板。</p></div></li>
|
|
250
|
+
</ol>
|
|
251
|
+
<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>
|
|
252
|
+
</section>
|
|
253
|
+
|
|
254
|
+
<section id="result">
|
|
255
|
+
<h2><span class="n">04</span>装完的目录</h2>
|
|
256
|
+
<p>以选了 claude 和 codex 为例,含按需创建的 Nacos 连接与依赖。<span style="color:var(--warn)">橙色</span>是被 <code>.gitignore</code> 忽略、每人本机各一份的内容;<code>.docnexus/</code> 内部依赖另按它自带的规则忽略。</p>
|
|
257
|
+
<div class="tree">项目根/
|
|
258
|
+
├── .agents/skills/ <span class="c"># skills 唯一来源 + .workflow-run.json 安装清单</span>
|
|
259
|
+
│ ├── workflow/ dev/ project-review/ code-graph/
|
|
260
|
+
│ ├── database-query/
|
|
261
|
+
│ │ └── <span class="ig">config.json</span> <span class="c"># 数据库连接(含密码)</span>
|
|
262
|
+
│ ├── nacos-config/ <span class="c"># 独立只读配置查询,无其他 skill 运行依赖</span>
|
|
263
|
+
│ │ ├── scripts/config.mjs
|
|
264
|
+
│ │ ├── <span class="ig">config.json</span> <span class="c"># 可选本机连接,用户创建;凭据引用环境变量</span>
|
|
265
|
+
│ │ └── <span class="ig">node_modules/</span> <span class="c"># 首次需要 YAML 时安装,不随包分发</span>
|
|
266
|
+
│ ├── md-to-wiki/<span class="ig">wiki-config.json</span>
|
|
267
|
+
│ ├── create-tech-md-doc/ create-release-md-doc/
|
|
268
|
+
│ └── docnexus-recall/ … <span class="c"># → .docnexus/skills/ 的链接</span>
|
|
269
|
+
├── .claude/
|
|
270
|
+
│ ├── skills/<skill> <span class="c"># → ../../.agents/skills/<skill></span>
|
|
271
|
+
│ ├── settings.json <span class="c"># CodeGraph:放行 codegraph_explore</span>
|
|
272
|
+
│ └── CLAUDE.md <span class="c"># CodeGraph 写入的说明</span>
|
|
273
|
+
├── .codex/config.toml <span class="c"># CodeGraph 的 Codex MCP 配置</span>
|
|
274
|
+
├── .mcp.json <span class="c"># CodeGraph 的 Claude MCP 配置</span>
|
|
275
|
+
├── <span class="ig">.codegraph/</span> <span class="c"># 代码图谱索引(SQLite)</span>
|
|
276
|
+
├── .docnexus/ <span class="c"># 项目根运行环境、skills、草稿与索引</span>
|
|
277
|
+
├── workflow-run/
|
|
278
|
+
│ ├── docs/requirements/ <span class="c"># 需求产物</span>
|
|
279
|
+
│ ├── docnexus/ <span class="c"># DocNexus 知识输出与模板</span>
|
|
280
|
+
│ │ ├── CONCEPTS.md concepts/
|
|
281
|
+
│ │ └── library/ records/ impacts/
|
|
282
|
+
│ └── <span class="ig">tmp/</span>
|
|
283
|
+
├── CLAUDE.md AGENTS.md <span class="c"># DocNexus 段落</span>
|
|
284
|
+
├── .ignore <span class="c"># 让代码搜索跳过需求目录</span>
|
|
285
|
+
└── .gitignore</div>
|
|
286
|
+
<p><code>.docnexus/.gitignore</code> 随业务项目提交;<code>.docnexus/project.json</code> 记录输出位置。无论 <code>workflow-run/</code> 是随代码提交还是独立文档仓库,依赖和检索库都不会被提交。</p>
|
|
287
|
+
</section>
|
|
288
|
+
|
|
289
|
+
<section id="verify">
|
|
290
|
+
<h2><span class="n">05</span>验证</h2>
|
|
291
|
+
<p>先跑自检。它会对比版本,检查手改或缺失的文件、软链接、项目画像、DocNexus 模板、<code>.gitignore</code> 凭据规则和 CodeGraph 索引。有错误时退出码是 1。</p>
|
|
292
|
+
<div class="cmd"><pre>npx @rowansenne/workflow-run doctor --offline<span class="c"> # --offline 不测数据库连接</span></pre><button class="copy" type="button">复制</button></div>
|
|
293
|
+
<p>全量安装成功时,输出里应该有这两行:</p>
|
|
294
|
+
<div class="cmd"><pre><span class="ok"> OK</span> DocNexus 运行环境 .docnexus/,知识输出 workflow-run/docnexus/,已接入 Agent
|
|
295
|
+
<span class="ok"> OK</span> CodeGraph 已接入(codegraph 1.x.x,索引在 .codegraph/)</pre></div>
|
|
296
|
+
<p>再确认索引和凭据都被忽略了:</p>
|
|
297
|
+
<div class="cmd"><pre>git check-ignore -v .codegraph .agents/skills/database-query/config.json .agents/skills/nacos-config/config.json</pre><button class="copy" type="button">复制</button></div>
|
|
298
|
+
<p>在 agent 里也能看:运行 <code>/workflow status</code>,<code>docnexus</code> 和 <code>codegraph</code> 两项都应是 <code>ok</code>。</p>
|
|
299
|
+
<p>Nacos 的本地候选用 <code>config.mjs inspect</code> 查看;只有 <code>get</code> 会访问远端。<code>/workflow status</code> 和 doctor 不测试 Nacos 连通性,doctor 只检查其本机连接的忽略规则。</p>
|
|
300
|
+
</section>
|
|
301
|
+
|
|
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>
|
|
309
|
+
</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>
|
|
320
|
+
<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>
|
|
325
|
+
</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 <仓库地址> && cd <项目>
|
|
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>
|
|
344
|
+
<p>默认情况下 <code>workflow-run/</code> 随代码提交。下面两种情况适合换成团队共用的文档仓库:不想让需求产物进代码仓库,或者一个需求横跨多个服务。换了之后 <code>workflow-run/</code> 本身就是文档仓库:</p>
|
|
345
|
+
<ul>
|
|
346
|
+
<li>代码仓库的 <code>.gitignore</code> 加上 <code>/workflow-run/</code>,不再管理它。</li>
|
|
347
|
+
<li>DocNexus 知识库也在文档仓库里,各服务共用。</li>
|
|
348
|
+
<li>目录结构不变。两种用法下产物都在 <code>workflow-run/docs/requirements/<需求名>/<项目名>/</code>,同一个需求下每个服务占一个子目录。</li>
|
|
349
|
+
</ul>
|
|
350
|
+
<div class="tree">team-docs/ <span class="c"># 文档仓库 = 每个服务的 workflow-run/</span>
|
|
351
|
+
├── docs/requirements/
|
|
352
|
+
│ └── 订单导出/
|
|
353
|
+
│ ├── order-service/ <span class="c"># 项目名 = profile.json 的 artifacts.project</span>
|
|
354
|
+
│ └── report-service/
|
|
355
|
+
├── docnexus/ <span class="c"># 共用知识库与模板</span>
|
|
356
|
+
│ ├── .gitignore <span class="c"># DocNexus 自带</span>
|
|
357
|
+
│ ├── <span class="ig">node_modules/</span> <span class="ig">store/</span> <span class="c"># 每人本机一份</span>
|
|
358
|
+
└── <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>
|
|
360
|
+
|
|
361
|
+
<h3>第一次搭建(全团队只做一次)</h3>
|
|
362
|
+
<p>先在 git 服务器上建一个空仓库,例如 <code>team-docs</code>,然后在第一个服务的项目根执行:</p>
|
|
363
|
+
<ol class="steps">
|
|
364
|
+
<li><div><strong>全量安装</strong><p>已经装过的项目跳过这一步。</p><div class="cmd"><pre>npx @rowansenne/workflow-run --envs claude,codex --skip-db --with-docnexus --with-codegraph</pre><button class="copy" type="button">复制</button></div></div></li>
|
|
365
|
+
<li><div><strong>切到文档仓库</strong><p>远端是空仓库时,<code>workflow-run/</code> 里现有的内容就是文档仓库的第一批内容。安装器同时让代码仓库忽略 <code>workflow-run/</code>,并把项目名写进 <code>workflow/profile.json</code>。不加 <code>--project</code> 时,项目名用 git 远端的仓库名。</p><div class="cmd"><pre>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></div></li>
|
|
366
|
+
<li><div><strong>提交并推送文档仓库</strong><p>依赖和检索库在业务项目根,由 <code>.docnexus/.gitignore</code> 忽略,<code>tmp/</code> 已写进文档仓库的 <code>.git/info/exclude</code>,直接提交即可。</p><div class="cmd"><pre>git -C workflow-run add -A
|
|
367
|
+
git -C workflow-run commit -m "chore: init team docs"
|
|
368
|
+
git -C workflow-run push -u origin main</pre><button class="copy" type="button">复制</button></div></div></li>
|
|
369
|
+
<li><div><strong>提交代码仓库</strong><p>提交 <code>.gitignore</code>(新增了 <code>/workflow-run/</code>)和带项目名的 <code>profile.json</code>。如果 <code>workflow-run/</code> 之前随代码提交过,先让代码仓库停止跟踪它,文件本身不受影响。</p><div class="cmd"><pre>git rm -r --cached workflow-run<span class="c"> # 之前提交过 workflow-run/ 时才需要</span>
|
|
370
|
+
git add -A && git commit -m "chore: move workflow-run to team docs repo"</pre><button class="copy" type="button">复制</button></div></div></li>
|
|
371
|
+
</ol>
|
|
372
|
+
|
|
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>
|
|
379
|
+
|
|
380
|
+
<h3>已经用了一段时间,要改用文档仓库</h3>
|
|
381
|
+
<p>做法和第一次搭建一样,不用手动迁移。旧版本随代码提交时,需求目录下没有项目名这一层,先运行 <code>upgrade</code>,它会把这些文件迁到 <code><需求名>/<项目名>/</code> 下(被 git 跟踪的用 <code>git mv</code>,保留历史):</p>
|
|
382
|
+
<div class="cmd"><pre>npx @rowansenne/workflow-run upgrade<span class="c"> # 旧结构迁到 <需求名>/<项目名>/</span>
|
|
383
|
+
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
|
+
<p>然后按「第一次搭建」的第 3、4 步提交两个仓库。如果文档仓库里已经有别的服务的内容,各服务的产物在各自的项目子目录下,不会冲突。冲突只会出在 DocNexus:两边都有知识库时,<code>docs-repo</code> 会退回原状,并列出冲突的文件。这时先按 DocNexus 自己的写入流程,把本项目沉淀的内容写进共用知识库,再把本地的 <code>workflow-run/docnexus/</code> 挪走后重跑。</p>
|
|
385
|
+
|
|
386
|
+
<h3>日常使用</h3>
|
|
387
|
+
<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 <项目名></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>
|
|
396
|
+
</table></div>
|
|
397
|
+
</section>
|
|
398
|
+
|
|
399
|
+
<section id="upgrade">
|
|
400
|
+
<h2><span class="n">09</span>升级与卸载</h2>
|
|
401
|
+
<h3>升级 workflow-run</h3>
|
|
402
|
+
<div class="cmd"><pre>npx @rowansenne/workflow-run upgrade</pre><button class="copy" type="button">复制</button></div>
|
|
403
|
+
<p>读安装清单里记录的环境,非交互升级 skills;手改过的文件先备份到 <code>workflow-run/tmp/upgrade-backup/</code>。</p>
|
|
404
|
+
<p><strong>DocNexus 要升级,必须带上 <code>--with-docnexus</code></strong>:它会用 <code>@latest</code> 重装 DocNexus 包(升到最新版)、刷新 skill 链接和说明段落,并导入新版本新增的模板(已有模板不动)。不带这个参数时复用已有 DocNexus,缺失则自动补装,并补入新增模板:</p>
|
|
405
|
+
<div class="cmd"><pre>npx @rowansenne/workflow-run upgrade --with-docnexus</pre><button class="copy" type="button">复制</button></div>
|
|
406
|
+
<p>只用 npm 单独升级 DocNexus 包(不刷新链接和段落)也可以,效果一样:</p>
|
|
407
|
+
<div class="cmd"><pre>npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus@latest</pre><button class="copy" type="button">复制</button></div>
|
|
408
|
+
<p>CodeGraph 不在 <code>upgrade</code> 范围内,单独升级:</p>
|
|
409
|
+
<div class="cmd"><pre>npm i -g @colbymchenry/codegraph@1</pre><button class="copy" type="button">复制</button></div>
|
|
410
|
+
<p>团队改过的模板和新默认模板有差异时,用 <code>seed-templates --diff</code> 只读查看,再按 DocNexus 的流程手动合并。</p>
|
|
411
|
+
|
|
412
|
+
<h3>卸载</h3>
|
|
413
|
+
<div class="cmd"><pre>npx @rowansenne/workflow-run uninstall<span class="c"> # skills 与链接;DocNexus 和 .gitignore 不动</span>
|
|
414
|
+
codegraph uninit<span class="c"> # 删除本项目索引</span>
|
|
415
|
+
codegraph uninstall<span class="c"> # 移除 agent 配置和 CLI</span></pre><button class="copy" type="button">复制</button></div>
|
|
416
|
+
<p>卸载时用户配置和手改过的文件先移到 <code>workflow-run/tmp/uninstall-backup/</code>。<code>.docnexus/</code> 运行环境和 <code>workflow-run/docnexus/</code> 知识输出保留,<code>CLAUDE.md</code> / <code>AGENTS.md</code> 里的 DocNexus 段落会撤掉。</p>
|
|
417
|
+
</section>
|
|
418
|
+
|
|
419
|
+
<section id="faq">
|
|
420
|
+
<h2><span class="n">10</span>常见问题</h2>
|
|
421
|
+
<details><summary>退出码是 1,但部分 skills 已落盘</summary><div>DocNexus 接入或必需模板导入失败时安装立即停止,不报告完成;修好输出提示的网络、npm 权限或模板问题后重跑。CodeGraph 是可选增强,接入失败会提示并保留其他已安装能力,随后可带 <code>--with-codegraph</code> 重试。</div></details>
|
|
422
|
+
<details><summary>全局安装 CodeGraph 报权限错误</summary><div>先用你平时的方式全局装好 <code>@colbymchenry/codegraph@1</code>(例如改用 nvm 管理的 Node),确认 <code>codegraph --version</code> 能运行,再重跑带 <code>--with-codegraph</code> 的命令。</div></details>
|
|
423
|
+
<details><summary>codegraph init 失败或太慢</summary><div>安装器会跳过建索引并提示。之后可以在项目根手动执行 <code>codegraph init</code>。索引建好后 agent 使用期间自动增量同步,<code>cg.mjs</code> 发现索引落后于工作区时也会先 <code>codegraph sync</code>。</div></details>
|
|
424
|
+
<details><summary>Qwen Code 不会自动查 DocNexus</summary><div>当前安装器会将 Qwen 的说明写入项目根 <code>QWEN.md</code>,并链接 DocNexus skills 到 <code>.qwen/skills/</code>。先核对这两处,再重启会话;缺失时用当前版本重跑安装命令刷新接入。</div></details>
|
|
425
|
+
<details><summary>Nacos 不出现在 workflow status,是否没有安装成功</summary><div>当前 Nacos 是独立按需查询能力,不在集中能力快照中。检查所选环境的 <code>nacos-config/SKILL.md</code>,用 inspect 定位本地配置,明确环境后用 get 验证网络与鉴权。只选 <code>--skills nacos-config</code> 时没有其他 skill 依赖,但安装器仍会接入必装 DocNexus。</div></details>
|
|
426
|
+
<details><summary>Codex 里看不到 codegraph_explore</summary><div>Codex 只在受信任的项目里加载 <code>.codex/config.toml</code>。确认已信任这个项目并重启 Codex。</div></details>
|
|
427
|
+
<details><summary>内网或离线安装 DocNexus</summary><div>用环境变量指定安装包:<code>DOCNEXUS_PKG=/path/to/rowansenne-docnexus-x.y.z.tgz npx @rowansenne/workflow-run --with-docnexus</code>。PowerShell 写成 <code>$env:DOCNEXUS_PKG="..."</code>。</div></details>
|
|
428
|
+
<details><summary>图谱里一个方法「没有调用方」,可以删吗</summary><div>不一定。静态分析看不到 Spring 多实现的选择、AOP、反射和配置驱动的路由,「没有调用方」不等于没人用。</div></details>
|
|
429
|
+
</section>
|
|
430
|
+
|
|
431
|
+
<footer>依据 0.29.0(2026-10-28)的 README、skill.json 与安装器源码更新。</footer>
|
|
432
|
+
</main>
|
|
433
|
+
</div>
|
|
434
|
+
|
|
435
|
+
<script>
|
|
436
|
+
(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
|
+
document.querySelectorAll('.copy').forEach(function (btn) {
|
|
462
|
+
btn.addEventListener('click', function () {
|
|
463
|
+
var pre = btn.parentNode.querySelector('pre');
|
|
464
|
+
var text = Array.prototype.map.call(pre.childNodes, function (n) {
|
|
465
|
+
return n.nodeType === 1 && n.classList.contains('c') ? '' : n.textContent;
|
|
466
|
+
}).join('').split('\n').map(function (l) { return l.replace(/\s+$/, ''); }).join('\n');
|
|
467
|
+
function done(msg) { btn.textContent = msg; setTimeout(function () { btn.textContent = '复制'; }, 1600); }
|
|
468
|
+
function fallback() {
|
|
469
|
+
var r = document.createRange(); r.selectNodeContents(pre);
|
|
470
|
+
var s = window.getSelection(); s.removeAllRanges(); s.addRange(r);
|
|
471
|
+
done('已选中');
|
|
472
|
+
}
|
|
473
|
+
try {
|
|
474
|
+
navigator.clipboard.writeText(text).then(function () { done('已复制'); }, fallback);
|
|
475
|
+
} catch (e) { fallback(); }
|
|
476
|
+
});
|
|
477
|
+
});
|
|
478
|
+
|
|
479
|
+
var links = document.querySelectorAll('nav.toc a');
|
|
480
|
+
var secs = Array.prototype.map.call(links, function (a) { return document.querySelector(a.getAttribute('href')); });
|
|
481
|
+
function spy() {
|
|
482
|
+
var y = window.scrollY + 120, idx = 0;
|
|
483
|
+
secs.forEach(function (s, i) { if (s && s.offsetTop <= y) idx = i; });
|
|
484
|
+
links.forEach(function (a, i) { a.classList.toggle('on', i === idx); });
|
|
485
|
+
}
|
|
486
|
+
window.addEventListener('scroll', spy, { passive: true });
|
|
487
|
+
spy();
|
|
488
|
+
})();
|
|
489
|
+
</script>
|
|
490
|
+
</body>
|
|
491
|
+
</html>
|