agent-intern

<div align="center"> # Claude 代码 × 反重力 CLI + OpenAI Codex — MCP 桥接 <img src="assets/bridge-animation.svg" width="100%" alt="Claude 代码桥接反重力 CLI 和 OpenAI Codex" /> **在 Claude 代码中驱动谷歌的 [反重力](https://antigravity.google/)（Gemini 3.5 Flash）和 [OpenAI Codex](https://developers.openai.com/codex/) 作为子代理——文本答案、图像生成和真正的编码工作，在您已经付费的配额上。** [](https://github.com/SinanTufekci/agent-intern/actions/workflows/ci.yml) [](https://pypi.org/project/agent-intern/) [](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](https://glama.ai/mcp/servers/SinanTufekci/agent-intern) [](https://antigravity.google/) [](#requirements) [](https://github.com/sponsors/SinanTufekci) </div> --- `agy`，谷歌的反重力 CLI，配备了一个无界面打印模式（`agy -p`），**但是该模式存在问题**：它会认证， 与模型对话，获取答案，然后**写入控制终端**，而不是标准输出——因此任何捕获标准输出的操作都不会收到任何内容（并且，在 TUI 下运行，agy 的文本会直接泄漏到主机的提示符中）。这个桥接器运行 `agy -p`，**使其与您的终端分离**，使其不会泄漏， 直接从 agy 的**自己的**转录文件中读取答案，并将答案作为干净的 MCP 工具交给 Claude 代码。 将廉价的工具调用工作委派给 Gemini，而无需离开您的终端。 > [!WARNING] > **此运行未沙盒化代码，拥有您的权限**。`agy -p` 自动执行其工具（读取/写入文件，运行 shell 命令，访问网络）**没有可用的批准门槛**。 > `--sandbox`（针对 `agy -p` 中的 1.0.6+ 版本进行修复）仅阻止 **shell 命令**，而文件写入和网络出口仍然完全开放——因此它不是真正的安全边界。 `workspace` 参数是一个**起始上下文**，**不是**安全边界。 仅在**受信任的内容上使用受信任的提示**；对于真正的隔离，在容器或 VM 中运行桥接器。 **[完整详情 →](#security)** > [!NOTE] > **现在还支持 OpenAI Codex**。同一个桥接器公开了 `codex_ask` / `codex_continue` / `codex_ask_watch` / `codex_swarm` / `codex_status`，驱动 OpenAI 的 `codex exec` 使用您现有的 Codex 登录。 Codex 是 **表现良好的** 兄弟姐妹：它将答案直接写入桥接器请求的 文件中（无需转录文件抓取），支持模型选择，并具有**真正的**沙盒。 请参阅 [Codex 桥接](#codex-bridge)。 ## 为什么您需要这个 | | | |---|---| | 🧠 **第二意见** | 在任务中途无需切换工具即可询问不同的模型家族。 | | 🎨 **图像生成** | 让 Gemini 绘制图像并获取保存的文件——无需额外的 API 密钥或图像工具。 | | 💸 **廉价委托** | 在 Claude 代币上烧掉 Antigravity AI Pro 配额用于琐碎工作。 | | 📁 **跨仓库读取** | 将其指向另一个项目目录，让 Gemini 读取/回答。 | | 🔌 **零新身份验证** | 利用您已经在 Antigravity IDE 中完成的登录——无需管理密钥。 | ## 工作原理 ```mermaid flowchart LR A([Claude 代码]) -- "MCP 工具调用" --> B["agy 桥接<br/>(server.py)"] B -- "agy -p 提示" --> C[反重力 CLI] C -- "Gemini 3.5 Flash (高)" --> M((模型)) M -- "答案" --> C C -. "写入（标准输出保持为空）" .-> T[("transcript.jsonl")] B -- "读取最终 PLANNER_RESPONSE" --> T B -- "纯文本" --> A ``` `agy -p` 将其真正的答案——它从不发送到标准输出的答案——持久化到： ``` ~/.gemini/antigravity-cli/brain/<conv-id>/.system_generated/logs/transcript.jsonl ``` 桥接器运行 agy， 通过 `cache/last_conversations.json` 定位对话（回退到启动时触摸的最新 `brain/` 目录）， 流式传输转录， 并返回最终的 `source=MODEL, status=DONE, type=PLANNER_RESPONSE` 条目——答案，减去中间工具调用步骤。 `antigravity_continue` 通过 `--conversation` 固定工作区的**确切**对话 ID，因此它永远不会恢复错误的线程。 ## 60 秒设置 **先决条件（任一方法）：** 安装 agy 并登录到反重力 **一次**（通过 IDE 或 `agy -i`），以便它具有可重用的凭证。 ### 推荐 - 无克隆，您控制更新 在 [`uv`](https://docs.astral.sh/uv/) 安装的情况下，在 `mcpServers` 下的 `~/.claude.json` 中直接从 [PyPI](https://pypi.org/project/agent-intern/) 注册桥接器 - 无需硬编码路径，无需记住 `git pull`： ```json "agent-intern": { "command": "uvx", "args": ["agent-intern"] } ``` uvx 固定到它第一次缓存的版本，并且**不**自动升级，因此您永远不会运行未经选择的更新 - 很重要，因为桥接器运行 [未沙盒化代码](#security)：意外（或泄露）版本无法执行，直到您选择它。 当启动检查警告有新版本时，请有选择地升级并重启 Claude 代码： ```bash uvx agent-intern@latest # 获取 + 运行最新版本（刷新 uv 的缓存） ``` > [!TIP] > 更喜欢自动更新？在配置中添加 `"args": ["agent-intern@latest"]` - 每次启动都运行最新版本。 方便，但每次都会拉取新代码。 ### 从源代码 克隆它以便您可以修改桥接器或固定本地副本： ```bash git clone https://github.com/SinanTufekci/agent-intern.git cd agent-intern pip install fastmcp python test_smoke.py # 3 次真实往返（询问，继续，图像）- 应该打印三行 PASS ``` > [!NOTE] > 烟雾测试会消耗一点 AI Pro 配额，并需要 ~30-60 秒。 然后将 Claude 代码指向 `server.py` 的绝对路径，在 `mcpServers` 下的 `~/.claude.json` 中： <table> <tr><th>Windows</th><th>macOS / Linux</th></tr> <tr><td> ```json "agent-intern": { "command": "python", "args": ["C:\\path\\to\\server.py"] } ``` </td><td> ```json "agent-intern": { "command": "python3", "args": ["/path/to/server.py"] } ``` </td></tr> </table> 重启 Claude 代码。 **11 种工具**出现 - 6 种用于反重力（**`antigravity_ask`**，**`antigravity_continue`**，**`antigravity_image`**，**`antigravity_swarm`**，**`antigravity_image_swarm`**，**`antigravity_status`**）和 5 种用于 Codex（**`codex_ask`**，**`codex_continue`**，**`codex_ask_watch`**，**`codex_swarm`**，**`codex_status`**）- 每个前缀为 `mcp__agent-intern__`。 单提示反重力工具采用 **`watch=true`** 标志用于实时浏览器视图；Codex 有专用的 **`codex_ask_watch`**。 > *"使用 antigravity_ask 总结此存储库的 README，分为三个项目符号。"* → Claude 通过桥接器路由提示，agy 读取工作区根目录下的文件，答案以纯字符串返回。 ## 工具 | 工具 | 目的 | |---|---| | `antigravity_ask(prompt, workspace?, timeout_s?=180, watch?=false)` | 启动一个**新的**反重力对话。 传递 `watch=true` 以打开实时浏览器视图（参见 [观看模式](#watch-mode)）。 | | `antigravity_continue(prompt, workspace?, timeout_s?=180, watch?=false)` | 继续**根于 `workspace`**（按 ID 固定）的对话。 `watch=true` 打开实时视图。 | | `antigravity_image(prompt, output_path?, workspace?, timeout_s?=240, watch?=false)` | 使用反重力生成图像；保存文件（扩展名修正为真实字节）并返回其路径 + 格式/大小。 `watch=true` 流式传输进度并**显示图像**内联。 | | `antigravity_swarm(prompts, workspaces?, max_concurrency?=4, timeout_s?=180, watch?=false)` | 以**独立的 agy 工作线程**并行运行**多个提示**；每个答案一次性返回（参见 [Swarm](#swarm)）。 | | `antigravity_image_swarm(prompts, output_paths?, workspaces?, max_concurrency?=4, timeout_s?=240, watch?=false)` | **并行生成多个图像**（每个提示一个工作线程）。 | | `antigravity_status()` | 设置诊断：**桥接器的版本 + 是否有新版本可用**，以及 agy 版本/兼容性、状态目录和最新转录文件可读性。不消耗配额。 | `workspace` 默认设置为 MCP 服务器的当前工作目录。 将其指向真正的项目目录以获取上下文相关的答案 - agy 允许模型访问该根目录下的文件。 `antigravity_image` 强制 agy 保存到显式绝对路径 - 没有它，agy 回退到自己的临时目录（`~/.gemini/antigravity-cli/scratch/`）。 然后它纠正文件扩展名以匹配真实字节：agy 的图像模型自行选择格式（照片类图像为 JPEG，平坦图形为 PNG），因此请求的 `out.png` 可能返回为 `out.jpg`。 返回的路径始终反映真实格式。 <a id="codex-bridge"></a> ## 🤖 Codex 桥接 除了反重力之外，桥接器还通过 `codex exec` 驱动 **[OpenAI Codex](https://developers.openai.com/codex/)**。 在 `agy -p` 是损坏的（它从不写入标准输出，因此桥接器抓取转录文件），`codex exec` 是表现良好的：它将答案直接写入桥接器请求的 文件中，因此答案返回干净 - 无需抓取。 继续工作是通过捕获 codex 自己的滚动文件（`~/.codex/sessions/.../rollout-*.jsonl`）并使用 `codex exec resume <id>` 恢复。 | 工具 | 目的 | |---|---| | `codex_ask(prompt, workspace?, sandbox?="read-only", model?, timeout_s?=180)` | 启动一个**新的** Codex 会话。 `sandbox` 是一个**真正的**边界（参见下文）；`model` 选择模型（`-m`）。 | | `codex_continue(prompt, workspace?, timeout_s?=180)` | 继续 **根于 `workspace`** 的 Codex 会话 - 恢复确切的会话 ID， 如果服务器重启，则回退到磁盘上最新的会话。 | | `codex_ask_watch(prompt, workspace?, sandbox?, model?, timeout_s?=180)` | 像 `codex_ask` 一样，但打开实时浏览器视图，从其 `--json` 事件流式传输 codex 的步骤（与 Antigravity 观看相同 - 参见 [观看模式](#watch-mode)）。 | | `codex_swarm(prompts, workspaces?, sandbox?, model?, max_concurrency?=4, timeout_s?=180)` | 以**独立的 one-shot 工作线程**并行运行 **多个 Codex 提示**；每个结果一次性返回。 | | `codex_status()` | 设置诊断：codex 版本，登录状态（`codex login status`），会话目录。 不消耗配额。 | **它与反重力工具有何不同** - **真正的沙盒。** `sandbox` 接受 `read-only`（默认 - 读取和答案，不写入任何内容）， `workspace-write`（可能编辑工作区下的文件）和 `danger-full-access`（无沙盒 - 避免）。 与 agy 的无效 `--sandbox` 不同，codex 的 `-s` 实际执行此操作。 `codex exec` 没有交互式批准门槛，因此此标志 **是**您的安全边界 - 故意选择写入访问权限。 - **模型选择有效。** `model` 映射到 codex 的 `-m`；agy 在打印模式下挂起模型切换，而 codex 不会。 - **没有图像工具。** Codex 是编码代理，不是图像模型 - 没有 `codex_image`。 它的优势是推理和真正的代码/仓库工作。 - **身份验证。** 使用现有的 Codex 登录（ChatGPT 帐户或 API 密钥）。 运行 `codex login` 一次；检查 `codex_status`。 无需桥接器管理的新密钥。 > [!WARNING] > `codex exec` 将模型作为 **具有无交互式批准门槛的自主代理运行**。 `sandbox` 标志（默认为 `read-only`）是真正的边界，但 `workspace-write` / `danger-full-access` 允许它修改文件 - 而 Swarm 运行 N 个代理一次。 仅在**受信任的内容上使用受信任的提示**。 <a id="watch-mode"></a> ## 👁️ 观看模式 - 代理内部（实验） 传递 **`watch=true`** 到 `antigravity_ask`，` 变成一个小终端风格的浏览器窗口，称为 **Agent Intern**，以 **观看 agy 工作实时**。agy 仍然无界面运行；桥接器在旁边提供一个小页面，在 `127.0.0.1` 上打开它，并在小而无边框的应用程序窗口中打开它，实时流式传输 agy 的步骤 - 它的计划叙述（▸）、它运行的实际命令（ `$`）和补全（✓）- 从转录文件中读取实时数据，最终答案渲染为 Markdown（对于 `antigravity_image`，生成的图像内联显示）。 <div align="center"> <table> <tr> <td width="50%" align="center"><b>`antigravity_ask` / `antigravity_continue`</b></td> <td width="50%" align="center"><b>`antigravity_image` - 图像内联</b></td> </tr> <tr> <td><img src="assets/watch-ask.gif" width="100%" alt="Agent Intern 观看窗口实时流式传输 agy 的步骤以获取文本询问 - 叙述，它运行的实际命令，完成，然后渲染最终的 Markdown 答案"></td> <td><img src="assets/watch-image.gif" width="100%" alt="Agent Intern 观看窗口实时流式传输图像生成并内联渲染完成后的图像"></td> </tr> </table> <sub>真实捕获 - agy 无界面运行，而 <b>Agent Intern</b> 窗口实时流式传输其步骤（▸ 叙述 · <code>$</code> 命令 · ✓ 补全），然后显示最终答案或图像。</sub> - **跨平台和尽力而为。** 优先使用 Chromium 浏览器（`--app` 模式）以获得窗口化外观；如果无法使用，则回退到普通浏览器窗口。 如果无法打开任何窗口，则运行仍然完成并正常返回。 - **窗口大小。** 设置 **`AGY_WATCH_WINDOW_SIZE`**（例如 `AGY_WATCH_WINDOW_SIZE=480,700`）以调整窗口大小；默认为 `560,760`。 在窗口中按 **Enter / Esc** 以关闭它。 - **一个窗口，重用。** 重复观看调用 **重用已打开的窗口** 而不是堆叠一个新窗口 - 打开的页面为新运行重置自身（Swarm 仪表板为新分发重建）。 如果您关闭了窗口，则下一次运行会打开一个新窗口。 设置 **`AGY_WATCH_ALWAYS_NEW=1`** 以强制每次都打开一个新窗口。 - **进度，键盘和复制。** 每个面板显示一个时间进度条（已用时间 / 超时）。Swarm 仪表板添加一个整体已完成/总数条和每个任务的每行时间条；使用 **↑/↓** 选择一个工作线程并使用 **↵** 打开其详细窗口。 答案渲染为 Markdown，并带有 **复制** 按钮，如果您滚动到顶部，则会出现一个“跳转到最新”徽章。 - **粗略，而不是基于令牌。** agy 以块为单位刷新其转录，因此您会收到几个实时的步骤，而不是字符流。 返回的值与非观看调用相同。 除您自己的机器外，什么也不会发送到任何地方。 <a id="swarm"></a> ## 🐝 Swarm - 并行运行 agy 工作线程 `antigravity_swarm` 和 `antigravity_image_swarm` 将提示列表分发给 **独立的 agy 工作线程，这些线程真正并发运行**（上限为 `max_concurrency`，默认为 4），然后以一个块返回每个工作线程的结果。 适用于独立、廉价的子任务 - 将 N 个文件汇总，询问关于 N 个仓库的相同问题，生成 N 个图像 - 而无需分别支付它们。 ``` antigravity_swarm(prompts=[ "将 src/auth.py 总结为 2 个项目符号。", "将 src/db.py 总结为 2 个项目符号。", "列出 src/api.py 中的公共函数。", ]) ``` <div align="center"> <img src="assets/watch-swarm.gif" width="62%" alt="Swarm 仪表板：三个 agy 工作线程并行运行，每个行显示其仓库，提示和最新步骤，以及每个工作线程的时间条，同时整体完成/总数计数器攀升 0/3 → 2/3 → 3/技术文档 </div> **如何在并发情况下保持正确。** 单代理工具通过锁序列化，因为 agy 在每次调用时都会重写 `last_conversations.json`，因此并发运行共享一个状态目录将会发生冲突。Swarm 规避了这一点：每个工作线程运行在 **自己的隔离 `HOME`/`USERPROFILE`**，因此 agy 的 `brain/`、`cache/` 和 `last_conversations.json` 永远不会冲突 - 无需锁定。 身份验证仍然有效，因为 agy 从 **OS 凭证存储** 读取它，而不是从 `~/.gemini`（在 agy 1.0.9 上验证）。 每个工作线程的 `cwd` 仍然是其实际 `workspace`，因此在那里的文件访问保持不变 - HOME 重定向仅隔离 **状态**。 在 3 个工作线程时测得 **约 2.8 倍加速**（AI Pro 后端不按帐户排序）；更高的 `max_concurrency` 以更快的墙上时钟为代价交易配额/速率限制压力。 - **`workspaces`** - 省略以使用服务器 cwd；传递 **1 项列表** 以将所有工作线程指向同一目录；传递 **每个提示对应一个条目** 以使用每个工作线程的独立目录。 - **错误隔离** - 失败的工作线程在原地报告；其他工作线程仍会返回。 - **`watch=true`** - 打开一个精简的实时 **Swarm 仪表板**（每行一个工作线程，显示仓库、提示和最新步骤）。 **点击一行** 以将该代理弹出到其自己的窗口中，流式传输其完整的步骤日志，位于仪表板旁边。 > [!WARNING] > Swarm 启动 **N 个未沙盒化 agy 代理同时运行** - 单次调用的 N 倍潜在注入表面（参见 [安全](#security)）。仅在**受信任的内容上使用受信任的提示**。 ## 模型与认证 - **模型：** 有效地使用 **Gemini 3.5 Flash（高速）** — 无论在 agy 的 `settings.json` 中将 `"model"` 字段设置为多少。agy 1.0.5 添加了一个 `--model` 标志（以及一个 `models` 子命令），该标志与打印模式相连，但 **切换到 `-p` 中的不同模型会使调用挂起**（在 1.0.5 上验证：传递已激活的标签会返回秒级，其他标签挂起 >60 秒）。因此，桥接器保持单模型；如果需要其他模型，请通过 agy 的 `settings.json` 进行更改。Flash 高速优化了工具调用的速度，因此它最适合作为 **快速子代理执行廉价工作**，而不是重度推理伙伴。 - **认证：** 利用您的操作系统上 `agy` 使用的凭证存储（Windows 凭证管理器、macOS 钥匙串、Linux 上的 libsecret — 桥接器直接不触及它）。登录一次；之后的每次调用都会在您已经付费的 **相同 AI Pro 配额** 上进行静默认证。 <a id="security"></a> ## ⚠️ 安全 `agy -p` 运行模型作为一个 **自主代理，自动执行其自己的工具** — 读取和写入文件，运行 shell 命令，并访问网络 — **没有审批门槛，也没有退出选项**。这不是桥接器做出的选择；这是 agy 的打印模式的工作方式。经验证实，在 **agy 1.0.9 / Windows** 上（以下三个检查仍然成立）： - 打印模式在没有 `--dangerously-skip-permissions` 的情况下运行工作区外的文件写入和实时网络获取 — 该标志对于 `-p` 是一个 **无操作**。没有 agy 标志禁用打印模式下的工具执行。 - agy 1.0.5 集成了权限系统（其日志显示 `toolPermission=request-review`），但它 **仍然不限制打印模式的执行** — 一个全新的 `-p` 运行在没有提示的情况下创建了一个工作区外的文件。 - `--sandbox` 不是一个可用的边界。agy 1.0.6 修复了它在 `-p` 中的传播（1.0.6/1.0.7 更新日志称之为“正确强制实施沙盒隔离”），现在它 **确实** 阻止了终端/ shell 命令执行 — 但在 1.0.9 上重新验证，它留下了 `write_to_file` 工具和网络 **完全开放**：在 `--sandbox` 下，模型仍然在工作区外写入了一个文件。agy 1.0.9 加固了沙盒的 **命令** 路径（更严格的精确匹配命令检查；`.git` 添加到了其危险路径列表），但这些都没有关闭工作区外的 `write_to_file` 漏洞。此外，一个 `--sandbox` 运行，其被阻止的终端命令暂停它，不会写入 **JSONL 转录**（只有 SQLite `.db`，在 1.0.9 上重新确认），因此桥接器无法读取响应 — 所以桥接器故意从不传递 `--sandbox`。 **这对您意味着：** - `workspace` 参数仅是一个 **起始上下文**，**不是安全边界** — 代理可以并且确实在它之外执行操作。 - 每次调用都有效地运行 **具有您的用户权限的任意代码**。 - 仅在 **受信任的提示和受信任的内容** 上调用此功能。受信任的输入在这里是经典的提示注入 **致命三要素**：私有数据访问 + 代码执行 + 网络出口。 - 为了真正的隔离，在 **容器或虚拟机中运行整个桥接器**。 桥接器本身只在 `~/.gemini/antigravity-cli/` 下执行跨平台的文件系统读取 — 没有私有 API，没有令牌窃取。上述风险完全在于允许 agy 子代理执行的操作。 ## 常见问题 <details> <summary><b>这是否违反谷歌的服务条款？</b></summary> 它在您的 **AI Pro 会话** 下运行官方的 `agy` CLI — 没有私有 API，没有令牌窃取，没有配额滥用。它只是桥接了 CLI 已经执行的操作。但是，您的 AI Pro / Antigravity 条款和条件适用，您有责任遵守它们。 </details> <details> <summary><b>当 agy 更新时会不会崩溃？</b></summary> 可能 — 它读取 agy 的 **内部、未文档化的** 状态文件，因此版本更新可能会更改路径或模式并静默破坏它。在 **1.0.10** 上重新验证（转录模式和 `-p` JSONL 输出未更改；实时提问往返 + `antigravity_status` 诊断通过）。已知的未来风险是 agy 的 **SQLite（`.db`）对话格式** （在 1.0.4 中添加，予定成为默认格式）：agy 1.0.10 仍然 **双写入** 每个对话到 `~/.gemini/antigravity-cli/conversations/<id>.db` 以及 JSONL 转录，因此一旦它停止写入 JSONL，读取器需要一个 SQLite 路径。如果您依赖此功能，请固定一个已知的 `agy` 版本。 </details> <details> <summary><b>为什么仅限 Gemini 3.5 Flash？</b></summary> agy 1.0.5 添加了一个 `--model` 标志，但在 `-p` 中切换到不同的模型会 **挂起** （打印模式等待一个步骤，但永远不会得到无头状态），因此实际上您获得的是 agy 的 `settings.json` 选择的模型 — 默认情况下为 Gemini 3.5 Flash（高速）。桥接器不公开模型旋钮，因为它在任何实际切换时都会挂起。 </details> <details> <summary><b>它能否生成图像？</b></summary> **是的 — 那就是 `antigravity_image` 工具**。agy 的打印模式在您的 AI Pro 配额上生成真正的图像；`antigravity_image` 驱动它，将文件保存到您选择的路径（或工作区中的时间戳默认路径），将扩展名固定为与实际字节匹配（agy 自行选择 JPEG 或 PNG），并返回路径。在 **agy 1.0.9 / Windows** 上验证。它是请求/响应的，并且运行一个正常的、无沙盒的 agy 会话（参见 [安全](#security)）。 </details> <details> <summary><b>是否会花费额外的钱？</b></summary> 不。它使用您已经付费的 **相同 AI Pro 配额**。冒烟测试花费的金额可忽略不计。 </details> <details> <summary><b>它会流式传输响应吗？</b></summary> 最终答案是请求/响应 — `agy -p` 一次返回所有内容，因此工具在 agy 完成后返回（每次调用通常需要 10–30 秒）。如果您想 **观察** agy 的工作过程，请将 **`watch=true`** 传递给 `antigravity_ask` / `antigravity_continue` / `antigravity_image`：它打开 **Agent Intern** 浏览器窗口，并实时流式传输从转录中读取的 agy 步骤 — 参见 [观察模式](#watch-mode)。它是粗粒度的（几个步骤，而不是按令牌），并且返回的值与非观察调用相同。 </details> <details> <summary><b>我可以同时运行多个调用吗？</b></summary> **单代理** 工具（`antigravity_ask` / `antigravity_continue` / `antigravity_image`）在服务器内 **序列化**：agy 在每次调用时都会重写 `last_conversations.json`，因此共享一个状态目录的并发运行会竞争并可能返回错误的结果。`threading.Lock` 使额外请求排队而不是竞争。 对于真正的并行性，请使用 **[`antigravity_swarm`](#swarm)** — 它在每个工作线程中运行在自己的隔离状态目录中，因此它们不会竞争，锁也不需要（在 3 个工作线程下约为 2.8 倍）。这是运行多个 agy 调用的一种支持的方式。 </details> ## 状态和注意事项 - ✅ **在 agy 1.0.10 上验证** — 基本目录、`last_conversations.json`、`brain/.../transcript.jsonl` 路径、转录模式和 `-p`/`-c`/`--print-timeout` 标志均未更改；实时提问往返 + `antigravity_status` 诊断通过。1.0.5 的 `-p` 元数据修复还意味着 agy 不再散布工作区目录。 - 🖥️ **控制台分离（新）** — agy `-p` 将其进度/答案写入 **控制终端**，而不是 stdout；在 TUI 下，该文本会泄漏到主机的提示中（在 1.0.9 上发现，在修复前）。桥接器现在在终端外启动 agy（`CREATE_NO_WINDOW` / 一个新的 POSIX 会话），因此它不会泄漏；答案仍然从转录中读取。 - ⏳ **SQLite 迁移是真正的风险** — agy 1.0.10 仍然为每个对话 **双写入** `.db`；参见 [FAQ](#faq)。如果 JSONL 转录消失，`_read_response` 会引发一个清晰的、与 SQLite 感知的错误。 - 🐛 **stdout 漏洞仍然存在** — `-p` 仍然不将答案打印到 stdout 在 1.0.9 上（1.0.9 的“打印模式恢复”更新日志修复 **未** 更改此功能以适用于新的 `-p`）。如果未来版本修复了 stdout，此变通方法变得冗余但无害。 - 👁️ **观察模式是实验性的** — 将 `watch=true` 传递给 `antigravity_ask` / `antigravity_continue` / `antigravity_image` 以打开 **Agent Intern** 浏览器窗口并实时观察 agy 的工作（粗粒度步骤；图像内联显示）。尽力而为，跨平台；参见 [观察模式](#watch-mode)。 - 🔒 **没有真正的沙盒** — agy 的 `--sandbox`（自 1.0.6 起）仅在 `-p` 中阻止 shell 命令，但仍然留下文件写入和网络出口开放（并且破坏转录读取），因此它不是边界；参见 [安全](#security)。 ## 要求 - Python 3.10+ - **对于 Antigravity 工具：** [`agy`](https://antigravity.google/) 1.0.0+ 在 `PATH` 上（在 **1.0.10** 上重新验证状态文件布局）和有效的 Antigravity / AI Pro 会话 - **对于 Codex 工具：** [`codex`](https://developers.openai.com/codex/) 在 `PATH` 上并登录（`codex login`）— 在 **codex-cli 0.141.0** 上验证 每个后端都是独立的 — 只安装您计划使用的 CLI（s）；其他工具只需通过其 `*_status` 工具报告“未找到”。 > [!TIP] > 如果 `agy` 不可靠地位于 `PATH` 上（例如，新终端或重启后在 Windows 上丢失），请设置 **`AGY_BIN`** 环境变量为其完整路径，桥接器将使用它而不是 `"agy"` — 例如，`AGY_BIN=%LOCALAPPDATA%\agy\bin\agy.exe`。同样，如果 `codex` 不可靠地位于 `PATH` 上，请设置 **`CODEX_BIN`**（原生 Windows 安装程序将其放在 `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\` 下）。 桥接器仅使用跨平台 Python（`Path.home()`、`subprocess`）读取 `~/.gemini/antigravity-cli/` 下的路径；`agy` 以相同的方式在每个 OS 上写入这些路径。**在 Windows 上开发和验证；macOS 和 Linux 应无修改地工作，前提是 `agy -i` 在那里运行。** 如果您在这些平台上测试它，请打开一个问题或 PR 来确认。 ## 开发 ```bash pip install -e ".[dev]" # fastmcp + pytest + ruff pytest test_server.py test_swarm.py # 离线单元测试 — 无 agy，无配额 ruff check . && ruff format --check . ``` `test_server.py` 和 `test_swarm.py` 涵盖纯解析/版本/群集逻辑与临时夹具（不需要 agy）；`test_smoke.py` 是实时端到端检查（提问、继续、图像和并行群集），花费少量配额。设置 **`AGY_BRIDGE_DEBUG=1`** 以将每次调用的诊断信息（解析的对话 ID、agy 退出代码、耗时）记录到 stderr — 启动时，如果已安装的 agy 版本比验证版本更新，服务器会警告。 **保持更新。** 更新是可选的：普通的 `uvx agent-intern` 固定在它第一次缓存的版本，并且 `git clone` 永远不会自动更新 — 因此桥接器只会运行您选择安装的代码（它运行无沙盒，因此这是故意的，而不是懒惰）。没有任何正在运行的服务器会更新；新版本仅在下一次 Claude Code 重启时生效。您可以通过两种方式了解发布信息，这两种方式都是尽力而为的 GitHub 标签检查： - **在聊天中 — [`antigravity_status`](#tools) 领先一行 `bridge version`，例如 `v0.10.3（最新）` 或 `v0.10.3 -> v0.10.4 可用；升级：uvx agent-intern@latest`。这是您在 MCP 客户端 UI 中实际看到的通知（可用更新保持 `[ok]` — 它是信息性的，不是故障）。 - **在启动时 — stderr**，其中服务器记录相同的单行警告。这仅在主机的 MCP 日志中（例如，通过 `/mcp` 在 Claude Code 中），而不是聊天中。 使用 `uvx agent-intern@latest`（或 `git pull`）升级并重启，或通过在配置中放入 `agent-intern@latest` 来选择加入自动更新。两个检查在离线或速率限制时都是沉默的，并且永远不会阻止启动。可以通过以下方式控制它们： | 环境变量 | 效果 | |---|---| | `AGY_BRIDGE_NO_UPDATE_CHECK=1` | 完全跳过 GitHub 检查（完全离线启动）。 | | `AGY_BRIDGE_REPO=owner/name` | 将检查指向一个分叉而不是上游存储库。 | **发布。** 在 **两个** `pyproject.toml` 和 `server.py` 中更新版本（`__version__`），更新 [`CHANGELOG.md`](CHANGELOG.md)，然后标记： ```bash git tag vX.Y.Z && git push origin vX.Y.Z ``` 标签触发两个工作流：`release.yml` 使用自动生成的注释创建 GitHub 发布，`publish.yml` 通过 [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) 构建并上传到 PyPI（无存储令牌 — `publish.yml` 在与 `pyproject.toml` 匹配之前验证标签）。一次性设置：在 `pypi.org/manage/project/agent-intern/settings/publishing/` 注册受信任的发布者（存储库 `SinanTufekci/agent-intern`，工作流 `publish.yml`，环境 `pypi`）。 ## 贡献 个人项目，**尽力维护** — 欢迎提出问题和 PR，但没有正常运行/兼容性承诺。如果 `agy -p` 曾经开始正确地将答案打印到 stdout，这个存储库就变成了一个有趣的历史文物。 ## 🌐 社区和致谢 - **Qiita（日本）：** 非常感谢 `@fallout` 和日本开发者社区的关注和提供宝贵的反馈！ - [详细混合设置指南（Claude Code × Antigravity CLI）](https://qiita.com/fallout/items/5097f0575b58f4c69b81) - [快速安装指南](https://qiita.com/fallout/items/d699df3d6931c07eb38d) > 💡 **路径解析修复：** 由于他们的社区现实世界的测试，我们发现并解决了 Windows 路径边缘情况，其中 MCP 服务器在启动时继承了一个 **陈旧的 `PATH`** 并且无法找到 `agy`。`AGY_BIN` 环境变量变通方法直接受到他们的报告启发！ ## 许可证 [MIT](LICENSE)。您想怎么处理它都行。