菜单
流程编排引擎。推进 task.json.flow 步骤（init/check/complete/reset）并维护任务级事件流 task.json.events（emit/check/recent）。触发关键词：flow advance、推进流程、当前步骤、初始化流程、emit event、查事件、task.json.events、flow-engine。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | flow-engine |
| description | 流程编排引擎。推进 task.json.flow 步骤（init/check/complete/reset）并维护任务级事件流 task.json.events（emit/check/recent）。触发关键词：flow advance、推进流程、当前步骤、初始化流程、emit event、查事件、task.json.events、flow-engine。 |
| model | haiku |
主流程状态机:读模板 + 写
task.json.workflow.flow推进 step，同步维护task.json.events任务级事件流。
| 场景 | 调用方 | 命令 |
|---|---|---|
| TAPD 工单开工 | /tapd start | flow_advance init --flow-id tapd-full --story-id <id> |
| 本地需求开工 | /story-start | flow_advance init --flow-id local-spec --story-id <id> |
| Bug 修复 | /bug-fix | flow_advance init --flow-id bugfix-{spec,plan,vibe} |
| Agent 完成 | 主 Claude | flow_advance complete <step_id> |
| 状态恢复 | task resume | flow_advance check --story-id <id> |
| 关键事件 | hook / agent | emit_event("...", {...}) 或 events.py emit ... |
task.json.workflow.flow(current_step_idx / current_step_id / current_step / next_step / phase / agent 双写)task.json.events(append-only, 按 story_id 路由).claude/templates/flows/*.json(创建时记录 frozen_template_hash, 推进时校验)flow_advance 会自己触发 agent(其实只更新状态,agent 由主 Claude 按 next_step 触发)emit_event 缺 --story-id 会直接被拒(必填,不会自动推断)args_from 只对 kind: command 有效,kind: skill 由对应 skill 自读 task.jsoncomplete <step_id> 中 step_id 不匹配 current 会报错(不能跨步完成,必须按顺序)docs/state/workflow-state.json 和 events.jsonl 已 DEPRECATED,不要再读写kind: skill 步骤必须经 Skill 工具调 target 指定的 skill 执行,禁止用同类 MCP/其他工具替代(如 notify 步禁用 send_qiwei_message 替代 notify skill——两者读不同配置)。该 skill 调用失败时,必先 retry 正确 skill 路径并确认成功,才能 complete <step>;不得"工具报错即就地标完成 + 降级"(本 session notify-qa-test 曾犯此错,见 FB-20260603-cc4d)python .claude/skills/flow-engine/scripts/flow_advance.py [--story-id <id>] <sub>
| 子命令 | 用法 | 说明 |
|---|---|---|
init | init --flow-id <flow> [--task-id <id>] [--force] | 创建 flow 子对象，锁模板 hash |
check | check | 只读输出 current / next / is_terminal |
complete | complete <step_id> [--result ok|failed] | 声明完成,advance 到下一步(幂等) |
reset | reset | 重置到 idx=0(debug 用) |
refreeze | refreeze | 模板被合法更新后,显式接受当前模板并更新 frozen_template_hash,消除推进时的 hash mismatch 持续告警(2026-06-05 加)。锁定语义不变:不 refreeze 仍按 init 时锁定版本告警,防静默换底盘 |
frozen_template_hash 告警处理:
load_steps每次推进重算模板 hash 与 init 时锁定值比对,不一致仅 stderr WARN 不阻断(继续用当前模板)。模板稳定时永不触发。若你有意改过 flow 模板(如增删步骤),运行中的 task 会持续告警 → 跑一次refreeze显式接受新版即可清除。
支持的 flow-id:tapd-full / local-spec / local-plan / local-vibe / bugfix-spec / bugfix-plan / bugfix-vibe / orchestrate
退出码:0=ok / 1=error(step 不匹配 / flow 未初始化等)
python .claude/skills/flow-engine/scripts/events.py <sub>
| 子命令 | 用法 | 说明 |
|---|---|---|
emit | emit <type> --story-id <id> [--data '<json>'] | 追加事件;缺 story_id 直接拒绝 |
check | check <type> --story-id <id> | 检查是否存在该类型事件(退出码 0/1) |
recent | recent --story-id <id> [--type <type>] [--limit 20] | 读最近事件(JSON) |
from events import emit_event, check_event, get_recent_events
emit_event("planner:all-cases-ready", {"story_id": "04-30-foo", "actor": "planner"})
if check_event("04-30-foo", "planner:all-cases-ready"):
...
hook 走 import(同进程零启动);agent / command 走 CLI(隔离)。
step 模板可声明可选字段 args_from,让 flow_advance 自动从 task.json 解析参数:
| 字段 | 类型 | 说明 |
|---|---|---|
args_from | list[str] | task.json 字段路径列表,支持点号嵌套(如 tapd.ticket_id),路径不存在取 null |
check / init / complete 返回值中,声明了 args_from 的 step 会附加 resolved_args: dict[路径, 值]。
示例:
{"id": "consensus-push", "kind": "command", "target": "/tapd push", "args_from": ["story_id"]}
主 Claude 据此直接拼 /tapd push <story_id>,无需自读 task.json。
约定:仅
kind: command的 step 用args_from;kind: skill由对应 skill 自读 task.json。
flowchart LR
A[init --flow-id] --> B[读模板 + 锁 hash]
B --> C[写 task.json.workflow.flow]
C --> D[主 Claude 读 check]
D --> E[执行 step]
E --> F[complete step_id]
F --> G{is_terminal?}
G -->|否| D
G -->|是| H[end]
| 路径 | 写入者 |
|---|---|
docs/task/store/<story_id>/task.json workflow section | flow_advance init/complete/reset |
docs/task/store/<story_id>/task.json events[] | events.emit / emit_event |
workflow.flow 子对象结构(只存引用 + 当前步快照, 不含完整 steps):
{
"flow_id": "local-plan",
"version": "1.1",
"frozen_template_hash": "aa06c71f04bf1ca0",
"current_step_idx": 2,
"current_step_id": "git-push",
"current_step": { "id": "git-push", "kind": "skill", "target": "git", "...": "..." },
"next_step": { "id": "merge", "kind": "skill", "target": "git", "...": "..." },
"started_at": "...",
"completed_at": null
}
旧的
docs/state/workflow-state.json和events.jsonl已 DEPRECATED。
.claude/skills/flow-engine/scripts/{flow_advance,events}.py.claude/templates/flows/*.json.claude/skills/task/scripts/{paths,task_store}.pyTAPD 统一入口 skill。工单拉取、共识管理、子任务回填、事件驱动同步。触发关键词：tapd、初始化、ticket sync、共识、Wiki 评审、子任务、工时回填、QA 通过、QA 打回、TAPD 事件、契约推送、同步工单、拉工单。
产出结构化 handoff 工件，让新 session 无痕接续当前任务。ctx-guard 阻断或主动切换 session 时使用。触发关键词：context reset、上下文重置、新开 session、切换 session、handoff。
运行架构适应度函数检查代码结构、契约、依赖方向。在代码修改前后使用，确保不引入架构违规。触发关键词：fitness、架构检查、适应度、lint、代码质量检查。
工作流熵管理。清理 stale TAPD cache、孤立 _index 条目、过期 task report。每日定时或手动触发。触发关键词：gc、垃圾回收、清理、cleanup、定时清理。
Git 操作统一入口。分支生命周期（create/merge/cleanup）、worktree（create/remove）、提交推送（commit-push）。按 docs/git-brance-spec.md + Conventional Commits 中文规范执行。触发关键词：创建分支、合并到 dev、合并到 uat、删除分支、清理分支、git push、commit、推送代码、worktree、提交代码。
统一集成测试入口。按 env.yaml 显式指定 / 文件名约定 fallback 探测被测项目的 testing skill,委托其跑测试输出统一 schema 的 verdict.json。