日常使用与会话
快速上手解决“第一次跑通”,这一页解决“每天怎么用”。重点不是背完快捷键,而是知道任务进行中如何反馈,以及何时保留、分支或压缩会话。
需要马上找到操作时,直接看按日常场景速查。例如模型列表太长,只保留常用模型,以及切换模型、保存默认值和调整思考级别。
先看懂终端界面
┌──────────────────────────────────────────┐│ 启动信息:快捷键、已加载的项目资源 │├──────────────────────────────────────────┤│ 消息区:用户、助手、工具、通知与错误 │├──────────────────────────────────────────┤│ 编辑器:输入任务、@ 文件、斜杠命令 │├──────────────────────────────────────────┤│ 页脚:目录、会话、模型、token 与费用 │└──────────────────────────────────────────┘工具输出可以折叠,但不要把“界面收起来了”误当成“工具没有执行”。需要确认系统状态时,仍应检查文件、Git 差异和真实命令结果。
编辑器边框的颜色会提示当前思考档位;默认主题从终端色板生成颜色。用 /thinking 选择,或在主输入框按 Shift+Tab 循环。具体颜色、当前模型和虚拟路由的区别见模型、思考与主题。
页脚状态行怎么看
输入框下方的 bar 在 Pi 中叫 footer,用途对应 Claude Code 的 statusline。默认第一行显示目录、Git 分支和可选会话名,第二行显示用量、费用、上下文占用,右侧是模型与思考档位。
完整的截图释义、与 Claude Code 的配置差异,以及 setStatus() / setFooter() 示例,见状态栏与 statusline。
先记住三个容易混淆的地方:
↑ / ↓ / R / W和费用是会话累计量;CH是最近一条助手响应的缓存命中率,不是累计平均。- 上下文百分比反映当前窗口占用,不是任务完成进度;压缩后可能暂时显示
?。 (auto)表示自动压缩,不是思考档位。用/thinking确认档位;要让新会话默认max,看保存默认 max。
一句话:累计看整场,CH 看上一句,百分比看当前窗口。
Agent 工作时也可以纠偏
不必等 Pi 完全结束才补充信息。运行中输入消息时,有两种队列:
| 操作 | 队列 | 何时交给 Agent |
|---|---|---|
Enter | steering | 当前助手回合的工具调用结束后,尽快插入 |
Alt+Enter | follow-up | 当前整项工作结束后,再作为下一条请求 |
Escape | 中止 | 停止当前操作,并把尚未投递的队列消息还回编辑器 |
Alt+Up | 取回 | 把排队消息取回编辑器继续修改 |
记法:Enter 尽快插话,Alt+Enter 排到会后,Alt+Up 取回修改,Escape 立即刹车。
简单判断:
- 发现方向错了,用 steering:“停止改配置,只修组件。”
- 想追加下一步,用 follow-up:“完成后再补一条测试。”
- 发现可能造成破坏,直接 中止,先检查当前状态。
不同终端可能占用 Alt+Enter 等按键。遇到冲突时执行 /hotkeys,并参考 Terminal setup。
会话不是一条直线
Pi 默认保存会话。每条记录都有自己的标识和父节点,因此一个会话可以形成树:
初始问题├── 方案 A│ └── 修正 A└── 方案 B └── 继续验证 B ← 当前分支这个心智模型比“一长串聊天消息”更有用:你可以回到旧节点尝试另一种方案,而不是复制整段上下文重新开始。
文件层面的形态(id / parentId 树、压缩点和 context_edit 长什么样)见会话文件解剖。
/tree、/fork、/clone 怎么选
| 目标 | 使用 | 结果 |
|---|---|---|
| 在同一任务里比较不同方案 | /tree | 在同一会话文件中切换节点并形成分支 |
| 从过去某条用户消息开始新任务 | /fork | 创建新的会话文件 |
| 保存当前活动分支,再继续实验 | /clone | 把当前分支复制到新的会话文件 |
| 只是想继续最近的工作 | pi -c | 打开当前目录最近的会话 |
| 想从历史中挑选 | pi -r 或 /resume | 打开会话选择器 |
记法:/tree 在树上爬(同一个会话文件),/fork 叉出新文件,/clone 复印当前分支。 命令行恢复则是 -c 接着干,-r 挑着续;/resume 和 -r 打开的是同一个选择器。
Git 提交和会话分支解决的不是同一件事:
- Git 保存文件状态。
- Pi 会话保存上下文、推理路径和工具记录。
重要修改前,两者都建立检查点最稳妥。
何时压缩上下文
长会话会逐渐逼近模型上下文上限。使用:
/compact/compact 重点保留接口决策、已改文件和未解决问题压缩会把较早内容总结成更短的记录。它是有损操作:细节可能被省略,不能替代 Git、任务说明或正式设计文档。
适合压缩的信号:
- Agent 开始忘记已经确认的约束。
- 同一个事实被反复重新读取。
- 当前任务已经进入明确的新阶段。
如果任务主题已经完全改变,开新会话通常比继续压缩更清楚。
三种日常工作流
下面是最小骨架。需要项目体检、小改动、根因排错、审查、文档和发布准备的完整可复制版本,前往六个工程工作流。
理解陌生项目
先不要修改文件。读取 README、依赖清单和入口,画出模块关系,并列出你仍不确定的三件事。修复小问题
先复现登录页的空状态问题,只修改相关 Vue 组件。完成后运行现有组件测试,并列出未覆盖风险。审查变更
pi @src/components/UserCard.vue @src/api/user.ts \ "只做 code review,关注边界情况、类型安全和错误恢复"任务描述最好包含范围、完成标准、验证方式和禁止动作。需要完整命令时查看命令速查。
会话的保存、导出与分享
会话默认位于:
~/.pi/agent/sessions/常用入口:
/name:给重要会话命名。/session:查看当前会话信息。/export:导出 HTML 或 JSONL。/import:恢复 JSONL 会话。/share:上传并生成链接。默认已认证 Radius 时使用 Radius,否则创建 GitHub secret Gist。
/share 会产生真实的外部网络和云端状态变化。可以用 sessionShareDestination 选择 auto、gist 或 radius;Radius 的访问范围取决于组织,secret Gist 知道链接的人仍可访问。分享或导出前检查提示词、代码片段、工具输出、系统提示和凭据。