跳转到内容

日常使用与会话

快速上手解决“第一次跑通”,这一页解决“每天怎么用”。重点不是背完快捷键,而是知道任务进行中如何反馈,以及何时保留、分支或压缩会话。

需要马上找到操作时,直接看按日常场景速查。例如模型列表太长,只保留常用模型,以及切换模型、保存默认值和调整思考级别。

先看懂终端界面

┌──────────────────────────────────────────┐
│ 启动信息:快捷键、已加载的项目资源 │
├──────────────────────────────────────────┤
│ 消息区:用户、助手、工具、通知与错误 │
├──────────────────────────────────────────┤
│ 编辑器:输入任务、@ 文件、斜杠命令 │
├──────────────────────────────────────────┤
│ 页脚:目录、会话、模型、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
Entersteering当前助手回合的工具调用结束后,尽快插入
Alt+Enterfollow-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 知道链接的人仍可访问。分享或导出前检查提示词、代码片段、工具输出、系统提示和凭据。

这些文件是纯 JSONL,可用自己的脚本统计或分析;结构见会话文件解剖,读取算法见高效读取会话数据。

下一步:从六个工程工作流复制一个真实任务;重复流程再用配置与扩展固化,遇到异常则按故障排查缩小问题。