内容
# 代理交叉点
[](https://www.npmjs.com/package/agent-crossbar)
[](https://pypi.org/project/agent-crossbar/)
将审查、建议、文本和开发工作委托给本地编码代理 — Codex、Claude、OpenCode — 通过单个 MCP 服务器。一次 `agent_start` 调用，一次 `job_result` 回答。
**实验性开发者预览（v0.3）。** API 可能会更改。提供商保证因实时门户而合格。
通过服务器密钥 `agents` 向 MCP 客户端公开。
## 十分钟快速入门
### 1. 安装
```bash
# 标准：uvx 拉取最新的 PyPI 版本
uvx agent-crossbar
# 或通过 npm（薄启动器 → 委托给 uvx）
npx agent-crossbar
```
先决条件：uv 适用于两种启动路径，因为 npm 包只是 `uvx` 的薄启动器；从 [uv 文档](https://docs.astral.sh/uv/getting-started/installation/) 安装它。
npm 路径还需要 [Node.js](https://nodejs.org/) ≥ 20。
### 2. 检查就绪状态（doctor）
```bash
uvx agent-crossbar doctor
# 可选：检查一个提供商并发出机器可读输出
uvx agent-crossbar doctor --profile codex --json
```
验证支持的提供商 CLI 是否已安装、已身份验证并且可运行。提供商必须 `ready` 才能创建作业。
### 3. 配置您的 MCP 客户端
#### Codex
对于 Codex 应用程序、CLI 和 IDE 扩展共用的用户范围安装：
```bash
codex mcp add agents -- uvx agent-crossbar
codex mcp list
```
这会将 Codex MCP 原生配置写入 `~/.codex/config.toml`。
等效的显式 TOML 是：
```toml
[mcp_servers.agents]
command = "uvx"
args = ["agent-crossbar"]
```
对于仅限信任项目的安装，请在存储库中将相同的 TOML 表放入 `.codex/config.toml`。
Codex 不使用 Claude Code 的 `.mcp.json` 格式。
#### Claude Code
Claude Code 使用原生 `claude_bg` 后端（`claude` 配置文件）。交互式跟进会附加一个 harness-owned 终端到同一个后台会话；打印模式保持禁用，因为 `claude -p` 使用单独的 Agent SDK 计费/计量计费 — 请参见下面的 [Claude 计费](#claude-subscription-vs-print-sdk-billing)。
对于用户范围安装：
```bash
claude mcp add --scope user agents -- uvx agent-crossbar
claude mcp get agents
```
使用 `--scope project` 代替，创建可共享的项目根 `.mcp.json`，
或省略 `--scope` 以使用 Claude Code 的私有本地项目范围。
**Claude 先决条件**：使用 `claude auth login` 进行身份验证。医生将报告 `needs_auth`，直到您这样做。
#### OpenCode
将以下内容添加到全局 `~/.config/opencode/opencode.json` 或项目根 `opencode.json`：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"agents": {
"type": "local",
"command": ["uvx", "agent-crossbar"],
"enabled": true
}
}
}
```
然后使用 `opencode mcp list` 验证它。
### 4. 第一个审查流程
MCP 服务器运行后，从任何 MCP 客户端：
```
1. profiles_list → 查看可用配置文件及其层级
2. profile_health → 在创建作业之前验证就绪状态
3. agent_start(
profile="codex",
model="gpt-5.6-sol",
prompt="Review my uncommitted changes for security issues.",
task="review"
) → 创建审查作业
4. job_tail(job_id="<id>") → 流式传输实时输出
5. job_result(job_id="<id>") → 获取最终结构化结果
```
## 工具（8）
| # | 工具 | 描述 |
|---|------|-------------|
| 1 | `agent_start` | 启动一个代理任务（询问、审查或开发）只需一次调用 |
| 2 | `profiles_list` | 列出可用的代理配置文件及其支持层级和功能 |
| 3 | `profile_health` | 为所有已配置的配置文件运行实时就绪探测 |
| 4 | `job_tail` | 按序列号流式传输增量作业输出 |
| 5 | `job_result` | 获取最终结构化结果、退出代码和摘要 |
| 6 | `job_send` | 向正在运行的交互式作业发送后续输入（不适用于 Claude bg） |
| 7 | `job_stop` | 停止正在运行的作业 |
| 8 | `job_list` | 列出当前客户端会话范围内的作业 |
**确切的 8 种工具 MCP 接口。** 没有隐藏的工具，也没有废弃的别名。
### 会话隔离
默认情况下，所有作业访问工具（`job_tail`、`job_result`、`job_stop`、
`job_send`、`job_list`）都限定在请求的 `client_session_id`。
客户端会话只能看到并操作自己的作业；外部作业
返回 `"error": "job_not_found"` 以及 `cross_session_note` 提示：
```json
{
"ok": false,
"error": "job_not_found",
"cross_session_note": "pass client_session_id=\"*\" for explicit local cross-session access"
}
```
#### 显式本地跨会话访问
将 `client_session_id="*"` 传递给 `job_tail`、`job_result`、`job_stop`、
`job_send` 或 `job_list`，以实现显式本地跨会话访问。
这允许任何本地客户端查看和操作所有作业，而无需环境变量或令牌设置 —
`"*"` 是字面上的选择字符串。
## 支持矩阵
### 支持的配置文件
| 配置文件 | 任务 | 后端 | 操作系统 | 模型选择 |
|---------|-------|---------|-----|-----------------|
| `codex` | 询问、审查、开发 | ACP 一次性（包括显式努力） | macOS、Linux | 每次调用都需要 |
| `claude` | 询问、审查、开发 | 原生 `claude_bg`；交互式跟进通过 `job_send`（无 `claude -p`） | macOS、Linux | 每次调用都需要 |
| `opencode` | 询问、审查、开发 | ACP 一次性（包括显式努力） | macOS、Linux | 每次调用都需要 |
`model` 是每个 `agent_start` 请求的必需参数。代理交叉点永远不会选择或回退到默认模型。
使用 `profiles_list` 在启动作业之前检查当前可用的模型 ID。
### 实验性（已安装，但未保证）
| 配置文件 | 任务 | 交互式 | 备注 |
|---------|-------|-------------|-------|
| `reasonix` | 询问、审查、开发 | 两者 | 支持非交互式和交互式模式；结果使用启发式 TUI 解析 |
| `chatgpt_pro` | 询问、审查 | false | 实验性 macOS GUI 适配器；需要手动签入 ChatGPT 应用/浏览器门户 |
### 提供商先决条件
| 提供商 | 二进制 | 身份验证检查 |
|----------|--------|-----------|
| Codex | `codex` CLI + `pnpm` | `codex login status` |
| Claude | `claude` CLI | `claude auth status --json` |
| OpenCode | `opencode` CLI | `opencode auth list` |
| Reasonix | `reasonix` CLI | `reasonix doctor --json` |
## Claude 订阅 vs 打印 SDK 计费
代理交叉点使用 Claude 的原生 `claude --bg` 订阅路径。这使用您普通的 Claude 计划 — 没有单独的 API 计费。
- `claude -p`（打印/SDK 模式）已**禁用** — 它使用单独的 Agent SDK 计量计费
- 使用 `interactive: true`，代理交叉点打开一个 harness-owned `claude attach <session-id>` tmux 会话；`job_send` 将下一个回合写入同一个原生会话
- 配置文件 `claude` 映射到 `claude_bg` 以进行一次性调用，内部映射到 `claude_bg_pty` 以进行附加式交互式调用
- 在作业创建之前，通过 `claude auth status --json` 验证就绪状态
## 超时
| 层 | 默认值 | 备注 |
|-------|---------|-------|
| 外部 MCP 读取超时 | 客户端依赖 | 在您的 MCP 客户端中设置。客户端超时不会**取消**持久的后台作业 — 它继续执行，结果仍然可以通过 `job_tail`/`job_result` 获取。 |
| 内部预检探针 | 配置文件依赖 | 顺序只读检查单独有界：最多 35 秒用于 Codex，25 秒用于 OpenCode，15 秒用于 Claude，30 秒用于 Reasonix。结果缓存 60 秒。失败阻止作业创建。 |
| ACP 启动和模型选择 | 30 秒 | `initialize`、`session/new` 和显式模型选择分别有界。提供商配额/速率限制诊断立即终止作业。 |
| `max_runtime_sec`（`agent_start`） | 1800 秒（30 分钟） | 服务器端作业截止日期，每个作业可配置。当超过时，作业以终端 `timeout` 结果终止。 |
| `job_tail` / `job_result` | — | 初始 `agent_start` 响应后随时可用。结果轮询不强制执行截止日期。 |
`doctor` CLI 仅报告就绪性和预检失败。它**不**报告活动作业超时或正在运行的作业状态。
## 本地状态和保留
- **状态目录**：`~/.local/state/agent-crossbar`（使用 `AGENT_CROSSBAR_STATE_DIR` 覆盖）
- **作业存储**：`jobs/` 下每个作业一个目录
- **保留**：v0.3 中没有自动清理 — 作业持续存在，直到手动删除 — 作业持续存在，直到手动删除
- **本地审计日志**：完整的 MCP 请求和响应有效载荷，包括提示和结果，都写入 `telemetry/`，具有所有者权限。
它们遵循相同的无清理策略，适用于 v0.3。
- **无远程遥测**：这些审计日志不会远程发送；代理交叉点不会联网。
## 通过错误代码进行故障排除
| 错误代码 | 含义 | 操作 |
|-----------|---------|--------|
| `codex_missing` | Codex CLI 不在 PATH 上 | 安装 Codex CLI |
| `codex_not_authenticated` | 未登录 Codex | 运行 `codex login` |
| `pnpm_missing` | pnpm 未安装 | 安装 pnpm（https://pnpm.io/installation） |
| `claude_missing` | Claude CLI 不在 PATH 上 | 安装 Claude Code |
| `not_authenticated` | Claude 未登录 | 运行 `claude auth login` |
| `opencode_missing` | OpenCode CLI 不在 PATH 上 | 安装 OpenCode CLI |
| `reasonix_missing` | Reasonix CLI 不在 PATH 上 | 安装 Reasonix CLI |
| `unsupported_os` | 提供商需要不同的操作系统 | 使用支持的操作系统或不同的提供商 |
| `chatgpt_pro_manual_gate` | ChatGPT Pro 需要手动设置 | 启动 ChatGPT 桌面应用程序并登录 |
| `missing_model` | `agent_start` 省略或传递空 `model` | 调用 `profiles_list`，选择模型并显式传递 |
| `provider_limit_exhausted` | 提供商配额、积分或速率限制已耗尽 | 等待重置或选择另一个显式可用的模型 |
| `provider_unavailable` | 当前没有可用的后端用于选定的模型 | 选择另一个模型或在提供商恢复后重试 |
| `acp_launch_error` | ACP 代理进程无法启动（二进制丢失，依赖错误） | 检查提供商 CLI 安装，运行 `agent-crossbar doctor` |
| `acp_protocol_error` | ACP 协议握手或消息错误（版本不匹配，请求无效） | 检查提供商和协议日志；提供商 CLI 可能需要升级 |
| `acp_timeout` | ACP 作业在等待已交付提示的响应时超过 `max_runtime_sec` | 遵循 `failure.next_action`：通常增加 `max_runtime_sec`；对于 OpenCode，`check_provider_limits_or_retry_with_free_model` |
| `acp_prompt_delivery_timeout` | ACP 启动未在调度提示之前完成 | 检查提供商可用性、配额、CLI 安装和选定的模型 |
`job_stop` 是幂等的。ACP 作业即使在提供商进程已经退出后仍然保留终端结果；运行的 ACP 子进程在必要时接收 SIGTERM，然后在有界的宽限期内接收 SIGKILL。
稳定的错误代码在补丁版本之间得到保证。作业结果中的 `next_action` 字段提供了确切的补救措施。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AGENT_CROSSBAR_STATE_DIR` | `~/.local/state/agent-crossbar` | 状态根目录 |
| `AGENT_CROSSBAR_CLIENT_NAME` | `agent-crossbar` | 遥测中的客户端名称 |
| `AGENT_CROSSBAR_CLIENT_VERSION` | `unknown` | 记录在本地审计日志中的可选客户端版本 |
| `AGENT_CROSSBAR_DEFAULT_CWD` | `PWD` | 开发作业的默认工作目录 |
**迁移说明**：旧的 `AGENT_HARNESS_*` 环境变量名称仍然有效，但会发出 `FutureWarning`。请将它们重命名为 `AGENT_CROSSBAR_*`。兼容性补丁将在 v0.4.0 中删除。
## 架构
```
MCP 客户端（Codex / Claude / OpenCode）
│
▼
FastMCP（“agents”）← 8 种工具 MCP 接口
│
┌────┼────┐
▼ ▼ ▼
Codex Claude OpenCode ← 提供商适配器
│ │ │
▼ ▼ ▼
ACP / claude_bg / tmux / GUI ← 提供商后端
```
单个 Python 包（PyPI 上的 `agent-crossbar`）。`agent_crossbar.adapters` 下有界定的提供商适配器。v0.3 中没有单独的插件包。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。贡献者的快速规则参见 [AGENTS.md](AGENTS.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
