OPEN SOURCE DEEP DIVE
Paseo:把 Claude Code / Codex / Copilot 等 coding agent 装进同一个自托管驾驶舱
自托管的多编码 Agent 编排平台(20.9k stars):Claude Code、Codex、Copilot、OpenCode、Pi、Antigravity、Muse Code 走同一界面,跑在你自己的机器与完整 dev 环境里;本地 daemon(WebSocket + 33 个 MCP 工具)统一编排,Electron 桌面 / Expo iOS·Android / Web / CLI 四端接入,git worktree 并行隔离、语音默认本地 ONNX、端到端加密 relay 远程跟进;monorepo 含 plugin registry、skills 与 Hub 生态,Apache-2.0。
一句话定位:把「多个 coding agent」收进同一台可以随身带的机器
Paseo 给自己的定义是 agentic development environment(ADE):它不是又一个 coding agent,而是把你已经装好、已经付费的那些 agent——Claude Code、Codex、Copilot、OpenCode、Pi、Antigravity、Muse Code——收进同一个界面里跑、看、管、合并。它跑在你自己的机器上,用你自己的工具、配置和 skills;Electron 桌面、Expo 原生 iOS/Android、Web、CLI 四种客户端连的是同一个本地 daemon。README 的第一句话就是它的立场:One interface for Claude Code, Codex, Copilot, OpenCode, Pi, Antigravity, and Muse Code agents.
和 Orca、herdr 这一层的产品相比,Paseo 的差异不在「能不能并行跑 agent」,而在三件事:自托管(daemon 在你机器上,代码不出门)、provider 抽象(原生适配器加 ACP 目录,一套接口吃下几十家 agent)、以及把移动端和语音当一等公民(手机上是完整 app 而不是通知壳,语音默认本地 ONNX 推理)。这三条主轴决定了下文所有的架构选择。
基本盘:一岁的仓库,两万星,一百万行 TypeScript
| 指标 | 读数(2026-10-15) |
|---|---|
| stars / forks / open issues | 20,907 / 2,479 / 1,276 |
| 建仓 / 最新版本 | 2025-10-13 / v0.11.2(2026-10-09) |
| 语言 / 许可 | TypeScript / Apache-2.0(GitHub API 读作 NOASSERTION,见下文) |
| monorepo 规模 | 12 个 npm workspace,4,554 个 TS/TSX 文件约 110 万行,其中测试文件 1,714 个 |
| 维护结构 | 单人主导(Mohamed Boudra),GitHub Sponsors 与公司赞助供养 |
几个读数值得停一下。第一,仓库 2025 年 10 月才建,到 2026 年 10 月刚满一年,star 曲线是这一年 agent 工具层最陡的一条之一。第二,license 在 GitHub API 里读作 NOASSERTION,因为 LICENSE 文件头部带了一段第三方代码声明;但 package.json 与文档都写明 Apache-2.0,自动化合规扫描会误报,需要人读文件确认。第三,1,276 个 open issue 对单人维护的项目是真实的运维面,下文「局限」会回到这一点。
架构赌注:一切围绕一个本地 daemon
Paseo 是 client-server 结构,思路和 Docker 同源:daemon 是一个 Node.js 进程,默认监听 127.0.0.1:6767,状态落在 $PASEO_HOME(默认 ~/.paseo)。它负责 agent 进程的生老病死、timeline 实时流、workspace 与 worktree 登记、终端、schedule,以及一个 MCP server。客户端全部是薄的:Electron 桌面 app 托管自己的 daemon 子进程;Expo app 与 CLI 通过 WebSocket 连上去;TypeScript SDK(@getpaseo/client)把同一套能力变成可编程接口。
这个形状带来的直接后果是「代码不出门」:agent 进程、文件、终端都在 daemon 那台机器上,客户端只收 timeline 事件、只发指令。它也解释了为什么移动端能做到完整 app——手机上不需要跑 agent,只需要连到那台跑着 agent 的机器。文档里把这条写成产品承诺:Your code never leaves your machine.
持久化选了文件型 JSON 而不是数据库:所有 store 在 $PASEO_HOME 下,Zod 校验、原子写(先写临时文件再 rename),没有 schema 迁移框架,靠可选字段加默认值做前向兼容。data-model.md 里有一条很硬的自检标准:一个好的 store 方法应该能干净地映射成一条 SQL 语句或一个事务。也就是说作者把 JSON 当实现细节,把 store 接口当未来可以换数据库的契约,而不是把「没数据库」当卖点。
Provider 抽象:六个原生适配器,加三十六项 ACP 目录
README 头条列了七家 agent,但文档里的 native support 只有六项:Claude Code、Codex、OpenCode、Pi、Antigravity、Muse Code;GitHub Copilot 走的是 ACP(Agent Client Protocol)目录,代码里有专门的 copilot-acp-agent.ts 适配器。这个差别值得写清楚,因为它暴露了真实策略:能深度集成的做原生适配器(Claude 走 SDK、Codex 走 app-server 协议、OpenCode 与 Pi 各有适配器),其余一律用 ACP 这个通用协议吃下来。
| Provider | 接入方式 | 备注 |
|---|---|---|
| Claude Code | 原生 SDK 适配器 | MCP、流式、深度推理 |
| Codex | 原生 app-server 适配器 | 沙箱控制、可选联网 |
| OpenCode / Pi | 原生适配器 | 多模型支持 |
| Antigravity | 内置 provider 插件驱动 agy CLI | 唯一永远 full access 的 provider |
| Muse Code | provider 插件,MSP over muse serve | Meta 的终端 agent |
| Copilot / Cursor / Cline / Gemini CLI / goose 等 36 项 | ACP 目录一键安装底层 CLI | Cursor、Kimi、Kiro、TRAE、Copilot 另有专门适配器处理怪癖 |
两条纪律贯穿 provider 层。其一,认证永远在 provider 自己那边:Paseo 不存任何 API key,用量面板(0.11 新增)也只是去读各家 CLI 已有的登录凭证来显示配额。其二,Antigravity 是唯一永远 full access 的 provider——agy 被外部驱动时无法弹权限框,所以 Paseo 用 --dangerously-skip-permissions 启动它,每次会话开头都警告一次。这是一个诚实但刺眼的设计决定,下文局限会再提。
编排:worktree 是隔离单位,MCP 是 agent 之间的语言
并行 agent 的隔离单位是 git worktree:默认落在 $PASEO_HOME/worktrees/ 下按源仓库路径哈希分组的目录里,一个 worktree 一个分支,互不踩。paseo.json 可以挂 setup hook、脚本和常驻服务(每个 worktree 独立端口),teardown 在最后一个引用它的 workspace 归档后才跑。选 worktree 而不是容器或副本,买到的是三样东西:不复制仓库、分支语义免费、合并回主干用开发者已经会的 git 流程。
agent 之间的协作走一个传输中立的 tool catalog,MCP 只是它的一个适配器:daemon 把三十三个工具注册成 MCP server,覆盖 agent 生命周期(create_agent、send_agent_prompt、get_agent_status、list_agents、cancel_agent、archive_agent、kill_agent、update_agent、get_agent_activity、set_agent_mode)、workspace(create_workspace、list_workspaces、rename_workspace、archive_workspace)、脚本与终端、schedule 与 heartbeat、以及 list_profiles。injectIntoAgents 默认关闭,需要手动打开——「agent 指挥 agent」在 Paseo 里不是 prompt 技巧,而是一组有权限边界的 RPC。
再往上是三个降低编排成本的设计:agent profiles 把 provider、model、thinking、mode 存成档案并附「何时使用」笔记,让编排者按笔记选人;schedules 用 cron 起新 agent;heartbeats 周期性给同一个 agent 续话。skills 目录(npx skills add getpaseo/paseo)给了三个开箱工作流:paseo-handoff 把规划与实现交给两家 agent、paseo-advisor 只请顾问不派活、paseo-committee 让两个立场相反的 agent 做根因分析再出方案。
移动端与语音:不是通知壳,是完整 app;语音默认本地
移动端是 Expo 写的原生 iOS 与 Android app,路由、workspace、timeline、终端、diff 全在手机上,和桌面连的是同一个 daemon。所以「在桌上开工、在地铁上跟进」不需要任何同步层——状态本来就在 daemon 那里,手机只是另一个会话。对并行 agent 来说这一点比功能列表更重要:五个 agent 同时跑的时候,稀缺资源是你的注意力,而「 anywhere 都能看一眼、插一句」决定了你要不要回到桌前。
语音是 local-first:STT 默认 parakeet-tdt-0.6b-v2-int8(仅英文),换成 v3 可自动识别 25 种欧洲语言;TTS 默认 kokoro-en-v0_19;两者都是 ONNX、CPU 推理,模型在 daemon 启动时按需下载到 $PASEO_HOME/models/local-speech。语音模式里的「思考」不另起炉灶,而是复用你已装好的 provider(claude、codex 或 opencode)开一个隐藏 agent 会话——凭证和推理都留在你的环境里,不引入第二套云端语音栈。
relay 与信任边界:把「不可信的中继」当设计前提
远程连接推荐走 relay:daemon 主动 outbound 连到中继(官方实现是 Elixir 写的 getpaseo/paseo-relay),手机在中继处与它会合,不需要开端口、不需要端口转发。加密是端到端的:daemon 生成持久 Curve25519 密钥对存在 $PASEO_HOME/daemon-keypair.json,配对二维码或链接携带 daemon 公钥作为信任锚,双方完成 NaCl box(XSalsa20-Poly1305)握手后 daemon 才处理任何命令。中继只能看到 IP、时序、包长和会话 ID,读不了内容、伪造不了消息、也重放不了旧会话。relay 在新安装上默认关闭,配对时才询问是否启用。
直连场景另有两道墙。一道是 Host 头白名单防 DNS rebinding:daemon.hostnames 默认只认 localhost、*.localhost 和所有 IP 地址,文档明说 CORS 不是完整的安全边界。另一道是语义化权限模型:九项权限(daemon.read、daemon.manage、tunnel.manage、access.manage、workspace.read、workspace.write、workspace.manage、automation.manage、hub.execute),principal 与 credential 分离以便轮换与吊销,会话只能收窄不能放大授权,owner、operator、viewer 只是 UI 预设、不落库。文档里有一句关键判断:agent 和终端共用 workspace 权限,因为两者都能执行代码并改写 workspace,再细分写权限就是声称一条 daemon 无法强制的隔离边界。
生态层:plugins、skills、Hub 各管一段
plugins 跑在 daemon 上、在所有客户端呈现同一套 UI:屏幕、侧栏项、workspace 面板、Command Center 项、slash 命令、composer pill、attachment 源、timeline 项、主题;还能介入 agent 生命周期(改配置、环境、MCP server,代答权限,turn 结束后续话)以及注册新 provider。0.11.0 起有官方 registry,paseo plugin add owner/slug 安装;仓库自带 14 个 plugin-examples 与十余个 usage-source 插件。文档对信任的态度很直接:插件不沙箱,server 代码以 daemon 用户权限运行,paseo plugin add 的意思就是「我信这个代码库」,包括它的依赖和未来更新。
Hub 是 daemon 之上的一层:显式执行 paseo hub connect 才建立关系,daemon 主动 outbound 连 Hub,Hub 永远不通过 relay 发现 daemon;GitHub、Slack、Discord、Linear 的 trigger 落到 hub.execute 权限上,而默认连接不带任何执行权。Hub 可托管在 hub.paseo.sh 或自托管。它的存在说明作者自己也在往「把活派给 agent」的更上层伸手,但今天的主体仍是运行时。
工程纪律:协议兼容契约是这个项目最硬的部分
app 和 daemon 分开 ships:用户从应用商店更新 app、按自己的心情更新 daemon,于是新 app 对旧 daemon、旧 app 对新 daemon 都真实存在,而开发环境里两边永远同版本——这正是贡献者最容易踩的坑。protocol-compatibility.md 把这件事写成两条契约。协议契约要求 schema 改动不得让任何方向解析失败:新字段必须 optional 带合理默认值,禁止把 optional 翻成 required、删字段、收窄类型,wire schema 必须是纯结构声明(不许 transform、catch、preprocess,因为入站校验器是生成出来的,生成器只编译纯 schema),提交前自问两句——六个月前的 app 还能解析这条消息吗,六个月前的 daemon 发来的东西这个 app 还收吗。特性契约则反过来:新功能不跨版本兼容,检测一次 capability(server_info.features),没有就提示升级,禁止写降级路径、禁止把防御分支撒进特性代码里。
规模上这是 12 个 npm workspace、约 110 万行 TS/TSX(4,554 个文件)、1,714 个测试文件的 monorepo,server 与 app 两个包各占约四十五万行。对一个「一个人写、使用者众筹养活」的项目,这个体量加上上面那套契约,说明作者把长期可维护当成了产品特性本身,而不是技术债的遮羞布。
局限与风险
单人维护是最根本的一条:README 明说 built by one person,靠 GitHub Sponsors 与公司赞助供养;1,276 个 open issue 和每周数个 release 是这条事实的两面。其次是 Antigravity 永远 full access:--dangerously-skip-permissions 意味着该 provider 下每个工具调用包括 shell 都不询问,文档有警告、会话有提示,但这是产品层面的风险敞口而非配置项。第三是会话重放的缺口:agy 不回放历史,daemon 重启后 Antigravity 记得对话而 Paseo 的 transcript 从零开始;Claude 的 transcript 落在别的项目目录时也曾出现「No activity to display」,0.11.1 修了一类但跨重启的完整记忆仍不是保证。第四是插件不沙箱,生态开放度和信任成本是同一枚硬币。第五是语音本地档默认仅英文,多语言要手动换 v3 模型,而中文不在 v3 的 25 语列表里。最后是 NOASSERTION 的 license 读数:合规自动化会把它标成未知许可,实际是 Apache-2.0 加一段第三方声明。
在本站坐标系里的位置
主板块是开源板 /opensource;能力枢纽以 agents(Agent 编排)为主,同时挂 code(AI 编码)与 harness(agent 运行时、插件加 skills 加 MCP 生态),垂直行业是 development。和 Orca 的关系最贴近:两者都是多 agent 并行加 worktree 隔离的 ADE,Orca 押 IDE 形状与 Ghostty 级终端和设计模式点选,Paseo 押自托管 daemon、全端客户端与本地语音。和 herdr 比,herdr 接管的是终端进程,Paseo 接管的是 agent 进程与 workspace 登记。和 multica、paperclip 比,那两者在更上层把活变成 issue 和公司组织,Paseo 在它们下面一层提供「跑起来」的能力;Hub 的 trigger 模型是 Paseo 往那一层伸的第一只手。对本站读者而言,它同时是「agent 编排」与「agent 运行时」两个枢纽的坐标原点之一:要看多 agent 怎么并行,看 worktree 与 MCP tool catalog;要看运行时怎么长出生态,看 plugins、skills 与协议兼容契约。