@rowansenne/workflow-run 0.29.1 → 0.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +45 -841
- package/dev/SKILL.md.tpl +8 -7
- package/dev/references/bug.md +1 -0
- package/dev/references/clarification-template.md +40 -0
- package/dev/references/clarify.md +40 -36
- package/dev/references/delivery.md +1 -1
- package/dev/references/planning.md +14 -14
- package/dev/references/preflight.md +1 -1
- package/dev/references/requirement-template.md +2 -2
- package/dev/skill.json +6 -0
- package/docs/architecture.html +628 -0
- package/docs/development.md +221 -0
- package/docs/docnexus-integration-plan.md +56 -0
- package/docs/full-install.html +491 -0
- package/docs/installation.md +211 -0
- package/docs/integrations.md +160 -0
- package/docs/team-guide.md +166 -0
- package/docs/workflows.md +129 -0
- package/package.json +4 -2
- package/workflow/SKILL.md.tpl +1 -1
- package/workflow/lib/artifact-finalize.mjs +11 -4
- package/workflow/lib/artifact-model.mjs +2 -2
- package/workflow/references/architecture.md +1 -1
- package/workflow/references/execution.md +10 -2
- package/workflow/references/requirements.md +3 -2
- package/workflow/references/runs.md +5 -5
- package/workflow/references/templates.md +2 -2
- package/workflow/scripts/artifact.mjs +1 -1
- package/workflow/scripts/pr-desc.mjs +2 -2
- package/workflow/scripts/requirement.mjs +2 -2
- package/workflow/scripts/template.mjs +3 -2
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# 工作流与命令
|
|
2
|
+
|
|
3
|
+
[返回首页](../README.md) · [安装与升级](installation.md) · [外部能力集成](integrations.md) · [团队共享、产物与模板](team-guide.md) · [维护、测试与发布](development.md)
|
|
4
|
+
|
|
5
|
+
## workflow:入口与项目画像
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
/workflow # 按请求路由到对应 skill;无具体请求时输出能力地图 + 状态
|
|
9
|
+
/workflow status # 检查项目画像、wiki、DocNexus、数据库是否可用
|
|
10
|
+
/workflow profile # 从仓库推断并经你确认后填写 workflow/profile.json
|
|
11
|
+
/workflow report # 本地效果报告(也可以直接运行 npx @rowansenne/workflow-run report)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
**效果报告**(`/workflow report` 或 `npx @rowansenne/workflow-run report [--since YYYY-MM-DD] [--all-branches] [--json]`)只读统计 `workflow-run/docs/requirements/` 下已落盘的产物,不上报、不另存记录,用来回答「用了以后有没有更好」。默认只看工作区;产物随特性分支提交、还没合并时加 `--all-branches`,用 git 只读扫描所有本地分支(同一路径以工作区为准)。统计内容:
|
|
15
|
+
|
|
16
|
+
* 审查:各级别发现条数、严重问题复核通过率、复审时上次问题的修复率;
|
|
17
|
+
* 交付:功能 / 缺陷、S / M / L、开工前经需求澄清确认的决定条数、带「未验证项」的交付;
|
|
18
|
+
* 知识:交付与审查的 DocNexus 沉淀率(只算真正问过沉淀的,「未询问」「无需沉淀」不计入分母;dev 内部审查不单独询问或重复计入交付沉淀)、正文引用了知识库文档的产物占比;
|
|
19
|
+
* 各分支链路:方案、交付说明、审查报告、技术方案、上线方案齐不齐,哪些文档还没发布到 wiki。
|
|
20
|
+
|
|
21
|
+
**完整流程状态与续接**:需求目录的 `meta.json` 同时保存绑定、产物索引和按运行 id 区分的 `runs`。每次运行关联分支,记录阶段、逐步完成标记、上下文、待用户决定、阻塞原因、历史与 revision;完成后保存 `status: completed` 和 `completed_at`。`/workflow status` 查看状态,`/workflow resume [运行id]` 核对后继续;`/workflow view` 展示运行与“已完成”,尚未生成 Markdown 的运行也可见。快速通道保持不绑定、不创建运行状态。完整 dev 在首次落盘前初判规模、选择完整流程并开始记录,需要清单时在 F2/B3 先生成业务场景 clarification.md 并等待产品反馈;F3/B3 技术澄清完成后收尾 requirement.md,再进入 F4/B4 的实现方案,补入此前已确认的进度;后续文档/发布用独立运行保留开发的完成记录。脚本用法见 `workflow/references/runs.md`,`sync` 不会清掉状态。
|
|
22
|
+
|
|
23
|
+
**F3 前的业务核对循环**:F1 理解需求后,在 F2 先用 `artifact.mjs finalize --kind clarification` 发布同一需求目录的 `clarification.md`,聚焦角色、正常 / 异常场景、业务规则、范围和业务验收,供你找产品核对与完善 PRD。每轮在同一清单更新答复和状态、追加新问题与反馈记录,保留编号和已确认项,自动归档旧版。业务项未明确时保持 F2 in_progress、运行为 waiting_user;业务明确并完成现状调研后进入 F3,澄清可行性、接口兼容、数据、权限、依赖等技术约束。技术问题改变业务场景时回 F2 更新清单。业务与技术约束均明确后收尾 requirement.md,再进入 F4 写方案。清单是正式产物,纳入视图和统计;没有业务待确认项且用户未要求时可省清单。
|
|
24
|
+
|
|
25
|
+
**运行反馈**(`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:
|
|
26
|
+
|
|
27
|
+
1. 团队照常用两三周;
|
|
28
|
+
2. 运行 `feedback` 汇总(或直接拿 `workflow-run/feedback/` 下的文件),按「常被跳过的步骤」「读不懂的规则」「提问太多」精简 SKILL.md,发新版本;
|
|
29
|
+
3. 各项目 `upgrade` 时清掉本项目旧版本的记录(git 历史里仍可找回),从新版本重新收集,回到第 1 步。
|
|
30
|
+
|
|
31
|
+
字段与记录规则见 `workflow/references/feedback.md`。
|
|
32
|
+
|
|
33
|
+
**PR / MR 描述**:`node <skills>/workflow/scripts/pr-desc.mjs [--branch b] [--base main] [--out 文件]` 把本分支的交付说明(做了什么、已确认的决定、改动、验证、配置 / SQL)、审查报告(结论、CRITICAL / HIGH、影响面)和相关文档路径汇总成描述;没有交付说明时退回用提交记录和改动文件列表。dev 交付后要提 PR 时会调用它;创建 PR 要你同意。
|
|
34
|
+
|
|
35
|
+
`workflow/profile.json` 是所有 skill 共用的项目事实,模板里不再写死任何公司或项目约定。缺失字段视为空,文档中对应位置写「待填写」。示例:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"main_branch": "master",
|
|
40
|
+
"build": "mvn -q -DskipTests compile",
|
|
41
|
+
"test": "mvn -q test",
|
|
42
|
+
"test_single": "mvn -q test -Dtest={target}",
|
|
43
|
+
"lint": "",
|
|
44
|
+
"config_center": "nacos",
|
|
45
|
+
"deploy": { "platform": "内部发布平台", "regions": ["华东-生产", "华南-生产", "海外-生产"] },
|
|
46
|
+
"job_annotation": "@XxlJob",
|
|
47
|
+
"data_review": true,
|
|
48
|
+
"toolchain": {
|
|
49
|
+
"java_home": "$JAVA_HOME",
|
|
50
|
+
"maven": { "settings": "$HOME/.m2/settings.xml", "repository": "/data/maven-repo" },
|
|
51
|
+
"gradle_user_home": "",
|
|
52
|
+
"node": ""
|
|
53
|
+
},
|
|
54
|
+
"env_vars": { "JAVA_HOME": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home" },
|
|
55
|
+
"notes": ["技术方案的「上线服务」与「数据链路」为必填"]
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
| 字段 | 影响 |
|
|
60
|
+
| --- | --- |
|
|
61
|
+
| `main_branch` | dev、project-review、文档类的 diff 基线 |
|
|
62
|
+
| `build` / `test` / `test_single` / `lint` | dev 的编译与测试 |
|
|
63
|
+
| `config_center` | project-review 第 10 维度(配置中心下发的 key 不算缺失)、dev 配置清单、上线方案的上线顺序与配置回滚 |
|
|
64
|
+
| `deploy` | 技术 / 上线方案「上线服务」的服务名与环境说明 |
|
|
65
|
+
| `job_annotation` | 技术方案「定时任务变更」识别任务类 |
|
|
66
|
+
| `data_review` | 是否输出技术方案模块 7 与上线方案 2.3 的库表评审块 |
|
|
67
|
+
| `toolchain` / `env_vars` | 开发环境配置:JDK(`java_home`)、Maven(`maven.settings` / `maven.repository`)、Gradle(`gradle_user_home`)、Node(`node`)的位置,以及路径里用到的变量。路径写 `$JAVA_HOME` 这类变量或本机绝对路径,`~` 展开为用户目录;**不含凭据**。构建跑不起来时 dev 用它核对 |
|
|
68
|
+
|
|
69
|
+
**开发环境配置**(`toolchain`):JDK 在哪、Maven 用哪个 `settings.xml`、本地仓库在哪个盘,这些决定构建和测试能不能跑起来,统一由画像提供,模板里不写死:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
node .agents/skills/workflow/scripts/resolve.mjs env --check # 逐个字段核对在本机是否存在
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`/workflow profile` 时会用 `infer-profile` 自动推断草稿(构建文件对应的工具、`JAVA_HOME` / `GRADLE_USER_HOME`、`~/.m2/settings.xml` 与其 `<localRepository>`、`~/.gradle`、锁定的 Node 版本),每个值带依据,经你确认后写入。Maven 的两份 `settings.xml`(全局 `$MAVEN_HOME/conf` 与用户级 `~/.m2`)**会合并、以用户级为准**,所以取用户级那份、全局的记在依据里;`<localRepository>` 也只认有效配置,注释里的示例会被忽略。路径可以写 `$JAVA_HOME`、`${VAR}`、`%VAR%`(用 `env_vars` 或本机环境展开)或 `~`。`env --check` 对每个字段给出展开后的路径、是否存在、哪个变量没配,以及本机实际的 `JAVA_HOME` / `MAVEN_HOME` / Node 目录,方便对照。**JDK、Maven 的位置每台机器不同**:团队共用一份就写 `profile.json`,个人不同就写 `profile.local.json` 的同名字段(优先),不用改团队那份;个人那份里写 `""` 表示**不用**团队那个值(用工具默认配置),不写这个键才是沿用。这一块只放路径和普通环境变量,token、密码一律不写。
|
|
76
|
+
|
|
77
|
+
**本机系统与终端**:安装 / 升级时检测一次,写进 `workflow/profile.local.json` 的 `env`(个人设置,已在 `.gitignore` 里,团队里各人各机器不同),例如 `{ "os": "windows", "shell": "powershell" }`。Windows 上区分 `pwsh`(PowerShell 7)和 `powershell`(Windows PowerShell 5.1,没有 `&&`),其他系统取 `$SHELL`。skill 写终端命令时读 `resolve.mjs env`(`profile` / `status` 的输出里也有),不再每次对话自己探测;skill 里给出的命令本身都是 `node …` / `git …`,在哪个终端都一样。换了终端或机器,重跑一次安装器即可。
|
|
78
|
+
|
|
79
|
+
## dev:开发与修 bug
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
/dev <需求描述 | PRD pageId/url> # 功能开发
|
|
83
|
+
/dev --bug <现象 | 报错 | 日志> # 缺陷修复
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**仅显式触发 dev**:实际调用 `/dev` / `$dev`、点选 dev skill,或明确说「按 dev 流程」「使用完整开发工作流」时才启动。正常分析、问答、修改代码、修 bug、重构、跑测试、提交 / 推送代码都直接处理,不自动做 dev 的开工检查、需求命名、绑定或文档落盘,也不主动询问是否开启 dev。讨论 dev 或引用命令示例不算启动;任务复杂、分支已有需求目录或旧运行也不算授权。
|
|
87
|
+
|
|
88
|
+
Codex 原生元数据 `dev/agents/openai.yaml` 设置 `policy.allow_implicit_invocation: false`;所有环境同时遵守 skill 入口规则与安装写入的项目说明。已由用户启动的同一 dev 任务可按当前阶段继续,无需每条消息重复命令;只要求分析或提交时仅处理该请求,不重启流程。升级 / 重装会更新规则,随后新建会话加载;其他宿主的原生调用策略取决于宿主支持,不能将配置校验等同于所有模型的行为保证。
|
|
89
|
+
|
|
90
|
+
* **功能开发**:开始前先确定工作分支,再确认需求名(给不出名字或说不清要做什么就不开始)→ 理解需求(可读 PRD、查 DocNexus 历史决策)→ F2 先出业务场景清单与产品核对、调研现有代码 → F3 技术澄清(基于已确认场景查证可行性与系统约束,必要取舍分轮给推荐;新业务问题回 F2;S 规模无未定决定时省提问)→ **规模判定(S / M / L 说明判定依据,不再询问确认)** → 按规模出方案(非快速通道一律落方案文档:S 简版、M 精简版、L 完整版;S 符合条件时先问是否走快速通道,走则不落盘)→ 小步实现并编译 → 补测试并运行 → 优先由独立子 agent 按 project-review 审查并落盘 `review.md`(没有子 agent 时在当前会话自查,报告注明审查者)→ 报告交给用户,等待选择「修复问题 / 交付」;修复则验证后重新审查、再次等待选择,选择交付后才将交付说明落盘到 `workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md`(带分支元信息;改动、验证结果、配置清单、未执行的 SQL),已接入 DocNexus 时交付里有值得记录的知识才问要不要沉淀(同意后以 `dev-notes` 分类写入,并把库内路径记回交付说明),没有就跳过并在元信息行写「无需沉淀」。审查和上线方案会按分支自动读取这份交付说明。
|
|
91
|
+
* **S 规模快速通道**:已发布本次正式清单或创建完整流程运行时继续完整流程,规模降为 S 也不切换。规模判定不询问用户;S 规模且不涉及配置、SQL / DDL、对外接口、表结构,也没有 F2 / F3 已确认或仍待澄清的业务决定,且本次未发布正式清单、未创建完整流程运行时,**问用户是否走快速通道**,问完等本轮答复——明确同意才走:编译、测试照常,审查在当前会话按标准清单做,**不绑定需求、不落任何产物文件**(方案 / `review.md` / 交付说明都不写;运行反馈照常记一行),对话里一次交付并注明「DocNexus:未询问(快速通道不问沉淀)」;拒绝或未明确同意就按完整流程落盘交付。实现中碰到上述任何一项或改动超过 3 个文件,先停下后续实现、重新评估规模,绑定需求并先回 F3(缺陷 B3)补需求文档,再到 F4 / B4 补方案、自检;M / L 确认方案后再继续实现、验证、审查与交付选择。缺陷修复同样适用(根因仍须在对话里写清楚)。
|
|
92
|
+
* **缺陷修复**:收集现象 → 用失败测试复现 → 用证据定位根因 → **判定规模并告知(S 规模问是否走快速通道;M / L 确认根因与修复方式后再改)** → 完整流程先生成描述现象、期望与验收的 `requirement.md`,再把根因与修复方式追加到 `plan.md`,同步更新文档头的修复分支与日期(不另建文件)→ 最小修复让测试转绿 → 审查并落盘报告(无子 agent 时当前会话自查)→ 用户选择修复或交付(修复后验证与复审;交付必须写明根因)。
|
|
93
|
+
* 审查优先用独立子 agent(期间不继续改被审代码,子 agent 只审查、写报告,不直接修复);没有子 agent 时降级为当前会话自查并把「审查者」写成当前 agent,不阻塞、也不跳过审查。遗留严重问题须说明风险并由用户明确接受,不能把选择交付写成审查通过。
|
|
94
|
+
* 守则:不写库、不改凭据、不擅自 commit / push、不装新依赖;测试没跑就写「未验证」。
|
|
95
|
+
* DocNexus 是必装组件,缺失或查询失败时先修复;wiki、CodeGraph、数据库为可选增强,所有 Skill 共用开工能力快照与失败处理规则(`workflow/references/capabilities.md`)。
|
|
96
|
+
|
|
97
|
+
## 脚本化的规则
|
|
98
|
+
|
|
99
|
+
能写成确定规则的判断都放在脚本里,SKILL.md 只说明什么时候调用,不再让 agent 按文字描述自己判断:
|
|
100
|
+
|
|
101
|
+
| 脚本(安装后在 `<skills>/` 下) | 作用 |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| `workflow/scripts/resolve.mjs template <skill> <文件名>` | 只从 DocNexus 知识库解析模板;缺失时给出导入或创建指引,不回退到包内模板 |
|
|
104
|
+
| `workflow/scripts/resolve.mjs profile` | 读项目画像,列出空字段 |
|
|
105
|
+
| `workflow/scripts/resolve.mjs env` | 本机系统与终端(安装时记录在 `profile.local.json`),写终端命令按它来 |
|
|
106
|
+
| `workflow/scripts/resolve.mjs env --check` | 核对画像里的开发环境配置(`toolchain`)在本机是否存在:每个字段给出 `resolved`(展开后)、`exists`、`unset_vars`,以及 `current`(本机实际的 `JAVA_HOME` / `MAVEN_HOME` / Node 目录)便于对照 |
|
|
107
|
+
| `workflow/scripts/docnexus.mjs <参数>` / `--node <脚本> <参数>` | 在业务项目根运行 `.docnexus/` 中的 CLI 或它的 node 脚本,知识输出到 `workflow-run/docnexus/`;Windows 上直接用 node 跑 CLI 入口,不经过 `.cmd` |
|
|
108
|
+
| `workflow/scripts/knowledge.mjs <skill> [--match 词] [--limit n] [--query 问题]` | 按 `readFrom` 的分类列出 DocNexus 文档(标题、摘要、路径,不含正文);`--query` 再在每个分类内 `recall --category`,直接使用新版按分类检索能力。必装组件不可用时退出码 2,查询失败返回非 0,不当作无匹配 |
|
|
109
|
+
| `workflow/scripts/resolve.mjs category <skill>` | 该 skill 写入 DocNexus 时的显式分类(画像 `docnexus_categories` 优先,其次 skill.json),输出 `seal_args` 与 `metadata`;未声明时退出码 1 |
|
|
110
|
+
| `workflow/lib/capabilities.mjs` | 集中探测必装 DocNexus 与可选增强;供 resolve status 输出本轮能力快照 |
|
|
111
|
+
| `workflow/scripts/resolve.mjs status` | `/workflow status` 的能力探测(不输出任何凭据) |
|
|
112
|
+
| `workflow/scripts/resolve.mjs infer-profile` | 按固定规则从构建文件、Makefile、依赖与配置文件、git 推断项目画像草稿,每个字段附依据;不写文件 |
|
|
113
|
+
| `workflow/scripts/lint-doc.mjs <文档> --skill <skill> [--facts]` | 对照当前生效的模板检查生成的文档:必填章节、残留 `{{...}}` 占位符、元信息行为错误;缺普通章节、顺序不一致为警告;列出待填写位置。`--facts` 再核对正文里的类名、文件、接口、表名:在对比分支的 diff 和代码里都找不到的记为警告(防编造) |
|
|
114
|
+
| `workflow/scripts/requirement.mjs which / bind / path / sync / pending / list / config` | 产物按需求归档(`workflow-run/docs/requirements/<需求>/<项目>/`,两种模式结构相同):查当前分支绑定的需求(没绑定时给出按分支名生成的建议名)、绑定需求名、给出本次落盘路径(不覆盖,带上一版的 wiki 记录)、重建 `meta.json`、列出所有需求;`config` 设置产物位置(文档仓库、项目名、提交提示),`pending` 看文档仓库里还没提交的产物 |
|
|
115
|
+
| `workflow/scripts/view.mjs [--out f] [--open]` | 项目文档视图(`/workflow view`、`npx @rowansenne/workflow-run view`):读需求目录里的产物,生成单个 HTML,按需求列出各阶段、审查记录(各级别数量、复核、与上次对比)、交付记录、沉淀到的知识文档,正文直接渲染;顶部「知识文档」列出每篇知识文档来自哪个需求、哪份产物;数据内嵌,只读、不联网,默认写到 `workflow-run/tmp/view/index.html` |
|
|
116
|
+
| `workflow/scripts/run.mjs show / start / save / complete / cancel` | 需求 meta.json 中的分支运行记录:恢复、checkpoint、已完成状态与时间、等待用户、修复回退、revision 冲突检查 |
|
|
117
|
+
| `workflow/scripts/artifacts.mjs [--branch b \| --all]` | 按分支汇总 `workflow-run/docs/requirements/` 下的方案、交付说明、审查报告、技术方案、上线方案及其 wiki 发布记录,给出下一步建议;分支取自文档元信息行,不另存记录。上线方案没传 `--tech` 时据此自动引用同分支的技术方案;project-review 据此对照本分支方案、识别复审 |
|
|
118
|
+
| `workflow/scripts/report.mjs [--since d] [--all-branches] [--json]` | 本地效果报告(`/workflow report`、`npx @rowansenne/workflow-run report`):审查发现与修复率、复核率、需求澄清、沉淀率、知识引用、各分支链路 |
|
|
119
|
+
| `workflow/scripts/feedback.mjs add … / summary [--json]` | 运行反馈:dev / project-review 交付后追加一行过程记录到 `workflow-run/feedback/<用户>.jsonl`;`summary` 按 skill 汇总,跳过的步骤和不清楚的规则按 SKILL.md 章节归类(`npx @rowansenne/workflow-run feedback`);`init` / `upgrade` 装了新版本时清掉本项目旧版本的记录 |
|
|
120
|
+
| `workflow/scripts/review-scope.mjs [--diff b...h \| --base b] [--exclude a,b]` / `rules <文件…>` | 审查范围:由脚本决定审哪些文件、跳过哪些(删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具产物,各带原因)、每个文件的风险级别和分批,以及按文件类型和改动内容该看审查清单的哪几节;`--base` 含未提交和未跟踪的新文件。`rules` 打印这些小节的原文和画像 `review.rules` 里匹配的项目规则。project-review 第 1、3、4 步与 dev 自审使用 |
|
|
121
|
+
| `workflow/scripts/locate.mjs <发现.json> [--diff b...h \| --base b]` | 给审查发现定位行号:按每条发现引用的原代码片段在文件里查找(精确 → 忽略空白 → 单行部分匹配),多处时优先本次改动的行,输出起止行、是否落在本次改动上;找不到的标出来要求重读代码。project-review 第 6 步复核使用 |
|
|
122
|
+
| `workflow/scripts/tables.mjs [--diff b...h \| --base b \| --files a,b]` | 找出改动涉及哪些表:实体注解(`@TableName` / `@Table`,没写表名时按类名推断)、Mapper XML 与代码里的 SQL、DDL 脚本;标出 DDL、是否在 `schema.md` 里,并给出拉表结构的命令。dev 调研 / 自检与 project-review 审 SQL / DDL 时使用 |
|
|
123
|
+
| `workflow/scripts/template.mjs list / draft / check / save <模板>` | 修改 / 创建模板(`/workflow template`):把当前模板复制成草稿(或 `--from <样例>` 抽骨架),`check` 校验格式、列出章节变化、拿最近几份已生成文档试跑 lint 看影响,`save` 给出写入 DocNexus 知识库的 capture 指引,不直接写知识库;必装组件不可用时先修复 |
|
|
124
|
+
| `workflow/scripts/pr-desc.mjs [--branch b] [--base m] [--out f]` | 按本分支产物生成 PR / MR 描述;没有交付说明时退回用 git 记录 |
|
|
125
|
+
| `database-query/scripts/query.mjs` | 执行 SQL:选连接、取密码(只通过环境变量传给客户端)、会话层只读、拦截写语句和多语句、自动补 LIMIT、超时、脱敏敏感列;支持 mysql / psql 客户端,其他 driver 退回 JDBC |
|
|
126
|
+
| `database-query/scripts/query.mjs --schema [--tables a,b] [--write]` | 按只读会话导出表结构为 Markdown;`--write` 写入 `references/schema.md` 的 `schema:begin` / `schema:end` 之间,标记外的补充说明保留;指定的表在库里不存在时标出 |
|
|
127
|
+
| `database-query/scripts/query.mjs --schema --tables a,b --indexes` | 另外列出索引(唯一与否、列顺序)和估算行数,供 dev / project-review 核对字段、索引支撑和 DDL 锁表风险 |
|
|
128
|
+
| `nacos-config/scripts/config.mjs inspect / get` | 本地定位 Nacos 连接;按显式环境、Namespace / Group / Data ID 只读获取配置,查询 key 或子树,返回脱敏属性与来源;独立运行,不创建需求状态 |
|
|
129
|
+
| `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 通道上传后补写 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rowansenne/workflow-run",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.30.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",
|
|
@@ -32,12 +32,14 @@
|
|
|
32
32
|
"create-release-md-doc",
|
|
33
33
|
"code-graph",
|
|
34
34
|
"nacos-config",
|
|
35
|
+
"docs",
|
|
35
36
|
"README.md",
|
|
36
37
|
"CHANGELOG.md"
|
|
37
38
|
],
|
|
38
39
|
"scripts": {
|
|
39
40
|
"test": "node --test \"tests/*.mjs\"",
|
|
40
|
-
"eval:triggers": "node scripts/eval-triggers.mjs"
|
|
41
|
+
"eval:triggers": "node scripts/eval-triggers.mjs",
|
|
42
|
+
"test:package": "node --test tests/test-package.mjs"
|
|
41
43
|
},
|
|
42
44
|
"devDependencies": {
|
|
43
45
|
"yaml": "^2.8.1"
|
package/workflow/SKILL.md.tpl
CHANGED
|
@@ -20,7 +20,7 @@ description: "Entry point for project workflow commands: /workflow, project prof
|
|
|
20
20
|
/workflow profile # 填写或更新项目画像
|
|
21
21
|
/workflow report # 本地效果报告(审查发现与修复率、需求澄清、沉淀与复用、各分支链路)
|
|
22
22
|
/workflow view # 项目文档视图:按需求浏览方案、交付、审查、技术 / 上线方案(本地静态页面)
|
|
23
|
-
/workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:requirement、tech、release、plan、delivery、review、checklist
|
|
23
|
+
/workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:clarification、requirement、tech、release、plan、delivery、review、checklist
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
## 能力地图(路由)
|
|
@@ -11,11 +11,12 @@ import { updateMeta } from './meta-store.mjs';
|
|
|
11
11
|
import { OLD_DIR, indexArtifacts } from './requirements.mjs';
|
|
12
12
|
|
|
13
13
|
export const ARTIFACT_TEMPLATES = {
|
|
14
|
+
clarification: ['dev', 'clarification-template.md'],
|
|
14
15
|
requirement: ['dev', 'requirement-template.md'],
|
|
15
16
|
plan: ['dev', 'plan-template.md'], review: ['project-review', 'report.md'], delivery: ['dev', 'delivery-template.md'],
|
|
16
17
|
tech: ['create-tech-md-doc', 'template.md'], release: ['create-release-md-doc', 'template.md'],
|
|
17
18
|
};
|
|
18
|
-
const allowed = { feature: ['requirement', 'plan', 'review', 'delivery'], bug: ['requirement', 'plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
|
|
19
|
+
const allowed = { feature: ['clarification', 'requirement', 'plan', 'review', 'delivery'], bug: ['clarification', 'requirement', 'plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
|
|
19
20
|
const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
|
|
20
21
|
const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
|
|
21
22
|
|
|
@@ -119,8 +120,9 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
|
|
|
119
120
|
const getSnapshot = snapshotReader(root, run);
|
|
120
121
|
// 文档收尾只能登记当前步骤,不能在一次落盘中跳到下游或替用户作确认。
|
|
121
122
|
if (Object.keys(input).some((k) => !['steps', 'status', 'waiting_for', 'reason', 'context'].includes(k))) throw new Error('收尾 checkpoint 只接受 steps / status / waiting_for / reason / context;阶段和用户选择用 run.mjs save');
|
|
122
|
-
const expectedStep = isDev(run) ? (kind === 'requirement' ? (run.kind === 'feature' ? 'F3' : 'B3') : kind === 'plan' ? (run.kind === 'feature' ? 'F4' : 'B4') : kind === 'review' ? (run.kind === 'feature' ? 'F7' : 'B5') : (run.kind === 'feature' ? 'F8' : 'B5')) : ({ review: 'R7', tech: 'T4', release: 'L4' })[run.kind];
|
|
123
|
+
const expectedStep = isDev(run) ? (kind === 'clarification' ? (run.kind === 'feature' ? 'F2' : 'B3') : kind === 'requirement' ? (run.kind === 'feature' ? 'F3' : 'B3') : kind === 'plan' ? (run.kind === 'feature' ? 'F4' : 'B4') : kind === 'review' ? (run.kind === 'feature' ? 'F7' : 'B5') : (run.kind === 'feature' ? 'F8' : 'B5')) : ({ review: 'R7', tech: 'T4', release: 'L4' })[run.kind];
|
|
123
124
|
if (run.stage !== expectedStep || Object.keys(input.steps ?? {}).some((s) => s !== expectedStep)) throw new Error(`产物应在 ${expectedStep} 收尾,只能更新该步骤`);
|
|
125
|
+
if (kind === 'clarification' && (run.steps[expectedStep].status === 'completed' || input.steps?.[expectedStep]?.status === 'completed')) throw new Error('清单发布不能代替阶段完成;保持 F2 / B3 进行中,核对后按阶段规则继续');
|
|
124
126
|
let requirement = null;
|
|
125
127
|
if (kind === 'plan') {
|
|
126
128
|
requirement = assertRequirement(root, req, run);
|
|
@@ -134,10 +136,15 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
|
|
|
134
136
|
const previous = before !== null && before !== digest ? relative(root, path.join(root, OLD_DIR, path.relative(path.join(root, 'workflow-run/docs/requirements'), req.abs), `${FILES[kind]}_v${oldVersion}.md`)) : null;
|
|
135
137
|
run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at,
|
|
136
138
|
...(requirement ? { requirement: { hash: requirement.hash, version: requirement.version } } : {}) } };
|
|
137
|
-
|
|
139
|
+
const clarificationChanged = kind === 'clarification' && current.artifacts?.clarification?.hash !== digest;
|
|
140
|
+
if (clarificationChanged || (kind === 'plan' && (current.artifacts?.plan?.hash !== digest || current.artifacts?.plan?.requirement?.hash !== requirement.hash))
|
|
138
141
|
|| (kind === 'requirement' && current.artifacts?.requirement?.hash !== digest)) {
|
|
139
142
|
run.plan_approval = null; run.implementation = null; run.validation = null; run.review = null; run.decision = null;
|
|
140
|
-
if (
|
|
143
|
+
if (clarificationChanged) {
|
|
144
|
+
// 保留正式文件与历史版本,只撤销本轮凭据,要求重新收尾需求和方案。
|
|
145
|
+
delete run.artifacts.requirement; delete run.artifacts.plan;
|
|
146
|
+
for (const step of coreSteps(run)) if (step !== expectedStep) run.steps[step] = { status: 'pending' };
|
|
147
|
+
} else if (kind === 'requirement') for (const step of coreSteps(run).slice(1)) run.steps[step] = { status: 'pending' };
|
|
141
148
|
}
|
|
142
149
|
applyCheckpoint(run, input, at, false);
|
|
143
150
|
if (kind === 'review') {
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
// 正式需求产物的统一纯模型;不扫描目录、不修改状态。
|
|
2
2
|
import { sections, section, tableRows, listItems, meta, isEmpty } from './document-model.mjs';
|
|
3
3
|
|
|
4
|
-
export const FILES = { requirement: 'requirement', plan: 'plan', delivery: 'delivery', review: 'review', tech: 'tech-doc', release: 'release-doc' };
|
|
5
|
-
export const LABELS = { requirement: '需求文档', plan: '方案', delivery: '交付说明', review: '审查报告', tech: '技术方案', release: '上线方案' };
|
|
4
|
+
export const FILES = { clarification: 'clarification', requirement: 'requirement', plan: 'plan', delivery: 'delivery', review: 'review', tech: 'tech-doc', release: 'release-doc' };
|
|
5
|
+
export const LABELS = { clarification: '澄清清单', requirement: '需求文档', plan: '方案', delivery: '交付说明', review: '审查报告', tech: '技术方案', release: '上线方案' };
|
|
6
6
|
export const KINDS = Object.keys(FILES).map((kind) => ({ kind, label: LABELS[kind] }));
|
|
7
7
|
|
|
8
8
|
// 文件名 → { kind, version };不是需求目录里的产物返回 null
|
|
@@ -84,7 +84,7 @@ view / report 读取需求工作区快照展示,不触发运行转换或远程
|
|
|
84
84
|
|
|
85
85
|
## 执行可靠性
|
|
86
86
|
|
|
87
|
-
|
|
87
|
+
完整流程在首次落盘前创建运行;需要产品核对时,在 F2 / B3 先发布偏业务场景的 clarification.md,逐轮归档、等待反馈。feature 业务明确并完成现状调研后进入 F3 技术澄清,最终在 F3 / B3 收尾 requirement.md,记录目标、范围、AC、有效决定与技术约束。清单发布不能代替阶段完成;无业务待确认项时可省清单。plan.md 保存实现设计并绑定需求 hash / 版本,需求变化使旧方案与下游证据失效;只调整设计不修改需求文档。view / report / PR 引用分别展示清单与需求文档。
|
|
88
88
|
|
|
89
89
|
关键转换由 run-gates 执行,不仅在 complete 检查。方案批准关联具体正文;验证在执行前 snapshot、执行后登记;review-handoff 从已保存事实和代码范围生成交接材料,不传实现者结论。审查结果同时返回报告草稿与结构化 findings/coverage,主 agent 统一收尾,交付选择绑定该轮代码与报告版本。
|
|
90
90
|
|
|
@@ -4,13 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
## 需求、方案与实现门禁
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
需要清单时,在 F2 / B3 初判规模、选择完整流程并 bind、start,先发布业务场景清单;无需清单时,澄清后判规模与通道,完整流程在收尾需求文档前 bind、start。快速通道仍不 bind。scope 保存审查基线和明确排除范围,缺省取需求 base/画像 main_branch 与 review.exclude:
|
|
8
8
|
|
|
9
9
|
```json
|
|
10
10
|
{"scope":{"base":"main","exclude":["unrelated/**"]}}
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>`
|
|
13
|
+
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>` 读取。清单用 dev 的 clarification-template.md,每轮复制到 tmp 修改后发布:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind clarification --draft workflow-run/tmp/clarification.md --input workflow-run/tmp/checkpoint.json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
等待业务反馈的 checkpoint 可写 `{"status":"waiting_user","waiting_for":"产品核对业务场景清单","steps":{"F2":{"status":"in_progress"}}}`(bug 改为 B3),context 记录清单引用和待反馈事项。clarification 仅在 F2 / B3 发布,不能借发布清单将该阶段标 completed;业务项解决后发布「业务已明确」的清单,完成 F2 调研,另行 save F2 completed、stage F3。F3 澄清技术约束;发现新业务问题回 F2 更新清单。业务与技术约束均明确后,在 F3 / B3 收尾需求文档:
|
|
14
20
|
|
|
15
21
|
```sh
|
|
16
22
|
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind requirement --draft workflow-run/tmp/requirement.md --input workflow-run/tmp/checkpoint.json
|
|
@@ -33,6 +39,8 @@ M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true
|
|
|
33
39
|
|
|
34
40
|
未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
|
|
35
41
|
|
|
42
|
+
业务清单内容变化时撤销本轮 requirement / plan 凭据,清除旧方案确认、实现、验证、审查与交付选择,并重置后续步骤;正式文件和历史版本保留供查阅,相同清单内容重新发布不触发该失效处理。即便需求和方案正文不变,也必须分别重新 finalize,M / L 重新取得方案确认。
|
|
43
|
+
|
|
36
44
|
需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
|
|
37
45
|
|
|
38
46
|
## 验证证据
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
```
|
|
8
8
|
workflow-run/docs/requirements/<需求名>/<项目名>/
|
|
9
9
|
├── meta.json # 运行记录 runs(阶段、步骤完成标记、等待决定、上下文、完成时间)及 需求名、绑定的分支、各产物(种类、版本、日期、wiki 发布记录、DocNexus 沉淀)
|
|
10
|
+
├── clarification.md # 业务场景清单(F2 / B3,多轮场景核对、产品答复与追加问题)
|
|
10
11
|
├── requirement.md # 需求文档(F3 / B3 收尾;目标、范围、AC 验收与澄清决定)
|
|
11
12
|
├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
|
|
12
13
|
├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才生成;S 快速通道不落盘)
|
|
@@ -43,7 +44,7 @@ node <skills>/workflow/scripts/requirement.mjs which
|
|
|
43
44
|
|
|
44
45
|
一个需求可以绑定多个分支(`bind` 在其他分支上用同一个名字即可)。
|
|
45
46
|
|
|
46
|
-
|
|
47
|
+
完整开发需要清单时,在 F2 首次落盘前 bind、start,先发布同目录的业务场景清单 clarification.md,逐轮 finalize、归档,纳入文档视图和统计;等待产品反馈时 F2 保持进行中、运行为 waiting_user。业务明确且现状调研完成后进入 F3 技术澄清,最终收尾 requirement.md 并引用清单 cite 与版本。无需清单时,完整流程在 F3 收尾需求前 bind、start;bug 在 B3 内先业务核对、后技术澄清。各产物独立版本化;S 快速通道不绑定、不落盘,需要正式清单即走完整流程。
|
|
47
48
|
|
|
48
49
|
## 运行状态
|
|
49
50
|
|
|
@@ -51,7 +52,7 @@ node <skills>/workflow/scripts/requirement.mjs which
|
|
|
51
52
|
|
|
52
53
|
## 落盘
|
|
53
54
|
|
|
54
|
-
正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <requirement|plan|delivery|review|tech|release> --draft <草稿>`
|
|
55
|
+
正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <clarification|requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验阶段、分支与知识模板,归档旧版、更新索引/版本并登记证据;clarification 在 F2 / B3,发布不能代替阶段完成;requirement 在 F3 / B3;plan 在 F4 / B4,并绑定需求版本;review 还须 packet 与结构化 result,delivery 须有效交付选择。不要直接覆盖正式文件后只 sync。
|
|
55
56
|
|
|
56
57
|
- 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
|
|
57
58
|
- 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。
|
|
@@ -30,8 +30,8 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
30
30
|
|
|
31
31
|
| kind | 步骤 | 首次创建时机 |
|
|
32
32
|
|---|---|---|
|
|
33
|
-
| `feature` | Step0、F1~F8 |
|
|
34
|
-
| `bug` | Step0、B1~B5 | B3
|
|
33
|
+
| `feature` | Step0、F1~F8 | 需要业务清单时在 F2 初判规模、选择完整流程并 bind,先发布 clarification.md;无需清单时在 F3 收尾 requirement.md 前创建 |
|
|
34
|
+
| `bug` | Step0、B1~B5 | B3 首次落盘前初判规模、选择完整流程并 bind;有清单先写 clarification.md,否则先写 requirement.md |
|
|
35
35
|
| `review` | R1~R7(project-review 第 1~7 步) | 独立审查需要落盘且绑定需求后;dev 内部审查不另开运行 |
|
|
36
36
|
| `tech` | T0~T4(技术方案 Step 0~4) | 确定需求和分支、绑定后 |
|
|
37
37
|
| `release` | L0~L4(上线方案 Step 0~4) | 确定需求和分支、绑定后 |
|
|
@@ -39,11 +39,11 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
39
39
|
|
|
40
40
|
“已完成”表示**本次运行范围已交付**,不是整个需求已经上线。dev 完成后,用户选择的技术方案、上线方案、wiki 发布是同一个 meta.json 中的新运行,不把已完成的 dev 改回未完成。提交、推送和知识沉淀仍按既有授权规则处理,不因 completed 自动执行;这些可选后续动作不阻止已完成的技能交付标记完成。
|
|
41
41
|
|
|
42
|
-
关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)
|
|
42
|
+
关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)。完整流程从首个业务场景清单或需求文档开始记录;清单在 F2 / B3 逐轮更新并保存 waiting_user;业务明确并完成调研后,feature 进入 F3 技术澄清,再收尾需求。方案绑定需求 hash/版本,方案确认绑定方案版本,验证和审查绑定代码快照,交付选择绑定本轮报告。
|
|
43
43
|
|
|
44
44
|
## 写 checkpoint
|
|
45
45
|
|
|
46
|
-
完整 dev
|
|
46
|
+
完整 dev 开始记录前已经完成的前置步骤要补入第一份 checkpoint,不能提前标完成。首次发布业务清单时 stage 为 F2,只补记 Step0、F1,F2 保持 in_progress;下面示例是无需清单、F3 准备收尾需求文档时:
|
|
47
47
|
|
|
48
48
|
```json
|
|
49
49
|
{
|
|
@@ -83,7 +83,7 @@ F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事
|
|
|
83
83
|
|
|
84
84
|
前面的 F4~F6 必须已按实际进度保存,不能为凑齐示例而直接标完成。bug 的 B5 同时包含审查与交付,报告完成等待选择时 B5 仍为 in_progress,最后交付才标完成。
|
|
85
85
|
|
|
86
|
-
- 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history
|
|
86
|
+
- 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;修复、验证和复审后再次等待选择。业务场景变化先回 F2 更新清单,再到 F3 重新收尾需求;仅技术约束变化回 F3,规模变化同时写 size。
|
|
87
87
|
- 用户明确选交付:按 execution.md 核对本轮证据,save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
|
|
88
88
|
- 等方案确认:`status: waiting_user`,waiting_for 说明待确认方案;方案已写不代表用户已同意。
|
|
89
89
|
- 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 模板来源(文档类 skill 共用)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
澄清清单、需求、技术方案、上线方案、方案、审查清单的模板由脚本判定,各 skill 不自行查找:
|
|
4
4
|
|
|
5
5
|
```
|
|
6
6
|
node <skills>/workflow/scripts/resolve.mjs template <skill> <文件名>
|
|
@@ -21,7 +21,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
|
|
|
21
21
|
|
|
22
22
|
## 修改模板(/workflow template)
|
|
23
23
|
|
|
24
|
-
用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `requirement` / `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
|
|
24
|
+
用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `clarification` / `requirement` / `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
|
|
25
25
|
|
|
26
26
|
1. **起草稿**:`node <skills>/workflow/scripts/template.mjs draft <模板>`,把当前生效的模板复制到 `workflow-run/tmp/template-draft/<skill>/<文件名>`(输出的 `draft`)。草稿已存在会沿用(上次没改完);要从当前模板重来加 `--force`。
|
|
27
27
|
- 退出码 2、`need_sample: true`:还没有这份模板,按下面「创建模板」第 1 步向用户要样例,再运行 `draft <模板> --from <样例文件>`(从 stdin 读用 `--from -`)。用户要「按这份文档重做模板」时同样用 `--from`。
|
|
@@ -24,7 +24,7 @@ export function main(argv) {
|
|
|
24
24
|
else if (action === 'abort') out = abortFinalization(root, { branch, id: opts.id });
|
|
25
25
|
else if (action === 'finalize') {
|
|
26
26
|
const [skill, template] = ARTIFACT_TEMPLATES[opts.kind] ?? [];
|
|
27
|
-
if (!skill || !opts.draft) throw new Error('finalize 需要 --kind requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
|
|
27
|
+
if (!skill || !opts.draft) throw new Error('finalize 需要 --kind clarification|requirement|plan|review|delivery|tech|release 和 --draft <草稿.md>');
|
|
28
28
|
const resolved = resolveTemplate(root, skill, template);
|
|
29
29
|
if (!resolved.ok) throw new Error(resolved.hint ?? JSON.stringify(resolved));
|
|
30
30
|
const source = fs.readFileSync(path.resolve(root, resolved.path), 'utf8');
|
|
@@ -25,7 +25,7 @@ export function buildDescription(root, branch, base, workspace = loadWorkspace(r
|
|
|
25
25
|
const view = branchView(root, branch, workspace);
|
|
26
26
|
const texts = new Map(workspace.artifacts.map((a) => [a.path, a.text]));
|
|
27
27
|
const read = (a) => a ? texts.get(a.path) : null;
|
|
28
|
-
const { requirement, delivery, review, plan, tech, release } = view.latest;
|
|
28
|
+
const { clarification, requirement, delivery, review, plan, tech, release } = view.latest;
|
|
29
29
|
const L = [];
|
|
30
30
|
const add = (title, body) => { if (body) L.push(`## ${title}`, '', body, ''); };
|
|
31
31
|
|
|
@@ -57,7 +57,7 @@ export function buildDescription(root, branch, base, workspace = loadWorkspace(r
|
|
|
57
57
|
add('影响面', keep(section(s, '影响面')));
|
|
58
58
|
}
|
|
59
59
|
|
|
60
|
-
const docs = [['需求文档', requirement], ['方案', plan], ['交付说明', delivery], ['审查报告', review], ['技术方案', tech], ['上线方案', release]]
|
|
60
|
+
const docs = [['澄清清单', clarification], ['需求文档', requirement], ['方案', plan], ['交付说明', delivery], ['审查报告', review], ['技术方案', tech], ['上线方案', release]]
|
|
61
61
|
|
|
62
62
|
.filter(([, a]) => a).map(([label, a]) => `- ${label}:\`${a.cite ?? a.path}\`${a.wiki?.url ? `(wiki:${a.wiki.url})` : a.wiki ? `(wiki pageId ${a.wiki.pageId})` : ''}`);
|
|
63
63
|
add('相关文档', docs.length ? docs.join('\n') : null);
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
// 用法(在项目根执行;--root 可指定项目根;--branch 缺省为当前 git 分支):
|
|
16
16
|
// requirement.mjs which [--branch b] # 当前分支绑定的需求;没绑定时给出建议名、最近的需求(文档仓库模式还列出其他项目的需求)
|
|
17
17
|
// requirement.mjs bind [--name <需求名>] [--branch b] [--base m] # 绑定(没有就新建);不给 --name 按分支名生成
|
|
18
|
-
// requirement.mjs path <plan|delivery|review|tech|release> [--branch b] # 本次落盘的文件路径(文件名固定;已有时上一版复制到
|
|
18
|
+
// requirement.mjs path <clarification|requirement|plan|delivery|review|tech|release> [--branch b] # 本次落盘的文件路径(文件名固定;已有时上一版复制到
|
|
19
19
|
// # workflow-run/tmp/old-artifacts/<种类>_v<N>.md,输出 previous)
|
|
20
20
|
// requirement.mjs sync [<需求目录或其中的文件> | --all] # 按目录里的文件重建 meta.json;指定了目录 / 文件时确认新版本号、输出归档了哪些上一版;
|
|
21
21
|
// # 文档仓库模式下带上提交提示
|
|
@@ -41,7 +41,7 @@ function currentBranch(root) {
|
|
|
41
41
|
}
|
|
42
42
|
|
|
43
43
|
// ------------------------------------------------------------------ CLI
|
|
44
|
-
const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | path <plan|delivery|review|tech|release> | sync [<目录|文件> | --all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--local] (通用:--root <项目根> --branch <分支>)';
|
|
44
|
+
const USAGE = '用法: requirement.mjs which | bind [--name <需求名>] | path <clarification|requirement|plan|delivery|review|tech|release> | sync [<目录|文件> | --all] | pending | list | config [--project <名>] [--commit-prompt on|off] [--local] (通用:--root <项目根> --branch <分支>)';
|
|
45
45
|
|
|
46
46
|
function main(argv) {
|
|
47
47
|
let root = process.cwd();
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
// node .agents/skills/workflow/scripts/template.mjs draft <模板> [--from <样例.md | ->] [--force]
|
|
11
11
|
// node .agents/skills/workflow/scripts/template.mjs check <模板> [--file <草稿>]
|
|
12
12
|
// node .agents/skills/workflow/scripts/template.mjs save <模板> [--file <草稿>]
|
|
13
|
-
// <模板>:requirement | tech | release | plan | delivery | review | checklist,或 <skill>[/<模板文件名>](如 create-tech-md-doc/template.md)
|
|
13
|
+
// <模板>:clarification | requirement | tech | release | plan | delivery | review | checklist,或 <skill>[/<模板文件名>](如 create-tech-md-doc/template.md)
|
|
14
14
|
// draft:把当前生效的模板复制成草稿;还没有模板(或 --from)时按样例抽骨架(make-template.mjs)。草稿已存在时不覆盖,--force 重来
|
|
15
15
|
// check:草稿本身的格式问题、与当前模板相比的章节变化、拿最近几份已生成文档按新旧模板各跑一次 lint-doc 看影响
|
|
16
16
|
// save:check 无错误后给出写入知识库的 capture 指引(写入后重新运行 resolve.mjs template 确认生效)
|
|
@@ -25,6 +25,7 @@ import { skeleton } from './make-template.mjs';
|
|
|
25
25
|
import { collect } from './artifacts.mjs';
|
|
26
26
|
|
|
27
27
|
const ALIASES = {
|
|
28
|
+
clarification: ['dev', 'clarification-template.md'],
|
|
28
29
|
requirement: ['dev', 'requirement-template.md'],
|
|
29
30
|
tech: ['create-tech-md-doc', 'template.md'],
|
|
30
31
|
release: ['create-release-md-doc', 'template.md'],
|
|
@@ -34,7 +35,7 @@ const ALIASES = {
|
|
|
34
35
|
checklist: ['project-review', 'checklist.md'],
|
|
35
36
|
};
|
|
36
37
|
// 模板 → 用它生成的产物种类(artifacts.mjs 的 KINDS),用来找已生成的文档试跑
|
|
37
|
-
const PRODUCES = { 'create-tech-md-doc/template.md': 'tech', 'create-release-md-doc/template.md': 'release', 'dev/requirement-template.md': 'requirement', 'dev/plan-template.md': 'plan', 'dev/delivery-template.md': 'delivery', 'project-review/report.md': 'review' };
|
|
38
|
+
const PRODUCES = { 'create-tech-md-doc/template.md': 'tech', 'create-release-md-doc/template.md': 'release', 'dev/clarification-template.md': 'clarification', 'dev/requirement-template.md': 'requirement', 'dev/plan-template.md': 'plan', 'dev/delivery-template.md': 'delivery', 'project-review/report.md': 'review' };
|
|
38
39
|
const SAMPLE_DOCS = 5;
|
|
39
40
|
|
|
40
41
|
const rel = (root, p) => path.relative(root, p).split(path.sep).join('/');
|