Pi Agent Desktop 使用指南

下载安装

打开下载页面，网站会优先推荐当前系统对应的安装包。v0.2.0 桌面安装包已经内置 Pi Coding Agent 0.84.0；macOS 与 Linux 还内置 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 个字符的简短标题，并实时更新侧边栏。标题生成不会进入会话历史或阻塞正常回复；模型不可用时会使用消息开头作为本地兜底。

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

调整聊天字号与对话宽度

入口设置→通用→会话

• 聊天字号提供小、标准、大、特大四档，修改会立即应用，并在重启后保留。
• 舒适宽度保持 760px；扩展宽度会随窗口自适应，最大为 960px。
• 消息、过程详情和输入框使用统一内容边界，在宽屏和最小窗口下也能保持对齐。

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

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

使用内置浏览器

入口主界面右侧→浏览器

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

管理浏览器权限

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

高级浏览器模式

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

使用 Herdr Agent 舰队

入口设置→Herdr

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

准备 Herdr 运行时

1. 在 macOS 或 Linux 打开“设置 → 开发工具”，找到 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；启动前会检查相应 CLI。
• Pi Session 与 Herdr Session 相互独立；Herdr prompt 不会写入 Pi 会话记录或 compaction 摘要。

观察与接管终端

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

运行受管后台进程

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

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

开始与查看进程

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 会有界清理进程树。

配置模型

入口设置→模型

Pi Agent Desktop v0.2.0 内置 Pi Coding Agent 0.84.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 和模型信息。这部分只在普通服务商列表无法满足需求时使用。

Skills 设置

入口选择项目→设置→技能

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

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

Plugins 设置

入口选择项目→设置→插件

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

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

消息渠道设置

入口设置→消息渠道

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

飞书 / Lark 扫码创建机器人

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

连接已有飞书 / Lark 应用

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

完成账号设置

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

开发工具设置

入口设置→开发工具

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

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

管理 Herdr 运行时

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

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

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

检查更新

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

保持消息渠道在线

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

本地数据

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

常见问题