aicodeking/pandacode · 上手攻略

  • 仓库：aicodeking/pandacode
  • 链接：https://github.com/aicodeking/pandacode
  • 分类：agent
  • 作者：spark
  • 更新：2026-10-24

一、它是什么

PandaCode 是一个原生桌面工作台，用来同时驾驭多个编码 agent CLI。它的定位一句话说清：它不自己写代码，它把你已经在用的那些编码 CLI 装进一个统一的图形界面，让你在同一个窗口里管理项目、任务、Git、终端、浏览器和 diff。

技术底座是 Tauri 2 + Rust + SQLite + 纯 TypeScript，用操作系统自带的 webview，不打包 Chromium、不常驻 Node 服务、不跑 React 运行时、不嵌编辑器引擎——这让它比同类 Electron 应用轻得多。

它能驱动的 harness 相当杂，按协议分成几类：

协议 Harness
原生（各自 CLI） Claude Code、Codex、Kimi Code、OpenCode、GLM Coding Plan、小米 MiMo（经 Claude Code）、Antigravity、xAI Grok Build
ACP（Agent Client Protocol） GitHub Copilot CLI、DeepSeek（dsh）、Command Code、Cline、Kilo Code
Pi RPC 模式 Pi 及其 fork omp（Oh My Pi）
MSP（Meta JSON-RPC 会话协议） Muse Code

配套能力：任务看板、agent 团队（architect + 最多 3 个 worker）、聊天机器人接入（Telegram/Slack/Discord/WhatsApp/本地 web）、云端 agent、本地 VM、iOS/Android 模拟器、部署、GitHub 视图、worktree 隔离、每轮变更审查、token 节省包。

许可用的是 PandaCode License：MIT 加一条——商业使用或公开发布的 fork 必须声明"This is a fork of PandaCode"并链接本仓库。无账号、无 license key、无遥测。

二、解决什么问题

现在一个人同时用 Claude Code、Codex、Copilot CLI 这件事，现状是开五六个终端：

  • 每个 CLI 各有自己的会话模型、diff 视图、权限确认 UI、终端；
  • 想并行跑几个任务，只能开多个 tab，靠人脑记"哪个 tab 在改哪个文件"；
  • 换个 harness 就要重读一遍它的文档；
  • 权限弹窗散落各处，没法集中批；
  • 想让 agent 跑长任务，只能守着电脑不睡。

PandaCode 把这些收敛成一个任务模型：每个任务（task）绑定一个 harness + model + 权限模式 + 独立的 git worktree，变成看板里的一列（Pending → In progress → Review → Completed）。具体解决的痛点：

  1. 并行任务可视化：跨项目的任务在看板上流转，Enter 发送、⌘/Ctrl+Enter steer（运行中插话），agent 跑的时候可以排队消息。
  2. 并行改文件不打架：每个任务默认开独立 worktree（<project>-worktrees/<branch>），配合"文件作用域（files scope）"让多个 worker 写不同文件时序列化。
  3. 权限确认集中化：审批请求以细条形式排在输入框上方，多个请求可一键 Approve all。
  4. 换 harness 不丢上下文：空闲任务可从模型选择器直接换 harness，用"历史交接（conversation carried forward）"机制迁移有上限的文本历史（最多 200 条消息 / 64 KiB），并明确告知用户发生了迁移。
  5. 长任务不绑电脑：云端 agent 在你自己的云账号机器上跑，笔记本合盖后继续，回来自动接上。

三、快速安装

3.1 下载安装包

从 GitHub Releases 直接下（各平台均有对应构建）：

# macOS Apple silicon（要求 macOS 12+）
curl -L -o PandaCode.dmg https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-macOS-arm64.dmg
# macOS Intel
curl -L -o PandaCode.dmg https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-macOS-x64.dmg
# Windows x64（Windows 10 1809+ 或 Windows 11）
curl -L -o PandaCode-setup.exe https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-Windows-x64-setup.exe
# Windows arm64（Windows 11 on ARM，如 Snapdragon X）
curl -L -o PandaCode-setup-arm64.exe https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-Windows-arm64-setup.exe
# Linux x64（Ubuntu 22.04+，X11 或 XWayland）
curl -L -o PandaCode.AppImage https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-Linux-x86_64.AppImage
# Linux arm64（Ubuntu 24.04+ aarch64）
curl -L -o PandaCode-aarch64.AppImage https://github.com/aicodeking/pandacode/releases/latest/download/PandaCode-Linux-aarch64.AppImage

每个文件旁都有 .sha256 校验和。

3.2 更省事：npx / Homebrew

npx pandacode                    # 下载最新构建、验证签名并安装
npx pandacode --dry-run          # 只下载并验证，不安装
brew install --cask aicodeking/pandacode/pandacode   # macOS
brew install aicodeking/pandacode/pandacode          # Linux

npx pandacode 会在本地为 macOS 应用签名，不需要再绕过 Gatekeeper。

3.3 签名与执行权限的坑（必读）

Release 构建没有代码签名，所以系统会拦：

# macOS：ad-hoc 签名且未 notarize，"系统设置 → 隐私与安全性 → 仍要打开"经常不生效
xattr -dr com.apple.quarantine /Applications/PandaCode.app
# Windows：SmartScreen 弹窗 → "更多信息" → "仍要运行"
# Linux：AppImage 需要执行权限
chmod +x PandaCode-Linux-x86_64.AppImage
# Linux：某些发行版需要 FUSE 2（libfuse2），或设置
export APPIMAGE_EXTRACT_AND_RUN=1

3.4 装编码 CLI

PandaCode 不提供任何模型额度或订阅，它只跑你已经装好并登录的 CLI。至少要装 Git 和一个编码 CLI：

npm i -g @github/copilot && copilot login              # GitHub Copilot CLI
npm i -g cline && cline auth                           # Cline
npm i -g @kilocode/cli && kilo auth login               # Kilo Code
npm i -g command-code && command-code login             # Command Code（需 Node 22+）
npm i -g @deepseek-ai/dsh                              # DeepSeek（dsh --profile acp）
npm i -g @earendil-works/pi-coding-agent               # Pi
bun install -g @oh-my-pi/pi-coding-agent                # omp（Oh My Pi，跑在 Bun 上）

Muse Code 走 Meta 的 launcher 装到 ~/.local/bin/muse，然后 muse login。

3.5 从源码构建

git clone https://github.com/aicodeking/pandacode.git
cd pandacode
npm ci
npm run desktop        # 等同于 npm run tauri dev

需要 Node.js 22 + 稳定版 Rust + 对应 OS 的 Tauri 前置依赖。 npm run dev 只起前端（普通浏览器里跑的是模拟数据，文件、Git、终端都是假的，不能当真）。npm run tauri build 出本地安装包，npm run release:build 出正式发布资产。

四、核心用法

4.1 基本流程

  1. 打开项目文件夹；
  2. 点 New task 或按 ⌘/Ctrl N；
  3. 在输入框里选 harness + model + reasoning effort（选择器可搜索，新任务记住上次选择）；
  4. 发送。

打开 Changes 看 diff 并暂存，或打开终端跑 shell。会话与 provider session ID 会跨重启持久化，但 agent 只在活跃轮次才启动。

4.2 快捷键

键 功能
⌘/Ctrl N 新任务
⌘/Ctrl K 命令面板
⌘/Ctrl J 终端
⌘/Ctrl B 侧边栏
⌘/Ctrl , 设置
⌘/Ctrl F / ⌘/Ctrl G 线程内查找 / 下一个匹配
Enter 发送（agent 运行中则排队）
⌘/Ctrl Enter steer（运行中插话）
Shift Enter 换行
⌘/Ctrl +/−/0 整体界面缩放（不只是文字）
⌘/Ctrl Shift Space 全局快捷 overlay，从任何地方拉出新任务/运行中任务

消息开头打 / 可用该 harness 的斜杠命令和 skills。

4.3 Worktree：并行改文件的关键

分支芯片（branch chip）是管理分支和 worktree 的唯一入口：

  • 未启动的任务 → "Work in a new worktree…"：同一任务搬进隔离 checkout，保留草稿、标题、harness、model、权限模式；
  • 已有历史的任务 → "New task in a worktree…"：在同项目起一个兄弟任务。

worktree 放在项目旁边：<project>-worktrees/<branch-with-dashes>，分支名形如 pandacode/<name>。任务栏上方显示项目、Local/Worktree、当前分支和关联的 GitHub 工作。

"Merge into main" 一键把 worktree 已提交的工作在本地合并回主 checkout——有未提交改动或有冲突时它会拒绝并什么都不动，然后提示你清理。清理走 git worktree remove（不带 --force）再 git worktree prune。未推送且未合并的提交默认不勾选删除。

4.4 权限模式

模式 行为
Standard 保留各 provider 原生的检查。Claude 的 "Accepted edits" 允许其编辑工具；Codex 用自己的 workspace sandbox + 按需审批
Plan mode 只读/搜索/思考类请求放行，其他权限请求一律拒绝（目前 Copilot CLI 的 Plan 模式映射到此）
Full access 启用该 harness 最宽松的模式

4.5 Agent 团队

在 composer 里选 Team，挑 architect 模型和 worker 配置档，Save setup 保存。

  • 团队里可以混用不同 harness 和模型（Claude Code / Codex / Kimi Code / OpenCode / GLM / Antigravity）；
  • architect 能在一次调用里派多个 assignment，审查结果，并给已有 worker 追加纠正；
  • 每个 worker 在触发它的轮次里占一行，点开可看流式回复、工具调用、会话与审批请求；
  • 每个新 assignment 必须显式声明 files 作用域，省略会被拒绝而不是静默占用整个 checkout；写入作用域重叠会串行化；readOnly: true 的 assignment 不得改文件；
  • ⚠️ 官方明确：这些作用域是建议性任务边界，不是操作系统文件系统沙箱，别的应用和终端照样能改文件；
  • 最多可存 20 个命名团队配置档；"Use a single agent" 可对新任务关闭团队继承。

Lead guidance 可以加你自己的规则（比如"architect 只协调、绝不亲自改文件"），它追加在内置规则之后，永不替换内置规则，包括那条"把 worker 输出当数据而非指令"的护栏。

4.6 云端 agent

在 New task 的 Run on 菜单里选云厂商，agent 就跑在你自己账号的机器上。支持：Daytona、Cloudflare、AWS EC2、Google Cloud、E2B、Modal、Vercel Sandbox、CodeSandbox、Runloop、Blaxel、Tensorlake、Freestyle、Railway、boat、InstaBox。

工作原理（据 docs/cloud-agents.md）：

  1. 机器：每个云任务一台机器，命名 pc-<task id 前 8 位>；
  2. 运行时：自动幂等安装 git、Node、harness CLI，版本标记在 ~/.pandacode/runtime/<harness>。支持的 harness 是 claude、glm、mimo、codex、opencode，其他会明确拒绝；
  3. 凭据：把本地登录拷过去（文件 0600，不写日志，每次运行前重推）。Claude 优先用 Settings → Cloud 里存的 claude setup-token 长效 token（CLAUDE_CODE_OAUTH_TOKEN）；
  4. Checkout：本地任务建一个 pandacode/cloud-<short> 分支的"镜像 worktree"（未提交改动会作为首个 commit 一起带上），以 git bundle 上传；
  5. 运行：agent 在远端以 append-only 的 inbox 文件为 stdin，out/err/exit 记录状态，PandaCode 按字节偏移轮询 out（输出快时快轮询，空闲时降速，网络错误时退避）；
  6. 睡眠/退出/恢复：合盖只暂停本地轮询，远端靠 keep_alive 继续（上限由 Info::max_unattended_minutes 决定）；退出 PandaCode 不影响远端；重开时从 offset 0 重放日志接上，inbox 里已有的行不会重写；
  7. 空闲：运行结束后 keep_alive(…, 15) 让机器自行停止；下次提示词会重新开机。非持久化机器或已删机器会被重建并从镜像 worktree + harness 保存的 session 文件恢复，保证 --resume 还能用。

⚠️ PandaCode 的本地 MCP host tools 不会提供给云端运行。

4.7 机器人接入

把 agent 放到 Telegram、Slack、Discord、WhatsApp 或本地 web chat 后面，每个对话就是一个普通任务（同样的流式、composer、模型选择器）。侧边栏 Bots 视图列出每个 bot 和它最新的消息。Bot 设置分页签：profile、conversations、memory、schedules、channels、rules、activity。

4.8 其他能力

  • GitHub 视图：仓库列表 + threads + PR + issues，一键 review、fix checks、merge、solve issue，每个开成独立关联 thread。
  • 模拟器：iOS Simulator 与 Android 模拟器在 inspector 里跑，agent 做完可以直接点。
  • 部署：从 header 起 Vercel、Cloudflare、Railway、AWS、Google Cloud 的部署任务，带审批门控的 CLI 运行。
  • Token saver：按任务的 response-style pack 减少输出 token。
  • Jev 附加插件（可选，默认关闭）：独立 Chrome profile 里的工作评审、项目规则检查和应用测试。

五、典型适用场景

  • 多 harness 并行：Claude Code 打主力、Copilot CLI 跑 lint/小修、Codex 做 review——在一个窗口里同时跑。
  • 大批量重构：架构师派多个 worker 各改一块文件，靠 files 作用域避免互撞。
  • 长任务托管：云端 agent 跑 overnight，本地合盖睡觉。
  • 移动端触达：用 Telegram 派活给 agent，用手机看进度。
  • 移动端开发：agent 写完 iOS/Android 代码，直接在模拟器里点。
  • 自托管 + 隐私敏感：数据只落本地 SQLite，无遥测无账号。

六、坑与注意

  1. macOS 首次启动会被 Gatekeeper 拦。ad-hoc 签名 + 未 notarize，"仍要打开"经常不生效，必须 xattr -dr com.apple.quarantine /Applications/PandaCode.app。或者干脆用 npx pandacode，它本地签名后不需要这步。
  2. Linux AppImage 可能缺 FUSE 2。装 libfuse2，或 APPIMAGE_EXTRACT_AND_RUN=1。
  3. npm run dev 是模拟环境，不是真实运行。浏览器里文件、Git、终端全是假的，做 UI 演示可以，当功能验证不行。
  4. 你必须自己装 CLI 并登录。PandaCode 不含 provider 订阅和额度。DeepSeek、Command Code 这类在 PandaCode 里看不到用量限额，得自己去对应平台查。
  5. Pi/omp 没有自带审批系统。PandaCode 通过本地 loopback bridge 扩展强制权限模式，集成控制台需要 Full access；omp 会被以 --approval-mode yolo 启动，以保证 bridge 是唯一的审批门。
  6. 换 harness 会丢私有推理、工具执行状态和早先的图片字节——交接只传有上限的文本历史（最多 200 条消息 / 64 KiB）。界面会显示"Conversation carried forward"提示。Codex 只在创建 thread 时支持注册动态工具，所以给它开/关团队会先排队一次历史交接再替换原生 ID。
  7. 换 harness 后不能复用上一个 harness 的原生 resume ID，provider 特有的 goal/settings 状态也不会带过去。
  8. 云端 agent 只支持 5 个 harness：claude、glm、mimo、codex、opencode。想用别的得自己在远端装。
  9. 云端运行拿不到本地 MCP host tools。
  10. 云端机器的凭据会被复制到远端（0600 文件）。这是把登录态搬出本机的动作，安全上要知情。
  11. files 作用域不是沙箱。官方原话："These are advisory task boundaries, not an operating-system filesystem sandbox." 别的应用和终端照样能改文件。
  12. worker 是配置档，不是常驻进程——architect 按需从配置档创建命名 assignment。
  13. 无遥测不等于零出网。README 明确列了自动检查：约每 6 小时查已装 CLI 的最新版本（formulae.brew.sh、downloads.claude.ai、api.github.com、cdn.kimi.com）、每天拉公开模型价格表、启动时查自己的更新。你选的 provider 的数据照发不误，但"完全不联网"的说法不成立。
  14. 密钥存储位置跨平台不一致：macOS 存在 app data 目录的 secrets.json（权限 0600，不进 Keychain，所以更新不会要你的登录密码；旧版本存 Keychain 的会在首次使用时迁移），Linux 用 Secret Service，Windows 用 Credential Manager。
  15. macOS 文件夹访问被拒时，用 Browse 按钮选目录，或到"系统设置 → 隐私与安全性 → 文件与文件夹"给 PandaCode 授权。
  16. 资源模型：没有后台目录轮询，没有递归文件 watcher；agent 每轮结束就退出，靠 provider session ID 恢复。
  17. 许可不是纯 MIT。商业使用或公开发布的 fork 必须声明"This is a fork of PandaCode"并链接本仓库。团队做二次分发要注意。

七、与同类对比

工具 定位 对比 PandaCode
Claude Code / Codex CLI 原生终端 单 CLI 交互 PandaCode 是多 harness 统一层，加看板、worktree、权限审批集中化、云端 agent、机器人
Cursor / Windsurf / Zed AI 编辑器 它们自带编辑器内核和模型服务；PandaCode 不内置编辑器，靠系统 webview，模型全靠外部 CLI 账号
Continue / Cline / Roo Code IDE 内插件 插件形态受限于 IDE；PandaCode 是独立桌面应用，能管多项目并行
Conductor / CodexBar 等多代理工具 多 agent 编排 PandaCode 的差异在协议广度（原生 + ACP + Pi RPC + MSP 四种）、worktree 隔离和机器人/云端通道
OpenHands / 自建 agent 沙箱 自带执行环境 PandaCode 不自己实现 agent，复用各家 CLI，因此能力上限等于那些 CLI，但维护成本低

八、一句话结论

PandaCode 是目前"给编码 agent CLI 套一层统一工作台"这条路线里完成度最高的选择之一——协议覆盖广（原生/ACP/Pi RPC/MSP）、worktree + 文件作用域的并行隔离设计扎实、云端 agent 与机器人接入让它真的能托管长任务，Tauri 架构也让它比 Electron 同类轻。但要清楚：它不提供模型额度、不提供编辑器内核、不内置沙箱、不内置任何 agent 能力——所有能力都来自你装的那些 CLI；而且 macOS 签名、跨 harness 上下文交接、无遥测但有自动检查这三点都需要实际评估。

九、来源清单

  • GitHub README（aicodeking/pandacode，main 分支）— 已 fetch，2026-10-24
  • docs/providers.md — 已 fetch
  • docs/worktrees.md — 已 fetch
  • docs/cloud-agents.md — 已 fetch
  • docs/architect-workers.md — 已 fetch
  • 仓库卡 organized/repo_cards/4604-aicodeking-pandacode.md

十、不确定与待核项

  • ⚠️ 本文未做 web_search 补充：本篇完全基于仓库 README + 4 份官方 docs 写作，未使用搜索结果。README 中链接的其他 docs（docs/task-board.md、docs/bots.md、docs/github.md、docs/attachments.md、docs/browser.md、docs/agent-usage.md、docs/agent-updates.md、docs/homebrew.md、docs/platform-support.md、docs/jev.md、docs/turn-changes.md、docs/slash-commands.md、docs/wallpapers.md、docs/releasing.md）未逐份抓取，其中 cloud-agents.md 提到的 provider 列表（docs/cloud-agents.md 表格含 InstaBox 等）在 README 的 provider 列表里部分未出现，两处口径可能不一致。
  • ⚠️ README 有截断：抓取内容在 "Resource limits" 一节末尾被截断（"so a follow-u…"）。npm run dev 之外的 Resource limits 后续细节、以及 README 可能存在的后续章节，本文未覆盖。
  • ⚠️ 版本号未核实：本文未抓取 package.json / Cargo.toml / 最新 release tag。文中出现的 "Node.js 22"、"schema 27"、"schema 14" 等均为文档内引用，未独立验证。Node 22 的要求在 README（Command Code）与 build from source 两处均提到，交叉一致。
  • ⚠️ 未抓 commit hash：仓库最近提交 2026-10-24，迭代快，建议生产使用前记录 git rev-parse HEAD。
  • ⚠️ star 数未交叉验证：仓库卡记 600 stars，本次未用 web_search 复核。
  • ⚠️ license 细节：README 称 "MIT with one addition"，未打开 LICENSE 文件原文核对该附加条款的确切措辞。
  • ⚠️ 「支持 harness 列表」有两处口径：README 说 ACP 支持 Copilot/Antigravity/Grok Build/DeepSeek/Command Code/Cline/Kilo Code，docs/cloud-agents.md 却只列 claude、glm、mimo、codex、opencode 支持云端运行。这两处不是同一维度（本地 vs 云端），本文按"本地支持广、云端仅 5 个"表述，但云端与 ACP harness 的交叉（如 Copilot CLI 能否跑在云端）未验证。
  • ⚠️ 未实测：本文所有命令均来自官方文档，未实际执行安装或运行。