Metadata-Version: 2.4
Name: clawsomeflow
Version: 0.1.1b4
Summary: Vertical agent workflow orchestration platform on top of ClawTeam and OpenClaw
Project-URL: Homepage, https://github.com/clawsomeflow/clawsomeflow
Project-URL: Repository, https://github.com/clawsomeflow/clawsomeflow
Project-URL: Issues, https://github.com/clawsomeflow/clawsomeflow/issues
Author: ClawsomeFlow Contributors
License: MIT
Keywords: agent,ai,clawteam,openclaw,orchestration,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: anyio<5.0.0,>=4.0.0
Requires-Dist: clawteam>=0.2.0
Requires-Dist: fastapi<1.0.0,>=0.110.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: questionary<3.0.0,>=2.0.1
Requires-Dist: rich<15.0.0,>=13.0.0
Requires-Dist: sqlmodel<1.0.0,>=0.0.16
Requires-Dist: structlog<26.0.0,>=24.0.0
Requires-Dist: typer<1.0.0,>=0.12.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.27.0
Requires-Dist: watchfiles<2.0.0,>=0.21.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov<6.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == 'release'
Requires-Dist: twine>=5.0.0; extra == 'release'
Provides-Extra: server
Requires-Dist: asyncpg<1.0.0,>=0.29.0; extra == 'server'
Requires-Dist: gunicorn<23.0.0,>=21.0.0; extra == 'server'
Requires-Dist: redis<6.0.0,>=5.0.0; extra == 'server'
Description-Content-Type: text/markdown

# ClawsomeFlow

> Make your multi-agent workflow Clawsome.
>
> 在 [ClawTeam](https://github.com/HKUDS/ClawTeam) 与 [OpenClaw](https://github.com/openclaw/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 的关系

```mermaid
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** |

---

## 🏗️ 架构总览

```mermaid
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 状态机

```mermaid
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 |

### 调度时序

```mermaid
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。

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

```bash
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，并配置用户级后台服务

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

```bash
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](frontend/README.md#internationalisation-i18n)。

### CLI 命令速查（更多见 [DEV.md](DEV.md)）

```bash
# 生命周期
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 集成并保留数据；可加 --thorough 彻底卸载
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、执行 `csflow upgrade --yes --force` 并启动服务；发布后用户请走远程脚本 |
| 用户正式部署（后台 + 开机自启） | `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` | 仅删 managed-agent 注册信息及对应 `openclaw.json` agents；**`~/.clawsomeflow/` 完整保留**，重装即可恢复 |
| 彻底卸载（含数据目录） | `csflow uninstall --thorough` | 在完成 OpenClaw 反注册后删除整个 `~/.clawsomeflow/` |
| 彻底删干净 | `csflow purge-data` | 列出每个目录大小让你确认 → 要求打字 `PURGE` → 删整个 `~/.clawsomeflow/`；**后台运行中会拒绝** |
| 降级（开发场景）| `pip install clawsomeflow==<旧版>` 然后 `csflow upgrade --force` | warn 后强行重跑 upgrade 流程；schema 只支持 forward-compatible，必要时手动备份 DB |

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

---

## 📦 版本发布与预览通道

ClawsomeFlow 遵循 [SemVer 2.0](https://semver.org/) + [PEP 440](https://peps.python.org/pep-0440/)：

| 通道 | 版本号示例 | 用户安装命令 | 何时使用 |
|---|---|---|---|
| **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`](CHANGELOG.md) 抽取该版本的 release notes 作为 body；pre-release 自动打 `prerelease` 标志

### 维护者：一键发版

整套流程脚本化在 [`scripts/release.sh`](scripts/release.sh)：

```bash
# 首次仅需：确保本机有 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](DEV.md) 的“发布流程（脚本化）”章节。

---

## 🛣️ 路线图

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

---

## 📄 License

MIT
