让 AI 学会复盘

你可能遇到过这种情况

你开了一个 3 小时的会话，AI 帮你做了很多事：

• 修了两个 bug
• 重构了一个模块
• 配置了 CI 流水线
• 写了一堆测试

第二天你想回顾一下：“昨天那个登录 bug 具体是怎么修的？“但你只有模糊的记忆——是改了 auth.ts 还是 middleware.ts？是加了空值检查还是改了类型断言？

你翻遍了 git log，commit message 写的是“fix: update auth“——等于没写。

💡 AI 做了很多事，但没有人记录“为什么这样做“。git 只记了改了什么，没记思考过程。

核心工具：pi-session-analyzer

pi-atelier 提供了 Session Analyzer（会话分析器）来搜索和分析历史会话：

💡 关于 pi-journal：pi-journal 可以通过 /journal 命令或 journal 工具生成日报/周报，采集 git 活动、记忆变更、会话活动三路数据。详见 4.2 pi-journal 原理。

实际案例：找到上周的 bug 修复

场景：跨会话搜索

你说：“帮我找一下上次修 DuckDB 时区问题的会话。”

AI 调用 session_search：

🔍 搜索 "DuckDB 时区" — 找到 2 个匹配会话：

1. 05-22 19:36 — DuckDB 时区配置修复
   改了 src/db/connection.ts
   
2. 05-20 14:30 — 数据库初始化讨论
   讨论了时区策略但没改代码

场景：查看会话详情

你说：“看看第一个会话的详细过程。”

AI 调用 session_analyze，生成时间线：

📅 会话时间线（05-22 19:36）

[19:36] 用户：DuckDB 查询返回 UTC 时间，需要改成中国时区
[19:37] AI：读取 db/connection.ts
[19:38] AI：发现连接时没有设置时区参数
[19:39] AI：修改 connection.ts，添加 SET timezone = 'Asia/Shanghai'
[19:40] AI：运行测试，2 个测试失败
[19:41] AI：发现测试用的 mock 没有时区设置
[19:42] AI：修改测试 mock
[19:43] AI：所有测试通过 ✅
[19:44] AI：提交 git commit "fix: set DuckDB timezone to Asia/Shanghai"

场景：按文件追踪

你说：“connection.ts 最近被谁改过？”

AI 调用 session_search 的 file 模式：

📄 src/db/connection.ts 的修改历史：

1. 05-22 19:36 — DuckDB 时区修复（你）
2. 05-20 14:30 — 数据库连接池配置（同事）
3. 05-18 09:15 — 初始创建（你）

Session Analyzer 的 compact 模式

entries 动作支持 compact 参数，精简输出适合快速浏览大会话：

# 标准模式
session_analyze(action="entries")
→ 完整的每条记录（含时间戳、类型、完整内容）

# Compact 模式
session_analyze(action="entries", compact=true)
→ 去掉 type 列、时间只保留 HH:MM、预览 60 字符
→ 适合 100+ 条记录的大会话

Session Analyzer 的分析维度

最有用的模式：takeover

takeover 生成一份“接手报告“，包含 5 个维度：

📋 会话接手报告

1. 用户意图：修复 DuckDB 时区问题
2. 修改文件：connection.ts, connection.test.ts
3. 最近步骤：修改了测试 mock，测试通过
4. 下一步：考虑是否需要在文档中说明时区行为
5. 关键决策：选择在连接层而非 SQL 层处理时区

当你想“接着上次的工作继续“时，这个报告能帮你（或者另一个 AI）快速恢复上下文。

最佳实践

✅ Session Analyzer 的高效用法

• grep 模式：跨所有会话搜索关键词（比翻 git log 快得多）
• file 模式：找到所有动过某个文件的会话（代码审查利器）
• takeover 模式：接手别人的工作时，先生成接手报告
• compact 模式：大会话快速浏览，精简输出
• audit 模式：定期检查 AI 是否有违规操作

❌ 常见误区

• 不要用 session_search 代替记忆——搜索是回溯（过去做了什么），记忆是知识（学到了什么）
• 不要期望找到代码全文——会话记录是摘要，不是完整备份

进阶场景

场景：审查 AI 是否遵守了规范

你给 AI 定了很多规矩（不要直接写 settings.json、不要覆盖大文件），但不确定它是否真的遵守了。用 audit 模式检查：

你：审查一下上次会话有没有违规操作

AI：
  🛠 session_analyze(action="audit", sessionId="...")
  
  ⚠️ 发现 2 个问题：
  1. [违规] 直接 writeFileSync(settings.json) — 应该用 patchSettingsSectionWithBackup
  2. [警告] 大文件 write 覆盖（312 行）— 应拆分或用 edit

audit 模式会检查：是否用了被禁止的操作、是否遵循了文件修改规范、是否有不安全的操作。

场景：了解 AI 的探索过程

AI 用 /tree 开了探索分支——试了方案 A 不行，又试了方案 B 成功了。你想知道方案 A 为什么不行：

你：上次 AI 试了两种方案，帮我看看每个分支的结果

AI：
  🛠 session_analyze(action="branches", sessionId="...")
  
  🌿 分支分析
  
  [主分支] 讨论重构方案
  [B1] 方案 A — 修改函数签名 + 兼容层
    结果：测试失败，兼容层引入了循环依赖
  [B2] 方案 B — 新建接口 + 渐进迁移
    结果：所有测试通过 ✅，已合回主分支

这比翻 git log 更有用——git 只记录最终结果，branches 能看到 AI 的试错过程。

场景：追踪子代理做了什么

会话中用了 subagent 启动了多个子代理。你想知道每个子代理的具体输出：

你：上次会话的子代理都干了什么？

AI：
  🛠 session_analyze(action="chain", sessionId="...")
  
  🔗 子代理链
  
  主代理
    ├──→ pv-explorer
    │     任务：分析 src/auth/ 目录的架构
    │     结果：5 个模块，2 个设计模式，依赖方向正确
    │
    └──→ pv-reviewer
          任务：审查 JWT → session 迁移方案
          结果：发现 1 个数据模型违反，2 个测试缺口

chain 模式追踪主代理和子代理之间的调用关系，清晰展示每个子代理收到了什么任务、返回了什么结果。

下一步

有了复盘能力，AI 和你都能回顾过去的工作。但还有一个问题：会话越长，AI 越容易“变笨“——开始重复自己、忘记前面的约定。

下一章，我们来看如何让 AI 在长会话中保持聪明。