教程 2：日常工作流

预计用时：20 分钟 | 目标：掌握 PI 在日常开发中的核心使用模式

1. 会话（Sessions）：PI 的记忆系统

PI 的所有对话以 JSONL 文件 的形式保存在 ~/.pi/agent/sessions/ 中，按工作目录组织。

会话的树形结构

PI 的会话不是线性对话，而是一棵树：

开始
  │
  ├─ 分支 A：实现功能 X（按 Enter 继续）
  │     │
  │     ├─ 子分支 A1：修复 bug
  │     └─ 子分支 A2：优化性能
  │
  └─ 分支 B：换个方案试试（用 /fork 创建）

这意味着你可以随时回到之前的某个节点，从那里继续探索。

常用会话操作

bash

# 启动时
pi                           # 新会话
pi -c                        # 继续最近的会话
pi -r                        # 浏览并选择历史会话
pi --session <路径或ID>       # 打开指定会话
pi --fork <路径或ID>          # 从指定会话分叉
pi --no-session              # 临时模式（不保存）

# 运行时
/new                         # 开始新会话
/resume                      # 恢复到之前的会话
/session                     # 查看当前会话信息（ID、Token、花费）
/tree                        # 浏览会话树
/fork                        # 从之前的消息创建新会话文件
/clone                       # 复制当前分支到新会话文件

使用 /tree 导航

按 /tree 或连续按两次 Escape：

搜索：直接输入关键字
折叠/展开分支：Ctrl+← / Ctrl+→
翻页：← / →
过滤模式（Ctrl+O 切换）：
- 默认 → 无工具 → 仅用户消息 → 仅标记 → 全部
打标签：Shift+L 标记书签，Shift+T 切换时间戳

2. 上下文压缩（Compaction）

当对话过长、接近模型的上下文窗口限制时，PI 会自动压缩。

自动压缩

默认开启
当上下文即将溢出时触发
保留最近的消息，压缩较旧的消息为摘要

手动压缩

/compact                              # 使用默认指令压缩
/compact 重点关注数据库相关的改动        # 自定义压缩指令

注意事项

⚠️ 压缩是有损的。完整的对话历史仍然保存在 JSONL 文件中，可以用 /tree 回溯。

压缩设置

在 settings.json 中调整：

json

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,    // 为 LLM 响应保留的 token
    "keepRecentTokens": 20000  // 不压缩的近期 token
  }
}

3. 模型管理

切换模型

/model          # 打开模型选择器
Ctrl+L          # 快捷键打开模型选择器
Ctrl+P          # 在限定模型间向前循环
Shift+Ctrl+P    # 在限定模型间向后循环

限定循环模型

在设置中配置 Ctrl+P 可循环的模型：

json

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

思考级别

用 Shift+Tab 切换思考级别：

级别	用途
`off`	不思考，直接回答
`minimal`	最少思考
`low`	低度思考
`medium`	中度思考（推荐日常使用）
`high`	高度思考（复杂问题）
`xhigh`	极高思考（极复杂问题）

编辑器边框颜色会反映当前思考级别。

CLI 指定模型

bash

pi --provider anthropic --model claude-sonnet-4-20250514 "帮我重构"
pi --model openai/gpt-4o "帮我重构"       # 带 provider 前缀
pi --model sonnet:high "解决复杂问题"     # 带思考级别

4. 文件操作

引用文件

在编辑器中输入 @ 模糊搜索项目文件：

@src/auth.ts 审查这个文件的权限逻辑

也可以启动时引用：

bash

pi @src/main.ts @src/auth.ts "审查这两个文件"
pi @screenshot.png "这个截图里有什么问题？"

PI 如何编辑文件

write：创建新文件或完全覆盖
edit：精确替换文件中的某段文本（推荐用于修改现有代码）

模型会自动选择合适的工具。你只需要告诉它你想做什么。

5. 分支与分叉工作流

场景 1：尝试不同的实现方案

1. 正常对话，PI 实现了方案 A
2. 用 /tree 回到分叉点
3. 选择不同分支或继续从那里开始
4. 告诉 PI：「试试方案 B」

场景 2：创建独立的新会话

/fork     # 从之前的某条用户消息创建新会话文件
          # 之前的对话会被放入编辑器，你可以修改后重新开始

场景 3：复制当前进度

/clone    # 把当前分支复制到新会话文件
          # 保留所有历史，编辑器为空

6. 会话导出与分享

/export [file]    # 导出为 HTML 文件
/share            # 上传为私有 GitHub Gist，生成可分享的 HTML 链接
/copy             # 复制最后一条助手消息到剪贴板

7. 实用技巧

管道输入

bash

cat error.log | pi -p "分析这个错误日志"
cat README.md | pi -p "翻译成中文"

只读模式

bash

pi --tools read,grep,find,ls -p "审查代码"

只允许读取和搜索，不写文件也不执行命令。

多行输入

Shift+Enter：换行（Windows Terminal 用 Ctrl+Enter）
Tab：路径补全

在编辑器中临时切换

输入 / 触发命令，或输入 /hotkeys 查看所有快捷键。

本章小结

✅ 理解了会话的树形结构和分支机制
✅ 掌握了 /tree、/fork、/clone 等会话管理操作
✅ 了解了上下文压缩机制
✅ 学会了模型切换和思考级别控制
✅ 掌握了文件引用和编辑方式
✅ 了解了会话导出和分享

下一步 → 教程 3：设置与上下文文件

教程 2：日常工作流 ​

1. 会话（Sessions）：PI 的记忆系统 ​

会话的树形结构 ​

常用会话操作 ​

使用 /tree 导航 ​

2. 上下文压缩（Compaction） ​

自动压缩 ​

手动压缩 ​

注意事项 ​

压缩设置 ​

3. 模型管理 ​

切换模型 ​

限定循环模型 ​

思考级别 ​

CLI 指定模型 ​

4. 文件操作 ​

引用文件 ​

PI 如何编辑文件 ​

5. 分支与分叉工作流 ​

场景 1：尝试不同的实现方案 ​

场景 2：创建独立的新会话 ​

场景 3：复制当前进度 ​

6. 会话导出与分享 ​

7. 实用技巧 ​

管道输入 ​

只读模式 ​

多行输入 ​

在编辑器中临时切换 ​

本章小结 ​

教程 2：日常工作流

1. 会话（Sessions）：PI 的记忆系统

会话的树形结构

常用会话操作

使用 /tree 导航

2. 上下文压缩（Compaction）

自动压缩

手动压缩

注意事项

压缩设置

3. 模型管理

切换模型

限定循环模型

思考级别

CLI 指定模型

4. 文件操作

引用文件

PI 如何编辑文件

5. 分支与分叉工作流

场景 1：尝试不同的实现方案

场景 2：创建独立的新会话

场景 3：复制当前进度

6. 会话导出与分享

7. 实用技巧

管道输入

只读模式

多行输入

在编辑器中临时切换

本章小结