Polygraph 完全指南：为 AI 编码 Agent 提供跨仓库统一视角和持久会话记忆

AI 编码 Agent 正在成为开发者日常工作的标配，但它们有两堵墙：空间之墙——一个 Agent 会话只能在一个仓库里工作，看不到变更对整个系统的波及范围；时间之墙——每次新会话都是一张白纸，上回调试到一半的上下文、决策推理、PR 关联信息全部丢失。

Polygraph 正是为解决这两堵墙而生的「元套件」（meta-harness）。它不替代你正在使用的 Agent（Claude Code、Codex、OpenCode），而是在它们之上增加跨仓库协作和持久记忆的能力。本文将全面介绍 Polygraph 的核心功能、安装使用和实战场景。

架构：合成 Monorepo

Polygraph 的核心思路是创建一个依赖关系图。它会索引你有权访问的每一个仓库（包括私有仓库和 GitHub 公开仓库），提取其中存在的项目、依赖关系、发布的包以及定义的 API。这些信息构成一个统一的图结构——Polygraph 的名字即来源于此。

在这个图之上，每个会话（session）都有一个 parent agent 负责保持全局任务上下文、规划跨仓库的工作，并将仓库级别的子任务委派给 child agents。Child agents 之间可以互相通信、请求权限和协调工作。结果就是：你的 Agent 拥有 monorepo 级别的操作体验，但实际仓库并不需要合并。

安装与环境

Polygraph 提供两种安装方式，覆盖 npm 和 Homebrew 生态：

npm 方式：

npm install -g polygraph@latest

Homebrew 方式：

brew install nrwl/tap/polygraph

安装完成后，你不需要额外配置环境变量或 API 密钥。所有认证通过 OAuth 设备流完成。

系统要求

• 支持 macOS 和 Linux
• 需要 GitHub 账号（用于授权仓库访问）
• 与 Claude Code、Codex、OpenCode 等主流 AI 编码 Agent 兼容

功能详解

1. 跨仓库 Agent 会话（Cross-repo Agent Sessions）

这是 Polygraph 最核心的功能。传统上，一个 Claude Code 或 Codex 会话只能工作在一个工作目录下。Polygraph 打破了这一限制：一个会话可以同时包含多个仓库，Agent 在会话中能读取和修改所有选定的仓库，就像它们是一个 monorepo 那样。

仓库在会话中扮演两种角色：上下文仓库（Agent 只需要读取它来理解 API、检查依赖或查阅文档）和变更仓库（Agent 需要实际修改并提交代码）。你可以在启动会话时选择仓库，也可以在工作过程中让 Agent 动态扩展。

polygraph session start

启动后，你可以用自然语言让 Agent 添加更多仓库：

请把 acme/frontend 加入这个会话。

2. 持久会话记忆（Memory and Resumability）

Agent 本身没有「情景记忆」。昨天调试到一半的 bug、已经否决的技术方案、团队成员之间的上下文交接——这些价值远超 git log 本身的信息，会在会话结束时全部消失。

Polygraph 把每一次会话记录为一个情景片段（episode），包含 Agent 轨迹、会话描述、涉及的仓库、分支、PR 和关联的 Issue。你可以精确地恢复到某个会话结束时的状态——不是拷贝一份 handoff 文件，而是真正的时间机器。

polygraph session resume

如果不指定 ID，CLI 会列出最近的会话供你选择。恢复后，Polygraph 会尽可能地重建会话状态：仓库、分支、Agent 轨迹以及相关的 Agent 缓存。

这种记忆是全组织共享的——任何人的 Agent 都可以引用和恢复团队其他成员创建的会话，打破了个人 Agent 之间的信息孤岛。

3. 跨仓库 PR 和 CI 协调

如果一个变更涉及 5 个仓库，你要分别打开 5 个 PR 并确保它们同时被审查和合并——这通常是跨仓库协作的最大痛点。

Polygraph 将这些 PR 关联到同一个会话中，实现一站式管理。一个会话可以追踪：

• 从每个仓库推送的分支
• 打开的 Draft PR
• 关联的已有 PR
• 各 PR 的 CI 状态
• 所有 PR 的就绪情况

Agent 可以直接从会话中创建 PR：

把所有变更推送并打开 PR。

或通过 CLI 手动控制：

polygraph git push-branch
polygraph git create-pr
polygraph git mark-pr-ready

对于已经存在的 PR，也可以关联到当前会话：

polygraph git associate-pr https://github.com/myorg/backend/pull/482

4. OSS 仓库集成

Polygraph 可以访问 GitHub 上的所有公开仓库，并且知道它们之间的依赖关系。这意味着你可以在会话中引入第三方开源仓库，实现端到端的问题复现和调试。

适用场景：

• Bug 报告中包含公开的复现仓库
• 你的代码依赖某个上游开源项目
• 需要针对公开的消费者验证未发布的修复

请把 @opentui/core 加入这个会话，检查我是否正确使用它的 API。

对于发布者-消费者验证场景，Polygraph 提供了 pack_and_copy 命令，可以将变更的包打包并直接安装到消费者仓库中测试，无需经过 registry 中转。

实战场景

场景一：跨仓库功能开发

假设你需要给后端 API 加一个新端点，同时在前端 UI 中展示它——两个仓库分属不同的团队，但变更必须同步落地。

polygraph session start

然后让 Agent 加入前端仓库，并在写代码之前先阅读两个仓库的架构：

请把 acme/frontend 加入这个会话。
这里有一份功能规格说明（feature-spec.md）。
在写代码之前，先阅读两个仓库的代码，确认 API 契约和共享类型结构。
然后按仓库拆解计划，每仓库一条。

Agent 会先阅读两个仓库的代码结构，理解现有的 API 模式和 UI 组件模式，然后制定出分仓库的执行计划。完成编码后，Agent 可以一键为两个仓库同时打开关联 PR。

场景二：CVE 安全补丁（全仓库扫描）

一个新的 CVE 公告发布了，你需要找出所有受影响的仓库、打上补丁、并记录审计痕迹。

polygraph session start

第一步：让 Agent 阅读公告并评估影响范围，不做任何修改：

请阅读这个安全公告并总结受影响版本和攻击面。
暂不要修改任何代码。
然后找出我账号下所有依赖了受影响的包的仓库，报告每个仓库的已安装版本、
依赖类型（直接/传递）和使用位置。

第二步，确认范围后，让 Agent 逐个修复：

对每个受影响的仓库：创建修复分支，将包升级到安全版本（传递依赖则使用 override 锁定）。
执行 install 和测试，不做其他任何修改。报告每个仓库的通过/失败情况。

第三步，将修复 PR 分发给对应团队：

为每个仓库打开 Draft PR，标题为 "fix(security): bump <包名> (<版本>)"
正文包含公告链接、变更内容、测试输出和此会话链接。
@-mention 对应仓库的维护者。

整个流程从单一会话完成，保证了审计轨迹的完整性。

Polygraph 与其他方案对比

常见问题

Q：Polygraph 会读取我的私有仓库代码吗？

A：Polygraph 通过 GitHub OAuth 授权访问你的仓库，权限与你个人一致。数据在传输和存储过程中加密。

Q：它支持哪些 Agent？

A：Claude Code、Codex、OpenCode 以及 GitHub 生态相关的编码 Agent。

Q：会改变我已有的仓库结构吗？

A：不会。Polygraph 不移动任何代码，不创建符号链接，不改动 Git 历史。它只在外部创建索引和会话记录。

Q：免费吗？

A：目前处于早期访问阶段，完全免费使用。任何定价变更前会提前 30 天通知。

Q：Polygraph 本身是一个 Agent 吗？

A：不是。它是一个元套件（meta-harness），为已有 Agent 增加跨仓库和记忆能力，并不替代你使用的编码 Agent。

总结

Polygraph 解决了一个真实且日益突出的问题：当 AI 编码 Agent 从单文件助手进化为全功能开发伙伴时，它们需要跨越仓库边界、记住历史决策、并与团队其他成员（以及他们的 Agent）共享上下文。Polygraph 以「合成 monorepo」的思路，在不改变实际仓库结构的前提下，为 Agent 提供了企业级协作能力。

如果你是重度使用 AI 编码 Agent 的开发者或团队，Polygraph 值得一试——尤其是当你频繁跨仓库开发、管理安全补丁、或需要在多个 Agent 之间共享会话上下文时。

相关链接：

• Polygraph 官网
• Polygraph 文档
• Quickstart 指南
• 跨仓库会话功能介绍
• 记忆与恢复功能介绍