# a2p2a （测试中 · alpha）

**把手上零散的 AI 接进同一个工作区，让它们分工把活干完。**

你手上可能已经有 Claude Code、Codex、Hermes、小龙虾 OpenClaw 这些命令行 AI，它们各干各的，互不相识。
a2p2a 做的事很朴素：**把它们接进同一个工作区，配上几个角色**，你说一句需求，它们自己聊清楚、分工、干活，过程你在群里看得见。

```
你说想法 → 秘书追问到清楚 → 目标进工作群 → 管理挑人派活 → 工人真干活 → HR 打分复盘
```

> **现在是什么状态**：能跑通完整链路（已实测），但还在早期，接口和界面都会改。
> 下面「现在已实现」是如实清单，「还没做」也一并列出来，免得你踩坑。

## 愿景（目标是这个，不是现在）

> **一个多智能体与人类共同协作的平台 —— 搭起属于自己的一人公司：让智能体高效、可靠地运行，让创意可以无限发挥。**

现在的 a2p2a 只是朝这个方向的第一步：先把「接进来、分好工、能干活、看得见」跑通。
一人公司要靠的是**可靠的编排 + 可复盘的评价**，这两块还在早期。

## 现在已实现（都是实测过的）

| 能力 | 现状 |
|---|---|
| 接入智能体 | 一条命令行模板，或一个 MCP 地址；**本机自动检测**（小龙虾 / Claude Code / Codex / Hermes / OpenCode / Aider）可一键接入；接上后它会**自报能力** |
| 智能体库 | 智能体是**全局通用**的：导入一次，多个工作区按需选用；角色（秘书/管理/HR/工人）在工作区里指定；需要更多窗口就**派生**一个（连接方式照抄） |
| 三个开关 | 秘书模式 / AgentBus / HR，**每个工作区独立**；关掉 AgentBus 就是**单 agent 直接干完**，没有中间环节 |
| 秘书 | 由你接进来的某个成员扮演：跟你**追问、把想法聊清楚**，确认后把**归纳好的目标**发到工作群 |
| 管理（主代理） | 只在 AgentBus 模式参与：按**能力标签 + 智能程度 + 价格分**挑人，选流程派活，并在群里说明为什么这么派 |
| HR | 按节拍打分（每 N 次任务，或你说「分析」）：硬性（耗时/上下文）、能力、智能程度（报错返工）、价格；报告进群 |
| 工作群 | **只给人看**：AI 之间走总线，聊天记录不污染 AI 上下文；消息带头像/用户名/类型，按任务折叠，可切「只看人话/看全部」 |
| 跟单个智能体 | 可以直接对话（测试用），也可以下**调整类干预**（配色/风格/重做这一步）；改输出或改流程的请求会被拒绝 |
| 内置智能体 | 自带一个跑在本机的：**执行命令行、读写文件、发群消息、调内部能力**（看成员/进度/分数、派流程、让 HR 打分）。填个模型 API 就能用 |
| 编排内核 | 流程 = 一份 JSON 文档；积木（秘书/分发器/CC工人/Hermes会话/汇总/审批）一个文件一个；支持**并行调度、重试、超时、输入瘦身、审批挂起与续跑、运行痕迹** |
| 自调优 | 读痕迹出**改进建议**（只建议，不自动改） |
| MCP 控制面 | 对外暴露 14 个工具，外部智能体（含 CC/Codex）能操控本系统，也能**自我注册**进来 |
| 界面 | 三栏 + 顶部标签；管理界面 5 页；多语言（中/英，语言包可插）；主题（浅/深/随系统）；附件上传；安全清空 / 恢复出厂 |
| 部署 | 一条 `bash start.sh` 起服务（自动装依赖）；数据全在 `data/a2p2a.db`，拷走即带走；`package.sh` 打发布包，`publish.sh` 建仓推送 |

## 还没做（诚实清单）

| 没做 | 说明 |
|---|---|
| 手机 APP | 计划中 |
| 技能 / MCP 深度绑定 | 计划中 |
| 自动改架构 | 自调优目前只**出建议**，不改流程；流程编辑器（画布）已删掉，不做 |
| 聪明的内置角色 | 秘书/管理/HR 的"聪明程度"取决于你接进来的那个 agent；内置智能体是基础版 |
| 挑人规则 | 单 agent 模式目前只按「空闲 + 价格分」挑，标签匹配还在早期 |
| 多用户 / 权限 | 单机单人设计，没有账号体系 |
| 平台验证 | 只在 Linux/WSL 实测过；Windows 原生（非 WSL）环境未验证 |

## 和别的方案比，差别在哪

| 别人 | a2p2a |
|---|---|
| 要求你把 agent 用它的 SDK 重写一遍 | **不改你的 agent**：一条命令或一个 MCP 地址就接进来 |
| 编排写成只有它能读的图 / 只有你懂的脚本 | 编排是 **一份 JSON 流程文档**，人和 AI 都能读写 |
| AI 聊天记录当成 AI 的上下文，越跑越贵 | **群只给人看**：AI 之间走总线，上下文干净 |
| 只能自己给自己派活 | **真的派活干活**：能跑命令行、改文件、调工具，不等你点确认 |
| 装完是空壳，还得自己配模型、配 agent | **自带一个本地智能体**：填个模型 API 就能跑命令行；本机已有的 agent 一键接入 |

## 30 秒上手

**装好 Node.js 就能一行跑**（跟 deepseek-harness 一样的用法）：

```bash
npx a2p2a
```

它会自己找（或装）Python、建好依赖、起服务并打开浏览器 —— 前端已经预构建在包里，**你不需要装 Node 之外的任何东西**。
数据存在 `~/.a2p2a/`，换版本、清缓存都不丢。

或者解压发布包双击启动（**只用 Python**，不需要 Node）：



**哪个系统都能起**（第一次自动装依赖，然后打开 http://localhost:8080 —— **前端已打包在里面，不需要 Node.js**）：

| 系统 | 怎么起 | 缺 Python 时 |
|---|---|---|
| **Windows** | 双击 `start.bat` | 自动装：优先 `winget install Python.Python.3.12`，没 winget 就下载官方安装器静默安装（装完重新双击一次） |
| **macOS** | 双击 `start.command` | 有 Homebrew 就 `brew install python`；否则弹 Xcode 命令行工具安装，或去 python.org 下安装包 |
| **Linux / WSL** | `bash start.sh` | 自动用 apt / dnf / pacman / zypper 装 `python3 python3-venv`（要 sudo 密码） |

> 三个入口都是同一个跨平台启动器 `start.py` 的外壳：建 `.venv` 装后端依赖 → 起服务 → 自动开浏览器。
> 后端**直接托管打包好的前端**，所以普通用户只需要 Python，不需要 Node.js，也不需要 WSL。

1. 左栏「**内置智能体**」→ 填模型线路（地址 / Key / 模型名）→ 启用（它就能跑命令行、读写文件、发群消息）
2. 左栏「**导入智能体**」→ 点「本机检测到的」里任意一个（小龙虾 / Claude Code / Codex / Hermes / OpenCode）一键接入
3. 「**管理界面 → 分工表**」→ 指定谁当秘书、谁当管理、谁当 HR
4. 回「秘书」标签说一句需求，或直接在「主工作群」里下命令

> 目录里那个 `data/` 是你的全部数据（工作区、成员、分数、记录）。拷走它就全带走了；删掉它就是全新一套。

## 三个开关（每个工作区独立）

| 开关 | 开 | 关 |
|---|---|---|
| 秘书模式 | 秘书跟你聊、追问，确认后把目标发到工作群 | 你直接面对工作群 |
| AgentBus | 管理智能体挑人派活（多 agent 编排） | 单 agent 模式：一个成员直接干完 |
| HR | 按节拍（每 N 次任务 / 你说分析）打分复盘 | 不打分 |

## 参考文献

| 文档 | 给谁看 |
|---|---|
| [`docs/dev/`](docs/dev/index.md) | **开发者**：架构 / 怎么写积木 / 流程格式 / 接口 / 接智能体 / 改动约定 / 路线图 |
| [`docs/publish.md`](docs/publish.md) | 发布流程（建仓推送、Release、topics） |
| [`docs/launch.md`](docs/launch.md) | 宣传文案与发帖计划 |

## 三个规矩（这就是全部设计）

| 规矩 | 落点 |
|---|---|
| **文档即流程** | 一条流程 = `flows/*.flow.json`（节点 + 连线 + 位置），AI 和人都能读写 |
| **一个积木一个文件** | `blocks/*.py`，继承 `Block`，只写 `inputs`/`outputs`/`run()`，导入即注册 |
| **痕迹落盘** | 每次运行写 `trace/<run_id>.jsonl` + `state-<run_id>.json`，这是自调优的燃料 |

## 用法

```bash
cd a2p2a

python run.py plan    flows/demo_offline.flow.json                 # 干跑：只看计划
python run.py run     flows/demo_offline.flow.json --input 用户消息="甲。乙"
python run.py run     flows/secretary_workers.flow.json --input 用户消息="…"   # 真干活（Claude Code）
python run.py approve trace/state-<run_id>.json --flow flows/approval_demo.flow.json --node 审批 --decision yes
python run.py evolve  flows/demo_offline.flow.json                 # 读痕迹，出改进建议
```

## 配置项（写在流程文档里，改了就有用）

| 配置 | 写在哪 | 作用 | 默认 |
|---|---|---|---|
| `max_parallel` | 流程顶层 | 同时最多跑几个节点（1 = 完全串行） | 4 |
| `retry` / `retry_delay_s` | 节点 `config` | 失败自动重试次数与间隔 | 0 / 2s |
| `timeout_s` | 节点 `config` | **runtime 层强制超时**（积木自己死循环也拉得回来） | 3600 |
| `max_input_chars` | 节点 `config` | 给这个节点的单个文本输入设上限（超出截断并记痕迹） | 6000 |
| `max_list_items` | 节点 `config` | 列表输入的条数上限 | 8 |
| `max_output_chars` | 节点 `config` | 产出进下游/痕迹前的截断上限 | 20000 |
| `auto_approve_low_risk` | **审批节点** `config` | 低风险动作自动放行，只拦高风险 | false |

## 上下文纪律（工人的上下文很短）

| 手段 | 谁做 |
|---|---|
| **一次只发一条任务**：清单 → 分发器(序号) → 各工人一条 | `blocks/dispatcher.py` |
| **输入自动瘦身**：超长文本截断、超长列表截条数，并在痕迹里留 `node_input_trimmed` | `runtime._trim_payload` |
| **产出自动截断**：进下游和痕迹前按 `max_output_chars` 截 | `runtime._trim_outputs` |
| **痕迹只存摘要**：每条事件里的内容截到 160 字，长正文留在产出里 | `runtime._brief` |

## 目录

| 路径 | 干什么 |
|---|---|
| `kernel/block.py` | 积木基类 + 注册表（借 Langflow 的 Component 设计） |
| `kernel/flowdoc.py` | 流程文档：加载 / 校验 / 拓扑排序 / 装配输入 |
| `kernel/runtime.py` | 执行器：调度、状态、痕迹、审批挂起与续跑 |
| `kernel/evolve.py` | 自调优 v0：读痕迹出建议（只建议，不自动改） |
| `blocks/` | 积木：秘书 / CC 工人 / 模拟工人 / 汇总 / 审批 |
| `flows/` | 流程文档：离线演示 / 真干活 / 审批闸门 |
| `trace/` | 运行痕迹与状态（自调优读这里） |
| `evolve/` | 生成的改进建议 |

## 节点状态（统一词表）

`idle → running → done / failed / waiting_approval / waiting_input / waiting_upstream`

- **waiting_approval**：要人点头 → 第 3 步把所有这类节点汇总起来，就是「集中审批收件箱」
- **waiting_input**：缺必填输入
- **waiting_upstream**：上游没跑完（含挂起），下游就等，不拿占位数据硬跑

## 自调优怎么长（v0 → vN）

v0 规则表在 `kernel/evolve.py` 的 `analyze()` 里，现在四条：反复失败 / 单节点太慢 / 反复等人 / 输入槽没接上。
往后每加一条规则就是加一个"看到这种痕迹就建议这么改"的映射；等你愿意让它自动改时，把 `propose()` 的输出直接喂给 AI 改 `flows/*.json`，再用 `plan` 干跑 + 回归样例把关即可。

## 参考与取舍

| 借来的 | 自己写的 |
|---|---|
| 积木抽象（inputs/outputs + 干活方法） | 组织语义（秘书/工人/汇报） |
| 流程文档结构（节点 + 连线 + 位置） | 双通道（聊天与干活分开） |
| 状态挂在节点上、实时可见 | 集中审批收件箱 |
| 循环/条件/工具的积木思路 | 按痕迹自调优 |


## 给别人用（发布版）

```bash
bash start.sh          # 起后端 :8080 + 前端 :5173（第一次会自动装前端依赖）
# 打开 http://localhost:5173
```

第一次用只有两步：

| 步骤 | 在哪做 | 填什么 |
|---|---|---|
| 1 | 左栏「**导入智能体**」 | 一条命令（或一个 MCP 地址），比如你自己的 `claude -p …`。接上后它会自报能力 |
| 2 | 「管理界面 → 分工表」 | 把接进来的成员指定角色：谁当**秘书**、谁当**管理**、谁当 **HR**（一个角色一个） |

**a2p2a 自己不配模型** —— 秘书 / 管理 / HR 都是用你接进来的成员在干活，它们用各自的接法。
所有数据都在 `data/a2p2a.db` 里：拷走它就带走了工作区、成员、分数和记录；删掉它就是全新的一套。

安全：左栏「设置 → 安全 / 清空」里可以「清空所有记录」或「恢复出厂」，都要先输入「删除」两个字。

## 目录

| 路径 | 干什么 |