# research-bridge

`research-bridge` 是一个本地 MCP 服务，用于连接 MCP 客户端与本机 Codex。它可以读取目标 Git 仓库、启动和跟进任务、查看事件与代码差异，并记录研究任务的审查证据。

本仓库包含源码、测试和示例配置。运行时数据库、审计记录、验证产物及本地密钥不属于源码，已由 `.gitignore` 排除。

## 能做什么

| 功能 | 主要工具 |
| --- | --- |
| 检查仓库 | `bridge_health`、`repo_snapshot`、`repo_read`、`repo_search` |
| 执行任务 | `codex_start_task`、`codex_send_followup`、`codex_abort` |
| 查看进展 | `codex_status`、`codex_events`、`codex_diff`、`codex_artifacts` |
| 审计与验收 | `codex_record_audit_event`、`codex_audit`、`workstream_accept_candidate` |
| 研究治理 | `rva_review_contract`、`rva_review_result`、`rva_review_next_experiment`、`research_cycle_status` |
| 研究知识 | `research_publish_knowledge`、`research_knowledge_status`、`research_migration_scan` |

执行任务与研究任务采用不同流程。普通执行任务可按配置自动结算；研究任务需要提交研究契约、审查结果，并完成知识发布和后续实验决策。RVA（研究验证代理）只负责对研究结论提出有界质疑，不接管 Codex 的代码实现。

## 环境要求

- Node.js 22.5 或更高版本。
- Git，以及 pnpm（推荐）或 npm。
- 已安装并完成认证的本地 Codex。
- 如需启用 DeepSeek RVA，另需 DeepSeek API 密钥；普通执行任务无需该密钥。

## 安装与运行

在项目目录执行：

```sh
pnpm install
pnpm run build
pnpm test
```

编译后的 MCP STDIO 入口是 `dist/index.js`。在启动服务的环境中指定要操作的目标仓库：

```powershell
$env:RESEARCH_BRIDGE_REPO_ROOT = 'C:\path\to\target-repo'
$env:RESEARCH_BRIDGE_DATA_DIR = 'C:\path\to\bridge-data'
node .\dist\index.js
```

也可以将 Node.js 可执行文件及 `dist/index.js` 的绝对路径配置到支持 STDIO 的 MCP 客户端，并在该客户端的服务环境变量中设置上述路径。连接后先调用 `bridge_health`，再调用 `repo_snapshot` 检查目标仓库。

服务只将 MCP 协议消息写到标准输出；运行日志写到标准错误。服务会启动独立的后台 worker，因此 MCP 会话断开不等于取消已开始的任务。

## 配置

复制 [`.env.example`](.env.example) 查看完整配置项。默认值由 [`src/config.ts`](src/config.ts) 定义。常用设置如下：

| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `RESEARCH_BRIDGE_REPO_ROOT` | 当前工作目录 | Codex 操作的目标 Git 仓库 |
| `RESEARCH_BRIDGE_DATA_DIR` | `~/.research-bridge` | SQLite 状态库及研究知识数据 |
| `RESEARCH_BRIDGE_AUDIT_DIR` | 本项目的 `.agents/audit/bridge` | 审计日志目录 |
| `RESEARCH_BRIDGE_ALLOW_WORKSPACE_WRITE` | `0` | 是否允许任务请求写入工作区 |
| `RESEARCH_BRIDGE_ALLOW_NETWORK` | `0` | 是否允许任务请求网络访问 |
| `RESEARCH_BRIDGE_CODEX_MODEL` | `gpt-6-astra` | Codex 默认模型 |
| `RESEARCH_BRIDGE_ALLOWED_MODELS` | `gpt-6-astra` | 可由调用方选择的模型列表 |
| `RESEARCH_BRIDGE_WORKER_READ_CONCURRENCY` | `4` | 同一仓库并行只读任务数上限 |
| `RESEARCH_BRIDGE_RVA_PROVIDER` | `CLAUDE_CODE_LEGACY_V1` | RVA 提供方；也可选 `DEEPSEEK_NATIVE_V1` |
| `DEEPSEEK_API_KEY` | 无 | 使用 DeepSeek 时必需 |

`RESEARCH_BRIDGE_REPO_ROOT` 可以与本项目目录不同。任务状态和知识数据保存在 `RESEARCH_BRIDGE_DATA_DIR`，审计日志保存在 `RESEARCH_BRIDGE_AUDIT_DIR`，不会自动写入目标仓库。

需要原生 DeepSeek RVA 时，设置 `RESEARCH_BRIDGE_RVA_PROVIDER=DEEPSEEK_NATIVE_V1` 和 `DEEPSEEK_API_KEY`。支持通过 `RESEARCH_BRIDGE_RVA_DEEPSEEK_ENDPOINT`、`RESEARCH_BRIDGE_RVA_DEEPSEEK_MODEL` 等变量调整请求参数。旧版 Claude Code RVA 仍可通过默认提供方使用；如需指定命令位置，设置 `RESEARCH_BRIDGE_RVA_CLAUDE_PATH`。

密钥应放在进程环境或本地密钥管理器中。不要提交 `.env`、数据库、审计文件或运行日志。

## 典型任务流程

1. 用 `bridge_health` 确认配置，再用 `repo_snapshot` 检查目标分支和工作区状态。
2. 调用 `codex_start_task`，保存返回的任务 ID。
3. 使用 `codex_status` 和 `codex_events` 查看进展；需要纠正时调用 `codex_send_followup`。
4. 通过 `codex_diff` 和 `codex_artifacts` 检查改动及产物。
5. 对需要人工验收的任务，记录审查证据与最终裁决，再完成关闭流程。

研究任务还需要记录结果审查、调用 `research_publish_knowledge`（或明确说明无知识可发布），并作出后续实验决策。仅有 Codex 执行结束或文件存在，并不代表研究结论已经验收。

对于带 workstream 的任务，研究模式由审查者评审候选交接文件，再通过 `workstream_accept_candidate` 推进指针；可信执行模式由执行者按预先给定的下一任务决策推进。两种模式都要求校验任务、交接文件及 SHA-256 绑定。

## 本地数据与安全边界

- 任务默认只读，且不允许网络访问。写入工作区或联网需要调用方请求，并同时得到主机配置允许。
- MCP 客户端被视为可信调用方。服务没有针对任意本机进程的独立用户认证；不要把它作为公开 HTTP 服务暴露。
- `codex_diff` 返回目标仓库的整体差异，其中可能包含任务开始前已有的未提交改动。审查时应结合任务基线。
- 状态保存在 SQLite 中；审计事件另写入 `events.jsonl` 和可读的 `audit.md`。运行数据目录应由 bridge 管理。
- 文件读取、搜索和事件分页均有上限；仓库路径会进行边界检查。

## 可选功能

**知识图谱浏览器：**运行 `pnpm run knowledge:browser`，默认访问 `http://127.0.0.1:4317`。页面只读取本地知识快照，不提供修改接口；可用 `--data-root` 和 `--port` 指定数据目录与端口。

**ChatGPT 网页端连接：**可通过 OpenAI Secure MCP Tunnel 连接本地 STDIO 服务。项目提供 `pnpm run tunnel:init`、`pnpm run tunnel:doctor` 和 `pnpm run tunnel:start`，以及 Windows 启动器 `scripts/tunnel.cmd`。此方式用于受授权的个人组织或工作区；不要公开 tunnel 凭据。Tunnel 配置需要 `CONTROL_PLANE_API_KEY` 和 `RESEARCH_BRIDGE_TUNNEL_ID`。

**历史研究迁移：**`research_migration_scan` 只生成待确认候选，不会自动把历史材料写成权威结论。候选需通过 `research_migration_resolve` 明确确认或拒绝。

## 开发

```sh
pnpm run check
pnpm test
pnpm run build
```

源码在 `src/`，测试在 `tests/`，MCP 输入输出契约见 `schemas/`。修改服务代码后，需要重新构建并重启 MCP 服务和 worker，运行中的进程不会自动加载新版本。

## 许可证

本项目使用 [MIT 许可证](LICENSE)。