@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.
- package/CHANGELOG.md +20 -0
- package/README.md +88 -26
- package/bin/lib/artifact-context.mjs +2 -0
- package/bin/lib/doctor.mjs +1 -1
- package/bin/lib/install.mjs +1 -1
- package/create-release-md-doc/SKILL.md.tpl +1 -0
- package/create-tech-md-doc/SKILL.md.tpl +1 -1
- package/dev/SKILL.md.tpl +15 -7
- package/dev/agents/openai.yaml +2 -0
- package/dev/references/bug.md +4 -3
- package/dev/references/clarify.md +1 -1
- package/dev/references/delivery-template.md +1 -1
- package/dev/references/delivery.md +4 -4
- package/dev/references/implementation.md +1 -1
- package/dev/references/plan-template.md +7 -11
- package/dev/references/planning.md +7 -3
- package/dev/references/preflight.md +1 -1
- package/dev/references/requirement-template.md +32 -0
- package/dev/skill.json +10 -2
- package/nacos-config/SKILL.md.tpl +42 -0
- package/nacos-config/package.json +7 -0
- package/nacos-config/references/connection.md +47 -0
- package/nacos-config/scripts/config.mjs +288 -0
- package/nacos-config/skill.json +9 -0
- package/package.json +6 -2
- package/project-review/SKILL.md.tpl +1 -0
- package/project-review/references/review-method.md +1 -1
- package/project-review/skill.json +2 -1
- package/workflow/SKILL.md.tpl +13 -9
- package/workflow/lib/artifact-finalize.mjs +26 -12
- package/workflow/lib/artifact-model.mjs +2 -2
- package/workflow/lib/code-snapshot.mjs +8 -2
- package/workflow/lib/run-gates.mjs +41 -24
- package/workflow/lib/runs.mjs +8 -7
- package/workflow/references/architecture.md +41 -3
- package/workflow/references/capabilities.md +3 -1
- package/workflow/references/execution.md +13 -3
- package/workflow/references/requirements.md +4 -1
- package/workflow/references/runs.md +11 -8
- 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/review-handoff.mjs +5 -4
- package/workflow/scripts/template.mjs +3 -2
- package/workflow/skill.json +2 -1
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
状态和需求绑定、产物索引统一保存在 `workflow-run/docs/requirements/<需求>/<项目>/meta.json` 的 `runs` 对象中,以运行 id 区分。每次运行有自己的分支、kind、规模、阶段、步骤状态、上下文、历史、revision 和完成时间;同一需求跨分支不会共用一个全局阶段。
|
|
4
4
|
|
|
5
|
+
本文是用户显式启动工作流后的状态协议,不是普通分析、代码修改或 Git 操作的入口。dev 仅由 `/dev` / `$dev`、点选 skill 或明确要求 dev / 完整开发工作流启动;新会话读取旧 runs 不构成恢复授权。已授权同一任务可按保存阶段续接;用户只要求分析或提交代码时,仅处理该请求,不重启流程或自行 save / complete。
|
|
6
|
+
|
|
5
7
|
**快速通道不 start、不 save、不 bind**,仍然只写既有运行反馈。`show` 只读,无绑定或旧需求没有 runs 时返回空列表,不创建目录,不根据文档存在推断“已完成”。
|
|
6
8
|
|
|
7
9
|
## 命令与状态
|
|
@@ -28,8 +30,8 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
28
30
|
|
|
29
31
|
| kind | 步骤 | 首次创建时机 |
|
|
30
32
|
|---|---|---|
|
|
31
|
-
| `feature` | Step0、F1~F8 |
|
|
32
|
-
| `bug` | Step0、B1~B5 |
|
|
33
|
+
| `feature` | Step0、F1~F8 | F3 收尾确定不走快速通道并 bind 后,先写 requirement.md |
|
|
34
|
+
| `bug` | Step0、B1~B5 | B3 收尾确定不走快速通道并 bind 后,先写 requirement.md |
|
|
33
35
|
| `review` | R1~R7(project-review 第 1~7 步) | 独立审查需要落盘且绑定需求后;dev 内部审查不另开运行 |
|
|
34
36
|
| `tech` | T0~T4(技术方案 Step 0~4) | 确定需求和分支、绑定后 |
|
|
35
37
|
| `release` | L0~L4(上线方案 Step 0~4) | 确定需求和分支、绑定后 |
|
|
@@ -37,21 +39,20 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
37
39
|
|
|
38
40
|
“已完成”表示**本次运行范围已交付**,不是整个需求已经上线。dev 完成后,用户选择的技术方案、上线方案、wiki 发布是同一个 meta.json 中的新运行,不把已完成的 dev 改回未完成。提交、推送和知识沉淀仍按既有授权规则处理,不因 completed 自动执行;这些可选后续动作不阻止已完成的技能交付标记完成。
|
|
39
41
|
|
|
40
|
-
关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)
|
|
42
|
+
关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)。完整流程从需求文档开始记录;方案绑定需求 hash/版本,方案确认绑定方案版本,验证和审查绑定代码快照,交付选择绑定本轮报告。
|
|
41
43
|
|
|
42
44
|
## 写 checkpoint
|
|
43
45
|
|
|
44
|
-
完整 dev
|
|
46
|
+
完整 dev 开始记录前已经完成的前置步骤,要把对话中确认的摘要补入第一份 checkpoint;没有实际完成的步骤不能补成 completed。例如 F3 收尾准备写需求文档时:
|
|
45
47
|
|
|
46
48
|
```json
|
|
47
49
|
{
|
|
48
|
-
"stage": "
|
|
50
|
+
"stage": "F3",
|
|
49
51
|
"status": "running",
|
|
50
52
|
"steps": {
|
|
51
53
|
"Step0": { "status": "completed" },
|
|
52
54
|
"F1": { "status": "completed" },
|
|
53
|
-
"F2": { "status": "completed" }
|
|
54
|
-
"F3": { "status": "completed", "note": "理解与验收已确认" }
|
|
55
|
+
"F2": { "status": "completed" }
|
|
55
56
|
},
|
|
56
57
|
"context": {
|
|
57
58
|
"summary": "本次要实现的行为",
|
|
@@ -66,6 +67,8 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
66
67
|
|
|
67
68
|
每完成一个步骤、发生阻塞、准备等待用户,或结束本轮会话前,save 一次;`context` 按顶层字段合并,列表字段更新时提供完整列表,不写密码、token。每一步可记录 `evidence`(命令、结果、产物路径、未验证原因)和 `note`;这些是已观察到的结果,不得用计划冒充。
|
|
68
69
|
|
|
70
|
+
F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事实来源,context 摘要与它保持一致。需求文档及方案各自独立版本、归档和展示;改需求须重新收尾依赖它的方案。历史文档不自动拆分,旧开发运行恢复时回到 F3 / B3 核实并补齐,不能用旧方案冒充需求文档。
|
|
71
|
+
|
|
69
72
|
报告必须先由 artifact.mjs finalize 收尾并登记审查证据;报告已交给用户、等待修复或交付时:
|
|
70
73
|
|
|
71
74
|
```json
|
|
@@ -86,7 +89,7 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
|
|
|
86
89
|
- 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
|
|
87
90
|
- 取消:用 cancel,input 提供 reason,不能用 complete 把取消记成完成。
|
|
88
91
|
|
|
89
|
-
交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤在 save 时就不能跳过,用户必须已选择交付,并有本运行已收尾、内容仍匹配且属于当前分支的 plan.md、review.md、delivery.md,以及有效代码与审查证据。独立审查也核对代码快照与报告收尾凭据,其他文档运行检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
|
|
92
|
+
交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤在 save 时就不能跳过,用户必须已选择交付,并有本运行已收尾、内容仍匹配且属于当前分支的 requirement.md、plan.md、review.md、delivery.md,以及有效代码与审查证据。独立审查也核对代码快照与报告收尾凭据,其他文档运行检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
|
|
90
93
|
|
|
91
94
|
complete 不接受待用户确认或 blocked 的运行。还在处理本次已承诺的交付事项时不能提前完成;可选下一步不属于本次运行范围。状态写入具有 revision 检查和短时元信息写锁;版本冲突时重新 show,核对并合并进度,不盲目重试覆盖。写入用 workflow-run/tmp/locks/ 下的短时锁目录(不落在需求目录、不会随产物提交),目录名为元信息相对路径的 SHA-256,避免长中文路径超过文件名限制。每次写入持有唯一的 PID/UUID 标记;只回收超过 30 秒且进程已退出的旧标记,非空锁目录不能删除,释放时也只删除自己的标记。mkdir 后尚未写入标记就崩溃的空目录,过期后同样自动恢复。
|
|
92
95
|
|
|
@@ -21,7 +21,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
|
|
|
21
21
|
|
|
22
22
|
## 修改模板(/workflow template)
|
|
23
23
|
|
|
24
|
-
用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `tech` / `release` / `plan` / `delivery` / `review` / `checklist`,或 `<skill>/<文件名>`;没说哪份时先 `template.mjs list` 列出来问。
|
|
24
|
+
用户要改某份模板(「技术方案模板加一节回滚」「上线方案去掉灰度那节」「审查报告的严重问题表加一列」),或要新建、按样例重做模板时,用 `template.mjs` 一路走完,不要直接编辑生效中的模板文件。`<模板>` 写别名 `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`。
|
|
@@ -31,7 +31,7 @@ DocNexus 是必装组件,知识库 `workflow-run/docnexus/library/templates/<s
|
|
|
31
31
|
- `impact`:最近几份已生成的文档按新模板会多出哪些错误(例如新的必填章节它们没有)。只影响以后生成和 lint,已有文档不会被改;
|
|
32
32
|
- `warnings`:例如没有任何必填章节;
|
|
33
33
|
- 附上草稿全文(或改动的部分)。
|
|
34
|
-
4. **用户确认后保存**:`node <skills>/workflow/scripts/template.mjs save <模板>`。它不直接写知识库,退出码 2:按输出的 `hint` 走 capture 流程把草稿写入知识库(写入要用户授权),完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份,再删除草稿。改的是带默认版本的模板(plan / delivery / review / checklist)时,知识库里的版本取代默认版本,以后升级 skills 也不会覆盖它。
|
|
34
|
+
4. **用户确认后保存**:`node <skills>/workflow/scripts/template.mjs save <模板>`。它不直接写知识库,退出码 2:按输出的 `hint` 走 capture 流程把草稿写入知识库(写入要用户授权),完成后运行 `resolve.mjs template <skill> <文件名>` 确认 `path` 指向知识库里的那份,再删除草稿。改的是带默认版本的模板(requirement / plan / delivery / review / checklist)时,知识库里的版本取代默认版本,以后升级 skills 也不会覆盖它。
|
|
35
35
|
5. 用户想撤销:DocNexus 里的模板按 timeline 恢复旧版本。
|
|
36
36
|
|
|
37
37
|
## 创建模板
|
|
@@ -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 plan|review|delivery|tech|release 和 --draft <草稿.md>');
|
|
27
|
+
if (!skill || !opts.draft) throw new Error('finalize 需要 --kind 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 { delivery, review, plan, tech, release } = view.latest;
|
|
28
|
+
const { 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 = [['方案', plan], ['交付说明', delivery], ['审查报告', review], ['技术方案', tech], ['上线方案', release]]
|
|
60
|
+
const docs = [['需求文档', 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);
|
|
@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process';
|
|
|
6
6
|
import { fileURLToPath } from 'node:url';
|
|
7
7
|
import { readRun } from '../lib/runs.mjs';
|
|
8
8
|
import { readProfile } from '../lib/project.mjs';
|
|
9
|
-
import {
|
|
9
|
+
import { snapshotReader, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
|
|
10
10
|
import { isDev, assertValidation, reviewInputs } from '../lib/run-gates.mjs';
|
|
11
11
|
import { scope } from './review-scope.mjs';
|
|
12
12
|
|
|
@@ -14,12 +14,13 @@ export function handoff(root, { branch, id, depth = '标准', capabilities = nul
|
|
|
14
14
|
const { req, run } = readRun(root, branch, id);
|
|
15
15
|
if (!['feature', 'bug', 'review'].includes(run.kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有进行中的开发/审查运行可生成交接材料');
|
|
16
16
|
if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
|
|
17
|
+
const getSnapshot = snapshotReader(root, run);
|
|
17
18
|
if (isDev(run)) {
|
|
18
19
|
if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
|
|
19
|
-
assertValidation(root, req, run);
|
|
20
|
+
assertValidation(root, req, run, undefined, getSnapshot);
|
|
20
21
|
}
|
|
21
22
|
if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
|
|
22
|
-
const snapshot =
|
|
23
|
+
const snapshot = getSnapshot();
|
|
23
24
|
const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
|
|
24
25
|
if (!reviewScope.ok) throw new Error(reviewScope.error);
|
|
25
26
|
assertSnapshot(root, run, snapshot);
|
|
@@ -28,7 +29,7 @@ export function handoff(root, { branch, id, depth = '标准', capabilities = nul
|
|
|
28
29
|
return {
|
|
29
30
|
run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
|
|
30
31
|
branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
|
|
31
|
-
plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
|
|
32
|
+
requirement_document: run.artifacts?.requirement ?? null, plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
|
|
32
33
|
validation: run.validation ?? null,
|
|
33
34
|
commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
|
|
34
35
|
capabilities,
|
|
@@ -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
|
-
// <模板>:tech | release | plan | delivery | review | checklist,或 <skill>[/<模板文件名>](如 create-tech-md-doc/template.md)
|
|
13
|
+
// <模板>: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
|
+
requirement: ['dev', 'requirement-template.md'],
|
|
28
29
|
tech: ['create-tech-md-doc', 'template.md'],
|
|
29
30
|
release: ['create-release-md-doc', 'template.md'],
|
|
30
31
|
plan: ['dev', 'plan-template.md'],
|
|
@@ -33,7 +34,7 @@ const ALIASES = {
|
|
|
33
34
|
checklist: ['project-review', 'checklist.md'],
|
|
34
35
|
};
|
|
35
36
|
// 模板 → 用它生成的产物种类(artifacts.mjs 的 KINDS),用来找已生成的文档试跑
|
|
36
|
-
const PRODUCES = { 'create-tech-md-doc/template.md': 'tech', 'create-release-md-doc/template.md': 'release', 'dev/plan-template.md': 'plan', 'dev/delivery-template.md': 'delivery', 'project-review/report.md': 'review' };
|
|
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' };
|
|
37
38
|
const SAMPLE_DOCS = 5;
|
|
38
39
|
|
|
39
40
|
const rel = (root, p) => path.relative(root, p).split(path.sep).join('/');
|