# Codex ↔ Antigravity AgentBridge 中文分发包

**换一个 Agent，不必再从头解释。**

[English](README.en.md) · [中文快速开始](QUICKSTART.md) · [安装与验证](#安装与验证) · [能力与状态](#能力与状态) · [技术文档](#技术文档)

你在 Codex 里查过的代码、确定的方案、踩过的坑，切到 Antigravity 后往往还要再讲一遍。AgentBridge 为同一用户本机的两个工具提供一个可追溯的上下文层：查回用户可见的历史，保存已确认的结论，在权限允许时继续工作。

仓库包含可安装 Skill、Python MCP 服务、合成测试和脱敏工程记录。它是个人项目，与 OpenAI 或 Google 没有官方隶属关系。

这个中文分发包在保留原有 Skill、引擎、参考文档和测试的基础上，增加了面向新手的安装脚本、隔离引导、只读诊断、配置模板和安全说明。它不会自动覆盖你的客户端配置，也不会把本机凭证或聊天数据带进仓库。

## 你可以用它做什么

部署并验证 MCP 后，可以这样向 Agent 提问：

```text
查一下我之前在 Antigravity 里对这个项目做过哪些决定，给出来源。
```

```text
把这次确认的非敏感结论保存到共享记忆，方便另一个 Agent 接着做。
```

历史检索保留来源，并在源数据提供时保留时间信息；记忆可以附带证据、项目和适用范围。接手工作时，Agent 可以核对原始讨论，不必只依赖一段手工转述。

## 能力与状态

| 能力 | 实现与证据 | 使用边界 |
| --- | --- | --- |
| 历史互读 | 两端用户可见正文的读取、搜索和来源追踪 | 未知格式与附件不承诺完整覆盖 |
| 共享记忆 | 已确认结论的写入、查询与版本更新 | 历史和记忆都不授予新的执行权限 |
| 增量同步 | SQLite/FTS 索引、同步水位和单实例锁 | 运行数据存本地私有目录，避免放在 SMB/NAS |
| 凭证使用 | 固定 profile、1Password 人工审批、非生产 canary | 没有预置业务凭证，也不支持任意密码自动互通 |
| 双向任务接力 | 开发机完成过受控原桌面双向 canary | 发送默认关闭；通用空闲唤醒和无人值守派单未完成 |

**历史互读、共享记忆与受控接力各有验证证据；完整的无人值守桌面代理仍在范围之外。** `native_completed` 只表示接收端声明完成，业务结果还要独立核验。

完整历史证据和未完成项见 [验收与限制](skills/codex-antigravity-bridge/references/acceptance.md)。

## 安装与验证

要求：macOS、Python 3.11+、SQLite FTS5。依赖版本记录在 `requirements.txt` 和 `requirements-dev.txt`；其他系统和桌面版本需要单独验收。

### 1. 获取代码并运行隔离测试

```sh
git clone https://github.com/yuanyuanyuan430/codex-antigravity-bridge-cn.git
cd codex-antigravity-bridge-cn
python3 scripts/doctor.py
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pytest -q
.venv/bin/python skills/codex-antigravity-bridge/scripts/engine/verify_mcp.py
```

默认测试使用临时目录与合成数据，不读取真实聊天、不调用 1Password。协议自测成功应返回 `ok: true`、`mode: isolated_synthetic`，两个客户端身份各发现 17 个工具。

本次文档更新复验（2026-09-12）：**159 项测试通过；隔离 MCP 自测通过。** 这些结果不证明你的桌面已配置完成。

### 2. 安装 Skill

在仓库根目录执行。脚本使用默认 Codex 用户目录，并在目标已存在时停止而不覆盖：

```sh
scripts/install_skill.sh
```

如果你设置了自定义 `CODEX_HOME`，相应调整目标路径：

```sh
CODEX_HOME=/path/to/.codex scripts/install_skill.sh
```

此步骤安装指南和代码；真实 MCP、同步服务与权限配置还需单独完成。

在新 Codex 任务中使用：

```text
使用 $codex-antigravity-bridge 检查本机的桥接环境，列出部署前需要补齐的条件。
```

已有任务是否发现新 Skill，以实际运行时扫描为准。

### 3. 连接两端 MCP

先看 [`config/README.md`](config/README.md) 和模板，再按 [部署与回滚](skills/codex-antigravity-bridge/references/deployment.md) 手动合并。两端连接同一私有数据目录，分别使用 `--client codex` 和 `--client antigravity`。修改配置前保留备份，只增改自己的 `agent_bridge` 条目。

配置完成后，先实际调用 `bridge_status`，检查覆盖范围和同步状态，再按授权范围同步。双向派单需要额外的固定目标配置与单独验收，默认安装不会开启。

## 工具与架构

| 用途 | 主要 MCP 工具 |
| --- | --- |
| 状态与历史 | `bridge_status`、`bridge_list_conversations`、`bridge_search`、`bridge_read` |
| 共享记忆 | `bridge_remember`、`bridge_list_memories` |
| 凭证状态与使用 | `bridge_credential_status`、`bridge_credential_profiles`、`bridge_use_credential` |
| 任务实验 | `bridge_capabilities`、`bridge_send_task`、`bridge_task_status`、`bridge_list_tasks`、`bridge_claim_native_task`、`bridge_complete_native_task`、`bridge_cancel_task`、`bridge_pause_tasks` |

```text
Codex / Antigravity
        │ MCP stdio（各自的 client 身份）
        ▼
  AgentBridge 服务
        ├── 历史适配器与增量同步
        ├── 本地 SQLite/FTS 与共享记忆
        ├── 固定凭证 profile 与审批
        └── 受限任务收件箱与接力实验
```

安装入口是 [`SKILL.md`](skills/codex-antigravity-bridge/SKILL.md)，实现与测试位于 [`scripts/engine/`](skills/codex-antigravity-bridge/scripts/engine/)。`mcp_call.py` 仅是连接同配置 MCP 服务的协议 helper，不是新的 CLI Agent，也不证明原桌面已热加载工具。

## 隐私与权限

只索引能证明确为用户可见的 user/assistant 正文，排除隐藏推理、系统指令、工具内部记录和附件二进制。源聊天数据库保持只读；任务接力保留原授权、审批、允许路径、幂等和所有权限制。

凭证通过固定 profile 与人工审批使用，不进入聊天、参数或共享库。脱敏是启发式的，不能保证识别任意密码；本地保存也不代表历史被返回给 Agent 后不会进入云模型上下文。

仓库不包含真实聊天、数据库、凭证 profile 或机器运行状态。实验不绕过 ACL、审批、MCP 拒绝或维护门禁，也不用 CLI `resume`/`clone` 冒充原桌面。任务状态含义和安全停止规则见技术文档。

## 技术文档

| 文档 | 内容 |
| --- | --- |
| [需求与边界](skills/codex-antigravity-bridge/references/requirements.md) | 原始目标、权限解释和验收条件 |
| [架构与数据流](skills/codex-antigravity-bridge/references/architecture.md) | 适配器、同步、索引、任务和凭证设计 |
| [部署与回滚](skills/codex-antigravity-bridge/references/deployment.md) | 最小配置、后台服务、维护和卸载 |
| [验收与限制](skills/codex-antigravity-bridge/references/acceptance.md) | 合成测试、开发机证据与剩余缺口 |
| [双向派单实验](skills/codex-antigravity-bridge/references/dispatch-experiment.md) | 固定目标、任务接力与停止规则 |
| [隐私与排障](skills/codex-antigravity-bridge/references/privacy-troubleshooting.md) | 隐私边界、失败恢复和发布检查 |
| [完整工程过程](skills/codex-antigravity-bridge/references/engineering-journal.md) | 探索过程、失败路径与后续工作 |

应用内部格式的适配依赖版本。一次开发机验收不会自动适用于另一台机器、更新后的客户端或所有既有任务。