agentic-flow-kit 0.4.0 → 0.5.0

package/templates/_agents/workflows/_TEMPLATE.md

@@ -0,0 +1,74 @@
+# Workflow 编排机制 — 编排脚本 + steps 扩展点
+
+> kit 的跨宿主编排机制：`.agents/workflows/` 下的编排脚本承载编排语义（依赖分层 / 并行 / 重试 / gate / 用户确认门 / run journal），**宿主 AI 经 AGENTS.md 常驻指令自动加载并按语义执行**——有子智能体的宿主并行 fan-out，没有的顺序自做，验收不变。零宿主协议适配：机制只依赖所有宿主共有的四样本领（读 AGENTS.md、读仓库文件、跑终端命令、子智能体）。
+
+## 自动加载（AGENTS.md 常驻指令）
+
+> 多工作包编排——用户要跑编排、或 plan 执行多工作包时：读 `.agents/workflows/` 编排脚本按本文档语义执行；自定义步骤在 `steps/`。
+
+## 编排脚本（`.agents/workflows/<主题>.md`）
+
+frontmatter（`name` / `description` / `concurrency` 默认 2）+ 一张 stages 表（`human` 列可选——不用确认门的可省该列，保持 9 列）：
+
+```md
+---
+name: 并行修两域
+description: 后端+前端并行实现 → 汇聚过测试 → 部署验证（step）→ 独立评审
+concurrency: 2
+---
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| backend | — | implementer | — | 实现后端 X | src/api/** | 项目测试过 | | | 1 |
+| frontend | — | implementer | — | 改前端 Y | web/** | 构建过 | | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | npm test | | |
+| confirm-deploy | gate-all | — | — | 用户对话内确认可上 staging | — | 一句「可以」 | | 用户确认 | |
+| deploy-check | confirm-deploy | — | 部署验证 | env=staging | | 部署命令 exit 0 | | | 0 |
+| review | deploy-check | independent-reviewer | — | 评审两域改动 | | 符合 plan 与判据 | | | 0 |
+```
+
+**stage 四形态**（互斥，恰填一项）：
+
+| 形态 | 判据 | 执行 |
+|------|------|------|
+| role 派单行 | `role` 非空 | 派子智能体（`task` 目标 / `files` 授权清单 / `accept` 验收判据写进派单头 + 红线行） |
+| step 行 | `step` 非空 | 宿主 AI 读 `steps/<step>.md` 按指引执行，`task / params` 列传参 |
+| gate 行 | `gate` 非空（role/step/human 空） | 终端跑命令，非零即中止 |
+| human 确认门行 | `human` 非空（其余形态列空） | 宿主 AI **停下向用户询问**（`task` 列 = 问什么、`accept` 列 = 通过判据），通过才派下层；驳回 → 中止汇总。**不派子智能体**（机器判据层面落实「子智能体不跨确认门」，取代早前 role 行伪装确认门的写法） |
+
+**编排语义**（执行口径，全宿主同一）：`after` 空 = 第 0 层；一层全 ok 才派依赖它的下一层；层内按 `concurrency` 分批——有子智能体的宿主并行 fan-out，没有的顺序自做（验收标准不变）；失败且 `retries` > 0 → 重派（全新上下文）；重试超限 / gate 非零 / human 驳回 → 中止后续、汇总报告失败项。human 行无重试语义（retries 视作 0）。
+
+**run journal**（断点续跑与重试计量）：每个 stage 每次尝试出结果（pass / fail / blocked）即记一行；中止后重跑先看 status——已 pass 的 stage 不重跑，从就绪层续：
+
+```bash
+node .agents/scripts/wf-journal.mjs add --wf <编排名> --stage <id> --status pass --form human   # fail/blocked 同式；--form ∈ role|step|gate|human
+node .agents/scripts/wf-journal.mjs status --wf <编排名>                                        # 已完成 / 就绪（含重试就绪×N）/ 待定
+```
+
+journal 落 `.agents/cache/orchestration-runs.jsonl`（本地运行态，可丢弃；同 run 同 stage 多行按末次生效，attempt 自动计次；`--new-run` 新起一轮）。
+
+## steps 扩展点（`.agents/workflows/steps/<名>.md`）
+
+kit 定义的扩展机制：文件名即步骤名（steps 目录即注册表），项目把自己的领域动作（部署 / 迁移 / 审计上报…）注册进来，编排脚本 step 行引用即用。
+
+```md
+---
+params: env（目标环境）；timeout-min（可选，默认 10）
+---
+# 步骤 — 部署验证
+
+1. 跑终端命令：`npm run deploy -- --env <env>`，非零即步骤失败并回报 stderr 尾段
+2. 跑冒烟检查：`curl -fsS https://<env>.example.com/healthz`
+3. 回报：部署版本号 + 冒烟结果
+```
+
+- frontmatter `params`：参数约定（自由文本列明名称与含义）；调用方在编排脚本 `task / params` 列传参（`k=v`，空格分隔多个）。
+- 正文：执行指引（编号步骤）——可指使命令、子智能体、检查动作；步骤失败按编排脚本行 `retries` 重试。
+
+## 纪律（先读）
+
+- **声明随 plan 确认后方可执行**：编排脚本是 plan 任务拆解的执行器，随 plan 草稿一并全文过目。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律用 human 形态行表达，不得派子智能体代行。
+- 收敛复核：派单返回后核对 diff 与授权文件范围（与 build.md 委派约定同口径）；BLOCKER 停住待处置。
+- **run journal 三条**：① 每个 stage 每次尝试出结果即 `wf-journal.mjs add` 记一行（含重试与 human 门结论）；② 中止后重跑先 `status`——已 pass 不重跑，从就绪层续；③ 收尾可把本 run 的 status 汇总粘 `workflow/delegations.md` 留痕（聚合脚本不读 journal）。
+- 留痕：每个派单 / step stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`，口径与 agg-delegations.cjs 对齐）。
+- 解析校验先行（机器门）：`node .agents/scripts/workflows-check.mjs`——role ∈ `.agents/roles/`、step ∈ `steps/`、after 引用存在且无环、四形态恰填一项、retries/concurrency 数值合法；任一不过即拒，不执行。

package/templates/_agents/workflows/pipeline-closing.md

@@ -0,0 +1,29 @@
+---
+name: pipeline-closing
+description: 推广环节 6 阶段闭环——起草 intent + plan（双写）→ 用户对话内确认 → 按 plan 改动面实施 → 3 关静态门（source-sync-check / npm test / doctor）→ 关单留痕（intent + plan → done + docs commit）。可复用于本项目所有 L1 推广环节（新增工具 / 微改动 / 协议修补）
+concurrency: 2
+---
+# workflow — pipeline-closing（推广环节 6 阶段闭环）
+
+> 把 5 个已闭环推广环节（E/A/D/C/F/B）的标准节奏固化为可复用编排。stage 用 role 派单 / gate 终端 / human 确认门三种形态——不引新 step（`_TEMPLATE.md` 解析校验要求 `step ∈ steps/`，新增 step 留给后续项目注册）。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | human | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|-------|---------|
+| author | — | implementer | — | 起草 intent + plan（双写 fill-{intent,plan}.mjs 生成草稿 + AI 填实），状态 draft | workflow/intents/<date>-<topic>.md, workflow/plans/<date>-<topic>.md | intent frontmatter 5 字段齐 + 状态 draft + 验收标准 ≥ 5 条；plan L1 极简 2 节齐 | | | 1 |
+| gate-doc | author | — | — | — | — | — | node .agents/scripts/fill-intent.test.mjs && node .agents/scripts/fill-plan.test.mjs | | |
+| confirm | gate-doc | — | — | plan 草稿全文过目，用户对话内一句"可以" → plan 状态 draft → approved + 回填「确认与复核」节 | — | plan 状态 approved + 「确认结果：approved（YYYY-MM-DD 用户对话内确认）」 | | 用户确认（plan 确认门） | |
+| plan-commit | confirm | implementer | — | 提交 plan 立项 commit（docs(workflow)） | workflow/intents/, workflow/plans/, workflow/INDEX.md | pre-commit 钩子全过；commit message 含 plan 改动面摘要 | | | 0 |
+| build | plan-commit | implementer | — | 按 plan §改动面 执行（含双源纪律：包源改了装副本手动同步） | 见 plan | plan 改动面全部完成；双源文件 sha 一致 | | | 1 |
+| gate-sync | build | — | — | — | — | — | node .agents/scripts/source-sync-check.mjs --diff（必须 0 差异） | | |
+| gate-test | build | — | — | — | — | — | npm test（必须全绿） | | |
+| gate-doctor | build | — | — | — | — | — | node bin/flow-kit.mjs doctor（必须 0 FAIL） | | |
+| feat-commit | gate-sync,gate-test,gate-doctor | implementer | — | 提交 feat commit（feat(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 build 改动面摘要 | | | 0 |
+| closeout | feat-commit | implementer | — | 补 intent 8 条验收勾验 + plan → done + 关单 docs commit 留痕；同步 INDEX.md（如适用） | workflow/intents/<date>-<topic>.md, workflow/plans/<date>-<topic>.md, workflow/INDEX.md | intent + plan 状态均 done；8 条验收勾验含 commit SHA 证据；commit message 含关单 commit + 8 条勾验摘要 | | | 0 |
+
+**编排语义**：第 0 层 author → 第 1 层 gate-doc + confirm（confirm 为 human 确认门形态——宿主 AI 停下询问用户，不派子智能体；通过才派下层）→ 第 2 层 plan-commit → 第 3 层 build → 第 4 层 3 关静态门（并行 fan-out）→ 第 5 层 feat-commit → 第 6 层 closeout。失败且 retries > 0 → 重派（全新上下文）；gate 非零 / human 驳回 → 中止后续、汇总报告失败项。每个 stage 每次尝试出结果记 `wf-journal.mjs add`；中止续跑先 `wf-journal.mjs status --wf pipeline-closing`（已 pass 不重跑）。
+
+**纪律**（先读）：
+- 声明随 plan 确认后方可执行——本 workflow 是 plan 任务拆解的执行器；plan 草稿先经用户对话内确认。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。确认门一律 human 形态行表达（confirm 行即此），不得派子智能体代行。
+- 留痕：每个派单 stage 完成后向 `workflow/delegations.md` 委派结果表追加一行（`一次通过` / `返工×N` / `返工待修`）。
+- 解析校验先行（机器门 `node .agents/scripts/workflows-check.mjs`）：role ∈ `.agents/roles/`、after 引用存在且无环、四形态恰填一项——任一不过即拒，不执行。

package/templates/_agents/workflows/source-sync-repair.md

@@ -0,0 +1,30 @@
+---
+name: source-sync-repair
+description: 装户面双源漂移修复专项——跑 source-sync-check 看 4 类差异（缺失 / 孤儿 / 漂移 / frontmatter-only-diff）→ 按 B-b 决策方向修齐（包源 → 装副本同步）→ 重跑确认 0 差异 → 走 pipeline-closing 标准关单。基于 F 环节真实过程沉淀
+concurrency: 2
+---
+# workflow — source-sync-repair（装户面双源漂移修复）
+
+> 双源结构（`templates/_agents/` 包源 + `.agents/` 装副本）的差异修复。F 环节（2026-09-25-fix-double-source-drift）首次实测发现 5 个真实差异并闭环，本文件（custom）把修复路径固化为可复用编排。所有 stage 用 role 派单 + gate 终端两种形态——不引新 step。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | retries |
+|----|-------|------|------|---------------|---------------|-------------------|------|---------|
+| scan-diff | — | implementer | — | 跑 source-sync-check --diff（首次摸底） | .agents/scripts/source-sync-check.mjs | 输出 4 类差异报告（缺失 / 孤儿 / 漂移 / frontmatter-only-diff），无 error | | 0 |
+| classify | scan-diff | implementer | — | 按差异类型分类：缺失/漂移走 repair；孤儿走白名单扩展或装副本删除；frontmatter-only-diff 走角色契约确认 | workflow/intents/<date>-fix-double-source-drift.md | intent 立 draft + 4 段改动面（漂移修复 / 白名单 / 测试 / docs）+ 9 条验收标准 | | 0 |
+| repair | classify | implementer | — | 按 intent 改动面修漂移：包源 → 装副本同步；白名单 RENDER_OUTPUT_FILES 扩展（含 hooks/commit-check.config.json 等 init 渲染产物）；test.mjs 新增 S8/S9 场景；双源纪律（包源改了装副本手动同步） | 见 intent | source-sync-check --diff 报告漂移数减少；双源文件 sha 一致 | | 1 |
+| gate-rescan | repair | — | — | — | — | — | node .agents/scripts/source-sync-check.mjs --diff（必须 0 差异） |  |
+| sync-refresh | gate-rescan | implementer | — | 跑 flow-kit sync 刷台账（owned 哈希按盘面自愈） | .agents/kit.json | sync exit 0；doctor 报 owned 漂移已自愈 | | 0 |
+| feat-commit | sync-refresh | implementer | — | 提交 feat commit（fix(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 4 段改动面 + 白名单扩展 | | 0 |
+| closeout | feat-commit | implementer | — | 走 pipeline-closing 标准关单（intent 8 条验收勾验 + plan → done + docs commit）；如有需要新建 wiki/双源漂移修复/README.md 沉淀 | workflow/intents/, workflow/plans/, workflow/INDEX.md, wiki/双源漂移修复/README.md | intent + plan 状态均 done；9 条验收勾验含 commit SHA 证据；wiki 主题更新（如适用） | | 0 |
+
+**编排语义**：第 0 层 scan-diff → 第 1 层 classify（差异分诊）→ 第 2 层 repair（按分诊结果修漂移）→ 第 3 层 2 关静态门（gate-rescan + sync-refresh，并行 fan-out）→ 第 4 层 feat-commit → 第 5 层 closeout（复用 pipeline-closing 6 阶段闭环尾段）。失败且 retries > 0 → 重派（全新上下文）；gate-rescan 非零 → 中止后续、回到 repair 重派。
+
+**与 pipeline-closing 的关系**：source-sync-repair 是 pipeline-closing 的子集（第 3-6 层复用），不重复定义 6 阶段全流程；closeout stage 引用 pipeline-closing 的关单动作。如需完整 6 阶段闭环（含 author / gate-doc / confirm / plan-commit），直接用 pipeline-closing 即可。
+
+**白名单扩展协议**（沿用 source-sync-check.mjs 的 RENDER_OUTPUT_FILES）：init 渲染产物（`kit.json` / `settings.json` / `hooks/commit-check.config.json`）不属双源结构；新增白名单项必须同时加进 source-sync-check.mjs + test.mjs 新场景，且 gate-rescan 跑通 0 命中才认闭环。
+
+**纪律**（先读）：
+- 声明随 plan 确认后方可执行；本 workflow 修复必须先立 intent + plan（用 pipeline-closing 的 author stage 起草）。
+- 子智能体不跨确认门、不 commit / push（派单红线行：只改授权文件；缺输入或需偏离 → `BLOCKER:` 停下）。
+- 留痕：每个派单 stage 完成后向 `workflow/delegations.md` 委派结果表追加一行。
+- 解析校验先行：role ∈ `.agents/roles/`、`after` 引用存在且无环——任一不过即拒，不执行。

package/templates/_agents/workflows/steps//347/244/272/344/276/213-/351/203/250/347/275/262/351/252/214/350/257/201.md

@@ -0,0 +1,10 @@
+---
+params: env（目标环境，必填）；timeout-min（超时分钟，可选，默认 10）
+---
+# 步骤 — 部署验证（示例）
+
+> kit steps 扩展点示例：把项目领域动作注册为可被编排脚本引用的步骤。文件名即步骤名；按项目实际改写。
+
+1. 跑终端命令：`npm run deploy -- --env <env>`（工作目录 = 项目根）；非零即步骤失败，回报 stderr 尾段
+2. 跑冒烟检查：`curl -fsS https://<env>.example.com/healthz`（URL 按项目改写）；非零即步骤失败
+3. 回报：部署版本号（取 deploy 输出中的 version 行）+ 冒烟检查结果

package/templates/_agents/workflows//347/244/272/344/276/213-/345/271/266/350/241/214/345/256/236/347/216/260/350/257/204/345/256/241.md

@@ -0,0 +1,16 @@
+---
+name: 示例-并行实现评审
+description: 两域并行实现 → 汇聚过测试门 → 部署验证（step）→ 独立评审（示例，按 plan 改写后使用）
+concurrency: 2
+---
+# workflow — 示例：并行实现评审
+
+> 格式示例：三形态各一处（role 派单 / gate / step）；id / after / task 按 plan 改写；随 plan 确认后方可执行。机制口径见 `_TEMPLATE.md`。
+
+| id | after | role | step | task / params | files（授权） | accept（验收判据） | gate | retries |
+|----|-------|------|------|---------------|--------------|-------------------|------|---------|
+| backend | — | implementer | — | 实现后端改动（示例占位，按 plan 改写） | src/api/** | 项目测试命令通过 | | 0 |
+| frontend | — | implementer | — | 实现前端改动（示例占位，按 plan 改写） | web/** | 项目构建命令通过 | | 0 |
+| gate-all | backend,frontend | — | — | — | — | — | npm test | |
+| deploy-check | gate-all | — | 示例-部署验证 | env=staging | | 部署命令与冒烟 exit 0 | | 0 |
+| review | deploy-check | independent-reviewer | — | 独立评审两域改动是否符合 plan 与验收判据 | | 符合 plan 与判据 | | 0 |

package/templates/workflow/README.md

@@ -15,7 +15,7 @@
 
 **命名一律英文 kebab-case**（如 `2026-09-07-<主题>.md`），**禁中文文件名**——check-loop 对非 ASCII 文件名给 warning。文档内容（标题/正文）不受此限。
 
-**文档协议（frontmatter 受限子集）**：四类文档头部一律为 YAML frontmatter（每行 `键: 值`，机器字段唯一来源）——`状态`（intent/spec/plan：draft/approved/done/superseded/cancelled；incident：open/fixed/closed，**严格枚举**，附注写 `备注:` 键）、`级别`（L0-L3）、`日期`/`发现`（YYYY-MM-DD）、`模块`（**新建文档必填**，取值见 `.agents/workflow-modules.txt` 词表，单值取主导模块；存量不回填，AI 触碰时顺手补）、L3 spec 的 `确认结果`/`确认时间`、回填件 `流程: legacy`。**`状态` 迁移须经 `approved`**（确认环节的机器可见态，`done` 只在关单出现）：新建的 spec/plan 若已 done 而 git 历史中从未出现行首 `状态: approved`，check-loop 报「确认态缺失」warning。check-loop 只扫 frontmatter 取机器字段（`fm_get` 字段断言），正文不再写「状态：/级别：」行；叙述性字段（独立复核/复盘三件套/验收勾验）仍留正文按节锚定。
+**文档协议（frontmatter 受限子集）**：四类文档头部一律为 YAML frontmatter（每行 `键: 值`，机器字段唯一来源）——`状态`（intent/spec/plan：draft/approved/done/superseded/cancelled；incident：open/fixed/closed，**严格枚举，单源 `.agents/workflow-enums.txt`**——check-loop / 看板 / 检索 / fill-* 一律读它，改枚举改那边；附注写 `备注:` 键）、`级别`（L0-L3，同单源）、`日期`/`发现`（YYYY-MM-DD）、`模块`（**新建文档必填**，取值见 `.agents/workflow-modules.txt` 词表，单值取主导模块；存量不回填，AI 触碰时顺手补）、L3 spec 的 `确认结果`/`确认时间`、回填件 `流程: legacy`。**`状态` 迁移须经 `approved`**（确认环节的机器可见态，`done` 只在关单出现）：新建的 spec/plan 若已 done 而 git 历史中从未出现行首 `状态: approved`，check-loop 报「确认态缺失」warning。check-loop 只扫 frontmatter 取机器字段（`fm_get` 字段断言），正文不再写「状态：/级别：」行；叙述性字段（独立复核/复盘三件套/验收勾验）仍留正文按节锚定。
 
 各子目录内 `_TEMPLATE.md` 为起步模板，复制后填写，不直接改动模板本身。
 

package/templates/_agents/cache/kb-index.json

@@ -1 +0,0 @@
-{"fp":"b779761db958797b","files":{"/tmp/kb-search-test-XdDPi6::workflow/intents/2026-09-21-bbb.md":{"st":[1790253784155.5151,270],"kind":"wf","meta":{"状态":"approved","级别":"L1","日期":"2026-09-21","模块":"pipeline"},"title":"乙需求","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","日期: 2026-09-21"],[5,"(frontmatter)","模块: pipeline"],[6,"(frontmatter)","---"],[7,"(标题)","# INTENT — 乙需求"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B乙"],[11,"目标",""]]},"/tmp/kb-search-test-XdDPi6::workflow/plans/2026-09-20-ccc.md":{"st":[1790253784155.5151,200],"kind":"wf","meta":{"状态":"approved","级别":"L1","模块":"purchase"},"title":"丙计划","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: approved"],[3,"(frontmatter)","级别: L1"],[4,"(frontmatter)","模块: purchase"],[5,"(frontmatter)","---"],[6,"(标题)","# PLAN — 丙计划"],[8,"目标","## 目标"],[9,"目标","- 只讲编码模板，不提另一个词"],[10,"目标",""]]},"/tmp/kb-search-test-XdDPi6::workflow/incidents/2026-09-01-aaa.md":{"st":[1790253784155.5151,270],"kind":"wf","meta":{"状态":"closed","级别":"L2","发现":"2026-09-01","模块":"material"},"title":"甲事故","lines":[[1,"(frontmatter)","---"],[2,"(frontmatter)","状态: closed"],[3,"(frontmatter)","级别: L2"],[4,"(frontmatter)","发现: 2026-09-01"],[5,"(frontmatter)","模块: material"],[6,"(frontmatter)","---"],[7,"(标题)","# INCIDENT — 甲事故"],[9,"目标","## 目标"],[10,"目标","- 统一口径：编码模板与分类层级，冲突处理见 A/B甲"],[11,"目标",""]]},"/tmp/kb-search-test-XdDPi6::wiki/测试主题/说明.md":{"st":[1790253784155.5151,47],"kind":"wiki","lines":[[1,"# 说明"],[2,""],[3,"编码模板的领域知识条目。"],[4,""]]}}}