Capacitor 实战教程：给 AI 编程 Agent 装上「黑匣子」，每个会话都可追溯

背景

AI 编程 Agent（Claude Code、Codex、Cursor 等）已经成为许多开发者的日常工具。它们帮你写代码、做重构、修 Bug，工作效率大幅提升。但有一个问题随着使用频率增加而越来越突出：Agent 做了那么多事，可它的会话记录去哪了？

你在 Claude Code 里跑了一个 200 多回合的 Session，修好了三个 Bug，重构了一个模块。第二天想回顾 Agent 当时怎么修的那个问题——找不到了。Agent 的会话记录要么存在本地看不见，要么存在终端缓冲区里被覆盖了。想跟队友分享 Agent 的推理过程？难上加难。

Capacitor 解决的就是这个问题。它是 Kurrent 团队开发的 Agent 会话观测工具，通过一个轻量 CLI 在你的 Agent 和真实编辑器之间架起桥梁，自动记录每个 Session 的完整生命周期——从什么时候开始、中间调用了哪些工具、消耗了多少 Token、最后修改了哪些文件，通通保存下来。而且这些记录是可搜索、可分享、可回顾的。

安装与环境

Capacitor 的核心是一个 npm 包，一行命令即可安装：

npm install -g @kurrent/kcap

安装后运行 kcap setup 完成初始化：

kcap setup          # 交互式配置，自动发现你的 Team
kcap setup --server-url  --no-prompt   # 脚本化配置

kcap setup 会自动检测你机器上已安装的 AI 编程 Agent（包括 Claude Code、Codex、Cursor、GitHub Copilot CLI、Gemini CLI、Kiro、Pi、OpenCode），并为你选择的 Agent 安装 Hook。Hook 会在 Agent 启动时自动加载，无需额外配置。

Capacitor 提供 Free 免费计划（5 个席位、自带 API Key，永久免费），对于个人开发者和小团队来说完全够用。

实战场景 1：Agent 会话录制与回放

安装完成后，Capacitor 会在后台静默运行。每次你启动 Claude Code 或 Codex，它都会自动创建一条会话记录。

想看刚才 Agent 做了什么？用 kcap recap 命令：

kcap recap            # AI 生成的摘要：做了什么、关键决定、遗留问题
kcap recap --full     # 完整对话记录
kcap recap --per-turn  # 按回合列出：每个 Prompt、调用的工具、耗时
kcap recap --get-turn 3  # 只看第 3 回合的详细信息

--per-turn 模式特别有用。它会输出一个紧凑的回合索引：

Turn 1  | Prompt: 重构用户模块                   | tools: 5 | files: 3 | tokens: 12.4k | 45s
Turn 2  | Prompt: 添加单元测试                    | tools: 8 | files: 2 | tokens: 8.1k  | 62s
Turn 3  | Prompt: 修复 CI 报错                   | tools: 3 | files: 1 | tokens: 3.5k  | 18s

然后你可以用 --get-turn 展开感兴趣的回合，看 Agent 当时怎么想的、调了哪些工具、最终改了什么文件。

实战场景 2：不同 Agent 之间的会话交接

团队协作中常遇到这种情况：你（A 成员）用 Codex 分析了某个模块的 Bug，因为临时被别的事打断，需要交给同事（B 成员）继续处理。传统做法是口头或 Slack 上描述一下现场进度——Agent 的中间状态全部丢失。

Capacitor 通过会话共享和 --chain 链式回顾解决了这个问题：

kcap recap --chain       # 查看连续会话的完整上下文
kcap recap --chain --full  # 链式完整对话记录

甚至可以在不同 Agent 之间交接。比如 Claude Code 读到一半的思路，可以交给 Codex 继续：

kcap recap --full claude-session-abc123

Capacitor 的 Dashboard 还支持多 Operator 模式——两个开发者在浏览器中同时驱动同一个 Agent，谁打了什么字都记录在时间线上。

实战场景 3：PR Review 附上 Agent 的推理过程

Pull Request Review 是团队协作中必不可少的一环。传统 Review 只能看到代码 diff——最终改了什么，但看不到背后的推理过程：Agent 为什么这么改？尝试过哪些方案？踩过什么坑？

Capacitor 将 Agent 的会话记录与 GitHub PR 关联起来，Reviewer 可以在 Code Review 时同时看到 Agent 的调试过程：

kcap review    # 关联 PR 与 Agent 会话记录

kcap recap  --chain

当 Review Agent 检查 PR 时，它不仅能读 diff，还能读到「提交者之前尝试过什么、为什么放弃了方案 A 选了方案 B」。这让 Code Review 从「二维的文本比对」升级成了「三维的推理过程审查」。

Dashboard 上集成的 PR Review 模块会显示：

• 会话摘要：Agent 在本次会话中改了什么、解决了什么问题
• 关键决策：Agent 在哪个回合做了什么选择
• 失败尝试：Agent 尝试过哪些方案但放弃了

最佳实践

1. 定期回顾 Agent 历史：每周用 kcap recap 回顾一周的 Agent 活动，了解工具使用模式和 Token 消耗分布
2. 团队规范：关键的代码改动，在 PR 中附上对应的 Session Recap 链接，让 Review 更有上下文
3. 搜索历史会话：遇到类似问题时，用 Dashboard 搜索「有没有处理过这个模块」，避免重复造轮子
4. 善用 –per-turn 索引：长 Session（100+ 回合）先看索引，再展开关键回合，而不是直接看完整对话
5. 重视 Token 消耗：关注每回合的 Token 统计，发现异常的消耗峰值（如某个工具反复出错导致大量重试）

总结

Capacitor 解决了一个看似简单但实际很关键的问题：AI 编程 Agent 的不可追溯性。它的做法也不复杂——在 Agent 背后加一个「黑匣子」记录仪。对于一个团队来说，这种可追溯性意味着 Agent 的工作不再是黑箱操作，而是可以检视、可以回顾、可以交接的工程资产。

Capacitor 支持 Claude Code、Codex、Cursor、Copilot、Gemini CLI、Kiro、Pi、OpenCode 等主流 AI 编程 Agent，只要有 npm 环境就能用。

• 项目官网：https://capacitor.kurrent.io
• CLI 仓库：https://github.com/kurrent-io/kcap-cli
• 定价：提供 Free 免费计划（5 席位），Team 计划 $15/用户/月