lijianfei.com

随着 Claude Code、OpenAI Codex、GitHub Copilot CLI 以及各类基于 ACP（Agent Client Protocol）协议的自主编码代理相继进入开发者的日常流水线，一个极其尖锐的工程矛盾浮出水面：我们拥有了多个推理能力拔尖的“代码外脑”，但它们各自为政、互不相通，工作空间互相争抢，更无法在离开电脑时安全掌控。

开源编排框架 Paseo（getpaseo/paseo）以“本地常驻 Daemon 控制面”为核心，通过 Git Worktree 物理隔离、TweetNaCl 端到端加密中继，以及三大高阶协作技能（Handoff、Advisor 与 Committee），成功构建起跨桌面、手机端与 CLI 的统一多 Agent 协同体系。

1. 痛点审视：多 Agent 并发开发的三重断层

在深度接入各类 Coding Agent 的日常实操中，多数团队都会遭遇以下三道“硬墙”：

flowchart TD
    subgraph P1["断层 1：模型割裂与各立门户"]
        A1["Claude Code: 擅长系统架构与大上下文推理"]
        A2["OpenAI Codex: 擅长密集生成与算法实现"]
        A3["Copilot CLI / OpenCode: 擅长敏捷修补与本地执行"]
        A1 -.->|"上下文丢失、缺乏统一度量与会话流转"| A2
        A2 -.->|"输出格式不一致、权限孤立"| A3
    end

    subgraph P2["断层 2：单工作树的文件并发踩踏"]
        W1["Agent A 正在重构 auth.ts"]
        W2["Agent B 正在为 user.ts 编写测试并触发 build"]
        W1 -->|"共享同一工作区"| Repo["同一本地 Git 仓库"]
        W2 -->|"引发脏索引、编译死锁与未提交文件覆盖"| Repo
    end

    subgraph P3["断层 3：移动端脱节与远程安全焦虑"]
        M1["离开工位 / 通勤在途"]
        M2["高危指令（如 rm -rf、git push -f）需要人工审批"]
        M1 -->|"只能靠 SSH 盲打或内网穿透暴露端口"| Risk["敏感 Token 与源码泄露风险"]
        M2 -->|"因无人确认导致 Agent 任务挂起阻断"| Risk
    end

针对上述痛点，由 Mohamed Boudra 发起的 Paseo 没有选择构建另一个庞大封闭的云端 Web 平台，而是选择“Local-first + Zero Telemetry”的纯本地控制面路线，让开发者的所有代码、凭证与执行环境牢牢锁在本地设备。

2. 系统全景：Paseo 本地常驻 Daemon 架构剖析

Paseo 采用现代 TypeScript Monorepo 组织结构，其核心组件自底向上划分为清晰的责任边界：

flowchart LR
    subgraph Clients["多端接入层 (Clients)"]
        D1["Desktop (Electron)"]
        D2["Mobile (Expo iOS/Android)"]
        D3["Web UI (Self-hosted)"]
        D4["Paseo CLI (@getpaseo/cli)"]
    end

    subgraph Transport["传输与加密层 (Transport)"]
        T1["Local WebSocket (ws://127.0.0.1:6767)"]
        T2["E2EE Relay (Curve25519 + XSalsa20)"]
    end

    subgraph Daemon["本地控制面 Daemon (@getpaseo/server)"]
        S1["AgentManager (会话生命周期与流合并)"]
        S2["WorktreeSession (动态分支隔离与生命周期管理)"]
        S3["PermissionEngine (双向人机交互决策阻断)"]
        S4["VoiceSubsystem (2-way Audio / STT / TTS)"]
    end

    subgraph Providers["底层执行代理 (Agent Runtimes)"]
        P1["Claude Code Runtime"]
        P2["Codex App Server"]
        P3["GitHub Copilot (ACP)"]
        P4["Cursor / Kimi / Trae (Generic ACP)"]
        P5["OpenCode / Pi"]
    end

    Clients --> Transport
    Transport --> Daemon
    Daemon --> Providers

2.1 模块分工一览

[!NOTE]
Paseo 运行时无需将代码推送到第三方 SaaS。Daemon 启动后在本地绑定独立端口，所有的 Agent 进程均作为 Daemon 的子进程在用户自己的 shell 环境变量中启动，天然继承本地的编译工具链、SSH 密钥与环境变量。

3. 异构 Agent 的通信归一化：ACP 适配与流式精算

为了让行为各异的 Coding Agent 在同一控制台协同，Paseo 实现了精巧的协议对齐引擎。

3.1 ACP（Agent Client Protocol）抽象层

在 packages/server/src/server/agent/providers/ 源码中，Paseo 通过 generic-acp-agent.ts、acp-agent.ts 与 codex-app-server-agent.ts 将所有 Agent 行为规范为标准的 JSON-RPC / ACP 通道：

// 摘自 packages/server/src/server/agent/providers/generic-acp-agent.ts 核心设计
export const GenericACPProviderParamsSchema = z
  .object({
    supportsMcpServers: z.boolean().optional(),
    clientCapabilities: z
      .object({
        fs: z
          .object({
            readTextFile: z.boolean().optional(),
            writeTextFile: z.boolean().optional(),
          })
          .optional(),
        terminal: z.boolean().optional(),
      })
      .optional(),
  })
  .passthrough();

无论下游是基于 stdio JSONL 通信的 Claude Code，还是采用 App Server 协议的 OpenAI Codex，抑或是支持 ACP 扩展的 Cursor 与 Trae，Paseo 均在服务端将其统一封装为具备统一 AgentClient 接口的会话实体，支持：

1. 统一工具调用拦截：所有工具申请（fs/write、bash/execute 等）均被标准化为 AgentPermissionRequest；
2. 渐进式模型解析：动态探查 Agent 支持的模型列表（如 GPT-5.5、Claude Opus 4.6）并挂载至统一前端。

3.2 高频流式合并（Stream Coalescing）

大型模型在输出代码或终端日志时，常常以极其高频的 Byte 流喷吐字符。若每个小 Chunk 都触发一次 WebSocket 推送与 React 重绘，移动端和桌面前端会立刻遭遇卡顿掉帧。

Paseo 在 agent-stream-coalescer.ts 中构建了滑动窗口合并器（AgentStreamCoalescer）：

sequenceDiagram
    participant LLM as 模型 / Agent 子进程
    participant Coalescer as AgentStreamCoalescer
    participant Front as 桌面 / 移动端 Timeline

    LLM->>Coalescer: 吐字 Token 1 (t=0ms)
    LLM->>Coalescer: 吐字 Token 2 (t=3ms)
    LLM->>Coalescer: 吐字 Token 3 (t=7ms)
    Note over Coalescer: 命中聚合窗口 (如 16ms 节流)<br/>避免逐字触发全链路重绘
    Coalescer->>Front: 批量派发合并增量帧 (t=16ms)
    LLM->>Coalescer: 吐字 Token 4 (t=20ms)
    Coalescer->>Front: 批量派发合并增量帧 (t=32ms)

结合 activity-curator.ts（活动精算器），Paseo 能够智能折叠 Agent 的中间思考链（Thinking 过程）、反复试探的工具调用与庞大构建日志，只将精炼的意图与最终变动高亮投递给开发者。

4. 并发防踩踏底座：动态 Git Worktree 隔离机制

多 Agent 协同最怕的就是“冲突乱套”：如果一个 Agent 在重构底层接口，另一个 Agent 在修补上层组件，两者共享同一个本地 Git 工作区，必然导致编译缓存污染、文件覆写与 Git 暂存区冲突。

Paseo 的解决方案是 Git Worktree 原生沙盒化。

flowchart TD
    MainRepo["本地 Git 主仓库 (/workspace)<br/>HEAD: main"]

    subgraph WT_Pool["Paseo Worktree 动态隔离池"]
        WT1["Worktree A: .paseo/worktrees/agent-feat-auth<br/>Branch: paseo/feat-auth (独立工作区)"]
        WT2["Worktree B: .paseo/worktrees/agent-fix-leak<br/>Branch: paseo/fix-leak (独立工作区)"]
    end

    MainRepo -->|"git worktree add -b"| WT1
    MainRepo -->|"git worktree add -b"| WT2

    WT1 -->|"Agent A (Claude Code) 专注重构"| CommitA["独立生成 Commit A"]
    WT2 -->|"Agent B (Codex) 专注排查泄漏"| CommitB["独立生成 Commit B"]

    CommitA -->|"审查通过后合并"| MainRepo
    CommitB -->|"任务取消后自动归档清理"| MainRepo

4.1 工作树调度核心逻辑

在 packages/server/src/server/worktree-session.ts 中，Paseo 提供了完整的隔离自动化管线：

1. 自动分支派生与目录初始化：
   开发者在派发任务时只要带上 --worktree 参数，Paseo 会自动以当前基线分支（如 main）派生临时分支 paseo/<slug>，并创建物理隔离的工作目录；
2. 环境自动化与依赖挂载：
   通过 runAsyncWorktreeBootstrap 自动同步本地环境变量，并在沙盒工作树内执行 npm install 或软链接 node_modules，杜绝重复安装耗时；
3. 安全归档与生命周期回收：
   当任务完成或被开发者放弃时，archiveCommand 会优雅清理工作树句柄，保留提交历史供主分支合并，或者彻底回滚，绝不污染开发者的主工作树。

5. 跨端安全命脉：TweetNaCl 端到端加密中继

很多开发者希望下班路上在手机端随时查看代码生成进度，或者对终端的高危操作（如 DROP DATABASE、rm -rf）进行人工授权。但直接将电脑的 SSH 或 Web 端口映射至公网，安全风险极高。

Paseo 在 packages/relay 中设计了一套基于 TweetNaCl 的全链路端到端加密（E2EE）中继方案：

sequenceDiagram
    autonumber
    participant Mobile as 移动端 App
    participant Relay as 分布式 Relay 节点
    participant Host as 本地电脑 (Paseo Daemon)

    Host->>Host: 生成 Curve25519 临时密钥对 (Daemon)
    Mobile->>Mobile: 扫码获取 Daemon 公钥并生成自身密钥对
    Mobile->>Relay: 握手请求 (携带目标 Peer ID)
    Relay-->>Host: 建立双向通道
    Note over Mobile,Host: Curve25519 (nacl.box.before) 计算共享密钥 (SharedKey)
    Mobile->>Relay: [Nonce 24B] + [XSalsa20 密文 (Payload)]
    Note over Relay: Relay 仅做二进制透明转发，无密钥无法解密
    Relay->>Host: 透传二进制数据包
    Host->>Host: XSalsa20-Poly1305 解密并执行本地调用

5.1 加密核心实现切片

在 packages/relay/src/crypto.ts 中，Paseo 的加密报文结构极度精炼：

// 摘自 packages/relay/src/crypto.ts
/**
 * E2EE crypto primitives using NaCl (tweetnacl).
 * - Key exchange: Curve25519 (nacl.box.before)
 * - Encryption: XSalsa20-Poly1305 (nacl.box.after / open.after)
 *
 * 二进制格式标准:
 * [nonce (24 bytes)] [ciphertext...]
 */

• 无须配置公网 IP：Daemon 与手机端均只需主动与分布式 Relay（官方基于 Elixir 开发的 getpaseo/paseo-relay）建立长连接；
• 防中间人监听：配对数据在扫码时刻完成公钥绑定，Relay 节点全程仅作为哑管道（Dumb Pipe）处理二进制帧，任何第三方即便劫持流量也无法破解源码或 Prompt；
• 零遥测保证：整套协议未埋入任何遥测上报，完全保证了商业源码的合规性。

6. 超越单兵作战：Paseo 三大协作技能范式

单 Agent 往往容易陷入局部最优或思维死胡同。Paseo 的真正威力在于其内置的三大 Agent 编排技能（Skills）：

flowchart TD
    subgraph S1["范式 1：/paseo-handoff (接力交割)"]
        H_Plan["规划型 Agent (如 Claude Opus)<br/>梳理架构、定位模块、制定 Acceptance Criteria"]
        H_Exec["实现型 Agent (如 Codex)<br/>在独立 Worktree 中专注搬砖码字与单元测试"]
        H_Plan -->|"自包含 Briefing 数据包"| H_Exec
    end

    subgraph S2["范式 2：/paseo-advisor (只读智囊)"]
        A_Main["主力 Agent 遇到疑难设计分歧"]
        A_Adv["外脑 Agent (异构模型)<br/>带严格 'No-edits' 保护指令与只读权限"]
        A_Main <-->|"征求第二意见 / 转发 /unslop 代码洁癖审查"| A_Adv
    end

    subgraph S3["范式 3：/paseo-committee (双星委员会辩论)"]
        C1["Agent A (如 Claude) 提出假设方案"]
        C2["Agent B (如 Codex) 展开反思挑刺"]
        C1 <-->|"对抗式交叉辩论与反驳"| C2
        C1 & C2 -->|"意见收敛并产出高置信度共识"| Cons["最终执行计划"]
    end

6.1 接力交割：/paseo-handoff

当一个 Agent 完成了深度推理与规划，需要将其移交给另一个更擅长批量代码生成的模型时，Paseo 要求交接双方必须遵循自包含规范：

• 接收任务的 Agent 初始上下文为零；
• Handoff 自动打包当前任务动机、涉及的关键文件路径、已尝试失败的路径、确定下来的技术决策与验收标准（Acceptance Criteria）；
• 自动关联独立的 Git Worktree，实现无缝接力。

6.2 只读智囊：/paseo-advisor

让另一个模型充当“代码军师”，但 绝不允许其触碰任何文件：

• 自动在系统 Prompt 尾部追加强力安全护栏：

  This is analysis only. Do NOT edit, create, or delete any files. Do NOT write code.
  

• 支持技能转发（Forwarded Skills）：主 Agent 可以指挥 Advisor 去运行 /unslop（代码异味过滤）或 /diagnose（构建报错诊断），并将 Advisor 的评估结果合成最终决策。

6.3 辩论委员会：/paseo-committee

面对极其顽固的并发死锁或系统重构，单个 Agent 容易进入“盲目修补”死循环。
/paseo-committee 会自动拉起两个来自不同模型家族的高智商 Agent（例如 Claude 与 Codex），提供完全一致的问题描述，促使其分别展开根因推演。若两方结论存在分歧，Paseo 会将对方的反驳论据交叉注入，直至双方在推演中收敛出最高置信度的解决方案。

7. 实操落地：从 CLI 到 TypeScript SDK 编排

7.1 本地极速启动与终端交互

安装并启动 Paseo 控制面：

# 全局安装 CLI
npm install -g @getpaseo/cli

# 启动 Daemon 服务（默认监听 6767 端口）
paseo

在终端快速派发隔离工作流：

# 指派 Claude 模型实现认证模块，并自动创建独立 Git Worktree
paseo run --provider claude/opus-4.6 --worktree feat-auth "重构 JWT 刷新逻辑并补齐单元测试"

# 列出当前所有活跃中的 Agent 任务
paseo ls

# 实时挂载并追踪特定 Agent 的输出流
paseo attach abc123

# 向正在运行的 Agent 追加补充指令
paseo send abc123 "同时兼容旧版 Authorization Header"

[!TIP]
运行 paseo 后打开桌面端或终端输出的链接，进入 Settings → Host → Pair Device，用手机 Paseo App 扫码即可完成 Curve25519 握手，随时把手机变成随身编码控制台。

7.2 基于 @getpaseo/client 编写自定义编排流水线

对于需要将 Agent 编排接入 CI/CD 或内部工单系统的场景，Paseo 提供了极简的 TypeScript SDK：

import { createPaseoClient } from "@getpaseo/client";

async function main() {
  // 1. 连接本地或远程 Paseo Daemon
  const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" });
  await client.connect();

  console.log("已成功建立与 Paseo Daemon 的通信通道");

  // 2. 派发带隔离环境的代码审查 Agent
  const agent = await client.agents.create({
    config: {
      provider: "codex/gpt-5.5",
    },
    cwd: "/Users/lijianfei/Projects/ecommerce-core",
    prompt: "检查当前 HEAD 相对于 main 分支的全部 diff，标出所有潜在的并发竞争风险。",
  });

  console.log(`Agent 已创建，会话 ID: ${agent.id}`);

  // 3. 等待 Agent 思考并输出最终裁决
  const result = await agent.waitForFinish();
  console.log("\n--- Agent 审查结论 ---\n");
  console.log(result.lastMessage);

  // 4. 安全关闭连接
  await client.close();
}

main().catch(console.error);

8. 总结与架构启示

在 AI 编码工具日趋同质化的当下，Paseo 给出了一个兼具极客审美与生产级考量的工程示范：

1. 从单兵到协同：不再强求某一个模型“包打天下”，而是通过标准化 ACP 适配让 Claude、Codex、Copilot 各展所长；
2. 物理隔离是并发底线：用 Git Worktree 解决代码覆写与暂存区争抢，保证多任务并行的整洁与可回滚性；
3. 安全与便携兼得：基于 TweetNaCl 的端到端加密通道，让开发者即便人在路上也能安全监控工位上的百万行代码流水线。

对于正在探索多 Agent 协同体系的团队或独立开发者，Paseo 的本地控制面模型与多角色辩论机制，无疑提供了一份极具参考价值的现代工程蓝图。