wanman

wanman：让 AI Agent 矩阵自主协作的开源运行时框架

开篇故事：单人列车启发的 AI 协同实验

想象一下，早高峰的东京地铁进站——列车缓缓停靠，车门打开又合上，全程只有一名司机在驾驶室操作，没有车掌来回巡视。日本人把这种「一人独立完成全程」的模式叫做「ワンマン電車」（一人列车）。如今，一位名叫 chekusu 的开发者将这个意象搬进了 AI 世界：让人类退居观察席，由多个 AI Agent 自动协作完成复杂任务，而不需要人类时刻盯着每一个 Agent 在做什么。

这个项目就是 wanman。

项目背景：从「AI 编程助手」到「AI 团队协同」

2024 年之后，以 Claude Code、OpenAI Codex 为代表的 AI 编程工具逐渐成熟。但这些工具本质上是单兵作战——一个人类用户指挥一个 Agent，Agent 完成代码编写或调试任务。这在简单场景下够用，但遇到需要产品设计、架构决策、代码实现、测试验证多环节配合的复杂项目时，单个 Agent 的能力就捉襟见肘。

wanman 的出现正是为了解决这个问题。它的核心命题是：如何让多个 AI Agent 像一个团队一样协同工作？ 具体来说，它让人类扮演「旁观者/调度者」角色，通过 CLI 向 Agent 矩阵下达任务，由多个专业化 Agent（CEO、dev、devops、marketing 等）分别处理不同环节，最后将结果汇总反馈给人类。

核心功能：JSON-RPC Supervisor 协调的多 Agent 架构

wanman 的架构设计非常清晰，分为三层：

第一层：Supervisor（监督进程）

Supervisor 是整个系统的中枢，运行在本地 Node.js 进程上，监听 localhost:3120 的 HTTP JSON-RPC 请求。它内部维护了多个关键存储组件：

• MessageStore：消息队列，管理 Agent 之间的通信
• ContextStore：共享上下文，Agent 可以读取/写入共享数据
• TaskPool：任务池，跟踪每个任务的状态和分配
• ArtifactStore：产物存储，存放 Agent 生成的文档、代码、报告等结构化产物
• InitiativeBoard：倡议板，管理跨 Agent 的长期目标
• CronScheduler：定时调度器，触发周期性任务

Supervisor 通过 JSON-RPC 协议与各 Agent 通信，所有消息都经过 Supervisor 路由和记录，确保整个协作过程可观测、可回放。

第二层：Agent 运行时

每个 Agent 以 Claude Code CLI 或 Codex CLI 子进程形式运行。wanman 不重新实现 LLM 调用逻辑，而是直接调用官方 CLI 的认证和能力。Agent 运行在独立的 Git worktree 中，并拥有隔离的 $HOME 目录，确保 Agent 的操作不会污染主项目的源代码或用户的 shell 环境配置。

Agent 有三种生命周期模式：

• 24/7 连续运行：Agent 循环接收消息 → 启动 CLI 子进程执行 → 等待退出 → 休眠后重试。这种模式适合需要持续待命的角色（如 CEO、feedback agent）。
• 按需触发（on-demand）：Agent 空闲等待，直到被 steer 指令或定时任务唤醒，执行一次后重新进入空闲。
• 空闲缓存（idle_cached）：介于两者之间，Agent 被唤醒时利用 Claude Code 的 session 恢复机制，保持对话上下文的连续性，同时不需要持续消耗计算资源。注意：这是 Claude Code 独有特性，Codex 不支持。

第三层：CLI 客户端

wanman CLI 是用户与 Supervisor 交互的界面，支持以下核心命令：

wanman send <agent> <message> [--steer]   # 向 Agent 发送消息，--steer 可打断当前任务
wanman recv --agent <name>                # 收取 Agent 的回复
wanman agents                             # 查看所有 Agent 及其状态
wanman task create <title>                 # 创建任务
wanman artifact list                      # 查看 Agent 生成的产物
wanman watch                              # 实时监视 Supervisor 事件流
wanman takeover <git-repo>                # 接管一个 Git 仓库，启动 Agent 矩阵

整个协作流程是：用户 wanman takeover . 启动 Supervisor 和 Agent 矩阵 → 用户在另一个终端用 wanman send 分配任务 → Supervisor 调度对应 Agent → Agent 通过 CLI 执行（读写文件、调用工具）→ 结果写回 ArtifactStore → 用户 wanman recv 收取回复。

技术架构：TypeScript monorepo + pnpm workspaces

wanman 采用 TypeScript monorepo 架构，使用 pnpm workspaces 管理多包依赖：

包	说明
@wanman/core	核心库：类型定义、RPC 协议实现、Agent 注册表
@wanman/runtime	运行时引擎：Supervisor 主进程、SQLite 持久化、WebSocket 通信、CLI 子进程管理
@wanman/cli	命令行工具：用户侧交互界面，支持 wanman 命令集
@wanman/host-sdk	主机 SDK：用于将 wanman 集成到其他 Node.js 应用
@wanman/finops	财务运营工具包：API 凭证清点、成本核算、Stripe 收入对账、产品 ROI 分析

技术栈选型：

• Runtime：Node.js >= 20，TypeScript，强类型保证
• 持久化：better-sqlite3（轻量嵌入式数据库），ws（WebSocket 通信）
• 构建：esbuild（CLI 打包）、turbo（monorepo 构建编排）、vitest（测试）
• 可选依赖：@sandbank.dev/db9（跨运行记忆适配器）

部署体验：纯 CLI，手动安装门槛中等

wanman 是一款纯命令行工具，不提供 Web UI 或 Docker 容器。部署流程如下：

1. 安装 Node.js >= 20 和 pnpm >= 9
2. git clone git@github.com:chekusu/wanman.git && cd wanman && pnpm install && pnpm build
3. 安装 Claude Code CLI（npm install -g @anthropic-ai/claude-code）并完成 claude 登录
4. wanman takeover <git-repo> 启动

整个过程约 10-15 分钟，对于有 Node.js 开发经验的工程师来说不算困难。但需要手动安装并认证 Claude Code/Codex CLI 是最主要的门槛——这要求用户拥有 Anthropic/OpenAI 的 API 账号且完成认证流程，这对非 AI 开发者的普通用户有一定阻碍。

不支持一键部署，因为项目不提供 Dockerfile 或 docker-compose.yml，且核心功能依赖本地 CLI 子进程管理，容器化并不能简化使用体验。

FinOps 工具包：从 Agent 协作到成本管控

wanman 还附带了一个 @wanman/finops 工具包，解决的是「跑了这么多 Agent，到底花了多少钱」这个问题。它支持：

• API 凭证清点：扫描代码仓库中的环境变量，识别引用了哪些付费 API（Anthropic、OpenAI 等）
• 成本核算：按产品维度统计指定账期的 API 花费
• Stripe 收入对账：同步 Stripe 收入数据，对比成本与收益
• ROI 分析：生成产品级投资回报率摘要

这套工具对于需要在本地运行大量 Agent 任务、成本敏感的团队很有价值。

局限与争议

1. 依赖官方 CLI 认证：wanman 本身不管理 LLM 认证，完全依赖 Claude Code/Codex CLI 的认证状态。一旦 CLI token 过期，整个 Agent 矩阵将无法运行。
2. Claude Code 独占特性：idle_cached 模式（会话恢复）只有 Claude Code 支持，Codex 用户无法享受这一优化。
3. 无 Web UI：所有交互通过命令行，对非技术用户不够友好。
4. Supervisor 单点：所有 Agent 通信经过 Supervisor，如果 Supervisor 崩溃，所有 Agent 协作状态可能丢失（虽然 SQLite 提供了部分持久化）。

行业意义：多 Agent 协作的开源范式探索

wanman 代表了 2025-2026 年 AI Agent 领域的一个重要趋势：从「单 Agent 执行」向「多 Agent 协作」的范式升级。它的设计理念——Supervisor 协调、Agent 隔离、JSON-RPC 通信——与主流的多 Agent 框架（如 AutoGen、LangChain Agents）有相似之处，但 wanman 的独特定位是「本地化 + 轻量化」，不依赖任何云服务，用户完全掌控数据和计算。

结合每月约 200+ stars 的增长趋势和 GitHub 上 641 stars 的成绩，wanman 正在成为 AI 开发者群体中一个值得关注的技术实验。