@rowansenne/workflow-run 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +97 -27
  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 +4 -5
  7. package/create-tech-md-doc/SKILL.md.tpl +4 -6
  8. package/dev/SKILL.md.tpl +22 -14
  9. package/dev/agents/openai.yaml +2 -0
  10. package/dev/references/bug.md +6 -3
  11. package/dev/references/clarify.md +1 -1
  12. package/dev/references/delivery-template.md +2 -2
  13. package/dev/references/delivery.md +11 -9
  14. package/dev/references/implementation.md +5 -1
  15. package/dev/references/plan-template.md +8 -12
  16. package/dev/references/planning.md +8 -4
  17. package/dev/references/preflight.md +3 -3
  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 +4 -3
  27. package/project-review/references/reporting.md +8 -8
  28. package/project-review/references/review-method.md +1 -1
  29. package/project-review/skill.json +2 -1
  30. package/workflow/SKILL.md.tpl +14 -9
  31. package/workflow/lib/artifact-finalize.mjs +156 -0
  32. package/workflow/lib/artifact-model.mjs +2 -2
  33. package/workflow/lib/code-snapshot.mjs +55 -0
  34. package/workflow/lib/meta-store.mjs +4 -2
  35. package/workflow/lib/path-match.mjs +21 -0
  36. package/workflow/lib/requirements.mjs +12 -7
  37. package/workflow/lib/run-gates.mjs +153 -0
  38. package/workflow/lib/runs.mjs +58 -14
  39. package/workflow/lib/workspace-read.mjs +3 -1
  40. package/workflow/references/architecture.md +51 -3
  41. package/workflow/references/capabilities.md +4 -2
  42. package/workflow/references/execution.md +105 -0
  43. package/workflow/references/requirements.md +15 -13
  44. package/workflow/references/runs.md +16 -11
  45. package/workflow/references/status.md +1 -0
  46. package/workflow/references/templates.md +2 -2
  47. package/workflow/scripts/artifact.mjs +39 -0
  48. package/workflow/scripts/pr-desc.mjs +2 -2
  49. package/workflow/scripts/review-handoff.mjs +59 -0
  50. package/workflow/scripts/review-scope.mjs +2 -21
  51. package/workflow/scripts/run.mjs +6 -8
  52. package/workflow/scripts/template.mjs +3 -2
  53. package/workflow/scripts/view.mjs +1 -1
  54. package/workflow/skill.json +2 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,29 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.29.0] - 2026-10-28
8
+
9
+ ### 修复
10
+ - Nacos CLI 入口按真实路径识别,支持默认软链接目录执行;多 profile 按名称集合匹配,避免静默退回基础连接;普通多 `@` 密码和环境变量凭据不再误判为 Maven 构建占位符;Oracle Thin / OCI 内嵌凭据 URL 整值脱敏。补充真实安装入口与完整读取回归验证。
11
+
12
+ ### 变更
13
+ - dev 改为显式触发:仅实际调用 `/dev` / `$dev`、点选 skill 或明确要求使用 dev / 完整开发工作流时进入;普通分析、代码修改、修复、测试和 Git 操作不再自动启动。Codex 元数据关闭隐式调用,workflow 路由与安装写入的项目说明同步收紧,保留已授权任务的阶段续接;更新正负分流用例与安装验证。
14
+
15
+ ### 新增
16
+ - 完整开发 / 修复新增独立 `requirement.md`:F3 / B3 澄清收尾时先生成目标、范围、AC 验收与业务决定,`plan.md` 只维护实现设计并绑定需求版本。支持模板、归档、视图、统计、审查交接和 PR 引用;需求变更使旧方案及下游证据失效,快速通道仍不落盘,不自动拆分历史文档。
17
+ - 独立 `nacos-config` skill:从 application / bootstrap YAML 或 properties 定位连接与占位符,按 Namespace / Group / Data ID 只读获取 Nacos 配置、查询参数或子树,支持命名连接、用户名密码 / token 鉴权、版本 1 / 2 / 3 协议、来源标注和敏感值脱敏。接入安装、升级保留、凭据忽略、workflow 路由及 dev / project-review 的按需核对。
18
+
19
+ ### 文档
20
+ - 同步 README、架构图解、全量安装教程与内部架构 / 能力边界,说明 9 个 skills、Nacos 独立调用、安装时的 DocNexus 策略、数据位置与模板来源;校正旧版本、层数和安装说明。测试与发布 CI 增加 YAML 测试依赖安装步骤。
21
+
22
+ ## [0.28.0] - 2026-10-26
23
+
24
+ ### 变更
25
+ - 完整 dev 的关键转换加入程序门禁:方案确认绑定正文版本,进入实现、审查与交付须有对应证据,严重遗留风险须逐项明确接受。
26
+ - 验证和审查绑定执行前的 Git/工作区快照,交付选择绑定本轮报告 hash 和版本;代码、基线、需求事实或报告变化时拒绝复用旧证据。
27
+ - 新增 artifact finalize / resume / abort:知识模板检查后统一发布、归档、更新索引与运行证据;meta.json 保存中断待办,重试不重复升版本,原 wiki 页面记录自动保留。
28
+ - 新增 review-handoff,从已保存的需求事实、范围和验证结果生成交接 JSON;独立审查返回报告草稿、结构化问题与逐文件覆盖,由主 agent 收尾。快速通道和首次创建运行时机保持不变。
29
+
7
30
  ## [0.27.0] - 2026-10-24
8
31
 
9
32
  ### 变更
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/
@@ -620,9 +682,11 @@ workflow-run/docs/requirements/<需求名>/<项目名>/
620
682
  * **随代码提交和独立文档仓库两种用法的结构完全一样**,切换时文件不用挪。一个需求横跨多个服务时,各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`:随代码提交时不用配置,取 git 远端仓库名(没有远端用目录名),第一次落盘时自动写进去;独立文档仓库时由 `docs-repo` 配置。
621
683
  * 旧版本随代码提交时没有 `<项目名>/` 这一层;`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`(被 git 跟踪的用 `git mv`,保留历史),结尾列出迁移了哪些需求,改动由你提交。目标里已有同名文件的需求不动,并提示手动处理;`doctor` 也会提示还没迁移的需求。
622
684
  * **需求名由你定**:dev 在 Step 0 先确定工作分支,再查询绑定并确认需求名,给不出名字或说不清这次要做什么时不会进入开发流程(默认值按分支名生成;也可以选已有的需求,例如修 bug 的新分支挂到原需求下)。从 `/workflow` 完整链路开始时同样先问(只问名字,第一次落盘时才 `bind`);S 快速通道也问,但不绑定、不落盘。确定后,同一分支上的各 skill 都写到这个目录,不再问。一个需求可以绑定多个分支。
623
- * 路径由 `workflow/scripts/requirement.mjs path <种类>` 给出,每种产物文件名固定,目录里只留最新版,引用不会失效;版本号记在 `meta.json` 的 `versions`。已有旧版时,上一版先复制到 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`(不提交),新版直接覆盖写入;skill 会列出归档的文件,请你确认后自己删除。上一版发布过 wiki 时,新版沿用同一个页面。
685
+ * 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。底层 requirement path / sync 仍保留,新的正式流程统一走 finalize。
624
686
  * 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
625
687
 
688
+ 完整 dev 的关键阶段由程序校验:M / L 方案确认绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;快速通道和首次创建运行的时机保持不变。协议见 [execution.md](workflow/references/execution.md)。
689
+
626
690
  **独立文档仓库(可选)**:不想让产物进代码仓库、或一个需求横跨多个服务时,装好 skills 后在项目根运行一条命令:
627
691
 
628
692
  ```bash
@@ -680,6 +744,10 @@ workflow-run(安装器仓库)/
680
744
  │ │ ├── requirement-read.mjs # 需求目录与元信息读取
681
745
  │ │ ├── requirements.mjs # 绑定、版本归档与索引同步
682
746
  │ │ ├── runs.mjs # 运行状态、阶段与完成校验
747
+ │ │ ├── run-gates.mjs # 方案、验证、审查与交付门禁
748
+ │ │ ├── code-snapshot.mjs # 代码内容摘要,绑定验证和审查证据
749
+ │ │ ├── artifact-finalize.mjs # 可恢复的产物收尾
750
+ │ │ ├── path-match.mjs # 共享范围匹配
683
751
  │ │ ├── meta-store.mjs # 写锁与原子存储
684
752
  │ │ ├── document-model.mjs # 标题、章节、表格等纯文本模型
685
753
  │ │ ├── artifact-model.mjs # 产物类型、元信息、审查与交付解析
@@ -693,6 +761,8 @@ workflow-run(安装器仓库)/
693
761
  │ ├── scripts/pr-desc.mjs # 按本分支产物生成 PR / MR 描述
694
762
  │ ├── scripts/template.mjs # 修改 / 创建模板:草稿 → 校验与影响 → 保存
695
763
  │ ├── scripts/tables.mjs # 找出改动涉及的数据库表
764
+ │ ├── scripts/artifact.mjs # 草稿收尾 / 中断恢复 / 安全取消
765
+ │ ├── scripts/review-handoff.mjs # 自动生成审查交接与结果结构
696
766
  │ ├── scripts/requirement.mjs # 产物按需求归档:绑定需求名、落盘路径、meta.json
697
767
  │ ├── scripts/view.mjs # 项目文档视图(本地静态页面)
698
768
  │ ├── scripts/make-template.mjs # 从样例文档抽模板骨架
@@ -782,7 +852,7 @@ npx @rowansenne/workflow-run seed-templates --diff # 团队改过
782
852
 
783
853
  ## 触发准确度评估
784
854
 
785
- 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` 逐条发送,取第一个被调用的工具判断分流结果:
786
856
 
787
857
  ```
788
858
  npm run eval:triggers # 全量,每条 1 次
@@ -793,7 +863,7 @@ node scripts/eval-triggers.mjs --only dev # 只跑期望为 dev 的用例
793
863
  * 需要已登录的 `claude` CLI(终端执行 `claude` 后 `/login`);每条请求会真实调用一次模型并计费,检测到第一个工具调用即终止,不会执行任何工具。
794
864
  * 期望 `none` 表示不该触发本项目的 skill;触发了你环境里的其他 skill(如全局安装的 pdf skill)也算对。
795
865
  * 额度用尽、未登录等调用失败记为 `E`(error),不计作「没触发」,并在结尾提示结果不可信。
796
- * 结果明细写到 `tmp/evals/`。改了任何 skill 的 description 后建议重跑一次(最近一次:26 条 × 3 次,78/78)。
866
+ * 结果明细写到 `tmp/evals/`。描述改动后可运行模型分流评估;它只观察首个工具调用,不等同于流程实际执行验证。旧触发规则的历史成绩不适用于当前显式入口规则。
797
867
 
798
868
  ## 为什么这些路径
799
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
 
@@ -71,11 +72,9 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
71
72
 
72
73
  ### Step 4 — 写文件
73
74
 
74
- - 路径:运行 `node <skills>/workflow/scripts/requirement.mjs path release --branch <dev分支>`,写到输出的 `path`(`workflow-run/docs/requirements/<需求名>/<项目名>/release-doc.md`,文件名固定;已有旧版时直接写新版,上一版由脚本归档到输出的 `previous`)。规则见 `<skills>/workflow/references/requirements.md`。
75
- - 退出码 2(这个分支还没绑定需求):问用户这个需求叫什么,默认值用输出的 `suggested_name`,再 `requirement.mjs bind --name "<需求名>" --branch <dev分支>`;用户不给名字时 `bind` 按分支名生成。
76
- - `wiki_record` 非空:上一版已发布到 wiki,新版第一行原样写这条记录,重新发布时更新同一页面。
77
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`。
78
- - 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <文档路径> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
75
+ - 正式收尾:Step 4 进入 L4,先写 `workflow-run/tmp/release-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind release --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
76
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
77
+ - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
79
78
  - 再把路径和摘要告诉用户。
80
79
 
81
80
  ### Step 5 — 后续(都需要用户同意)
@@ -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 |
@@ -69,11 +69,9 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
69
69
 
70
70
  ### Step 4 — 写文件
71
71
 
72
- - 路径:运行 `node <skills>/workflow/scripts/requirement.mjs path tech --branch <dev分支>`,写到输出的 `path`(`workflow-run/docs/requirements/<需求名>/<项目名>/tech-doc.md`,文件名固定;已有旧版时直接写新版,上一版由脚本归档到输出的 `previous`)。规则见 `<skills>/workflow/references/requirements.md`。
73
- - 退出码 2(这个分支还没绑定需求):问用户这个需求叫什么,默认值用输出的 `suggested_name`,再 `requirement.mjs bind --name "<需求名>" --branch <dev分支>`;用户不给名字时 `bind` 按分支名生成。
74
- - `wiki_record` 非空:上一版已发布到 wiki,新版第一行原样写这条记录,重新发布时更新同一页面。
75
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`。
76
- - 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <文档路径> --skill create-tech-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
72
+ - 正式收尾:Step 4 进入 T4,先写 `workflow-run/tmp/tech-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind tech --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
73
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
74
+ - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
77
75
  - 再把路径和摘要告诉用户。
78
76
 
79
77
  ### Step 5 — 后续(都需要用户同意)
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,8 +34,8 @@ 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>`,补记真实完成的前置步骤。
31
- 每步完成、等待、阻塞和结束会话前 save;修复回 F5 / B4,交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md`。
37
+ 非快速通道在 F3 / B3 收尾、首次落盘需求文档前 bind,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,补记真实完成的前置步骤;首个文档为 `requirement.md`。
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
 
34
41
  ## 功能开发流程
@@ -40,30 +47,31 @@ 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) 再选择快速通道;完整流程用 `requirement.mjs path plan` 写 `plan.md` 并 lint / sync,S / M 简版、L 完整版;M / L 确认后继续。
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
 
54
- 读 [implementation.md 的 F5](references/implementation.md);小步修改、小步运行 `profile.build`,公共签名先看影响面;改动、配置清单与 SQL 脚本进入交付依据。
62
+ 读 [implementation.md 的 F5](references/implementation.md);完整流程先通过方案版本门禁,再小步修改、运行 `profile.build`,公共签名先看影响面;改动、配置清单与 SQL 脚本进入交付依据。
55
63
 
56
64
  ### F6 — 验证
57
65
 
58
- 读 [implementation.md 的 F6](references/implementation.md);执行相关测试、`profile.test` 与已配置的 lint;记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留。
66
+ 读 [implementation.md 的 F6](references/implementation.md);完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留。
59
67
 
60
68
  ### F7 — 审查、报告与用户选择
61
69
 
62
- 先读 [delivery.md 的 F7](references/delivery.md),完整流程按 project-review 第 1~7 步审查;优先独立子 agent,无则当前会话并如实署名。完整流程落报告、交用户、等修复或交付选择;内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
70
+ 先读 [delivery.md 的 F7](references/delivery.md),完整流程用 `review-handoff.mjs --id <id>` 生成交接材料,按 project-review 第 1~7 步审查;优先独立子 agent,无则当前会话并如实署名。子 agent 返回草稿与结构化结果,主 agent 用 `artifact.mjs finalize --kind review` 收尾,交用户、等修复或交付选择;内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
63
71
 
64
72
  ### F8 — 交付
65
73
 
66
- 读 [delivery.md 的 F8](references/delivery.md);完整流程取得交付选择后用 `requirement.mjs path delivery` 写 `delivery.md`、自检并汇总,快速通道仅对话交付。反馈用 `feedback.mjs add`;沉淀分类用 `resolve.mjs category dev`,详细授权、元信息与后续操作按该文执行。
74
+ 读 [delivery.md 的 F8](references/delivery.md);完整流程记录绑定本轮代码和报告的交付选择后,用 `artifact.mjs finalize --kind delivery` 收尾 `delivery.md` 并汇总,快速通道仅对话交付。反馈用 `feedback.mjs add`;沉淀分类用 `resolve.mjs category dev`,详细授权、元信息与后续操作按该文执行。
67
75
 
68
76
  ## 缺陷修复流程(`--bug`)
69
77
 
@@ -77,11 +85,11 @@ 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
 
84
- 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程通过 `requirement.mjs path plan` 归档旧版后,在原 `plan.md` 追加修复方案并更新文档头,不另建方案;M / L 确认后修复,复现测试由红变绿。
92
+ 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
85
93
 
86
94
  ### B5 — 审查与交付
87
95
 
@@ -89,7 +97,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
89
97
 
90
98
  ## Artifact Location
91
99
 
92
- 正式产物按 `<skills>/workflow/references/requirements.md` 归入 `workflow-run/docs/requirements/<需求>/<项目>/`,首次落盘前 bind;写入与归档细则见 [delivery.md 的 Artifact Location](references/delivery.md)。写完 sync,用输出的 cite 引用,lint 错误先修正。
100
+ 正式产物按 `<skills>/workflow/references/requirements.md` 归入 `workflow-run/docs/requirements/<需求>/<项目>/`,首次落盘前 bind;写入与归档细则见 [delivery.md 的 Artifact Location](references/delivery.md) 与 execution.md。正式产物统一 finalize,用输出的 cite 引用;中断先 resume。
93
101
  普通聊天的辅助文件默认放 `workflow-run/other/`,不绑定需求、不登记运行;源码、已有文件和用户指定路径沿用原规则。
94
102
 
95
103
  ## Rules
@@ -0,0 +1,2 @@
1
+ policy:
2
+ allow_implicit_invocation: false
@@ -17,14 +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 运行 `requirement.mjs bind`(未绑定时),再用 `requirement.mjs path plan` 拿路径(已有 `plan.md` 时脚本会先把上一版归档到 `workflow-run/tmp/old-artifacts/`),把根因结论与修复方式写成 `plan.md` 的「修复方案」一节**追加**在原文之后(前面留一个空行与上一节隔开,避免标题被上一行吞掉)——保留已有方案正文、不另建文件;同时将文档头的分支更新为当前修复分支、日期更新为本次日期,不能只在追加的章节里写新分支,否则产物索引仍会归到旧分支。没有 `plan.md` 时按模板建一份,只填适用的节。写完 `requirement.mjs sync <方案路径>` 更新 `meta.json`,运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检,再运行 `artifacts.mjs --branch <当前修复分支>` 确认 `latest.plan` 指向这份方案;M / L 等用户确认修复方式后再改代码,S 可以在同一轮确认并开始。修复中规模变化时说明变化依据,按新规模继续。
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 沉淀时根因是首要候选。
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 沉淀候选。