桌面端入门
语言：中文 | English
pagent Desktop 是一个能在电脑上直接聊天、让 AI 帮你干活的桌面应用。你用大白话下达任务，它能读写文件、跑命令、生成网页或 PDF，结果就摆在窗口右侧。
这份文档面向第一次使用的普通用户，从下载到发出第一条消息，一步一步带你走通。想改桌面端源码，请看 开发者 README。
Desktop 实景
五分钟上手路线
我需要准备什么
- 一台 Mac（Apple 芯片，M1 及以后）。Windows / Linux 见 其它系统。
- 一个大模型服务的 API Key（比如 DeepSeek 的
sk-...）。没有的话，向导里也会教你去哪拿。 - 大约 10 分钟。
不需要懂编程，也不需要提前装 Docker。
第 1 步：安装后端命令（必做）
桌面应用本身只是个"外壳"，真正干活的是一个叫 pagent 的命令行程序。先把它装到电脑上。
打开「终端」（在「启动台」搜索"终端"），粘贴执行：
uv tool install pagent没有 uv？ uv 是一个管理 Python 环境的小工具。先按 安装指南 装好 uv，再回来执行上面这行。
装完后，在终端输入 pagent --help 能看到帮助信息，就说明成功了。
这一步不能跳过
桌面应用启动时会去找 pagent 命令。如果没装，应用会提示"无法启动后端"。
第 2 步：下载桌面应用
去 pagent 的 GitHub Releases 页面，下载最新版里的：
- macOS（Apple 芯片） — 名字类似
pagent-Desktop-<版本号>-mac-arm64.zip
下载后双击解压，把里面的 pagent Desktop 拖进「应用程序」文件夹。
macOS 提示「已损坏，无法打开」？别慌
这不是应用坏了。因为这个应用没有花钱买 Apple 的签名证书，macOS 对所有"来路不明"的应用都会这样拦一下。解决办法很简单：
打开「终端」，粘贴执行（路径按你的实际安装位置改）：
xattr -cr "/Applications/pagent Desktop.app"然后再双击打开，就正常了。解压出来的文件夹里还有一份 打开说明.txt，内容和这里一样。
为什么会这样？想深入了解
xattr -cr 的作用是移除 macOS 给下载文件打的"隔离标记"。这是未签名应用的通病，很多开源软件都需要这一步，属于正常现象，不影响使用。右键 →「打开」有时也行，但对"已损坏"这种提示经常无效，优先用上面的命令。
Windows / Linux 怎么办？
目前主要发布 macOS 版。Windows / Linux 的安装包正在通过 CI 陆续提供；在那之前，你可以：
- 用 VS Code 插件（跨平台，功能相同）
- 或直接用终端命令
pagent
第 3 步：跟着首次设置走
第一次打开应用时，如果还没装好 pagent 或没配 API Key，会自动弹出 首次设置 向导。它分三步，配完才能进主界面——跟着走就行。
顶部会显示 完成下列步骤后即可开始使用。
第 1 步「环境」
这一步检查电脑上有没有装好 uv 和 pagent CLI：
- 都显示 已安装 → 看到 环境已就绪，可以继续。，点 下一步。
- 有 需要安装 的 → 点 安装 pagent（应用帮你自动装），或点 复制命令 自己去终端跑，装完点 重新检测。
第 2 步「API Key」
填入你的大模型 API Key（形如 sk-...），选好 模型。Base URL（可选） 留空即用默认。
- 如果应用已检测到 Key，会提示 已检测到 API Key，可直接下一步，想换再填。
- Key 会被写入本地配置文件
~/.pagent/pagent.toml。
第 3 步「沙箱」
"沙箱"就是 AI 干活的地方。选 本机（推荐 · 无需 Docker）就好，之后在「新建任务」里随时能改。点 完成 进入主界面。
| 选项 | 说明 | 适合谁 |
|---|---|---|
| 本机 | 本机上的独立 workspace，无需 Docker | 绝大多数人（默认） |
| 直接编辑 | 原地改所选项目目录 | 像 coding CLI 一样改 git 仓库 |
| 容器 | 命令在 Docker/Podman 里跑，文件仍在 thread workspace | 需要 Linux 镜像 |
| 远程 | SSH 到另一台机器 | GPU / 超算 / 远端工具链 |
这四种是并列后端，不是 inplace 的四种写法。对照见 怎么选沙箱后端。
想稍后再配？
向导底部有 稍后配置 可以跳过部分步骤。但发消息前必须有 API Key，否则发送后会报错。
配好后，随时能从**左下角用户菜单 →「首次设置」**再打开这个向导。
第 4 步：新建任务，发第一条消息
进入主界面后，点左侧的 新建任务。
填三样：
| 字段 | 怎么选 |
|---|---|
| 沙箱类型 | 本机使用独立 workspace；直接编辑会原地修改所选项目 |
| 镜像 | 只有选"容器"时才出现，填本机 pagent 镜像（如 pagent:latest） |
| 项目目录 | 点 浏览，选择这次任务使用的项目 |
点 创建会话，然后在底部输入框打字，按 Enter 发送（Shift+Enter 换行）。
直接编辑的效果类似在项目目录中启动代码 Agent，文件修改会立即生效。建议先用 Git 保存当前状态。此模式下通过 项目 面板浏览文件，单独的 沙箱 Tab 会隐藏。
试试对它说：
帮我在这个目录建一个 index.html，做一个简单的个人主页
发送后你会看到 AI 一步步执行，生成的网页会出现在窗口右侧。
认识主界面
窗口分三栏：
- 左侧 · 会话历史 — 你的每次对话都存在这里，点一条就能接着聊。上方是 新建任务。
- 中间 · 对话 — 消息、AI 的执行步骤、底部输入框都在这。
- 右侧 · 文件与生成物 — 沙箱目录、项目文件、生成的网页/PDF 预览、运行日志。
拖动栏之间的分隔条可以调整宽度。按 ⌘K 或点标题栏的快捷键按钮查看全部快捷键。
底部输入框
输入框提示是 给 pagent 下达任务，输入 @ 引用文件。几个关键按钮：
| 按钮 | 作用 |
|---|---|
| 发送 / 停止 | 发送消息；AI 运行时会变成 停止，点它可中断 |
| 闪电（YOLO） | 打开后 AI 的工具调用自动批准，不再逐个问你——只在信任任务时开 |
| 圆环 | 显示当前对话占用上下文的大致比例 |
| @ | 输入 @ 可以把项目或沙箱里的文件引用进消息 |
关于 YOLO（闪电）
默认情况下，AI 每次要动文件或跑命令都会征求你同意。打开 YOLO 后它会自动批准所有操作，速度快但风险高。只在你清楚任务安全时再开。
右侧：文件与生成物
AI 生成的网页、PDF、图片等，都能在右侧直接预览。文件树能看到沙箱和项目里的所有文件，日志区能看到后端的运行情况——遇到问题时先看这里。
日常操作
删除会话
在左侧会话列表，鼠标移到某条会话上，点 删除会话 图标，会弹出确认框：
弹窗会显示 删除「会话标题」后无法恢复，确认删除吗？，点 删除 确认，点 取消 放弃。删除无法撤销，请确认后再操作。
切换 / 恢复会话
点左侧任意一条历史会话即可切过去接着聊。应用启动时会自动尝试恢复你最近的一条会话。
设置与帮助
| 入口 | 里面有什么 |
|---|---|
| 标题栏 齿轮（设置） | 环境自检（uv / pagent / API Key / 容器的状态灯）+ 磁盘占用 + 查看 pagent.toml |
| 标题栏 书本（文档） | 在浏览器打开本文档站 |
| 用户菜单 扫码看文档 | 手机扫码在手机上看文档 |
| 用户菜单 首次设置 | 重新打开三步设置向导 |
设置面板里的配置是只读的。要改模型或高级选项，用文本编辑器打开 ~/.pagent/pagent.toml 修改。
不想用向导，手动配 Key？
方式一 · 环境变量：
export DEEPSEEK_API_KEY=sk-...方式二 · 配置文件（推荐）： 新建 ~/.pagent/pagent.toml：
[provider.deepseek]
kind = "deepseek"
api_key = "sk-..."
model = "deepseek-v4-flash"
[agent]
provider = "deepseek"更多模型见 模型与 API Key。
我的文件都存在哪
~/.pagent/
├── pagent.toml # 你的 API Key 和模型设置
├── threads/ # 所有会话记录
└── skills/ # 可选的本地技能
<你选的项目目录>/
└── artifacts/ # AI 生成的文件（网页等）保护好你的 Key
pagent.toml 里有你的真实 API Key，不要发给别人，也不要提交到 Git 仓库。
遇到问题
| 现象 | 试试这样 |
|---|---|
| 打开提示「已损坏，无法打开」 | 终端执行 xattr -cr "/Applications/pagent Desktop.app" |
| 提示后端 / Bridge 起不来 | 终端执行 uv tool install pagent，再看右侧日志 |
| 发消息后报错 | 检查 pagent.toml 里的 Key，或设置 DEEPSEEK_API_KEY |
| 设置里写「还没有配置文件」 | 按上文新建 ~/.pagent/pagent.toml |
| 工具一直显示「运行中」 | 点 停止，或重新发一条消息 |
进阶
- 连接远程服务器：桌面端可以不连本地，而是连一台远程的
pagent服务器（多台设备共享会话）。这属于进阶用法，需要配置传输方式，可参考仓库文档。 - VS Code 插件 — 在 VS Code 里用同一个 AI，跨平台。
- 安装指南 — 还没装
uv从这里开始。