@rowansenne/workflow-run 0.30.0 → 0.31.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 CHANGED
@@ -4,6 +4,14 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.31.0] - 2026-10-31
8
+
9
+ ### 文档
10
+ - 精简 README 为安装、9 个 skills 使用示例、常用维护命令与文档入口;同步全部 CLI 子命令和代理命令示例,补齐非交互安装的 --yes、环境列表引号,以及获取最新发布包的 @latest;同步架构页示例与复制按钮,修正 DocNexus 浏览入口。
11
+
12
+ ### 新增
13
+ - HTTP 接口验证按改动触发:F4 列出接口、AC 与测试场景,F6 沿用既有框架补充并执行接口层测试,F7 检查覆盖与执行证据。覆盖正常请求、适用的参数错误及权限场景,断言状态码与响应;已有覆盖充分的内部重构复用测试,缺环境如实记录未验证及可执行请求。同步方案、交付模板与审查清单。
14
+
7
15
  ## [0.30.0] - 2026-10-30
8
16
 
9
17
  ### 新增
package/README.md CHANGED
@@ -1,84 +1,58 @@
1
- # workflow-run — 项目级 Agent Skills 一键初始化
1
+ # workflow-run — 项目级 Agent Skills
2
2
 
3
- 为团队项目安装 **9 个 skills**:workflow、dev、project-review、code-graph、database-query、nacos-config、md-to-wiki、create-tech-md-doc、create-release-md-doc,覆盖开发、审查、配置查询和文档交付。
3
+ 为 Codex、Claude Code、豆包办公、Qwen Code 和 WorkBuddy 安装 9 个项目级 skills,覆盖开发、代码审查、只读查询和文档交付。
4
4
 
5
- 支持 Codex CLI、Claude Code、豆包办公、Qwen Code 和腾讯 WorkBuddy。由宿主代理读取规则并执行脚本,无需常驻 Agent 服务。
5
+ ## 安装
6
6
 
7
- ## 首次安装
8
-
9
- 需要 **Node.js >= 22.13** 和 npm。在业务项目根执行;Windows 使用管理员终端:
7
+ 需要 **Node.js >= 22.13** 与 npm,在业务项目根执行;Windows 使用管理员终端。
10
8
 
11
9
  ```bash
12
- npx @rowansenne/workflow-run --with-codegraph
13
- ```
14
-
15
- 按提示选择代理环境、配置数据库。DocNexus 文档库必装并自动接入;CodeGraph 可选,不需要时去掉 `--with-codegraph`。
16
-
17
- 只安装 Codex 环境、暂不配置数据库:
18
-
19
- ```bash
20
- npx @rowansenne/workflow-run --envs codex --yes --skip-db
21
- ```
22
-
23
- 安装后重新打开代理会话,运行 `/workflow profile` 填写项目画像,再用 `/workflow status` 检查状态。明确输入 `/dev` 才进入完整开发工作流;普通分析、修改、测试请求不会自动启动 dev。
24
-
25
- [安装选项与 Windows 说明](docs/installation.md) · [分步图文教程](docs/full-install.html) · [工作流与命令](docs/workflows.md)
10
+ # Codex:非交互安装,暂不配置数据库
11
+ npx @rowansenne/workflow-run@latest --envs codex --yes --skip-db
26
12
 
27
- ## 团队共享
28
-
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/` 不提交;安装器会追加对应忽略规则。
33
-
34
- 团队成员克隆后,在项目根运行以下命令补齐本机依赖与入口,再检查状态:
35
-
36
- ```bash
37
- npx @rowansenne/workflow-run upgrade
38
- npx @rowansenne/workflow-run doctor --offline
13
+ # 交互选择环境、配置数据库,并接入 CodeGraph
14
+ npx @rowansenne/workflow-run@latest --with-codegraph
39
15
  ```
40
16
 
41
- 跨服务需求可共用独立文档仓库:
17
+ DocNexus 必装并自动接入,CodeGraph 可选。安装后重新打开代理会话,运行 `/workflow profile` 填写项目画像,再运行 `/workflow status` 检查状态。
42
18
 
43
- ```bash
44
- npx @rowansenne/workflow-run docs-repo <团队文档仓库地址>
45
- ```
19
+ ## 在代理里使用
46
20
 
47
- [完整提交清单、文档仓库与模板定制](docs/team-guide.md)
21
+ 以下输入放在代理对话中,分支、路径、连接名和页面 ID 按项目替换。
48
22
 
49
- ## 个人配置
23
+ | Skill | 示例 |
24
+ | --- | --- |
25
+ | workflow | `/workflow resume` 继续流程;`/workflow view` 查看需求文档 |
26
+ | dev | `/dev 订单导出支持按渠道筛选`;`/dev --bug 导出订单时重复返回数据` |
27
+ | project-review | `用 project-review 审查当前分支相对 main 的改动` |
28
+ | code-graph | `用 code-graph 查看 OrderService.exportOrders 的调用入口` |
29
+ | database-query | `用 database-query 查询 test 连接:SELECT id, status FROM orders LIMIT 10` |
30
+ | nacos-config | `用 nacos-config 读取测试环境 order-test.yaml 中的 order.timeout` |
31
+ | create-tech-md-doc | `/create-tech-md-doc feature/order-export main` |
32
+ | create-release-md-doc | `/create-release-md-doc feature/order-export main` |
33
+ | md-to-wiki | `/md-to-wiki "技术方案.md" 123456`(需配置 wiki 和已有目标页面) |
50
34
 
51
- 团队约定放在 `.agents/skills/workflow/profile.json`;本机工具链路径和个人偏好放在同目录的 `profile.local.json`,后者不提交。使用 `--copy` 时,路径随所选代理环境变化。
35
+ 完整 dev 流程:业务场景清单 → 技术澄清 → 方案 → 实现与验证(接口改动含 HTTP 测试)→ 审查 → 选择修复或交付。明确调用 dev 或要求完整开发流程后才启动,普通修改、测试和提交请求直接处理。
52
36
 
53
- 数据库连接由安装提示配置;wiki 默认关闭;Nacos 可从选定的 application / bootstrap 配置读取,也可使用本机命名连接。凭据不要写入团队画像。
37
+ 更多示例:[流程、模板与审查](docs/workflows.md#代理命令示例) · [数据库、CodeGraph、Nacos 与 wiki](docs/integrations.md)。
54
38
 
55
- [画像与工具链说明](docs/workflows.md) · [数据库、wiki 与 Nacos 凭据说明](docs/team-guide.md) · [DocNexus、CodeGraph、Nacos 与 wiki 集成](docs/integrations.md)
39
+ ## 常用维护命令
56
40
 
57
- ## 升级与故障恢复
41
+ 以下命令在终端、业务项目根执行:
58
42
 
59
43
  ```bash
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 # 按安装清单卸载
44
+ npx @rowansenne/workflow-run@latest upgrade # 升级 skills,保留用户配置
45
+ npx @rowansenne/workflow-run@latest doctor --offline # 本地自检
46
+ npx @rowansenne/workflow-run@latest view --open # 打开本地文档视图
47
+ npx @rowansenne/workflow-run@latest seed-templates --update # 补入模板并更新未定制的旧默认模板
64
48
  ```
65
49
 
66
- - **入口缺失或链接失效**:运行 `upgrade`,重新打开代理会话后再检查。
67
- - **需要更新 DocNexus**:使用 `upgrade --with-docnexus`。当前旧布局清理会删除旧知识且不备份;涉及旧版本时,先保存知识目录,再按[升级说明](docs/integrations.md)处理。
68
- - **模板缺失**:默认模板可用 `seed-templates` 补齐;技术方案、上线方案模板需按团队样例创建,见[模板定制](docs/team-guide.md)。
69
- - **完整流程中断**:使用 `/workflow resume` 查看下一步;有待完成的产物收尾时,按状态提示恢复或取消。
50
+ 团队共享 `.agents/skills/`、画像和流程产物;本机连接、凭据及 `profile.local.json` 不提交。更新 DocNexus 前阅读[旧布局清理说明](docs/integrations.md#破坏性更新旧布局强制清理)。
70
51
 
71
- [重装、升级、卸载与旧包改名](docs/installation.md) · [更新记录](CHANGELOG.md)
52
+ 全部子命令与安装参数见[安装与升级](docs/installation.md#子命令),提交边界和模板定制见[团队指南](docs/team-guide.md)。
72
53
 
73
- ## 专题文档
54
+ ## 文档
74
55
 
75
- | 文档 | 内容 |
76
- | --- | --- |
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 包的安装、执行和卸载。
56
+ [安装与升级](docs/installation.md) · [工作流与命令](docs/workflows.md) · [外部能力集成](docs/integrations.md) · [团队指南](docs/team-guide.md) · [维护与发布](docs/development.md) · [更新记录](CHANGELOG.md)
57
+
58
+ [架构图解](docs/architecture.html) · [分步安装教程](docs/full-install.html)
package/dev/SKILL.md.tpl CHANGED
@@ -56,7 +56,7 @@ description: "Explicitly requested dev workflow for feature development or bug f
56
56
 
57
57
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
58
58
 
59
- 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
59
+ 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
60
60
 
61
61
  ### F5 — 实现
62
62
 
@@ -64,7 +64,7 @@ description: "Explicitly requested dev workflow for feature development or bug f
64
64
 
65
65
  ### F6 — 验证
66
66
 
67
- 读 [implementation.md 的 F6](references/implementation.md);完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留。
67
+ 读 [implementation.md 的 F6](references/implementation.md);HTTP 接口或接口行为有变化时,沿用既有框架补充并执行接口层测试,覆盖正常请求、适用的参数错误和权限场景,断言状态码与响应。完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留;缺接口测试环境时附可执行请求与预期结果。
68
68
 
69
69
  ### F7 — 审查、报告与用户选择
70
70
 
@@ -28,6 +28,7 @@
28
28
 
29
29
  - 构建:{{命令}} → {{通过 / 失败 / 未运行(原因)}}
30
30
  - 测试:{{命令}} → {{通过 n 个 / 失败 / 未运行(原因)}};新增测试:{{列表}}
31
+ - HTTP 接口测试:{{方法 / 路径、关联 AC、测试文件 / 用例、覆盖场景、执行命令与实际结果;环境跑不了写「未验证」、原因、所需环境及可执行请求与预期状态码 / 响应;不涉及写「不涉及」}}
31
32
  - 开工前已有的失败:{{Step 0 基线里已经失败的测试 / 编译错误,本次未处理;没有写「无」,没跑基线写原因}}
32
33
  - 未验证项:{{表里「未验证」的验收项及其他:需要用户在什么环境怎么验证;没有写「无」}}
33
34
 
@@ -18,6 +18,9 @@
18
18
  完整流程按 `<skills>/workflow/references/execution.md`「验证证据」,在执行前 snapshot,执行后 save validation;只有代码快照仍一致,结果才能登记。feature 完成 F6 后进入 F7,bug 完成 B4 后进入 B5。快速通道不调用运行命令,下面的构建、测试与验收验证仍执行。
19
19
 
20
20
  - 按验收标准补充或更新单元测试 / 集成测试,测试放在项目既有测试目录、沿用既有测试框架。
21
+ - **HTTP 接口测试按改动触发**:新增 / 修改 HTTP 接口,或改动影响接口的参数校验、鉴权、状态码、响应结构及业务行为时,补充或更新对应接口测试并执行。内部重构未改变接口行为、已有接口测试覆盖充分时,运行现有测试即可,不强制新增重复用例。
22
+ - **接口层覆盖与断言**:沿用项目既有框架,通过 HTTP 请求或框架的 HTTP 测试入口覆盖路由、请求绑定、校验、鉴权与响应序列化;只调用 Service 的单元测试不能作为 HTTP 接口测试证据。至少覆盖正常请求、参数错误(有入参约束时);涉及权限时覆盖未登录 / 无权限场景。断言预期 HTTP 状态码、关键响应字段或错误信息,并关联验收标准的 AC 编号(快速通道用对话中的验收项);不引入额外测试平台,不穷举无关边界。
23
+ - **接口执行证据**:记录接口方法与路径、测试文件 / 用例、执行命令和实际结果,写入 validation.checks 与交付说明。环境不具备时保留测试用例,标「未验证」并说明原因、所需环境,给出可执行请求(含测试输入、必要请求头和预期状态码 / 响应);不将未执行或只通过单元测试写成接口测试通过。
21
24
  - **验收项对应到证据**:以 requirement.md 的 AC 编号为准,写明靠哪个测试或手动操作验证、结果如何;没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填,快速通道用对话中确认的验收项。
22
25
  - 先跑相关测试(`profile.test_single`,或代码图谱的 `impact` 选出的测试),修到通过;最后跑一次 `profile.test` 全量(之后又改了代码就再跑)。有 `profile.lint` 时一并运行。全量里出现、基线没跑到的失败,先看失败的测试是否碰到本次改动的代码,确认无关的按已有失败记录并写明依据。按本轮 CodeGraph 通道分析相关测试;script 模式取自 `node <skills>/code-graph/scripts/cg.mjs impact --base <main_branch>` 输出的 `tests`;`impact` 的 `entry_points`、`sql`、`config_keys` 写进交付说明(受影响的接口 / 消费者 / 定时任务、表、配置)。改动碰到 SQL、实体或 DDL 时运行 `node <skills>/workflow/scripts/tables.mjs --base <main_branch>`,对其中的表再核对一次实际表结构(见 `<skills>/workflow/references/tables.md`),结果写进交付说明的 SQL 节。
23
26
  - 如实报告结果:失败就给出失败输出并继续修;环境跑不了(缺依赖、缺中间件)就明确写「未验证」以及用户该如何验证。**不得声称未运行的测试已通过。**
@@ -53,6 +53,7 @@
53
53
  ## 6. 验证计划
54
54
 
55
55
  - 单元测试:{{引用 requirement.md 的 AC 编号,说明测试如何覆盖,不重写验收标准}}
56
+ - HTTP 接口测试:{{涉及 HTTP 接口或接口行为变化时,列方法 / 路径、关联 AC、正常请求、参数错误及适用的未登录 / 无权限场景;既有框架、复用 / 新增用例、命令与环境。不涉及则写「不涉及」,覆盖充分的内部重构可只运行现有用例}}
56
57
  - 集成 / 手工验证:{{环境、步骤、预期}}
57
58
  - 回滚方式:{{代码回滚 / 开关 / 数据回滚}}
58
59
 
@@ -47,3 +47,5 @@ requirement.md 是需求事实来源,context 只保存续接摘要。业务变
47
47
  **S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
48
48
 
49
49
  **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案草稿通过 `<skills>/workflow/references/execution.md` 的 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
50
+
51
+ **HTTP 接口验证计划**:涉及新增 / 修改 HTTP 接口,或参数校验、鉴权、状态码、响应结构及接口业务行为变化时,在验证计划列出方法、路径、关联 AC 与待测场景:正常请求、参数错误(有入参约束时),以及适用的未登录 / 无权限场景。沿用现有框架,明确已有用例如何复用、哪些需要补充、执行命令和环境;F6 按计划编写并执行。纯内部重构且接口行为不变、已有覆盖充分时只列现有测试,不另建重复用例。缺陷修复在 B4 使用相同规则。
@@ -193,7 +193,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
193
193
 
194
194
  <header class="hero">
195
195
  <div>
196
- <div class="eyebrow">@rowansenne/workflow-run · 0.30.0 · 2026-10-30</div>
196
+ <div class="eyebrow">@rowansenne/workflow-run · 0.31.0 · 2026-10-31</div>
197
197
  <h1>让 AI 编程代理按团队的规矩干活</h1>
198
198
  <p class="lede">一套装进项目里的 Agent Skills:从需求澄清、开发、测试、自审到技术方案和上线方案,每一步怎么做、做到什么程度、哪些事必须先问人,都写成团队共享的规则和脚本,随代码一起提交。</p>
199
199
  <div class="facts">
@@ -204,7 +204,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
204
204
  </div>
205
205
  </div>
206
206
  <div class="term" aria-label="安装示例">
207
- <pre><span class="p">$ </span>npx @rowansenne/workflow-run --with-docnexus --with-codegraph
207
+ <pre><span class="p">$ </span>npx @rowansenne/workflow-run@latest --with-codegraph
208
208
  <span class="dim">? 选择环境(回车 = 全部)</span>
209
209
  <span class="ok">✔</span> .agents/skills/ <span class="dim">单一来源</span>
210
210
  <span class="ok">✔</span> .claude/skills/ → 软链接
@@ -334,7 +334,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
334
334
  <p>共享核心不反向依赖命令脚本、纯模型不做 I/O——这条边界写进了测试,违反会直接跑挂。安装器自己的环境探测也用 <code>lib/project</code>,不另写一份。</p>
335
335
  <p>升级只换分发文件;项目画像、数据库、wiki 和 Nacos 本机配置保留不动,手改过的文件先备份。默认单一来源 + 相对软链接,也支持 <code>--copy</code>。</p>
336
336
  <p>DocNexus 在安装环节必装,哪怕只选 Nacos;Nacos 读取脚本没有 workflow / DocNexus 运行依赖。DocNexus 自带 skills 不计入本包的 9 个。</p>
337
- <p><code>npx @rowansenne/workflow-run doctor</code> 检查链接、画像、凭据是否被忽略、数据库能否只读连上。</p>
337
+ <p><code>npx @rowansenne/workflow-run@latest doctor</code> 检查链接、画像、凭据是否被忽略、数据库能否只读连上。</p>
338
338
  </aside>
339
339
  </div>
340
340
  </section>
@@ -378,9 +378,9 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
378
378
  <li><span class="code">F1</span><div class="name">理解需求</div><div class="what">拉 PRD,召回以往的约定和坑,列初版验收标准</div></li>
379
379
  <li class="gate"><span class="code">F2</span><div class="name">业务核对与调研</div><div class="what">先落业务场景清单,与产品逐轮核对;明确后结合场景调研代码与数据<br><span class="art">clarification.md</span></div></li>
380
380
  <li class="gate"><span class="code">F3</span><div class="name">需求澄清</div><div class="what">基于已确认场景澄清可行性、接口兼容、数据与权限等技术约束;确认理解一致后收尾需求文档<br><span class="art">requirement.md</span></div></li>
381
- <li class="gate"><span class="code">F4</span><div class="name">方案</div><div class="what">需求明确后引用需求版本,写实现设计、实施和验证计划(S / M 简版);M / L 确认方案后实现<br><span class="art">plan.md</span></div></li>
381
+ <li class="gate"><span class="code">F4</span><div class="name">方案</div><div class="what">需求明确后引用需求版本,写实现设计、实施和验证计划(S / M 简版);涉及 HTTP 改动时列接口验证场景,M / L 确认后实现<br><span class="art">plan.md</span></div></li>
382
382
  <li><span class="code">F5</span><div class="name">实现</div><div class="what">贴合现有写法,不顺手重构;SQL 只写脚本不执行</div></li>
383
- <li><span class="code">F6</span><div class="name">验证</div><div class="what">先相关测试再全量;完整流程绑定执行前代码快照,验收项逐条对应到证据</div></li>
383
+ <li><span class="code">F6</span><div class="name">验证</div><div class="what">先相关测试再全量;HTTP 接口改动补接口层测试,覆盖正常、适用的参数错误与权限场景;绑定执行前快照,按 AC 记录结果,缺环境写未验证</div></li>
384
384
  <li class="gate"><span class="code">F7</span><div class="name">审查</div><div class="what">完整流程自动生成交接材料,优先独立子 agent 审查;返回草稿与结构化结果,由主 agent 收尾 review.md,再等用户选择修复或交付<br><span class="art">review.md</span></div></li>
385
385
  <li class="gate"><span class="code">F8</span><div class="name">交付</div><div class="what">用户选择交付后才生成交付说明;提交、PR 先问,沉淀有值得记的内容才问<br><span class="art">delivery.md</span></div></li>
386
386
  </ol>
@@ -456,46 +456,61 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
456
456
  <div class="kicker">常用命令</div>
457
457
  <h2>日常就两类输入:代理里说需求,终端里管安装</h2>
458
458
  <div class="prose">
459
- <p>开发、审查、出文档在装好 skills 的代理会话里完成;安装、升级、自检在项目根的终端执行,命令前缀统一是 <code>npx @rowansenne/workflow-run</code>,下表写全。</p>
459
+ <p>开发、审查、出文档在代理对话中输入;安装、升级、自检在业务项目根的终端执行。以下示例与 README 和专题文档一致,分支、路径、连接、日期和页面 ID 按项目替换。</p>
460
460
  </div>
461
461
  <div class="tbl">
462
462
  <table>
463
- <thead><tr><th>代理里输入</th><th>做什么</th></tr></thead>
463
+ <thead><tr><th>代理对话示例</th><th>用途</th></tr></thead>
464
464
  <tbody>
465
- <tr><td>/dev &lt;需求描述&gt;</td><td>功能开发全流程:确定工作分支 → 定需求名 → F2 业务场景清单与产品核对(多轮更新)→ F3 技术澄清 → 需求明确 → 方案 → 实现 → 测试 → 独立子 agent 审查与报告(无则当前会话自查)→ 用户选择修复或交付(完整交付才生成交付说明)</td></tr>
466
- <tr><td>/dev --bug &lt;现象&gt;</td><td>缺陷修复全流程:复现 → 定位根因 → 最小修复 → 验证 → 审查报告 → 用户选择修复或交付</td></tr>
467
- <tr><td>/workflow</td><td>按明确请求路由独立能力;dev 须有显式流程授权。普通修改或提交不进入 dev;不带请求时输出能力地图和状态</td></tr>
468
- <tr><td>/workflow profile</td><td>填写或更新项目画像(主分支、构建测试命令、toolchain)</td></tr>
469
- <tr><td>/workflow status</td><td>开工快照:DocNexus 必装门槛、CodeGraph 通道、数据库与 wiki 配置</td></tr>
470
- <tr><td>读取测试环境 Nacos 的 order.yaml,查看 order.timeout</td><td>进入 nacos-config:定位本地连接,选择环境和 Data ID,再只读获取脱敏结果</td></tr>
471
- <tr><td>/workflow template &lt;模板&gt; [怎么改]</td><td>修改或创建文档模板:clarification、requirement、tech、release、plan、delivery、review、checklist</td></tr>
472
- <tr><td>/create-tech-md-doc &lt;dev分支&gt; &lt;主分支&gt;</td><td>从分支 diff 按团队模板生成技术方案</td></tr>
473
- <tr><td>/create-release-md-doc &lt;dev分支&gt; &lt;主分支&gt;</td><td>生成上线方案,自动引用同分支的技术方案和交付说明</td></tr>
474
- <tr><td>/workflow report</td><td>效果报告:审查发现与修复率、需求澄清、DocNexus 沉淀与复用</td></tr>
475
- <tr><td>/workflow view</td><td>按需求浏览全部产物的本地页面(加 --open 直接打开)</td></tr>
476
- <tr><td>/md-to-wiki &lt;md&gt; [pageId]</td><td>发布到 Confluence;发布过的文档省略 pageId 直接更新</td></tr>
465
+ <tr><td><code>/workflow</code></td><td>查看能力地图</td></tr>
466
+ <tr><td><code>/workflow profile</code></td><td>初始化项目画像</td></tr>
467
+ <tr><td><code>/workflow status</code></td><td>检查能力与当前流程进度</td></tr>
468
+ <tr><td><code>/workflow resume</code></td><td>续接当前分支流程(有多个运行时可追加运行 ID)</td></tr>
469
+ <tr><td><code>/workflow report</code></td><td>查看效果报告</td></tr>
470
+ <tr><td><code>/workflow view</code></td><td>浏览需求产物</td></tr>
471
+ <tr><td><code>/workflow template clarification 增加场景优先级</code></td><td>修改业务场景清单模板</td></tr>
472
+ <tr><td><code>/workflow template plan 补充 HTTP 接口验证场景</code></td><td>修改实现方案模板</td></tr>
473
+ <tr><td><code>/dev 订单导出支持按渠道筛选</code></td><td>功能开发</td></tr>
474
+ <tr><td><code>/dev --bug 导出订单时重复返回数据</code></td><td>缺陷修复</td></tr>
475
+ <tr><td><code>用 project-review 审查当前分支相对 main 的改动</code></td><td>分支审查</td></tr>
476
+ <tr><td><code>用 project-review 快审当前未提交的改动</code></td><td>工作区快审</td></tr>
477
+ <tr><td><code>/create-tech-md-doc feature/order-export main --prd 123456</code></td><td>技术方案</td></tr>
478
+ <tr><td><code>/create-release-md-doc feature/order-export main</code></td><td>上线方案(自动查找同分支已有技术方案)</td></tr>
479
+ <tr><td><code>/md-to-wiki &quot;技术方案.md&quot; 123456 --validate-only</code></td><td>wiki 校验</td></tr>
480
+ <tr><td><code>/md-to-wiki &quot;技术方案.md&quot; 123456</code></td><td>wiki 发布(需要已配置 wiki 和已有目标页面)</td></tr>
481
+ <tr><td><code>用 database-query 查询 test 连接:SELECT id, status FROM orders LIMIT 10</code></td><td>只读查库</td></tr>
482
+ <tr><td><code>用 code-graph 查看 OrderService.exportOrders 从哪些接口或任务进入</code></td><td>调用入口分析</td></tr>
483
+ <tr><td><code>用 nacos-config 读取测试环境 order-test.yaml 中的 order.timeout</code></td><td>Nacos 参数查询</td></tr>
477
484
  </tbody>
478
485
  </table>
479
486
  </div>
480
- <p class="sub" style="margin-top:10px">project-review 和 database-query 没有斜杠命令:直接说「审一下这次改动」「查一下 order 表有哪些索引」就会触发。</p>
487
+ <p class="sub" style="margin-top:10px">没有固定参数格式的能力直接用自然语言指定 skill 和目标。模板别名:<code>clarification</code>、<code>requirement</code>、<code>plan</code>、<code>delivery</code>、<code>review</code>、<code>checklist</code>、<code>tech</code>、<code>release</code>。技术 / 上线方案须提供两个分支;wiki 发布须已配置连接并有目标页面。</p>
481
488
  <div class="tbl">
482
489
  <table>
483
- <thead><tr><th>终端里执行(项目根)</th><th>做什么</th></tr></thead>
490
+ <thead><tr><th>终端命令示例(业务项目根)</th><th>用途</th></tr></thead>
484
491
  <tbody>
485
- <tr><td>npx @rowansenne/workflow-run init --with-docnexus --with-codegraph</td><td>首次安装 / 重装;<code>--skills dev</code> 只装子集,<code>--copy</code> 不建软链接</td></tr>
486
- <tr><td>npx @rowansenne/workflow-run upgrade</td><td>升级到当前版本:用户配置保留,手改过的文件先备份</td></tr>
487
- <tr><td>npx @rowansenne/workflow-run doctor</td><td>自检:版本、软链接、项目画像、DocNexus 模板、数据库连通、.gitignore</td></tr>
488
- <tr><td>npx @rowansenne/workflow-run seed-templates</td><td>把自带的文档模板导入 DocNexus(已有的不覆盖)</td></tr>
489
- <tr><td>npx @rowansenne/workflow-run view --open</td><td>生成并打开项目文档视图(同 /workflow view)</td></tr>
490
- <tr><td>npx @rowansenne/workflow-run docnexus view</td><td>打开 DocNexus 知识库的本地只读浏览页面(前台常驻,Ctrl+C 停止)</td></tr>
491
- <tr><td>npx @rowansenne/workflow-run report --since 2026-10-01</td><td>效果报告(同 /workflow report),只读统计产物</td></tr>
492
- <tr><td>npx @rowansenne/workflow-run feedback --json</td><td>运行反馈汇总:提问轮数、跳过的步骤、读不懂的规则,精简 skill 的依据</td></tr>
493
- <tr><td>npx @rowansenne/workflow-run docs-repo &lt;仓库地址&gt;</td><td>改用团队独立文档仓库;不带地址显示当前状态</td></tr>
494
- <tr><td>npx @rowansenne/workflow-run uninstall</td><td>按安装清单卸载,用户配置备份到 workflow-run/tmp/</td></tr>
492
+ <tr><td><code>npx @rowansenne/workflow-run@latest init --envs codex --yes --skip-db</code></td><td>安装或重装;首次安装段落已给出省略 init 的写法</td></tr>
493
+ <tr><td><code>npx @rowansenne/workflow-run@latest upgrade</code></td><td>按安装清单升级 skills,保留用户配置,手改的 skill 文件先备份;自动补入新增模板</td></tr>
494
+ <tr><td><code>npx @rowansenne/workflow-run@latest doctor --offline</code></td><td>本地自检;去掉 --offline 时另测数据库连通性</td></tr>
495
+ <tr><td><code>npx @rowansenne/workflow-run@latest uninstall</code></td><td>按安装清单卸载,保留用户产物并备份用户配置</td></tr>
496
+ <tr><td><code>npx @rowansenne/workflow-run@latest seed-templates</code></td><td>补导入缺失的默认模板,不覆盖已有模板</td></tr>
497
+ <tr><td><code>npx @rowansenne/workflow-run@latest report --since 2026-10-01 --all-branches --json</code></td><td>统计指定日期起、工作区及所有本地分支中的产物</td></tr>
498
+ <tr><td><code>npx @rowansenne/workflow-run@latest feedback --json</code></td><td>汇总运行反馈</td></tr>
499
+ <tr><td><code>npx @rowansenne/workflow-run@latest view --open</code></td><td>生成并打开本地文档视图</td></tr>
500
+ <tr><td><code>npx @rowansenne/workflow-run@latest docs-repo git@git.example.com:team/team-docs.git --project order-service</code></td><td>接入团队文档仓库;省略仓库地址时显示当前状态</td></tr>
501
+ <tr><td><code>npx @rowansenne/workflow-run@latest --with-codegraph</code></td><td>交互选择代理环境、配置数据库,并接入可选 CodeGraph;DocNexus 自动安装,无需额外指定 --with-docnexus</td></tr>
502
+ <tr><td><code>npx @rowansenne/workflow-run@latest upgrade --with-docnexus</code></td><td>额外更新 DocNexus 依赖;更新前阅读旧布局清理说明</td></tr>
503
+ <tr><td><code>npx @rowansenne/workflow-run@latest seed-templates --update</code></td><td>补入模板,并更新未定制的旧默认模板</td></tr>
504
+ <tr><td><code>npx @rowansenne/workflow-run@latest seed-templates --diff</code></td><td>只读查看团队定制模板与新默认模板的差异,供手动合并</td></tr>
505
+ <tr><td><code>npx @rowansenne/workflow-run@latest view --out workflow-run/tmp/docs.html</code></td><td>指定文档视图输出路径</td></tr>
506
+ <tr><td><code>node .agents/skills/workflow/scripts/docnexus.mjs view</code></td><td>打开知识库的本地只读浏览服务,Ctrl+C 停止</td></tr>
507
+ <tr><td><code>npx @rowansenne/workflow-run@latest --help</code></td><td>查看全部命令和参数</td></tr>
508
+ <tr><td><code>npx @rowansenne/workflow-run@latest --version</code></td><td>查看当前包版本</td></tr>
495
509
  </tbody>
496
510
  </table>
497
511
  </div>
498
- <p class="sub" style="margin-top:10px">skill 内部还有一批脚本命令(<code>resolve.mjs</code>、<code>requirement.mjs</code>、<code>review-scope.mjs</code>、<code>template.mjs</code>、<code>locate.mjs</code>、<code>tables.mjs</code>、<code>knowledge.mjs</code> 等),由各流程自动调用,不用记。</p>
512
+ <p class="sub" style="margin-top:10px">非交互安装要同时指定 <code>--envs</code> 和 <code>--yes</code>;没有数据库连接时加 <code>--skip-db</code>。<code>--with-docnexus</code> 用于强制更新 DocNexus,默认缺失即安装。安装参数见 <a href="installation.md#子命令">安装与升级</a>,代理示例见 <a href="workflows.md#代理命令示例">工作流与命令</a>;DocNexus 更新前先读 <a href="integrations.md#破坏性更新旧布局强制清理">旧布局清理说明</a>。</p>
513
+ <p class="sub" style="margin-top:10px">skill 内部还有 <code>resolve.mjs</code>、<code>requirement.mjs</code>、<code>review-scope.mjs</code>、<code>template.mjs</code>、<code>locate.mjs</code> 等脚本,由各流程调用,详见 <a href="workflows.md#脚本化的规则">脚本说明</a>。</p>
499
514
  </section>
500
515
 
501
516
  <section>
@@ -528,7 +543,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
528
543
  <li><strong>只读是默认</strong>:<code>readonly</code> 为 true 或缺省都按只读处理,写语句在会话层直接拦截;只有显式 <code>"readonly": false</code> 的连接才允许写,而且要你点名用那个连接。</li>
529
544
  <li><strong>密码不进对话</strong>:按 <code>password_env</code> 指向的环境变量 → <code>DB_PASSWORD</code> → <code>password</code> 字段的顺序取,推荐用环境变量。</li>
530
545
  <li><code>mask_columns</code>(顶层或单连接,正则数组)追加脱敏列;手机号、证件号、银行卡等默认已打码。</li>
531
- <li><code>npx @rowansenne/workflow-run doctor</code> 会试连一次验证配置(<code>--offline</code> 跳过连通性测试)。</li>
546
+ <li><code>npx @rowansenne/workflow-run@latest doctor</code> 会试连一次验证配置(<code>--offline</code> 跳过连通性测试)。</li>
532
547
  </ul>
533
548
  </div>
534
549
  <div>
@@ -558,7 +573,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
558
573
  <div class="tree"><pre>node .agents/skills/nacos-config/scripts/config.mjs inspect
559
574
  node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resources/bootstrap.yml --file src/main/resources/application-test.yml --data-id order-test.yaml --key order.timeout</pre></div>
560
575
  <p class="sub" style="margin-top:12px">支持 JSON / YAML / properties;首次解析 YAML 若缺依赖,在该 skill 目录运行 npm 安装。默认使用 Nacos 1.x / 2.x 的兼容 API,也可显式选择 2.x API 或 3.x Client API。<code>/workflow status</code> 与 <code>doctor</code> 均不测试 Nacos 远端连通性;doctor 会检查本机连接文件的忽略规则。</p>
561
- <div class="callout">本页对应 0.30.0,包含 F2 业务核对与 F3 技术澄清流程;dev 工作流仅在用户显式要求时启动。</div>
576
+ <div class="callout">本页对应 0.31.0,包含 HTTP 接口验证规则、F2 业务核对与 F3 技术澄清流程;dev 工作流仅在用户显式要求时启动。</div>
562
577
  </section>
563
578
 
564
579
  <section>
@@ -579,7 +594,7 @@ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resource
579
594
  ├── tech-doc.md <span class="c"># 技术方案(create-tech-md-doc)</span>
580
595
  └── release-doc.md <span class="c"># 上线方案(create-release-md-doc)</span></pre>
581
596
  </div>
582
- <p class="sub" style="margin-top:12px;font-size:14px">可以随代码提交,也可以把 <code>workflow-run/</code> 整个换成团队的独立文档仓库,多个服务共用,目录结构不变。<code>npx @rowansenne/workflow-run view</code> 生成本地页面按需求浏览。</p>
597
+ <p class="sub" style="margin-top:12px;font-size:14px">可以随代码提交,也可以把 <code>workflow-run/</code> 整个换成团队的独立文档仓库,多个服务共用,目录结构不变。<code>npx @rowansenne/workflow-run@latest view</code> 生成本地页面按需求浏览。</p>
583
598
  <p class="sub" style="margin-top:12px;font-size:14px">业务场景清单与需求文档是两个独立正式产物。需要清单时,在 F2 / B3 初判规模、选择完整流程并 bind、start;每轮从草稿 finalize 为 <code>clarification.md</code>,更新原问题答复和状态、追加新问题与反馈记录,保留编号并归档旧版,纳入视图、统计与 PR 引用。F3 / B3 完成技术澄清后,<code>requirement.md</code> 引用清单及版本,汇总有效业务决定与技术约束。</p>
584
599
  </div>
585
600
  <div class="loop">
@@ -588,7 +603,7 @@ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resource
588
603
  <div class="step"><div class="dot">3</div><div><b>交付时沉淀</b><p>交付里有值得记的内容才问:已确认的决定、新约定、缺陷根因;没有就跳过,元信息行写「无需沉淀」。同主题的更新原文,不重复新建。</p></div></div>
589
604
  <div class="step"><div class="dot">4</div><div><b>下次被召回</b><p>审查沉淀的问题模式,会在下一次 dev 开工时被列出来。</p></div></div>
590
605
  <div class="callout">写入知识库每次都要你同意;没有值得沉淀的内容时不问。DocNexus 是必装组件,不可用时先修复,不降级。</div>
591
- <p class="sub" style="margin-top:12px;font-size:14px">想直接翻知识库:在项目根运行 <code>npx @rowansenne/workflow-run docnexus view</code>,会起一个本地只读的文档浏览服务并打印访问地址,<code>Ctrl+C</code> 停止。加 <code>--port 8080</code> 可指定端口,不加则随机。</p>
606
+ <p class="sub" style="margin-top:12px;font-size:14px">想直接翻知识库:在项目根运行 <code>node .agents/skills/workflow/scripts/docnexus.mjs view</code>,会起一个本地只读的文档浏览服务并打印访问地址,<code>Ctrl+C</code> 停止。加 <code>--port 8080</code> 可指定端口,不加则随机。</p>
592
607
  </div>
593
608
  </div>
594
609
  </section>
@@ -598,7 +613,7 @@ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resource
598
613
  <h2>skill 自己也按数据迭代</h2>
599
614
  <div class="prose">
600
615
  <p>dev 和 project-review 每跑完一次,静默记一行过程数据到 <code>workflow-run/feedback/&lt;用户&gt;.jsonl</code>:提问了几轮、用户纠正过几次理解、跳过了哪些步骤、哪条规则读不懂或做不到。只记过程,不记代码和业务名词,也不额外打扰用户。</p>
601
- <p>团队用两三周后,<code>npx @rowansenne/workflow-run feedback</code> 按 skill 和章节汇总,据此精简或修正规则、发新版本;各项目升级时清掉旧版本的记录,从新版本重新收集。结果类数据(审查发现、修复率、沉淀率)则由 <code>npx @rowansenne/workflow-run report</code> 命令从产物里统计。</p>
616
+ <p>团队用两三周后,<code>npx @rowansenne/workflow-run@latest feedback</code> 按 skill 和章节汇总,据此精简或修正规则、发新版本;各项目升级时清掉旧版本的记录,从新版本重新收集。结果类数据(审查发现、修复率、沉淀率)则由 <code>npx @rowansenne/workflow-run@latest report</code> 命令从产物里统计。</p>
602
617
  </div>
603
618
  </section>
604
619
 
@@ -608,7 +623,7 @@ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resource
608
623
  <p>推荐全量安装,同时接入 DocNexus 文档库和 CodeGraph 代码图谱,需要 Node.js 22.13 及以上。装完运行 <code>/workflow profile</code> 填项目画像,再用 <code>/dev</code> 提一个小需求。分步说明见 <a href="full-install.html">图文教程</a>。</p>
609
624
  </div>
610
625
  <div class="term">
611
- <pre id="cmd"><span class="p">$ </span>npx @rowansenne/workflow-run --with-docnexus --with-codegraph</pre>
626
+ <pre id="cmd"><span class="p">$ </span>npx @rowansenne/workflow-run@latest --with-codegraph</pre>
612
627
  <button class="copy" id="copy-btn" type="button">复制命令</button>
613
628
  </div>
614
629
  </div>
@@ -618,7 +633,7 @@ node .agents/skills/nacos-config/scripts/config.mjs get --file src/main/resource
618
633
  <script>
619
634
  document.getElementById('copy-btn').addEventListener('click', (e) => {
620
635
  const btn = e.currentTarget;
621
- const text = 'npx @rowansenne/workflow-run --with-docnexus --with-codegraph';
636
+ const text = 'npx @rowansenne/workflow-run@latest --with-codegraph';
622
637
  const done = () => { btn.textContent = '已复制'; setTimeout(() => { btn.textContent = '复制命令'; }, 1600); };
623
638
  const fallback = () => { const r = document.createRange(); r.selectNodeContents(document.getElementById('cmd')); const s = getSelection(); s.removeAllRanges(); s.addRange(r); btn.textContent = '已选中,按 ⌘C / Ctrl+C 复制'; };
624
639
  try { navigator.clipboard.writeText(text).then(done, fallback); } catch { fallback(); }
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## 当前架构
6
6
 
7
- 本文对应 0.30.0(2026-10-30),包括 F2 业务场景清单、F3 技术澄清、需求与方案证据失效规则,以及锁定依赖和发布包验证。
7
+ 本文对应 0.31.0(2026-10-31),包括 F2 业务场景清单、F3 技术澄清、HTTP 接口验证、需求与方案证据失效规则,以及锁定依赖和发布包验证。
8
8
 
9
9
  安装分发与任务运行分开。运行时由宿主代理读取 skill 规则、调用脚本;workflow-run 本身不启动常驻 Agent 服务。
10
10
 
@@ -7,7 +7,7 @@
7
7
  需要 **Node.js >= 22.13** 与 npm(DocNexus 为必装组件)。只用 npx 安装,在项目根执行(以当前目录为项目根;Windows 要在管理员终端里运行)。推荐全量安装:
8
8
 
9
9
  ```
10
- npx @rowansenne/workflow-run --with-codegraph
10
+ npx @rowansenne/workflow-run@latest --with-codegraph
11
11
  ```
12
12
 
13
13
  按提示:选择环境(编号多选,回车 = 全部)→ 确认 / 填写数据库连接 → 自动生成。安装时自动接入 DocNexus 文档库(开发约定与审查问题的沉淀和召回、团队定制的文档模板),`--with-codegraph` 接入 CodeGraph 代码图谱(改动影响到的接口、MQ、定时任务和测试);不需要 CodeGraph 就去掉 `--with-codegraph`。装完后在 agent 里运行 `/workflow profile` 填写项目画像。
@@ -16,35 +16,60 @@ npx @rowansenne/workflow-run --with-codegraph
16
16
 
17
17
  整体架构、dev 主线流程、独立能力调用、数据归属与知识闭环见 [docs/architecture.html](architecture.html)(下载后用浏览器打开)。
18
18
 
19
- 非交互示例(bash、zsh、PowerShell 写法一样):
19
+ 非交互示例(bash、zsh、PowerShell 写法一样;环境列表加引号):
20
20
 
21
+ ```bash
22
+ # 已有数据库连接配置时,安装全部代理环境
23
+ npx @rowansenne/workflow-run@latest --envs all --yes --with-codegraph
24
+
25
+ # 跳过数据库配置,安装 Codex 与 Qwen
26
+ npx @rowansenne/workflow-run@latest --envs "codex,qwen" --skip-db --yes --with-codegraph
27
+
28
+ # 全部代理环境分别拷贝,不使用软链接
29
+ npx @rowansenne/workflow-run@latest --envs all --skip-db --yes --copy
30
+
31
+ # 只安装 Claude 环境,DocNexus 自动接入
32
+ npx @rowansenne/workflow-run@latest --envs claude --skip-db --yes
21
33
  ```
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
- ```
34
+
35
+ `--with-docnexus` 表示强制更新 DocNexus,首次安装时无需额外指定;默认缺失即安装,已安装则复用。未跳过数据库配置且本机没有已有连接时,`--yes` 会报错,应改用交互安装或加 `--skip-db`。
28
36
 
29
37
  ### 子命令
30
38
 
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` 只读打印团队改过的模板与新默认模板的差异,供手动合并 |
39
+ 以下命令在业务项目根的终端执行。示例使用 `@latest`,确保获取最新发布包;路径、日期、仓库地址与项目名按实际情况替换。
42
40
 
41
+ | 命令 | 可复制示例 | 作用 |
42
+ | --- | --- | --- |
43
+ | `init`(默认) | `npx @rowansenne/workflow-run@latest init --envs codex --yes --skip-db` | 安装或重装;首次安装段落已给出省略 init 的写法 |
44
+ | `upgrade` | `npx @rowansenne/workflow-run@latest upgrade` | 按安装清单升级 skills,保留用户配置,手改的 skill 文件先备份;自动补入新增模板 |
45
+ | `doctor` | `npx @rowansenne/workflow-run@latest doctor --offline` | 本地自检;去掉 --offline 时另测数据库连通性 |
46
+ | `uninstall` | `npx @rowansenne/workflow-run@latest uninstall` | 按安装清单卸载,保留用户产物并备份用户配置 |
47
+ | `seed-templates` | `npx @rowansenne/workflow-run@latest seed-templates` | 补导入缺失的默认模板,不覆盖已有模板 |
48
+ | `report` | `npx @rowansenne/workflow-run@latest report --since 2026-10-01 --all-branches --json` | 统计指定日期起、工作区及所有本地分支中的产物 |
49
+ | `feedback` | `npx @rowansenne/workflow-run@latest feedback --json` | 汇总运行反馈 |
50
+ | `view` | `npx @rowansenne/workflow-run@latest view --open` | 生成并打开本地文档视图 |
51
+ | `docs-repo` | `npx @rowansenne/workflow-run@latest docs-repo git@git.example.com:team/team-docs.git --project order-service` | 接入团队文档仓库;省略仓库地址时显示当前状态 |
52
+
53
+ 常用附加参数:
54
+
55
+ ```bash
56
+ # 更新 DocNexus 依赖;旧布局清理行为先看外部能力集成文档
57
+ npx @rowansenne/workflow-run@latest upgrade --with-docnexus
58
+
59
+ # 更新未定制的旧默认模板;定制模板仅查看差异后手动合并
60
+ npx @rowansenne/workflow-run@latest seed-templates --update
61
+ npx @rowansenne/workflow-run@latest seed-templates --diff
62
+
63
+ # 指定文档视图输出路径;从其他目录操作项目
64
+ npx @rowansenne/workflow-run@latest view --out workflow-run/tmp/docs.html
65
+ npx @rowansenne/workflow-run@latest doctor --offline --project-root ../order-service
66
+
67
+ # 查看全部参数或当前包版本
68
+ npx @rowansenne/workflow-run@latest --help
69
+ npx @rowansenne/workflow-run@latest --version
43
70
  ```
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
- ```
71
+
72
+ 升级 DocNexus 的旧布局清理说明见[外部能力集成](integrations.md#破坏性更新旧布局强制清理)。
48
73
 
49
74
  ## 安装路径与启用方式
50
75
 
package/docs/workflows.md CHANGED
@@ -2,6 +2,34 @@
2
2
 
3
3
  [返回首页](../README.md) · [安装与升级](installation.md) · [外部能力集成](integrations.md) · [团队共享、产物与模板](team-guide.md) · [维护、测试与发布](development.md)
4
4
 
5
+ ## 代理命令示例
6
+
7
+ 下列内容在代理对话中输入,不是在终端执行。分支、路径、连接、表名和页面 ID 按项目替换;没有固定参数格式的能力使用自然语言指定 skill 和目标。
8
+
9
+ | 目的 | 示例 |
10
+ | --- | --- |
11
+ | 查看能力地图 | `/workflow` |
12
+ | 初始化项目画像 | `/workflow profile` |
13
+ | 检查能力与当前流程进度 | `/workflow status` |
14
+ | 续接当前分支流程 | `/workflow resume`(有多个运行时可追加运行 ID) |
15
+ | 查看效果报告 | `/workflow report` |
16
+ | 浏览需求产物 | `/workflow view` |
17
+ | 修改业务场景清单模板 | `/workflow template clarification 增加场景优先级` |
18
+ | 修改实现方案模板 | `/workflow template plan 补充 HTTP 接口验证场景` |
19
+ | 功能开发 | `/dev 订单导出支持按渠道筛选` |
20
+ | 缺陷修复 | `/dev --bug 导出订单时重复返回数据` |
21
+ | 分支审查 | `用 project-review 审查当前分支相对 main 的改动` |
22
+ | 工作区快审 | `用 project-review 快审当前未提交的改动` |
23
+ | 技术方案 | `/create-tech-md-doc feature/order-export main --prd 123456` |
24
+ | 上线方案 | `/create-release-md-doc feature/order-export main`(自动查找同分支已有技术方案) |
25
+ | wiki 校验 | `/md-to-wiki "技术方案.md" 123456 --validate-only` |
26
+ | wiki 发布 | `/md-to-wiki "技术方案.md" 123456`(需要已配置 wiki 和已有目标页面) |
27
+ | 只读查库 | `用 database-query 查询 test 连接:SELECT id, status FROM orders LIMIT 10` |
28
+ | 调用入口分析 | `用 code-graph 查看 OrderService.exportOrders 从哪些接口或任务进入` |
29
+ | Nacos 参数查询 | `用 nacos-config 读取测试环境 order-test.yaml 中的 order.timeout` |
30
+
31
+ 模板别名:`clarification`、`requirement`、`plan`、`delivery`、`review`、`checklist`、`tech`、`release`。技术 / 上线方案命令必须提供开发分支和基线分支;PRD 使用 pageId 或 URL,wiki 发布使用已有页面的 pageId 或含 pageId 的 URL。
32
+
5
33
  ## workflow:入口与项目画像
6
34
 
7
35
  ```
@@ -91,6 +119,7 @@ Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_inv
91
119
  * **S 规模快速通道**:已发布本次正式清单或创建完整流程运行时继续完整流程,规模降为 S 也不切换。规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有 F2 / F3 已确认或仍待澄清的业务决定,且本次未发布正式清单、未创建完整流程运行时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并先回 F3(缺陷 B3)补需求文档,再到 F4 / B4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
92
120
  * **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 审查并落盘报告(无子 agent 时当前会话自查)→ 用户选择修复或交付(修复后验证与复审;交付必须写明根因)。
93
121
  * 审查优先用独立子 agent(期间不继续改被审代码,子 agent 只审查、写报告,不直接修复);没有子 agent 时降级为当前会话自查并把「审查者」写成当前 agent,不阻塞、也不跳过审查。遗留严重问题须说明风险并由用户明确接受,不能把选择交付写成审查通过。
122
+ * **HTTP 接口验证**:新增 / 修改接口或接口行为时,F4 在方案列出方法 / 路径、AC 和场景,F6 沿用既有框架编写或更新并执行接口层测试,F7 标准 / 深审检查覆盖与执行证据。至少测正常请求、适用的参数错误和未登录 / 无权限场景,断言状态码与关键响应;纯内部重构且接口行为不变、已有覆盖充分时运行现有用例即可。缺环境时记录未验证、原因及可执行请求和预期结果,不将单元测试通过视为 HTTP 接口测试通过。缺陷修复 B4 / B5 沿用相同规则。
94
123
  * 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
95
124
  * DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
96
125
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.30.0",
3
+ "version": "0.31.0",
4
4
  "description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -81,6 +81,8 @@
81
81
 
82
82
  ## 13. 测试
83
83
  - [ ] 本次改动的逻辑有没有对应的测试(新增分支、边界、异常路径),尤其是修 bug 时有没有能复现原问题的测试
84
+ - [ ] 新增 / 修改 HTTP 接口或接口行为时,是否有对应接口层测试,覆盖正常请求、参数错误(有入参约束时)和适用的未登录 / 无权限场景;是否断言状态码、关键响应字段或错误信息,有验收标准时对应 AC
85
+ - [ ] HTTP 测试是否实际经过路由、请求绑定、校验、鉴权与响应序列化,而非只调用 Service;是否已执行并记录结果,缺环境时是否明确「未验证」及可执行请求和预期结果;接口行为不变且覆盖充分的内部重构可复用已有用例
84
86
  - [ ] 测试是否真的断言了行为,而不是只调用一遍不出异常;mock 是否把要测的逻辑也 mock 掉了
85
87
  - [ ] 改了既有行为时,旧测试是被正确更新,还是被删掉 / 注释掉 / 加了 `@Disabled`
86
88
 
@@ -27,6 +27,8 @@
27
27
 
28
28
  每个文件只看 `review-scope.mjs` 给它的 `sections`(清单小节号,按文件类型和改动内容定),一批文件用 `node <skills>/workflow/scripts/review-scope.mjs rules <文件…>`(带上和第 1 步一样的 `--diff` / `--base`)打印这些小节的原文和画像 `review.rules` 里匹配到的项目规则,按它检查;整个改动再过一次 `overall_sections`(9 影响面、13 测试)。深审读整份清单(`node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取 `path`),包括风格。对每个发现给出 文件、**问题所在的原代码片段**(从文件里照原样复制,第 6 步靠它定位行号)、问题描述、严重级别、修改建议。
29
29
 
30
+ 审查深度包含测试维度时,HTTP 接口或接口行为有变化的,在第 13 节核对接口测试与实际执行证据;有方案时对照其验证计划,检查正常请求、参数错误及适用的权限场景,以及状态码与响应断言。不能用仅调用 Service 的单元测试代替接口层验证。环境跑不了的列为未验证,说明缺少的覆盖与实际风险,不写成接口测试已通过。
31
+
30
32
  ## 第 5 步 — 影响面分析
31
33
 
32
34
  改动是否影响其他调用方/模块。按本轮 CodeGraph 通道分析(script 模式运行 `node <skills>/code-graph/scripts/cg.mjs impact --diff <基线>...<dev>`;未提交改动用 `--base <基线>`):列出受影响的接口、MQ 消费者、定时任务、测试、表和配置 key,报告「影响面」按入口归纳并带文件:行号。Spring 注入、AOP、MyBatis XML、MQ topic、配置 key 图谱看不到,照常 grep(见 `<skills>/workflow/references/codegraph.md`)。查不到调用方的符号不能当作安全,要明说"未确认"。