Pi Agent Desktop 使用指南

下载安装

打开 下载页面，网站会优先推荐当前系统对应的安装包。v0.4.1 桌面安装包已经内置 Pi Coding Agent 1.2.0 与 Herdr v0.8.2，日常使用不需要另外安装 Pi CLI。

安装于 macOS

1. 根据芯片类型下载 Apple Silicon 或 Intel 版本的 DMG。
2. 打开 DMG，把 Pi Agent Desktop 拖到“应用程序”文件夹。
3. 从“应用程序”打开。正式发布包已经签名并通过 Apple 公证。

安装于 Windows

1. 下载 Windows x64 未签名 Beta 安装程序并运行。
2. 按安装向导完成安装。
3. 当前安装包尚未配置代码签名；如果 SmartScreen 显示“未知发布者”，确认文件来自项目的 GitHub Releases后，选择“更多信息 → 仍要运行”。

安装于 Linux

1. 下载 Linux x64 AppImage。
2. 在文件属性中允许“作为程序执行”，或运行 chmod +x Pi-Agent-Desktop-*.AppImage.
3. 打开 AppImage。Linux 版本当前使用手动更新。

认识主界面

开始第一条会话

1. 在左侧选择项目目录。
2. 点击“新建会话”。
3. 确认输入框下方已经选择可用模型。
4. 描述你的目标，例如“介绍这个项目”或“帮我查找登录页面”。

如果只是聊天或处理临时任务，也可以选择一个空目录。只有在你明确授权工具后，Agent 才能读取或修改相应项目文件。

自动命名与回到最新消息

新会话发送首条有效消息后，应用会用当前模型在后台生成不超过 40 个字符的简短标题，并实时更新侧边栏。标题生成不会进入会话历史或阻塞正常回复；模型不可用时会使用消息开头作为本地兜底。

• 在“设置 → 通用 → 会话”中关闭或重新开启“自动命名新会话”。
• 手动设置的名称始终优先，自动标题不会覆盖手动重命名。
• 斜杠命令、空白、单字符和纯图片消息不会触发自动命名。
• 向上浏览旧消息后，点击右下角“滚动到底部”按钮即可回到最新内容并恢复流式输出自动跟随。

切换界面语言

打开设置→通用→界面语言

可以选择 English、简体中文或繁體中文。台湾、香港、澳门及 zh-Hant 系统语言会默认使用繁体中文，并优先保留你已选择的语言。原生对话框、文件右键菜单、浏览器确认提示、托盘与应用菜单都会同步切换。

调整聊天字号、对话宽度与模型回复宽度

打开设置→通用→会话

• 聊天字号提供小、标准、大、特大四档，修改会立即应用，并在重启后保留。
• 舒适宽度保持 760px；扩展宽度会随窗口自适应，最大为 960px。
• “模型回复宽度”单独控制回复气泡：舒适宽度保持原有阅读宽度；“填满对话列”让段落、表格和代码块使用当前聊天列的完整空间。
• 模型回复宽度与外层对话宽度相互独立；打开右侧面板后，填满模式会随可用空间收缩。
• 消息、过程详情和输入框使用统一内容边界，在宽屏和最小窗口下也能保持对齐。

设置提示缓存预热

“提示缓存预热”提供关闭、“长时间运行工具时”和“空闲时也预热”三种模式。它可以在长工具调用或空闲期间保持模型提示缓存活跃，但可能消耗模型用量；该设置与 Pi CLI 共享。若部分运行中的会话未能立即更新，重新打开这些会话即可。

发送附件与操作本地文件链接

• 通过拖放、粘贴或输入框旁的附件按钮添加图片或任意文件；非图片附件显示为文件卡片。
• 大尺寸截图和 Retina PNG 会在进入草稿前按最长边 2048 像素、目标约 512 KiB 自动缩放并转为 JPEG，常见截图可以保存到草稿并在重启后恢复。
• 支持只发送附件；Agent 正在流式回复时，带附件的消息也可以加入 Steer / Follow-up 队列。
• 发送失败时，附件和文字会合并回当前草稿，不会覆盖发送期间继续输入的新内容。
• Markdown 消息会识别 Windows、POSIX 和 UNC 本地路径；仓库内相对路径在应用内打开，绝对路径可在系统文件管理器中定位。
• 右键点击本地文件链接，可以打开文件、选择默认应用或“打开方式”、另存为、复制路径、复制文本内容，或在文件夹中显示。
• 输入 @ 引用项目文件时，应用会按需浏览并搜索最多 300 个候选；在用户主目录中默认隐藏 AppData 或 Library ，显式输入目录名称后仍可访问。
• 文件搜索工具不可用、超时或失败时，界面会显示降级状态并保留当前目录候选，不会卡住输入或静默返回不完整结果。

使用内置浏览器

打开主界面右侧→浏览器

内置浏览器使用真实 Chromium 页面。你和 Agent 操作同一个页面，可以保留标签页、Profile 与登录状态，并在需要时随时接管。

管理浏览器权限

在“设置 → 浏览器”中管理全局默认和具体会话的永久权限。授权弹窗产生的许可只对当前会话临时生效；不再需要时，可以随时撤销。

高级浏览器模式

高级模式提供可信输入、网络检查、JavaScript 经验库和确认后的写请求重放，并使用专用 Profile。这个开关只在本次应用启动期间有效，Agent 工具不会接收或返回 Cookie 值。

使用 Herdr Agent 舰队

打开设置→Herdr

Pi Agent Desktop 通过 Herdr v0.8.2 / protocol 20 管理本机 Agent 舰队。Pi 可以在原主对话中使用 herdr_* 工具；标题栏显示 Fleet 状态，右侧 Herdr 终端用于观察、排查和显式接管。

准备 Herdr 运行时

1. 在 macOS、Linux 或 Windows x64 打开“设置 → 开发工具”，找到 Herdr。应用已经内置经过完整性校验的 v0.8.2，可直接安装、更新、修复或卸载私有运行时，无需另行联网下载。
2. 打开“设置 → Herdr”并启用集成，然后选择 Attach 或 Managed 模式、填写 Herdr Session 名称并按需开启自动连接。
3. Attach 连接由你手动启动的系统 Herdr，Pi Desktop 不会停止它；Managed 会自动启动、监控、有限重启并管理 Pi Desktop 的私有 server。
4. Managed 在禁用 Herdr、切换模式、卸载运行时或退出应用时关闭私有 server；它不会接管或终止外部 Herdr。

从主对话管理 Agent

• 24 个 herdr_* 工具覆盖 Fleet 查询、workspace / tab / pane 创建与管理、Agent 启动与提示、等待、按键、状态解释、进程诊断和输出等待。
• 标题栏右侧按 workspace、tab、pane 和 Agent 层级展示空闲、运行中、已阻塞、已完成或未知状态；初始页和激活会话使用同一列表。
• 可启动 pi、 claude、 codex、 gemini、 omp、 opencode、 copilot、 kimi、 droid、 grok、 qwen和 agy.
• Managed 模式会在固定 allowlist 目录中发现常见 Agent CLI，并只把允许的 Agent command 加入 launcher overlay；不会运行登录 shell、读取 shell profile、联网安装或递归扫描用户目录。
• missing-locally 仅表示 Desktop 未在受支持的本地目录中找到该 CLI。在 Attach 模式下，外部 Herdr Session 返回的启动结果仍是准确信息。
• Pi Session 与 Herdr Session 相互独立；Herdr prompt 不会写入 Pi 会话记录或 compaction 摘要。

观察与接管终端

• 右侧 Herdr 终端支持 ANSI 输出、自动适配尺寸、只读观察、显式键盘接管、输入限流、断线恢复和有界缓冲。
• 关闭终端视图不会关闭 Herdr pane 或 Agent；可以选择在关闭视图时释放终端控制权。
• 关闭 workspace、pane 或 Agent 必须经过本机确认。Herdr v0.8.2 无法只停止 Agent，因此“关闭 Agent”会明确关闭它所在的 pane 及其中进程。
• Windows x64 的终端子进程由原生 Job Object 约束，应用或终端异常退出时会执行有界清理。

运行受管后台进程

开启设置→通用→受管后台进程

受管后台进程让 Agent 在应用管理的生命周期内持续运行开发服务器、watcher、mock API 和其他项目任务，不需要使用 shell &、 nohup或外部终端。短命令使用会话所选的 Shell：Bash，或 Windows 上的 PowerShell。

开始与查看进程

1. 选择受信任的项目目录，在“设置 → 通用”中开启“启用受管后台进程”。此功能默认关闭。
2. 让 Agent 启动开发服务器、watch build 或其他长期任务；Agent 会使用 process_* 工具管理它们。
3. 打开主界面右侧“进程”面板，查看 owner、状态、readiness、脱敏日志、loopback endpoint 与退出原因。
4. 对可用 endpoint 点击“在浏览器中打开”，即可与内置 Browser 联调；进程能力与 Browser 授权彼此独立。

控制进程与日志

• 可以发送一行 stdin、停止、强制停止、重启进程，并搜索、复制或导出日志。
• 慢启动任务使用日志 cursor 继续观察，不会重复读取全部输出；日志使用有界缓冲并自动脱敏常见敏感信息。
• 每个进程只属于启动它的 Agent 会话，其他会话不可见；重启会生成新的 run ID，过期操作会被拒绝。
• 用户停止的进程不会被 Agent 自动重新启动；Host 或应用异常退出时，crash reaper 会有界清理进程树。

Windows PowerShell 支持

在 Windows 上使用 PowerShell 5.1 或 7 执行 Agent 命令。可选择新会话的默认 Shell，已有会话保留原有选择。

1. 在 Windows 上，打开「设置 → 通用 → Agent 默认 Shell」，选择 PowerShell 或 Bash。新会话默认使用 PowerShell；此设置只影响之后创建的会话。
2. 优先使用可用的 PowerShell 7，也支持 Windows PowerShell 5.1。可在「开发工具」中指定可执行文件；安装或更改路径后，请刷新工具状态。

请拆分过长的 PowerShell 命令。超过 Windows 长度限制的命令会在执行前明确报错，不会被静默截断后执行。

配置模型

打开设置→模型

Pi Agent Desktop v0.4.1 内置 Pi Coding Agent 1.2.0，但不提供模型额度。你需要连接已有的模型服务账号，或填写模型服务商提供的 API Key。模型设置支持英文、简体中文和繁体中文。

使用 API Key

1. 打开“设置 → 模型”，点击“添加服务商”。
2. 选择你的模型服务商。
3. 如需代理或兼容端点，可先填写 Base URL；留空则使用服务商默认地址。
4. 粘贴 API Key，点击“保存”；应用会同步刷新 Agent Host 的模型状态。
5. 选择要使用的模型；如果界面提供“测试”，可以先测试连接。
6. 关闭设置，在会话输入框下方选择刚配置的模型。

Base URL 会覆盖当前 API Key 服务商的请求地址，并与 API Key 一起在点击页面底部“保存”后生效。模型目录刷新受到完整超时保护；即使服务初始化或最终目录整理卡住，也会停止等待并继续保留缓存模型。

管理模型显示范围

1. 打开“设置 → 模型”，选择一个已经连接的订阅账号或 API Key 服务商。
2. 在模型区域查看已启用数量；模型较多时，可以按名称或模型 ID 搜索。
3. 勾选或取消单个模型，也可以点击“全部启用”或“全部禁用”批量调整。
4. 等待选择保存完成，返回会话后即可在模型选择器中看到启用的模型。

选择会持久化到 Pi 设置并兼容已有的思考等级配置，但不会改变当前会话正在使用的模型。应用会阻止保存没有任何有效模型的配置，避免模型选择器不可用。

刷新模型目录

1. 在会话输入框下方打开模型选择器。
2. 点击“刷新模型目录”，从已配置的 Provider 获取最新模型。
3. 等待刷新完成；离线、超时或部分 Provider 失败时，界面会显示对应状态或警告。

会话启动时优先读取本地缓存的模型目录，避免每次启动都发起网络请求。刷新失败不会清空已有模型，缓存目录仍可继续使用。

使用 OAuth 登录

1. 在“添加服务商”中选择支持 OAuth 的服务商。
2. 点击“登录”，按提示在浏览器中完成授权。
3. 回到应用，确认服务商显示为已连接；登录或退出后模型状态会自动同步。

自定义兼容服务

如果你使用的是兼容 OpenAI、Anthropic 或 Google API 的自建服务，可以添加自定义服务商，并填写 Base URL、API 类型、API Key 和模型信息。这部分只在普通服务商列表无法满足需求时使用。

模型配置恢复

1. 打开「设置 → 模型」并修正提示的字段。其余无法在界面中编辑的字段，请手动修改 ~/.pi/agent/models.json。支持行注释与尾逗号。
2. 重新加载磁盘上的配置，再重新加载会话后发送消息。恢复后检查已选模型及 Auto 路由。

OpenRouter 根据当前账号权限刷新模型目录。Desktop 与 Pi CLI 共享 ~/.pi/agent/ 下的缓存；切换账号或离线启动后，请联网刷新，替换过期或来自其他账号的目录。

Auto 自动路由

配置快模型和强模型，Auto 按思考级别或任务复杂度为每次新提问选择模型，并显示实际作答的模型。

1. 打开「设置 → 模型 → 自动路由」，启用 Auto，选择快模型、强模型及各自的思考级别。保存后，在输入框下方选择 Auto。
2. 可按思考级别路由，或添加决策模型判断任务复杂度。决策请求会增加耗时和用量；判断失败时，Auto 使用强模型。
3. 工具续接沿用已选模型。可在自动重试时尝试另一个已配置模型，并按实际模型查看用量。
4. 路由配置在新建、重新加载会话或重新选择 Auto 后生效。

MCP 服务管理

通过 stdio 或 Streamable HTTP 连接本地与远程工具。在设置中导入配置、通过 OAuth 登录、测试连接并预览资源。

1. 打开「设置 → MCP」，选择「全局」或「当前项目」，然后添加服务或导入 JSON 配置。
2. 配置 stdio 命令或 Streamable HTTP URL，按需使用 OAuth 或服务商凭据引用，再测试连接。
3. 浏览工具、资源和资源模板，在服务详情中预览资源内容或重新连接。
4. 项目配置覆盖同名全局配置，扩展来源与待应用的更改单独显示。
5. 保存 MCP 配置不等于授权工具。请在当前会话的工具菜单中授权；嵌套调用也遵守同样的权限。

图片生成与决策模型

通过 Codemode 生成图片、分类内容、进行是非判断或评分。生成的图片在重新打开会话后仍可查看。

1. 在「设置 → 模型」配置可用的图片或决策模型，然后在会话工具菜单启用 Codemode。「完全访问」预设包含 Codemode 和工具搜索。
2. 让 Agent 生成图片或对内容进行分类。支持图片输入的决策模型也能判断截图。这些模型提供辅助能力，不在聊天主模型菜单中选择。
3. OpenAI 决策接口需要 API Key，ChatGPT 订阅登录不提供此能力。通过 API Key 添加 TypeSafe / Jev 服务商，即可使用 jev-latest。
4. 服务商详情页可测试图片和决策模型，测试可能产生费用。调用支持取消，并在会话历史中保留输入、结果、状态和用量。

工具权限与执行历史

按会话分支查看直接与嵌套调用的执行树。检查状态、耗时、输入和完整结果，重开或压缩会话后仍可查阅。

1. 会话工具菜单分别控制模型可见入口、可被嵌套查找的工具与实际执行授权。权限变更会同步到运行时。
2. 大结果与临时输出会持久保存，支持分页读取。重开或压缩会话后，Agent 可通过 tool_history_get 查询原始内容。
3. 中断后保留已完成的子调用，未确认的结果标记为中断或结果未知。恢复时不会自动重放操作。

模型高级配置

• 打开「设置 → 模型 → 模型高级配置」，调整自动上下文压缩、回复预留 Token、最近内容保留量及按模型覆盖的参数。
• 配置 Agent 和服务商的重试次数、等待时间、请求超时，以及自动、SSE、WebSocket 或缓存 WebSocket 传输方式。
• 模型编辑支持按思考级别配置采样参数、设置图片与请求输入限制，以及按模型 ID 覆盖配置。支持的模型可选择 Max 推理级别。
• 高级设置与 Pi CLI 共享。重新加载现有会话后生效；已信任项目的设置可覆盖全局值。保存时会检测外部修改，减少配置冲突。

Skills 设置

打开选择项目→设置→技能

这里只介绍设置方法。Skill 的具体能力和使用方式由它自己的说明决定。

1. 先在左侧选择项目，再打开“设置 → 技能”。
2. 选择已有 Skill，使用右上角开关设置它是否对模型可见。
3. 需要添加时点击“添加技能”，搜索名称，选择“全局”或“当前项目”，再点击“安装”。
4. 只有确实需要自定义说明时才修改内容，并点击“保存更改”。

Plugins 设置

打开选择项目→设置→插件

插件页只需要配置插件来源、安装范围和启用状态。

1. 先选择项目，再打开“设置 → 插件”。
2. 点击“添加插件”，填写 npm 包、Git 仓库或本地绝对路径。
3. 选择“全局”或“当前项目”，然后点击“安装”。
4. 在已安装列表中启用、禁用、更新或移除插件。
5. 设置发生变化后，点击“重新加载会话”使配置生效。

消息渠道设置

打开设置→消息传递渠道

先选择要连接的渠道。飞书 / Lark 推荐使用官方扫码创建，也可以继续连接已有自建应用：

附件与对应回合准确关联。已取消或由扩展接管的消息不再影响后续 Desktop 回合，也不会重复发送上一轮助手回复。

飞书 / Lark 扫码创建机器人

1. 点击“连接飞书 / Lark”，选择“扫码创建（推荐）”。
2. 选择账号区域：飞书（中国）或 Lark。
3. 点击“生成二维码”，使用对应客户端扫码并完成官方授权。
4. 授权完成后，应用会自动创建机器人、配置所需权限、保存凭据、验证身份并启动连接。

连接已有飞书 / Lark 应用

在接入方式中选择“已有应用”，选择飞书或 Lark，再填写 App ID 和 App Secret。扫码流程不会读取已有应用的 App Secret。

完成账号设置

1. 保存账号信息，并按需设置默认工作目录和访问策略。
2. 启动账号，确认状态显示为“运行中”。
3. 使用“测试连接”检查配置；需要与当前会话共享上下文时，再绑定对应消息对话。

开发工具设置

打开设置→开发工具

应用会自动扫描所需工具。普通使用只需要处理显示为“缺少”或“不可用”的项目。

1. 点击“重新扫描”，查看工具状态、来源和版本。
2. 已经安装的工具保持“自动”，检测不正确时点击“选择”指定路径。
3. 缺少工具且应用提供托管版本时，点击“安装”；文件损坏时点击“修复”。

Windows 会结合安装布局与同目录 Git 版本识别 Git Bash，因此自定义 Git for Windows 目录和带版本号的 PortableGit 目录也能被正确发现。

优先使用可用的 PowerShell 7，也支持 Windows PowerShell 5.1。可在「开发工具」中指定可执行文件；安装或更改路径后，请刷新工具状态。

管理 Herdr 运行时

macOS、Linux 与 Windows x64 版都随包提供经过完整性校验的 Herdr v0.8.2。在“开发工具”中可以查看内置版本、已安装版本和私有磁盘占用，并执行安装、更新、修复或卸载；这些操作从应用内置副本恢复，不会另行下载 Herdr。

Herdr 版本随 Pi Desktop 更新。卸载私有运行时不会删除 Herdr Session，也不会移除安装包中的恢复副本。

更新、后台运行与本地数据

检查更新

打开“设置 → 关于”，可以检查稳定版更新。macOS 与 Windows 支持在应用内下载并安装；Linux AppImage 当前需要从下载页面手动获取新版本。

保持消息渠道在线

在“设置 → 通用”开启“关闭窗口时最小化到托盘”。关闭主窗口后消息渠道会继续运行；从托盘菜单选择“退出”才会真正停止应用。

本地数据

Desktop 的工具权限与执行记录保存在应用数据目录。完整备份时，除 ~/.pi/agent/ 外，还需保留其中的 tool-executions 日志和内容文件。

• 会话和 Pi 配置默认保存在本机的 ~/.pi/agent/ 目录中。
• 已经使用 Pi CLI 的用户可以直接复用原有会话和配置。
• 模型请求仍会发送给你所选择的模型服务商，请同时了解该服务商的隐私政策。
• 消息渠道凭证使用操作系统安全存储加密保存，不会在设置页中重新显示。

常见问题