clawsomeflow 0.1.1b5

Vertical agent workflow orchestration platform on top of ClawTeam and OpenClaw

ClawsomeFlow

Make your multi-agent workflow Clawsome.

在 ClawTeam 与 OpenClaw 之上的 垂直领域 Agent 任务流编排平台。 让用户通过 Web 界面定制专业任务流，平台自动驱动 ClawTeam 与 OpenClaw 智能体按依赖编排执行。

---

🦞 为什么是 ClawsomeFlow，而不是 "ClawTeam GUI"？

如果只是给 ClawTeam 套一层可视化壳，没必要做这个项目。ClawsomeFlow 的存在价值来自两个根本性架构改造——它们让 ClawsomeFlow 从"协议工具"跨进"产品平台"。

🧠 核心设计哲学

LLM 是强大的计算单元，但是糟糕的协调器。

把控制流从自然语言里剥离出来，写回代码里。让 LLM 只做它擅长的事——执行单点任务。

改造一：细颗粒度调度引擎，替代 clawteam launch

clawteam launch 是"按 TOML 一次性拉起整个团队"的快捷脚本——所有调度决策被前置写死在模板里。它对 ClawsomeFlow 来说根本不可用。

ClawTeam launch	ClawsomeFlow 调度引擎
跑预定义 TOML 模板	跑用户在 Web UI 编辑的动态 DAG
全员同时上线	按 DAG 依赖按需激活
全用模板默认参数	每节点独立 profile / 模型 / worktree / 命令
必然让 worker 自循环	调度器主动派发
无节点级失败策略	retry / skip / abort 节点级配置
假设单团队场景	多 Run 并行 + 多用户隔离
黑盒动作	每动作落 RunEvent 可审计
跑完无 cleanup 决策	finalize_run 自动 merge + 冲突处理
跑完后无法干预	UI 可中止 / 重试单节点

一句话：launch 是"协议层的便捷脚本"，ClawsomeFlow 是"产品层的编排引擎"，目标完全错位。

改造二：服务调度，替代 Prompt 注入循环规则到 Agent 自调度

ClawTeam / OpenClaw 原生模式：worker spawn 时通过 prompt 注入"持续循环 polling 自管理"协议，靠 LLM 自觉做调度。 ClawsomeFlow 模式：worker prompt 只描述当前任务，调度器代码决定何时派发、何时重试、何时退出。

维度	Prompt 自调度（ClawTeam 原生）	服务调度（ClawsomeFlow）
控制流位置	写在自然语言里，依赖 LLM 解释	写在 Python 代码里，确定执行
失败检测	LLM 卡死无人知	worker_reported + timeout + leader_inbox_failed 三信号（代码收敛）
并发控制	难（agent 各自轮询竞争）	易（调度器统一编排）
Token 经济	每轮 polling 几百~几千 token	派发一次只消耗任务本身
行为可预测性	临场发挥（同输入不同结果）	代码确定（同输入同动作）
审计 / 计费	行为隐藏在 LLM 黑盒	每个 dispatch / completion / failure 落 RunEvent
重试 / 跳过 / 中止	LLM 临场发挥	调度器策略明确 + 用户 UI 可干预
多 Run 并发	难追踪	调度器持有完整上下文
企业治理	无事务边界，难限流 / 配额 / 多租户	每动作可审计、计费、限流
失败恢复	看 LLM 是否记得重试	明确 max_retries + on_failure 策略

这两个改造带来的连锁价值

• ✅ 企业级可观测性：每动作可审计、回放、计费
• ✅ 可靠性显著提升：失败信号可观测、可重试、可按策略收敛
• ✅ Token 成本下降 50%+：消除 polling 开销
• ✅ 支持复杂业务场景：多用户 / 多租户 / 节点级 SLA / 配额
• ✅ 产品化基础：UI 可中止 / 重试 / 干预

没有这两个改造，ClawsomeFlow 就只是 ClawTeam 的可视化壳，没有真正的产品差异化。它们是 ClawsomeFlow 之所以是 "ClawsomeFlow" 而不是 "ClawTeam GUI" 的根本原因。

---

✨ 核心亮点

产品亮点（业务视角）

1. 为复杂任务流而生：告别命令行，用自然语言编排任务流 用户在 Web UI 用自然语言定义目标与任务，后端自动接管编译、派发、监控与收敛。相较 ClawTeam 原生管理，ClawsomeFlow 提供更细粒度控制；在 OpenClaw 场景下，通过会话隔离、worktree 约束与调度防线，让多 agent 执行更稳定，补齐 OpenClaw 在多 agent 协同上的短板。AI Decompose 还会按当前界面语言（中文/英文）约束 leader 返回任务语言。

2. 多用户并行 + 多平台 agent 协同 支持多用户并发触发 Run，支持 OpenClaw / Claude 等多平台 agent 在同一 DAG 中协同执行，并通过 team/session/worktree 三层隔离避免串扰。

3. 自然语言创建与治理 OpenClaw agent（可持续演进） 支持通过自然语言创建、修改 agent 角色定义、增减 skills、扩展定时任务能力；后续会持续演进为带有“经验自增长”能力的 agent 治理体系。

技术亮点（实现视角）

1. 细颗粒度调度引擎（取代 clawteam launch） ClawsomeFlow 后端内建 FlowScheduler 异步调度器，每个 Flow Run 由独立的 RunController 驱动：建空团队 → 建任务 DAG → 按依赖并发 spawn worker → 末端汇总。每个节点的 spawn 时机、profile、worktree、命令参数完全独立可控。

2. 统一 Session 复用模型 — 调度器主动派发，worker 不 polling

   • 每个 FlowAgent = 一个长期会话，多个 task 复用同一 session（LLM 上下文 + 进程开销）
   • 调度器派发优先级：live inject > resume re-spawn > fresh spawn
   • live inject（毫秒级）：CLI clawteam runtime inject ... --summary <prompt>，复用 ClawTeam 已有的 tmux paste-buffer 能力
   • resume re-spawn（进程已退出）：CLI clawteam spawn ... --resume + 紧随 inject
   • fresh spawn（首次/resume 失败）：CLI clawteam spawn ... --no-keepalive（不传 --task → 不触发循环协议注入）+ 紧随 inject
   • OpenClaw 特殊路径：常规 DAG 任务在 agent 专属 session 中执行 openclaw agent --local --session-id <stable_id> --message <task>，通过稳定 session-id 续会话（执行容器仍由 ClawTeam/tmux 承载）；投诉阶段改为 headless 派发（不依赖 tmux 会话）

3. 几乎零嵌入耦合 — 全 CLI/MCP 通道 ClawsomeFlow 与 ClawTeam 通过公开的 CLI + MCP 接口通信，不依赖 ClawTeam 内部 Python API。当前调度失败检测路径不依赖 is_agent_alive/worker_dead；仅保留历史兼容的最小嵌入兜底能力（1 行 import，后续可替换为纯 CLI 能力）。

4. Leader 末端登场，由调度器组装汇总素材 team spawn-team 阶段只注册 leader 元数据（不 spawn 进程）。DAG 末端的 leader_summary 任务变 ready 时，调度器拉取所有 worker 给 leader 的 inbox 消息 → 拼装汇总 prompt → 一次性 spawn leader → 产出最终交付后退出。Leader 不空转、不浪费 token，但拥有所有上下文做最终决策。

5. OpenClaw 托管 Agent + Skill 体系（含 worktree 隔离） 用户 agent 由后端直接创建并注册到 OpenClaw，随后由目标 agent 自行完善定义文档，最后由后端统一执行 workspace git commit。用户 agent 创建时自动 git init 主仓，每个 Run 在独立 worktree 编辑；OpenClaw 默认在每个任务完成时 self-merge 到基线分支，非 OpenClaw 按 manual/auto/skip 策略在收尾阶段处理合入。

6. 双形态架构，当前仅开放本地部署

   • 本地个人模式：SQLite + 单机 ClawTeam/OpenClaw + 单用户，零依赖即开即用
   • 企业服务端模式：PostgreSQL + Redis + 多用户协作（代码路径保留，当前暂不向用户开放） 当前 CLI 发布策略：用户侧仅允许 --mode local

7. 集中式数据治理 所有 ClawsomeFlow 自身数据落 ~/.clawsomeflow/，ClawTeam 与 OpenClaw 自有目录不复制不重叠

8. 拥抱原生，不重复造轮子 任务监控直链 ClawTeam 原生 Web UI（clawteam board serve）。ClawsomeFlow 只做"启动器 + 高层状态展示 + Agent 治理"，把 ClawTeam 已有能力发挥到位

9. 多 Agent 后端开箱即用 通过 ClawTeam 的 NativeCliAdapter，原生支持 Claude Code / Codex / OpenClaw / Nanobot / Kimi / Gemini / Qwen / OpenCode。Cursor 因无标准 CLI 暂不支持

---

🧩 与 ClawTeam / OpenClaw 的关系

flowchart LR
    user[用户] -->|Web UI| CSF[ClawsomeFlow]
    CSF -->|"MCP + CLI<br/>(1 行嵌入兜底探活)"| CT["ClawTeam<br/>多智能体协议层"]
    CSF -->|HTTP Gateway + skill 回调| OC["OpenClaw<br/>Agent 运行时"]
    CT -->|spawn| Workers["Claude Code / Codex /<br/>OpenClaw / Nanobot / ..."]
    OC -->|被 ClawTeam spawn 或<br/>独立 subprocess 派发| Workers

层	职责	谁来做
协议层（团队/任务/邮箱/工作区）	多 agent 协作的底层语义	ClawTeam
Agent 运行时	单个 agent 的执行容器	OpenClaw / Claude Code / Codex / ...
编排层（DAG 调度 + 监控触发）	Flow 定义、调度引擎、Run 控制	ClawsomeFlow
产品层（Web UI + 多用户 + NL 创建）	让非工程用户也能编排	ClawsomeFlow

---

🏗️ 架构总览

flowchart TB
    subgraph FE [前端 React]
        UI["FlowEditor / RunPanel /<br/>OpenclawAgents / Profiles"]
    end

    subgraph BE [ClawsomeFlow 后端 FastAPI]
        API[REST API + WebSocket]
        SCH[FlowScheduler<br/>RunController × N]
        OCB[OpenClaw Bridge]
        SKI[Skill Installer]
    end

    subgraph CT [ClawTeam]
        MCP[MCP Server]
        CLI[clawteam CLI]
    end

    subgraph OC [OpenClaw]
        GW["Gateway :18789"]
        OCJ[openclaw.json]
        OCSK[skills 目录]
    end

    subgraph PERS [持久化]
        FS["~/.clawsomeflow/"]
        SQ["SQLite / Postgres"]
    end

    UI <--> API
    API --> SCH
    API --> OCB
    SCH -->|读状态| MCP
    SCH -->|spawn/team/task| CLI
    OCB -->|HTTP token| GW
    OCB -->|asyncio 锁| OCJ
    SKI --> OCSK
    GW -.->|skill 回调| API
    API --> FS
    API --> SQ

---

📂 数据布局

ClawsomeFlow 自有数据全部集中在 ~/.clawsomeflow/：

~/.clawsomeflow/
├── config.json                         # 部署模式、关联路径、用户配置
├── db.sqlite                           # 本地模式索引（server 模式走 PG）
├── .flows/                             # Flow 定义 JSON
│   └── {flow_id}.json
├── .runs/                              # Run 元数据 + 事件日志
│   └── {run_id}/
│       ├── meta.json
│       └── events.jsonl
├── .system/                            # 平台内部目录（保留给内部运行态）
├── .common-agent-source/               # common-agent-source 运行时镜像（规则 + skills）
├── .clawsomeflow-agent-tools/          # 全局 agent 工具脚本
├── .skills-source/                     # 由 openclaw-agent-source 投影出的可安装 skill 缓存
└── agents/                             # OpenClaw agent 工作目录
    └── {agentID}/
        ├── workspace/                  # 主项目 git 仓（在 openclaw.json 中将该 agent 的 workspace 字段登记为此路径）
        ├── identity.json               # ClawsomeFlow 元数据
        └── history/                    # 任务执行记录

Worktree 不在 ClawsomeFlow 治理目录 — 由 ClawTeam 自动创建在 ~/.clawteam/workspaces/{team}/{agent_name}/（含 OpenClaw 的 worktree）。Run 结束不会统一“一刀切” merge+cleanup：OpenClaw 不做终态集中 worktree cleanup；non-openclaw 在 manual review 的 merge/dismiss 决策后按策略 cleanup（merge conflict 保留 worktree）。

ClawTeam 的状态在 ~/.clawteam/（含所有 worktree），OpenClaw 的状态在 ~/.openclaw/，ClawsomeFlow 自有状态在 ~/.clawsomeflow/，三者不复制不重叠。

---

🔁 调度引擎工作模式

双层数据模型

Flow
├── agents: [FlowAgent]      # 会话身份（spawn 一次 + 复用 session）
│   ├── id (= ClawTeam agent_name，全 Flow 唯一)
│   ├── kind (claude|codex|openclaw|gemini|kimi|...)
│   ├── is_leader
│   ├── dispose_after_done   # 全部 task 完成后是否主动 shutdown
│   └── ...
└── tasks:  [FlowTask]       # DAG 节点（任务依赖在此）
    ├── id
    ├── owner_agent_id  ──→  FlowAgent.id（多对一）
    ├── depends_on (任务级 DAG → ClawTeam blocked_by)
    └── is_leader_summary

Worker Session 状态机

stateDiagram-v2
    [*] --> Absent: 创建 FlowAgent
    Absent --> Spawning: 首个 task ready
    Spawning --> Idle: 进程启动 + TUI ready
    Idle --> Busy: 调度器 dispatch 新 task
    Busy --> Idle: worker 标 task completed + 报 inbox
    Idle --> Exited: 全部 task 完成 后 调度器发 shutdown
    Busy --> Crashed: 进程异常退出
    Crashed --> Resuming: 还有未完成 task
    Resuming --> Idle: --continue resume 成功
    Resuming --> Spawning: resume 失败 fallback re-spawn
    Exited --> [*]

派发决策矩阵

Session 状态	TUI 类（claude/codex/...）	OpenClaw
absent	clawteam spawn tmux <cli> --workspace --repo <Flow.repo> --no-keepalive	clawteam spawn tmux bash --workspace --repo <openclaw 主仓> --no-keepalive（bash 启动空 shell，cwd=worktree，ClawTeam 自动创建 worktree）
idle	clawteam runtime inject ... --summary <prompt>（毫秒级）	tmux send-keys "openclaw agent --local --session-id csflow-{team}-{agent} --message ..." Enter（在 shell 内执行 OpenClaw 命令）
busy	跳过等下轮	跳过等下轮
crashed	拼 agent 原生 resume 命令（claude --continue 等）+ clawteam spawn ... --no-workspace --repo <existing_worktree> 复用 worktree	重新 spawn shell（worktree 已在）+ session-id 自然续会话历史
自管 merge（仅 OpenClaw）	❌ 不适用	每个 owner task 的完成步骤内即执行 self-merge（先 merge 再 task_update completed）；Run 收尾阶段不再做 OpenClaw workspace cleanup

调度时序

flowchart TB
    Start[Run 启动] --> C1["team spawn-team<br/>注册 leader 元数据"]
    C1 --> C2["team_member_add<br/>注册其他 agents"]
    C2 --> C3["task create × N<br/>带 owner + blocked_by"]
    C3 --> C4["每个 FlowAgent 创建<br/>WorkerSession state=absent"]
    C4 --> Loop{"调度循环<br/>0.5–3s 自适应"}
    Loop --> Done["处理 completed task<br/>→ session.busy 转 idle"]
    Done --> Fail["失败检测<br/>(worker_reported / timeout / leader_inbox_failed)"]
    Fail -->|有失败| HF[retry/skip/abort]
    Fail -->|无失败| Scan[扫描 ready task]
    HF --> Loop
    Scan --> Disp{"按 owner.session.state 派发"}
    Disp -->|absent| Spawn[fresh spawn]
    Disp -->|idle tmux| Inj[live inject]
    Disp -->|idle openclaw| Oc[openclaw subprocess]
    Disp -->|crashed| Res[resume re-spawn]
    Disp -->|busy| Sk[跳过]
    Disp -->|leader_summary ready| L["拉 inbox 拼汇总<br/>派给 leader session"]
    Spawn --> Loop
    Inj --> Loop
    Oc --> Loop
    Res --> Loop
    Sk --> Loop
    L --> Loop
    Loop --> Disp2{idle 且无新任务<br/>且 dispose_after_done}
    Disp2 -->|yes| SD[shutdown session]
    SD --> Loop
    Disp2 -->|no| Loop
    Loop -->|leader_summary task completed| Final[进入终结阶段]

协议注入策略

Worker dispatch prompt（每次派发结构相同，调度器主动推送）：

任务 #{task_id}: {subject}
{description}

完成后按顺序执行：
1. git add -A && git commit -m "task {task_id}: {subject}"
2. （非 leader 任务）clawteam inbox send {team} {leader_id} "task {task_id} done: <完成情况摘要>"
3. clawteam task update {team} {clawteam_task_id} --status completed
4. End this turn

OpenClaw 且 merge_strategy=agent_self 时，完成步骤会在 task update completed 前插入“切到基线分支工作区并执行 merge”的自合入流程。

Leader 末端汇总 prompt（调度器拉 inbox 后拼装）：

你是本次 Flow 的最终交付负责人。以下是各成员汇报，请基于此产出最终交付：

=== {worker_a} (任务: {subject}) ===
<inbox 消息>
...
完成后：commit + task update completed → 退出

⚖️ 相对 ClawTeam 的增量价值

维度	ClawTeam 原生	ClawsomeFlow 增量
任务流定义	TOML 模板 + 手写	Web UI 编辑（先列表，后拖拽 DAG）
执行入口	clawteam launch 一次性全 spawn	调度引擎按依赖并发逐节点 spawn，每节点独立配置
Worker 行为	仅支持 prompt 注入"持续循环 polling"（依赖 LLM 自觉）	调度器主动派发：live inject / resume / spawn 自决，worker 不 polling，行为完全确定
Leader 行为	prompt 注入"每轮看板 + 等待 45 秒"	末端一次性 spawn，调度器把 inbox 消息拼成 prompt 主动派发，leader 产出即退出
Token 消耗	高（持续 polling 累积上下文）	低（按需派发，会话间不重复消费协议提示）
同 agent 多任务	task.owner 字段 + worker prompt 循环	Session 复用：调度器主动 dispatch 到同一 session，毫秒级 live inject
会话复用	keepalive 自动 resume + 注入 polling 提示	复用 ClawTeam inject_runtime_message + build_resume_command，但调度器持有 lifecycle 主动权（keepalive=False）
失败策略	看 LLM 临场发挥	节点级 retry/skip/abort 由调度器明确执行
OpenClaw 集成	仅作为可被 spawn 的 CLI 客户端	后端直连创建/注册 + 目标 Agent 自完善定义 + 通用 skill 体系
多用户	CLAWTEAM_USER 命名空间	完整用户体系（local 单用户 / server 多用户）
部署形态	单机 CLI 工具	同代码双形态（本地 + 企业服务端）
数据治理	数据散在 ~/.clawteam/	ClawsomeFlow 自有数据集中 ~/.clawsomeflow/
监控	终端 Rich + 静态 Web	复用 ClawTeam Web UI，ClawsomeFlow 只做 Run 高层状态

🧵 并发模型

关注点	行为
clawteam spawn 调用	几百毫秒返回（启动 tmux 窗口），不等任务执行
不同 agent_name 节点并发 spawn	完全 OK，独立 worktree + 独立 tmux 窗口
同 agent_name 处理多任务	统一 Session 复用：absent → fresh spawn；idle → live inject（毫秒级）；crashed → resume 命令重启（不走 create_workspace 路径，不重建 worktree）
多 Run 隔离	team_name 含 run_id UUID（csflow-{run_id_short}）；OpenClaw --session-id 必须含 team_name（csflow-{team}-{flow_agent_id}），否则两 Run 给同 OpenClaw agent 会续到同会话；任何 main_repo（含 TUI 的 Flow.repo 与 OpenClaw 主仓）多 Run 并发 spawn 时用 lock("clawteam_main_repo:{repo_path}") 保护 git 元数据
Worktree 路径	完全由 ClawTeam 管理：spawn 时 --workspace --repo <main_repo>，ClawTeam 自动创建在 ~/.clawteam/workspaces/{team}/{agent_name}/；ClawsomeFlow 不写 git CLI 代码
Leader 与 Merge 决策权	Leader 不直接 merge，给出 merge 建议写在最终交付。TUI 类默认 merge_strategy=manual：用户在 UI 根据 leader 建议 + worker diff 决定 merge；成功 merge 或 dismiss 后会自动 best-effort workspace cleanup 对应 non-openclaw agent（merge conflict 不清理，保留给用户手动解冲突）。可选 auto（调度器自动）/ skip。manual 场景下，若 Run 处于正常收敛路径，pending merge 全部处理后进入 awaiting_user_complaint；若 Run 已失败/中止，则 pending merge 处理完后直接回到对应终态。OpenClaw 默认 agent_self：每个任务完成步骤内执行 self-merge，不做终态集中 worktree cleanup
失败检测	保留三类信号：worker_reported / timeout / leader_inbox_failed；不再依赖 is_agent_alive/worker_dead 作为调度失败信号
Task 状态同步原则	本地 task 状态与 ClawTeam 严格同构，仅 pending/in_progress/completed/blocked 四态；dispatch 成功后立即 task_update(..., in_progress)，失败收敛信息通过 RunEvent/失败集合记录，不创造本地新状态类别。自然收敛门槛为 leader summary task completed（非“全任务 completed”）
投诉阶段调度与收尾	投诉内部 task 仅用于本次 Run（csflow_internal + csflow_exclude_history）；OpenClaw 投诉派发走 headless openclaw agent --local --session-id ...（不依赖 tmux）。投诉完成/跳过后统一走 run_terminal_tail_cleanup（按策略 team cleanup）
投诉超时自动收敛	Run 进入 awaiting_user_complaint 超过 12 小时后，后台自动按“跳过投诉”路径收敛（事件：run_complaint_auto_skipped）
Spawn 通道	全走 CLI：clawteam spawn ... --no-keepalive（不传 --task → 不触发循环协议注入）+ 紧随 clawteam runtime inject 投递任务。无需嵌入式 Python API
ClawTeam skill 自动加载冲突	Claude Code 会按 description 关键词自动加载 ~/.claude/skills/clawteam，其中 Worker Loop Protocol 教 worker 自己 polling → 破坏调度模型。MVP 对策：dispatch message 顶部加 ## ClawsomeFlow Dispatch Context 4 行覆盖指令（零额外文件，与 OpenClaw 工作上下文块整合）。不删/不改 ClawTeam skill（侵入用户配置 / ClawTeam 升级即被覆盖）。P1 兜底：实测发现 agent 真受 ClawTeam skill 引导才启用 csflow-worker skill 强覆盖。长期：提 PR 加 clawteam spawn --no-default-skills
严禁 build_agent_prompt 注入循环（4 道防线）	调度器代码强制：① spawn 不传 --task（避免 build_agent_prompt 触发，对 claude/codex/gemini/kimi/qwen/opencode/pi/nanobot 全适用；OpenClaw 不走 spawn 天然免疫）② spawn 不传 --skill clawteam ③ 强制 --no-keepalive ④ 每次 dispatch message 顶部含调度上下文块
不传 --task 后必要信息怎么补	ClawsomeFlow dispatch message 模板自包含所有必要内容：身份块（agent_name/team/leader/user）+ 工作上下文块（worktree 路径/分支）+ 任务块 + 完成步骤块（具体命令拼好），每次派发完整拼接，不依赖任何长期注入
keepalive 与统一模型	强制 --no-keepalive（ClawTeam 默认 True！）：避免 ClawTeam 自动重启 + 注入 polling prompt 绕过调度器主动派发；resume 决策完全由 ClawsomeFlow 调度器持有
Resume 路径	不依赖 ClawTeam --resume 标志（默认空 SessionStore + 仅支持 claude）；改为直接拼 agent 原生 resume 命令（claude --continue / codex resume --last 等）；必须 --no-workspace --repo <recorded_path> 防止 worktree 重建丢内容
Live inject TUI ready	ClawTeam runtime inject 不等 CLI 启动完成；ClawsomeFlow 自实现 _wait_tui_ready（30 行，复刻 tmux capture-pane 检查提示符）
inbox 读取策略	调度器统一使用 mailbox_peek（只读不删），保证同一条 worker→leader 消息可被多个下游任务复用；leader 汇总阶段读取的是 leader inbox 全量结构化消息（保留 from_agent/task_id），可能包含非任务类回复，由 leader 按上下文甄别
上游消息透传语义	对某下游任务的一级依赖，先按上游 owner_agent_id 去重；每个上游 owner 传给下游的是该发送方（from_agent == owner_agent_id）发给 leader 的全部消息（按时间顺序拼接）
投诉反馈读取语义	投诉阶段目标 agent 作为 inbox 收件方：逐个读取 mailbox_peek(team, target_agent_id)，再过滤 from_agent == leader_id 作为投诉反馈
Task 超时	FlowTask 加 timeout_seconds（默认 1800s）；调度器记录 dispatched_at，按 effective_timeout = max(task.timeout_seconds, 1800) 判定（下限 30 分钟，避免前端写过小值误伤）；超时按失败处理（ClawTeam 无超时机制）
同 team 并发 spawn	per-team asyncio.Lock 防止 tmux 创建竞态
多 Run 并行	各自独立 RunController，共享 MCP 连接池
企业模式横向扩展	RunController 可拆到 Redis Stream 多 worker 消费

---

🌳 Worktree 管理（全走 ClawTeam，无自管 git CLI）

完全取消 ClawsomeFlow 自管 worktree。所有 worktree 由 ClawTeam spawn 时自动创建在 ~/.clawteam/workspaces/{team}/{agent_name}/，ClawsomeFlow 不写任何 git subprocess 代码，全程通过 clawteam workspace ... CLI 与 MCP 操作。

Agent 类型	主仓位置（spawn 时 --repo）	Worktree 路径
TUI 类（claude/codex/...）	Flow.repo（用户业务 git repo）	~/.clawteam/workspaces/{team}/{agent.id}/（ClawTeam 自动建）
OpenClaw	~/.clawsomeflow/agents/{agentID}/workspace/（创建 agent 时自动 git init）	~/.clawteam/workspaces/{team}/{agent.id}/（ClawTeam 自动建）

OpenClaw Agent 的项目数据模型

OpenClaw Agent 创建时 ClawsomeFlow 做两件事：

1. 在 ~/.openclaw/openclaw.json 中将该 agent 的 workspace 字段登记为 ~/.clawsomeflow/agents/{agentID}/workspace/（OpenClaw 标准能力）
2. 在该路径下自动 git init，建立项目主仓（main 分支）

每个 Run 启动时通过 clawteam spawn tmux openclaw --workspace --repo <主仓>（不传 --task）让 ClawTeam 自动创建 worktree。OpenClaw 的合并发生在每个任务完成步骤（agent_self）内；Run 终态不再统一执行 OpenClaw workspace cleanup。

⚠️ 关键认知：OpenClaw agent 的工作目录由 openclaw.json 写死，subprocess 的 cwd 完全无效。所以"让 agent 写到 worktree"的核心不是改 cwd，而是强约束 agent 主动用 worktree 绝对路径读写文件。

三层保险：

1. Message 显式给绝对路径 + 硬约束声明（核心）：dispatch message 含 ## 工作上下文 块明文给 worktree 绝对路径 + 声明"所有写入必须以此前缀开头，禁止写主仓"
2. csflow-worktree-runner skill 行为契约（强化）：必装 skill，教 agent 自检清单
3. 调度器事后审计 + 自愈（兜底）：task completed 后服务端校验 — 主仓被脏写入则 stash 走 + worktree 缺 commit 则自动 checkpoint

会话生命周期与 worktree：

• absent → ClawTeam spawn 时自动创建 worktree
• idle → 派发新任务（TUI: live inject；OpenClaw: subprocess），worktree 不动（agent 在原 worktree 累积工作）
• crashed → resume 时严格 --no-workspace --repo <existing_path> 复用（防 ClawTeam 默认重建丢内容）

Merge 决策权（按平台分流）

ClawTeam 没有自动 merge，merge 是显式人工/agent 决策。ClawsomeFlow 按平台分流 merge 策略：

平台	merge_strategy 选项	默认	谁执行 merge
TUI 类（claude/codex/...）	manual / auto / skip	manual	manual: 用户在 UI 决定 → 调度器调 clawteam workspace merge；auto: 调度器自动
OpenClaw	agent_self / skip	agent_self	OpenClaw agent 自己（每个任务完成步骤内 merge；调度器不做终态集中 workspace cleanup）

为什么 OpenClaw 自管 merge：OpenClaw 是 ClawsomeFlow 治理的"长期数据维护者"，主仓在 ClawsomeFlow 目录，agent 知道整个项目历史与本次工作上下文，让它自己决定如何合入比让用户审每个细节更合适。 为什么 TUI 类不自管 merge：TUI agent 通常用于用户业务 repo，由用户决定 merge 更安全（业务关键）。

冲突的 worktree 不自动清理，UI 上展示路径让用户用 IDE 解决。

---

👁️ 通过 ClawTeam Web UI 看所有平台执行进度

ClawsomeFlow 复用 ClawTeam 自带的 clawteam board serve Web UI 实现"所有 AI 平台统一可视化"，不重做监控（默认端口由配置项 clawteam_board_port 控制，默认 17018）。

内容	ClawTeam Web UI	tmux attach
各 agent task 状态变化（pending/in_progress/completed/blocked）	✅ 完全可见（含 OpenClaw）	—
各 agent inbox 消息（worker → leader 汇报）	✅ 完全可见	—
Team kanban 整体进度	✅ 完全可见	—
Worker 实时工作输出（TUI 类）	❌ Web UI 不渲染 tmux 内容	✅ tmux attach 可见
OpenClaw 实时工作输出	❌ Web UI 不渲染 tmux 内容	✅ tmux attach 可见（OpenClaw 通过 send-keys 在 shell 内执行 openclaw agent --message ...）

常规 DAG 任务里，OpenClaw 派发通过 tmux send-keys 在 shell 内执行命令，因此可在 tmux 侧看到执行过程；但投诉阶段 OpenClaw 走 headless 派发，不保证出现在 tmux 窗口：

• 用户 clawteam board attach <team> 平铺看所有 agent 的 tmux 窗口
• ClawTeam Web UI 看 task 状态 + inbox 消息（高层进度）
• 两者配合覆盖完整可观测性

ClawsomeFlow 自己的 Web UI 只负责"启动 Flow / 配置 / Run 状态高层 / pending merges + 用户投诉环节 UI"，详细监控全部跳转链接到 ClawTeam（board serve / board attach / board live）。

🚀 快速开始

ClawsomeFlow 完全不依赖 docker。当前对外只开放本地模式，pip install -U clawsomeflow && csflow start 即可。server 模式代码路径保留用于后续迭代，CLI 暂不开放。当前本地模式正式支持 Linux 与 macOS。

本地模式（推荐 — 个人 / 单机协作）

pip install -U clawsomeflow && csflow start

# Or install into an isolated user venv at ~/.clawsomeflow/.venv
scripts/install_clawsomeflow.sh
~/.clawsomeflow/.venv/bin/csflow start

# Or (推荐给小白用户) 自动托管运行环境 + 后台服务
bash scripts/install-user.sh --yes

• 默认安装稳定通道（会自动跳过 beta / rc）
• 预发布通道需显式传参：pip install --pre -U clawsomeflow 或 scripts/install_clawsomeflow.sh --pre
• 推荐路径 pip install -U clawsomeflow && csflow start 不需要下载项目源码到本地
• 平台支持：Linux / macOS（Windows 暂未正式支持）
• 以上两条用户安装路径默认都从 PyPI 拉取最新稳定 release（除非显式传 --pre）
• install-user.sh 会自动创建 ~/.clawsomeflow/.venv、安装 clawsomeflow/clawteam、写入 ~/.local/bin/{csflow,clawsomeflow,clawteam} shim，并按“首装 install / 已部署 upgrade”的方式做原地升级（不卸载用户数据）

开发者源码安装（用于开发调试，不保证是最新 release 版）：

git clone https://github.com/clawsomeflow/clawsomeflow.git
cd clawsomeflow
pip install -e ./backend
csflow start

# Or install this checkout into ~/.clawsomeflow/.venv
scripts/clawsomeflow_local_install
~/.clawsomeflow/.venv/bin/csflow start

若环境里的 clawteam 版本不含 runtime 子命令，请先执行： pip install -U clawteam
然后重新运行 csflow start。install-user.sh 与 install_clawsomeflow.sh 会在安装阶段自动做这项检查。

想试体验最新 beta？pip install --pre clawsomeflow 即可（PEP 440 标准行为）。 详见 发布流程。

csflow start 会自动：

1. 检查依赖（python ≥3.10 / git / tmux / node ≥22 / clawteam（需含 runtime 子命令）/ openclaw），并自动尝试安装缺失的必需依赖（默认开启）
2. 首次运行写默认 ~/.clawsomeflow/config.json（SQLite，端口 17017）
3. 初始化数据布局 + 部署 OpenClaw 通用源与工具
4. 配置并重启后台服务（Linux: systemd --user; macOS: launchd LaunchAgent）
5. Linux 自动确保 loginctl linger 已开启（用于开机自启，不依赖登录会话）；macOS 通过 LaunchAgent 实现登录后自动拉起
6. 启动后输出 Agent 工具检查摘要：当前可调用的非 OpenClaw Agent、以及仍支持但待安装的工具清单；若未安装 OpenClaw，会单独提示但不会自动安装

零外部依赖：SQLite + 进程内锁，开箱即用。

服务端模式（企业多用户）

当前版本暂不向用户开放 server 部署入口：

• csflow init/install --mode server 会直接失败（参数校验阶段拒绝）。
• 原因：我们优先保证单机模式稳定，并把 server 能力与本地架构彻底解耦后再开放。
• 进展与问题台账见 SERVER_MODE_MULTIUSER_AUDIT.md。

Web UI 语言

前端默认英文，提供独立的中文切换 pill（顶栏右上角）。首次访问统一显示英文（不读 navigator.language，避免中文浏览器自动切走）；之后每次切换都持久化到 localStorage["csflow-lang"]，下次再访问直接走你选的那个。两份字典在 frontend/src/i18n/{en,zh}.ts（en 是默认），新增字符串两处都要同步（TS 严格类型保证不漏翻）。详见 frontend/README.md。

CLI 命令速查（更多见 DEV.md）

# 生命周期
csflow start              # 一条命令搞定：依赖检查 + init/upgrade + 重启后台服务
csflow stop               # 优雅停止（PID 文件 → SIGTERM → SIGKILL）
csflow status             # 版本 / 运行状态 / 配置 / 数据计数（Rich 表格）
csflow init [--force]     # 初始化并在末尾重启后台服务（当前仅 local）
csflow install            # init 的别名；已部署时自动走统一升级管线并重启服务
csflow serve              # 仅启动（不做 dep-check / init，给 systemd/launchd/supervisor 用）
csflow doctor             # 完整体检：依赖 + 配置 + OpenClaw 集成 + gateway 探活
csflow upgrade [--dry-run]   # pip install -U 之后跑这条：对齐数据目录并重启服务
csflow uninstall          # 卸载 OpenClaw 集成并停掉后台服务（保留 ~/.clawsomeflow）
csflow purge-data         # 删整个 ~/.clawsomeflow/（强确认；要打字 PURGE）

# 运营
csflow flows list / show <id>
csflow runs list / start <flow-id> --input k=v / show <id> [--events 50] / abort <id> / merge <run> <agent>
# `runs abort` 对任意非终态 Run 生效（含 awaiting_user_review / awaiting_user_complaint / complaint_processing）
csflow agents list / create "<NL prompt>" / chat <id> "<message>" / remove <id> [--purge]
csflow agents reinstall-skills [<agent-id>]   # 升级后给老 agent 补装新 skill (e.g. csflow-task-decomposer)

# 调试
csflow logs tail [-n 50] [-f]
csflow logs grep <run_id>
csflow logs export <target-path-or-zip>   # 导出排障包 zip（.logs + .runs + 配置/索引元数据），便于用户回传
csflow logs verify-anti-loop   # 4 道防线审计：扫历史 spawn 事件断言无 --task / --skill clawteam / --no-keepalive

卸载 / 升级 / 重装

ClawsomeFlow 把"卸代码"和"删数据"严格分开 —— 误操作不会丢东西。

你想做什么	命令	副作用
开发者本机一键部署	./deploy.sh	仅供项目开发者本地使用：自动补齐 Python 3.11、重装 csflow/clawteam 到 3.11，并按“首装 install / 已部署 upgrade”执行原地收敛（不卸载用户数据）
用户正式部署（后台 + 开机自启）	pip install clawsomeflow 然后 csflow start	start 会自动配置并重启用户级后台服务（Linux: systemd --user；macOS: launchd）
升级到新版本（用户级后台服务）	pip install -U clawsomeflow 然后 csflow upgrade --yes	跑 schema migration（如有）+ 刷新 skill + 命令末尾自动重启后台服务
升级（懒人版）	pip install -U clawsomeflow 然后 csflow start	start 在已部署场景会执行一次安全 redeploy；若 marker stale 则自动跑完整 upgrade
重装到新机器但保留旧数据	把 ~/.clawsomeflow/ 拷过去；pip install + csflow start	start 会自动做 redeploy/upgrade，把数据目录对齐到新包版本
卸载 ClawsomeFlow（保留所有 flow / agent 数据）	csflow uninstall	停掉并禁用 csflow 用户级后台服务（释放服务端口）+ 仅删 managed-agent 注册信息；~/.clawsomeflow/ 完整保留，重装即可恢复
彻底卸载（含数据目录）	csflow purge-data	列出每个目录大小让你确认 → 要求打字 PURGE → 删整个 ~/.clawsomeflow/；后台运行中会拒绝
降级（开发场景）	pip install clawsomeflow==<旧版> 然后 csflow upgrade --force	warn 后强行重跑 upgrade 流程；schema 只支持 forward-compatible，必要时手动备份 DB

升级体系细节见 DEV.md 的“卸载、升级与重装策略”章节。

---

📦 版本发布与预览通道

ClawsomeFlow 遵循 SemVer 2.0 + PEP 440：

通道	版本号示例	用户安装命令	何时使用
Release	1.2.3	pip install -U clawsomeflow	默认通道；稳定、推荐生产
Beta	1.2.3b1	pip install --pre -U clawsomeflow	大特性 RC 前；欢迎吃螃蟹
Release Candidate	1.2.3rc1	pip install --pre -U clawsomeflow	release 前最后一道关

关键保证：未加 --pre 时 pip 永远跳过 beta / rc，所以即便我们刚发了 1.3.0b1，pip install -U clawsomeflow 拉到的还是上一个稳定版 1.2.3。这是 PEP 440 的默认行为，不是我们自己实现的。

每个版本随发布同时产生：

• PyPI wheel + sdist —— pip install 立即可用
• Git tag v1.2.3 —— 不可变的代码快照
• GitHub Release —— 自动从 CHANGELOG.md 抽取该版本的 release notes 作为 body；pre-release 自动打 prerelease 标志

维护者：一键发版

整套流程脚本化在 scripts/release.sh：

# 首次仅需：确保本机有 python3.11 + gh
# Linux: sudo apt install python3.11 python3.11-venv gh
# macOS: brew install gh
gh auth login                              # GitHub CLI（首次）

# release.sh 会自动创建/复用 .venv311，自动安装 build/twine/pytest 工具链
# 并在脚本退出时自动 deactivate

# 交互式发版（推荐）
./scripts/release.sh
#   → 测试 + 构建 → 选 patch/minor/major + release/beta/rc → 二次确认
#   → cut CHANGELOG → 同步版本号 → commit + tag → push → 上传 PyPI → 发 GitHub Release

# 非交互（CI / 直接命令）
./scripts/release.sh -y patch release      # 一键稳定版小版本发布（最常用）
./scripts/release.sh patch                 # X.Y.Z → X.Y.(Z+1)，release 通道
./scripts/release.sh minor beta            # X.Y.Z → X.(Y+1).0b1
./scripts/release.sh patch beta            # 已经在 beta 上则 b1 → b2

# 排练（不 push、不上传，只走 git 本地）
./scripts/release.sh --dry-run minor

# 上 TestPyPI 试一次
./scripts/release.sh --testpypi patch beta

脚本会做严格的前置检查（必须在 main 分支、工作区干净、tags 已 fetch、依赖工具齐全、[Unreleased] 非空），任一不满足直接退出。

详细发布文档见 DEV.md 的“发布流程（脚本化）”章节。

---

🛣️ 路线图

阶段	内容	状态
P0	数据布局、ClawTeam/OpenClaw 集成、列表式 Flow 编辑、调度引擎、本地模式	🚧 进行中
P1	失败策略、Profile UI、模板互通、Human Gate 节点	📅 规划
P2	React Flow 拖拽画布、企业服务端模式、垂直模板市场	📅 规划
P3	更多 OpenClaw skills（监控、批量、统计）	💡 探索

---

📄 License

MIT