Loopflow

终端原生的 Loop 编排协调层。一个统一调度内核(core = SQLite schema + 读写函数),常驻 daemon 轮询,用 cron / 事件拉起本地 agent(Claude Code / Codex)执行固定任务,多个 Loop 经事件流转组成 Workflow。

三层调用链:L1 调用方 agent(交互态 Claude Code)→ L2 协调层(本仓库)→ L3 底层 runner agent(headless claude -p / codex exec)。

v0 范围

core + daemon + CLI 三件,用 CLI 手动 register_loop 跑通自用 pipeline(分诊 → 确认 → 实现)。SDK 与 Claude Code 插件是同一内核的后续薄皮。

设计文档

见 Obsidian vault:~/obsidian-knowledge/wiki/projects/loopflow/

• PRD.md — 需求(四大能力、非目标、成功标准)
• Spec.md — 架构、数据模型、core 接口、L3 调用契约、CLI

安装与使用(v0)

pip install -e ".[dev]"           # 安装,得到 loopflow 命令
loopflow setup                    # 探测 agent → 生成 ~/.loopflow/agents.toml
loopflow wf add pipe "分诊线"
loopflow loop add triage --trigger 'cron:0 */6 * * *' \
    --agent claude --prompt '扫新 issue 分诊;完成后打印 EMIT confirm-ready <issue>' \
    --workflow pipe --workdir ~/repos/target
loopflow loop add confirm --trigger 'event:confirm-ready' --agent claude \
    --prompt '确认 {payload};打印 EMIT impl-ready {payload}' --gate --workflow pipe
loopflow loop add impl --trigger 'event:impl-ready' --agent claude \
    --prompt '实现 {payload} 并提 PR' --workflow pipe --workdir ~/repos/target
loopflow run                      # 起 daemon 轮询(launchd 保活见下)

常用观测 / 控制:loopflow status、loopflow history [loop_id]、 loopflow ack <event_id>(放行 gate)、loopflow replay <event_id>(死信重入队)、 loopflow emit <type> [payload](手动注入事件)。

launchd 保活(macOS):loopflow setup 已把正确的 plist 写到 ~/Library/LaunchAgents/com.loopflow.daemon.plist(用 loopflow 的绝对路径,含 KeepAlive/RunAtLoad 与日志)。启用 / 排错 / 停用:

launchctl load   ~/Library/LaunchAgents/com.loopflow.daemon.plist   # 常驻
launchctl list | grep loopflow   # 第一列是数字 PID 即成功;- = 没起,看第二列退出码 + $LOOPFLOW_HOME/daemon.err.log
launchctl unload ~/Library/LaunchAgents/com.loopflow.daemon.plist   # 停用

ProgramArguments 必须是绝对路径(launchd 用最小 PATH,python3.11 这类相对名找不到会退 78)——setup 已替你处理。非 macOS:Linux 用 systemd(Restart=always),或 nohup/tmux/supervisor 让 loopflow run 常驻。

EMIT 约定:事件流转靠 L3 agent 在 stdout 打印 EMIT <事件名> <payload>, 把这句写进 Loop 的 --prompt 里即可,agent 无需集成 loopflow。

⚠️ 保持 pipeline 无环:F8 死信只兜住失败的 Loop。若某 agent 打印的 EMIT 触发了自己(或构成 A→B→A 环),daemon 会每轮(约 5s)拉起一次付费调用、永不停止——下游事件不带 dedup_key,v0 无环检测。务必让 Loop 只 EMIT 下游 的事件类型,不要 EMIT 自身的触发类型。

Web 看板(看 daemon 死活 / loop / 事件流)

loopflow web              # 开 http://127.0.0.1:8787,自动开浏览器
loopflow web --no-open    # 不开浏览器

只读看板 —— 左栏是 daemon 状态(心跳 + 进程 + launchd)、事件计数、workflow/loop 树; 右栏是最近 50 条事件,点开任一条可看 payload、EMIT 输出、以及这一趟流程的因果链。 只绑 127.0.0.1,页面每 5 秒自刷(展开明细时暂停)。

放行 gate / 重入队死信 / 增删 loop 仍走 CLI —— 看板不写库。

daemon 状态有四种:运行中(心跳新鲜)、正在执行 (长跑 agent 阻塞了轮询, 不是故障)、轮询停摆(进程还在但循环卡死)、未运行(进程没了)。

MCP server(让 Agent 管 Loop)

交互态 Claude Code 可用原生工具管理 Loop,不必手敲 CLI。装 MCP extra 后注册:

python3.11 -m pip install -e ".[mcp]"
claude mcp add loopflow -- python3.11 -m loopflow.mcp

或写进 .mcp.json:

{ "mcpServers": { "loopflow": { "command": "python3.11", "args": ["-m", "loopflow.mcp"] } } }

server 读同一个 LOOPFLOW_HOME,自动命中 daemon/CLI 那个 DB。暴露 14 个工具: list_loops/get_loop/register_loop/update_loop/remove_loop、 list_workflows/get_workflow_status/create_workflow、 emit_event/list_events/status/query_history/ack/replay。 只管理不执行——真正跑 Loop 的仍是 daemon(loopflow run)。

状态

idea — 设计定稿,源码待 writing-plans 阶段落地。