Paseo 进阶实战教程：多 Agent / Worktree / Chat / Loop

面向已经具备 Claude Code / Codex / OpenCode 使用经验的开发者
目标：学会用 Paseo 在真实项目中做多 Agent 编排、隔离开发、协作沟通与自动修复闭环

---

1. Paseo 是什么

Paseo 不是模型本身，而是一个本地运行的 Agent 调度层。

它的核心价值是：

• 在你的机器上统一管理多个 AI 编码 Agent
• 同时接入 Claude Code、Codex、OpenCode
• 支持多个 Agent 并行运行
• 支持 worktree 隔离任务
• 支持 chat room 协作
• 支持 loop 自动修复直到验证通过
• 支持桌面端、CLI、移动端统一连接同一个本地 daemon

你可以把它理解成：

• Claude / Codex / OpenCode = 干活的模型 Agent
• Paseo = 本地 Agent 调度中心

---

2. 工作原理

Paseo 使用 client-server 架构：

CLI / Desktop / Mobile / Web
            |
         Paseo daemon
            |
   Claude / Codex / OpenCode

也就是说：

1. 先启动本地后台服务 daemon
2. 再通过 CLI / App 连接 daemon
3. daemon 去创建、运行、恢复、停止具体 Agent

所以使用 Paseo 时，最重要的两个概念是：

• daemon：后台服务
• agent：执行具体任务的智能体

---

3. 安装前准备

在使用 Paseo 前，你至少要准备好一个 Provider CLI，并确保已经登录可用：

• Claude Code
• Codex
• OpenCode

建议先确认这些命令能在终端里找到，例如：

claude --version
codex --version
opencode --version

此外，仓库里要求的 Node 版本在 .tool-versions 中是：

• nodejs 22.20.0

---

4. 安装方式

注意：虽然你查看的是 xianyu110/paseo 仓库，但当前源码中的包名和 CLI 名仍然是上游命名：

• npm 包：@getpaseo/cli
• CLI 命令：paseo

4.1 全局安装 CLI

npm install -g @getpaseo/cli

安装完成后，查看版本：

paseo --version

4.2 启动本地 daemon

paseo daemon start

查看状态：

paseo daemon status

4.3 检查 provider 是否可用

paseo provider ls

查看某个 provider 的模型：

paseo provider models codex
paseo provider models claude

带思考选项一起看：

paseo provider models codex --thinking

---

5. 核心命令总览

Paseo 最重要的命令可以分成这几类：

5.1 Agent 基础命令

paseo run
paseo ls
paseo logs
paseo send
paseo wait
paseo stop
paseo archive
paseo delete
paseo inspect

5.2 Daemon 管理

paseo daemon start
paseo daemon status
paseo daemon stop
paseo daemon restart

5.3 Provider 管理

paseo provider ls
paseo provider models <provider>

5.4 进阶编排能力

paseo chat ...
paseo loop ...
paseo worktree ...
paseo terminal ...
paseo permit ...

---

6. 先掌握基础 Agent 工作流

6.1 启动一个 Agent

最简单：

paseo run "阅读当前仓库并总结模块结构"

指定 provider：

paseo run --provider codex/gpt-5.4 "修复当前仓库的后端测试"
paseo run --provider claude/opus "审查当前项目的架构风险"

6.2 后台运行

paseo run -d --title "fix-tests" --provider codex/gpt-5.4 "修复失败测试"

常用参数：

• -d, --detach：后台运行
• --title：给 agent 起名字
• --provider：指定 provider/model
• --model：指定模型
• --mode：指定运行模式
• --cwd：指定工作目录
• --worktree：在新 worktree 中运行
• --base：worktree 基准分支
• --wait-timeout：等待超时
• --output-schema：要求结构化输出

6.3 查看 Agent 列表

paseo ls

全局列出所有目录下的 Agent：

paseo ls -g

JSON 输出：

paseo ls --json

6.4 查看日志

paseo logs <agent-id>

实时跟随：

paseo logs <agent-id> -f

只看最后 10 条：

paseo logs <agent-id> --tail 10

只看工具调用：

paseo logs <agent-id> --filter tools

6.5 给 Agent 追发任务

paseo send <agent-id> "顺便把测试补上"

不等待执行结束：

paseo send <agent-id> --no-wait "继续优化错误处理"

从文件读取 prompt：

paseo send <agent-id> --prompt-file ./handoff.txt

带图片：

paseo send <agent-id> --image screenshot.png "按这张图调整页面布局"

6.6 等待执行结束

paseo wait <agent-id>

带超时：

paseo wait <agent-id> --timeout 60

6.7 停止、归档、删除

paseo stop <agent-id>
paseo archive <agent-id>
paseo delete <agent-id>

强制归档运行中的 Agent：

paseo archive <agent-id> --force

---

7. 多 Agent 并行：最常用的进阶模式

多 Agent 最适合下面这些分工：

• impl：负责实现
• review：负责审查
• qa：负责测试思路和验收标准
• research：负责读代码和定位问题

推荐搭配：

• Codex：实现
• Claude：审查 / 规划 / 验证

7.1 并行启动多个 Agent

paseo run -d \
  --title "impl-backend-auth" \
  --provider codex/gpt-5.4 \
  "在当前仓库实现登录接口，包含 session 管理和错误处理"

paseo run -d \
  --title "review-auth-design" \
  --provider claude/opus \
  "阅读当前认证相关代码，审查登录接口设计风险，不要修改代码，只输出评审意见"

paseo run -d \
  --title "test-plan-auth" \
  --provider claude/sonnet \
  "阅读仓库后输出登录功能的测试清单，覆盖成功、失败、边界情况"

查看所有 Agent：

paseo ls

7.2 多 Agent 并行使用建议

适合并行的场景：

• 一个 Agent 改代码，另一个 Agent 做 review
• 一个 Agent 查代码，另一个 Agent 做实现
• 一个 Agent 写后端，另一个 Agent 整理测试计划

不适合并行的场景：

• 多个 Agent 同时改同一批文件
• 多个 Agent 没有清晰边界，互相覆盖改动

7.3 最佳实践

• 每个 Agent 都起明确 title
• 每个 Agent 的职责尽量单一
• 不同 Agent 尽量分属不同模块或不同 worktree
• 长任务默认都用 -d

---

8. Worktree：隔离开发的关键能力

如果多个 Agent 同时在同一个工作区改代码，很容易冲突。
Paseo 的正确进阶玩法是：

• 每个大任务一个 worktree
• 不同 Agent 在不同 worktree 工作

8.1 在新 worktree 中运行 Agent

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "feature-auth" \
  --worktree feature-auth \
  "实现用户认证模块，包括登录、退出、token 刷新"

指定基准分支：

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "feature-auth" \
  --worktree feature-auth \
  --base main \
  "实现用户认证模块，包括登录、退出、token 刷新"

8.2 同时开多个 worktree 任务

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "fix-billing" \
  --worktree fix-billing \
  --base main \
  "修复 billing 模块中的金额计算错误，并补测试"

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "feature-notification" \
  --worktree feature-notification \
  --base main \
  "实现通知中心页面和通知已读逻辑"

8.3 查看 worktree

paseo worktree ls

8.4 归档 worktree

paseo worktree archive feature-auth

8.5 什么时候必须用 worktree

强烈建议使用 worktree 的场景：

• 大功能开发
• 重构
• 数据库迁移
• 多 Agent 并行写代码
• 你不想污染主工作区

---

9. Chat Room：让多个 Agent 协作

Paseo 的一个重要特点是支持 Agent 通过 chat room 协作，而不是靠你手工搬运上下文。

9.1 创建聊天室

paseo chat create auth-room --purpose "认证模块改造协作"

9.2 发消息

paseo chat post auth-room "任务启动：实现、评审、QA 三个角色开始协作"

回复某条消息：

paseo chat post auth-room "我建议先拆 session 管理" --reply-to <msg-id>

9.3 @ 指定 Agent

paseo chat post auth-room "@abc123 登录接口已完成，请开始 review"

群发：

paseo chat post auth-room "@everyone 当前目标：今天内完成 auth 模块端到端可用版本"

9.4 读取消息

paseo chat read auth-room --limit 20

只看某个 Agent 的消息：

paseo chat read auth-room --agent abc123

9.5 等待新消息

paseo chat wait auth-room --timeout 5m

9.6 推荐的协作模式

你可以把一个 room 当作任务总线：

• orchestrator 发任务
• impl 汇报进度
• review 提问题
• qa 列验收标准

例如：

paseo chat post auth-room "需求：支持邮箱登录、退出、token 刷新"
paseo chat post auth-room "@impl-agent 先给出实现拆分方案"
paseo chat post auth-room "@review-agent 拆分方案出来后马上审查"
paseo chat post auth-room "@qa-agent 给出验收清单"

9.7 什么时候适合 chat

适合：

• 3 个以上 Agent 协作
• 希望上下文共享、可追踪
• 希望你自己也随时能插话、纠偏

不适合：

• 只有一个 Agent 的小任务
• 非协作型一次性执行

---

10. Loop：自动修到通过

loop 是 Paseo 非常适合工程化场景的功能。
它的核心思想是：

• 一个 worker Agent 干活
• 一个 verifier Agent 检查
• 一个或多个 --verify-check 命令做最终裁决
• 失败就继续迭代，直到通过或达到上限

10.1 修测试直到通过

paseo loop run "修复当前仓库失败的后端测试" \
  --verify "检查这次改动是否真的解决了问题，并确认没有引入明显回归" \
  --verify-check "npm test" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/opus \
  --max-iterations 5

10.2 修 lint / typecheck

paseo loop run "修复当前仓库中的 TypeScript 和 lint 报错" \
  --verify "检查修复是否最小且没有破坏原有语义" \
  --verify-check "npm run typecheck" \
  --verify-check "npm run lint" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/sonnet \
  --max-iterations 6

10.3 每轮归档 Agent

paseo loop run "修复单测" \
  --verify "审查修复质量" \
  --verify-check "npm test" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/opus \
  --archive

10.4 查看 loop 状态

paseo loop ls
paseo loop inspect <loop-id>
paseo loop logs <loop-id>

停止 loop：

paseo loop stop <loop-id>

10.5 Loop 适用场景

非常适合：

• npm test
• pytest
• go test ./...
• cargo test
• npm run typecheck

不适合：

• 需求本身不明确
• 没有可执行验证标准
• 需要大量产品判断的任务

---

11. 一个完整的高级工作流示例

目标：实现“用户登录 + token 刷新”功能，并尽量自动化闭环。

第 1 步：开 worktree 跑实现 Agent

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "impl-auth-refresh" \
  --worktree auth-refresh \
  --base main \
  "在当前仓库实现用户登录与 token 刷新，并补充必要测试"

第 2 步：起 review Agent

paseo run -d \
  --provider claude/opus \
  --title "review-auth-refresh" \
  --worktree auth-refresh \
  --base main \
  "只做审查：阅读 auth-refresh worktree 中的改动，关注 session、安全性、错误处理、测试覆盖"

第 3 步：创建 chat room

paseo chat create auth-refresh-room --purpose "登录与 token 刷新功能协作"

第 4 步：广播当前目标

paseo chat post auth-refresh-room "@everyone 本轮目标：完成登录、刷新 token、测试通过"

第 5 步：启动 loop 自动逼近完成状态

paseo loop run "继续修复 auth-refresh 中未通过的测试和问题" \
  --verify "检查认证实现是否合理，尤其关注安全与边界条件" \
  --verify-check "npm test" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/opus \
  --max-iterations 5

第 6 步：持续观察进度

paseo ls
paseo logs <impl-agent-id> -f
paseo chat read auth-refresh-room --limit 30
paseo loop ls

---

12. 推荐的高级使用模板

模板 A：实现 + 审查

• Codex：实现
• Claude：审查
• loop：自动验证

适合：

• 功能开发
• bug 修复
• 测试修复

模板 B：研究 + 实现 + QA

• Claude Sonnet：先研究代码和风险
• Codex：根据结论实现
• Claude Opus：最终验收

适合：

• 复杂需求
• 旧代码库改造
• 大模块重构

模板 C：多功能并行开发

• 每个功能一个 worktree
• 每个 worktree 一个 impl Agent
• 一个或多个 review Agent
• 用 chat room 做跨任务协调

适合：

• 同时开发多个 feature
• 团队式 Agent 编排
• 需要保留协作历史

---

13. 最佳实践清单

13.1 title 要清晰

推荐：

--title "impl-checkout-phase1"
--title "review-auth-risk"
--title "qa-billing-tests"

避免：

--title "task1"
--title "fix"
--title "agent"

13.2 尽量固定 provider 分工

建议长期约定：

• codex/gpt-5.4：实现
• claude/opus：审查 / 高难度验证
• claude/sonnet：研究 / QA / 测试清单

13.3 长任务都用后台模式

paseo run -d ...

然后配合：

paseo ls
paseo logs <id> -f

13.4 高风险任务默认用 worktree

比如：

• 重构
• 大功能
• 数据库改动
• 多 Agent 并行写代码

13.5 只要有明确验证条件，就考虑 loop

如果你能写出：

--verify-check "npm test"

那这个任务通常就值得放进 loop。

---

14. 常见问题

Q1：多个 Agent 会不会互相覆盖代码？

会。

解决方式：

• 不同任务用不同 --worktree
• 同一工作区内不要让多个 Agent 同时改同一模块

Q2：chat room 会不会自动驱动 Agent 行动？

Paseo 支持基于 room 和 @mention 的协调，但最佳实践仍然是：

• 明确 @ 谁
• 明确让它做什么
• 必要时对对应 Agent 再发 paseo send

Q3：loop 是不是万能自动修复器？

不是。
它最适合“目标明确 + 可验证”的任务，不适合需求模糊的探索性工作。

Q4：为什么 worktree 这么重要？

因为高级用法里真正痛苦的往往不是模型，而是：

• 上下文混乱
• 文件冲突
• 中途回滚困难

worktree 是最简单有效的隔离手段。

---

15. 推荐起手式

如果你现在就要开始真正使用 Paseo 的进阶能力，可以先跑这套：

paseo daemon start
paseo provider ls

paseo run -d \
  --provider codex/gpt-5.4 \
  --title "impl-auth" \
  --worktree auth-task \
  --base main \
  "实现用户认证功能并补测试"

paseo run -d \
  --provider claude/opus \
  --title "review-auth" \
  --worktree auth-task \
  --base main \
  "审查 auth-task 中的认证实现风险，不要改代码"

paseo chat create auth-task-room --purpose "auth 功能协作"
paseo chat post auth-task-room "@everyone 本轮目标：完成 auth 功能与测试"

paseo loop run "修复 auth-task 中未通过的问题" \
  --verify "审查认证实现与测试质量" \
  --verify-check "npm test" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/opus \
  --max-iterations 5

如果这套流程能跑顺，你就已经掌握 Paseo 的核心进阶玩法了。

---

16. 命令速查表

Daemon

paseo daemon start
paseo daemon status
paseo daemon stop
paseo daemon restart

Provider

paseo provider ls
paseo provider models codex
paseo provider models claude --thinking

Agent

paseo run "..."
paseo run -d --title "..." --provider codex/gpt-5.4 "..."
paseo ls
paseo logs <id> -f
paseo send <id> "..."
paseo wait <id>
paseo stop <id>
paseo archive <id>
paseo delete <id>

Worktree

paseo run --worktree feature-x --base main "..."
paseo worktree ls
paseo worktree archive feature-x

Chat

paseo chat create room-name --purpose "..."
paseo chat post room-name "..."
paseo chat post room-name "@agent-id ..."
paseo chat read room-name --limit 20
paseo chat wait room-name --timeout 5m

Loop

paseo loop run "..." \
  --verify "..." \
  --verify-check "npm test" \
  --provider codex/gpt-5.4 \
  --verify-provider claude/opus \
  --max-iterations 5

paseo loop ls
paseo loop inspect <id>
paseo loop logs <id>
paseo loop stop <id>

---

17. 参考链接

• 仓库 README
  https://github.com/xianyu110/paseo/blob/main/README.md

• CLI 总入口
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/cli.ts

• run 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/agent/run.ts

• send 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/agent/send.ts

• wait 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/agent/wait.ts

• chat 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/chat/index.ts

• loop 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/loop/index.ts

• worktree 命令
  https://github.com/xianyu110/paseo/blob/main/packages/cli/src/commands/worktree/index.ts

• 架构文档
  https://github.com/xianyu110/paseo/blob/main/docs/ARCHITECTURE.md

---