ai-r

ai-r

English | Русский | 中文 | 日本語 | Español

某个 Agent 报告“完成了”。却无从核验。

ai-r 会读取五种编码 Agent 的会话历史，让新的 Agent 冷静核查 git 无法回答的问题：

• 它是否撒了谎、是否弄坏了什么——是否信守承诺、是否运行过危险命令（如果运行过，是否已回滚），它实际改了什么、花了多少成本；
• 它为什么选择那条路——依据什么计划、出于什么意图，以及是谁动手修改的。

在我们自己的数据集中，涵盖 20 多个项目中五种 Agent 的 1600 多个会话，我们就是这样发现了 312 条高风险命令（rm -rf、curl|sh、git push --force）：Agent 自己发现并回滚了其中两条，其他 310 条都悄无声息地执行了——git 不会显示这些操作。

git 显示代码中发生了什么；ai-r 显示 Agent 的做事过程是否值得信任。只读：不调用大模型，不访问网络。

快速示例——Agent 询问历史记录

主要使用模式是 MCP：Agent（Claude、Codex，等等）直接调用 ai-r，用日常语言询问历史记录。例如，找出之前的 Agent 最终确定的计划，以及被舍弃的草稿：

Show me the plan from the last session — final only, no intermediate revisions.
→ plan(session=…, kind="final")  →  get_body(id, shallow=true)

  plan:            "Migrate auth to JWT: 1) extract the check…"
  dropped_drafts:  2   ← two drafts the agent threw away along the way
  session:         a3f… (claude)

快速追溯编辑归属——一条终端命令，同时覆盖所有 Agent：

ai-r find-file-edits auth.py --since 2026-06-01

2026-06-03  codex   auth.py  "add a refresh token"                 edit
2026-06-07  claude  auth.py  "extract the check into middleware"   edit

痛点

• “完成了，我按照计划 Y 做了 X”——却无从核验：Agent 把计划记录成一种形式，把编辑记录成另一种形式。
• 你在任务中途切换了 Agent，结果丢失了上下文。你无处询问“另一个 Agent 已经尝试过什么？”
• 文件中出现了一处编辑——却说不清楚哪个 Agent 做的，以及它是根据什么请求做的。

原因之一：每个 Agent 都用自己的方式记录历史——Claude 和 Codex 使用 JSONL，OpenCode 使用 SQLite，Antigravity 使用“brain”目录，Pi 使用按项目划分的 JSONL。五种格式，五种布局，彼此无法对齐。

承诺

ai-r 将这五种格式整合到一个只读接口中。无论会话由哪个工具记录，你都可以让任何 Agent、脚本或自己查询。每种 Agent 使用一种查询形式；格式差异由解析器在内部统一处理。

即使只用一种 Agent 也能使用：审计自己的 Claude 历史记录（或 Codex 历史记录，等等）。支持五种格式，是为了让你切换工具时历史记录不会断掉——并不要求你必须拥有全部五种格式。

作为 RAG 数据源

在“LLM + 外部数据源”的设置（RAG）中，ai-r 是数据源——更准确地说，是覆盖 Agent 会话的检索层。对于查询，它返回的不是一段日志，而是经过解析的实体：计划、意图、编辑的作者归属，以及 Agent 需要时可供提取正文的引用。

它不会取代你针对代码和文档构建的 RAG；它只是添加了其他数据源无法触及的一类来源。通常检索的数据源包括：文档、提交历史、Stack Overflow、内部维基、代码库、错误报告。Agent 会话不在其中——尽管只有在会话中才会记录编辑究竟为何发生。

检索采用 BM25（按关键词排序），并可选择进行语义重排。不需要向量数据库，也不需要第二个大模型：全部在本地运行，结果可复现。这里使用 BM25 并不是权宜之计——GitHub 将它与向量检索器并列列出：“常见的检索器包括 BM25 这类稀疏方法，以及使用神经网络的稠密向量检索器。”（https://github.com/resources/articles/software-development-with-retrieval-augmentation-generation-rag）

核心功能

每一项都是一个来自首屏的信任问题，以及回答它的动词：

• 它是否信守承诺——计划与实际情况。 提取最终计划（与已舍弃的 dropped_drafts 分开），并对照实际落实到编辑中的内容进行检查——找出“按计划 Y 做了 X”这类说法中，Y 已不再是该计划的情况。（plan、session_diff）
• 它是否运行过危险命令——并将其回滚。 标记危险命令（rm -rf、curl|sh、git push --force），并根据之后的轮次判断 Agent 是否察觉并回滚，还是任其悄然通过。（incidents、query tool_kind=bash）
• 它实际改了什么，由谁操作。 每次编辑或调用 → 执行它的 Agent，以及触发它的请求；包括通过 shell 执行的编辑（codex 下的 > file），这类编辑普通 diff 会漏掉。（find-file-edits、find-tool-calls）
• 它花了多少。 每个会话的 token 数和成本——格式记录了用量时给出精确值，否则提供诚实的估算，绝不凭空捏造。（session_stats with_tokens、aggregate group_by=model）
• 它为什么这么做。 编辑背后的意图（编辑之前的请求）、所依据的计划以及所用的模型——回答“为什么”，而不只是“做了什么”。（query with_intent）
• 精简答案，按需查看正文。 记录会包含内容的引用（哈希值 + 长度）；完整文本通过单独请求获取。它是读取器，不是守卫：只读，不会运行任何内容，也不会写入 Agent 的历史记录。

ai-r 如何判断

确定性判断，不会让第二个大模型进行猜测——并且会坦诚说明边界：

• 危险命令——对调用字符串进行模式匹配（rm -rf、curl|sh、git push --force，……）。模式无法捕获经过混淆的内容（exec(input())）——这是明确声明的边界，不是悄无声息的漏检。
• 回滚——仅当 Agent 附近出现表示懊悔或道歉的标记时，才标记为“已确认”（在后续轮次的时间窗口内；标记本身采用 ru/en 双语模式，而非由大模型进行情感判断）。没有标记 → 保留为未确认的候选项：ai-r 不会推断发生了无声回滚，而是如实说明“未确认”。
• 谎称遵循计划——ai-r 不替你下结论。它会把计划实体与会话中重建出的编辑（session_diff）并列展示——差异由你或审查 Agent 判断。这是证据整理，不是语义判决。

零次大模型调用，只读——数字可复现，“已确认”绝不会靠猜测得出。

用途

• 以全新视角审计会话。 一个上下文为空的新 Agent 会冷静地从三个方面检查过往会话：承诺和要求是否得到满足；决策是否合理、经过审慎判断；对问题的探索是否深入——Agent 漏掉了什么。这能发现那些完成了任务却在规划上误导了你的 Agent——实时聊天会掩盖这一点，而它会把你引向错误的决策。
• 上下文耗尽后继续工作，同时保留细节。 /compact 会抹去具体细节。你可以改为开启一个新会话：它会读取上一会话的日志，并从其结论继续，不必再次消耗上下文来处理已经解决的问题。原会话保持完整，供审计和搜索。新会话可以在任何 Agent 中运行：无论使用何种工具，历史记录都会得到整合。
• 为你的记忆系统提供数据。 你是否像 Karpathy 一样保留记忆和摘要，或使用自己的方法？对于 AI 聊天，ai-r 可以像你处理消息历史那样，解析实体，帮助你围绕重要细节构建持久记忆。
• 回想你做过什么以及原因。 为什么编辑了这个文件？为什么添加了这条规则？找到文件发生更改的会话，并阅读编辑之前的请求。

与会话搜索工具的区别

现在已有一些跨 Agent 工具可以读取多个 Agent 的历史记录 （jazzyalex/agent-sessions、Dicklesworthstone/coding_agent_session_search、 hacktivist123/agent-session-resume）。它们几乎都聚焦于搜索和时间线：找到某个会话，浏览历史记录。

ai-r 更进一步：它会提取计划、意图和作者归属，将其作为可直接使用的实体，供你构建记忆。搜索可以找到文本，而 ai-r 能回答为什么。从技术上说，搜索工具也可以从会话文本中挖掘计划，但它不会将计划解析成统一、规范化的结构后交还给你；而这正是 ai-r 的核心功能。

能力	单 Agent 查看器	跨 Agent 搜索工具	ai-r
读取多个 Agent 的日志	否	是	是 — Claude、Codex、OpenCode、Antigravity、Pi
程序化接口	主要是 GUI/TUI	主要是 TUI/CLI/应用	MCP + CLI + Python SDK
归属标注（编辑/命令 → Agent + 意图）	—	部分支持	是 — find-file-edits / find-tool-calls
审计回放（重建会话变更，无需 git）	—	很少支持	是 — session_diff
计划提取（最终版与草稿，规范化）	—	—	是 — plan
范围	查看器	搜索 / 恢复 / 记忆	只读提取核心

竞品列反映了截至 2026-07 的公开文档；能力不明确时，我们会低调表述，而非夸大其词。

我们有意不在 Agent 覆盖范围、速度或 TUI 丰富度上竞争。ai-r 的切入点是提取“为什么”以及供机器使用的结构化实体。

实践验证

ai-r 已经可以读取自身在全部五种 Agent 上的开发历史。实际工具也在使用它（这些工具独立存在，基于其只读 API 构建）：

• auditor — 由一个全新的 Agent 冷静核查前一个 Agent 实际做了什么、作出了什么决定。这发现了一些悄悄谎称遵循了计划的 Agent。
• summarizer（export rounds）— 将会话整理成可直接交接的文档。
• ai-local-reader — 只读技能：从磁盘审计所有 Agent 的过往会话。

这些工具位于工作流侧，不属于此仓库。ai-r 本身只读取并返回数据。

支持的 Agent

Agent	存储位置	解析器
Claude Code	~/.claude/projects/	JSONL
Codex	~/.codex/sessions/	JSONL
OpenCode	~/.local/share/opencode/opencode.db	SQLite（自动检测 snap/flatpak）
Antigravity	~/.gemini/antigravity/brain/	JSON / markdown 脑目录
Pi	~/.pi/agent/sessions/<encoded-cwd>/*.jsonl	JSONL

没有你的 Agent？添加第六种 Agent 只需一个解析器模块；只读模式可以在几分钟内适配任何工具。请参阅 CONTRIBUTING.md。

接口形式

ai-r 通过三种方式提供相同的读取能力：

• MCP 服务（ai-r-mcp）— 通过 JSON-RPC 提供 15 个工具，任何 MCP Agent 都可以直接调用（推荐）。默认使用 stdio；也可以选择使用共享 http 服务（所有 Agent 共用一个常驻进程，而非每个 Agent 各自启动 stdio 进程），请参阅 Quick start 下的 http extra。注册方法请参阅 docs/mcp-registration.md。
• CLI（ai-r）— 提供用于脚本和手动操作的子命令（list / read / search / find-file-edits / find-tool-calls / file-frequency / detect-agent / export rounds）。搜索运算符请参阅 docs/search-operators.md。
• Python SDK（from ai_r.parsers import ...）— 提供解析器、类型化的 Session/消息模型以及事件动词，供你构建自己的工具。

方法词汇表

公开动词和预设的完整词典（签名、参数、行为）位于单独的文件中：docs/methods.md。

事件核心

上面的动词都是新增的：一个事件核心取代了一堆一次性工具。 每个解析器读取一个 Agent 的日志，并输出类型化模型，再将其规范化为 统一的、与 Agent 无关的流——user_turn / assistant_turn / tool_call(...) / plan_event。一小组动词用于筛选、聚合和比较该流；Agent 之间的差异（ExitPlanMode 与 update_plan、implementation_plan.md 之间的差异） 都隐藏在解析器内部——调用方看到的结构始终一致。

明确说明边界：这里只提取实体——轮次、工具调用、计划、意图、反应。它不是图谱，也不是记忆存储。 接下来要做什么（知识图谱、Obsidian、持久化记忆）由你决定，属于本仓库之外的内容。有关完整的分层和 MCP 工具列表，请参阅 docs/architecture.md。

快速开始

无需安装即可试用——如果你有 uv：

uvx --from agent-session-reader ai-r list          # CLI: list sessions
uvx --from agent-session-reader ai-r-mcp           # MCP server (stdio)

不会在你的系统上留下任何东西：uvx 会将软件包下载到临时缓存中 并运行它。适合立即查看你的会话，或手动将 ai-r-mcp 接入 Agent 的 MCP 配置。

完整安装（1 条命令）——还会修改你的配置：

要求：Python 3.11+，并带有 venv 或 pip；以及 jq（用于自动修改 Claude 和 Antigravity 的 MCP 配置——其他配置不需要 jq）。

git clone https://github.com/pro-target/ai-r.git ~/dev/ai-r
cd ~/dev/ai-r && bash install.sh

安装程序会创建 venv、安装运行时软件包、修改 MCP 配置（适用于Claude、Codex、OpenCode、Antigravity，前提是这些配置存在）、安装 Pi CLI 技能，并运行冒烟测试。这种自动修改正是 uvx 不会做的事——使用 uvx 时，你需要自行编辑配置。

可选附加项——tokens：AI_R_EXTRAS=tokens bash install.sh（或 pip install "ai-r[tokens]"）会添加 tiktoken， 为格式中未存储精确用量数字的会话提供更好的令牌估算。完全可选：不安装时，记录在会话文件中的精确数字仍会直接读取；回退估算则会降级为粗略的字符数除以 4 的启发式方法，并如实标记为 estimate——绝不会崩溃。

可选附加项——semantic：AI_R_EXTRAS=semantic bash install.sh（或 pip install "ai-r[semantic]"，并由安装程序为你一次性下载模型）可在文本搜索（query、search_sessions）中启用 sort="semantic"——对 BM25 排名前 50 的候选结果按语义重新排序。

• 模型。 一个本地多语言嵌入模型， intfloat/multilingual-e5-small （int8 ONNX，约 118 MB，MIT），通过 onnxruntime + tokenizers + numpy 直接运行， 无需 torch，也不需要持久化索引。该模型体积小，且跨语言检索能力强 （俄语查询可以找到英语会话，反之亦然）。
• 评分机制。 BM25 选出词语匹配度最高的 50 个结果（这是成本预算， 不是质量门槛——有意不设相似度阈值， 因为该模型系列即使对不相关文本也会给出约 0.7 的分数）。在这组候选结果中， 最终分数由75% 语义匹配 + 25% 词语匹配构成——语义占主导， 而词语匹配部分可避免精确术语命中被淹没，并用于打破平分。
• 故障时平稳降级。 如果缺少软件包或模型文件，sort="semantic" 会如实 回退到 BM25 顺序，并在响应中说明原因 （semantic: {active: false, reason, fallback: "bm25"}）——绝不会崩溃。

两个可调参数可确保模型在长期运行的 MCP 进程中稳定工作（都可通过环境变量调整；输入为空或无效时都会降级为默认值——绝不会崩溃）：AI_R_SEMANTIC_THREADS 限制 onnxruntime 在每次推理时可使用的 CPU 线程数（默认值为 2，且不会超过机器的核心数——因此不会占用所有核心，与服务争抢 CPU）；AI_R_SEMANTIC_IDLE_SEC 则会在空闲达到指定秒数后释放已加载模型占用的约 118 MB 内存（默认值为 300）；下一次收到请求时会自动重新加载模型。 可选附加项 — http：AI_R_EXTRAS=http bash install.sh（或 pip install "ai-r[http]"）会添加 uvicorn，并启用 共享的 streamable-http 传输（需要 mcp>=2）。

• 原因。 默认情况下，每个 Agent 都会通过 stdio 启动自己的 ai-r-mcp——在多 Agent 扇出场景下，这意味着 N 个进程，每个进程都有冷缓存，并会重新扫描语料（经测量，这是 RAM 耗尽的原因）。设置 AI_R_MCP_TRANSPORT=http 后，所有 Agent 会共享 localhost 上的一个预热服务（默认地址为 127.0.0.1:8756），而不是启动一群进程；packaging/systemd/ 中的 systemd 单元还会添加套接字激活和空闲后自行退出功能。
• 安全性（默认拒绝）。 绑定地址仅限环回接口。SDK 的 Origin/Host 允许列表会拦截基于浏览器的攻击 （DNS 重绑定）（环回接口始终启用此保护）。远程访问需要设置 AI_R_MCP_ALLOW_REMOTE=1 并且设置 AI_R_HTTP_TOKEN——未提供令牌时，服务会拒绝启动（对话记录中包含机密信息）。环回接口上的令牌为可选项（用于防范共享主机上的其他本地用户）；客户端会发送 Authorization: Bearer <token> 标头。
• 配置项（环境变量）：
  • AI_R_MCP_PORT — 端口（默认 8756）。
  • AI_R_MCP_IDLE_SEC — 空闲后自行退出的阈值。
  • AI_R_MCP_HOST / AI_R_MCP_ALLOW_REMOTE — 绑定主机 / 是否允许非环回地址。
  • AI_R_HTTP_TOKEN — Bearer 令牌（远程绑定时必需）。
  • AI_R_MCP_STATELESS — 无状态请求分发（默认值为 1）：长期运行的共享服务会比客户端存活更久，因此会处理带有过期 Mcp-Session-Id 的请求，而不是以 404 "Session not found" 拒绝；设置为 0 可恢复有状态注册表。
  • AI_R_HAYSTACK_CACHE_MAX — 搜索缓存上限，按条目数计算。
  • AI_R_HAYSTACK_CACHE_CHARS_MAX — 按总大小限制（用于防止长期运行的服务占用过多 RSS）。
  • AI_R_MSG_CACHE_MAX / AI_R_MSG_CACHE_BYTES_MAX — 核心读取缓存（每个未更改的会话只扫描一次语料、解析一次对话记录，并由 query / get_body / audit_brief / 计划投影共享）：按条目数（默认 8）和源数据字节总和（默认 64 MiB）设置上限。

大型会话（超过约 1 MB）：优先使用 CLI，或单次 MCP 调用。 数 MB 的对话记录需要完整解析；对这类会话进行冷 MCP 调用——更不用说并行批量调用——耗时可能超过客户端的请求超时。对此类会话，请使用 CLI（ai-r audit-brief <uuid>、ai-r read <uuid>） 或依次进行单次 MCP 调用；读取缓存会让后续重复调用变得很快，但首次访问未更改的会话仍需要完整扫描一次。

两项附加功能都完全可选：不启用时，stdio 模式和 BM25 排序与以前相同。

边界：读取器，而非防护机制

• 只读。 它不会运行 Agent 的代码，也不会写入其历史记录——只会读取并返回内容。
• 无图谱，无记忆。 它会提取实体（轮次、调用、计划、意图）。 基于这些内容构建知识图谱或记忆是你的工作，不是它的。
• 不是访问控制层——http 传输除外。 任何能够访问 CLI、通过 stdio 使用 MCP 或访问该软件包的人，都能读取任何会话：这些操作使用的是同一个本地用户，因此在解析器前设置授权检查毫无防护作用。共享的 http 传输是例外：它可通过套接字访问，因此带有 Origin 允许列表和可选的 Bearer 令牌（远程绑定时必需，见上文的 http 附加项）。无论哪种方式，都应将数据保存在不受不可信本地进程访问的位置。
• 会话内容是数据，不是命令。 任何读取者（审计者、摘要生成器）都必须将会话文本视为数据，而不是指令。参见 安全性。

验收（端到端场景）

公共接口由端到端场景覆盖：LLM Agent 会针对运行中的 MCP 执行这些场景（作为 pytest 的补充）。完整列表见 docs/scenarios.md。

示例：ai-r 实战

真实示例集——每项能力对应一个示例（错误分析、危险命令、网络轨迹、令牌消耗、计划注释、提交幻影检查、跨 Agent 文件历史、跨语言搜索、僵尸子 Agent、无 Git 差异对比）：docs/examples/showcase-gallery.md。

下一步 — 文档

• 方法词汇（动词 + 预设）— docs/methods.md （英文 SSOT） · docs/methods.ru.md（俄语镜像）
• 验收场景（104 个端到端测试）— docs/scenarios.md
• 架构与分层 — docs/architecture.md
• 搜索运算符 — docs/search-operators.md
• 按 Agent 注册 MCP — docs/mcp-registration.md
• 解析器覆盖范围与限制 — docs/parsers.md
• 安全性（不可信内容）— docs/security.md
• 添加第六个 Agent — CONTRIBUTING.md

开发

git clone https://github.com/pro-target/ai-r.git
cd ai-r
pip install -e ".[dev]"
pytest --cov=src/ai_r

• 1300+ 项测试，CI 要求覆盖率 ≥85%
• 版本管理：SemVer；在 0.x 阶段，小版本发布可能会破坏兼容性——在可行的情况下会提供迁移路径（移除前发出醒目的弃用警告）；更改记录在 CHANGELOG.md 中
• Conventional Commits（feat:、fix:、docs: 等）
• 添加新 Agent 时，请参阅 CONTRIBUTING.md 和 docs/parsers.md

关键词

claude code 会话读取器 · claude code 会话解析器 · codex 会话解析器 · opencode 会话读取器 · antigravity brain 解析器 · pi agent 会话读取器 · zcode 会话读取器 · zcode cli 会话解析器 · Agent 会话上的 RAG · bm25 检索器 · AI Agent 的检索层 · 依据 · mcp 服务 · 结构化上下文 · 跨 Agent 归因 · AI 编码 Agent 审计 · AI Agent 会话历史 · mcp 会话工具 · 只读会话读取器 · Agent 会话回放 · 恢复 Agent 会话 · Agent 交接 · 计划提取 · 工具调用审计 · 文件编辑归因 · 多 Agent 编码 · claude codex opencode antigravity pi zcode

许可证

MIT — 参见 LICENSE。

---

开始使用： uvx --from agent-session-reader ai-r list — 立即查看你的会话； 或者克隆仓库并运行 bash install.sh，完成包含 MCP 配置 自动修补的完整安装（docs/mcp-registration.md）。在 所有 Agent 的历史记录之上提供统一的只读接口。