agentic-flow-kit 0.9.1 → 0.9.4
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/README.md +93 -93
- package/modules/hosts/claude/commands/wf-build.md +3 -3
- package/modules/hosts/claude/commands/wf-design.md +3 -3
- package/modules/hosts/claude/commands/wf-new-task.md +13 -2
- package/modules/hosts/claude/commands/wf-plan.md +3 -3
- package/modules/hosts/claude/commands/wf-sync-hosts.md +1 -1
- package/modules/hosts/claude/commands/wf-test.md +1 -1
- package/modules/hosts/codex/commands/wf-build.md +3 -3
- package/modules/hosts/codex/commands/wf-design.md +3 -3
- package/modules/hosts/codex/commands/wf-new-task.md +13 -2
- package/modules/hosts/codex/commands/wf-plan.md +3 -3
- package/modules/hosts/codex/commands/wf-sync-hosts.md +1 -1
- package/modules/hosts/codex/commands/wf-test.md +1 -1
- package/modules/hosts/cursor/commands/wf-build.md +3 -3
- package/modules/hosts/cursor/commands/wf-design.md +3 -3
- package/modules/hosts/cursor/commands/wf-new-task.md +13 -2
- package/modules/hosts/cursor/commands/wf-plan.md +3 -3
- package/modules/hosts/cursor/commands/wf-sync-hosts.md +1 -1
- package/modules/hosts/cursor/commands/wf-test.md +1 -1
- package/modules/hosts/opencode/commands/wf-build.md +3 -3
- package/modules/hosts/opencode/commands/wf-design.md +3 -3
- package/modules/hosts/opencode/commands/wf-new-task.md +13 -2
- package/modules/hosts/opencode/commands/wf-plan.md +3 -3
- package/modules/hosts/opencode/commands/wf-sync-hosts.md +1 -1
- package/modules/hosts/opencode/commands/wf-test.md +1 -1
- package/modules/hosts/trae/commands/wf-build.md +3 -3
- package/modules/hosts/trae/commands/wf-design.md +3 -3
- package/modules/hosts/trae/commands/wf-new-task.md +13 -2
- package/modules/hosts/trae/commands/wf-plan.md +3 -3
- package/modules/hosts/trae/commands/wf-sync-hosts.md +1 -1
- package/modules/hosts/trae/commands/wf-test.md +1 -1
- package/modules/hosts/trae/rules/project-workflow.md +1 -1
- package/package.json +45 -45
- package/templates/_agents/commands/build.md +2 -2
- package/templates/_agents/commands/design.md +1 -1
- package/templates/_agents/commands/plan.md +3 -3
- package/templates/_agents/commands/sync-hosts.md +1 -1
- package/templates/_agents/scripts/check-lane-surface.mjs +20 -7
- package/templates/_agents/scripts/check-lane-surface.test.mjs +24 -2
- package/templates/_agents/scripts/check-ledger-invariant.mjs +135 -0
- package/templates/_agents/scripts/check-ledger-invariant.test.mjs +161 -0
- package/templates/_agents/scripts/check-loop.mjs +58 -15
- package/templates/_agents/scripts/check-loop.test.mjs +100 -2
- package/templates/_agents/scripts/confirm-doc.mjs +19 -7
- package/templates/_agents/scripts/confirm-doc.test.mjs +31 -0
- package/templates/_agents/scripts/fill-intent.mjs +1 -1
- package/templates/_agents/scripts/fill-plan.test.mjs +4 -3
- package/templates/_agents/scripts/gate-checklist.mjs +1 -0
- package/templates/_agents/scripts/gen-workflow-metrics.mjs +75 -5
- package/templates/_agents/scripts/gen-workflow-metrics.test.mjs +104 -2
- package/templates/_agents/scripts/policy.mjs +1 -0
- package/templates/_agents/scripts/pre-push.test.mjs +8 -1
- package/templates/_agents/scripts/solidify-task.test.mjs +5 -2
- package/templates/_agents/scripts/stage-gates.mjs +29 -6
- package/templates/_agents/scripts/trust-mode.test.mjs +110 -0
- package/templates/_agents/scripts-test-exempt.txt +10 -0
- package/templates/_githooks/pre-commit +12 -0
- package/templates/workflow/README.md +3 -2
- package/templates/workflow/plans/_TEMPLATE.md +1 -1
|
@@ -13,8 +13,8 @@ description: Build 阶段 · 起 plan + 实现代码 + 自验(两道确认门
|
|
|
13
13
|
1. 确认同名入口文档(approved intent 或已确认的 incident)+ spec(若 L2/L3)均已确认;否则回上一阶段(fill/confirm 未过即拒)
|
|
14
14
|
2. 起草 plan:
|
|
15
15
|
- 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
16
|
-
- L2/L3 按 4
|
|
17
|
-
- L1
|
|
16
|
+
- L2/L3 按 4 节填写:改动方案 / 任务拆解(每个任务有判据) / 执行顺序 / 验证计划(与 fill-plan.mjs 单源一致)
|
|
17
|
+
- L1 使用 Quick-Plan 极简三节:改动方案 / 约束与风险(原 Spec 核心) / 验证计划;多文件多步骤时可补任务拆解/执行顺序
|
|
18
18
|
3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28
|
|
19
19
|
**确认落态唯一入口**(2026-09-27 起):用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」(draft→approved / approved→done;对话内明确确认后 AI 可 `--delegated "<原话>"` 代录,台账如实记 source/quote——**逐件调用 + 逐件原话**(一次一份,build.md「逐件确认」口径;多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力))。check-loop 15 如实口径:缺记录/指纹不配对 → hard-block 拦截;伪造台账本地不可机器防,留痕供事后对质;done 内容绑定(2026-09-28 起)——关单编辑(勾验/回填)先于 done 确认、confirm-doc 是最后一次写入,此后修订走 superseded 或新 intent。
|
|
20
20
|
4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
|
|
@@ -26,7 +26,7 @@ description: Build 阶段 · 起 plan + 实现代码 + 自验(两道确认门
|
|
|
26
26
|
- 列改动文件清单(读后改 vs 新建)
|
|
27
27
|
- 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
|
|
28
28
|
- **owned 文件同步**:kit.owned 列表文件(AGENTS.md / workflow 模板等)sync 不动,须列「手动同步装副本」步骤(见 incidents/2026-09-25-wf-runtime 复盘)
|
|
29
|
-
- 标注触达红线(对照根 `AGENTS.md
|
|
29
|
+
- 标注触达红线(对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有))
|
|
30
30
|
6. 停下,等用户确认改动清单
|
|
31
31
|
|
|
32
32
|
### 实现
|
|
@@ -4,20 +4,20 @@ description: Design 阶段 · 起 spec(L2/L3 强制,L1 可省略直接进 bu
|
|
|
4
4
|
|
|
5
5
|
# Design · 起 spec
|
|
6
6
|
|
|
7
|
-
> L2/L3 强制;L1
|
|
7
|
+
> L2/L3 强制;L1 走快车道(直接跳 `next: build.md` 起草 Quick-Plan)。
|
|
8
8
|
|
|
9
9
|
## 执行
|
|
10
10
|
|
|
11
11
|
1. 确认同名入口文档已批准:新需求为 approved intent,修复为已确认的 incident 草稿;否则拒绝,分别回 `plan.md` / `maintain.md`(2026-09-30 起机器强制:fill-spec / confirm-doc 对前置未过直接拒绝 exit 2、不落盘不记账)
|
|
12
12
|
2. 级别判断(对照 AGENTS.md 第 3 条):
|
|
13
|
-
- **L1**(实现级改动,未命中 L2/L3)→
|
|
13
|
+
- **L1**(实现级改动,未命中 L2/L3)→ 走快车道,省略 spec,直接跳 `next: build.md` 起草 Quick-Plan
|
|
14
14
|
- **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
|
|
15
15
|
- **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
|
|
16
16
|
3. 起草 spec:
|
|
17
17
|
- **填空工具先跑**:`node .agents/scripts/fill-spec.mjs --level <L1|L2|L3> --topic <主题> --output workflow/specs/<date>-<主题>.md`——输出含 frontmatter 5 字段 + 5 节正文(功能行为/数据流/系统改动/约束遵守映射/风险评估)的草稿;AI 据此填实
|
|
18
18
|
- 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
19
19
|
- 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
|
|
20
|
-
- 约束映射必须对照根 `AGENTS.md
|
|
20
|
+
- 约束映射必须对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)与改动域目录级 `AGENTS.md`(如有)逐条说明如何满足
|
|
21
21
|
- 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
|
|
22
22
|
- **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单(字段清单)」还是「选择器/弹窗」,禁止自行推定交互形态
|
|
23
23
|
4. 起草后停下,输出草稿全文给用户过目
|
|
@@ -18,11 +18,22 @@ description: AI-Native 闭环总入口 · 6 阶段路由(新需求 → plan /
|
|
|
18
18
|
| **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
|
|
19
19
|
| **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
|
|
20
20
|
|
|
21
|
+
## 风险定级(第 0 步,先定级再路由)
|
|
22
|
+
|
|
23
|
+
动工前先按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
|
|
24
|
+
|
|
25
|
+
| 泳道 | 级别 | 确认与审计口径 |
|
|
26
|
+
|------|------|---------------|
|
|
27
|
+
| **协作道**(敏捷优先,审计异步补) | L0 例行 / L1 实现级 | L0 直接 commit,豁免 intent;L1 快车道(intent 一句话确认 + 极简 plan)即动工。独立复核不设同步前置,check-loop 与事后 review 兜底;确认/代录可 `--batch` 批量(仅 L0/L1) |
|
|
28
|
+
| **防御道**(严谨优先,确认同步拦) | L2 规则/契约 / L3 数据与运行时结构 | 同步确认门:spec 确认通过方可起草 plan,plan 确认后方可动手;L3 加新会话独立复核,未确认不放行 |
|
|
29
|
+
|
|
30
|
+
> 定级结果落 intent frontmatter `risk_level`(=级别,`fill-intent.mjs` 自动写入,机器选道用);协作道勾触达红线会被 check-loop 判「红线判低」hard 拦(就高升级 L2/L3 并补同名 spec)。
|
|
31
|
+
|
|
21
32
|
## 路由判断
|
|
22
33
|
|
|
23
34
|
- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
|
|
24
35
|
- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
|
|
25
|
-
|
|
36
|
+
- L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
|
|
26
37
|
- L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
|
|
27
38
|
- 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
|
|
28
39
|
- **改完代码要验证**:直接进 `test.md`(验证通过即关单;L1 到此结束)
|
|
@@ -34,7 +45,7 @@ description: AI-Native 闭环总入口 · 6 阶段路由(新需求 → plan /
|
|
|
34
45
|
| 级别 | 改什么 | 流程 |
|
|
35
46
|
|------|--------|------|
|
|
36
47
|
| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
|
|
37
|
-
| L1 | **实现级改动**(未命中 L2/L3) |
|
|
48
|
+
| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) $\rightarrow$ 实现 $\rightarrow$ 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账 |
|
|
38
49
|
| L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
|
|
39
50
|
| L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
|
|
40
51
|
|
|
@@ -13,11 +13,11 @@ description: Plan 阶段 · 立 intent(AI 起草、用户确认;本阶段不
|
|
|
13
13
|
1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next(L1 → `build.md`,L2/L3 → `design.md`)
|
|
14
14
|
2. 否则起草新 intent:
|
|
15
15
|
- **先检索同类**:`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用(防重复立项 / 重复踩坑)
|
|
16
|
-
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+
|
|
16
|
+
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+ 9 节(背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核)的草稿;AI 据此填实,模板与节标题机器保证不出错
|
|
17
17
|
- 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
|
|
18
18
|
- frontmatter 填 `模块:`(词表见 `.agents/workflow-modules.txt`,新建文档必填,check-loop 会警告)
|
|
19
|
-
- 按
|
|
20
|
-
- 红线勾选对照根 `AGENTS.md
|
|
19
|
+
- 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准(L1 微改动可省非目标/约束两节,不硬填)
|
|
20
|
+
- 红线勾选对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有);**没触及就全不勾**,不要硬填
|
|
21
21
|
3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
|
|
22
22
|
4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
|
|
23
23
|
|
|
@@ -9,7 +9,7 @@ description: 跨宿主适配层同步(正文段 sha 比对 + 用户拍板 +
|
|
|
9
9
|
|
|
10
10
|
## 何时跑
|
|
11
11
|
|
|
12
|
-
- 改 `templates/_agents/commands/*.md` 正文后(
|
|
12
|
+
- 改 `templates/_agents/commands/*.md` 正文后(11 个 commands 文件)
|
|
13
13
|
- 改 `templates/_agents/roles/*.md` 正文后(3 个 roles 文件)
|
|
14
14
|
- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
|
|
15
15
|
- 不跑:仅改 frontmatter;改 trae 钩子/规则;改包源其他文件
|
|
@@ -55,7 +55,7 @@ node bin/flow-kit.mjs doctor # §6.5 delegations + §6.6 o
|
|
|
55
55
|
- 失败项已修复并复测通过
|
|
56
56
|
- **关单**(日常闭环点,不依赖是否上 prod):
|
|
57
57
|
- 关单前一键过门:`node .agents/scripts/verify.mjs`(npm test + check-loop 固定编排,任一失败非零退出,非绿不关单)
|
|
58
|
-
- 新需求:逐条勾验入口 intent
|
|
58
|
+
- 新需求:逐条勾验入口 intent「验收标准」,每条补「证据:」(例如:粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA),intent $\rightarrow$ done;同名 spec/Quick-Plan(若有)仍 approved $\rightarrow$ done。**注意:勾选但缺证据会被 check-loop 拦截(hard-block)**
|
|
59
59
|
- **approved 留痕提交**(2026-09-30 起):done 确认前确认**本次关单文档**的 approved 态已进 git 历史(越早越好——approved 后即应提交;若尚未,先补提交再 done;门为逐份校验,三件套均关单时逐份各自满足)——confirm-doc 的 done 前置门硬校验(历史未出现「状态: approved」→ 拒绝落账);done 后再提交 done 态与其余改动
|
|
60
60
|
**确认落态唯一入口**(2026-09-27 起):用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」(draft→approved / approved→done;对话内明确确认后 AI 可 `--delegated "<原话>"` 代录,台账如实记 source/quote——**逐件调用 + 逐件原话**(一次一份,build.md「逐件确认」口径;多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力))。check-loop 15 如实口径:缺记录/指纹不配对 → hard-block 拦截;伪造台账本地不可机器防,留痕供事后对质;done 内容绑定(2026-09-28 起)——**关单编辑(勾验/回填确认结果)先于 done 确认、confirm-doc 是最后一次写入**,此后修订走 superseded 或新 intent。
|
|
61
61
|
- 修复:防复发验证已落地,incident → closed(经确认门 confirm-doc:open→fixed / fixed→closed 两跳、无单跳;2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认,口径同 done 内容绑定)
|
|
@@ -14,8 +14,8 @@ description: Build 阶段 · 起 plan + 实现代码 + 自验(两道确认门
|
|
|
14
14
|
1. 确认同名入口文档(approved intent 或已确认的 incident)+ spec(若 L2/L3)均已确认;否则回上一阶段(fill/confirm 未过即拒)
|
|
15
15
|
2. 起草 plan:
|
|
16
16
|
- 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
17
|
-
- L2/L3 按 4
|
|
18
|
-
- L1
|
|
17
|
+
- L2/L3 按 4 节填写:改动方案 / 任务拆解(每个任务有判据) / 执行顺序 / 验证计划(与 fill-plan.mjs 单源一致)
|
|
18
|
+
- L1 使用 Quick-Plan 极简三节:改动方案 / 约束与风险(原 Spec 核心) / 验证计划;多文件多步骤时可补任务拆解/执行顺序
|
|
19
19
|
3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28
|
|
20
20
|
**确认落态唯一入口**(2026-09-27 起):用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」(draft→approved / approved→done;对话内明确确认后 AI 可 `--delegated "<原话>"` 代录,台账如实记 source/quote——**逐件调用 + 逐件原话**(一次一份,build.md「逐件确认」口径;多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力))。check-loop 15 如实口径:缺记录/指纹不配对 → hard-block 拦截;伪造台账本地不可机器防,留痕供事后对质;done 内容绑定(2026-09-28 起)——关单编辑(勾验/回填)先于 done 确认、confirm-doc 是最后一次写入,此后修订走 superseded 或新 intent。
|
|
21
21
|
4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
|
|
@@ -27,7 +27,7 @@ description: Build 阶段 · 起 plan + 实现代码 + 自验(两道确认门
|
|
|
27
27
|
- 列改动文件清单(读后改 vs 新建)
|
|
28
28
|
- 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
|
|
29
29
|
- **owned 文件同步**:kit.owned 列表文件(AGENTS.md / workflow 模板等)sync 不动,须列「手动同步装副本」步骤(见 incidents/2026-09-25-wf-runtime 复盘)
|
|
30
|
-
- 标注触达红线(对照根 `AGENTS.md
|
|
30
|
+
- 标注触达红线(对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有))
|
|
31
31
|
6. 停下,等用户确认改动清单
|
|
32
32
|
|
|
33
33
|
### 实现
|
|
@@ -5,20 +5,20 @@ description: Design 阶段 · 起 spec(L2/L3 强制,L1 可省略直接进 wf
|
|
|
5
5
|
|
|
6
6
|
# Design · 起 spec
|
|
7
7
|
|
|
8
|
-
> L2/L3 强制;L1
|
|
8
|
+
> L2/L3 强制;L1 走快车道(直接跳 `next: build.md` 起草 Quick-Plan)。
|
|
9
9
|
|
|
10
10
|
## 执行
|
|
11
11
|
|
|
12
12
|
1. 确认同名入口文档已批准:新需求为 approved intent,修复为已确认的 incident 草稿;否则拒绝,分别回 `plan.md` / `maintain.md`(2026-09-30 起机器强制:fill-spec / confirm-doc 对前置未过直接拒绝 exit 2、不落盘不记账)
|
|
13
13
|
2. 级别判断(对照 AGENTS.md 第 3 条):
|
|
14
|
-
- **L1**(实现级改动,未命中 L2/L3)→
|
|
14
|
+
- **L1**(实现级改动,未命中 L2/L3)→ 走快车道,省略 spec,直接跳 `next: build.md` 起草 Quick-Plan
|
|
15
15
|
- **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
|
|
16
16
|
- **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
|
|
17
17
|
3. 起草 spec:
|
|
18
18
|
- **填空工具先跑**:`node .agents/scripts/fill-spec.mjs --level <L1|L2|L3> --topic <主题> --output workflow/specs/<date>-<主题>.md`——输出含 frontmatter 5 字段 + 5 节正文(功能行为/数据流/系统改动/约束遵守映射/风险评估)的草稿;AI 据此填实
|
|
19
19
|
- 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
20
20
|
- 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
|
|
21
|
-
- 约束映射必须对照根 `AGENTS.md
|
|
21
|
+
- 约束映射必须对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)与改动域目录级 `AGENTS.md`(如有)逐条说明如何满足
|
|
22
22
|
- 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
|
|
23
23
|
- **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单(字段清单)」还是「选择器/弹窗」,禁止自行推定交互形态
|
|
24
24
|
4. 起草后停下,输出草稿全文给用户过目
|
|
@@ -19,11 +19,22 @@ description: 闭环总入口 · 路由判断(新需求 → wf-plan / 修复
|
|
|
19
19
|
| **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
|
|
20
20
|
| **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
|
|
21
21
|
|
|
22
|
+
## 风险定级(第 0 步,先定级再路由)
|
|
23
|
+
|
|
24
|
+
动工前先按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
|
|
25
|
+
|
|
26
|
+
| 泳道 | 级别 | 确认与审计口径 |
|
|
27
|
+
|------|------|---------------|
|
|
28
|
+
| **协作道**(敏捷优先,审计异步补) | L0 例行 / L1 实现级 | L0 直接 commit,豁免 intent;L1 快车道(intent 一句话确认 + 极简 plan)即动工。独立复核不设同步前置,check-loop 与事后 review 兜底;确认/代录可 `--batch` 批量(仅 L0/L1) |
|
|
29
|
+
| **防御道**(严谨优先,确认同步拦) | L2 规则/契约 / L3 数据与运行时结构 | 同步确认门:spec 确认通过方可起草 plan,plan 确认后方可动手;L3 加新会话独立复核,未确认不放行 |
|
|
30
|
+
|
|
31
|
+
> 定级结果落 intent frontmatter `risk_level`(=级别,`fill-intent.mjs` 自动写入,机器选道用);协作道勾触达红线会被 check-loop 判「红线判低」hard 拦(就高升级 L2/L3 并补同名 spec)。
|
|
32
|
+
|
|
22
33
|
## 路由判断
|
|
23
34
|
|
|
24
35
|
- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
|
|
25
36
|
- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
|
|
26
|
-
|
|
37
|
+
- L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 Quick-Plan → `test.md`
|
|
27
38
|
- L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
|
|
28
39
|
- 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
|
|
29
40
|
- **改完代码要验证**:直接进 `test.md`(验证通过即关单;L1 到此结束)
|
|
@@ -35,7 +46,7 @@ description: 闭环总入口 · 路由判断(新需求 → wf-plan / 修复
|
|
|
35
46
|
| 级别 | 改什么 | 流程 |
|
|
36
47
|
|------|--------|------|
|
|
37
48
|
| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
|
|
38
|
-
| L1 | **实现级改动**(未命中 L2/L3) |
|
|
49
|
+
| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) $\rightarrow$ 实现 $\rightarrow$ 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账 |
|
|
39
50
|
| L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
|
|
40
51
|
| L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
|
|
41
52
|
|
|
@@ -14,11 +14,11 @@ description: Plan 阶段 · 立 intent(AI 起草、用户确认;本阶段不
|
|
|
14
14
|
1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next(L1 → `build.md`,L2/L3 → `design.md`)
|
|
15
15
|
2. 否则起草新 intent:
|
|
16
16
|
- **先检索同类**:`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用(防重复立项 / 重复踩坑)
|
|
17
|
-
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+
|
|
17
|
+
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+ 9 节(背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核)的草稿;AI 据此填实,模板与节标题机器保证不出错
|
|
18
18
|
- 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
|
|
19
19
|
- frontmatter 填 `模块:`(词表见 `.agents/workflow-modules.txt`,新建文档必填,check-loop 会警告)
|
|
20
|
-
- 按
|
|
21
|
-
- 红线勾选对照根 `AGENTS.md
|
|
20
|
+
- 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准(L1 微改动可省非目标/约束两节,不硬填)
|
|
21
|
+
- 红线勾选对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有);**没触及就全不勾**,不要硬填
|
|
22
22
|
3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
|
|
23
23
|
4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
|
|
24
24
|
|
|
@@ -10,7 +10,7 @@ description: 跨宿主适配层同步(正文段 sha 比对 + 用户拍板 +
|
|
|
10
10
|
|
|
11
11
|
## 何时跑
|
|
12
12
|
|
|
13
|
-
- 改 `templates/_agents/commands/*.md` 正文后(
|
|
13
|
+
- 改 `templates/_agents/commands/*.md` 正文后(11 个 commands 文件)
|
|
14
14
|
- 改 `templates/_agents/roles/*.md` 正文后(3 个 roles 文件)
|
|
15
15
|
- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
|
|
16
16
|
- 不跑:仅改 frontmatter;改 trae 钩子/规则;改包源其他文件
|
|
@@ -56,7 +56,7 @@ node bin/flow-kit.mjs doctor # §6.5 delegations + §6.6 o
|
|
|
56
56
|
- 失败项已修复并复测通过
|
|
57
57
|
- **关单**(日常闭环点,不依赖是否上 prod):
|
|
58
58
|
- 关单前一键过门:`node .agents/scripts/verify.mjs`(npm test + check-loop 固定编排,任一失败非零退出,非绿不关单)
|
|
59
|
-
- 新需求:逐条勾验入口 intent
|
|
59
|
+
- 新需求:逐条勾验入口 intent「验收标准」,每条补「证据:」(例如:粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA),intent $\rightarrow$ done;同名 spec/Quick-Plan(若有)仍 approved $\rightarrow$ done。**注意:勾选但缺证据会被 check-loop 拦截(hard-block)**
|
|
60
60
|
- **approved 留痕提交**(2026-09-30 起):done 确认前确认**本次关单文档**的 approved 态已进 git 历史(越早越好——approved 后即应提交;若尚未,先补提交再 done;门为逐份校验,三件套均关单时逐份各自满足)——confirm-doc 的 done 前置门硬校验(历史未出现「状态: approved」→ 拒绝落账);done 后再提交 done 态与其余改动
|
|
61
61
|
**确认落态唯一入口**(2026-09-27 起):用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」(draft→approved / approved→done;对话内明确确认后 AI 可 `--delegated "<原话>"` 代录,台账如实记 source/quote——**逐件调用 + 逐件原话**(一次一份,build.md「逐件确认」口径;多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力))。check-loop 15 如实口径:缺记录/指纹不配对 → hard-block 拦截;伪造台账本地不可机器防,留痕供事后对质;done 内容绑定(2026-09-28 起)——**关单编辑(勾验/回填确认结果)先于 done 确认、confirm-doc 是最后一次写入**,此后修订走 superseded 或新 intent。
|
|
62
62
|
- 修复:防复发验证已落地,incident → closed(经确认门 confirm-doc:open→fixed / fixed→closed 两跳、无单跳;2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认,口径同 done 内容绑定)
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
alwaysApply: true
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
本项目工作流唯一权威是根目录 `AGENTS.md`:开工前必须完整读取并严格遵循(任务流程 /
|
|
5
|
+
本项目工作流唯一权威是根目录 `AGENTS.md`:开工前必须完整读取并严格遵循(任务流程 / 通用约束与红线 / 目录级规则 / 运行时与验证标准),本规则只做入口指针,不复制内容。
|
|
6
6
|
|
|
7
7
|
- 规则加载是惰性的:根 `AGENTS.md` 常驻;目录级 `AGENTS.md`(如有,如 `backend/AGENTS.md`、`frontend/AGENTS.md`)只在该目录文件被读取或被提及时才生效——动对应目录前先主动读,别凭记忆。
|
|
8
8
|
- 终端环境差异(shell 可用性 / 退出码取法 /「命令不存在 ⇒ 假绿」)见 `.agents/notes/runtime-env.md` §1。
|
package/package.json
CHANGED
|
@@ -1,45 +1,45 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "agentic-flow-kit",
|
|
3
|
-
"version": "0.9.
|
|
4
|
-
"description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎(阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算)+ workflow 文档闭环 + wiki 知识库,装完自包含、零运行时依赖",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"scripts": {
|
|
7
|
-
"test": "node src/run-tests.mjs",
|
|
8
|
-
"prepack": "node -e \"require('fs').rmSync('templates/_agents/cache',{recursive:true,force:true})\" && node scripts/check-pack-eol.mjs"
|
|
9
|
-
},
|
|
10
|
-
"bin": {
|
|
11
|
-
"flow-kit": "bin/flow-kit.mjs"
|
|
12
|
-
},
|
|
13
|
-
"files": [
|
|
14
|
-
"bin",
|
|
15
|
-
"src",
|
|
16
|
-
"templates",
|
|
17
|
-
"modules",
|
|
18
|
-
"README.md",
|
|
19
|
-
"!templates/_agents/cache",
|
|
20
|
-
"!templates/_agents/cache/**"
|
|
21
|
-
],
|
|
22
|
-
"engines": {
|
|
23
|
-
"node": ">=18.0.0"
|
|
24
|
-
},
|
|
25
|
-
"keywords": [
|
|
26
|
-
"ai-native",
|
|
27
|
-
"workflow",
|
|
28
|
-
"agent",
|
|
29
|
-
"scaffold",
|
|
30
|
-
"cli",
|
|
31
|
-
"wiki",
|
|
32
|
-
"check-loop",
|
|
33
|
-
"closed-loop"
|
|
34
|
-
],
|
|
35
|
-
"license": "MIT",
|
|
36
|
-
"private": false,
|
|
37
|
-
"repository": {
|
|
38
|
-
"type": "git",
|
|
39
|
-
"url": "git+https://github.com/zerosloney/agentic-flow-kit.git"
|
|
40
|
-
},
|
|
41
|
-
"bugs": {
|
|
42
|
-
"url": "https://github.com/zerosloney/agentic-flow-kit/issues"
|
|
43
|
-
},
|
|
44
|
-
"homepage": "https://github.com/zerosloney/agentic-flow-kit#readme"
|
|
45
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "agentic-flow-kit",
|
|
3
|
+
"version": "0.9.4",
|
|
4
|
+
"description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎(阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算)+ workflow 文档闭环 + wiki 知识库,装完自包含、零运行时依赖",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"test": "node src/run-tests.mjs",
|
|
8
|
+
"prepack": "node -e \"require('fs').rmSync('templates/_agents/cache',{recursive:true,force:true})\" && node scripts/check-pack-eol.mjs"
|
|
9
|
+
},
|
|
10
|
+
"bin": {
|
|
11
|
+
"flow-kit": "bin/flow-kit.mjs"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"bin",
|
|
15
|
+
"src",
|
|
16
|
+
"templates",
|
|
17
|
+
"modules",
|
|
18
|
+
"README.md",
|
|
19
|
+
"!templates/_agents/cache",
|
|
20
|
+
"!templates/_agents/cache/**"
|
|
21
|
+
],
|
|
22
|
+
"engines": {
|
|
23
|
+
"node": ">=18.0.0"
|
|
24
|
+
},
|
|
25
|
+
"keywords": [
|
|
26
|
+
"ai-native",
|
|
27
|
+
"workflow",
|
|
28
|
+
"agent",
|
|
29
|
+
"scaffold",
|
|
30
|
+
"cli",
|
|
31
|
+
"wiki",
|
|
32
|
+
"check-loop",
|
|
33
|
+
"closed-loop"
|
|
34
|
+
],
|
|
35
|
+
"license": "MIT",
|
|
36
|
+
"private": false,
|
|
37
|
+
"repository": {
|
|
38
|
+
"type": "git",
|
|
39
|
+
"url": "git+https://github.com/zerosloney/agentic-flow-kit.git"
|
|
40
|
+
},
|
|
41
|
+
"bugs": {
|
|
42
|
+
"url": "https://github.com/zerosloney/agentic-flow-kit/issues"
|
|
43
|
+
},
|
|
44
|
+
"homepage": "https://github.com/zerosloney/agentic-flow-kit#readme"
|
|
45
|
+
}
|
|
@@ -28,7 +28,7 @@ next: .agents/commands/test.md
|
|
|
28
28
|
1. 确认同名入口文档(approved intent 或已确认的 incident)+ spec(若 L2/L3)均已确认;否则回上一阶段(fill/confirm 未过即拒)
|
|
29
29
|
2. 起草 plan:
|
|
30
30
|
- 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
31
|
-
- L2/L3 按 4
|
|
31
|
+
- L2/L3 按 4 节填写:改动方案 / 任务拆解(每个任务有判据) / 执行顺序 / 验证计划(与 fill-plan.mjs 单源一致)
|
|
32
32
|
- L1 使用 Quick-Plan 极简三节:改动方案 / 约束与风险(原 Spec 核心) / 验证计划;多文件多步骤时可补任务拆解/执行顺序
|
|
33
33
|
3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28
|
|
34
34
|
**确认落态唯一入口**(2026-09-27 起):用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」(draft→approved / approved→done;对话内明确确认后 AI 可 `--delegated "<原话>"` 代录,台账如实记 source/quote——**逐件调用 + 逐件原话**(一次一份,build.md「逐件确认」口径;多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力))。check-loop 15 如实口径:缺记录/指纹不配对 → hard-block 拦截;伪造台账本地不可机器防,留痕供事后对质;done 内容绑定(2026-09-28 起)——关单编辑(勾验/回填)先于 done 确认、confirm-doc 是最后一次写入,此后修订走 superseded 或新 intent。
|
|
@@ -41,7 +41,7 @@ next: .agents/commands/test.md
|
|
|
41
41
|
- 列改动文件清单(读后改 vs 新建)
|
|
42
42
|
- 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
|
|
43
43
|
- **owned 文件同步**:kit.owned 列表文件(AGENTS.md / workflow 模板等)sync 不动,须列「手动同步装副本」步骤(见 incidents/2026-09-25-wf-runtime 复盘)
|
|
44
|
-
- 标注触达红线(对照根 `AGENTS.md
|
|
44
|
+
- 标注触达红线(对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有))
|
|
45
45
|
6. 停下,等用户确认改动清单
|
|
46
46
|
|
|
47
47
|
### 实现
|
|
@@ -31,7 +31,7 @@ next: .agents/commands/build.md
|
|
|
31
31
|
- **填空工具先跑**:`node .agents/scripts/fill-spec.mjs --level <L1|L2|L3> --topic <主题> --output workflow/specs/<date>-<主题>.md`——输出含 frontmatter 5 字段 + 5 节正文(功能行为/数据流/系统改动/约束遵守映射/风险评估)的草稿;AI 据此填实
|
|
32
32
|
- 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
|
|
33
33
|
- 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
|
|
34
|
-
- 约束映射必须对照根 `AGENTS.md
|
|
34
|
+
- 约束映射必须对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)与改动域目录级 `AGENTS.md`(如有)逐条说明如何满足
|
|
35
35
|
- 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
|
|
36
36
|
- **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单(字段清单)」还是「选择器/弹窗」,禁止自行推定交互形态
|
|
37
37
|
4. 起草后停下,输出草稿全文给用户过目
|
|
@@ -21,11 +21,11 @@ next: L1 → .agents/commands/build.md (起草 Quick-Plan) ;L2/L3 → .agents/
|
|
|
21
21
|
1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next(L1 → `build.md`,L2/L3 → `design.md`)
|
|
22
22
|
2. 否则起草新 intent:
|
|
23
23
|
- **先检索同类**:`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收,新 intent 引用(防重复立项 / 重复踩坑)
|
|
24
|
-
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+
|
|
24
|
+
- **填空工具先跑**:`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段(含 risk_level)+ 9 节(背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核)的草稿;AI 据此填实,模板与节标题机器保证不出错
|
|
25
25
|
- 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
|
|
26
26
|
- frontmatter 填 `模块:`(词表见 `.agents/workflow-modules.txt`,新建文档必填,check-loop 会警告)
|
|
27
|
-
- 按
|
|
28
|
-
- 红线勾选对照根 `AGENTS.md
|
|
27
|
+
- 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准(L1 微改动可省非目标/约束两节,不硬填)
|
|
28
|
+
- 红线勾选对照根 `AGENTS.md` 红线/约束相关节(如「项目适配区」「门禁与提交」)+ 改动域目录级 `AGENTS.md`(如有);**没触及就全不勾**,不要硬填
|
|
29
29
|
3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
|
|
30
30
|
4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
|
|
31
31
|
|
|
@@ -22,7 +22,7 @@ next: .agents/commands/build.md(漂移属 build 改权威源未同步导致的
|
|
|
22
22
|
|
|
23
23
|
## 何时跑
|
|
24
24
|
|
|
25
|
-
- 改 `templates/_agents/commands/*.md` 正文后(
|
|
25
|
+
- 改 `templates/_agents/commands/*.md` 正文后(11 个 commands 文件)
|
|
26
26
|
- 改 `templates/_agents/roles/*.md` 正文后(3 个 roles 文件)
|
|
27
27
|
- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
|
|
28
28
|
- 不跑:仅改 frontmatter;改 trae 钩子/规则;改包源其他文件
|
|
@@ -23,6 +23,8 @@
|
|
|
23
23
|
import fs from 'node:fs';
|
|
24
24
|
import path from 'node:path';
|
|
25
25
|
import { spawnSync } from 'node:child_process';
|
|
26
|
+
import { laneOfEntry, laneOfDoc } from './stage-gates.mjs';
|
|
27
|
+
import { loadKitPolicy } from './policy.mjs';
|
|
26
28
|
|
|
27
29
|
const argv = process.argv.slice(2);
|
|
28
30
|
const argOf = (k) => {
|
|
@@ -44,6 +46,8 @@ const STAGED = stagedArg
|
|
|
44
46
|
: gitOut(ROOT, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']).split(/\r?\n/).filter(Boolean);
|
|
45
47
|
|
|
46
48
|
const isExperiment = /^experiment\//.test(BRANCH);
|
|
49
|
+
// 泳道协议锚(单源 policy.mjs):无 kit.json 的测试夹具回落 v1(无键=双字段协议从未生效,单字段判)
|
|
50
|
+
const RISK_LEVEL_SINCE = loadKitPolicy(ROOT).riskLevelSince;
|
|
47
51
|
|
|
48
52
|
// frontmatter 读取(CRLF 容忍;口径同 check-loop fmGet:--- 包夹、键行前缀匹配)
|
|
49
53
|
const fmOf = (file) => {
|
|
@@ -88,7 +92,10 @@ const loadPatterns = () => {
|
|
|
88
92
|
return pats;
|
|
89
93
|
};
|
|
90
94
|
|
|
91
|
-
// 活跃入口收集(incident≡intent 等价;日期键 intent=日期 / incident
|
|
95
|
+
// 活跃入口收集(incident≡intent 等价;日期键 intent=日期 / incident=发现)。
|
|
96
|
+
// 泳道单源(2026-10-02 caliber-convergence 方案 C 分歧双严):intent 走 laneOfEntry(双字段三态,
|
|
97
|
+
// 协议锚 policy.riskLevelSince),其余走 laneOfDoc(级别单字段)——suspect(缺失/非法/分歧)不计
|
|
98
|
+
// high(不作豁免依据)、计入拦截集(消息按 suspect 给「两字段对齐」指引)。
|
|
92
99
|
const ACTIVE = {
|
|
93
100
|
intent: new Set(['draft', 'approved']),
|
|
94
101
|
incident: new Set(['open', 'fixed']),
|
|
@@ -102,7 +109,10 @@ const collectActive = () => {
|
|
|
102
109
|
if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
|
|
103
110
|
const fm = fmOf(path.join(dirPath, f));
|
|
104
111
|
if (!ACTIVE[kind].has(fm['状态'] || '')) continue;
|
|
105
|
-
|
|
112
|
+
const lane = kind === 'intent'
|
|
113
|
+
? laneOfEntry(fm['级别'] || '', fm['risk_level'] || '', RISK_LEVEL_SINCE, fm['日期'] || '')
|
|
114
|
+
: laneOfDoc(fm['级别'] || '');
|
|
115
|
+
out.push({ rel: `workflow/${dir}/${f}`, base: f.replace(/\.md$/, ''), level: fm['级别'] || '', risk: fm['risk_level'] || '', lane, date: fm[dateKey] || '', kind });
|
|
106
116
|
}
|
|
107
117
|
}
|
|
108
118
|
return out;
|
|
@@ -116,16 +126,19 @@ const patterns = loadPatterns();
|
|
|
116
126
|
const hits = patterns.length ? STAGED.filter((p) => patterns.some((re) => re.test(p))) : [];
|
|
117
127
|
if (hits.length) {
|
|
118
128
|
const active = collectActive();
|
|
119
|
-
const hasHigh = active.some((e) => e.
|
|
129
|
+
const hasHigh = active.some((e) => e.lane === 'high');
|
|
120
130
|
if (!hasHigh) {
|
|
121
|
-
const low = active.filter((e) => e.
|
|
131
|
+
const low = active.filter((e) => e.lane !== 'high'); // low + suspect 均拦(suspect 不作豁免依据)
|
|
122
132
|
if (low.length) {
|
|
123
133
|
const newest = [...low].sort((a, b) => (b.date || '').localeCompare(a.date || '') || b.rel.localeCompare(a.rel))[0];
|
|
134
|
+
const fixVerb = newest.lane === 'suspect'
|
|
135
|
+
? '① 对齐该入口「级别」与「risk_level」两字段至一致的 L2/L3(fill-intent 双写口径;现两值缺失/非法/分歧)并补同名 spec(.agents/commands/design.md)'
|
|
136
|
+
: '① 升级该入口「级别」与「risk_level」两字段至 L2/L3 并补同名 spec(.agents/commands/design.md)';
|
|
124
137
|
const text = [
|
|
125
|
-
`[触达面判低] 暂存命中 L2
|
|
138
|
+
`[触达面判低] 暂存命中 L2 触达面,但活跃入口无泳道 high(存在 low/suspect):`,
|
|
126
139
|
` 命中: ${hits.join(' ')}`,
|
|
127
|
-
` 关联入口: ${newest.rel}
|
|
128
|
-
` 修法(三选一):
|
|
140
|
+
` 关联入口: ${newest.rel}(级别 ${newest.level || '缺失'}/risk_level ${newest.risk || '缺失'}→ 泳道 ${newest.lane}${newest.date ? `,${newest.date}` : ''};活跃非 high 共 ${low.length} 件)`,
|
|
141
|
+
` 修法(三选一): ${fixVerb}`,
|
|
129
142
|
` ② 该入口已完成则关单(done)或显式放弃(superseded/cancelled)——不留活跃残留`,
|
|
130
143
|
` ③ 面清单误配则修 .agents/lane-surfaces.txt`,
|
|
131
144
|
].join('\n');
|
|
@@ -133,12 +133,34 @@ const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
|
|
|
133
133
|
check('incident 等价:fixed L1 算活跃低级入口 → 阻断',
|
|
134
134
|
r.code === 1 && r.out.includes('[触达面判低]') && r.out.includes('incidents/2026-09-30-inc.md'), r.out);
|
|
135
135
|
}
|
|
136
|
-
// ---
|
|
136
|
+
// --- 级别缺失:suspect 拦截(方案 C:不能自证 high 即拦,消息给两字段对齐指引)---
|
|
137
137
|
{
|
|
138
138
|
const d = mkfix();
|
|
139
139
|
base(d, { level: '', status: 'draft' });
|
|
140
140
|
const r = run(d, { staged: ['templates/t.md'] });
|
|
141
|
-
check('
|
|
141
|
+
check('级别缺失 → 泳道 suspect 拦断且消息含两字段对齐指引',
|
|
142
|
+
r.code === 1 && r.out.includes('suspect') && r.out.includes('对齐'), r.out);
|
|
143
|
+
}
|
|
144
|
+
// --- 方案 C:级别与 risk_level 分歧 → suspect 拦截(两字段协议期)---
|
|
145
|
+
{
|
|
146
|
+
const d = mkfix();
|
|
147
|
+
w(d, '.agents/lane-surfaces.txt', '^templates/\n');
|
|
148
|
+
w(d, '.agents/kit.json', JSON.stringify({ policyVersion: 2 }));
|
|
149
|
+
w(d, 'workflow/intents/2026-10-02-divergent.md',
|
|
150
|
+
intent('x', '状态: approved\n级别: L2\nrisk_level: L1\n日期: 2026-10-02\n模块: pipeline'));
|
|
151
|
+
const r = run(d, { staged: ['templates/t.md'] });
|
|
152
|
+
check('分歧(L2/L1)→ suspect 拦断(不作豁免依据)',
|
|
153
|
+
r.code === 1 && r.out.includes('suspect') && r.out.includes('2026-10-02-divergent'), r.out);
|
|
154
|
+
}
|
|
155
|
+
// --- 方案 C:两字段一致 high → 豁免(对照)---
|
|
156
|
+
{
|
|
157
|
+
const d = mkfix();
|
|
158
|
+
w(d, '.agents/lane-surfaces.txt', '^templates/\n');
|
|
159
|
+
w(d, '.agents/kit.json', JSON.stringify({ policyVersion: 2 }));
|
|
160
|
+
w(d, 'workflow/intents/2026-10-02-aligned.md',
|
|
161
|
+
intent('x', '状态: approved\n级别: L2\nrisk_level: L2\n日期: 2026-10-02\n模块: pipeline'));
|
|
162
|
+
const r = run(d, { staged: ['templates/t.md'] });
|
|
163
|
+
check('两字段一致 L2 → 豁免放行', r.code === 0 && !r.out.includes('触达面判低'), r.out);
|
|
142
164
|
}
|
|
143
165
|
// --- 平台边界:CRLF frontmatter ---
|
|
144
166
|
{
|