Skip to content

paseo.md

Latest commit

 

History

History
591 lines (464 loc) · 48.3 KB

paseo.md

File metadata and controls

591 lines (464 loc) · 48.3 KB
Raw

Paseo

一句话定位：面向桌面、Web 与移动端的本地优先 Coding Agent 控制面：由 daemon 统一持有 workspace、provider session、timeline、权限请求、终端与远程连接，并通过 MCP / native tools 让 Claude Code、Codex、OpenCode、Pi、OMP 与 ACP Agent 跨 provider 协作。 分析日期：2026-08-22 项目地址：https://github.com/getpaseo/paseo

基本信息

项目 值
仓库 getpaseo/paseo
URL https://github.com/getpaseo/paseo
默认分支 main
冻结源码 HEAD 7c430777bfb3117eb1d359eddb69235ea308930e
Star 14,667（2026-08-22 快照）
Fork 1,558（2026-08-22 快照）
许可证 AGPL-3.0-or-later；GitHub API 返回 NOASSERTION，以根 LICENSE 为准
语言 TypeScript；少量 Kotlin / Swift / C++ native module
首次提交 fee0f4fd，2025-10-13
最近提交 7c430777，2026-08-22；release 后的 lockfile/Nix 修订，commit 标记 [skip ci]
最新 Release v0.5.0-beta.5，2026-08-22，prerelease
历史规模 5,092 commits / 157 个 Git author identities / 4,232 个 tracked files
GitHub contributors 151（Contributors API 完整分页；含 bot）
代码规模 TypeScript 约 76.2 万行 + TSX 约 13.9 万行，含测试与生成/辅助代码
测试资产 1,416 个 test/spec/e2e 命名文件；Vitest + Playwright + real daemon/provider + packaged Electron smoke
Issue / PR 477 open issues / 494 open PR（Search API 分拆）
分析方式 canonical source 静态审查 + 完整 Git 历史 + GitHub API + CI/Release 证据；未安装依赖、未构建、未运行项目

证据口径： 文中使用【源码事实】【官方主张】【社区事实】【推导】区分证据类型。官方文档描述能力与预期边界；只有能由冻结 HEAD、Git/GitHub 快照或真实 CI run 交叉验证的内容才作为审计事实。

场景一：是否值得采用

解决的问题

【源码事实】Paseo 不重新实现模型推理和通用 agent loop，而是在现有 Coding Agent 之上补齐一个 daemon-owned control plane：

  • 把 Claude Code、Codex、Copilot、OpenCode、Pi、OMP 与任意 ACP stdio Agent 投影成统一的 agent/session/timeline surface；
  • 让多个 Agent 在同一 workspace 或独立 Git worktree 中并行工作；
  • 从 Desktop、Web、iOS、Android、CLI 和 TypeScript SDK 查看、继续、取消、归档会话；
  • 把权限请求、provider mode、model/thinking、子 Agent、终端、workspace scripts、计划任务和 heartbeat 放到同一协议；
  • 通过 E2EE relay 或 direct WebSocket 远程接管本机/VPS 上的 daemon；
  • 通过 Hub 把 GitHub、Slack、Discord 事件变成受约束的 workflow steps。

【推导】它解决的不是“哪个模型更聪明”，而是谁拥有跨 provider 的 session、workspace、状态投影、远程控制和恢复语义。这使 Paseo 更接近 Agent Development Environment / control plane，而不是 Coding Agent runtime。

核心能力与边界

能做什么

  • 【源码事实】packages/protocol 用 Zod schema 定义 typed WebSocket envelope、agent snapshot/timeline、provider capability、workspace、terminal、schedule 与 permission contract。
  • 【源码事实】packages/server/src/server/agent/agent-manager.ts:1127-1132 是 agent registration 入口；daemon 持有 agent map、生命周期锁、provider client/session、timeline 与 client dispatch。
  • 【源码事实】packages/server/src/server/agent/agent-storage.ts:1-45 将 metadata 与 provider persistence handle 写入磁盘，并通过 writeJsonFileAtomic 落盘。
  • 【源码事实】内置 provider definition 覆盖 Claude、Codex、Copilot、OpenCode、Pi、OMP；public-docs/custom-providers.md:136-153 允许用 ACP stdio 接入 Gemini、Hermes 等其它 Agent。
  • 【源码事实】public-docs/orchestration.md:13-33 明确区分 provider-native subagent 与 Paseo-managed subagent：后者可以跨 provider、跨 workspace，并由 daemon 持有生命周期。
  • 【源码事实】MCP/native tool catalog 能创建/控制 Agent、workspaces、terminals、scripts、schedules、heartbeats、provider discovery 与权限响应（public-docs/mcp.md:30-117）。
  • 【源码事实】插件可贡献 daemon behavior、workspace/global panel、command center、theme 与附件来源；插件默认关闭。
  • 【源码事实】Hub 支持外部 trigger、有限 agent/environment 选择、step runtime/idle timeout、有限 output authority 与 daemon relationship lifecycle。

不能做什么

  • 【源码事实】Paseo 不拥有 provider 的模型调用、上下文压缩、工具实现与完整 permission enforcement；这些仍由各 provider SDK/CLI 决定。
  • 【源码事实】内置 provider 的 OAuth/API 认证通常由各 CLI 持有；但 custom provider 的 agents.providers.*.env 会持久化在 private config.json 并传给子进程（config.ts:230-247、persisted-config.ts:415-435）。因此官方“Paseo never stores provider API keys”不能覆盖自定义 provider 路径。
  • 【源码事实】默认 timeline store 是内存；daemon 持久化 Agent 投影与 provider persistence handle，恢复时从 provider streamHistory() 重建。durableTimelineStore 是可选接口，生产 bootstrap 当前未注入（agent-manager.ts:665-704、bootstrap.ts:911-921）。
  • 【源码事实】核心没有全局 agent queue、资源配额、抢占、worker lease 或 DAG admission；packages/server/src/tasks 的 task graph/排序库不会自行创建或调度 Agent。多 Agent 的默认语义是并行 session + 上层 MCP/skill/Hub 编排。
  • 【源码事实】worktree 是并行修改隔离，不是 OS security boundary。
  • 【官方主张】Hub 文档直接声明：Hub 不 sandbox provider process，也不会使外部文本安全（public-docs/hub/security.md:9-17）。
  • 【源码事实】没有通用 container/microVM/Seatbelt/Landlock abstraction；Docker 是单独部署边界，强度取决于挂载与 provider 自身设置。
  • 【源码事实】插件 backend 是 trusted local code，能在 daemon 机器上 unsandboxed 执行；插件文档明确不面向分发，API 仍会 breaking（public-docs/plugins/index.md:9-22）。
  • 【推导】它能“协调”多 Agent，但不是自动任务规划器或一致性证明器。父 Agent 是否正确拆解、review 和 merge，仍取决于 prompt/skill/workflow 与人类 gate。
  • 【推导】统一 UI 的 safe/moderate/dangerous 标签不等于不同 provider 获得等价的底层 sandbox；每个 provider 的 mode/options 必须单独审计。

与竞品差异

参照物 对方核心所有权 Paseo 的差异
Conductor cloud coding-agent control plane + cloud sandbox 最接近的商业直接竞品；Paseo 更 local/BYOS/开源，Conductor 的信任与隔离模型更云优先
OpenHands Agent Canvas 多 Agent/automation control center + local/Docker/VM/cloud backends 最强开源直接竞品；平台/企业/automation 更重，Paseo 的多端 local-first cockpit 更聚焦
Agent Deck / Claude Squad terminal/TUI 多 Agent、worktree、review 更轻、更容易采用；放弃 Paseo 的富 GUI、移动端、typed SDK/Hub 后是现实低成本替代
Nimbalyst 多 Agent + worktree 的 visual AI workspace 同层但更偏 AI-native IDE；Paseo 更强调 daemon/provider lifecycle 与远程控制
Claude Code / Codex CLI / OpenCode / Pi 模型 loop、工具与原生 session Paseo 位于其上层，统一管理多 provider 和多端客户端，不替代这些 runtime
DeepSeek Harness / Prime Agent / Grok Build 完整 Coding Agent runtime/harness Paseo 更专注控制面和投影；推理与大部分工具仍外包给 provider
Vibe Kanban / Emdash task board、queue、workspace Paseo 对 live agent timeline、permission、terminal、provider session 与移动端接管更深；团队 board/RBAC 不是当前强项
workmux / Claude Squad / Herdr tmux/terminal + worktree Paseo 更重，但有 typed protocol、durable state、provider adapter、SDK、远程与移动端 surface
AgentAPI 单 Agent HTTP facade Paseo 管理的是 agent fleet、workspace 与多端状态，不只是把一个 CLI 包成 API
OpenHands 自有 runtime、sandbox/cloud deployment Paseo 更 local-first/BYOS，保留用户已有订阅与 provider CLI；统一隔离能力更弱

集成成本

  • 个人本机试用：中。 Desktop/CLI 入口清晰，但需要已安装并登录至少一个 provider；多 provider 的模式和凭据仍各自管理。
  • 源码开发：高。 Node >=22.19，15 个 workspace manifest、React Native/Expo、Electron、native audio、daemon、relay、WebSocket、provider SDK 与多平台 release 形成宽 monorepo。
  • 远程/移动端：中高。 Relay 简化网络，但需要理解二维码 trust anchor、daemon keypair、device pairing、E2EE 与 direct auth 的差异。
  • Hub 自动化：高。 必须治理外部 trigger allowlist、prompt injection、cwd、provider-native sandbox/options、output authority、secret scope、timeout 与配置仓 push 权限。
  • 二次分发：高。 AGPL-3.0-or-later 对修改版网络服务有源码提供义务；企业部署前必须做法务确认。
  • 从零到 demo： 已有 Claude/Codex/OpenCode 登录环境时预计 15–45 分钟；安全的远程/Hub PoC 应按半天到一天估算，不能只以“手机连上”为完成。

依赖 / SDK 选型证据

全量扫描得到 297 个直接 dependency references、218 个唯一包名；package-lock.json v3 有 3,001 个 package entries、2,978 个 integrity entries，未发现 Git/GitHub 浮动依赖。下表只解释决定架构的关键依赖。

Dependency Type Used for Problem solved Evidence Reuse signal Caution
zod schema / protocol RPC、config、provider manifest、持久记录验证 避免 daemon/client/plugin 共享手写校验 packages/protocol/package.json；agent-storage.ts 多客户端、持久化状态和插件共享 TS contract 时优先 schema 演进仍需显式兼容层，不能只升级类型
@anthropic-ai/claude-agent-sdk provider SDK Claude session、stream、tool/permission 映射 替代反解析 Claude TUI packages/server/package.json；providers/claude-* 需要稳定结构化 Claude 集成时优先 固定 0.3.220；上游行为和认证仍是外部依赖
@modelcontextprotocol/sdk protocol SDK 向 Agent 注入 Paseo orchestration tools 标准化 agent→control-plane 工具调用 packages/server/package.json；agent/mcp-server.ts Agent 已支持 MCP 且只需工具 surface 时 MCP 不定义 provider session、workspace ownership 或 OS sandbox
@agentclientprotocol/sdk protocol SDK 接入 Copilot/任意 ACP stdio Agent 避免每个 Agent 单独发明 session JSON-RPC packages/server/package.json；providers/acp-* 异构 Agent 都能讲 ACP 时复用价值高 capabilities/modes 运行时漂移，兼容性需要真实 provider 测试
@opencode-ai/sdk provider SDK OpenCode server/session/event 集成 保留结构化事件与 active-turn steering packages/server/package.json；providers/opencode-* 深度接入 OpenCode 时 已有 issue #3601 显示 pin 与新 server schema 可能漂移
node-pty + @xterm/* runtime / UI daemon-owned terminal 与跨端 terminal projection 保留真实 shell/TUI fidelity server/app manifests；terminal modules 需要远程接管真实终端时 native 构建、多平台行为与高权限宿主进程风险
tweetnacl crypto relay ECDH 与 XSalsa20-Poly1305 authenticated encryption 让 relay 不必读取内容 packages/relay/package.json；relay/src/crypto.ts 需要小型、审计充分的 NaCl primitive 时 channel 语义仍需 session binding、anti-replay 与 key lifecycle；不要只看 cipher 名称
express + ws server / transport HTTP/WebSocket daemon、SDK/clients 成熟的本地控制 API 与事件通道 server/client/relay manifests；server/bootstrap.ts local daemon + 多 client surface 远程暴露必须叠加 auth、TLS/VPN、Host/CORS 与 origin policy
React Native / Expo UI framework iOS、Android 与 Web 共用 app surface 一套交互模型覆盖移动/浏览器 packages/app/package.json 移动端是一等产品面时 依赖树很宽，native/web 行为不等价，QA 成本高
Electron desktop runtime Desktop shell、managed daemon 与 updater 提供跨平台本地 ADE packages/desktop/package.json 需要桌面原生打包/更新时 供应链、asar dependency closure、签名和自动更新需持续验证
Vitest + Playwright test stack unit/browser/real daemon/Electron E2E 验证跨进程与用户可见 contract root/server/app/desktop manifests；docs/testing.md 多 surface control plane 值得直接复用该分层 全套非常重；route-based CI 可能遗漏跨包组合，只能靠 main integration 补齐

风险评估

风险项 评估 说明
许可证合规 ⚠️ 中高 当前根许可证是 AGPL-3.0-or-later；#2982 正在征求历史贡献者 consent 迁移 Apache-2.0，但观察日尚未完成。采用必须按当前 AGPL 判断，不能预支未来宽松许可证
Bus factor ❌ 高 5,092 commits 中 boudra 4,532；第二位人类贡献者 28 commits，核心知识与 merge authority 高度集中
供应商锁定 ⚠️ 中 BYOS 与 ACP 降低模型锁定，但 protocol、app cache、Hub workflow、plugin 和 timeline 深度依赖 Paseo
维护趋势 ✅ 极度活跃 2026-08-22 同日多次 merge/release；过去最新 400 个 closed PR 样本中 263 merged
版本稳定性 ❌ 高变动 当前 0.5.0-beta.5，plugin 标为 experimental；高速 provider/API/UI 变化与 breaking release 并存
Backlog ❌ 高 477 open issues（中位年龄 24.3 天）+ 494 open PR（中位年龄 18.5 天）
安全历史 ⚠️ 尚未形成长期样本 GitHub repository security advisories API 返回 0；有 SECURITY.md，但项目不足一年，不能由“0 advisory”推断无风险
宿主权限 ❌ 高影响 Agent、workspace scripts、terminals、plugins、custom binaries、stdio MCP/ACP 可在宿主用户权限下执行；无统一 OS sandbox
Hub authority ❌ 高影响 已登记 Hub 可指定绝对 cwd、env、MCP servers、tool policy 和 worktree；daemon 只做结构/绝对路径验证，没有独立 cwd root、env/MCP allowlist 或本地审批 ceiling。Hub、Hub 凭据和 .paseo 配置仓应按远程执行 principal 管理
凭据存储 ⚠️ 分路径 built-in provider 通常复用各 CLI 的 OAuth/API credential store；custom provider 文档则直接允许把 API key 放进 agents.providers.*.env。config.json 会被收紧为 private file，但仍是本地明文 secret，必须保护/备份排除 $PASEO_HOME
远程控制 ⚠️ 可硬化 loopback/Unix socket/E2EE relay/Host allowlist 是优点；direct network 默认无密码，错误暴露后影响大
Telemetry / 隐私 ✅ 一方实现较克制 README 明确主张无 telemetry/tracking；静态审计未找到 Paseo 自有 PostHog/Sentry/Mixpanel 等上报调用。lockfile 中有 Expo/AI SDK 带入的 Segment/OpenTelemetry 传递依赖，这不证明发生采集；provider API、relay/Hub、更新检查和 Git/GitHub 仍有预期网络出站，不能把“无产品遥测”扩大成“零网络”
Relay anti-replay ⚠️ session 内缺口 SECURITY.md:31-39 明确：fresh key 防跨 session replay，但 live session 内尚未实现 replay protection，只使用随机 nonce、不跟踪 nonce/counter；issue #3675 还挑战 pairing restart 文档，不能写成无条件“无法重放”
远程制品 ❌ 高 本地 Sherpa 语音模型 catalog 只有 URL/归档名，无 SHA-256/signature；下载后直接交给系统 tar/unzip。需固定摘要并使用拒绝绝对路径、..、危险 symlink 的解包器
持久化损坏 ❌ 高 workspace registry 对非 ENOENT 的读取/JSON 错误只 warning 后以空 cache 继续；后续 mutation 可能原子覆盖原损坏文件。应 fail closed、quarantine 并要求显式恢复
CI / Release 供应链 ❌ 高 lock integrity/signature 很强；但多处 Action 用浮动 major tag，CI 全局安装未固定 Claude Code/OpenCode CLI，Android 使用 EAS latest，Docker provenance 关闭，desktop 手工 release 可让 checkout ref 与 tag 来源分离

结论

推荐架构学习；推荐多 Agent 重度用户固定版本、低权限、可信仓库做受控试用；团队高权限生产与公网 Hub 自动化暂观望。

理由：

  1. Paseo 已形成完整、可复用的 control-plane contract，不是 UI 壳或 tmux wrapper。
  2. daemon-owned state、provider adapter、typed protocol、worktree、cross-provider subagent、E2EE relay 和多端 UI 的组合很稀缺。
  3. 工程和 CI 信号强，文档也主动声明真实安全边界。
  4. 但 beta、高 backlog、单维护者集中、AGPL、插件/Agent/Hub 的宿主权限，以及 provider churn，使它还不适合“装上即交给生产凭据与不可信请求”。

场景二：技术架构学习

核心架构图

Desktop / Web / iOS / Android / CLI / TypeScript SDK
                         │
               typed HTTP + WebSocket protocol
                         │
┌────────────────────────▼──────────────────────────────┐
│ Paseo Daemon                                           │
│ Project/Workspace │ AgentManager │ Timeline │ Permission│
│ Terminal/PTY      │ Schedules    │ Plugins  │ Hub       │
└───────────┬────────────────┬───────────────┬────────────┘
            │                │               │
      Provider adapters   MCP/native tools  Relay client
            │                │               │
 Claude/Codex/Copilot/   child Agent →   NaCl E2EE relay
 OpenCode/Pi/OMP/ACP     Paseo control       │
            │                                │
 model loop / tools / auth / provider-native sandbox   Mobile
            │
 filesystem / git worktree / terminal / network / external APIs

底层技术架构

最小架构内核

脱掉 UI、语音、浏览器、Hub 与插件后，Paseo 仍必须保留：

Protocol Schemas + Daemon-owned Agent/Workspace State + Provider Adapter Registry + Agent Projection/Provider Handle Persistence + Client Event Projection。

要实现跨 provider orchestration，再加：

Agent-facing MCP/native Tool Catalog + Parent/Child Ownership + Worktree Lifecycle + Permission Projection。

核心抽象

抽象 源码位置 职责 关键字段 / 方法 为什么重要
Protocol schemas packages/protocol/src/** 定义 RPC envelope、snapshot、timeline、provider、workspace 和 permission contract Zod schemas、capabilities、version 防止多个客户端和 daemon 各自猜 shape
AgentManager packages/server/src/server/agent/agent-manager.ts agent registration、lifecycle、timeline、provider session、dispatch createAgent、archive/cancel、timeline append、lifecycle locks daemon authority 的核心 owner
AgentSessionConfig / provider client agent/agent-sdk-types.ts 把不同 provider 投影为统一 session contract create/resume/send/cancel/mode/model/features 隔离 provider 差异，避免 UI 绑定 SDK
Provider registry/manifest agent/providers/**、protocol/provider-manifest.ts 静态/动态 provider capability 与 mode provider id、mode、unattended、models、options UI 标签与真实 runtime 配置之间的桥
Agent storage agent/agent-storage.ts metadata、owner、persistence handle、snapshot 落盘 Zod stored record、atomic JSON write daemon 重启后恢复逻辑状态
Timeline projection agent-timeline-store.ts、AgentManager、provider streamHistory() 在内存中归一 provider history/live events，再投影给 client in-memory timeline、optional durable store、provider history hydration 默认恢复依赖 provider 原生 history；不能把可选接口误当 production durable log
Workspace manager server/workspace/** local/worktree workspace、branch、scripts、lifecycle project/workspace id、directory、isolation 并发修改和 Agent ownership 的目录边界
Orchestration tools agent/tools/**、agent/mcp-server.ts 向 Agent 暴露 create/send/status/workspace/terminal/schedule tool catalog、capability token、parent context 让 Agent 调 control plane，不让 prompt 直接改 daemon internals
Encrypted channel packages/relay/src/crypto.ts、encrypted-channel.ts client/daemon 经不可信 relay 建立加密通道 keypair、shared key、nonce、box/open 把 relay 从内容信任边界移除
Hub execution server/hub/** 外部 trigger、workflow step、daemon relationship、output authority execution id、scopes、timeouts、allowed outputs 将 webhook 自动化与普通交互会话分离
Plugin runtime server/plugins/**、packages/plugin 本地扩展 backend/client surfaces child process、contributions、cleanup/reload 扩展产品面而不硬编码进 daemon，但扩大信任面

控制面 / 数据面

  • 控制面： config、provider catalog、agent/workspace ownership、mode/permission UI、MCP tool policy、schedules、Hub workflow activation、device pairing、plugin enablement。
  • 数据面： provider process/SDK 调用、shell/PTY、Git/worktree、workspace scripts、文件编辑、browser automation、relay frames、Hub external APIs。
  • 关键不变量： 控制面决定“谁可以请求什么”，但数据面最终在 provider 与宿主权限下执行；不能用 UI 标签替代数据面隔离审计。

关键执行链路

Client / MCP create_agent
  ↓
protocol schema validation
  ↓
AgentManager.createAgent(config, id, ownership/workspace options)
  ↓
resolve provider definition + validate provider-native options
  ↓
write stored agent metadata / parent ownership
  ↓
lazy create or resume provider session
  ↓
provider event → normalize timeline/status/permission
  ↓
update in-memory timeline + persist Agent projection/provider handle
  ↓
dispatch WebSocket projection
  ↓
Desktop/Web/Mobile/SDK render the same agent state

Cross-provider subagent：

Parent Agent receives Paseo tools
  ↓ create_workspace (optional worktree)
  ↓ create_agent(provider/model/workspace)
Paseo binds parentAgentId + workspaceId
  ↓
Child provider runtime works independently
  ↓ timeline/status completion notification
Parent continues, follows up, reviews or detaches manually

Hub：

GitHub / Slack / Discord event
  ↓ authenticated provider connection + filters
Hub workflow activation
  ↓ finite environment/agent selection + step timeout
Daemon relationship scope: hub.execution.*
  ↓ named provider options + cwd + allowed outputs
Provider process executes on host
  ↓ explicit reply/GitHub authority or finish_execution

状态模型

状态类型 位置 谁读写 生命周期 / 一致性规则
Agent metadata/owner/persistence handle $PASEO_HOME agent records；agent-storage.ts daemon only Zod validate；temp write + rename 原子替换；未见 fsync durability 保证
Timeline 默认 InMemoryAgentTimelineStore；可选 durable interface 未在 production bootstrap 注入 AgentManager/provider event path live timeline 在内存；重启后用 provider streamHistory() 重建；provider history 不完整时 daemon 不能自行补齐
Project/workspace/worktree daemon stores + Git filesystem workspace managers、client/MCP workspaceId 是 owner；worktree lifecycle 与 agent archive/merge 分离
Provider-native session Claude/Codex/OpenCode/ACP/Pi/OMP runtime provider adapter + external CLI/SDK lazy start/resume/release；兼容性和 auth 由 provider 共同决定
Permission request runtime waiter + protocol event provider adapter、client/MCP responder 请求与响应映射到 provider-native enforcement；不同 provider 不等价
Terminal/process daemon runtime terminal manager/node-pty stable daemon owner；宿主进程权限，不因 UI 关闭自动变成 sandbox
Relay identity/session daemon keypair、pairing/connection state daemon/client persistent daemon identity + encrypted channels；pairing link 是 trust anchor
Hub relationship/execution hub-relationship.json + runtime controller daemon/Hub active/revoked 状态、same-origin transport validation、scoped execution
Plugin state config + child process runtime daemon/plugin global opt-in；compile/start/reload/stop，失败保持可诊断状态

契约边界

  • 内部契约： Zod schema、provider client/session interface、AgentManager ownership、workspace IDs、timeline sequence、plugin contribution API。
  • 外部 API / CLI / MCP： WebSocket/HTTP、@getpaseo/client、paseo CLI、ACP stdio、自带 MCP/native tool catalog、Hub API。
  • Agent-facing contract： create_agent 等工具、/paseo skills、provider-native options；skill 只提供使用方法，daemon schema 才是执行 authority。
  • 安全契约： loopback/Unix socket、password、Host allowlist、relay handshake、Hub relationship scopes；以上都不覆盖宿主文件系统/网络 sandbox。
  • 版本契约： 当前 client 硬编码 protocolVersion: 1，server 要求严格相等；双向兼容承诺只发生在同一 wire version 内，通过 optional fields/capability gate 演进，并非版本区间协商。

失败与降级模型

失败类型 检测方式 系统行为 降级 / 修复动作
Provider 不可用/认证失败 binary discovery、startup timeout、SDK error agent 显示 setup/error，不应伪装 idle provider diagnostics、重新登录、reload/future launch
Provider protocol 漂移 schema/API rejection、capability mismatch 特定 provider 功能失败 pin/升级 SDK，真实 provider E2E；issue #3599/#3601 是当前证据
Daemon/client 断线 socket close、generation/reconnect client 保留 replica/cache 并重同步 direct/relay reconnect；在线状态重投影，daemon 重启后从 provider history 重建 timeline
Agent crash/idle release process exit、session status 错误或 lazy release，后续尝试 resume provider-specific persistence handle + streamHistory()；失败需显式反馈，daemon 无默认 durable event log 兜底
持久化写失败 atomic write/rename error、schema parse 保留旧文件或拒绝加载新记录 temp cleanup、日志/诊断；无 fsync 表明断电级 durability 仍有限
Relay 篡改 NaCl box.open 失败 拒绝 frame/关闭 channel 重新握手；仍需 anti-replay/session 语义审计
Plugin compile/crash esbuild/child exit plugin 标记 failed，daemon 主体继续 查日志、修复后显式 reload；不要自动信任未知插件
Hub 不可信输入 trigger auth/filter/schema/timeouts 只进入匹配 workflow sender/repo allowlist、finite classifier、最小 cwd/output、容器/VM
CI 路由遗漏 path classifier + main integration PR 可能只跑相关 legs main 全集、packaged smoke、手动 real-provider tests

可复刻设计不变量

  1. Daemon owns lifecycle; clients own views. 多端 UI 不应各自持有 provider process/session 真相。
  2. Provider capability is data, not conditionals scattered in UI. mode/model/feature 先进入 manifest/schema，再由 adapter 实现。
  3. Workspace location and parent ownership are orthogonal. 跨 workspace 子 Agent 仍可属于同一 parent。
  4. Remote transport and execution authority are separate. E2EE 只保护通道，不能替代 daemon auth、workflow scope 与宿主 sandbox。
  5. Worktree isolation precedes parallelism, but never冒充 security isolation.
  6. External trigger authority must be finite and explicit. environment、agent、output 与 timeout 在 workflow 中可审查。
  7. Agent projection 与 provider history 分层。 持久化 handle 能恢复 provider session，不等于 daemon 自己拥有完整 durable event log。

关键设计决策与 trade-off

决策 选择 放弃了什么 为什么
BYOS provider 包装现有 CLI/SDK/ACP 无统一推理 loop 和统一 sandbox 复用订阅、生态与原生能力，降低模型锁定
Daemon-owned state client 只做 projection/cache 单进程/纯前端简单性 支持多端、重连、后台长任务与远程接管
Zod typed protocol schema-first RPC 自由 JSON 的快速迭代 版本漂移可检测，可生成 SDK/compat contract
Provider-specific permission 统一 UI 投影 + 原生 options “一个 policy 控所有 Agent”的表面一致性 尊重 provider 真实 enforcement；代价是安全语义不完全等价
E2EE relay relay 不读 payload 简单 reverse proxy 手机接入方便；增加 key/session/pairing 复杂度
Trusted local plugins child process + client contributions 通用 sandboxed marketplace 快速扩展 daemon/UI；安全和兼容成本由用户承担
React Native + Electron 移动/Web 共用 app，desktop 单独 shell 更小依赖与纯 Web 简单性 多端一等产品体验；测试矩阵巨大
AGPL 网络 copyleft 宽松商业嵌入 保护 hosted fork 回馈；提高企业采用门槛

值得学习的模式

  • daemon authoritative state + multi-client replica；
  • provider adapter 与 protocol manifest 分离；
  • native subagent 与 control-plane subagent 分轨展示；
  • capability token 保护 agent-injected MCP，而不是让本机所有进程无条件调用；
  • Hub 将 trigger filter、finite classifier、named agent options、allowed outputs 放在可审查 YAML 中；
  • plugin reload 保持失败可见，不让旧版本静默继续运行；
  • atomic JSON write + schema validation；
  • package lock integrity/signature 校验与 packaged Electron smoke；
  • platform-sensitive E2E 明确覆盖 real daemon、browser、Electron 和 provider。

反模式 / 踩坑点

  • 把 safe/moderate/dangerous 颜色当成统一 sandbox；
  • 让 agent 或插件运行在主用户账户并挂载全部 home/provider credentials；
  • 将 direct daemon 绑定到 LAN/0.0.0.0 却不设 password/TLS/VPN；
  • 因为 relay E2EE 就忽略 pairing link、metadata leakage 与 replay/session binding；
  • 把 494 open PR 理解为“生态繁荣所以都值得合并”；它同时意味着审阅吞吐和重复实现压力；
  • 在 Hub 中把原始外部文本直接交给有写权限/网络/回复 authority 的 Agent；
  • 在同一 checkout 并行运行多个可写 Agent，绕过 workspace/worktree owner；
  • 深 fork 整个 90 万行 TS/TSX monorepo，只为复刻 adapter 或 MCP catalog。

可借鉴的具体技术点

  1. 从 packages/protocol 抽取 schema-first control-plane contract。
  2. 复刻 AgentManager 的 ownership/lifecycle lock，而不是复制其全部产品功能。
  3. 借鉴 parentAgentId 与 workspaceId 正交建模。
  4. 采用 provider manifest + adapter interface，真实 capability 由 runtime discovery 补齐。
  5. 远程接入采用 outbound relay + E2EE 或 VPN，而不是直接公网端口。
  6. 外部 workflow 使用 finite enum classifier + least-authority output grants。
  7. plugin 默认关闭、显式安装、独立进程、可诊断 reload；若做分发市场，再增加签名、权限 manifest 与 sandbox。

架构解剖

目录结构

packages/
  protocol/    共享 schema、messages、provider manifest、version contract
  server/      daemon：agent/workspace/terminal/git/schedule/browser/plugin/Hub
  client/      TypeScript client、RPC/event projection、relay connection
  cli/         daemon/project/workspace/agent/schedule/plugin/Hub commands
  app/         Expo React Native：iOS/Android/Web 共用产品 surface
  desktop/     Electron shell、managed daemon、updater、packaged smoke
  relay/       NaCl key exchange/encrypted channel/client transport
  plugin/      plugin SDK 与 React/native contribution contracts
  highlight/   多语言 source highlighting
  website/     paseo.sh 文档/站点
public-docs/   面向用户的产品、security、SDK、Hub、plugin 文档
skills/        Paseo orchestration 与 workflow skills
.github/       CI path routing、release、Docker、desktop/mobile publishing

技术栈

  • 运行时 / 框架： Node.js >=22.19、TypeScript、Express、WebSocket、React 19、React Native/Expo、Electron。
  • Provider / protocol： Claude Agent SDK、OpenAI/Codex integration、OpenCode SDK、ACP SDK、MCP SDK、custom stdio process。
  • 数据 / 状态： JSON/JSONL-style local state、atomic file replace、daemon in-memory maps、Git worktrees、provider-native persistence handles。
  • 构建 / 打包： npm workspaces、esbuild、Metro/Expo、electron-builder、Nix、Docker multi-arch。
  • 测试： Vitest、Vitest browser、Playwright、real daemon/provider E2E、Electron packaged smoke。
  • CI/CD： GitHub Actions，path-routed required jobs、main integration、npm signature validation、multi-platform artifacts、Docker publish。

模块依赖关系

protocol ← client ← app / cli / plugin consumers
    ↑         ↑
    └──── server ─── provider SDKs / ACP / MCP
            ├── workspace / git / terminal
            ├── relay client ↔ relay service ↔ remote client
            ├── plugin child process
            └── Hub relationship / execution

desktop → server + cli + app bundle

protocol 是窄腰；server 是控制面 authority；app/desktop/CLI 是不同 client；provider SDK 与宿主进程属于数据面。

扩展机制

  1. Custom provider profile： extend first-class provider，替换 command/env/models。
  2. ACP stdio provider： 任意支持 ACP 的 Agent 运行时注册 capabilities/modes/models。
  3. MCP / native tool injection： 将 Paseo orchestration catalog 注入 Agent。
  4. Local plugins： daemon behavior + UI contributions，实验性、trusted-only。
  5. Skills： 给 Agent 提供如何调用工具的流程层，不扩大 daemon schema authority。
  6. Hub workflows： 外部事件、step DAG/conditions、named agents/environments 与 output grants。

质量与成熟度

代码质量

  • 【源码事实】TypeScript strict/schema-first 边界清晰，protocol、provider、client、server 和 plugin workspace 分层合理。
  • 【源码事实】docs/testing.md 明确禁止结构快照式测试，主张 ports/adapters unit tests 与 real E2E 两类；失败 UI 必须覆盖 pending/success/failure。
  • 【源码事实】metadata 使用 schema validation 与 temp+rename atomic write；但 atomic-file.ts:5-20 未做 file/directory fsync，不能声称断电级 durability。
  • 【源码事实】provider-specific modules 和 capability manifest 比巨型 switch 更可维护；custom ACP 进一步降低硬编码扩展成本。
  • 【推导】复杂度仍很高：agent manager、bootstrap、provider adapters、app state 与多平台 release 是深耦合热点；宽产品面让回归面远超普通 CLI Agent。
  • 【社区事实】近期 changelog/issue 仍持续修 timeline write amplification、provider startup/teardown、reconnect、mobile cache、Windows shell 和 UI performance，说明主路径在快速硬化而非稳定平台期。

测试

  • 1,416 个 test/spec/e2e 命名文件，不能等同覆盖率；仓库未公布统一 line/branch coverage 数字。
  • 单元：Vitest + typed in-memory adapters。
  • Browser：Vitest browser + Playwright real browser。
  • Daemon E2E：真实 socket、filesystem、Git/workspace、timeline/reconnect。
  • Provider：.real.e2e.test.ts 以真实凭据验证 Claude/Codex/OpenCode/Pi/OMP 等；默认 CI 不依赖外部账户。
  • Desktop：real Electron、packaged app、daemon startup 和 CLI terminal smoke。
  • 平台：Linux/Windows server，Electron macOS/Windows/Linux，Expo/iOS/Android 走独立 release/QA 路径。
  • 【本次限制】未安装依赖、未运行本地测试；运行证据来自 GitHub CI，不将静态 test count 写成“测试已通过”。

CI/CD

  • Tag v0.5.0-beta.5 对应 acad9f6881bd0e2ae3c23028f7062c95119cee2b。
  • GitHub 截至观察日已有 170 个 releases：最早 2026-02-11，约 193 天内完成 170 次发布；相邻 release 间隔中位约 0.76 天。修复速度强，但 churn、升级回归与 provenance 压力同样高。
  • 该 release commit 的 CI run 32600133683 为 success；同一 commit 的 Docker、website、release notes/Nix flows 也完成。
  • 当前 HEAD 是 release 后 [skip ci] 的 lockfile signature/Nix hash 修订，因此没有独立 HEAD run；不能把 tag CI 的绿色扩大到后续 HEAD。
  • CI 有 dependency host/integrity、lockfile signature、lint/typecheck/unit/E2E/Playwright shards、Windows、desktop packaged smoke、relay、CLI matrix。
  • Actions pinning 不一致：step-security/harden-runner 等固定 SHA，actions/checkout@v6、setup-node@v4、artifact actions 等仍跟随浮动 major tag。
  • package-lock.json integrity 覆盖率高、无 Git floating refs，是明显优点。

文档质量

  • docs/architecture.md、agent-lifecycle.md、data-model.md、protocol-compatibility.md、testing.md 深度高。
  • public-docs 覆盖 security、connectivity、Docker、providers、SDK、MCP、orchestration、plugins 与 Hub。
  • SECURITY.md 包含 threat model 和私密报告流程；GitHub Security Advisories API 当前无已发布 advisory。
  • 凭据文档存在需要收窄的绝对表述：SECURITY.md:81-83 的“never stores provider API keys”适用于 provider-owned 默认认证，不适用于 custom provider env；后者由 schema 读取、持久化并传给 runtime。
  • Changelog 超过 2,400 行，按 release 记录 added/improved/fixed 与外部贡献者。
  • 不足：实现和文档都高速变化；issue #3675 已指出 pairing restart 文案与观察行为冲突，security claims 仍需测试支撑。

Issue / PR 健康度

  • 【社区事实】477 open issues：全量快照中位年龄 24.3 天，P90 约 114.5 天，186 个无 issue comment。
  • 【社区事实】494 open PR：中位年龄 18.5 天，P90 约 60.2 天；需要单独查看 review 记录，PR API 的 issue-comment 字段不能代表无 review。
  • 【社区事实】最近 400 个 closed PR 样本中 263 merged，created→merged 中位约 3 小时、P90 约 57.1 小时，吞吐极快。
  • 【社区事实】该 merged 样本 190 个由 boudra 发起，仍有 cleiter、colonelpanic8、BrianAguilarWasco、kaspesi 等外部作者真实合入。
  • 【社区事实】全历史中外部非 bot 有 332 个 merged PR，占 merged PR 约 29.3%；外部已决 PR 合并率约 42.2%，开放 PR 的约 95.1% 来自外部作者。贡献通道真实开放，但评审队列和进入门槛都很高。
  • 【推导】这是“高活跃、高响应、高积压、高集中度”的仓库。快速 merge 是效率，也提高审阅负荷与回归概率；494 open PR 不是单向健康信号。

社区与生态

社区评价

【社区事实】Stars/Forks、外部 PR 与多语言修复表明用户基础真实。最新 issue 样本覆盖：

  • provider/API 漂移：#3599 Codex MCP protocol、#3601 OpenCode SDK/server schema；
  • daemon lifecycle：#3616 端口冲突 restart loop；
  • 持久化/性能：#3611 timeline 膨胀；
  • Windows/mobile：#3582、#3632、#3691、#3698；
  • security docs：#3675 pairing session rotation claim；
  • multi-agent UX：#3608/#3609/#3654/#3713。

【推导】这些不是“项目不可用”的证明，而是宽平台 + 多 provider 控制面不可避免的真实维护成本。Paseo 的优势是这些问题通常能在同日看到对应 PR；风险是 backlog 已大到新用户不能预期每个边缘环境都立即得到维护者响应。

衍生项目 / 插件生态

  • 官方 standalone relay：getpaseo/paseo-relay（Elixir）。
  • Relay 需求有真实外溢：官方 relay 观察日 42 stars / 11 forks，社区 Cloudflare Workers/Durable Objects 实现 zenghongtu/paseo-relay 为 185 stars / 15 forks；这证明自托管连接路径是实际需求，也意味着 deployment/security 口径分散。
  • @getpaseo/client、@getpaseo/protocol、@getpaseo/plugin 提供 SDK surface。
  • Local plugins 已支持 panel、command、theme、attachments、daemon behavior，但官方仍标记 experimental/personal local use。paseo-skins 是“社区实验→官方 theme contribution point”的早期样本，规模仍小。
  • ACP provider catalog 允许 Gemini、Hermes、Grok Build 等标准 Agent 进入同一控制面。
  • Orchestration skills 将常见 delegation/committee/workflow 变成 Agent 使用说明；技能包来自 release bundle，不是启动时下载任意远端代码。
  • Hub 是独立第一方仓 getpaseo/hub，观察日创建不足三周、19 stars、已发 7 个版本；它扩展 GitHub、Slack、Discord event-driven workflows，但尚不是有网络效应的成熟生态中心，其配置仓本身还是高权限 supply-chain surface。
  • 非官方 VS Code 扩展观察日约 287 installs；ACP adapters、Antigravity runner、Go binding 已出现，但多为个位/十位 stars，生态属于萌芽而非成熟 marketplace。
  • Open milestones 为 0、组织 Projects 为空；125 条 Discussions 主要承担 ideas/Q&A 分流，没有公开、带 owner/date/status 的产品 roadmap。

竞品对比

分层后，Paseo 的真实位置是：

Product Surface     Desktop / Web / iOS / Android / CLI
Orchestration       parent-child / heartbeats / schedules / Hub workflows
Workspace           local / worktree / scripts / Git/PR
Session Facade      typed protocol / timeline / permission / resume
Provider Adapter    Claude / Codex / OpenCode / Pi / OMP / ACP
                     ↓
Agent Runtime       外部 provider 所有

它比 terminal/worktree 工具重，但比自建多 provider daemon 完整；比 OpenHands 更 local/BYOS，但隔离不统一；比 Vibe Kanban 更接近 live agent cockpit，团队 task governance/RBAC 尚弱；比单一 Coding Agent runtime 更擅长跨 provider，而不负责模型 loop。

关键代码走读

1. packages/server/src/server/agent/agent-manager.ts

  • 职责： daemon 的 agent lifecycle authority。
  • 实现要点： createAgent 进入 registration tracking；archive/delete/cancel 走 per-agent lifecycle mutation；provider event 归一为 status/timeline/subagent/permission 后广播给 clients。
  • 审计判断： 这是核心深模块，也是复杂度集中点。任何 split 都必须保持 agent ownership、registration、timeline commit 与 provider disposal 的原子关系。

2. packages/server/src/server/agent/agent-sdk-types.ts + providers/**

  • 职责： 统一 provider client/session contract。
  • 实现要点： create/resume/send/cancel、model/mode/thinking/features、event stream 和 persistence handle；provider modules 适配 Claude/Codex/OpenCode/ACP/Pi/OMP 的不同生命周期。
  • 审计判断： 最有复用价值的是 adapter boundary，不是 UI。安全上要保留 provider-native options，不要压成一个虚假的 universal permission enum。

3. packages/server/src/server/agent/agent-storage.ts + atomic-file.ts

  • 职责： 持久 agent metadata/owner/provider handle。
  • 实现要点： Zod validate、project/workspace/Hub owner、temp file + rename。
  • 审计判断： schema + atomic replace 是正确基线；缺 fsync 表明它适合 crash consistency，不足以宣称电源故障下 durable commit。

4. packages/relay/src/crypto.ts + encrypted-channel.ts

  • 职责： daemon/client 经不可信 relay 的 E2EE channel。
  • 实现要点： Curve25519 shared key、NaCl box、随机 nonce、handshake 后 frame encryption。
  • 审计判断： confidentiality/integrity primitive 选择稳健；官方 threat model 已承认 live-session replay protection 未实现。需要把 pairing/session binding、nonce uniqueness、message counter/replay cache 与 key rotation 当成协议层，而不是由 cipher 自动保证。

5. packages/server/src/server/hub/**

  • 职责： daemon relationship、external trigger execution 与 output authority。
  • 实现要点： same-origin WebSocket transport、durable active/revoked record、scoped hub.execution.*、step timeout、named agent/environment、explicit outputs。
  • 审计判断： 配置级 least authority 做得好；但外部 prompt 最终仍进入 provider process。高风险 workflow 必须放在独立 OS user/container/VM。

6. packages/server/src/server/plugins/**

  • 职责： compile/start/reload/stop trusted local plugin，聚合 backend/client contributions。
  • 实现要点： esbuild、独立 Node child process、RPC、日志与 cleanup。
  • 审计判断： process isolation 防 daemon 内存直接污染，但不是安全 sandbox；默认关闭和“仅可信本地代码”文案是正确边界。

评分

维度 评分(1-5) 说明
功能覆盖度 5 provider/session/worktree/terminal/remote/mobile/SDK/MCP/Hub/plugin 几乎覆盖完整控制面
代码质量 4 schema-first、adapter 分层和真实 E2E 强；核心 owner 与多平台产品面仍复杂，主路径持续修复
文档质量 5 architecture、lifecycle、data model、security、testing 与用户文档罕见地完整且边界诚实
社区活跃度 4 极高吞吐与真实外部贡献；backlog 与单维护者集中扣分
架构设计 5 daemon-owned state、provider adapter、跨 provider ownership 与多端 projection 很有代表性
学习价值 5 适合研究 control plane、协议、workspace ownership、remote trust 与 provider boundary
可借鉴度 4 抽象和不变量值得复用；AGPL、90 万行 TS/TSX monorepo 不适合整仓照搬

总结

一句话评价

Paseo 是当前开源生态中产品面最完整的一类跨 provider Coding Agent 控制面；真正值得复刻的是 daemon ownership、typed adapter contract 与 workspace/parent 正交建模，而不是把 E2EE、approval UI 或 worktree 误写成统一 sandbox。

谁应该用

  • 同时使用 Claude Code、Codex、OpenCode、Pi/OMP/ACP Agent，希望统一桌面/手机监控和接管的个人开发者；
  • 需要一台 Mac mini/VPS 运行 Agent、手机远程审批和查看进度的人；
  • 想把一个 Agent 作为 orchestrator，跨 provider 创建子 Agent/worktree 的高级用户；
  • 想研究多端 Agent control plane、provider adapter、E2EE relay、Hub workflow 的平台工程团队。

谁不应该直接用

  • 只使用一个 CLI Agent、不需要移动端或多 workspace 的用户；
  • 需要强多租户 RBAC、审计日志合规和统一 OS/microVM sandbox 的企业；
  • 想直接把公网 webhook 文本交给挂载生产凭据和全仓写权限 Agent 的团队；
  • 无法接受 AGPL 网络服务义务或 beta 高频升级的商业产品；
  • 想从其源码 fork 一个轻量工具的人。

下一步

  1. 固定 v0.5.0-beta.5，在无生产秘密的测试仓做本地单 host PoC。
  2. 默认保留 provider 的 ask/auto-review；不要启用 bypass/full-access/allow-all。
  3. 验证 agent create/resume/cancel、permission、worktree、daemon restart 与移动端 reconnect。
  4. 远程优先 E2EE relay 或 Tailscale；direct network 必须 password + TLS/VPN + Host allowlist。
  5. 需要 Hub 时，用独立 OS user/container、只挂一个 repo、禁外网或最小 egress，并对 sender/repo/outputs 做 allowlist。
  6. 插件、custom binary、stdio ACP/MCP 只加载固定版本和已审计来源。
  7. 对 custom provider 避免把长期 key 直接写进 config.json；优先用短期凭据、受控 wrapper/secret manager，并将 $PASEO_HOME 作为敏感目录排除出普通备份和日志。
  8. 企业采用前完成 AGPL 法务评估、provider credential inventory、threat model、backup/recovery 与 upgrade rollback 演练。