01 — 安装与首启
安装与首次启动
Perch 目前是 Windows 10/11 x64 的单文件可执行程序。下载后放到任意位置运行；没有安装器。
- 需要 WebView2 Runtime、ConPTY 和 Job Objects。
- 构建未签名，Windows SmartScreen 可能会让你确认。
- hook 接收器解包到 %LOCALAPPDATA%\Perch\bin；日志在 %APPDATA%\Perch\perch.log。
02 — Workspaces 与项目
Workspaces 与项目
Project 就是一个文件夹。每个新 Agent 都在真实项目里运行，终端就是产品表面。
- 首屏是 Workspaces；左栏顺序为 Workspaces / Overview / Settings。
- 添加项目和新建 Agent 是两步：先选择或创建文件夹，再选择 Agent。
- 旧的合成默认区不再作为新 Agent 的目标；数据仍保留在盘上，留给之后的 Chat。
- 关闭只是停止运行，记录会保留；之后可以按原 paneId 接回。
03 — 首次设置引导
首次设置引导
引导不会在启动时自动出现。只有你尝试新建 Agent、但没有任何已安装且可启动的 Agent 时，它才出现。
- 安装或选择一个 Agent。
- 接入内置网关和一个模型。
- 完成后只关闭引导；不跳页，也不自动启动 Agent。
- 如果已经有可用 Agent，新建 Agent 会直接打开正常的选择器。
04 — 网关与模型
内置网关与模型
Perch 自带本地网关，模型按 pane 应用。网关和供应商配置收在 Perch 自己的目录里，不碰你其他 agent 的配置。
- 网关在本机运行。provider 密钥、路由、用量和插件都在内嵌的网关控制台里。
- 不同格子可以使用不同模型，不需要改全局 agent 配置。
- profile 应用失败时，这次启动会停下并报出可读错误，不会静默回退。
- 网关引擎由 magpie 提供；控制台保留它的归属与措辞。
05 — 文件栏
只读文件栏
右栏提供当前 agent 周围的只读文件视图。
- 碰过的：平铺工作清单，文件名 + 项目相对父目录。
- 全部：当前项目的目录树，从根层打开；展开状态按项目在本次会话内保留。
- 路径显示为项目相对路径；完整路径只用于复制和定位动作。
- 点击文件打开内联预览，不会写盘。
06 — 数据与隐私
数据与隐私
Perch 没有账号系统，也没有自己的遥测。
- %APPDATA%\Perch：设置、座位记录、hook 事件和日志。
- %LOCALAPPDATA%\Perch：网关引擎、provider 密钥和 agent 配置沙盒。
- agent CLI 和 magpie 有各自的网络行为与策略。
07 — 故障排查
故障排查
先看日志，再检查这些常见情况。
- 缺少 WebView2：按提示安装，或运行 winget install Microsoft.EdgeWebView2Runtime。
- SmartScreen 拦截：选择更多信息 → 仍要运行；测试版未签名。
- 找不到 Agent：等安装完成，再回到新建 Agent。
- 网关或模型不可用：打开总览 → 网关，检查连接和供应商。
- 反馈问题时附上 %APPDATA%\Perch\perch.log；日志不含 provider key。