@rowansenne/workflow-run 0.28.0 → 0.29.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +88 -26
  3. package/bin/lib/artifact-context.mjs +2 -0
  4. package/bin/lib/doctor.mjs +1 -1
  5. package/bin/lib/install.mjs +1 -1
  6. package/create-release-md-doc/SKILL.md.tpl +1 -0
  7. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  8. package/dev/SKILL.md.tpl +15 -7
  9. package/dev/agents/openai.yaml +2 -0
  10. package/dev/references/bug.md +4 -3
  11. package/dev/references/clarify.md +1 -1
  12. package/dev/references/delivery-template.md +1 -1
  13. package/dev/references/delivery.md +4 -4
  14. package/dev/references/implementation.md +1 -1
  15. package/dev/references/plan-template.md +7 -11
  16. package/dev/references/planning.md +7 -3
  17. package/dev/references/preflight.md +1 -1
  18. package/dev/references/requirement-template.md +32 -0
  19. package/dev/skill.json +10 -2
  20. package/nacos-config/SKILL.md.tpl +42 -0
  21. package/nacos-config/package.json +7 -0
  22. package/nacos-config/references/connection.md +47 -0
  23. package/nacos-config/scripts/config.mjs +288 -0
  24. package/nacos-config/skill.json +9 -0
  25. package/package.json +6 -2
  26. package/project-review/SKILL.md.tpl +1 -0
  27. package/project-review/references/review-method.md +1 -1
  28. package/project-review/skill.json +2 -1
  29. package/workflow/SKILL.md.tpl +13 -9
  30. package/workflow/lib/artifact-finalize.mjs +26 -12
  31. package/workflow/lib/artifact-model.mjs +2 -2
  32. package/workflow/lib/code-snapshot.mjs +8 -2
  33. package/workflow/lib/run-gates.mjs +41 -24
  34. package/workflow/lib/runs.mjs +8 -7
  35. package/workflow/references/architecture.md +41 -3
  36. package/workflow/references/capabilities.md +3 -1
  37. package/workflow/references/execution.md +13 -3
  38. package/workflow/references/requirements.md +4 -1
  39. package/workflow/references/runs.md +11 -8
  40. package/workflow/references/templates.md +2 -2
  41. package/workflow/scripts/artifact.mjs +1 -1
  42. package/workflow/scripts/pr-desc.mjs +2 -2
  43. package/workflow/scripts/review-handoff.mjs +5 -4
  44. package/workflow/scripts/template.mjs +3 -2
  45. package/workflow/skill.json +2 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,26 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.29.1] - 2026-10-29
8
+
9
+ ### 优化
10
+ - 同一轮证据校验按需读取并复用代码快照,减少保存、审查和交付中的重复全量扫描;开发流程的审查交接与报告收尾由 8 次扫描降至 4 次。保留交接结束、发布前及中断恢复时的重新检查,每份证据仍独立校验 digest。新增快照复用与扫描次数回归测试。
11
+
12
+ ## [0.29.0] - 2026-10-28
13
+
14
+ ### 修复
15
+ - Nacos CLI 入口按真实路径识别,支持默认软链接目录执行;多 profile 按名称集合匹配,避免静默退回基础连接;普通多 `@` 密码和环境变量凭据不再误判为 Maven 构建占位符;Oracle Thin / OCI 内嵌凭据 URL 整值脱敏。补充真实安装入口与完整读取回归验证。
16
+
17
+ ### 变更
18
+ - dev 改为显式触发:仅实际调用 `/dev` / `$dev`、点选 skill 或明确要求使用 dev / 完整开发工作流时进入;普通分析、代码修改、修复、测试和 Git 操作不再自动启动。Codex 元数据关闭隐式调用,workflow 路由与安装写入的项目说明同步收紧,保留已授权任务的阶段续接;更新正负分流用例与安装验证。
19
+
20
+ ### 新增
21
+ - 完整开发 / 修复新增独立 `requirement.md`:F3 / B3 澄清收尾时先生成目标、范围、AC 验收与业务决定,`plan.md` 只维护实现设计并绑定需求版本。支持模板、归档、视图、统计、审查交接和 PR 引用;需求变更使旧方案及下游证据失效,快速通道仍不落盘,不自动拆分历史文档。
22
+ - 独立 `nacos-config` skill:从 application / bootstrap YAML 或 properties 定位连接与占位符,按 Namespace / Group / Data ID 只读获取 Nacos 配置、查询参数或子树,支持命名连接、用户名密码 / token 鉴权、版本 1 / 2 / 3 协议、来源标注和敏感值脱敏。接入安装、升级保留、凭据忽略、workflow 路由及 dev / project-review 的按需核对。
23
+
24
+ ### 文档
25
+ - 同步 README、架构图解、全量安装教程与内部架构 / 能力边界,说明 9 个 skills、Nacos 独立调用、安装时的 DocNexus 策略、数据位置与模板来源;校正旧版本、层数和安装说明。测试与发布 CI 增加 YAML 测试依赖安装步骤。
26
+
7
27
  ## [0.28.0] - 2026-10-26
8
28
 
9
29
  ### 变更
package/README.md CHANGED
@@ -1,19 +1,51 @@
1
1
  # workflow-run — 项目级 Agent Skills 一键初始化
2
2
 
3
- 把 **workflow(入口路由 + 共用项目画像)**、**dev(功能开发 / 缺陷修复编排)**、**database-query(数据库查询)**、**project-review(代码审查)**、**code-graph(代码图谱:影响面、调用入口、MQ、定时任务、SQL 涉及的表)**、**md-to-wiki(发布文档到**
3
+ 将开发、审查、配置查询和文档交付封装为 **9 个项目级 skills**:workflow、dev、project-review、database-query、nacos-config、code-graph、md-to-wiki、create-tech-md-doc、create-release-md-doc。在项目根执行安装命令,为所选代理环境生成 skills、共享规则和执行脚本。
4
4
 
5
- **Confluence)**、**create-tech-md-doc /create-release-md-doc(从 git diff 生成技术 / 上线方案)**
5
+ 支持环境:**Codex CLI / Claude Code / 豆包办公(Doubao)/ 千问(Qwen Code)/ 腾讯 WorkBuddy**。
6
6
 
7
- 封装成通用项目级 Skills。在工作目录执行一条命令、选择环境,自动生成到各 AI 编程代理的项目级
7
+ > 需求产物、知识输出、反馈与临时文件统一放在 `workflow-run/`,可随代码提交或作为独立文档仓库。已安装 skills 在代理的技能目录,DocNexus 运行环境在 `.docnexus/`,CodeGraph 索引在 `.codegraph/`;业务源码沿用项目原有位置。
8
+ > 安装只用 npx,在项目根执行。推荐 `npx @rowansenne/workflow-run --with-codegraph`;DocNexus 必装,缺失时自动接入。
8
9
 
9
- 技能目录,团队共享(可提交 git)。
10
+ ## 当前架构
10
11
 
11
- 支持环境:**Codex CLI / Claude Code / 豆包办公(Doubao)/ 千问(Qwen Code)/ 腾讯 WorkBuddy**。
12
+ 本文对应 0.29.0(2026-10-28),包括独立 `nacos-config`、需求文档与 dev 显式触发规则。
12
13
 
13
- > 本工具在项目里的产出(需求产物、DocNexus 工作区、项目模板、临时文件)都放在项目根的
14
- > `workflow-run/`
15
- > 一个目录里,不往项目的其他地方写;它可以随代码提交,也可以整个是团队的独立文档仓库(见「独立文档仓库」)。
16
- > 安装只用 npx,在项目根执行。推荐 `npx @rowansenne/workflow-run --with-codegraph`;DocNexus 必装,缺失时自动接入。
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` 调整为引用需求并保留团队结构。
17
49
 
18
50
  ## 快速开始
19
51
 
@@ -27,7 +59,7 @@ npx @rowansenne/workflow-run --with-codegraph
27
59
 
28
60
  全量安装的分步说明见图文教程 [docs/full-install.html](docs/full-install.html)(下载后用浏览器打开)。
29
61
 
30
- 整体架构(代理 / 用户 view / 工作流编排 / 工具 / 底层文档库四层、dev 主线流程、设计约定、产物与知识闭环)见 [docs/architecture.html](docs/architecture.html)(下载后用浏览器打开)。
62
+ 整体架构、dev 主线流程、独立能力调用、数据归属与知识闭环见 [docs/architecture.html](docs/architecture.html)(下载后用浏览器打开)。
31
63
 
32
64
  非交互示例(bash、zsh、PowerShell 写法一样):
33
65
 
@@ -35,10 +67,25 @@ npx @rowansenne/workflow-run --with-codegraph
35
67
  npx @rowansenne/workflow-run --envs all --yes --with-docnexus --with-codegraph # 用现有数据库配置,装全部环境
36
68
  npx @rowansenne/workflow-run --envs codex,qwen --skip-db --with-docnexus --with-codegraph # 跳过数据库
37
69
  npx @rowansenne/workflow-run --envs all --skip-db --copy --with-docnexus --with-codegraph # 不用软链接,各环境独立拷贝
38
- npx @rowansenne/workflow-run --envs claude --skip-db # 最小安装:只装 skills,不接 DocNexus 和 CodeGraph
70
+ npx @rowansenne/workflow-run --envs claude --skip-db # 全部 skills + 必装 DocNexus,不接 CodeGraph
39
71
  npx @rowansenne/workflow-run uninstall # 按安装清单卸载
40
72
  ```
41
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
+
42
89
  ### 子命令
43
90
 
44
91
  | 命令 | 作用 |
@@ -93,7 +140,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
93
140
 
94
141
  如果仍然不可见,先确认业务项目下确实有 `.codebuddy/skills/workflow/SKILL.md`,并保留安装命令、`doctor --offline` 输出与 WorkBuddy 版本以便排查。项目级配置目录见 [WorkBuddy 官方说明](https://www.codebuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Project)。
95
142
 
96
- 每个 skill 目录结构(四环境一致):
143
+ 各环境中的 skill 内容相同;默认共用 `.agents/skills/` 的这一份文件:
97
144
 
98
145
 
99
146
 
@@ -102,6 +149,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
102
149
  ├── workflow/ # 入口:路由到各 skill、能力探测、维护共用项目画像
103
150
  │ ├── SKILL.md
104
151
  │ ├── scripts/resolve.mjs # 模板来源 / 画像 / 能力探测的判定脚本
152
+ │ ├── lib/ # 共享模型、读取、状态与门禁,随 workflow 安装
105
153
  │ └── profile.json # 项目画像:主分支、构建 / 测试命令、配置中心、发布平台等(无凭据,可提交;重跑不覆盖)
106
154
  ├── project-review/ # 代码审查
107
155
  │ ├── SKILL.md # 触发描述 + 审查工作流(含大改动分批、发现复核)
@@ -118,19 +166,22 @@ npx @rowansenne/workflow-run@latest doctor --offline
118
166
  │ ├── config.json # 数据库连接(init 生成,已加入 .gitignore)
119
167
  │ ├── scripts/query.mjs # 执行查询:会话只读、写语句拦截、自动 LIMIT、脱敏
120
168
  │ └── references/schema.md # 表结构速查(初始为空,建议补齐后提交)
169
+ ├── nacos-config/ # 独立只读远程配置查询,无其他 skill 运行依赖
170
+ │ ├── SKILL.md
171
+ │ ├── scripts/config.mjs # inspect 本地定位 / get 远程读取、参数查询、脱敏
172
+ │ ├── package.json # YAML 解析依赖;首次需要时在本目录安装
173
+ │ └── config.json # 可选命名连接,用户自行配置,不生成、不提交
121
174
  ├── md-to-wiki/ # 发布 md 到 Confluence wiki
122
175
  │ ├── SKILL.md # GATE:wiki 未配置则禁止启动
123
176
  │ ├── wiki-config.json # wiki 连接(init 生成,默认 enabled=false,已 gitignore)
124
177
  │ └── scripts/md-to-wiki.mjs # md → Confluence Storage Format XHTML 转换 + 良构校验(Node,无依赖)
125
- ├── create-tech-md-doc/ # 从分支 diff 生成技术方案 md(按项目模板,没有就用样例创建)
126
- │ ├── SKILL.md
127
- │ └── template.md
128
- ├── create-release-md-doc/ # 从分支 diff 生成上线方案 md(按项目模板,没有就用样例创建)
129
- │ ├── SKILL.md
130
- │ └── template.md
178
+ ├── create-tech-md-doc/ # 从分支 diff 生成技术方案,生效模板在 DocNexus
179
+ │ └── SKILL.md # 首次按用户样例创建模板,不附带 template.md
180
+ ├── create-release-md-doc/ # 从分支 diff 生成上线方案,生效模板在 DocNexus
181
+ │ └── SKILL.md
131
182
  └── dev/ # 开发 / 修 bug:需求→调研→方案→实现→测试→自审→交付
132
183
  ├── SKILL.md
133
- └── references/plan-template.md # 方案模板(S / M 简版、L 完整;快速通道不用)
184
+ └── references/plan-template.md # 导入 DocNexus 的方案模板种子;快速通道不用
134
185
  ```
135
186
 
136
187
  ## workflow:入口与项目画像
@@ -149,7 +200,7 @@ npx @rowansenne/workflow-run@latest doctor --offline
149
200
  * 知识:交付与审查的 DocNexus 沉淀率(只算真正问过沉淀的,「未询问」「无需沉淀」不计入分母;dev 内部审查不单独询问或重复计入交付沉淀)、正文引用了知识库文档的产物占比;
150
201
  * 各分支链路:方案、交付说明、审查报告、技术方案、上线方案齐不齐,哪些文档还没发布到 wiki。
151
202
 
152
- **完整流程状态与续接**:需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支,记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision;完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态,`/workflow resume [运行id]` 核对后继续;`/workflow view` 展示运行与“已完成”,尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在 F4/B4 确定流程后开始记录,补入此前已确认的进度;后续文档/发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`,`sync` 不会清掉状态。
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` 不会清掉状态。
153
204
 
154
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:
155
206
 
@@ -212,9 +263,13 @@ node .agents/skills/workflow/scripts/resolve.mjs env --check # 逐个字段核
212
263
  /dev --bug <现象 | 报错 | 日志> # 缺陷修复
213
264
  ```
214
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
+
215
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` 分类写入,并把库内路径记回交付说明),没有就跳过并在元信息行写「无需沉淀」。审查和上线方案会按分支自动读取这份交付说明。
216
- * **S 规模快速通道**:规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有需要澄清的业务决定时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并回 F4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
217
- * **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 审查并落盘报告(无子 agent 时当前会话自查)→ 用户选择修复或交付(修复后验证与复审;交付必须写明根因)。
271
+ * **S 规模快速通道**:规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有需要澄清的业务决定时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并先回 F3(缺陷 B3)补需求文档,再到 F4 / B4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
272
+ * **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 审查并落盘报告(无子 agent 时当前会话自查)→ 用户选择修复或交付(修复后验证与复审;交付必须写明根因)。
218
273
  * 审查优先用独立子 agent(期间不继续改被审代码,子 agent 只审查、写报告,不直接修复);没有子 agent 时降级为当前会话自查并把「审查者」写成当前 agent,不阻塞、也不跳过审查。遗留严重问题须说明风险并由用户明确接受,不能把选择交付写成审查通过。
219
274
  * 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
220
275
  * DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
@@ -491,16 +546,18 @@ dev 与 project-review 的 SKILL.md 保留门禁、步骤路由、必要命令
491
546
  | `database-query/scripts/query.mjs` | 执行 SQL:选连接、取密码(只通过环境变量传给客户端)、会话层只读、拦截写语句和多语句、自动补 LIMIT、超时、脱敏敏感列;支持 mysql / psql 客户端,其他 driver 退回 JDBC |
492
547
  | `database-query/scripts/query.mjs --schema [--tables a,b] [--write]` | 按只读会话导出表结构为 Markdown;`--write` 写入 `references/schema.md` 的 `schema:begin` / `schema:end` 之间,标记外的补充说明保留;指定的表在库里不存在时标出 |
493
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 或子树,返回脱敏属性与来源;独立运行,不创建需求状态 |
494
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 通道上传后补写 |
495
551
 
496
552
  ## 测试
497
553
 
498
554
  ```bash
499
- npm test # bash 冒烟测试 + 全部 node 测试
555
+ npm install --ignore-scripts --no-package-lock # 安装仓库测试依赖(YAML 解析);不是业务项目安装命令
556
+ npm test # 全部 Node 测试
500
557
  node --test "tests/*.mjs" # 只跑 node 测试(三个平台都能跑)
501
558
  ```
502
559
 
503
- 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)。
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 服务,不连接真实配置中心)。
504
561
 
505
562
  安装器的黑盒场景都在 `tests/test-install.mjs`,三个平台共用:每个用例在临时目录放一份安装器副本(项目外),执行安装后检查目录、软链接和配置。覆盖全新安装(单一来源 + 相对软链接)、`WORKFLOW_RUN_NO_SYMLINK=1` 退回独立拷贝、`--copy`、`--yes` 无数据库配置时退出码 1、含 `/ & | " \` 的密码、重跑保留用户配置、安装清单、手改的 skill 文件备份后更新为新版、删除模板文件后的清理(改过的先备份)、卸载与备份、`--copy` 拷贝换成链接(合并用户配置)、两份配置冲突、`.gitignore` 只追加缺失规则。
506
563
 
@@ -541,6 +598,8 @@ CI(`.github/workflows/test.yml`)在 push 到 main 和每个 PR 上运行:m
541
598
  | `.gitignore` 规则 | 忽略的内容 | 何时追加 |
542
599
  | --- | --- | --- |
543
600
  | `**/database-query/config.json` | 数据库连接(含密码) | 总是 |
601
+ | `**/nacos-config/config.json` | 可选 Nacos 本机连接配置,密码 / token 仅引用环境变量 | 总是 |
602
+ | `**/nacos-config/node_modules/` | Nacos skill 的本机 YAML 解析依赖 | 总是 |
544
603
  | `**/wiki-config.json` | wiki 地址与 token | 总是 |
545
604
  | `**/workflow/profile.local.json` | 个人设置:本机系统与终端、提交提示开关 | 总是 |
546
605
  | `/workflow-run/tmp/` | 临时产物:查询导出、wiki 临时 XHTML、旧版产物归档、升级 / 卸载备份、`view` 页面 | `workflow-run/` 不是独立 git 仓库时 |
@@ -575,6 +634,8 @@ git status --short --ignored
575
634
 
576
635
  不在对话中输出密码。
577
636
 
637
+ * **Nacos**:优先读取用户选定的 application / bootstrap;可选本机 `nacos-config/config.json` 使用 `password_env` / `token_env` 引用凭据并由 gitignore 忽略。配置获取只读,不输出密码或 token,不缓存远程原文,也不自动改写数据库连接。生效环境与 Data ID 不明确时先确认。
638
+
578
639
  ## wiki 能力说明(连接空着不启动)
579
640
 
580
641
 
@@ -610,6 +671,7 @@ git status --short --ignored
610
671
  ```
611
672
  workflow-run/docs/requirements/<需求名>/<项目名>/
612
673
  ├── meta.json # runs 保存分支运行状态、逐步完成标记与完成时间;另含 需求名、绑定的分支、各产物(版本、日期、wiki 发布记录、DocNexus 沉淀),给以后的可视化用
674
+ ├── requirement.md # 需求文档(F3 / B3 收尾:目标、范围、AC 验收与澄清决定)
613
675
  ├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
614
676
  ├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才写;S 快速通道不落盘)
615
677
  ├── review.md # 审查报告(独立审查或 dev 完整流程自查;S 快速通道不落盘);复审也写这个文件,上一版归档到 workflow-run/tmp/old-artifacts/
@@ -790,7 +852,7 @@ npx @rowansenne/workflow-run seed-templates --diff # 团队改过
790
852
 
791
853
  ## 触发准确度评估
792
854
 
793
- 7 个 skill 的描述有交叉(如「修 bug」该走 dev 而不是 project-review),`evals/trigger-cases.json` 收录了 26 条真实口吻的请求及期望的 skill(含不该触发任何 skill 的近似请求)。评估方法:在临时项目里装好全部 skill,用 `claude -p` 逐条发送,取第一个被调用的工具判断分流结果:
855
+ 当前 9 个 skills 的分流用例保存在 `evals/trigger-cases.json`,包含显式 `/dev` / `$dev` / 指定开发工作流的正例,以及普通分析、实现、修复、测试、提交和推送不进入 dev 的反例。评估方法:在临时项目里装好全部 skill,用 `claude -p` 逐条发送,取第一个被调用的工具判断分流结果:
794
856
 
795
857
  ```
796
858
  npm run eval:triggers # 全量,每条 1 次
@@ -801,7 +863,7 @@ node scripts/eval-triggers.mjs --only dev # 只跑期望为 dev 的用例
801
863
  * 需要已登录的 `claude` CLI(终端执行 `claude` 后 `/login`);每条请求会真实调用一次模型并计费,检测到第一个工具调用即终止,不会执行任何工具。
802
864
  * 期望 `none` 表示不该触发本项目的 skill;触发了你环境里的其他 skill(如全局安装的 pdf skill)也算对。
803
865
  * 额度用尽、未登录等调用失败记为 `E`(error),不计作「没触发」,并在结尾提示结果不可信。
804
- * 结果明细写到 `tmp/evals/`。改了任何 skill 的 description 后建议重跑一次(最近一次:26 条 × 3 次,78/78)。
866
+ * 结果明细写到 `tmp/evals/`。描述改动后可运行模型分流评估;它只观察首个工具调用,不等同于流程实际执行验证。旧触发规则的历史成绩不适用于当前显式入口规则。
805
867
 
806
868
  ## 为什么这些路径
807
869
 
@@ -10,6 +10,8 @@ const BLOCK = [
10
10
  START,
11
11
  '## 工作流文件落盘边界',
12
12
  '',
13
+ '- dev 工作流仅在用户实际调用 `/dev` / `$dev`、点选 dev skill,或明确要求使用 dev / 完整开发工作流时启动。普通分析、问答、代码修改、修 bug、重构、测试、提交代码和推送都不构成启动授权;讨论 dev 或引用命令示例也不构成授权。',
14
+ '- 未获 dev 流程授权时,直接处理当前任务,不自动做工作流开工探测、确认需求名、绑定需求、创建运行或补齐需求 / 方案 / 审查 / 交付文档,也不主动询问是否开启 dev。已授权的同一 dev 任务可按当前阶段续接;只问分析或要求提交代码时仅处理当前请求,不重启或自行推进流程。旧运行、旧产物和分支绑定不构成新任务或新会话的恢复授权。',
13
15
  `- 普通聊天中生成的报告、分析、方案、草稿、导出等辅助文件,默认写到项目根的 \`${HOME}/other/\`(需要时创建,可按主题建子目录)。不要因为分支已绑定需求就放进需求目录。`,
14
16
  `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / path / sync 或 run.mjs,不创建或更新需求 meta.json,也不将这些文件计入需求产物和运行状态。`,
15
17
  '- 项目源码、测试、配置及已有文件的维护仍遵循项目原目录;工作流自身指定的临时目录、知识库等路径沿用各自规则。用户明确指定输出路径时按用户要求执行,不自动搬移已有文件。',
@@ -143,7 +143,7 @@ export function doctor(root, offline) {
143
143
  step('.gitignore');
144
144
  const gi = path.join(root, '.gitignore');
145
145
  const lines = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8').split(/\r?\n/).map((l) => l.trim()) : [];
146
- const need = ['**/database-query/config.json', '**/wiki-config.json'];
146
+ const need = ['**/database-query/config.json', '**/nacos-config/config.json', '**/wiki-config.json'];
147
147
  const lack = need.filter((r) => !lines.includes(r));
148
148
  if (lack.length) bad(`.gitignore 缺少 ${lack.join(' ')}:凭据可能被提交,重跑 npx @rowansenne/workflow-run upgrade 补齐`); else ok('凭据文件已被忽略');
149
149
 
@@ -226,7 +226,7 @@ export function linkSkills(root, envName, rel, skills = SKILLS) {
226
226
  // DocNexus 的运行依赖、检索库和草稿由项目根的 .docnexus/.gitignore 忽略。
227
227
  export function updateGitignore(root, withCodeGraph = false) {
228
228
  const gi = path.join(root, '.gitignore');
229
- const rules = ['**/database-query/config.json', '**/wiki-config.json', '**/workflow/profile.local.json', homeIsRepo(root) ? `/${HOME}/` : `/${TMP_DIR}/`];
229
+ const rules = ['**/database-query/config.json', '**/nacos-config/config.json', '**/nacos-config/node_modules/', '**/wiki-config.json', '**/workflow/profile.local.json', homeIsRepo(root) ? `/${HOME}/` : `/${TMP_DIR}/`];
230
230
  if (withCodeGraph) rules.push('.codegraph/'); // 本地索引(SQLite),各人各建
231
231
  const existing = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8').split(/\r?\n/).map((l) => l.trim()) : [];
232
232
  const missing = rules.filter((r) => !existing.includes(r));
@@ -38,6 +38,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
38
38
  ### Step 2 — 采集 diff 并抽取事实
39
39
 
40
40
  按 `references/diff-collection.md` 执行:有技术方案(`--tech` 或自动关联)时先解析它复用其事实;其余层用三点 `<main>...<dev>` 分层采集。只写 diff 中可见的事实,看不到写「待补充」。有 `prd_context` 时做 PRD 对齐校验。
41
+ 同分支有 `latest.requirement` 时,引用其目标、范围和 AC 验收作为上线回归依据,标明文档路径与版本;部署、SQL 与配置变更仍以 diff / 交付说明核实,不把需求计划当成已实现事实。
41
42
 
42
43
  ### Step 3 — 选模板并填充
43
44
 
@@ -46,7 +46,7 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
46
46
 
47
47
  | 事实 | 来源 |
48
48
  |---|---|
49
- | 需求背景 | 有 PRD 时取 `prd_context`;无 PRD 写「待补充」 |
49
+ | 需求背景 | 优先引用同分支 `latest.requirement` 的目标、范围与澄清结论;外部 PRD 用 `prd_context` 并标来源;都没有写「待补充」 |
50
50
  | 影响范围 | 各层命中的模块 / 包名;代码图谱可用时补上 `cg.mjs impact --diff <main>...<dev>` 的受影响入口与模块(见 `<skills>/code-graph/SKILL.md`) |
51
51
  | 详细方案 | Service 变更;有 PRD 时补业务语义并标注来源 |
52
52
  | 接口 / 消息协议 / 字段变更 | 接口与消息层、DTO / VO |
package/dev/SKILL.md.tpl CHANGED
@@ -1,20 +1,27 @@
1
1
  ---
2
2
  name: dev
3
- description: "Implement a feature or fix a bug in this project end to end: understand the requirement, study existing code, clarify open decisions with the user in rounds, plan at the right size, implement in small verified steps, run tests, have an independent subagent review and write a report, then let the user choose fixes or delivery with config/SQL checklists. Use when the user asks to develop, implement, add, change or fix something in the codebase — including concrete refactors that touch several classes (swap a type such as Date → LocalDateTime, rename, replace an API) followed by running tests — or invokes /dev <需求> or /dev --bug <现象>. Trigger phrases: 帮我开发 / 实现这个需求 / 加个接口 / 改一下这个逻辑 / 把 X 改成 Y / 重构一下 / 改完跑一下测试 / 修这个 bug / 排查并修复 / 线上报错了帮我修 / implement this feature / fix this bug. Not for pure code review (project-review), SQL lookups (database-query) or doc generation (create-tech-md-doc / create-release-md-doc)."
3
+ description: "Explicitly requested dev workflow for feature development or bug fixing, from requirements and planning through implementation, verification, review and delivery. Invoke only when the user issues /dev or $dev, explicitly asks to start/use the dev skill or the full development workflow (按 dev 流程 / 启动完整开发工作流), or explicitly resumes a previously authorized dev run. Ordinary analysis, questions, code edits, refactors, bug fixes, tests, Git commits/pushes, or mentions and quoted examples of dev do not authorize this workflow. Do the requested ordinary task directly without starting dev."
4
4
  ---
5
5
 
6
6
  # Dev
7
7
 
8
- 把需求或缺陷推进到可交付。`/dev <需求 | PRD>` 为功能开发,`/dev --bug <现象>` 为缺陷修复;自然语言按同样意图路由。
8
+ 把需求或缺陷按用户明确选择的流程推进到可交付。`/dev <需求 | PRD>` 为功能开发,`/dev --bug <现象>` 为缺陷修复;`$dev` 或明确要求「按 dev 流程」「启动完整开发工作流」同样可进入。
9
9
  进入每个阶段前,读取下面指向的 reference 对应小节;不在开工时一次加载全部方法说明。
10
10
 
11
+ ## 触发边界(先于所有流程步骤)
12
+
13
+ - **仅显式进入**:用户实际调用 `/dev` / `$dev`、点选 dev skill,或明确要求使用 dev / 完整开发工作流。讨论 dev、引用文档或命令示例、改写本 skill 的规则,都不是启动指令。
14
+ - **普通任务直接处理**:分析代码、解释问题、提供建议、实现 / 修改 / 修复 / 重构、运行测试、代码提交 / 推送等请求本身不触发 dev;不因任务复杂、文件多、涉及配置或分支已有需求绑定而升级为 dev。不要为这些任务主动询问是否开启 dev。
15
+ - **未获流程授权时**:即使本文件已被自动加载,也只处理当前普通任务,不运行 dev 的开工探测、需求命名、bind / start / save / finalize,不生成 requirement / plan / review / delivery 或流程反馈。其他被用户明确要求的独立 skill 按其规则执行。
16
+ - **已启动流程的续接**:同一任务此前已获 dev 授权,可按保存阶段继续,不要求每条消息重复 `/dev`;用户只问分析、只要求提交代码或指定当前独立操作时,仅处理该请求,不重启流程、重做前置步骤或自行推进阶段。新会话仅发现旧运行或旧产物,不等于恢复授权;用户明确要求继续该 dev 运行时才恢复。
17
+
11
18
  ## 门禁
12
19
 
13
20
  - 开工先运行 `node <skills>/workflow/scripts/resolve.mjs status`;DocNexus 必装,不可用先修复。可选增强复用 `<skills>/workflow/references/capabilities.md` 的本轮快照。
14
21
  - 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
15
22
  - 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
16
23
  - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有已确认的业务决定;具体资格见 F4。
17
- - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F4(bug 回 B4)补方案。
24
+ - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
18
25
  - 完整流程每轮审查落 `review.md`,交报告后等待明确选择修复或交付;选择交付前不创建或更新 `delivery.md`。
19
26
  - 修复后必须验证、复审并再次等选择;严重遗留风险须说明并取得明确接受,不能把一般的“交付”当作接受风险。
20
27
  - 交付选择不授权提交、推送、发布或知识写入;没有值得沉淀的知识不询问,有则先取得授权。
@@ -27,7 +34,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
27
34
  ## 完整流程的运行状态
28
35
 
29
36
  确定工作分支后先 `run.mjs show`;恢复时核对 context、代码与证据,不能把“继续”当作交付选择。
30
- 非快速通道在 F4 / B4 首次落盘前 bind,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,补记真实完成的前置步骤。
37
+ 非快速通道在 F3 / B3 收尾、首次落盘需求文档前 bind,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,补记真实完成的前置步骤;首个文档为 `requirement.md`。
31
38
  每步完成、等待、阻塞和结束会话前 save;修复回 F5 / B4,交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md` 与 [execution.md](../workflow/references/execution.md)。
32
39
  交付、自检、摘要与反馈处理后,末步标 completed,再 `run.mjs complete`,保存 completed(已完成)和 completed_at;已完成运行不覆盖。
33
40
 
@@ -40,14 +47,15 @@ description: "Implement a feature or fix a bug in this project end to end: under
40
47
  ### F2 — 现状调研
41
48
 
42
49
  读 [planning.md 的 F2](references/planning.md);按本轮能力沿调用链读代码,涉及表时用 `tables.mjs --files <文件>` 定位;事实与证据进入方案依据。
50
+ 涉及远程参数或开关且已安装 nacos-config 时,按 `<skills>/nacos-config/SKILL.md` 按需读取并标明来源;无法读取时注明「未核对远程配置」,不把代码默认值当成远程实际值。
43
51
 
44
52
  ### F3 — 需求澄清
45
53
 
46
- 读 [clarify.md](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);事实自己查、决定交用户;输出验收标准、范围和已确认决定,实现中新决定先停下来澄清。
54
+ 读 [clarify.md](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);事实自己查、决定交用户。澄清后按 F4 标准判定规模与快速通道;完整流程用 `artifact.mjs finalize --kind requirement` 收尾 `requirement.md`,独立保存目标、范围、验收与决定。实现中新决定先回本步更新需求文档。
47
55
 
48
56
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
49
57
 
50
- 先读 [planning.md 的 F4](references/planning.md) 再选择快速通道;完整流程用 `artifact.mjs finalize --kind plan` 将草稿收尾为 `plan.md`,S / M 简版、L 完整版;M / L 确认后记录 approval,再进入实现。
58
+ 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
51
59
 
52
60
  ### F5 — 实现
53
61
 
@@ -77,7 +85,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
77
85
 
78
86
  ### B3 — 定位根因
79
87
 
80
- 读 [bug.md 的 B3](references/bug.md);沿链路找第一个出错位置,以代码 / 日志 / 数据 / 历史形成根因证据,并查同类风险。
88
+ 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先生成独立 requirement.md、完成 B3,再进入修复方案。
81
89
 
82
90
  ### B4 — 修复与验证
83
91
 
@@ -0,0 +1,2 @@
1
+ policy:
2
+ allow_implicit_invocation: false
@@ -17,16 +17,17 @@
17
17
  - 沿调用链找到**第一个**出错的位置,用证据(代码行、日志、数据、git 历史 `git log -L` / `git blame`)说明为什么错。
18
18
  - 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
19
19
  - 检查同一根因是否在其他调用方同样存在。
20
+ - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成 requirement.md,用 `artifact.mjs finalize --kind requirement` 并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
20
21
 
21
22
  ### B4 — 修复与验证
22
23
 
23
- - 修复前按 F4 的标准判定规模并告知用户(规模不询问确认);S 规模符合快速通道条件时照 F4 问用户是否走快速通道,问完等本轮答复再改代码:明确同意才走快速通道(不落盘),拒绝或未明确同意按完整流程。
24
- - **完整流程先把修复方案追加进 `plan.md`**:按 Artifact Location 绑定需求并创建 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支和本次日期。没有方案则按模板创建草稿,只填适用节。用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 取得用户确认后记录 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
24
+ - 复用 B3 收尾时按 F4 标准判定的规模和通道,不重复询问;范围变化时重新判定。快速通道退出时先回 B3 补需求文档,再补方案。
25
+ - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 取得用户确认后记录 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
25
26
  - 做能消除根因的**最小改动**;B2 的测试由红变绿,相关已有测试保持通过(运行方式同 F6)。
26
27
  - 如果历史脏数据需要修正,写成 SQL 脚本交给用户,不直接执行。
27
28
 
28
29
  ### B5 — 审查与交付
29
30
 
30
- 同 F7、F8:优先由独立子 agent 审查(没有子 agent 时在当前会话自查)并落盘 `review.md`,交报告后等待用户选择修复或交付;修复后验证、复审,再等选择,完整流程仅在用户选择交付后生成 `delivery.md`(「类型」写缺陷修复)。快速通道同样适用于缺陷修复:S 规模、用户在 B4 已同意走快速通道,不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金,且同类风险排查没有发现其他调用方受影响时,不绑定需求、不落任何产物文件,审查在当前会话做,交付在对话里一次完成并注明「DocNexus:未询问(快速通道不问沉淀)」;根因(证据链、修复方式)必须在对话里写清楚。完整交付时,交付说明的「根因」节必须写:证据链、修复方式、为什么这样修、同类风险排查结果;DocNexus 沉淀时根因是首要候选。
31
+ 同 F7、F8:优先由独立子 agent 审查(没有子 agent 时在当前会话自查)并落盘 `review.md`,交报告后等待用户选择修复或交付;修复后验证、复审,再等选择,完整流程仅在用户选择交付后生成 `delivery.md`(「类型」写缺陷修复)。快速通道同样适用于缺陷修复:S 规模、用户在 B3 收尾时已同意走快速通道,不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金,且同类风险排查没有发现其他调用方受影响时,不绑定需求、不落任何产物文件,审查在当前会话做,交付在对话里一次完成并注明「DocNexus:未询问(快速通道不问沉淀)」;根因(证据链、修复方式)必须在对话里写清楚。完整交付时,交付说明的「根因」节必须写:证据链、修复方式、为什么这样修、同类风险排查结果;DocNexus 沉淀时根因是首要候选。
31
32
 
32
33
  B4 的方案、实现进入与验证证据分开登记:方案 finalize 后,M / L 记录 approval,再 save implement: true;验证用执行前 snapshot 与实际 checks,B4 最后才标 completed。B5 按 execution.md 的交接、报告收尾、交付选择和交付收尾执行,报告完成不代表 B5 已完成。
@@ -54,4 +54,4 @@
54
54
  - **需求要点**、**验收标准**(可验证的行为)、**不在本次范围**
55
55
  - **已确认的决定**:每条一句话,标注是用户决定还是按推荐采纳
56
56
 
57
- M / L 规模等用户确认「理解一致」后才进入方案;这些决定写进方案文档第 1 节和交付说明,值得长期记住的(业务规则、取舍)在交付时作为 DocNexus 沉淀候选。
57
+ M / L 规模等用户确认「理解一致」后,按 planning.md 的 F3 收尾先生成独立 requirement.md,再进入方案;这些决定保存在需求文档,plan.md 只引用需求路径与版本,交付说明按需汇总。值得长期记住的业务规则与取舍在交付时作为 DocNexus 沉淀候选。
@@ -24,7 +24,7 @@
24
24
 
25
25
  | 验收项 | 测试 / 操作 | 结果 |
26
26
  |---|---|---|
27
- | {{F1 / F3 的验收标准,每条一行;缺陷修复写「现象不再出现」}} | {{测试类.方法,或手动操作步骤}} | {{通过 / 失败 / 未验证(原因)}} |
27
+ | {{requirement.md 的 AC 编号与验收项,每条一行;缺陷修复写对应的预期行为}} | {{测试类.方法,或手动操作步骤}} | {{通过 / 失败 / 未验证(原因)}} |
28
28
 
29
29
  - 构建:{{命令}} → {{通过 / 失败 / 未运行(原因)}}
30
30
  - 测试:{{命令}} → {{通过 n 个 / 失败 / 未运行(原因)}};新增测试:{{列表}}
@@ -20,18 +20,18 @@
20
20
 
21
21
  独立文档仓库中 F7 的报告提交提示延后到本步:完整流程交付完成后运行 `requirement.mjs pending`,按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」询问;不让审查环节提前询问或执行提交。
22
22
 
23
- **快速通道交付**(见 F4「S 规模快速通道」):一次对话交付,不绑定需求、不落任何产物文件——方案、`review.md`、交付说明都不写,不跑 lint、不问 DocNexus 沉淀(运行反馈仍照常记一行),交付里注明「DocNexus:未询问(快速通道不问沉淀)」。给:结果一句话、改动文件、验证(验收项 → 测试 / 操作 → 结果,构建 / 测试命令与结果,开工前已有的失败,未验证项如实写)、当前会话审查的结论与遗留问题;按完整流程第 4 步记录运行反馈;然后只问提交(建议的 commit message)。用户说「落盘交付说明」或之后要出上线方案时,先绑定需求,回到 F4 补方案、F7 补审查报告(`review.md`),取得交付选择后,才按下面的完整流程生成交付说明、判断沉淀。
23
+ **快速通道交付**(见 F4「S 规模快速通道」):一次对话交付,不绑定需求、不落任何产物文件——方案、`review.md`、交付说明都不写,不跑 lint、不问 DocNexus 沉淀(运行反馈仍照常记一行),交付里注明「DocNexus:未询问(快速通道不问沉淀)」。给:结果一句话、改动文件、验证(验收项 → 测试 / 操作 → 结果,构建 / 测试命令与结果,开工前已有的失败,未验证项如实写)、当前会话审查的结论与遗留问题;按完整流程第 4 步记录运行反馈;然后只问提交(建议的 commit message)。用户说「落盘交付说明」或之后要出上线方案时,先绑定需求,回到 F3 补需求文档、F4 补方案、F7 补审查报告(`review.md`),取得交付选择后,才按下面的完整流程生成交付说明、判断沉淀。
24
24
 
25
25
  完整流程:
26
26
 
27
- 1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,先写到 tmp 草稿,按 execution.md 用 `artifact.mjs finalize --kind delivery` 发布(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写最新审查报告,有方案(`plan.md`)时也写方案路径。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
27
+ 1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,先写到 tmp 草稿,按 execution.md 用 `artifact.mjs finalize --kind delivery` 发布(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写 requirement.md 的 cite / 版本、最新方案与审查报告。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
28
28
  2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 sync 代替。
29
29
  3. **对话里给摘要**:结果、验证(含未验证项)、最新审查报告路径与结论、遗留问题和用户接受的风险、配置 / SQL 有无、交付文件路径;不必把全文贴进对话。
30
30
  4. **记录运行反馈**(不问用户):按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill dev --model <模型名> --mode <feature|bug> --size <S|M|L> --fast <yes|no> --rounds <提问轮数> --corrections <用户纠正理解的次数> --acceptance <已验证>/<总数> --baseline-failures <n>`,有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程,不写代码和业务名词;报错就提一句,不影响交付。
31
31
  完成上述交付摘要与反馈后,按运行状态协议将 F8(bug 为 B5)标 completed 并 complete。下面的可选后续动作在完成标记后处理。
32
32
 
33
33
  5. **询问下一步**,不要自行执行:
34
- - 提交:给出建议的 commit message 和要 add 的文件(只含本需求的改动,Step 0 确认无关的不 add;建议把方案、审查报告和交付说明一起提交,随分支保留),用户同意后再 `git commit`;**不 push**,除非用户明确要求。
34
+ - 提交:给出建议的 commit message 和要 add 的文件(只含本需求的改动,Step 0 确认无关的不 add;建议把需求文档、方案、审查报告和交付说明一起提交,随分支保留),用户同意后再 `git commit`;**不 push**,除非用户明确要求。
35
35
  - PR / MR:用户要提 PR / MR 时,运行 `node <skills>/workflow/scripts/pr-desc.mjs`(缺省当前分支、基线 `profile.main_branch`),它把本分支的交付说明、审查报告、技术方案、上线方案汇总成描述(没有交付说明时退回用提交记录和改动文件),把输出给用户;用 `gh pr create` / `glab mr create` 创建要用户明确同意。
36
36
  - 文档:运行 `node <skills>/workflow/scripts/artifacts.mjs` 看本分支已有哪些产物(方案、交付说明、审查报告、技术方案、上线方案及 wiki 发布记录),按输出的 `next` 建议下一步:M / L 规模缺技术方案时建议 `create-tech-md-doc`,要上线时建议 `create-release-md-doc`(会自动引用本分支的技术方案和交付说明)。
37
37
  - **沉淀到 DocNexus**:先判断本次交付有没有**特别值得记录**的内容——已确认的决定、新约定、踩到的坑、缺陷根因、配置 / 表结构变化;标准是「下次做同类需求时,它能不能少踩一次坑或少做一次决定」,分支、产物路径这类工作流信息不算。
@@ -46,5 +46,5 @@
46
46
  产物按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`,规则见 `<skills>/workflow/references/requirements.md`:
47
47
 
48
48
  - **需求名**:Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`(用户明确同意按分支名生成时不带 `--name`);S 快速通道不 bind、不落盘。缺陷修复同样处理(可以选择挂到原需求下)。
49
- - **正式写入**:按 `<skills>/workflow/references/execution.md`,方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
49
+ - **正式写入**:按 `<skills>/workflow/references/execution.md`,需求、方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind requirement|plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
50
50
  - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新仍显式 sync。
@@ -18,6 +18,6 @@
18
18
  完整流程按 `<skills>/workflow/references/execution.md`「验证证据」,在执行前 snapshot,执行后 save validation;只有代码快照仍一致,结果才能登记。feature 完成 F6 后进入 F7,bug 完成 B4 后进入 B5。快速通道不调用运行命令,下面的构建、测试与验收验证仍执行。
19
19
 
20
20
  - 按验收标准补充或更新单元测试 / 集成测试,测试放在项目既有测试目录、沿用既有测试框架。
21
- - **验收项对应到证据**:F1 / F3 的每条验收标准写明靠哪个测试或手动操作验证、结果如何;没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填,快速通道在对话里列同样的对应。
21
+ - **验收项对应到证据**:以 requirement.md 的 AC 编号为准,写明靠哪个测试或手动操作验证、结果如何;没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填,快速通道用对话中确认的验收项。
22
22
  - 先跑相关测试(`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
23
  - 如实报告结果:失败就给出失败输出并继续修;环境跑不了(缺依赖、缺中间件)就明确写「未验证」以及用户该如何验证。**不得声称未运行的测试已通过。**
@@ -1,20 +1,16 @@
1
1
  # 方案 — {{需求名}}
2
2
 
3
3
  > 规模:{{S / M / L}} | 分支:{{dev分支}} | 日期:{{YYYY-MM-DD}}
4
- > 需求来源:{{对话 / PRD 链接}} | 参考记忆:{{workflow-run/docnexus/library/... 或「无」}}
4
+ > 需求文档:{{requirement.md 的 cite 与版本}} | 参考记忆:{{workflow-run/docnexus/library/... 或「无」}}
5
5
 
6
6
  <!-- 非快速通道一律落盘:S / M 只需要第 1、3、4、6 节,每节几行即可;L 写完整。走 S 快速通道时不写本文件。
7
7
  缺陷修复在 B4 的草稿中追加一节「## 修复方案(根因 + 修复方式)」,前面留一个空行与上一节隔开,保留原方案正文;文档头更新为当前修复分支和本次日期,上一版由 artifact.mjs finalize --kind plan 归档。
8
8
  标题里的「方案」同时覆盖功能开发与缺陷修复两种用法。 -->
9
9
 
10
- ## 1. 需求要点与验收标准
10
+ ## 1. 方案依据
11
11
 
12
- - 要点:{{一句话说明要做什么、为谁做}}
13
- - 验收标准:
14
- 1. {{可验证的行为,例如「调用 X 接口传 Y,返回 Z」}}
15
- 2. {{异常 / 边界行为}}
16
- - 不在本次范围:{{明确排除的部分}}
17
- - 已确认的决定:{{F3 澄清中定下的业务规则与取舍,标注用户决定 / 按推荐采纳}}
12
+ - 需求文档:{{requirement.md 的 cite 与版本;目标、范围、验收与业务决定以该文档为准,不复制维护}}
13
+ - 实现思路:{{如何实现已确认的需求;不在这里重新定义业务范围}}
18
14
 
19
15
  ## 2. 现状
20
16
 
@@ -56,10 +52,10 @@
56
52
 
57
53
  ## 6. 验证计划
58
54
 
59
- - 单元测试:{{覆盖哪些验收标准}}
55
+ - 单元测试:{{引用 requirement.md 的 AC 编号,说明测试如何覆盖,不重写验收标准}}
60
56
  - 集成 / 手工验证:{{环境、步骤、预期}}
61
57
  - 回滚方式:{{代码回滚 / 开关 / 数据回滚}}
62
58
 
63
- ## 7. 待确认问题
59
+ ## 7. 实现待办
64
60
 
65
- - [ ] {{需要用户或产品确认的问题}}
61
+ - [ ] {{尚待核实的技术事项;新增业务决定回需求澄清并更新 requirement.md}}