@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,211 @@
1
+ # 安装与升级
2
+
3
+ [返回首页](../README.md) · [工作流与命令](workflows.md) · [外部能力集成](integrations.md) · [团队共享、产物与模板](team-guide.md) · [维护、测试与发布](development.md)
4
+
5
+ ## 快速开始
6
+
7
+ 需要 **Node.js >= 22.13** 与 npm(DocNexus 为必装组件)。只用 npx 安装,在项目根执行(以当前目录为项目根;Windows 要在管理员终端里运行)。推荐全量安装:
8
+
9
+ ```
10
+ npx @rowansenne/workflow-run --with-codegraph
11
+ ```
12
+
13
+ 按提示:选择环境(编号多选,回车 = 全部)→ 确认 / 填写数据库连接 → 自动生成。安装时自动接入 DocNexus 文档库(开发约定与审查问题的沉淀和召回、团队定制的文档模板),`--with-codegraph` 接入 CodeGraph 代码图谱(改动影响到的接口、MQ、定时任务和测试);不需要 CodeGraph 就去掉 `--with-codegraph`。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
14
+
15
+ 全量安装的分步说明见图文教程 [docs/full-install.html](full-install.html)(下载后用浏览器打开)。
16
+
17
+ 整体架构、dev 主线流程、独立能力调用、数据归属与知识闭环见 [docs/architecture.html](architecture.html)(下载后用浏览器打开)。
18
+
19
+ 非交互示例(bash、zsh、PowerShell 写法一样):
20
+
21
+ ```
22
+ npx @rowansenne/workflow-run --envs all --yes --with-docnexus --with-codegraph # 用现有数据库配置,装全部环境
23
+ npx @rowansenne/workflow-run --envs codex,qwen --skip-db --with-docnexus --with-codegraph # 跳过数据库
24
+ npx @rowansenne/workflow-run --envs all --skip-db --copy --with-docnexus --with-codegraph # 不用软链接,各环境独立拷贝
25
+ npx @rowansenne/workflow-run --envs claude --skip-db # 全部 skills + 必装 DocNexus,不接 CodeGraph
26
+ npx @rowansenne/workflow-run uninstall # 按安装清单卸载
27
+ ```
28
+
29
+ ### 子命令
30
+
31
+ | 命令 | 作用 |
32
+ | --- | --- |
33
+ | `init`(默认,可省略) | 安装或重装 |
34
+ | `upgrade` | 读安装清单里记录的环境与模式,非交互升级到当前版本:保留数据库配置等用户配置,skills 文件一律更新为新版(手改过的先备份到 `workflow-run/tmp/upgrade-backup/`)。加 `--with-docnexus` 时把 DocNexus 包也升到最新版(`@latest`),刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落,并导入新增的文档模板(只新增,不改动已有模板);不加则复用已安装的 DocNexus,缺失时自动补装,并导入新增模板 |
35
+ | `doctor` | 自检:已装版本与当前包对比、手改 / 缺失的文件、软链接是否断开、项目画像、DocNexus 模板是否齐全、各数据库连接能否只读 `SELECT 1`(`--offline` 跳过)、`.gitignore` 是否忽略了凭据。有错误时退出码 1 |
36
+ | `uninstall` | 等价于 `--uninstall` |
37
+ | `report` | 本地效果报告:只读统计 `workflow-run/docs/requirements/` 下的产物(`--since YYYY-MM-DD`、`--all-branches`、`--json`),见 [工作流与命令](workflows.md) |
38
+ | `feedback` | 运行反馈汇总:dev / project-review 每次运行记录到 `workflow-run/feedback/<用户>.jsonl` 的过程数据(`--json`),见 [工作流与命令](workflows.md) |
39
+ | `view` | 项目文档视图:按需求浏览方案、交付说明、审查记录(含复审修复情况)、技术 / 上线方案,生成本地静态页面(`--out <文件>`、`--open`) |
40
+ | `docs-repo <仓库地址>` | 改用团队文档仓库:`workflow-run/` 是空的就克隆,已有内容就原地接上远端(目录结构相同,文件不用挪)、代码仓库忽略它、配置本项目的项目名(`--project`,默认 git 远端仓库名)、接上仓库里的 DocNexus;不带地址显示当前状态,见 [团队共享与产物](team-guide.md) |
41
+ | `seed-templates` | 只把默认文档模板导入 DocNexus,不重装 skills。`--update` 把导入后未改动的模板更新为新版;`--diff` 只读打印团队改过的模板与新默认模板的差异,供手动合并 |
42
+
43
+ ```
44
+ npx @rowansenne/workflow-run upgrade # 拿最新版升级
45
+ npx @rowansenne/workflow-run doctor --offline
46
+ npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
47
+ ```
48
+
49
+ ## 安装路径与启用方式
50
+
51
+
52
+ | 环境 | 生成目录 | 启用方式 |
53
+ | ----------- | ---------------------------- | ---------------------------------------- |
54
+ | codex | `.agents/skills/`(**单一来源**,完整文件) | 重启 codex 自动发现;也可 `/use project-review` 手动加载 |
55
+ | claude-code | `.claude/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | Claude Code 自动发现,无需额外配置 |
56
+ | doubao | `.agents/skills/`(与 codex 共用) | 豆包办公自动发现(新会话生效) |
57
+ | qwen | `.qwen/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | Qwen Code 自动发现;`/skills` 面板可查看与切换 |
58
+ | workbuddy | `.codebuddy/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | WorkBuddy 打开项目目录后读取(项目级优先于用户级 `~/.workbuddy/skills/`) |
59
+
60
+ **单一来源 + 软链接**:skills 只在 `.agents/skills/` 装一份完整文件,`.claude/skills`、`.qwen/skills`、`.codebuddy/skills` 下按 skill 建相对软链接(`../../.agents/skills/<skill>`),改模板、填配置都只需改一处。因此即使只选了 claude、qwen 或 workbuddy,`.agents/skills/` 也会生成。
61
+
62
+ * 按 skill 建链接而不是链接整个目录,这样 `.claude/skills/` 里还能放其他 skill(例如 DocNexus 的链接)。
63
+ * 之前用 `--copy`(或建不了链接时)装的独立拷贝,再不带 `--copy` 安装时会换成链接:拷贝里填过的用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)先并入 `.agents/skills/`,原目录移到 `workflow-run/tmp/backup/<时间>/<环境>/`;两份都填过且内容不同时不会自动合并,会保留那个目录并提示手动处理。
64
+ * Windows:安装与升级(`init` / `upgrade`)**必须在管理员终端执行**(建目录软链接需要该权限);在普通终端运行会直接停下、不做任何改动,并提示改用「以管理员身份运行」的终端。`doctor`、`seed-templates`、`uninstall` 不要求管理员。少数文件系统仍建不了软链接时,该环境自动退回独立拷贝。在 Windows 上 clone 含软链接的仓库需要 `git config core.symlinks true`。
65
+ * 不想用软链接:加 `--copy`,每个环境各装一份完整文件。
66
+
67
+ ### 在 Windows 的 WorkBuddy 中使用
68
+
69
+ 在**业务项目根目录**打开管理员 PowerShell,运行 npm 包提供的安装命令(仅 `npm install` 下载包不会生成项目技能):
70
+
71
+ ```powershell
72
+ npx @rowansenne/workflow-run@latest --envs workbuddy --copy --skip-db --yes
73
+ npx @rowansenne/workflow-run@latest doctor --offline
74
+ ```
75
+
76
+ 这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`,便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝,保留已填配置,再更新技能文件;共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时,全新安装不会生成 `.qwen/skills/`。
77
+
78
+ 安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,重新打开项目并新建会话,再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数,不是额外的独立技能。
79
+
80
+ 如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
81
+
82
+ 各环境中的 skill 内容相同;默认共用 `.agents/skills/` 的这一份文件:
83
+
84
+
85
+ ```
86
+ <env-dir>/
87
+ ├── workflow/ # 入口:路由到各 skill、能力探测、维护共用项目画像
88
+ │ ├── SKILL.md
89
+ │ ├── scripts/resolve.mjs # 模板来源 / 画像 / 能力探测的判定脚本
90
+ │ ├── lib/ # 共享模型、读取、状态与门禁,随 workflow 安装
91
+ │ └── profile.json # 项目画像:主分支、构建 / 测试命令、配置中心、发布平台等(无凭据,可提交;重跑不覆盖)
92
+ ├── project-review/ # 代码审查
93
+ │ ├── SKILL.md # 触发描述 + 审查工作流(含大改动分批、发现复核)
94
+ │ └── references/
95
+ │ ├── checklist.md # 14 维度审查清单(配置维度按 profile.config_center 判断;含幂等、DB 变更、测试、语言专项)
96
+ │ ├── report.md # 审查报告模板(触发条件、复核列、复审对比、需求对照;lint-doc 据此自检)
97
+ │ ├── diff-strategy.md # 读 diff 的策略:按规模全量 / 按风险分批,未提交改动
98
+ │ └── diff-collection-common.md # 与文档类共用的分层过滤规则
99
+ ├── code-graph/ # 代码图谱查询(基于 CodeGraph)
100
+ │ ├── SKILL.md # 触发描述 + 命令 + 结果归纳方式
101
+ │ └── scripts/cg.mjs # impact / entry / mq / jobs / tables / status
102
+ ├── database-query/ # 数据库查询
103
+ │ ├── SKILL.md # 触发描述 + 查询工作流 + 只读/安全规则
104
+ │ ├── config.json # 数据库连接(init 生成,已加入 .gitignore)
105
+ │ ├── scripts/query.mjs # 执行查询:会话只读、写语句拦截、自动 LIMIT、脱敏
106
+ │ └── references/schema.md # 表结构速查(初始为空,建议补齐后提交)
107
+ ├── nacos-config/ # 独立只读远程配置查询,无其他 skill 运行依赖
108
+ │ ├── SKILL.md
109
+ │ ├── scripts/config.mjs # inspect 本地定位 / get 远程读取、参数查询、脱敏
110
+ │ ├── package.json # YAML 解析依赖;首次需要时在本目录安装
111
+ │ └── config.json # 可选命名连接,用户自行配置,不生成、不提交
112
+ ├── md-to-wiki/ # 发布 md 到 Confluence wiki
113
+ │ ├── SKILL.md # GATE:wiki 未配置则禁止启动
114
+ │ ├── wiki-config.json # wiki 连接(init 生成,默认 enabled=false,已 gitignore)
115
+ │ └── scripts/md-to-wiki.mjs # md → Confluence Storage Format XHTML 转换 + 良构校验(Node,无依赖)
116
+ ├── create-tech-md-doc/ # 从分支 diff 生成技术方案,生效模板在 DocNexus
117
+ │ └── SKILL.md # 首次按用户样例创建模板,不附带 template.md
118
+ ├── create-release-md-doc/ # 从分支 diff 生成上线方案,生效模板在 DocNexus
119
+ │ └── SKILL.md
120
+ └── dev/ # 开发 / 修 bug:需求→调研→方案→实现→测试→自审→交付
121
+ ├── SKILL.md
122
+ └── references/plan-template.md # 导入 DocNexus 的方案模板种子;快速通道不用
123
+ ```
124
+
125
+ ## 参数
126
+
127
+
128
+ | 参数 | 说明 |
129
+ | ----------------------- | --------------------------------------------------------------------- |
130
+ | `--envs` | 环境列表,逗号分隔:`codex,claude,doubao,qwen,workbuddy`;`all` = 全部 |
131
+ | `--skip-db` | 跳过数据库连接配置(database-query 不生成 config.json) |
132
+ | `--with-docnexus` | 强制将必装的 DocNexus 更新到最新版;默认缺失即安装、已有则复用(需 Node >= 22.13 与 npm) |
133
+ | `--with-codegraph` | 可选:接入 [CodeGraph](https://github.com/colbymchenry/codegraph) 代码图谱,见 [CodeGraph 集成](integrations.md) |
134
+ | `--copy` | 不建软链接,各环境独立拷贝一份完整 skills |
135
+ | `--skills <列表>` | 只装这些 skill(逗号分隔),自动带上 `requires` 依赖;之后可以再用 `--skills` 补装,已装的保留;`upgrade` 只升级装过的。不含 database-query 时不询问数据库 |
136
+ | `--seed-templates` | 把自带的文档模板导入 DocNexus(已有的不覆盖);接入 DocNexus 后文档类 skill 只从知识库取模板。每次安装 / 升级都会自动执行 |
137
+ | `--uninstall` | 按安装清单卸载本项目装的 skills 与链接,见下方「卸载」 |
138
+ | `--offline` | `doctor` 不测试数据库连通性 |
139
+ | `--yes` | 非交互:自动使用已有数据库配置(依次查找 `.codex/database-query/config.json` 与各环境已安装的 `database-query/config.json`);都没有且未 `-SkipDb` 时报错退出 |
140
+ | `--project-root` | 项目根目录;默认当前目录 |
141
+ | `--version` | 显示版本 |
142
+ | `--help` | 帮助 |
143
+
144
+ ## 重跑与升级
145
+
146
+ 可以放心重复执行 init 来升级模板;只想按原来的环境升级时用 `npx @rowansenne/workflow-run upgrade`,不用再选一遍:
147
+
148
+ * `SKILL.md`、`references/checklist.md`、`template.md`、脚本等**模板文件会被更新**;但被你**手动改过**的模板文件不会被静默覆盖(见下方「安装清单」);
149
+ * 新版本模板里已删除的文件会被清理;你改过的不删,保留并在结尾提示;
150
+ * 用户填过的 `md-to-wiki/wiki-config.json`、`database-query/references/schema.md`、`workflow/profile.json` **保留不覆盖**;
151
+ * `database-query/config.json` 只在本次确认或填写了数据库配置时写入;`--skip-db` 时保留已有文件;
152
+ * `.gitignore` 规则无论是否配置数据库都会补齐(只追加缺失的行);
153
+ * 安装器按 skill 目录自动发现文件(`*.tpl` 去掉后缀),新增 `references/` 文件不需要改安装器。
154
+ * skill 的元数据只写在各目录的 `skill.json` 里(见[维护说明](development.md#skilljson)),安装器、`seed-templates` 和 `resolve.mjs` 都从它读取。
155
+ * 设置环境变量 `WORKFLOW_RUN_NO_SYMLINK=1` 可强制不建软链接(各环境独立拷贝);无法建链接时会先探测,旧目录原样保留、只更新模板。
156
+
157
+ ### 从 skills-init 改名过来
158
+
159
+ 包从 `@rowansenne/skills-init` 改名为 `@rowansenne/workflow-run`,项目里的目录从 `skills-init/` 改成 `workflow-run/`,安装清单从 `.skills-init.json` 改成 `.workflow-run.json`。不做自动迁移:在旧项目里运行新包时,会列出要执行的改名命令后停下,例如:
160
+
161
+ ```bash
162
+ git mv skills-init workflow-run
163
+ ```
164
+
165
+ ```bash
166
+ mv .agents/skills/.skills-init.json .agents/skills/.workflow-run.json
167
+ ```
168
+
169
+ (`skills-init/` 是独立文档仓库、没被代码仓库跟踪时用 `mv`;PowerShell 里 `mv` 同样可用。)改完再运行 `npx @rowansenne/workflow-run upgrade`:它会重建 DocNexus skill 链接、补上 `workflow-run/` 的 `.gitignore` / `.ignore` 规则,并提示删掉 `CLAUDE.md` / `AGENTS.md` 里 `skills-init:docnexus` 的旧段落和含 `skills-init/` 的旧忽略规则。
170
+
171
+ ### 安装清单
172
+
173
+ 每次安装后在 `.agents/skills/.workflow-run.json`(`--copy` 时各目标目录各一份)写入清单:安装器版本、安装时间、所选环境、安装模式,以及每个 skill 的模板文件相对路径与 sha256。用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)只记录存在与否,不记哈希,重跑和升级都不覆盖。
174
+
175
+ **skills 目录里的其他文件(SKILL.md、skill.json、references、scripts)一律以安装包为准**,重跑和升级时总是更新为新版,不询问:
176
+
177
+ | 情况 | 处理 |
178
+ | --- | --- |
179
+ | 当前内容与清单记录一致(没改过) | 直接更新 |
180
+ | 与清单记录不同(手改过) | 原文件先备份到 `workflow-run/tmp/upgrade-backup/<时间>/<相对项目根的路径>`,再更新为新版;结尾列出这些文件和备份目录 |
181
+ | 目录里没有清单,无从判断 | 和新版不同的文件同样备份后更新;结尾只用一行说明哪个目录没有清单、备份了几个文件,不当作手改过 |
182
+ | 清单里有、新版里已没有 | 没改过直接删除;改过的备份后删除 |
183
+
184
+ * 这样 `SKILL.md`、`skill.json`、脚本始终是同一个版本,不会出现「新 SKILL.md 配旧 skill.json」的混搭。
185
+ * 项目自己的定制不要改 skills 目录里的文件,放到不会被覆盖的地方:项目事实和约定写 `workflow/profile.json`(约定写 `notes`),文档模板只能在 DocNexus 里定制(skills 自带的默认模板只读),通用规则写 `CLAUDE.md` / `AGENTS.md`。
186
+ * 需要找回手改内容时到备份目录里取。
187
+
188
+ ### 卸载
189
+
190
+ ```
191
+ npx @rowansenne/workflow-run uninstall
192
+ ```
193
+
194
+ 按清单移除本项目安装的 skill 文件、`.claude/skills`、`.qwen/skills`、`.codebuddy/skills` 下指向 `.agents/skills` 的软链接,以及清单本身:
195
+
196
+ * 用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)和手改过的模板文件先移到 `workflow-run/tmp/uninstall-backup/<时间戳>/<安装目录>/<skill>/`,结尾列出;
197
+ * 不在清单里的文件、你自己的 skill 和链接都不动;skill 目录里还有你自己加的文件时保留该目录并提示;目录清空后才删除;
198
+ * `.gitignore` 里追加的规则和 DocNexus 不处理;没有清单时什么也不做。
199
+
200
+ ## 为什么这些路径
201
+
202
+
203
+ * **Codex CLI 项目级 skills** 官方约定为 `.agents/skills/`(团队提交即共享),与豆包办公
204
+
205
+ 的项目级技能目录一致,因此两者共用一份。
206
+
207
+ * **Claude Code** 项目级为 `.claude/skills/`,自动发现。
208
+
209
+ * **Qwen Code** 项目级为 `.qwen/skills/`,自动发现。
210
+
211
+ * **腾讯 WorkBuddy** 读项目工作目录下的 `.codebuddy/`(与 CodeBuddy Code 一致),项目级技能在 `.codebuddy/skills/`,同名时优先于用户级;它也读 `AGENTS.md`。
@@ -0,0 +1,160 @@
1
+ # 外部能力集成
2
+
3
+ [返回首页](../README.md) · [安装与升级](installation.md) · [工作流与命令](workflows.md) · [团队共享、产物与模板](team-guide.md) · [维护、测试与发布](development.md)
4
+
5
+ ## Nacos 配置读取(nacos-config)
6
+
7
+ 独立 skill,默认随全量安装,也可用 `npx @rowansenne/workflow-run --skills nacos-config --envs codex --yes --skip-db` 单独安装。可直接请求「读取测试环境 Nacos 的 order-test.yaml,查看 order.timeout」,开发和审查也可按需调用。
8
+
9
+ ```text
10
+ node .agents/skills/nacos-config/scripts/config.mjs inspect
11
+ 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
12
+ ```
13
+
14
+ 首次读取 YAML 如缺少依赖,运行 `npm install --prefix .agents/skills/nacos-config --ignore-scripts --no-package-lock`。支持 application / bootstrap 的 YAML、properties、环境变量及本地属性占位符;多环境不自动猜选。也可配置本机 `nacos-config/config.json` 多连接并用 `--conn test` 选择,该文件和本 skill 的依赖目录由安装器加入 gitignore,重装保留配置。密码 / token 使用环境变量,不接受命令行明文凭据。
15
+
16
+ 真实目录与 Claude / Qwen / WorkBuddy 的默认软链接入口均可运行。多个 profile 可传 `--profile test,local`,匹配任一条件文档并按文件 / 文档顺序覆盖;包含多个 `@` 的普通密码可用。Oracle Thin / OCI 连接串包含内嵌凭据时整值脱敏,详细规则见连接说明。
17
+
18
+ 按明确的 Namespace / Group / Data ID 获取单个配置,支持 Nacos 1.x / 2.x 兼容 API(默认 `1`)、2.x API(`--api-version 2`)和 3.x Client API(`--api-version 3`),输出脱敏属性和读取来源。只允许配置 GET 与登录 POST,不发布、不删除、不自动写入数据库连接;不模拟 Spring 完整的配置合并与运行时最终值。连接格式与协议说明见 [nacos-config/references/connection.md](../nacos-config/references/connection.md)。
19
+
20
+ ## DocNexus 文档库(必装)
21
+
22
+ 接入支持 `--output-dir` 的 DocNexus format 7,在**业务项目根**执行安装和初始化:
23
+
24
+ ```bash
25
+ npm install --prefix ./.docnexus --save-exact @rowansenne/docnexus
26
+ ./.docnexus/node_modules/.bin/docnexus init --output-dir workflow-run --agent none
27
+ ```
28
+
29
+ `workflow-run` 自动补齐 DocNexus 接入,并链接所选 Agent 的 skills、写入项目说明、导入文档模板。
30
+
31
+ ### 运行环境与知识输出
32
+
33
+ ```text
34
+ <业务项目>/
35
+ ├── .docnexus/ # npm 运行环境与内部状态
36
+ │ ├── package.json / package-lock.json
37
+ │ ├── project.json # format_version=7,output_dir=workflow-run
38
+ │ ├── node_modules/ # CLI 和依赖
39
+ │ ├── skills/ / schemas/
40
+ │ └── drafts/ / store/ / .runtime/
41
+ └── workflow-run/
42
+ ├── docnexus/ # 知识输出,内部不安装 npm
43
+ │ ├── CONCEPTS.md / concepts/
44
+ │ └── library/ / records/ / impacts/
45
+ ├── docs/requirements/ # 工作流产物
46
+ ├── other/ # 普通聊天生成的辅助文件,按需创建
47
+ └── tmp/
48
+ ```
49
+
50
+ 所有 DocNexus 命令均从业务项目根运行,CLI 返回的路径直接用于读取和引用,不添加或删除前缀:
51
+
52
+ ```bash
53
+ node .agents/skills/workflow/scripts/docnexus.mjs status
54
+ node .agents/skills/workflow/scripts/docnexus.mjs view
55
+ node .agents/skills/workflow/scripts/docnexus.mjs usage export > workflow-run/docnexus-usage.json
56
+ ```
57
+
58
+ `status` 返回 `workspace_path`、`library_path`、`internal_directory`。知识输出固定为 `workflow-run/docnexus/`;草稿与辅助脚本位于 `.docnexus/`。模板保存在 `workflow-run/docnexus/library/templates/<skill>/`。
59
+
60
+ | 环境 | DocNexus skill 入口 | 项目说明 |
61
+ | --- | --- | --- |
62
+ | claude | `.claude/skills/` → `.docnexus/skills/` | `CLAUDE.md` |
63
+ | codex / doubao | `.agents/skills/` → `.docnexus/skills/` | `AGENTS.md` |
64
+ | workbuddy | `.codebuddy/skills/` → `.docnexus/skills/` | `AGENTS.md` |
65
+ | qwen | `.qwen/skills/` → `.docnexus/skills/` | `QWEN.md` |
66
+
67
+ 升级 / 重装刷新入口与说明,不改手写段落。知识写入仍走 DocNexus 的授权与 capture 流程。普通 `uninstall` 移除 Agent 入口和说明,保留 `.docnexus/` 运行环境与知识输出。
68
+
69
+ `.docnexus/.gitignore` 由 DocNexus 维护,忽略运行依赖、索引、草稿和内置资源;`.docnexus/project.json`、npm 清单和锁文件应随代码提交。知识输出随 `workflow-run/` 提交;独立文档仓库模式下只在文档仓库提交知识,本项目仍保存自己的 `.docnexus/` 配置和运行环境。
70
+
71
+ ### 破坏性更新:旧布局强制清理
72
+
73
+ 本次不兼容旧 DocNexus,不迁移、不备份旧知识。`init` / `upgrade` 在安装前强制删除:
74
+
75
+ - 旧版 `workflow-run/docnexus/`(含旧 `project.json`、npm / skills / store 等内部文件的布局);
76
+ - 嵌套的 `workflow-run/.docnexus/` 及 `workflow-run/tmp/duplicate-docnexus/` 旧备份;
77
+ - 能识别的根目录旧 `docnexus/` 安装、旧 Agent 链接与不兼容的内部项目状态。
78
+
79
+ 新版知识输出不含这些旧内部文件,后续重装 / 升级会保留新版 `library/`、`records/` 等知识。工作流的需求文档、其他临时文件和普通同名业务目录保留。清理失败会停止;npm / init 失败返回非零。
80
+
81
+ 已安装项目重新接入:
82
+
83
+ ```bash
84
+ npx @rowansenne/workflow-run upgrade --with-docnexus
85
+ ```
86
+
87
+ 新项目用 `npx @rowansenne/workflow-run`,自动安装必需的 DocNexus。默认从 npm 安装最新版(`@rowansenne/docnexus@latest`),接入和升级都取最新版;离线或本地验证可设 `DOCNEXUS_PKG=/path/to/package-or-source` 指定安装来源(此时不再追加 `@latest`),必须使用支持 format 7 和 `--output-dir` 的版本。
88
+
89
+ ## CodeGraph 代码图谱与 code-graph skill(可选)
90
+
91
+ [CodeGraph](https://github.com/colbymchenry/codegraph)(MIT,100% 本地)把项目预先解析成代码知识图谱。图谱里有:
92
+ - 符号、调用边、继承 / 实现(含接口到实现的调用);
93
+ - Spring 路由;
94
+ - MyBatis XML 语句与 Mapper 接口的对应;
95
+ - `@Value` 配置 key。
96
+
97
+ 本项目的集成分两层:
98
+
99
+ - **CodeGraph 本身(外部依赖)**:解析与图谱由上游维护。全局装一份,各项目各建索引 `.codegraph/`;Claude Code / Codex 还能直接用它的 MCP 工具 `codegraph_explore` 读代码。
100
+ - **code-graph skill(自己的封装)**:`code-graph/scripts/cg.mjs` 调用 CodeGraph 的库(`CodeGraph.openSync` / `getNodesInFile` / `getCallers` / `getCallees`),面向本工作流做查询,并补上 CodeGraph 看不到的 Java / Spring 关联:
101
+
102
+ | 命令 | 作用 |
103
+ |---|---|
104
+ | `cg.mjs impact --diff <main>...<dev>` / `--base <main>` | 从 diff 找到改动的方法、配置常量、XML 语句,向上追调用方(默认 3 层),一次给出:受影响的 **HTTP 接口**、**MQ 消费者**(含 topic)、**定时任务**;受影响的代码文件;受影响和改动过的**测试**;向下调用到的 **SQL 语句与表**;改动的**配置 key**;删除的文件 |
105
+ | `cg.mjs entry <Class.method>` | 一个方法向上能到达哪些入口(接口、消费者、定时任务),以及哪些测试覆盖它 |
106
+ | `cg.mjs mq [--topic t]` | topic 的消费方(`@KafkaListener`、`@RabbitListener`、`@RocketMQMessageListener`、`@JmsListener`、`@StreamListener`)与生产方(`*Template.send/convertAndSend/syncSend…`) |
107
+ | `cg.mjs jobs` | `@Scheduled`、`@XxlJob` 定时任务入口 |
108
+ | `cg.mjs tables [--table t]` | MyBatis XML 语句(namespace.id)涉及的表 |
109
+ | `cg.mjs status` | 索引与库是否可用 |
110
+
111
+ `mq`、`jobs`、`tables` 只扫源码,没有索引也能用。`impact`、`entry` 需要 `.codegraph/` 索引和 CodeGraph 的库(Node >= 22.5);开工快照区分 script / cli / source,Skill 按共享规则选择一次,不逐步试错。
112
+
113
+ dev、project-review、技术方案、上线方案都在对应环节调用它:
114
+ - **dev**:改公共方法前看入口;验证时先跑受影响的测试;交付说明里写受影响的接口 / 表 / 配置。
115
+ - **project-review**:「影响面」按入口归纳。
116
+ - **技术方案、上线方案**:影响范围、中间件上线、回归验证参考 `impact` 的结果。
117
+
118
+ 用法约定见 `workflow/references/codegraph.md`。
119
+
120
+ ### 安装:`--with-codegraph`
121
+
122
+ 加 `--with-codegraph` 时,装完 skills 后额外执行:
123
+
124
+ 1. 找不到 `codegraph` 命令时执行 `npm i -g @colbymchenry/codegraph@1`。全局装 CLI 和库(平台包约 300MB,所以不在每个项目里各装一份);code-graph skill 按 1.x 的库接口编写。
125
+ 2. 所选环境里有 claude / codex 时,执行 `codegraph install --target=<claude,codex> --location=local --yes`,把 MCP 配置写进本项目:
126
+ - claude:`.mcp.json`、`.claude/settings.json`(自动放行 `codegraph_explore`)、`.claude/CLAUDE.md`;
127
+ - codex:`.codex/config.toml`、`AGENTS.md`;Codex 只在受信任的项目里加载项目级配置。
128
+ - doubao、qwen、workbuddy 不在 CodeGraph 支持的 agent 里,在这些环境用 code-graph skill 和 `codegraph` CLI。
129
+ 3. 执行 `codegraph init <项目根> --yes` 建索引,生成 `.codegraph/`(本地 SQLite),并把它加入 `.gitignore`。之后 agent 使用期间自动增量同步;`cg.mjs` 发现索引落后于工作区时也会先 `codegraph sync`。
130
+
131
+ * 能力探测:`resolve.mjs status` 的 `codegraph`(`ok` = 有 `.codegraph/` 且 `codegraph` 命令可用)。`/workflow status` 和 `doctor` 都会显示。
132
+ * 没有 `.codegraph/` 时,skills **不会自己建索引**,只在交付或报告里注明「未使用代码图谱」。要不要建索引由你决定。
133
+ * 本工具和 `cg.mjs` 调用 codegraph 时都带 `DO_NOT_TRACK=1`。但 CodeGraph 自身默认上报匿名使用统计(不含代码、路径、符号名),`--yes` 不会询问;需要关闭时运行 `codegraph telemetry off`。
134
+ * 静态分析的局限:Spring 多实现的选择、AOP、反射、配置驱动的路由看不到;图谱里「没有调用方」不等于没人用。
135
+ * 卸载:`codegraph uninstall` 移除 agent 配置和 CLI,`codegraph uninit` 删除本项目的索引。
136
+
137
+ ## wiki 能力说明(连接空着不启动)
138
+
139
+
140
+ * `md-to-wiki` 带 **GATE**:执行前先读 `wiki-config.json`,若文件缺失 / `enabled` 非 true /
141
+
142
+ `base_url` 为空 → **立即停止**,提示用户补配,不做任何转换与上传。
143
+
144
+ * `create-tech-md-doc` / `create-release-md-doc` 的 `--prd`**&#x20;增强**同样受 GATE 约束:
145
+
146
+ 未配置时自动回退纯 diff 流程(文档生成主流程不受影响)。
147
+
148
+ * 启用方式(三选一):
149
+
150
+ 1. 填写 `md-to-wiki/wiki-config.json`:`enabled: true` + `base_url`(如
151
+
152
+ `https://wiki.example.com`)+ `api_token`(Confluence PAT);
153
+
154
+ 2. 环境接入 Confluence MCP(如 Claude Code 的 `wiki-mcp`),SKILL.md 会优先走 MCP 通道;
155
+
156
+ 3. 同时保留 `remote_url` 字段记录远程 MCP 地址(可选)。
157
+
158
+ * 上传通道自动选择:环境有 wiki MCP 工具 → 用工具;否则用 `wiki-config.json` 的 REST 参数
159
+
160
+ 调 Confluence REST API。
@@ -0,0 +1,166 @@
1
+ # 团队共享、产物与模板
2
+
3
+ [返回首页](../README.md) · [安装与升级](installation.md) · [工作流与命令](workflows.md) · [外部能力集成](integrations.md) · [维护、测试与发布](development.md)
4
+
5
+ ## 哪些文件提交、哪些忽略
6
+
7
+ 安装 / 升级时安装器只往项目的 `.gitignore` 追加缺失的规则(已有内容不动),`doctor` 会检查凭据规则还在不在。团队成员照下面两张表即可。
8
+
9
+ **提交**(团队共享):
10
+
11
+ | 路径 | 说明 |
12
+ | --- | --- |
13
+ | `.agents/skills/` | skills 单一来源,含安装清单 `.workflow-run.json` |
14
+ | `.claude/skills/`、`.qwen/skills/`、`.codebuddy/skills/` | 指向 `.agents/skills/` 的相对软链接(Windows 上 clone 需 `git config core.symlinks true`) |
15
+ | `.agents/skills/workflow/profile.json` | 项目画像(无凭据),产物目录用的项目名也在这里 |
16
+ | `.agents/skills/database-query/references/schema.md` | 表结构速查,补齐后提交 |
17
+ | `workflow-run/docs/requirements/` | 需求产物;独立文档仓库模式下提交到文档仓库 |
18
+ | `workflow-run/other/` | 普通聊天生成的报告、方案、草稿、导出等辅助文件(按需创建,可按主题分目录);不进入需求索引、运行状态、需求统计与文档视图,按需提交 |
19
+ | `workflow-run/feedback/` | 运行反馈,每人一个文件;独立文档仓库模式下提交到文档仓库 |
20
+ | `.docnexus/project.json`、npm 清单与锁文件 | DocNexus 项目配置与运行依赖版本,随代码提交 |
21
+ | `workflow-run/docnexus/` | DocNexus 知识输出与定制的文档模板。独立文档仓库模式下提交到文档仓库 |
22
+ | `.ignore` | 让代码搜索跳过需求目录(不影响 git) |
23
+ | `.gitignore`、`CLAUDE.md` / `AGENTS.md` / `QWEN.md` | 安装器追加的忽略规则、文件落盘约定、DocNexus 说明段落 |
24
+
25
+ **忽略**(每人每机器一份,或可重新生成):
26
+
27
+ | `.gitignore` 规则 | 忽略的内容 | 何时追加 |
28
+ | --- | --- | --- |
29
+ | `**/database-query/config.json` | 数据库连接(含密码) | 总是 |
30
+ | `**/nacos-config/config.json` | 可选 Nacos 本机连接配置,密码 / token 仅引用环境变量 | 总是 |
31
+ | `**/nacos-config/node_modules/` | Nacos skill 的本机 YAML 解析依赖 | 总是 |
32
+ | `**/wiki-config.json` | wiki 地址与 token | 总是 |
33
+ | `**/workflow/profile.local.json` | 个人设置:本机系统与终端、提交提示开关 | 总是 |
34
+ | `/workflow-run/tmp/` | 临时产物:查询导出、wiki 临时 XHTML、旧版产物归档、升级 / 卸载备份、`view` 页面 | `workflow-run/` 不是独立 git 仓库时 |
35
+ | `/workflow-run/` | 整个文档仓库(它自己提交);同时在文档仓库的 `.git/info/exclude` 加 `/tmp/` | 独立文档仓库模式(`docs-repo`) |
36
+ | `.codegraph/` | CodeGraph 本地索引(SQLite) | `--with-codegraph` |
37
+
38
+ 查某个文件为什么被忽略、看当前所有被忽略的文件:
39
+
40
+ ```bash
41
+ git check-ignore -v .agents/skills/database-query/config.json
42
+ ```
43
+
44
+ ```bash
45
+ git status --short --ignored
46
+ ```
47
+
48
+ ## 凭据安全
49
+
50
+
51
+ * **数据库**:连接配置从已有 `.codex/database-query/config.json` 自动迁移,或按提示填写。
52
+
53
+ 生成后 `**/database-query/config.json` 追加到 `.gitignore`,**请勿提交**。
54
+
55
+ * **wiki**:连接配置**默认留空**(`enabled: false`)。启用时填写各环境
56
+
57
+ `md-to-wiki/wiki-config.json` 的 `base_url` / `api_token`;`**/wiki-config.json` 同样加入
58
+
59
+ `.gitignore`,**请勿提交**。
60
+
61
+ * 技能内置安全规则:database-query 只读查询优先、写操作必须用户确认、敏感字段脱敏、
62
+
63
+ 不在对话中输出密码。
64
+
65
+ * **Nacos**:优先读取用户选定的 application / bootstrap;可选本机 `nacos-config/config.json` 使用 `password_env` / `token_env` 引用凭据并由 gitignore 忽略。配置获取只读,不输出密码或 token,不缓存远程原文,也不自动改写数据库连接。生效环境与 Data ID 不明确时先确认。
66
+
67
+ ## 产物输出规范(统一落位)
68
+
69
+ 普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认写到 `workflow-run/other/`(按需创建,可按主题建子目录),不绑定需求、不登记运行状态,也不进入需求统计与文档视图。安装与 `upgrade` 会向所选环境的 `CLAUDE.md` / `AGENTS.md` / `QWEN.md` 写入这条项目级指令,无需接入 DocNexus;卸载只清理自己的指令段,保留手写内容与产物。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用原路径;用户明确指定输出路径时以用户为准。不会自动搬移已有文件。
70
+
71
+ 一个需求的文档产物放在**同一个需求目录**里,方案(开发 / 缺陷修复)、交付说明、审查报告、技术方案、上线方案一起看:
72
+
73
+ ```
74
+ workflow-run/docs/requirements/<需求名>/<项目名>/
75
+ ├── meta.json # runs 保存分支运行状态、逐步完成标记与完成时间;另含 需求名、绑定的分支、各产物(版本、日期、wiki 发布记录、DocNexus 沉淀),给以后的可视化用
76
+ ├── clarification.md # 业务场景清单(F2 / B3,多轮核对产品答复)
77
+ ├── requirement.md # 需求文档(F3 / B3 收尾:目标、范围、AC 验收与澄清决定)
78
+ ├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
79
+ ├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才写;S 快速通道不落盘)
80
+ ├── review.md # 审查报告(独立审查或 dev 完整流程自查;S 快速通道不落盘);复审也写这个文件,上一版归档到 workflow-run/tmp/old-artifacts/
81
+ ├── tech-doc.md # 技术方案
82
+ └── release-doc.md # 上线方案
83
+ ```
84
+
85
+ * **随代码提交和独立文档仓库两种用法的结构完全一样**,切换时文件不用挪。一个需求横跨多个服务时,各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`:随代码提交时不用配置,取 git 远端仓库名(没有远端用目录名),第一次落盘时自动写进去;独立文档仓库时由 `docs-repo` 配置。
86
+ * 旧版本随代码提交时没有 `<项目名>/` 这一层;`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`(被 git 跟踪的用 `git mv`,保留历史),结尾列出迁移了哪些需求,改动由你提交。目标里已有同名文件的需求不动,并提示手动处理;`doctor` 也会提示还没迁移的需求。
87
+ * **需求名由你定**: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
+ * 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
90
+
91
+ 完整 dev 的关键阶段由程序校验:M / L 方案确认绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;需要产品核对清单时,在首版清单前创建运行、等待反馈时保存状态;快速通道仍不创建运行。协议见 [execution.md](../workflow/references/execution.md)。
92
+
93
+ **独立文档仓库(可选)**:不想让产物进代码仓库、或一个需求横跨多个服务时,装好 skills 后在项目根运行一条命令:
94
+
95
+ ```bash
96
+ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <项目名>]
97
+ ```
98
+
99
+ 它会:
100
+ - `workflow-run/` 里没有内容(或只有 `tmp/`)时,把文档仓库克隆到这里(`tmp/` 先挪开再放回);
101
+ - 已有随项目提交的产物、DocNexus 时,原地 `git init` 并接上远端,文件不用挪(旧结构的产物先迁到 `<需求>/<项目名>/`)。远端是空仓库时,本地内容就是文档仓库的第一批内容;远端已有内容时检出远端,本地文件和远端同路径冲突(多半是两边都有 DocNexus 知识库)就退回原状并列出冲突的文件,不合并;代码仓库还跟踪着 `workflow-run/` 时提示 `git rm -r --cached workflow-run`;
102
+ - 然后代码仓库的 `.gitignore` 加 `/workflow-run/`,文档仓库的 `.git/info/exclude` 加 `/tmp/`;把项目名写进 `workflow/profile.json`(默认沿用已配置的,其次 git 远端仓库名;`profile.json` 随代码提交,记得提交它);文档仓库里有 DocNexus 时接上本项目的链接和段落,本机还没装它的依赖时提示运行 `upgrade --with-docnexus`。不带地址运行显示当前状态;只改项目名:`docs-repo --project <项目名>`。
103
+
104
+ `workflow-run/` 自己是 git 仓库就是这个模式:目录结构不变,各服务在同一个需求目录下各占一个子目录,DocNexus 知识库也在这个仓库里各服务共用。项目名写在 `workflow/profile.json` 的 `artifacts.project`,只配一次(`docs-repo` 会配好;没配时 skill 会问你一次)。文档里引用产物写成「文档仓库名:路径」,各服务、各人的克隆里都一样。
105
+
106
+ * 写完产物后 skill 会列出文档仓库里没提交的文件和建议的提交信息,你确认后才提交,推送另外问。不想被提示:`requirement.mjs config --commit-prompt off --local`(写在个人的 `workflow/profile.local.json`,已加入 `.gitignore`,不影响团队)。
107
+ * 其他服务的需求要先在 `workflow-run/` 里拉下来(`git -C workflow-run pull`),绑定时才看得到。
108
+ * `/workflow view` 在这个模式下显示文档仓库里所有项目的需求。
109
+
110
+ **浏览**:`/workflow view` 或 `npx @rowansenne/workflow-run view --open` 生成一个本地页面(`workflow-run/tmp/view/index.html`)。左边是需求列表,可按名称或分支搜索;右边是这个需求的各阶段、审查记录(每轮的级别数量、复核、与上次对比的修复情况)、交付记录,以及各份文档的渲染正文。页面是生成那一刻的快照,产物有更新时重新生成。
111
+
112
+ 其他产物:
113
+
114
+ | 技能 | 产物 | 位置 |
115
+ | --- | --- | --- |
116
+ | database-query | 查询结果 | 默认对话输出;导出时 `workflow-run/tmp/database-query/result-<时间戳>.csv` |
117
+ | md-to-wiki | 转换临时 XHTML | `workflow-run/tmp/md-to-wiki/_wiki_upload_<时间戳>.html`(上传后可删) |
118
+
119
+ 规则:
120
+
121
+ * 本工具的产出都在 `workflow-run/`:`docs/requirements/`(需求产物)、`docnexus/`(DocNexus 工作区,含定制的文档模板)是**持久产物**,随代码提交或在独立文档仓库里提交,团队共享。
122
+ * `workflow-run/tmp/` 是**临时产物**目录,安装时自动把 `/workflow-run/tmp/` 加入 `.gitignore`,不入库。
123
+
124
+ ## 自定义模板
125
+
126
+ 文档类 skill 的模板来源取决于项目是否接入了 DocNexus,生成的文档开头会注明「模板来源」:
127
+
128
+ * **已接入 DocNexus:只用知识库里的模板** `workflow-run/docnexus/library/templates/<skill>/<文件名>`(分类 `doc-template`)。不再使用 skill 自带的默认模板。库里缺模板时 skill 会停下来,提示你导入后再继续,不会悄悄回退到默认模板。
129
+ * **DocNexus 不可用**:修复必装组件后继续,不使用包内模板降级。
130
+ * **默认模板只读,定制只走 DocNexus**:要改模板或新建模板,都写进 DocNexus 知识库,团队共享同一份、每次变更有 timeline。不要直接改 skills 目录里的模板(升级会覆盖);`workflow-run/templates/` 下的项目模板已不再生效,`doctor` 会提示你导入知识库后删除。
131
+
132
+ | skill | 文件名 | 用途 | 默认模板 |
133
+ | --- | --- | --- | --- |
134
+ | create-tech-md-doc | `template.md` | 技术方案模板 | **不提供**,第一次用时按样例创建 |
135
+ | create-release-md-doc | `template.md` | 上线方案模板 | **不提供**,第一次用时按样例创建 |
136
+ | dev | `clarification-template.md` | F2 业务场景待确认清单(技术澄清前,产品往返核对) | 有 |
137
+ | dev | `plan-template.md` | 方案模板(开发 / 修复) | 有 |
138
+ | dev | `delivery-template.md` | 交付说明模板 | 有 |
139
+ | project-review | `checklist.md` | 审查清单 | 有 |
140
+ | project-review | `report.md` | 审查报告模板 | 有 |
141
+
142
+ **技术方案、上线方案的模板按团队自己的格式创建**:各团队发到 wiki 的文档格式不同,skills 不再自带固定格式。第一次生成时 skill 会停下来,请你给一份团队现有的同类文档(本地 Markdown,或 wiki 的 pageId / URL)作样例,用 `workflow/scripts/make-template.mjs` 抽出章节和表格结构,把正文换成填写说明,你确认后经你授权写入 DocNexus。因此这两类文档**需要先接入 DocNexus**(`--with-docnexus`),未接入时 skill 会停下来提示。之后想换格式,直接说「重新生成技术方案模板」。
143
+
144
+ **修改模板**:说「改技术方案模板,加一节回滚方案」或 `/workflow template release 去掉灰度那节`,agent 会一路走完:
145
+
146
+ 1. 把当前生效的模板复制成草稿 `workflow-run/tmp/template-draft/<skill>/<文件名>`,只改草稿;
147
+ 2. `template.mjs check` 校验格式(必填 ` *`、可选「(如有)」、占位符),列出新增 / 删除的章节、必填变化,并拿最近几份已生成的文档试跑,告诉你新模板下它们会多出哪些错误;
148
+ 3. 你确认后经你授权按 capture 流程写入 DocNexus 知识库,再确认生效;要撤销按 DocNexus 的 timeline 恢复旧版本。
149
+
150
+ 模板别名:`clarification`、`requirement`、`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板(澄清清单、需求文档、方案、交付说明、审查报告、审查清单)也走这条路,知识库里的版本取代默认版本,升级不会覆盖。未接入 DocNexus 时不能修改模板,agent 会提示你先接入。
151
+
152
+ * `doctor` 和 `/workflow status` 会列出还没创建的模板,以及要先接入 DocNexus 才能创建的模板。
153
+
154
+ **模板导入 DocNexus**:
155
+
156
+ ```
157
+ npx @rowansenne/workflow-run --envs claude --skip-db --with-docnexus # 接入时自动导入默认模板
158
+ npx @rowansenne/workflow-run seed-templates # 已接入的项目补导入缺的模板(upgrade 时也会自动导入新增的)
159
+ npx @rowansenne/workflow-run seed-templates --update # 导入后没改过的模板更新为新版
160
+ npx @rowansenne/workflow-run seed-templates --diff # 团队改过的模板:打印与新默认模板的差异,手动合并
161
+ ```
162
+
163
+ * 只导入 DocNexus 里还没有的、有默认版本的模板(技术方案、上线方案不在内),已有的不覆盖;项目已接入但缺模板时,安装结束会列出缺哪几份。
164
+ * 之后模板随知识库更新:直接编辑 `workflow-run/docnexus/library/templates/...` 后在业务项目根执行 `./.docnexus/node_modules/.bin/docnexus document sync --id <id>` 采纳;或者在生成文档后,skill 发现你做了结构性调整时会提议同步回模板(你确认后才写入)。每次变更都记录在 DocNexus 的 timeline 里,可追溯。
165
+ * 模板里的 `{{...}}` 是给 agent 的填写提示,DocNexus 原样保存;不要写成单独一行的 `{{fact:...}}`(那是 DocNexus 的事实引用语法)。
166
+ * 以前放在 `workflow-run/templates/` 下的项目模板:接入 DocNexus 后,缺模板时 skill 会把它作为 `import_from` 提议导入知识库;导入后删除这些文件。