Metadata-Version: 2.4
Name: clawsomeflow
Version: 0.1.1b12
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 工作流编排平台。  
> 你只需要用自然语言描述目标，ClawsomeFlow 负责把多 Agent 协作变成可控、可观测、可收敛的工程系统。

`Python 3.11+` `FastAPI` `React` `ClawTeam` `OpenClaw` `DAG Scheduler`

[为什么是 ClawsomeFlow](#-为什么是-clawsomeflow) · [核心特性](#-clawsomeflows-key-features) · [架构](#-架构总览) · [快速开始](#-快速开始) · [路线图](#-路线图)

---

## 📰 News

- **2026-05**：调度模型稳定在“服务端主动派发”范式，默认抑制 Prompt 轮询自调度。
- **2026-05**：OpenClaw 路径完成深度适配：会话隔离、工作目录隔离、并发冲突治理。
- **2026-05**：投诉闭环进入主流程：Run 可从用户投诉反哺为结构化改进任务。

---

## ✨ ClawsomeFlow's Key Features

| 🌳 OpenClaw 深度适配 | 🧠 AI + 精确编排 | 🗣️ 自然语言完成所有工作 | 🔄 投诉闭环机制 |
|---|---|---|---|
| 解决 OpenClaw 多任务并行中的会话边界不清与 workspace 并发冲突。<br>每个 Run / Agent 都有稳定隔离语义。 | 把控制流从 Prompt 拿回代码：调度器决定派发、重试、超时、收敛。<br>行为更可控，显著减少无效 token 消耗。 | Flow 定义、Agent 创建、任务编排、运行干预，都可通过自然语言在 UI/CLI 完成。 | Run 支持“用户投诉 → 反思处理 → 回写经验”的闭环机制，形成持续自增长。 |

| 🚀 多 Agent 协同 | 📊 企业级可观测性 | 🔐 隔离与治理并重 | 🧩 与现有生态兼容 |
|---|---|---|---|
| 支持 OpenClaw / Claude / Codex / Gemini / Kimi / Qwen / OpenCode / Nanobot 同图协同。 | 每个 dispatch/completion/failure 都记录为 RunEvent，可审计、可回放、可计费。 | team/session/worktree 三层隔离，避免串扰与误写。 | 不重造协议层，沿用 ClawTeam CLI + MCP，并复用其监控面板能力。 |

---

## 🤔 为什么是 ClawsomeFlow？

多 Agent 框架常见痛点不是“模型能力不足”，而是“协作控制流不稳定”：  
流程写在 Prompt 里，最终行为取决于 Agent 当下理解和模型质量，系统可预测性、成本和恢复能力都不够强。

ClawsomeFlow 的核心方法很直接：

- **把协调从自然语言迁回代码**：LLM 负责单点任务，调度器负责全局编排。
- **把并发与隔离做成默认能力**：同一团队并行、多 Run 并行、OpenClaw 并行都能稳定落地。
- **把失败处理做成流程内建**：失败信号、重试策略、用户投诉统一进入收敛通道。

### 四个你会立即感知到的差异

1. **深度适配 OpenClaw，协同稳定性优先**  
   针对 OpenClaw 多任务并发的会话隔离模糊和 workspace 并发访问冲突，ClawsomeFlow 在调度层做了会话与目录双隔离，并且将恢复路径纳入标准状态机。

2. **从 Prompt 驱动到精确编排，行为更可控**  
   ClawTeam 原生模式偏 Prompt 协议驱动，worker 行为受模型状态影响较大；ClawsomeFlow 则由服务端调度器主动派发，重试/跳过/中止由明确策略执行，显著减少轮询 token 开销。

3. **自然语言完成从定义到治理的全链路**  
   你可以用自然语言定义 Flow、创建 Agent、下发运行目标、做人工干预，不需要手写复杂编排脚本。

4. **投诉闭环让系统“越跑越懂你”**  
   在 `awaiting_user_complaint` 阶段接收反馈后，系统会进入投诉处理并沉淀经验，形成可持续反思与改进机制。

#### ✨ The Result?

你负责目标，ClawsomeFlow 负责把多 Agent 协同执行做成稳定系统。

---

## 🎯 ClawsomeFlow In Action

### 1) 用自然语言定义 Flow，系统自动编译为 DAG

用户给出业务目标后，平台自动完成任务分解、依赖关系建立、执行编排和状态跟踪。

```text
用户目标（自然语言）
  -> Flow 结构化定义
  -> DAG 编译与校验
  -> 多 Agent 并发执行
  -> Leader 汇总交付
```

### 2) 调度器主动派发，替代 Worker Prompt 轮询

```text
RunController tick loop
  -> 拉取 task + inbox 快照
  -> 识别 ready 任务
  -> 按 session 状态选择 inject / resume / spawn
  -> 记录 RunEvent 并收敛失败
```

### 3) 用户投诉进入闭环，推动经验自增长

```text
awaiting_user_review
  -> awaiting_user_complaint
  -> complaint_processing
  -> completed / completed_with_conflicts / failed
```

### 对比：Prompt 自调度 vs ClawsomeFlow 服务调度

| 维度 | Prompt 自调度（常见模式） | ClawsomeFlow |
|---|---|---|
| 控制流位置 | 在 Prompt 中，依赖模型解释 | 在代码中，确定执行 |
| 并发治理 | Agent 自轮询，易竞争 | 调度器统一编排，边界清晰 |
| OpenClaw 稳定性 | 会话与 workspace 冲突风险高 | 会话隔离 + worktree 隔离 + 恢复路径 |
| 失败恢复 | 依赖 Agent 临场发挥 | retry/skip/abort 明确策略 |
| Token 成本 | 轮询开销高 | 按需派发，显著降低无效消耗 |
| 可审计性 | 黑盒上下文居多 | 全链路 RunEvent 可追踪 |

---

## 🧩 与 ClawTeam / OpenClaw 的关系

```mermaid
flowchart LR
    user[用户] -->|Web UI / NL| CSF[ClawsomeFlow]
    CSF -->|CLI + MCP| CT[ClawTeam 协议层]
    CSF -->|Gateway / Agent API| OC[OpenClaw 运行时]
    CT -->|spawn/inject| Agents[Claude / Codex / OpenClaw / ...]
    OC -->|session 执行| Agents
```

| 层 | 职责 | 所属 |
|---|---|---|
| 协议层 | team/task/mailbox/workspace 语义 | ClawTeam |
| 运行时层 | 单个 Agent 执行容器 | OpenClaw / Claude / Codex / ... |
| 编排层 | DAG 调度、失败收敛、终态处理 | ClawsomeFlow |
| 产品层 | Web UI、多用户、NL Agent 治理 | ClawsomeFlow |

---

## 🏗️ 架构总览

```mermaid
flowchart TB
    subgraph FE[Frontend]
        UI[Flow Editor / Run Panel / Agent 管理]
    end

    subgraph BE[ClawsomeFlow Backend]
        API[REST + WebSocket]
        SCH[FlowScheduler + RunController]
        BRIDGE[OpenClaw Bridge]
    end

    subgraph EXT[External Runtime]
        CT[ClawTeam CLI/MCP]
        OC[OpenClaw]
    end

    subgraph DATA[Data]
        CSFHOME[~/.clawsomeflow]
        DB[SQLite]
    end

    UI <--> API
    API --> SCH
    API --> BRIDGE
    SCH --> CT
    BRIDGE --> OC
    API --> CSFHOME
    API --> DB
```

---

## 🚀 快速开始

当前对外默认推荐 **local 模式**（单机稳定优先）。

### 安装与启动

```bash
# 推荐：直接安装并启动
pip install -U clawsomeflow && csflow start

# 方案 2：安装到受控用户 venv
scripts/install_clawsomeflow.sh
~/.clawsomeflow/.venv/bin/csflow start

# 方案 3：一键托管（含后台服务）
bash scripts/install-user.sh --yes
```

### 你将得到什么

- 自动依赖检查与初始化（Python/git/tmux/node/clawteam/openclaw）。
- 自动创建并维护 `~/.clawsomeflow/` 数据目录。
- 自动配置后台服务（Linux `systemd --user` / macOS `launchd`）。
- 自动部署 OpenClaw 相关通用 tools 与 skills 运行资源。

### 常用命令

```bash
# 生命周期
csflow start
csflow stop
csflow status
csflow doctor

# Flow / Run
csflow flows list
csflow runs list
csflow runs start <flow-id> --input k=v
csflow runs abort <run-id>

# Agent 治理
csflow agents list
csflow agents create "用自然语言描述你要的 Agent"
csflow agents chat <agent-id> "继续完善该 Agent 的能力"

# 调试
csflow logs tail -f
csflow logs verify-anti-loop
```

---

## 📂 数据布局（关键路径）

```text
~/.clawsomeflow/      # ClawsomeFlow 自身数据（配置、runs、flows、agents）
~/.clawteam/          # ClawTeam 状态与 worktrees
~/.openclaw/          # OpenClaw 运行时状态
```

三者分工明确、互不覆盖：  
ClawsomeFlow 不直接接管 ClawTeam worktree，也不把 OpenClaw 运行态混写进自身目录。

---

## 🗺️ 路线图

| 阶段 | 内容 | 状态 |
|---|---|---|
| **P0** | 调度引擎、OpenClaw 深度适配、本地模式稳定化 | 🚧 进行中 |
| **P1** | 失败策略增强、Profile 能力、Human Gate 节点 | 📅 规划 |
| **P2** | 可视化 DAG 画布、企业服务端模式、多用户协作深化 | 📅 规划 |
| **P3** | 更丰富的 Agent 技能生态与自治治理能力 | 💡 探索 |

---

## 📄 License

MIT
