Pisper

使用教程

从安装到进阶：配置模型、并行推进多个 Agent、用分支比较不同方案，并在终端和手机上接着同一段工作。

安装 Pisper

桌面安装包自带 TUI 与 Runtime，无需预装 Node.js。

Windows

优先选择普通 -setup.exe；已有 WebView2 可离线安装，缺失时联网补齐。离线电脑缺少 WebView2 或无法确认时，选择包含该依赖的 -offline-setup.exe。两种包都不包含按需下载的语音模型。

macOS

按 Apple Silicon / Intel 选择 .dmg，拖入「应用程序」。使用系统 WKWebView，无需额外内核包。尚未公证，首次打开见下方常见问题。

Linux

可选 .AppImage 或 .deb；AppImage 需先加可执行权限，可能需要 FUSE。离线部署需预先准备发行版所需系统库，DEB 可能依赖 WebKitGTK 等包。

用 npm 安装

已有 Node.js 20+ 时，也可以用 npm 安装命令行版本：

npm i -g pisper
pisper        # 启动终端 TUI
pisper web    # 打开 Web 前端与配置页

提示：npm 包只是安装器，会下载并校验签名后的 TUI 与 Runtime 组件，不包含桌面界面。

配置模型 Provider

Pisper 不内置模型，需要你自己的 Provider 和 API Key。请求由你选定的 Runtime 直连 Provider。

  1. 打开模型设置

    桌面端进入 设置 → 模型；终端中执行 /provider。

  2. 选择协议并填写凭据

    选择 Provider 协议，按需覆盖 Base URL，填入 API Key。Key 在界面中始终以掩码显示。

  3. 拉取并选择模型

    保存后刷新模型列表，为当前会话选定模型。保存与切换是解耦的，改配置不会打断正在运行的会话。

本地配置导入：模型设置页检测到可导入的 Codex 或 Claude 配置时，会显示一行提示。点击“查看”展开连接管理，再选择导入；应用启动时不再弹出导入提醒。

会话级模型：每个会话可以用不同模型。适合让便宜模型跑批量改动、贵模型做关键决策。

第一个会话

  1. 选择工作目录

    新建会话时指定项目目录。会话的文件读写与命令执行都以它为基准。

  2. 让 Agent 认识项目

    执行 /init，Pisper 会分析项目并生成或补全根目录的 AGENTS.md。已有的有效说明会被保留。

  3. 描述目标，而不是步骤

    直接说想达成什么。思考过程、工具调用和执行结果会分层展开，可随时折叠。

语音输入 对话模式

并行会话与分屏

每个会话独享模型、上下文、工作目录与权限，互不干扰。

  • 分屏：拖动会话标签到窗口任意一侧，可上下左右四面分屏。
  • 同屏对比：让多个 Agent 用不同思路解决同一问题，进度同屏可见。
  • 跨会话直达：Ctrl + K 搜索并跳到目标会话或 Turn，自动载入历史并滚动到现场。

关于并行数量：并行会话都会真实消耗 Provider 配额，请按额度和速率限制安排。

追忆分支与 Turn 标签

长对话会被压成主干与分叉视图。你可以在任意已完成的 Turn 上开新分支，源会话一字不改。

什么时候开分支

  • 想比较两种实现方案，又不想丢掉已经聊出来的上下文。
  • Agent 走偏了，希望回到岔路口重新给方向。
  • 需要保留一条“能用的版本”，同时继续激进尝试。

Turn 标签

给关键 Turn 钉上标签，作为可检索的锚点。标签绑定持久化边界，不依赖会过期的消息 ID，长会话里依然稳定。

工具、插件与 MCP

核心工具常驻上下文；扩展能力按需激活、用完即退，避免把上下文塞满。

类型 用途 激活方式
核心工具 读写文件、执行命令、检索代码 常驻，直接可用
本地插件 项目专属的自定义能力 描述需求后由 Pisper 生成、校验并安装
MCP 服务 结构化接入外部系统与真实数据 在 MCP 设置中配置服务端
技能 可复用的成套操作流程 按需加载，可自动触发

缺能力时直接说

不必先去找插件。描述你需要什么，Pisper 会编写、校验并安装本地插件，下一轮对话即可调用。

让其他 Agent 调用 Pisper

Pisper 可以连接外部 MCP 服务，也可以作为内置 MCP 服务供同一台电脑上的其他 Agent 调用。 服务默认关闭，在 Pisper 的 MCP 页面开启后，复制地址与令牌到支持 Streamable HTTP 和自定义 Authorization 请求头的客户端。

内置服务只监听本机回环地址。持有令牌的客户端可以读取会话与记忆、发送消息并调用已开放的工作流等能力； 会话内的工具继续遵守已有审批规则。请保管好令牌，需要时可在 Pisper 中轮换。 查看完整连接步骤与工具清单 →

执行模式与审批模式

两个正交的开关，都在输入区工具栏上，随时可切换： 执行模式决定 Agent 怎么干活，审批模式决定它能触碰什么。

执行模式：Plan / Goal / Team

模式 工作方式 适用场景
Plan 按计划推进当前消息，完成本轮后等待下一条指令 日常对话与开发任务（默认）
Goal 由单个 Agent 围绕目标持续自主推进，直到完成或暂停，可设 Token 预算 长任务、需要自驱动的目标
Team 由主 Agent 动态组织多个 subagent 分工协同，可设团队 Token 预算 需要并行拆解的大块工作（需 Runtime 具备多 Agent 能力）

审批模式：决定权限边界

模式 可执行范围 适用场景
审批后写入 approval-required 修改工作区文件前展示 Diff 并等待批准；Shell 命令也需要逐条批准 代码审查、方案调研、需要确认的开发工作
自动审批 workspace-write 允许修改当前工作区并自动批准常规命令；外部访问仍受限制 日常开发、重构、跑测试与构建
完全访问 full-access 允许访问本机文件和网络；Shell 不再逐次请求授权 需要完整主机权限的操作

终端里用 /mode 查看与切换审批模式，如 /mode approval-required、/mode workspace-write、/mode full-access。

可视化工作流

把 Prompt、文件、MCP 与通知连成一张图，让重复的事交给流程跑。

  1. 新建工作流

    进入工作流页面，从空白图开始，或基于已有工作流复制。

  2. 连接节点

    拖拽添加 Prompt、文件输入、MCP 调用与通知节点，用连线定义执行顺序与数据流向。

  3. 试跑并观察

    手动运行一次，确认每个节点的输入输出符合预期后再接入定时任务。

定时任务与通知

定好频率与时区，到点 Agent 自己开工，结果推到你手边。

  • 触发目标：可以是一段 Prompt，也可以是已经调好的工作流。
  • 通知渠道：系统通知之外，可接飞书与个人微信，实现双向对话。
  • 离开电脑也能跟进：渠道消息可直接回复，会话继续推进。

星忆项目记忆

事实、偏好与决策会被记住并可检索，项目再长也不用重复自我介绍。

先审后用：记忆条目在写入前需要你确认，避免把错误结论固化下来。

终端 TUI

桌面装好后 pisper 命令即可用，与桌面端共用同一套 Runtime 和会话数据。

pisper            # 在当前目录启动
pisper web        # 打开 Web 前端配置页

常用 Slash 命令

命令 作用
/init 分析项目并生成或完善 AGENTS.md
/sessions 打开跨目录的历史会话选择器
/model 切换当前会话模型
/changes 查看 Git 或 SVN 改动，可提交与推送
/compact 立即摘要较早上下文
/mode 查看或切换执行模式

也可以直接请求工具，例如 /read README.md、/bash npm test，或调用技能 /skill:<name>。完整命令见 TUI 命令参考。

移动端 App

App 内置与桌面同源的 Node/Pisper Runtime，首次启动直接进入本机运行，不必先连电脑。

平台 安装说明
Android 已签名 arm64 APK，可直接安装；首次侧载按系统提示允许未知来源。
iOS 未签名 IPA，需用 AltStore、Sideloadly 或自有开发者账号重签。

本机运行

  1. 等待 Runtime 就绪

    首次启动会初始化内置 Runtime，随后直接进入正常 Pisper 界面。

  2. 配置 Provider

    会话、Provider 配置与工作区只保存在 App 私有目录。

  3. 了解能力边界

    本机 Runtime 仅监听随机回环端口，并会隐藏 embedded Node 无法承载的能力入口。

远程访问与配对

手机也可以连接桌面 Runtime，用电脑的算力和完整能力。配对必须由桌面端明确批准。

  1. 桌面端开启远程访问

    进入 设置 → 远程访问 开启。建议首次配对时手机与电脑在同一局域网。

  2. 手机发起申请

    在 设置 → 服务器 → 添加服务器 中允许本地网络访问，选择自动发现的桌面并发起申请。

  3. 桌面批准

    桌面用户明确批准后才会签发设备令牌。发现不到或异地时，改用桌面生成的一次性二维码。

链路安全：所有路径都校验 TLS 指纹并使用设备 Bearer 令牌；连接后优先走 LAN，不可达时回退 Iroh P2P。

数据与目录

Runtime 默认只监听 127.0.0.1，敏感格式会自动脱敏。

项目 位置
桌面 / 终端数据 ~/.pisper/agent，可用 PISPER_AGENT_DIR 覆盖
移动端数据 App 私有目录，随应用卸载一并清除

备份注意：该目录含 Provider 凭据与会话内容，请勿提交到仓库或公开分享。

组件更新

Desktop、TUI 与 Runtime 各自独立检查与更新，需要什么就只更新什么。

在 设置 → 更新 中查看各组件版本并单独触发更新；涉及 Runtime 替换的更新会提示重启。

常见问题

macOS 提示「无法打开」

Pisper 尚未经过 Apple 公证。确认安装包来自官方 Releases 后，在 系统设置 → 隐私与安全性 选择 仍要打开。若没有该选项： 

sudo xattr -rd com.apple.quarantine /Applications/Pisper.app

请仅对从官方 Releases 下载并放入 /Applications 的应用使用此命令。

Linux AppImage 无法启动

chmod +x Pisper_*_linux_x86_64.AppImage
./Pisper_*_linux_x86_64.AppImage

缺少 FUSE 时安装 libfuse2 或 libfuse2t64，也可改用 .deb。

模型请求失败

确认 Provider 可达、凭据有效、所选模型对你的账号可用。Provider 流量由你选定的 Runtime 直连，不经过第三方中转。

手机发现不到桌面

确认两端同一局域网、桌面已开启远程访问、手机已允许本地网络权限。仍失败就用二维码配对，截图也可发到异地手机。

还有其他问题

在 Issue 区 反馈，附上版本号、系统版本与完整报错。请勿粘贴 API Key、配对令牌或私有内容。