@rowansenne/workflow-run 0.29.1 → 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 +12 -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 +11 -4
- package/workflow/lib/artifact-model.mjs +2 -2
- 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/template.mjs +3 -2
package/README.md
CHANGED
|
@@ -1,880 +1,84 @@
|
|
|
1
1
|
# workflow-run — 项目级 Agent Skills 一键初始化
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
为团队项目安装 **9 个 skills**:workflow、dev、project-review、code-graph、database-query、nacos-config、md-to-wiki、create-tech-md-doc、create-release-md-doc,覆盖开发、审查、配置查询和文档交付。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
支持 Codex CLI、Claude Code、豆包办公、Qwen Code 和腾讯 WorkBuddy。由宿主代理读取规则并执行脚本,无需常驻 Agent 服务。
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
> 安装只用 npx,在项目根执行。推荐 `npx @rowansenne/workflow-run --with-codegraph`;DocNexus 必装,缺失时自动接入。
|
|
7
|
+
## 首次安装
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
需要 **Node.js >= 22.13** 和 npm。在业务项目根执行;Windows 使用管理员终端:
|
|
11
10
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
安装分发与任务运行分开。运行时由宿主代理读取 skill 规则、调用脚本;workflow-run 本身不启动常驻 Agent 服务。
|
|
15
|
-
|
|
16
|
-
| 部分 | 代码位置 | 职责 |
|
|
17
|
-
| --- | --- | --- |
|
|
18
|
-
| 安装分发 | `bin/`、各 skill 的 `skill.json` | 自动发现 skills,展开 `requires` 依赖,安装 / 链接、升级、卸载、自检;保留用户配置 |
|
|
19
|
-
| 流程规则 | 各 skill 的 `SKILL.md.tpl`、`references/` | 安装后生成 `SKILL.md`;定义触发边界、阶段、确认点和按需读取的细节 |
|
|
20
|
-
| 命令入口 | `workflow/scripts/` | 画像、需求、运行、审查范围、产物收尾、模板、知识检索与报告等命令 |
|
|
21
|
-
| 共享核心 | `workflow/lib/` | 路径和数据模型、统一读取快照、元信息锁、版本、运行门禁、代码证据与可恢复收尾 |
|
|
22
|
-
| 能力型 skills | `code-graph/`、`database-query/`、`md-to-wiki/`、`nacos-config/` | 各自执行代码图谱查询、SQL、wiki 读写或 Nacos 只读查询,连接与凭据留在对应目录 |
|
|
23
|
-
| 数据与展示 | `workflow-run/`、`.docnexus/`、`view` / `report` | 保存需求产物、运行状态和知识;按需生成只读视图与统计 |
|
|
24
|
-
|
|
25
|
-
```mermaid
|
|
26
|
-
flowchart TD
|
|
27
|
-
Installer[安装器:bin + skill.json] --> Skills[项目级 skills:规则与 references]
|
|
28
|
-
Agent[宿主代理:用户请求] --> Skills
|
|
29
|
-
Skills --> Commands[workflow/scripts:流程命令]
|
|
30
|
-
Commands --> Core[workflow/lib:共享规则与状态]
|
|
31
|
-
Core --> Artifacts[workflow-run:文档、meta.json、反馈]
|
|
32
|
-
Skills --> Tools[能力型 skills:图谱 / 数据库 / wiki / Nacos]
|
|
33
|
-
Tools --> Systems[CodeGraph / 数据库 / Confluence / Nacos]
|
|
34
|
-
Commands --> Knowledge[DocNexus:项目知识与模板]
|
|
35
|
-
View[view / report:只读展示] --> Core
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
这张图表示职责和调用关系,每次请求只经过需要的分支。独立能力按各自入口调用;`workflow` 提供路由,`dev` 仅在用户显式选择开发工作流时启动。`nacos-config` 的 `requires` 为空,可独立读取远程配置,也可由 dev / project-review 按需调用;目前 Nacos 不纳入 `resolve.mjs status` 的集中能力探测,`inspect` 只检查本地候选,实际网络和鉴权由 `get` 验证。
|
|
39
|
-
|
|
40
|
-
共享核心随 workflow 安装,`lib` 不反向依赖 `scripts`,纯模型不做 I/O。需求 `meta.json` 保存绑定、版本索引和运行;Markdown 保存正文及发布 / 沉淀引用。只读展示不推进状态,文件存在不代表运行完成。完整流程通过方案版本、执行前代码快照、验证和审查证据校验阶段转换,产物收尾支持恢复与取消。
|
|
41
|
-
|
|
42
|
-
安装器仍统一接入必装组件 DocNexus,包括只选择 `nacos-config` 的安装;这属于安装策略,Nacos 读取脚本本身不调用 workflow 或 DocNexus。技术 / 上线方案的生效模板由 DocNexus 保存,首次按用户样例创建;包内审查、开发模板用于导入知识库,不是运行时的回退来源。
|
|
43
|
-
|
|
44
|
-
图解见 [docs/architecture.html](docs/architecture.html),共享核心、数据归属与证据门禁见 [workflow/references/architecture.md](workflow/references/architecture.md)。
|
|
45
|
-
|
|
46
|
-
**需求与方案分开**:完整开发 / 修复在理解、调研和澄清后,先于 F3 / B3 收尾生成 `requirement.md`(背景目标、范围、AC 验收标准、已确认决定),再于 F4 / B4 生成 `plan.md`(实现设计、风险、实施与验证计划)。两份文档独立版本与归档;方案记录依据的需求 hash / 版本,需求变化后旧方案与下游证据失效。S 快速通道仍不落盘,历史 plan 不会自动拆分。
|
|
47
|
-
|
|
48
|
-
升级会导入新增的 `dev/requirement-template.md`。方案模板默认种子已改为引用需求文档;已有知识库模板不会被重装覆盖,未改过的默认模板可用 `seed-templates --update` 更新,团队定制的方案模板按 `/workflow template plan` 调整为引用需求并保留团队结构。
|
|
49
|
-
|
|
50
|
-
## 快速开始
|
|
51
|
-
|
|
52
|
-
需要 **Node.js >= 22.13** 与 npm(DocNexus 为必装组件)。只用 npx 安装,在项目根执行(以当前目录为项目根;Windows 要在管理员终端里运行)。推荐全量安装:
|
|
53
|
-
|
|
54
|
-
```
|
|
11
|
+
```bash
|
|
55
12
|
npx @rowansenne/workflow-run --with-codegraph
|
|
56
13
|
```
|
|
57
14
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
全量安装的分步说明见图文教程 [docs/full-install.html](docs/full-install.html)(下载后用浏览器打开)。
|
|
61
|
-
|
|
62
|
-
整体架构、dev 主线流程、独立能力调用、数据归属与知识闭环见 [docs/architecture.html](docs/architecture.html)(下载后用浏览器打开)。
|
|
63
|
-
|
|
64
|
-
非交互示例(bash、zsh、PowerShell 写法一样):
|
|
65
|
-
|
|
66
|
-
```
|
|
67
|
-
npx @rowansenne/workflow-run --envs all --yes --with-docnexus --with-codegraph # 用现有数据库配置,装全部环境
|
|
68
|
-
npx @rowansenne/workflow-run --envs codex,qwen --skip-db --with-docnexus --with-codegraph # 跳过数据库
|
|
69
|
-
npx @rowansenne/workflow-run --envs all --skip-db --copy --with-docnexus --with-codegraph # 不用软链接,各环境独立拷贝
|
|
70
|
-
npx @rowansenne/workflow-run --envs claude --skip-db # 全部 skills + 必装 DocNexus,不接 CodeGraph
|
|
71
|
-
npx @rowansenne/workflow-run uninstall # 按安装清单卸载
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
### Nacos 配置读取(nacos-config)
|
|
75
|
-
|
|
76
|
-
独立 skill,默认随全量安装,也可用 `npx @rowansenne/workflow-run --skills nacos-config --envs codex --yes --skip-db` 单独安装。可直接请求「读取测试环境 Nacos 的 order-test.yaml,查看 order.timeout」,开发和审查也可按需调用。
|
|
77
|
-
|
|
78
|
-
```text
|
|
79
|
-
node .agents/skills/nacos-config/scripts/config.mjs inspect
|
|
80
|
-
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
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
首次读取 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 使用环境变量,不接受命令行明文凭据。
|
|
84
|
-
|
|
85
|
-
真实目录与 Claude / Qwen / WorkBuddy 的默认软链接入口均可运行。多个 profile 可传 `--profile test,local`,匹配任一条件文档并按文件 / 文档顺序覆盖;包含多个 `@` 的普通密码可用。Oracle Thin / OCI 连接串包含内嵌凭据时整值脱敏,详细规则见连接说明。
|
|
86
|
-
|
|
87
|
-
按明确的 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)。
|
|
88
|
-
|
|
89
|
-
### 子命令
|
|
90
|
-
|
|
91
|
-
| 命令 | 作用 |
|
|
92
|
-
| --- | --- |
|
|
93
|
-
| `init`(默认,可省略) | 安装或重装 |
|
|
94
|
-
| `upgrade` | 读安装清单里记录的环境与模式,非交互升级到当前版本:保留数据库配置等用户配置,skills 文件一律更新为新版(手改过的先备份到 `workflow-run/tmp/upgrade-backup/`)。加 `--with-docnexus` 时把 DocNexus 包也升到最新版(`@latest`),刷新 skill 链接与 `CLAUDE.md` / `AGENTS.md` 段落,并导入新增的文档模板(只新增,不改动已有模板);不加则复用已安装的 DocNexus,缺失时自动补装,并导入新增模板 |
|
|
95
|
-
| `doctor` | 自检:已装版本与当前包对比、手改 / 缺失的文件、软链接是否断开、项目画像、DocNexus 模板是否齐全、各数据库连接能否只读 `SELECT 1`(`--offline` 跳过)、`.gitignore` 是否忽略了凭据。有错误时退出码 1 |
|
|
96
|
-
| `uninstall` | 等价于 `--uninstall` |
|
|
97
|
-
| `report` | 本地效果报告:只读统计 `workflow-run/docs/requirements/` 下的产物(`--since YYYY-MM-DD`、`--all-branches`、`--json`),见「workflow:入口与项目画像」 |
|
|
98
|
-
| `feedback` | 运行反馈汇总:dev / project-review 每次运行记录到 `workflow-run/feedback/<用户>.jsonl` 的过程数据(`--json`),见「运行反馈」 |
|
|
99
|
-
| `view` | 项目文档视图:按需求浏览方案、交付说明、审查记录(含复审修复情况)、技术 / 上线方案,生成本地静态页面(`--out <文件>`、`--open`) |
|
|
100
|
-
| `docs-repo <仓库地址>` | 改用团队文档仓库:`workflow-run/` 是空的就克隆,已有内容就原地接上远端(目录结构相同,文件不用挪)、代码仓库忽略它、配置本项目的项目名(`--project`,默认 git 远端仓库名)、接上仓库里的 DocNexus;不带地址显示当前状态,见「产物输出规范」 |
|
|
101
|
-
| `seed-templates` | 只把默认文档模板导入 DocNexus,不重装 skills。`--update` 把导入后未改动的模板更新为新版;`--diff` 只读打印团队改过的模板与新默认模板的差异,供手动合并 |
|
|
102
|
-
|
|
103
|
-
```
|
|
104
|
-
npx @rowansenne/workflow-run upgrade # 拿最新版升级
|
|
105
|
-
npx @rowansenne/workflow-run doctor --offline
|
|
106
|
-
npx @rowansenne/workflow-run docs-repo git@git.example.com:team/team-docs.git
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
## 安装路径与启用方式
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
| 环境 | 生成目录 | 启用方式 |
|
|
114
|
-
| ----------- | ---------------------------- | ---------------------------------------- |
|
|
115
|
-
| codex | `.agents/skills/`(**单一来源**,完整文件) | 重启 codex 自动发现;也可 `/use project-review` 手动加载 |
|
|
116
|
-
| claude-code | `.claude/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | Claude Code 自动发现,无需额外配置 |
|
|
117
|
-
| doubao | `.agents/skills/`(与 codex 共用) | 豆包办公自动发现(新会话生效) |
|
|
118
|
-
| qwen | `.qwen/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | Qwen Code 自动发现;`/skills` 面板可查看与切换 |
|
|
119
|
-
| workbuddy | `.codebuddy/skills/<skill>` → 软链接到 `.agents/skills/<skill>` | WorkBuddy 打开项目目录后读取(项目级优先于用户级 `~/.workbuddy/skills/`) |
|
|
120
|
-
|
|
121
|
-
**单一来源 + 软链接**:skills 只在 `.agents/skills/` 装一份完整文件,`.claude/skills`、`.qwen/skills`、`.codebuddy/skills` 下按 skill 建相对软链接(`../../.agents/skills/<skill>`),改模板、填配置都只需改一处。因此即使只选了 claude、qwen 或 workbuddy,`.agents/skills/` 也会生成。
|
|
122
|
-
|
|
123
|
-
* 按 skill 建链接而不是链接整个目录,这样 `.claude/skills/` 里还能放其他 skill(例如 DocNexus 的链接)。
|
|
124
|
-
* 之前用 `--copy`(或建不了链接时)装的独立拷贝,再不带 `--copy` 安装时会换成链接:拷贝里填过的用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)先并入 `.agents/skills/`,原目录移到 `workflow-run/tmp/backup/<时间>/<环境>/`;两份都填过且内容不同时不会自动合并,会保留那个目录并提示手动处理。
|
|
125
|
-
* Windows:安装与升级(`init` / `upgrade`)**必须在管理员终端执行**(建目录软链接需要该权限);在普通终端运行会直接停下、不做任何改动,并提示改用「以管理员身份运行」的终端。`doctor`、`seed-templates`、`uninstall` 不要求管理员。少数文件系统仍建不了软链接时,该环境自动退回独立拷贝。在 Windows 上 clone 含软链接的仓库需要 `git config core.symlinks true`。
|
|
126
|
-
* 不想用软链接:加 `--copy`,每个环境各装一份完整文件。
|
|
127
|
-
|
|
128
|
-
### 在 Windows 的 WorkBuddy 中使用
|
|
129
|
-
|
|
130
|
-
在**业务项目根目录**打开管理员 PowerShell,运行 npm 包提供的安装命令(仅 `npm install` 下载包不会生成项目技能):
|
|
131
|
-
|
|
132
|
-
```powershell
|
|
133
|
-
npx @rowansenne/workflow-run@latest --envs workbuddy --copy --skip-db --yes
|
|
134
|
-
npx @rowansenne/workflow-run@latest doctor --offline
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
这里用 `--copy` 在 `.codebuddy/skills/<skill>/` 生成真实目录和 `SKILL.md`,便于排除目录软链接的兼容问题。已有指向 `.agents/skills/` 的本工具链接会先转成独立拷贝,保留已填配置,再更新技能文件;共享来源和 Qwen 等其他环境的链接不变。后续 `upgrade` 沿用最近一次显式安装的环境和模式。只选择 WorkBuddy 时,全新安装不会生成 `.qwen/skills/`。
|
|
138
|
-
|
|
139
|
-
安装后,将 **同一个业务项目目录**设为 WorkBuddy 任务的工作目录,重新打开项目并新建会话,再尝试 `/workflow status`、`/dev` 或 `/project-review`。`/workflow profile` 等是技能参数,不是额外的独立技能。
|
|
140
|
-
|
|
141
|
-
如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
|
|
142
|
-
|
|
143
|
-
各环境中的 skill 内容相同;默认共用 `.agents/skills/` 的这一份文件:
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
```
|
|
148
|
-
<env-dir>/
|
|
149
|
-
├── workflow/ # 入口:路由到各 skill、能力探测、维护共用项目画像
|
|
150
|
-
│ ├── SKILL.md
|
|
151
|
-
│ ├── scripts/resolve.mjs # 模板来源 / 画像 / 能力探测的判定脚本
|
|
152
|
-
│ ├── lib/ # 共享模型、读取、状态与门禁,随 workflow 安装
|
|
153
|
-
│ └── profile.json # 项目画像:主分支、构建 / 测试命令、配置中心、发布平台等(无凭据,可提交;重跑不覆盖)
|
|
154
|
-
├── project-review/ # 代码审查
|
|
155
|
-
│ ├── SKILL.md # 触发描述 + 审查工作流(含大改动分批、发现复核)
|
|
156
|
-
│ └── references/
|
|
157
|
-
│ ├── checklist.md # 14 维度审查清单(配置维度按 profile.config_center 判断;含幂等、DB 变更、测试、语言专项)
|
|
158
|
-
│ ├── report.md # 审查报告模板(触发条件、复核列、复审对比、需求对照;lint-doc 据此自检)
|
|
159
|
-
│ ├── diff-strategy.md # 读 diff 的策略:按规模全量 / 按风险分批,未提交改动
|
|
160
|
-
│ └── diff-collection-common.md # 与文档类共用的分层过滤规则
|
|
161
|
-
├── code-graph/ # 代码图谱查询(基于 CodeGraph)
|
|
162
|
-
│ ├── SKILL.md # 触发描述 + 命令 + 结果归纳方式
|
|
163
|
-
│ └── scripts/cg.mjs # impact / entry / mq / jobs / tables / status
|
|
164
|
-
├── database-query/ # 数据库查询
|
|
165
|
-
│ ├── SKILL.md # 触发描述 + 查询工作流 + 只读/安全规则
|
|
166
|
-
│ ├── config.json # 数据库连接(init 生成,已加入 .gitignore)
|
|
167
|
-
│ ├── scripts/query.mjs # 执行查询:会话只读、写语句拦截、自动 LIMIT、脱敏
|
|
168
|
-
│ └── references/schema.md # 表结构速查(初始为空,建议补齐后提交)
|
|
169
|
-
├── nacos-config/ # 独立只读远程配置查询,无其他 skill 运行依赖
|
|
170
|
-
│ ├── SKILL.md
|
|
171
|
-
│ ├── scripts/config.mjs # inspect 本地定位 / get 远程读取、参数查询、脱敏
|
|
172
|
-
│ ├── package.json # YAML 解析依赖;首次需要时在本目录安装
|
|
173
|
-
│ └── config.json # 可选命名连接,用户自行配置,不生成、不提交
|
|
174
|
-
├── md-to-wiki/ # 发布 md 到 Confluence wiki
|
|
175
|
-
│ ├── SKILL.md # GATE:wiki 未配置则禁止启动
|
|
176
|
-
│ ├── wiki-config.json # wiki 连接(init 生成,默认 enabled=false,已 gitignore)
|
|
177
|
-
│ └── scripts/md-to-wiki.mjs # md → Confluence Storage Format XHTML 转换 + 良构校验(Node,无依赖)
|
|
178
|
-
├── create-tech-md-doc/ # 从分支 diff 生成技术方案,生效模板在 DocNexus
|
|
179
|
-
│ └── SKILL.md # 首次按用户样例创建模板,不附带 template.md
|
|
180
|
-
├── create-release-md-doc/ # 从分支 diff 生成上线方案,生效模板在 DocNexus
|
|
181
|
-
│ └── SKILL.md
|
|
182
|
-
└── dev/ # 开发 / 修 bug:需求→调研→方案→实现→测试→自审→交付
|
|
183
|
-
├── SKILL.md
|
|
184
|
-
└── references/plan-template.md # 导入 DocNexus 的方案模板种子;快速通道不用
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
## workflow:入口与项目画像
|
|
188
|
-
|
|
189
|
-
```
|
|
190
|
-
/workflow # 按请求路由到对应 skill;无具体请求时输出能力地图 + 状态
|
|
191
|
-
/workflow status # 检查项目画像、wiki、DocNexus、数据库是否可用
|
|
192
|
-
/workflow profile # 从仓库推断并经你确认后填写 workflow/profile.json
|
|
193
|
-
/workflow report # 本地效果报告(也可以直接运行 npx @rowansenne/workflow-run report)
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
**效果报告**(`/workflow report` 或 `npx @rowansenne/workflow-run report [--since YYYY-MM-DD] [--all-branches] [--json]`)只读统计 `workflow-run/docs/requirements/` 下已落盘的产物,不上报、不另存记录,用来回答「用了以后有没有更好」。默认只看工作区;产物随特性分支提交、还没合并时加 `--all-branches`,用 git 只读扫描所有本地分支(同一路径以工作区为准)。统计内容:
|
|
197
|
-
|
|
198
|
-
* 审查:各级别发现条数、严重问题复核通过率、复审时上次问题的修复率;
|
|
199
|
-
* 交付:功能 / 缺陷、S / M / L、开工前经需求澄清确认的决定条数、带「未验证项」的交付;
|
|
200
|
-
* 知识:交付与审查的 DocNexus 沉淀率(只算真正问过沉淀的,「未询问」「无需沉淀」不计入分母;dev 内部审查不单独询问或重复计入交付沉淀)、正文引用了知识库文档的产物占比;
|
|
201
|
-
* 各分支链路:方案、交付说明、审查报告、技术方案、上线方案齐不齐,哪些文档还没发布到 wiki。
|
|
202
|
-
|
|
203
|
-
**完整流程状态与续接**:需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支,记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision;完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态,`/workflow resume [运行id]` 核对后继续;`/workflow view` 展示运行与“已完成”,尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在 F3/B3 收尾确定不走快速通道后开始记录,先生成独立 requirement.md,再进入 F4/B4 的实现方案,补入此前已确认的进度;后续文档/发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`,`sync` 不会清掉状态。
|
|
204
|
-
|
|
205
|
-
**运行反馈**(`npx @rowansenne/workflow-run feedback [--json]`):效果报告只看落盘的产物,看不到过程。dev 和 project-review 每跑完一次,用 `workflow/scripts/feedback.mjs add` 静默追加一行到 `workflow-run/feedback/<git 用户名>.jsonl`:模型、规模 / 深度、是否走快速通道、向用户提问几轮、用户纠正过几次理解、验收项验证了几条、跳过了哪些步骤、**哪条规则读不懂或做不到**、用户主动说的抱怨。只记过程,不记代码和业务名词;不额外问用户。每人一个文件,随 `workflow-run/` 提交,多人不冲突。独立文档仓库模式下,安装器在文档仓库的 `workflow-run/.gitattributes` 里给这些文件配 `merge=union`,同一个文件在几个分支上都有记录时合并也不冲突;随代码提交时不改代码仓库的 `.gitattributes`,合并时遇到冲突保留两边的行即可。用来定期精简 skill:
|
|
206
|
-
|
|
207
|
-
1. 团队照常用两三周;
|
|
208
|
-
2. 运行 `feedback` 汇总(或直接拿 `workflow-run/feedback/` 下的文件),按「常被跳过的步骤」「读不懂的规则」「提问太多」精简 SKILL.md,发新版本;
|
|
209
|
-
3. 各项目 `upgrade` 时清掉本项目旧版本的记录(git 历史里仍可找回),从新版本重新收集,回到第 1 步。
|
|
210
|
-
|
|
211
|
-
字段与记录规则见 `workflow/references/feedback.md`。
|
|
212
|
-
|
|
213
|
-
**PR / MR 描述**:`node <skills>/workflow/scripts/pr-desc.mjs [--branch b] [--base main] [--out 文件]` 把本分支的交付说明(做了什么、已确认的决定、改动、验证、配置 / SQL)、审查报告(结论、CRITICAL / HIGH、影响面)和相关文档路径汇总成描述;没有交付说明时退回用提交记录和改动文件列表。dev 交付后要提 PR 时会调用它;创建 PR 要你同意。
|
|
214
|
-
|
|
215
|
-
`workflow/profile.json` 是所有 skill 共用的项目事实,模板里不再写死任何公司或项目约定。缺失字段视为空,文档中对应位置写「待填写」。示例:
|
|
216
|
-
|
|
217
|
-
```json
|
|
218
|
-
{
|
|
219
|
-
"main_branch": "master",
|
|
220
|
-
"build": "mvn -q -DskipTests compile",
|
|
221
|
-
"test": "mvn -q test",
|
|
222
|
-
"test_single": "mvn -q test -Dtest={target}",
|
|
223
|
-
"lint": "",
|
|
224
|
-
"config_center": "nacos",
|
|
225
|
-
"deploy": { "platform": "内部发布平台", "regions": ["华东-生产", "华南-生产", "海外-生产"] },
|
|
226
|
-
"job_annotation": "@XxlJob",
|
|
227
|
-
"data_review": true,
|
|
228
|
-
"toolchain": {
|
|
229
|
-
"java_home": "$JAVA_HOME",
|
|
230
|
-
"maven": { "settings": "$HOME/.m2/settings.xml", "repository": "/data/maven-repo" },
|
|
231
|
-
"gradle_user_home": "",
|
|
232
|
-
"node": ""
|
|
233
|
-
},
|
|
234
|
-
"env_vars": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" },
|
|
235
|
-
"notes": ["技术方案的「上线服务」与「数据链路」为必填"]
|
|
236
|
-
}
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
| 字段 | 影响 |
|
|
240
|
-
| --- | --- |
|
|
241
|
-
| `main_branch` | dev、project-review、文档类的 diff 基线 |
|
|
242
|
-
| `build` / `test` / `test_single` / `lint` | dev 的编译与测试 |
|
|
243
|
-
| `config_center` | project-review 第 10 维度(配置中心下发的 key 不算缺失)、dev 配置清单、上线方案的上线顺序与配置回滚 |
|
|
244
|
-
| `deploy` | 技术 / 上线方案「上线服务」的服务名与环境说明 |
|
|
245
|
-
| `job_annotation` | 技术方案「定时任务变更」识别任务类 |
|
|
246
|
-
| `data_review` | 是否输出技术方案模块 7 与上线方案 2.3 的库表评审块 |
|
|
247
|
-
| `toolchain` / `env_vars` | 开发环境配置:JDK(`java_home`)、Maven(`maven.settings` / `maven.repository`)、Gradle(`gradle_user_home`)、Node(`node`)的位置,以及路径里用到的变量。路径写 `$JAVA_HOME` 这类变量或本机绝对路径,`~` 展开为用户目录;**不含凭据**。构建跑不起来时 dev 用它核对 |
|
|
15
|
+
按提示选择代理环境、配置数据库。DocNexus 文档库必装并自动接入;CodeGraph 可选,不需要时去掉 `--with-codegraph`。
|
|
248
16
|
|
|
249
|
-
|
|
17
|
+
只安装 Codex 环境、暂不配置数据库:
|
|
250
18
|
|
|
251
19
|
```bash
|
|
252
|
-
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
`/workflow profile` 时会用 `infer-profile` 自动推断草稿(构建文件对应的工具、`JAVA_HOME` / `GRADLE_USER_HOME`、`~/.m2/settings.xml` 与其 `<localRepository>`、`~/.gradle`、锁定的 Node 版本),每个值带依据,经你确认后写入。Maven 的两份 `settings.xml`(全局 `$MAVEN_HOME/conf` 与用户级 `~/.m2`)**会合并、以用户级为准**,所以取用户级那份、全局的记在依据里;`<localRepository>` 也只认有效配置,注释里的示例会被忽略。路径可以写 `$JAVA_HOME`、`${VAR}`、`%VAR%`(用 `env_vars` 或本机环境展开)或 `~`。`env --check` 对每个字段给出展开后的路径、是否存在、哪个变量没配,以及本机实际的 `JAVA_HOME` / `MAVEN_HOME` / Node 目录,方便对照。**JDK、Maven 的位置每台机器不同**:团队共用一份就写 `profile.json`,个人不同就写 `profile.local.json` 的同名字段(优先),不用改团队那份;个人那份里写 `""` 表示**不用**团队那个值(用工具默认配置),不写这个键才是沿用。这一块只放路径和普通环境变量,token、密码一律不写。
|
|
256
|
-
|
|
257
|
-
**本机系统与终端**:安装 / 升级时检测一次,写进 `workflow/profile.local.json` 的 `env`(个人设置,已在 `.gitignore` 里,团队里各人各机器不同),例如 `{ "os": "windows", "shell": "powershell" }`。Windows 上区分 `pwsh`(PowerShell 7)和 `powershell`(Windows PowerShell 5.1,没有 `&&`),其他系统取 `$SHELL`。skill 写终端命令时读 `resolve.mjs env`(`profile` / `status` 的输出里也有),不再每次对话自己探测;skill 里给出的命令本身都是 `node …` / `git …`,在哪个终端都一样。换了终端或机器,重跑一次安装器即可。
|
|
258
|
-
|
|
259
|
-
## dev:开发与修 bug
|
|
260
|
-
|
|
20
|
+
npx @rowansenne/workflow-run --envs codex --yes --skip-db
|
|
261
21
|
```
|
|
262
|
-
/dev <需求描述 | PRD pageId/url> # 功能开发
|
|
263
|
-
/dev --bug <现象 | 报错 | 日志> # 缺陷修复
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
**仅显式触发 dev**:实际调用 `/dev` / `$dev`、点选 dev skill,或明确说「按 dev 流程」「使用完整开发工作流」时才启动。正常分析、问答、修改代码、修 bug、重构、跑测试、提交 / 推送代码都直接处理,不自动做 dev 的开工检查、需求命名、绑定或文档落盘,也不主动询问是否开启 dev。讨论 dev 或引用命令示例不算启动;任务复杂、分支已有需求目录或旧运行也不算授权。
|
|
267
|
-
|
|
268
|
-
Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_invocation: false`;所有环境同时遵守 skill 入口规则与安装写入的项目说明。已由用户启动的同一 dev 任务可按当前阶段继续,无需每条消息重复命令;只要求分析或提交时仅处理该请求,不重启流程。升级 / 重装会更新规则,随后新建会话加载;其他宿主的原生调用策略取决于宿主支持,不能将配置校验等同于所有模型的行为保证。
|
|
269
|
-
|
|
270
|
-
* **功能开发**:开始前先确定工作分支,再确认需求名(给不出名字或说不清要做什么就不开始)→ 理解需求(可读 PRD、查 DocNexus 历史决策)→ 调研现有代码 → 需求澄清(借鉴 grill-me:按决策树分轮提问,每题给推荐答案;事实自己查、决定交给用户;S 规模无未定决定时跳过澄清提问)→ **规模判定(S / M / L 说明判定依据,不再询问确认)** → 按规模出方案(非快速通道一律落方案文档:S 简版、M 精简版、L 完整版;S 符合条件时先问是否走快速通道,走则不落盘)→ 小步实现并编译 → 补测试并运行 → 优先由独立子 agent 按 project-review 审查并落盘 `review.md`(没有子 agent 时在当前会话自查,报告注明审查者)→ 报告交给用户,等待选择「修复问题 / 交付」;修复则验证后重新审查、再次等待选择,选择交付后才将交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`(带分支元信息;改动、验证结果、配置清单、未执行的 SQL),已接入 DocNexus 时交付里有值得记录的知识才问要不要沉淀(同意后以 `dev-notes` 分类写入,并把库内路径记回交付说明),没有就跳过并在元信息行写「无需沉淀」。审查和上线方案会按分支自动读取这份交付说明。
|
|
271
|
-
* **S 规模快速通道**:规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有需要澄清的业务决定时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并先回 F3(缺陷 B3)补需求文档,再到 F4 / B4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
|
|
272
|
-
* **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 审查并落盘报告(无子 agent 时当前会话自查)→ 用户选择修复或交付(修复后验证与复审;交付必须写明根因)。
|
|
273
|
-
* 审查优先用独立子 agent(期间不继续改被审代码,子 agent 只审查、写报告,不直接修复);没有子 agent 时降级为当前会话自查并把「审查者」写成当前 agent,不阻塞、也不跳过审查。遗留严重问题须说明风险并由用户明确接受,不能把选择交付写成审查通过。
|
|
274
|
-
* 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
|
|
275
|
-
* DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
|
|
276
22
|
|
|
277
|
-
|
|
23
|
+
安装后重新打开代理会话,运行 `/workflow profile` 填写项目画像,再用 `/workflow status` 检查状态。明确输入 `/dev` 才进入完整开发工作流;普通分析、修改、测试请求不会自动启动 dev。
|
|
278
24
|
|
|
25
|
+
[安装选项与 Windows 说明](docs/installation.md) · [分步图文教程](docs/full-install.html) · [工作流与命令](docs/workflows.md)
|
|
279
26
|
|
|
27
|
+
## 团队共享
|
|
280
28
|
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
| `--with-docnexus` | 强制将必装的 DocNexus 更新到最新版;默认缺失即安装、已有则复用(需 Node >= 22.13 与 npm) |
|
|
286
|
-
| `--with-codegraph` | 可选:接入 [CodeGraph](https://github.com/colbymchenry/codegraph) 代码图谱,见下方「CodeGraph 代码图谱(可选)」 |
|
|
287
|
-
| `--copy` | 不建软链接,各环境独立拷贝一份完整 skills |
|
|
288
|
-
| `--skills <列表>` | 只装这些 skill(逗号分隔),自动带上 `requires` 依赖;之后可以再用 `--skills` 补装,已装的保留;`upgrade` 只升级装过的。不含 database-query 时不询问数据库 |
|
|
289
|
-
| `--seed-templates` | 把自带的文档模板导入 DocNexus(已有的不覆盖);接入 DocNexus 后文档类 skill 只从知识库取模板。每次安装 / 升级都会自动执行 |
|
|
290
|
-
| `--uninstall` | 按安装清单卸载本项目装的 skills 与链接,见下方「卸载」 |
|
|
291
|
-
| `--offline` | `doctor` 不测试数据库连通性 |
|
|
292
|
-
| `--yes` | 非交互:自动使用已有数据库配置(依次查找 `.codex/database-query/config.json` 与各环境已安装的 `database-query/config.json`);都没有且未 `-SkipDb` 时报错退出 |
|
|
293
|
-
| `--project-root` | 项目根目录;默认当前目录 |
|
|
294
|
-
| `--version` | 显示版本 |
|
|
295
|
-
| `--help` | 帮助 |
|
|
29
|
+
- 将 `.agents/skills/`、所选环境的 skills 链接、项目画像 `workflow/profile.json` 和安装器生成的项目说明提交到代码仓库。
|
|
30
|
+
- 业务场景清单、需求文档、方案、审查和交付说明统一放在 `workflow-run/docs/requirements/`;知识与团队模板放在 `workflow-run/docnexus/`。
|
|
31
|
+
- `.docnexus/` 的项目配置、npm 清单和锁文件随代码提交,运行依赖在每台机器上安装。
|
|
32
|
+
- 数据库、wiki、Nacos 本机连接配置、`profile.local.json` 和 `workflow-run/tmp/` 不提交;安装器会追加对应忽略规则。
|
|
296
33
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
接入支持 `--output-dir` 的 DocNexus format 7,在**业务项目根**执行安装和初始化:
|
|
34
|
+
团队成员克隆后,在项目根运行以下命令补齐本机依赖与入口,再检查状态:
|
|
300
35
|
|
|
301
36
|
```bash
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
`workflow-run` 自动补齐 DocNexus 接入,并链接所选 Agent 的 skills、写入项目说明、导入文档模板。
|
|
307
|
-
|
|
308
|
-
### 运行环境与知识输出
|
|
309
|
-
|
|
310
|
-
```text
|
|
311
|
-
<业务项目>/
|
|
312
|
-
├── .docnexus/ # npm 运行环境与内部状态
|
|
313
|
-
│ ├── package.json / package-lock.json
|
|
314
|
-
│ ├── project.json # format_version=7,output_dir=workflow-run
|
|
315
|
-
│ ├── node_modules/ # CLI 和依赖
|
|
316
|
-
│ ├── skills/ / schemas/
|
|
317
|
-
│ └── drafts/ / store/ / .runtime/
|
|
318
|
-
└── workflow-run/
|
|
319
|
-
├── docnexus/ # 知识输出,内部不安装 npm
|
|
320
|
-
│ ├── CONCEPTS.md / concepts/
|
|
321
|
-
│ └── library/ / records/ / impacts/
|
|
322
|
-
├── docs/requirements/ # 工作流产物
|
|
323
|
-
├── other/ # 普通聊天生成的辅助文件,按需创建
|
|
324
|
-
└── tmp/
|
|
37
|
+
npx @rowansenne/workflow-run upgrade
|
|
38
|
+
npx @rowansenne/workflow-run doctor --offline
|
|
325
39
|
```
|
|
326
40
|
|
|
327
|
-
|
|
41
|
+
跨服务需求可共用独立文档仓库:
|
|
328
42
|
|
|
329
43
|
```bash
|
|
330
|
-
|
|
331
|
-
node .agents/skills/workflow/scripts/docnexus.mjs view
|
|
332
|
-
node .agents/skills/workflow/scripts/docnexus.mjs usage export > workflow-run/docnexus-usage.json
|
|
44
|
+
npx @rowansenne/workflow-run docs-repo <团队文档仓库地址>
|
|
333
45
|
```
|
|
334
46
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
| 环境 | DocNexus skill 入口 | 项目说明 |
|
|
338
|
-
| --- | --- | --- |
|
|
339
|
-
| claude | `.claude/skills/` → `.docnexus/skills/` | `CLAUDE.md` |
|
|
340
|
-
| codex / doubao | `.agents/skills/` → `.docnexus/skills/` | `AGENTS.md` |
|
|
341
|
-
| workbuddy | `.codebuddy/skills/` → `.docnexus/skills/` | `AGENTS.md` |
|
|
342
|
-
| qwen | `.qwen/skills/` → `.docnexus/skills/` | `QWEN.md` |
|
|
343
|
-
|
|
344
|
-
升级 / 重装刷新入口与说明,不改手写段落。知识写入仍走 DocNexus 的授权与 capture 流程。普通 `uninstall` 移除 Agent 入口和说明,保留 `.docnexus/` 运行环境与知识输出。
|
|
47
|
+
[完整提交清单、文档仓库与模板定制](docs/team-guide.md)
|
|
345
48
|
|
|
346
|
-
|
|
49
|
+
## 个人配置
|
|
347
50
|
|
|
348
|
-
|
|
51
|
+
团队约定放在 `.agents/skills/workflow/profile.json`;本机工具链路径和个人偏好放在同目录的 `profile.local.json`,后者不提交。使用 `--copy` 时,路径随所选代理环境变化。
|
|
349
52
|
|
|
350
|
-
|
|
53
|
+
数据库连接由安装提示配置;wiki 默认关闭;Nacos 可从选定的 application / bootstrap 配置读取,也可使用本机命名连接。凭据不要写入团队画像。
|
|
351
54
|
|
|
352
|
-
|
|
353
|
-
- 嵌套的 `workflow-run/.docnexus/` 及 `workflow-run/tmp/duplicate-docnexus/` 旧备份;
|
|
354
|
-
- 能识别的根目录旧 `docnexus/` 安装、旧 Agent 链接与不兼容的内部项目状态。
|
|
55
|
+
[画像与工具链说明](docs/workflows.md) · [数据库、wiki 与 Nacos 凭据说明](docs/team-guide.md) · [DocNexus、CodeGraph、Nacos 与 wiki 集成](docs/integrations.md)
|
|
355
56
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
已安装项目重新接入:
|
|
57
|
+
## 升级与故障恢复
|
|
359
58
|
|
|
360
59
|
```bash
|
|
361
|
-
npx @rowansenne/workflow-run
|
|
60
|
+
npx @rowansenne/workflow-run doctor --offline # 本地自检,不连接数据库
|
|
61
|
+
npx @rowansenne/workflow-run upgrade # 更新 skills,保留用户配置
|
|
62
|
+
npx @rowansenne/workflow-run seed-templates # 补导入缺少的默认模板
|
|
63
|
+
npx @rowansenne/workflow-run uninstall # 按安装清单卸载
|
|
362
64
|
```
|
|
363
65
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
[CodeGraph](https://github.com/colbymchenry/codegraph)(MIT,100% 本地)把项目预先解析成代码知识图谱。图谱里有:
|
|
369
|
-
- 符号、调用边、继承 / 实现(含接口到实现的调用);
|
|
370
|
-
- Spring 路由;
|
|
371
|
-
- MyBatis XML 语句与 Mapper 接口的对应;
|
|
372
|
-
- `@Value` 配置 key。
|
|
373
|
-
|
|
374
|
-
本项目的集成分两层:
|
|
375
|
-
|
|
376
|
-
- **CodeGraph 本身(外部依赖)**:解析与图谱由上游维护。全局装一份,各项目各建索引 `.codegraph/`;Claude Code / Codex 还能直接用它的 MCP 工具 `codegraph_explore` 读代码。
|
|
377
|
-
- **code-graph skill(自己的封装)**:`code-graph/scripts/cg.mjs` 调用 CodeGraph 的库(`CodeGraph.openSync` / `getNodesInFile` / `getCallers` / `getCallees`),面向本工作流做查询,并补上 CodeGraph 看不到的 Java / Spring 关联:
|
|
378
|
-
|
|
379
|
-
| 命令 | 作用 |
|
|
380
|
-
|---|---|
|
|
381
|
-
| `cg.mjs impact --diff <main>...<dev>` / `--base <main>` | 从 diff 找到改动的方法、配置常量、XML 语句,向上追调用方(默认 3 层),一次给出:受影响的 **HTTP 接口**、**MQ 消费者**(含 topic)、**定时任务**;受影响的代码文件;受影响和改动过的**测试**;向下调用到的 **SQL 语句与表**;改动的**配置 key**;删除的文件 |
|
|
382
|
-
| `cg.mjs entry <Class.method>` | 一个方法向上能到达哪些入口(接口、消费者、定时任务),以及哪些测试覆盖它 |
|
|
383
|
-
| `cg.mjs mq [--topic t]` | topic 的消费方(`@KafkaListener`、`@RabbitListener`、`@RocketMQMessageListener`、`@JmsListener`、`@StreamListener`)与生产方(`*Template.send/convertAndSend/syncSend…`) |
|
|
384
|
-
| `cg.mjs jobs` | `@Scheduled`、`@XxlJob` 定时任务入口 |
|
|
385
|
-
| `cg.mjs tables [--table t]` | MyBatis XML 语句(namespace.id)涉及的表 |
|
|
386
|
-
| `cg.mjs status` | 索引与库是否可用 |
|
|
387
|
-
|
|
388
|
-
`mq`、`jobs`、`tables` 只扫源码,没有索引也能用。`impact`、`entry` 需要 `.codegraph/` 索引和 CodeGraph 的库(Node >= 22.5);开工快照区分 script / cli / source,Skill 按共享规则选择一次,不逐步试错。
|
|
389
|
-
|
|
390
|
-
dev、project-review、技术方案、上线方案都在对应环节调用它:
|
|
391
|
-
- **dev**:改公共方法前看入口;验证时先跑受影响的测试;交付说明里写受影响的接口 / 表 / 配置。
|
|
392
|
-
- **project-review**:「影响面」按入口归纳。
|
|
393
|
-
- **技术方案、上线方案**:影响范围、中间件上线、回归验证参考 `impact` 的结果。
|
|
66
|
+
- **入口缺失或链接失效**:运行 `upgrade`,重新打开代理会话后再检查。
|
|
67
|
+
- **需要更新 DocNexus**:使用 `upgrade --with-docnexus`。当前旧布局清理会删除旧知识且不备份;涉及旧版本时,先保存知识目录,再按[升级说明](docs/integrations.md)处理。
|
|
68
|
+
- **模板缺失**:默认模板可用 `seed-templates` 补齐;技术方案、上线方案模板需按团队样例创建,见[模板定制](docs/team-guide.md)。
|
|
69
|
+
- **完整流程中断**:使用 `/workflow resume` 查看下一步;有待完成的产物收尾时,按状态提示恢复或取消。
|
|
394
70
|
|
|
395
|
-
|
|
71
|
+
[重装、升级、卸载与旧包改名](docs/installation.md) · [更新记录](CHANGELOG.md)
|
|
396
72
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
加 `--with-codegraph` 时,装完 skills 后额外执行:
|
|
400
|
-
|
|
401
|
-
1. 找不到 `codegraph` 命令时执行 `npm i -g @colbymchenry/codegraph@1`。全局装 CLI 和库(平台包约 300MB,所以不在每个项目里各装一份);code-graph skill 按 1.x 的库接口编写。
|
|
402
|
-
2. 所选环境里有 claude / codex 时,执行 `codegraph install --target=<claude,codex> --location=local --yes`,把 MCP 配置写进本项目:
|
|
403
|
-
- claude:`.mcp.json`、`.claude/settings.json`(自动放行 `codegraph_explore`)、`.claude/CLAUDE.md`;
|
|
404
|
-
- codex:`.codex/config.toml`、`AGENTS.md`;Codex 只在受信任的项目里加载项目级配置。
|
|
405
|
-
- doubao、qwen、workbuddy 不在 CodeGraph 支持的 agent 里,在这些环境用 code-graph skill 和 `codegraph` CLI。
|
|
406
|
-
3. 执行 `codegraph init <项目根> --yes` 建索引,生成 `.codegraph/`(本地 SQLite),并把它加入 `.gitignore`。之后 agent 使用期间自动增量同步;`cg.mjs` 发现索引落后于工作区时也会先 `codegraph sync`。
|
|
407
|
-
|
|
408
|
-
* 能力探测:`resolve.mjs status` 的 `codegraph`(`ok` = 有 `.codegraph/` 且 `codegraph` 命令可用)。`/workflow status` 和 `doctor` 都会显示。
|
|
409
|
-
* 没有 `.codegraph/` 时,skills **不会自己建索引**,只在交付或报告里注明「未使用代码图谱」。要不要建索引由你决定。
|
|
410
|
-
* 本工具和 `cg.mjs` 调用 codegraph 时都带 `DO_NOT_TRACK=1`。但 CodeGraph 自身默认上报匿名使用统计(不含代码、路径、符号名),`--yes` 不会询问;需要关闭时运行 `codegraph telemetry off`。
|
|
411
|
-
* 静态分析的局限:Spring 多实现的选择、AOP、反射、配置驱动的路由看不到;图谱里「没有调用方」不等于没人用。
|
|
412
|
-
* 卸载:`codegraph uninstall` 移除 agent 配置和 CLI,`codegraph uninit` 删除本项目的索引。
|
|
413
|
-
|
|
414
|
-
## 重跑与升级
|
|
415
|
-
|
|
416
|
-
可以放心重复执行 init 来升级模板;只想按原来的环境升级时用 `npx @rowansenne/workflow-run upgrade`,不用再选一遍:
|
|
417
|
-
|
|
418
|
-
* `SKILL.md`、`references/checklist.md`、`template.md`、脚本等**模板文件会被更新**;但被你**手动改过**的模板文件不会被静默覆盖(见下方「安装清单」);
|
|
419
|
-
* 新版本模板里已删除的文件会被清理;你改过的不删,保留并在结尾提示;
|
|
420
|
-
* 用户填过的 `md-to-wiki/wiki-config.json`、`database-query/references/schema.md`、`workflow/profile.json` **保留不覆盖**;
|
|
421
|
-
* `database-query/config.json` 只在本次确认或填写了数据库配置时写入;`--skip-db` 时保留已有文件;
|
|
422
|
-
* `.gitignore` 规则无论是否配置数据库都会补齐(只追加缺失的行);
|
|
423
|
-
* 安装器按 skill 目录自动发现文件(`*.tpl` 去掉后缀),新增 `references/` 文件不需要改安装器。
|
|
424
|
-
* skill 的元数据只写在各目录的 `skill.json` 里(见下方「skill.json」),安装器、`seed-templates` 和 `resolve.mjs` 都从它读取。
|
|
425
|
-
* 设置环境变量 `WORKFLOW_RUN_NO_SYMLINK=1` 可强制不建软链接(各环境独立拷贝);无法建链接时会先探测,旧目录原样保留、只更新模板。
|
|
426
|
-
|
|
427
|
-
### 从 skills-init 改名过来
|
|
428
|
-
|
|
429
|
-
包从 `@rowansenne/skills-init` 改名为 `@rowansenne/workflow-run`,项目里的目录从 `skills-init/` 改成 `workflow-run/`,安装清单从 `.skills-init.json` 改成 `.workflow-run.json`。不做自动迁移:在旧项目里运行新包时,会列出要执行的改名命令后停下,例如:
|
|
430
|
-
|
|
431
|
-
```bash
|
|
432
|
-
git mv skills-init workflow-run
|
|
433
|
-
```
|
|
434
|
-
|
|
435
|
-
```bash
|
|
436
|
-
mv .agents/skills/.skills-init.json .agents/skills/.workflow-run.json
|
|
437
|
-
```
|
|
438
|
-
|
|
439
|
-
(`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/` 的旧忽略规则。
|
|
440
|
-
|
|
441
|
-
### 安装清单
|
|
442
|
-
|
|
443
|
-
每次安装后在 `.agents/skills/.workflow-run.json`(`--copy` 时各目标目录各一份)写入清单:安装器版本、安装时间、所选环境、安装模式,以及每个 skill 的模板文件相对路径与 sha256。用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)只记录存在与否,不记哈希,重跑和升级都不覆盖。
|
|
444
|
-
|
|
445
|
-
**skills 目录里的其他文件(SKILL.md、skill.json、references、scripts)一律以安装包为准**,重跑和升级时总是更新为新版,不询问:
|
|
446
|
-
|
|
447
|
-
| 情况 | 处理 |
|
|
448
|
-
| --- | --- |
|
|
449
|
-
| 当前内容与清单记录一致(没改过) | 直接更新 |
|
|
450
|
-
| 与清单记录不同(手改过) | 原文件先备份到 `workflow-run/tmp/upgrade-backup/<时间>/<相对项目根的路径>`,再更新为新版;结尾列出这些文件和备份目录 |
|
|
451
|
-
| 目录里没有清单,无从判断 | 和新版不同的文件同样备份后更新;结尾只用一行说明哪个目录没有清单、备份了几个文件,不当作手改过 |
|
|
452
|
-
| 清单里有、新版里已没有 | 没改过直接删除;改过的备份后删除 |
|
|
453
|
-
|
|
454
|
-
* 这样 `SKILL.md`、`skill.json`、脚本始终是同一个版本,不会出现「新 SKILL.md 配旧 skill.json」的混搭。
|
|
455
|
-
* 项目自己的定制不要改 skills 目录里的文件,放到不会被覆盖的地方:项目事实和约定写 `workflow/profile.json`(约定写 `notes`),文档模板只能在 DocNexus 里定制(skills 自带的默认模板只读),通用规则写 `CLAUDE.md` / `AGENTS.md`。
|
|
456
|
-
* 需要找回手改内容时到备份目录里取。
|
|
457
|
-
|
|
458
|
-
### 卸载
|
|
459
|
-
|
|
460
|
-
```
|
|
461
|
-
npx @rowansenne/workflow-run uninstall
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
按清单移除本项目安装的 skill 文件、`.claude/skills`、`.qwen/skills`、`.codebuddy/skills` 下指向 `.agents/skills` 的软链接,以及清单本身:
|
|
465
|
-
|
|
466
|
-
* 用户配置(`config.json`、`schema.md`、`wiki-config.json`、`profile.json`)和手改过的模板文件先移到 `workflow-run/tmp/uninstall-backup/<时间戳>/<安装目录>/<skill>/`,结尾列出;
|
|
467
|
-
* 不在清单里的文件、你自己的 skill 和链接都不动;skill 目录里还有你自己加的文件时保留该目录并提示;目录清空后才删除;
|
|
468
|
-
* `.gitignore` 里追加的规则和 DocNexus 不处理;没有清单时什么也不做。
|
|
469
|
-
|
|
470
|
-
### skill.json
|
|
471
|
-
|
|
472
|
-
每个 skill 目录下有一份 `skill.json`,是这个 skill 元数据的唯一来源:
|
|
473
|
-
|
|
474
|
-
```json
|
|
475
|
-
{
|
|
476
|
-
"name": "create-tech-md-doc",
|
|
477
|
-
"order": 6,
|
|
478
|
-
"userFiles": {},
|
|
479
|
-
"requires": ["workflow"],
|
|
480
|
-
"optional": ["md-to-wiki", "create-release-md-doc"],
|
|
481
|
-
"shared": ["diff-collection-common.md", "prd-fetch.md"],
|
|
482
|
-
"templates": [{ "id": "template.md", "src": "template.md", "title": "技术方案模板", "summary": "...", "lint": { "requiredMeta": ["模板来源"] } }],
|
|
483
|
-
"docnexus": { "category": "tech-design", "reason": "create-tech-md-doc skill 从技术方案中沉淀的决策、约定与风险", "readFrom": ["create-tech-md-doc", "dev"] }
|
|
484
|
-
}
|
|
485
|
-
```
|
|
73
|
+
## 专题文档
|
|
486
74
|
|
|
487
|
-
|
|
|
75
|
+
| 文档 | 内容 |
|
|
488
76
|
| --- | --- |
|
|
489
|
-
|
|
|
490
|
-
|
|
|
491
|
-
|
|
|
492
|
-
|
|
|
493
|
-
|
|
|
494
|
-
|
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
当前分类与参考关系:
|
|
498
|
-
|
|
499
|
-
| skill | 写入分类 | 开工前参考(readFrom) |
|
|
500
|
-
| --- | --- | --- |
|
|
501
|
-
| `dev` | `dev-notes` | dev、create-tech-md-doc、project-review |
|
|
502
|
-
| `project-review` | `code-review` | project-review、dev |
|
|
503
|
-
| `create-tech-md-doc` | `tech-design` | create-tech-md-doc、dev |
|
|
504
|
-
| `create-release-md-doc` | `release-plan` | create-release-md-doc、create-tech-md-doc |
|
|
505
|
-
|
|
506
|
-
导入的模板固定为 `doc-template`;`database-query`、`md-to-wiki` 不读写知识库。这样形成闭环:审查发现的反复问题沉淀为 `code-review`,下次 dev 开工前会被列出来。测试会检查:SKILL.md 里有 DocNexus 写入步骤的 skill 必须声明分类并通过 `resolve.mjs category` 取用;`readFrom` 只能引用声明了分类的 skill,且 SKILL.md 里有对应的 `knowledge.mjs` 调用。
|
|
507
|
-
|
|
508
|
-
`tests/test-skills-meta.mjs` 会检查:skill 的文件里出现了别的 skill 的路径(如 `md-to-wiki/scripts/…`、`workflow/scripts/…`),就必须在 `requires` 或 `optional` 里声明;`requires` 声明了就必须真的用到,而且不能成环。
|
|
509
|
-
|
|
510
|
-
当前依赖关系:`workflow` Skill 负责入口编排,其 `lib/` 提供共享核心(项目配置、需求、运行、文档与产物模型),`scripts/` 保留对外命令路径;`dev`、`project-review`、两个文档 skill 依赖它;`dev` 还依赖 `project-review`(自审必做,要读它的审查清单);`database-query`、`md-to-wiki` 也自动带上 workflow,以复用统一开工检查;wiki 凭据只由 `md-to-wiki` 的脚本读取,其他 skill 拉 PRD 统一调用 `upload.mjs get`。
|
|
511
|
-
|
|
512
|
-
dev 与 project-review 的 SKILL.md 保留门禁、步骤路由、必要命令和结果去向;进入阶段前才读取对应 reference 的小节。dev 的开工、调研方案、实现验证、审查交付和缺陷修复分开加载;审查的方法、复核、报告与后续也分开加载。完整流程的步骤编号、用户选择、运行状态与正式产物规则沿用原协议,必守规则不藏在脚本注释中。
|
|
513
|
-
|
|
514
|
-
状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照,正文与元信息采集一次,使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`;正文、文档头和发布记录来自 Markdown,产物索引由显式 `sync` 重建。`list` 只读,`sync` 不再从文档头隐式增加绑定分支,绑定使用 `bind`。跨项目视图仍展示全部服务,分支查询和效果报告默认当前项目;`--all-branches` 保持同路径工作区优先,Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告,可读的正文仍展示,读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](workflow/references/architecture.md)。
|
|
515
|
-
|
|
516
|
-
新增一个 skill 就是新建目录、写 `SKILL.md.tpl` 和 `skill.json`,再加进 `package.json` 的 `files`。`tests/test-skills-meta.mjs` 会检查它们是否一致。
|
|
517
|
-
|
|
518
|
-
## 脚本化的规则
|
|
519
|
-
|
|
520
|
-
能写成确定规则的判断都放在脚本里,SKILL.md 只说明什么时候调用,不再让 agent 按文字描述自己判断:
|
|
521
|
-
|
|
522
|
-
| 脚本(安装后在 `<skills>/` 下) | 作用 |
|
|
523
|
-
| --- | --- |
|
|
524
|
-
| `workflow/scripts/resolve.mjs template <skill> <文件名>` | 只从 DocNexus 知识库解析模板;缺失时给出导入或创建指引,不回退到包内模板 |
|
|
525
|
-
| `workflow/scripts/resolve.mjs profile` | 读项目画像,列出空字段 |
|
|
526
|
-
| `workflow/scripts/resolve.mjs env` | 本机系统与终端(安装时记录在 `profile.local.json`),写终端命令按它来 |
|
|
527
|
-
| `workflow/scripts/resolve.mjs env --check` | 核对画像里的开发环境配置(`toolchain`)在本机是否存在:每个字段给出 `resolved`(展开后)、`exists`、`unset_vars`,以及 `current`(本机实际的 `JAVA_HOME` / `MAVEN_HOME` / Node 目录)便于对照 |
|
|
528
|
-
| `workflow/scripts/docnexus.mjs <参数>` / `--node <脚本> <参数>` | 在业务项目根运行 `.docnexus/` 中的 CLI 或它的 node 脚本,知识输出到 `workflow-run/docnexus/`;Windows 上直接用 node 跑 CLI 入口,不经过 `.cmd` |
|
|
529
|
-
| `workflow/scripts/knowledge.mjs <skill> [--match 词] [--limit n] [--query 问题]` | 按 `readFrom` 的分类列出 DocNexus 文档(标题、摘要、路径,不含正文);`--query` 再在每个分类内 `recall --category`,直接使用新版按分类检索能力。必装组件不可用时退出码 2,查询失败返回非 0,不当作无匹配 |
|
|
530
|
-
| `workflow/scripts/resolve.mjs category <skill>` | 该 skill 写入 DocNexus 时的显式分类(画像 `docnexus_categories` 优先,其次 skill.json),输出 `seal_args` 与 `metadata`;未声明时退出码 1 |
|
|
531
|
-
| `workflow/lib/capabilities.mjs` | 集中探测必装 DocNexus 与可选增强;供 resolve status 输出本轮能力快照 |
|
|
532
|
-
| `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测(不输出任何凭据) |
|
|
533
|
-
| `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿,每个字段附依据;不写文件 |
|
|
534
|
-
| `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts]` | 对照当前生效的模板检查生成的文档:必填章节、残留 `{{...}}` 占位符、元信息行为错误;缺普通章节、顺序不一致为警告;列出待填写位置。`--facts` 再核对正文里的类名、文件、接口、表名:在对比分支的 diff 和代码里都找不到的记为警告(防编造) |
|
|
535
|
-
| `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、给出本次落盘路径(不覆盖,带上一版的 wiki 记录)、重建 `meta.json`、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示),`pending` 看文档仓库里还没提交的产物 |
|
|
536
|
-
| `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图(`/workflow view`、`npx @rowansenne/workflow-run view`):读需求目录里的产物,生成单个 HTML,按需求列出各阶段、审查记录(各级别数量、复核、与上次对比)、交付记录、沉淀到的知识文档,正文直接渲染;顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物;数据内嵌,只读、不联网,默认写到 `workflow-run/tmp/view/index.html` |
|
|
537
|
-
| `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录:恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
|
|
538
|
-
| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录,给出下一步建议;分支取自文档元信息行,不另存记录。上线方案没传 `--tech` 时据此自动引用同分支的技术方案;project-review 据此对照本分支方案、识别复审 |
|
|
539
|
-
| `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告(`/workflow report`、`npx @rowansenne/workflow-run report`):审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
|
|
540
|
-
| `workflow/scripts/feedback.mjs add … / summary [--json]` | 运行反馈:dev / project-review 交付后追加一行过程记录到 `workflow-run/feedback/<用户>.jsonl`;`summary` 按 skill 汇总,跳过的步骤和不清楚的规则按 SKILL.md 章节归类(`npx @rowansenne/workflow-run feedback`);`init` / `upgrade` 装了新版本时清掉本项目旧版本的记录 |
|
|
541
|
-
| `workflow/scripts/review-scope.mjs [--diff b...h \| --base b] [--exclude a,b]` / `rules <文件…>` | 审查范围:由脚本决定审哪些文件、跳过哪些(删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具产物,各带原因)、每个文件的风险级别和分批,以及按文件类型和改动内容该看审查清单的哪几节;`--base` 含未提交和未跟踪的新文件。`rules` 打印这些小节的原文和画像 `review.rules` 里匹配的项目规则。project-review 第 1、3、4 步与 dev 自审使用 |
|
|
542
|
-
| `workflow/scripts/locate.mjs <发现.json> [--diff b...h \| --base b]` | 给审查发现定位行号:按每条发现引用的原代码片段在文件里查找(精确 → 忽略空白 → 单行部分匹配),多处时优先本次改动的行,输出起止行、是否落在本次改动上;找不到的标出来要求重读代码。project-review 第 6 步复核使用 |
|
|
543
|
-
| `workflow/scripts/tables.mjs [--diff b...h \| --base b \| --files a,b]` | 找出改动涉及哪些表:实体注解(`@TableName` / `@Table`,没写表名时按类名推断)、Mapper XML 与代码里的 SQL、DDL 脚本;标出 DDL、是否在 `schema.md` 里,并给出拉表结构的命令。dev 调研 / 自检与 project-review 审 SQL / DDL 时使用 |
|
|
544
|
-
| `workflow/scripts/template.mjs list / draft / check / save <模板>` | 修改 / 创建模板(`/workflow template`):把当前模板复制成草稿(或 `--from <样例>` 抽骨架),`check` 校验格式、列出章节变化、拿最近几份已生成文档试跑 lint 看影响,`save` 给出写入 DocNexus 知识库的 capture 指引,不直接写知识库;必装组件不可用时先修复 |
|
|
545
|
-
| `workflow/scripts/pr-desc.mjs [--branch b] [--base m] [--out f]` | 按本分支产物生成 PR / MR 描述;没有交付说明时退回用 git 记录 |
|
|
546
|
-
| `database-query/scripts/query.mjs` | 执行 SQL:选连接、取密码(只通过环境变量传给客户端)、会话层只读、拦截写语句和多语句、自动补 LIMIT、超时、脱敏敏感列;支持 mysql / psql 客户端,其他 driver 退回 JDBC |
|
|
547
|
-
| `database-query/scripts/query.mjs --schema [--tables a,b] [--write]` | 按只读会话导出表结构为 Markdown;`--write` 写入 `references/schema.md` 的 `schema:begin` / `schema:end` 之间,标记外的补充说明保留;指定的表在库里不存在时标出 |
|
|
548
|
-
| `database-query/scripts/query.mjs --schema --tables a,b --indexes` | 另外列出索引(唯一与否、列顺序)和估算行数,供 dev / project-review 核对字段、索引支撑和 DDL 锁表风险 |
|
|
549
|
-
| `nacos-config/scripts/config.mjs inspect / get` | 本地定位 Nacos 连接;按显式环境、Namespace / Group / Data ID 只读获取配置,查询 key 或子树,返回脱敏属性与来源;独立运行,不创建需求状态 |
|
|
550
|
-
| `md-to-wiki/scripts/upload.mjs info / put / target / record` | REST 上传通道:`info` 读页面标题与版本给用户确认;`put --expect-version <n> [--record <md>]` 先校验 XHTML 良构,版本对不上就拒绝上传,上传后确认版本 +1,并把发布记录写回 Markdown 第一行注释(转换时丢弃,不出现在页面上);`target` 读出记录,再次发布同一文档不必再给 pageId;`record` 供 MCP 通道上传后补写 |
|
|
551
|
-
|
|
552
|
-
## 测试
|
|
553
|
-
|
|
554
|
-
```bash
|
|
555
|
-
npm install --ignore-scripts --no-package-lock # 安装仓库测试依赖(YAML 解析);不是业务项目安装命令
|
|
556
|
-
npm test # 全部 Node 测试
|
|
557
|
-
node --test "tests/*.mjs" # 只跑 node 测试(三个平台都能跑)
|
|
558
|
-
```
|
|
559
|
-
|
|
560
|
-
node 测试覆盖:skill.json 一致性、子命令(upgrade / doctor / seed-templates / uninstall)、`resolve.mjs` 与画像推断、`lint-doc.mjs`(含 `--facts` 核对,用临时 git 仓库)、`artifacts.mjs`、`knowledge.mjs`、`query.mjs` 与表结构导出(用假的 mysql / psql 客户端)、md-to-wiki 转换与上传(用本地假 Confluence 服务)、DocNexus 模板导入与版本跟踪(用假的 docnexus CLI),以及 Nacos 本地配置解析、版本 1 / 2 / 3 协议、鉴权、只读、脱敏与错误处理(本地模拟 HTTP 服务,不连接真实配置中心)。
|
|
561
|
-
|
|
562
|
-
安装器的黑盒场景都在 `tests/test-install.mjs`,三个平台共用:每个用例在临时目录放一份安装器副本(项目外),执行安装后检查目录、软链接和配置。覆盖全新安装(单一来源 + 相对软链接)、`WORKFLOW_RUN_NO_SYMLINK=1` 退回独立拷贝、`--copy`、`--yes` 无数据库配置时退出码 1、含 `/ & | " \` 的密码、重跑保留用户配置、安装清单、手改的 skill 文件备份后更新为新版、删除模板文件后的清理(改过的先备份)、卸载与备份、`--copy` 拷贝换成链接(合并用户配置)、两份配置冲突、`.gitignore` 只追加缺失规则。
|
|
563
|
-
|
|
564
|
-
```bash
|
|
565
|
-
node --test "tests/*.mjs"
|
|
566
|
-
```
|
|
567
|
-
|
|
568
|
-
CI(`.github/workflows/test.yml`)在 push 到 main 和每个 PR 上运行:macOS、Ubuntu(Node 22)和 Windows(Node 22、24)都跑全部 node 测试。
|
|
569
|
-
|
|
570
|
-
## 发布
|
|
571
|
-
|
|
572
|
-
1. 在 `CHANGELOG.md` 的 `[Unreleased]` 下记录改动,发布时改成 `## [x.y.z] - 日期`,同步改 `package.json` 的 `version`。
|
|
573
|
-
2. 推送 `vx.y.z` tag:`.github/workflows/release.yml` 校验 tag 与版本、CHANGELOG 一致,跑测试,然后用 npm Trusted Publishing 发布(不需要 npm token / OTP)。
|
|
574
|
-
3. Trusted Publisher 只能给 npm 上已存在的包配置:新包名第一次要在本机登录 npm 后手动 `npm publish --access public`,之后在 npmjs.com 的包设置 → Trusted Publisher 里登记 GitHub 仓库 `guilianerde/skills-init` 与工作流 `release.yml`。
|
|
575
|
-
|
|
576
|
-
## 哪些文件提交、哪些忽略
|
|
577
|
-
|
|
578
|
-
安装 / 升级时安装器只往项目的 `.gitignore` 追加缺失的规则(已有内容不动),`doctor` 会检查凭据规则还在不在。团队成员照下面两张表即可。
|
|
579
|
-
|
|
580
|
-
**提交**(团队共享):
|
|
581
|
-
|
|
582
|
-
| 路径 | 说明 |
|
|
583
|
-
| --- | --- |
|
|
584
|
-
| `.agents/skills/` | skills 单一来源,含安装清单 `.workflow-run.json` |
|
|
585
|
-
| `.claude/skills/`、`.qwen/skills/`、`.codebuddy/skills/` | 指向 `.agents/skills/` 的相对软链接(Windows 上 clone 需 `git config core.symlinks true`) |
|
|
586
|
-
| `.agents/skills/workflow/profile.json` | 项目画像(无凭据),产物目录用的项目名也在这里 |
|
|
587
|
-
| `.agents/skills/database-query/references/schema.md` | 表结构速查,补齐后提交 |
|
|
588
|
-
| `workflow-run/docs/requirements/` | 需求产物;独立文档仓库模式下提交到文档仓库 |
|
|
589
|
-
| `workflow-run/other/` | 普通聊天生成的报告、方案、草稿、导出等辅助文件(按需创建,可按主题分目录);不进入需求索引、运行状态、需求统计与文档视图,按需提交 |
|
|
590
|
-
| `workflow-run/feedback/` | 运行反馈,每人一个文件;独立文档仓库模式下提交到文档仓库 |
|
|
591
|
-
| `.docnexus/project.json`、npm 清单与锁文件 | DocNexus 项目配置与运行依赖版本,随代码提交 |
|
|
592
|
-
| `workflow-run/docnexus/` | DocNexus 知识输出与定制的文档模板。独立文档仓库模式下提交到文档仓库 |
|
|
593
|
-
| `.ignore` | 让代码搜索跳过需求目录(不影响 git) |
|
|
594
|
-
| `.gitignore`、`CLAUDE.md` / `AGENTS.md` / `QWEN.md` | 安装器追加的忽略规则、文件落盘约定、DocNexus 说明段落 |
|
|
595
|
-
|
|
596
|
-
**忽略**(每人每机器一份,或可重新生成):
|
|
597
|
-
|
|
598
|
-
| `.gitignore` 规则 | 忽略的内容 | 何时追加 |
|
|
599
|
-
| --- | --- | --- |
|
|
600
|
-
| `**/database-query/config.json` | 数据库连接(含密码) | 总是 |
|
|
601
|
-
| `**/nacos-config/config.json` | 可选 Nacos 本机连接配置,密码 / token 仅引用环境变量 | 总是 |
|
|
602
|
-
| `**/nacos-config/node_modules/` | Nacos skill 的本机 YAML 解析依赖 | 总是 |
|
|
603
|
-
| `**/wiki-config.json` | wiki 地址与 token | 总是 |
|
|
604
|
-
| `**/workflow/profile.local.json` | 个人设置:本机系统与终端、提交提示开关 | 总是 |
|
|
605
|
-
| `/workflow-run/tmp/` | 临时产物:查询导出、wiki 临时 XHTML、旧版产物归档、升级 / 卸载备份、`view` 页面 | `workflow-run/` 不是独立 git 仓库时 |
|
|
606
|
-
| `/workflow-run/` | 整个文档仓库(它自己提交);同时在文档仓库的 `.git/info/exclude` 加 `/tmp/` | 独立文档仓库模式(`docs-repo`) |
|
|
607
|
-
| `.codegraph/` | CodeGraph 本地索引(SQLite) | `--with-codegraph` |
|
|
608
|
-
|
|
609
|
-
查某个文件为什么被忽略、看当前所有被忽略的文件:
|
|
610
|
-
|
|
611
|
-
```bash
|
|
612
|
-
git check-ignore -v .agents/skills/database-query/config.json
|
|
613
|
-
```
|
|
614
|
-
|
|
615
|
-
```bash
|
|
616
|
-
git status --short --ignored
|
|
617
|
-
```
|
|
618
|
-
|
|
619
|
-
## 凭据安全
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
* **数据库**:连接配置从已有 `.codex/database-query/config.json` 自动迁移,或按提示填写。
|
|
624
|
-
|
|
625
|
-
生成后 `**/database-query/config.json` 追加到 `.gitignore`,**请勿提交**。
|
|
626
|
-
|
|
627
|
-
* **wiki**:连接配置**默认留空**(`enabled: false`)。启用时填写各环境
|
|
628
|
-
|
|
629
|
-
`md-to-wiki/wiki-config.json` 的 `base_url` / `api_token`;`**/wiki-config.json` 同样加入
|
|
630
|
-
|
|
631
|
-
`.gitignore`,**请勿提交**。
|
|
632
|
-
|
|
633
|
-
* 技能内置安全规则:database-query 只读查询优先、写操作必须用户确认、敏感字段脱敏、
|
|
634
|
-
|
|
635
|
-
不在对话中输出密码。
|
|
636
|
-
|
|
637
|
-
* **Nacos**:优先读取用户选定的 application / bootstrap;可选本机 `nacos-config/config.json` 使用 `password_env` / `token_env` 引用凭据并由 gitignore 忽略。配置获取只读,不输出密码或 token,不缓存远程原文,也不自动改写数据库连接。生效环境与 Data ID 不明确时先确认。
|
|
638
|
-
|
|
639
|
-
## wiki 能力说明(连接空着不启动)
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
* `md-to-wiki` 带 **GATE**:执行前先读 `wiki-config.json`,若文件缺失 / `enabled` 非 true /
|
|
644
|
-
|
|
645
|
-
`base_url` 为空 → **立即停止**,提示用户补配,不做任何转换与上传。
|
|
646
|
-
|
|
647
|
-
* `create-tech-md-doc` / `create-release-md-doc` 的 `--prd`** 增强**同样受 GATE 约束:
|
|
648
|
-
|
|
649
|
-
未配置时自动回退纯 diff 流程(文档生成主流程不受影响)。
|
|
650
|
-
|
|
651
|
-
* 启用方式(三选一):
|
|
652
|
-
|
|
653
|
-
1. 填写 `md-to-wiki/wiki-config.json`:`enabled: true` + `base_url`(如
|
|
654
|
-
|
|
655
|
-
`https://wiki.example.com`)+ `api_token`(Confluence PAT);
|
|
656
|
-
|
|
657
|
-
2. 环境接入 Confluence MCP(如 Claude Code 的 `wiki-mcp`),SKILL.md 会优先走 MCP 通道;
|
|
658
|
-
|
|
659
|
-
3. 同时保留 `remote_url` 字段记录远程 MCP 地址(可选)。
|
|
660
|
-
|
|
661
|
-
* 上传通道自动选择:环境有 wiki MCP 工具 → 用工具;否则用 `wiki-config.json` 的 REST 参数
|
|
662
|
-
|
|
663
|
-
调 Confluence REST API。
|
|
664
|
-
|
|
665
|
-
## 产物输出规范(统一落位)
|
|
666
|
-
|
|
667
|
-
普通聊天生成的报告、分析、方案、草稿、导出等辅助文件默认写到 `workflow-run/other/`(按需创建,可按主题建子目录),不绑定需求、不登记运行状态,也不进入需求统计与文档视图。安装与 `upgrade` 会向所选环境的 `CLAUDE.md` / `AGENTS.md` / `QWEN.md` 写入这条项目级指令,无需接入 DocNexus;卸载只清理自己的指令段,保留手写内容与产物。源码、测试、配置和已有文件的维护、工作流指定的临时目录与知识库沿用原路径;用户明确指定输出路径时以用户为准。不会自动搬移已有文件。
|
|
668
|
-
|
|
669
|
-
一个需求的文档产物放在**同一个需求目录**里,方案(开发 / 缺陷修复)、交付说明、审查报告、技术方案、上线方案一起看:
|
|
670
|
-
|
|
671
|
-
```
|
|
672
|
-
workflow-run/docs/requirements/<需求名>/<项目名>/
|
|
673
|
-
├── meta.json # runs 保存分支运行状态、逐步完成标记与完成时间;另含 需求名、绑定的分支、各产物(版本、日期、wiki 发布记录、DocNexus 沉淀),给以后的可视化用
|
|
674
|
-
├── requirement.md # 需求文档(F3 / B3 收尾:目标、范围、AC 验收与澄清决定)
|
|
675
|
-
├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
|
|
676
|
-
├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才写;S 快速通道不落盘)
|
|
677
|
-
├── review.md # 审查报告(独立审查或 dev 完整流程自查;S 快速通道不落盘);复审也写这个文件,上一版归档到 workflow-run/tmp/old-artifacts/
|
|
678
|
-
├── tech-doc.md # 技术方案
|
|
679
|
-
└── release-doc.md # 上线方案
|
|
680
|
-
```
|
|
681
|
-
|
|
682
|
-
* **随代码提交和独立文档仓库两种用法的结构完全一样**,切换时文件不用挪。一个需求横跨多个服务时,各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`:随代码提交时不用配置,取 git 远端仓库名(没有远端用目录名),第一次落盘时自动写进去;独立文档仓库时由 `docs-repo` 配置。
|
|
683
|
-
* 旧版本随代码提交时没有 `<项目名>/` 这一层;`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`(被 git 跟踪的用 `git mv`,保留历史),结尾列出迁移了哪些需求,改动由你提交。目标里已有同名文件的需求不动,并提示手动处理;`doctor` 也会提示还没迁移的需求。
|
|
684
|
-
* **需求名由你定**:dev 在 Step 0 先确定工作分支,再查询绑定并确认需求名,给不出名字或说不清这次要做什么时不会进入开发流程(默认值按分支名生成;也可以选已有的需求,例如修 bug 的新分支挂到原需求下)。从 `/workflow` 完整链路开始时同样先问(只问名字,第一次落盘时才 `bind`);S 快速通道也问,但不绑定、不落盘。确定后,同一分支上的各 skill 都写到这个目录,不再问。一个需求可以绑定多个分支。
|
|
685
|
-
* 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。底层 requirement path / sync 仍保留,新的正式流程统一走 finalize。
|
|
686
|
-
* 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
|
|
687
|
-
|
|
688
|
-
完整 dev 的关键阶段由程序校验:M / L 方案确认绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;快速通道和首次创建运行的时机保持不变。协议见 [execution.md](workflow/references/execution.md)。
|
|
689
|
-
|
|
690
|
-
**独立文档仓库(可选)**:不想让产物进代码仓库、或一个需求横跨多个服务时,装好 skills 后在项目根运行一条命令:
|
|
691
|
-
|
|
692
|
-
```bash
|
|
693
|
-
npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <项目名>]
|
|
694
|
-
```
|
|
695
|
-
|
|
696
|
-
它会:
|
|
697
|
-
- `workflow-run/` 里没有内容(或只有 `tmp/`)时,把文档仓库克隆到这里(`tmp/` 先挪开再放回);
|
|
698
|
-
- 已有随项目提交的产物、DocNexus 时,原地 `git init` 并接上远端,文件不用挪(旧结构的产物先迁到 `<需求>/<项目名>/`)。远端是空仓库时,本地内容就是文档仓库的第一批内容;远端已有内容时检出远端,本地文件和远端同路径冲突(多半是两边都有 DocNexus 知识库)就退回原状并列出冲突的文件,不合并;代码仓库还跟踪着 `workflow-run/` 时提示 `git rm -r --cached workflow-run`;
|
|
699
|
-
- 然后代码仓库的 `.gitignore` 加 `/workflow-run/`,文档仓库的 `.git/info/exclude` 加 `/tmp/`;把项目名写进 `workflow/profile.json`(默认沿用已配置的,其次 git 远端仓库名;`profile.json` 随代码提交,记得提交它);文档仓库里有 DocNexus 时接上本项目的链接和段落,本机还没装它的依赖时提示运行 `upgrade --with-docnexus`。不带地址运行显示当前状态;只改项目名:`docs-repo --project <项目名>`。
|
|
700
|
-
|
|
701
|
-
`workflow-run/` 自己是 git 仓库就是这个模式:目录结构不变,各服务在同一个需求目录下各占一个子目录,DocNexus 知识库也在这个仓库里各服务共用。项目名写在 `workflow/profile.json` 的 `artifacts.project`,只配一次(`docs-repo` 会配好;没配时 skill 会问你一次)。文档里引用产物写成「文档仓库名:路径」,各服务、各人的克隆里都一样。
|
|
702
|
-
|
|
703
|
-
* 写完产物后 skill 会列出文档仓库里没提交的文件和建议的提交信息,你确认后才提交,推送另外问。不想被提示:`requirement.mjs config --commit-prompt off --local`(写在个人的 `workflow/profile.local.json`,已加入 `.gitignore`,不影响团队)。
|
|
704
|
-
* 其他服务的需求要先在 `workflow-run/` 里拉下来(`git -C workflow-run pull`),绑定时才看得到。
|
|
705
|
-
* `/workflow view` 在这个模式下显示文档仓库里所有项目的需求。
|
|
706
|
-
|
|
707
|
-
**浏览**:`/workflow view` 或 `npx @rowansenne/workflow-run view --open` 生成一个本地页面(`workflow-run/tmp/view/index.html`)。左边是需求列表,可按名称或分支搜索;右边是这个需求的各阶段、审查记录(每轮的级别数量、复核、与上次对比的修复情况)、交付记录,以及各份文档的渲染正文。页面是生成那一刻的快照,产物有更新时重新生成。
|
|
708
|
-
|
|
709
|
-
其他产物:
|
|
710
|
-
|
|
711
|
-
| 技能 | 产物 | 位置 |
|
|
712
|
-
| --- | --- | --- |
|
|
713
|
-
| database-query | 查询结果 | 默认对话输出;导出时 `workflow-run/tmp/database-query/result-<时间戳>.csv` |
|
|
714
|
-
| md-to-wiki | 转换临时 XHTML | `workflow-run/tmp/md-to-wiki/_wiki_upload_<时间戳>.html`(上传后可删) |
|
|
715
|
-
|
|
716
|
-
规则:
|
|
717
|
-
|
|
718
|
-
* 本工具的产出都在 `workflow-run/`:`docs/requirements/`(需求产物)、`docnexus/`(DocNexus 工作区,含定制的文档模板)是**持久产物**,随代码提交或在独立文档仓库里提交,团队共享。
|
|
719
|
-
* `workflow-run/tmp/` 是**临时产物**目录,安装时自动把 `/workflow-run/tmp/` 加入 `.gitignore`,不入库。
|
|
720
|
-
|
|
721
|
-
## 自定义模板
|
|
722
|
-
|
|
723
|
-
本仓库(安装器)的结构如下,`.tpl` 后缀不会被任何平台误加载。它放在项目外,不要和项目里放产出的 `workflow-run/` 混在一起:
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
```
|
|
728
|
-
workflow-run(安装器仓库)/
|
|
729
|
-
├── bin/
|
|
730
|
-
│ ├── workflow-run.mjs # 安装器入口(唯一实现,Node >= 22.13):参数解析与 init / upgrade / doctor / uninstall / seed-templates / report / view / docs-repo 调度
|
|
731
|
-
│ ├── lib/ # core / prompt / db / install / uninstall / docnexus / doctor / docsrepo
|
|
732
|
-
│ ├── skills.mjs # 读取各 skill 的 skill.json
|
|
733
|
-
│ └── seed-templates.mjs # 把文档模板导入 DocNexus
|
|
734
|
-
├── package.json # npm 包信息(bin: workflow-run)
|
|
735
|
-
├── shared/ # 多个 skill 共用的参考文件(diff-collection-common.md、prd-fetch.md),安装时按 skill.json 的 shared 拷入
|
|
736
|
-
├── tests/ # node 测试
|
|
737
|
-
├── evals/trigger-cases.json # 多 skill 分流评估用例
|
|
738
|
-
├── scripts/eval-triggers.mjs # 分流评估脚本
|
|
739
|
-
├── README.md # 本说明
|
|
740
|
-
├── workflow/
|
|
741
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
742
|
-
│ ├── lib/ # 共享核心;不反向依赖 scripts 命令入口
|
|
743
|
-
│ │ ├── project.mjs # 布局、画像、环境与配置
|
|
744
|
-
│ │ ├── requirement-read.mjs # 需求目录与元信息读取
|
|
745
|
-
│ │ ├── requirements.mjs # 绑定、版本归档与索引同步
|
|
746
|
-
│ │ ├── runs.mjs # 运行状态、阶段与完成校验
|
|
747
|
-
│ │ ├── run-gates.mjs # 方案、验证、审查与交付门禁
|
|
748
|
-
│ │ ├── code-snapshot.mjs # 代码内容摘要,绑定验证和审查证据
|
|
749
|
-
│ │ ├── artifact-finalize.mjs # 可恢复的产物收尾
|
|
750
|
-
│ │ ├── path-match.mjs # 共享范围匹配
|
|
751
|
-
│ │ ├── meta-store.mjs # 写锁与原子存储
|
|
752
|
-
│ │ ├── document-model.mjs # 标题、章节、表格等纯文本模型
|
|
753
|
-
│ │ ├── artifact-model.mjs # 产物类型、元信息、审查与交付解析
|
|
754
|
-
│ │ └── workspace-read.mjs # 工作区 / Git 采集、统一读取快照
|
|
755
|
-
│ ├── scripts/resolve.mjs # 模板来源 / 画像 / 画像推断 / 能力探测
|
|
756
|
-
│ ├── scripts/lint-doc.mjs # 对照模板检查生成的文档
|
|
757
|
-
│ ├── scripts/infer-profile.mjs # 画像推断规则(resolve.mjs infer-profile 调用)
|
|
758
|
-
│ ├── scripts/knowledge.mjs # 按分类列出相关的 DocNexus 文档
|
|
759
|
-
│ ├── scripts/artifacts.mjs # 按分支汇总各 skill 产物与 wiki 发布记录
|
|
760
|
-
│ ├── scripts/report.mjs # 本地效果报告
|
|
761
|
-
│ ├── scripts/pr-desc.mjs # 按本分支产物生成 PR / MR 描述
|
|
762
|
-
│ ├── scripts/template.mjs # 修改 / 创建模板:草稿 → 校验与影响 → 保存
|
|
763
|
-
│ ├── scripts/tables.mjs # 找出改动涉及的数据库表
|
|
764
|
-
│ ├── scripts/artifact.mjs # 草稿收尾 / 中断恢复 / 安全取消
|
|
765
|
-
│ ├── scripts/review-handoff.mjs # 自动生成审查交接与结果结构
|
|
766
|
-
│ ├── scripts/requirement.mjs # 产物按需求归档:绑定需求名、落盘路径、meta.json
|
|
767
|
-
│ ├── scripts/view.mjs # 项目文档视图(本地静态页面)
|
|
768
|
-
│ ├── scripts/make-template.mjs # 从样例文档抽模板骨架
|
|
769
|
-
│ ├── scripts/doc-sections.mjs # 原解析导出入口,转交 lib/document-model.mjs
|
|
770
|
-
│ ├── references/ # profile.md、capabilities.md、templates.md、docnexus.md、status.md、tables.md、requirements.md、codegraph.md(其他 skill 直接读对应文件)
|
|
771
|
-
│ └── profile.json.tpl # 空画像,首次使用时由 agent 推断并经确认后填写
|
|
772
|
-
├── dev/
|
|
773
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
774
|
-
│ └── references/ # plan-template.md(方案模板)、delivery-template.md(交付模板)
|
|
775
|
-
├── project-review/
|
|
776
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
777
|
-
│ └── references/ # checklist.md.tpl、report.md.tpl(报告模板)、diff-strategy.md
|
|
778
|
-
├── code-graph/
|
|
779
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
780
|
-
│ └── scripts/cg.mjs # 调 CodeGraph 库 + 扫源码补 MQ / 定时任务 / XML 表
|
|
781
|
-
├── database-query/
|
|
782
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
783
|
-
│ ├── scripts/query.mjs # 只读查询执行与表结构导出
|
|
784
|
-
│ └── references/ # config.example.json、schema.md.tpl
|
|
785
|
-
├── md-to-wiki/
|
|
786
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
787
|
-
│ ├── wiki-config.json.tpl
|
|
788
|
-
│ ├── references/ # upload.md(上传通道)、troubleshooting.md(脚本与排错)
|
|
789
|
-
│ └── scripts/ # md-to-wiki.mjs(转换 + 良构校验)、upload.mjs(REST 上传)
|
|
790
|
-
├── create-tech-md-doc/
|
|
791
|
-
│ ├── SKILL.md.tpl · skill.json
|
|
792
|
-
│ └── references/ # diff-collection.md(分层采集)、prd.md(PRD 拉取);模板不随包提供
|
|
793
|
-
└── create-release-md-doc/
|
|
794
|
-
├── SKILL.md.tpl · skill.json
|
|
795
|
-
└── references/ # diff-collection.md、prd.md;模板不随包提供
|
|
796
|
-
```
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
* 修改 `SKILL.md.tpl` 可调整触发词、工作流、输出模板(四环境共用同一份)。
|
|
801
|
-
|
|
802
|
-
* 项目相关的约定(配置中心、发布平台与 Region、定时任务注解、是否需要库表评审)不写在模板里,统一由 `workflow/profile.json` 提供;换项目时只需重新填画像。
|
|
803
|
-
|
|
804
|
-
* 安装后建议运行一次 `SHOW TABLES` 并 `DESCRIBE` 关键表,把结构补进
|
|
805
|
-
|
|
806
|
-
`<env-dir>/database-query/references/schema.md`,能显著提升查库效率。
|
|
807
|
-
|
|
808
|
-
* SKILL.md 只保留主流程,细节放在各自的 `references/`,agent 需要时再读,减少每次触发占用的上下文。
|
|
809
|
-
|
|
810
|
-
### 模板从哪里取
|
|
811
|
-
|
|
812
|
-
文档类 skill 的模板来源取决于项目是否接入了 DocNexus,生成的文档开头会注明「模板来源」:
|
|
813
|
-
|
|
814
|
-
* **已接入 DocNexus:只用知识库里的模板** `workflow-run/docnexus/library/templates/<skill>/<文件名>`(分类 `doc-template`)。不再使用 skill 自带的默认模板。库里缺模板时 skill 会停下来,提示你导入后再继续,不会悄悄回退到默认模板。
|
|
815
|
-
* **DocNexus 不可用**:修复必装组件后继续,不使用包内模板降级。
|
|
816
|
-
* **默认模板只读,定制只走 DocNexus**:要改模板或新建模板,都写进 DocNexus 知识库,团队共享同一份、每次变更有 timeline。不要直接改 skills 目录里的模板(升级会覆盖);`workflow-run/templates/` 下的项目模板已不再生效,`doctor` 会提示你导入知识库后删除。
|
|
817
|
-
|
|
818
|
-
| skill | 文件名 | 用途 | 默认模板 |
|
|
819
|
-
| --- | --- | --- | --- |
|
|
820
|
-
| create-tech-md-doc | `template.md` | 技术方案模板 | **不提供**,第一次用时按样例创建 |
|
|
821
|
-
| create-release-md-doc | `template.md` | 上线方案模板 | **不提供**,第一次用时按样例创建 |
|
|
822
|
-
| dev | `plan-template.md` | 方案模板(开发 / 修复) | 有 |
|
|
823
|
-
| dev | `delivery-template.md` | 交付说明模板 | 有 |
|
|
824
|
-
| project-review | `checklist.md` | 审查清单 | 有 |
|
|
825
|
-
| project-review | `report.md` | 审查报告模板 | 有 |
|
|
826
|
-
|
|
827
|
-
**技术方案、上线方案的模板按团队自己的格式创建**:各团队发到 wiki 的文档格式不同,skills 不再自带固定格式。第一次生成时 skill 会停下来,请你给一份团队现有的同类文档(本地 Markdown,或 wiki 的 pageId / URL)作样例,用 `workflow/scripts/make-template.mjs` 抽出章节和表格结构,把正文换成填写说明,你确认后经你授权写入 DocNexus。因此这两类文档**需要先接入 DocNexus**(`--with-docnexus`),未接入时 skill 会停下来提示。之后想换格式,直接说「重新生成技术方案模板」。
|
|
828
|
-
|
|
829
|
-
**修改模板**:说「改技术方案模板,加一节回滚方案」或 `/workflow template release 去掉灰度那节`,agent 会一路走完:
|
|
830
|
-
|
|
831
|
-
1. 把当前生效的模板复制成草稿 `workflow-run/tmp/template-draft/<skill>/<文件名>`,只改草稿;
|
|
832
|
-
2. `template.mjs check` 校验格式(必填 ` *`、可选「(如有)」、占位符),列出新增 / 删除的章节、必填变化,并拿最近几份已生成的文档试跑,告诉你新模板下它们会多出哪些错误;
|
|
833
|
-
3. 你确认后经你授权按 capture 流程写入 DocNexus 知识库,再确认生效;要撤销按 DocNexus 的 timeline 恢复旧版本。
|
|
834
|
-
|
|
835
|
-
模板别名:`tech`、`release`、`plan`、`delivery`、`review`、`checklist`。改带默认版本的模板(方案、交付说明、审查报告、审查清单)也走这条路,知识库里的版本取代默认版本,升级不会覆盖。未接入 DocNexus 时不能修改模板,agent 会提示你先接入。
|
|
836
|
-
|
|
837
|
-
* `doctor` 和 `/workflow status` 会列出还没创建的模板,以及要先接入 DocNexus 才能创建的模板。
|
|
838
|
-
|
|
839
|
-
**模板导入 DocNexus**:
|
|
840
|
-
|
|
841
|
-
```
|
|
842
|
-
npx @rowansenne/workflow-run --envs claude --skip-db --with-docnexus # 接入时自动导入默认模板
|
|
843
|
-
npx @rowansenne/workflow-run seed-templates # 已接入的项目补导入缺的模板(upgrade 时也会自动导入新增的)
|
|
844
|
-
npx @rowansenne/workflow-run seed-templates --update # 导入后没改过的模板更新为新版
|
|
845
|
-
npx @rowansenne/workflow-run seed-templates --diff # 团队改过的模板:打印与新默认模板的差异,手动合并
|
|
846
|
-
```
|
|
847
|
-
|
|
848
|
-
* 只导入 DocNexus 里还没有的、有默认版本的模板(技术方案、上线方案不在内),已有的不覆盖;项目已接入但缺模板时,安装结束会列出缺哪几份。
|
|
849
|
-
* 之后模板随知识库更新:直接编辑 `workflow-run/docnexus/library/templates/...` 后在业务项目根执行 `./.docnexus/node_modules/.bin/docnexus document sync --id <id>` 采纳;或者在生成文档后,skill 发现你做了结构性调整时会提议同步回模板(你确认后才写入)。每次变更都记录在 DocNexus 的 timeline 里,可追溯。
|
|
850
|
-
* 模板里的 `{{...}}` 是给 agent 的填写提示,DocNexus 原样保存;不要写成单独一行的 `{{fact:...}}`(那是 DocNexus 的事实引用语法)。
|
|
851
|
-
* 以前放在 `workflow-run/templates/` 下的项目模板:接入 DocNexus 后,缺模板时 skill 会把它作为 `import_from` 提议导入知识库;导入后删除这些文件。
|
|
852
|
-
|
|
853
|
-
## 触发准确度评估
|
|
854
|
-
|
|
855
|
-
当前 9 个 skills 的分流用例保存在 `evals/trigger-cases.json`,包含显式 `/dev` / `$dev` / 指定开发工作流的正例,以及普通分析、实现、修复、测试、提交和推送不进入 dev 的反例。评估方法:在临时项目里装好全部 skill,用 `claude -p` 逐条发送,取第一个被调用的工具判断分流结果:
|
|
856
|
-
|
|
857
|
-
```
|
|
858
|
-
npm run eval:triggers # 全量,每条 1 次
|
|
859
|
-
node scripts/eval-triggers.mjs --runs 3 # 每条 3 次,看稳定性
|
|
860
|
-
node scripts/eval-triggers.mjs --only dev # 只跑期望为 dev 的用例
|
|
861
|
-
```
|
|
862
|
-
|
|
863
|
-
* 需要已登录的 `claude` CLI(终端执行 `claude` 后 `/login`);每条请求会真实调用一次模型并计费,检测到第一个工具调用即终止,不会执行任何工具。
|
|
864
|
-
* 期望 `none` 表示不该触发本项目的 skill;触发了你环境里的其他 skill(如全局安装的 pdf skill)也算对。
|
|
865
|
-
* 额度用尽、未登录等调用失败记为 `E`(error),不计作「没触发」,并在结尾提示结果不可信。
|
|
866
|
-
* 结果明细写到 `tmp/evals/`。描述改动后可运行模型分流评估;它只观察首个工具调用,不等同于流程实际执行验证。旧触发规则的历史成绩不适用于当前显式入口规则。
|
|
867
|
-
|
|
868
|
-
## 为什么这些路径
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
* **Codex CLI 项目级 skills** 官方约定为 `.agents/skills/`(团队提交即共享),与豆包办公
|
|
873
|
-
|
|
874
|
-
的项目级技能目录一致,因此两者共用一份。
|
|
875
|
-
|
|
876
|
-
* **Claude Code** 项目级为 `.claude/skills/`,自动发现。
|
|
877
|
-
|
|
878
|
-
* **Qwen Code** 项目级为 `.qwen/skills/`,自动发现。
|
|
879
|
-
|
|
880
|
-
* **腾讯 WorkBuddy** 读项目工作目录下的 `.codebuddy/`(与 CodeBuddy Code 一致),项目级技能在 `.codebuddy/skills/`,同名时优先于用户级;它也读 `AGENTS.md`。
|
|
77
|
+
| [安装与升级](docs/installation.md) | 环境路径、参数、Windows、安装清单、升级与卸载 |
|
|
78
|
+
| [工作流与命令](docs/workflows.md) | 项目画像、开发与修复、运行续接、反馈、脚本规则 |
|
|
79
|
+
| [外部能力集成](docs/integrations.md) | DocNexus、CodeGraph、Nacos、wiki |
|
|
80
|
+
| [团队共享、产物与模板](docs/team-guide.md) | 提交边界、凭据、文档仓库、模板定制 |
|
|
81
|
+
| [维护、测试与发布](docs/development.md) | 架构、仓库结构、skill 元数据、测试与发版 |
|
|
82
|
+
| [架构图解](docs/architecture.html) | 调用关系、开发流程、数据归属与知识闭环 |
|
|
83
|
+
|
|
84
|
+
维护本包时使用 `npm ci --ignore-scripts` 安装锁定依赖,`npm test` 运行全部测试;`npm run test:package` 可单独验证实际 npm 包的安装、执行和卸载。
|