内容
**免责声明：AI 生成内容，可能未经代码审查**
# ACP 转 MCP 桥接器
将任何兼容 [ACP](https://agentclientprotocol.com) 的代理包装成 [MCP](https://modelcontextprotocol.io) 服务器。一个带有昂贵模型的协调器通过 MCP 工具调用将任务委托给一个更便宜的子代理。
```
协调器（Claude Code / Copilot） ──MCP──▶ 桥接器 ──ACP──▶ 子代理（OpenCode）
```
## 快速开始
无需安装 — 直接使用 `npx` 运行：
```bash
npx acp-mcp-bridge \
--model coder:openrouter/openai/gpt-4o-mini \
--model reviewer:openrouter/deepseek/deepseek-v3.2
```
或者从源代码编译：
```bash
git clone ... && cd acp-mcp-bridge
npm install && npm run build
node dist/index.js --model coder:openrouter/openai/gpt-4o-mini
```
## MCP 配置示例
### Copilot
在 `~/.copilot/_user/mcps/acp.json` 中添加：
```json
{
"mcpServers": {
"acp-bridge": {
"tools": ["*"],
"type": "stdio",
"command": "npx",
"args": [
"-y", "acp-mcp-bridge",
"--model", "coder:openrouter/openai/gpt-4o-mini",
"--model", "reviewer:openrouter/deepseek/deepseek-v3.2"
]
}
}
}
```
### Claude Code
在项目根目录的 `.mcp.json` 中添加：
```json
{
"mcpServers": {
"acp-bridge": {
"command": "npx",
"args": [
"-y", "acp-mcp-bridge",
"--model", "coder:openrouter/openai/gpt-4o-mini",
"--model", "reviewer:openrouter/deepseek/deepseek-v3.2"
]
}
}
}
```
### 在本地运行 OpenCode
如果 OpenCode 已经配置了提供商，请使用不带前缀的裸模型 ID：
```bash
npx acp-mcp-bridge --model fast:gpt-5-nano --model smart:claude-sonnet-4-20250514
```
启动后，使用 `agent_list_models` 工具检查可用模型。
## MCP 工具
| 工具 | 描述 |
|---|---|
| `agent_prompt` | 一次性提示 — 每个调用完整的生命周期，无状态保留 |
| `agent_session_new` | 创建持久会话 + 发送初始提示 |
| `agent_session_prompt` | 在现有会话中继续对话 |
| `agent_session_cancel` | 取消正在进行的提示 |
| `agent_session_close` | 关闭会话（保留输出文件） |
| `agent_session_list` | 列出当前工作空间中的会话 |
| `agent_session_load` | 恢复以前的会话 |
| `agent_session_fork` | 分叉现有会话（如果代理支持） |
| `agent_session_delete` | 永久删除会话 + 输出文件 |
| `agent_list_models` | 列出带有别名的可用模型 |
## 模型别名
`--model` 标志定义了**别名**和**允许列表条目**：
```bash
--model coder:openrouter/openai/gpt-4o-mini # 别名：模型 ID
--model reviewer:openrouter/deepseek/deepseek-v3.2
--model bare-model-id # 无别名，仅允许列表
```
- `agent_list_models` 报告别名，而不是原始模型 ID
- 所有提示工具都接受别名作为 `model` 参数
- 如果未提供 `--model` 标志，则所有代理模型都可用，无需过滤
- 每个 `--model` 标志都作为允许列表 — 未列出的模型不可访问
## 输出文件
子代理响应写入 `.acp-as-mcp/outputs/`（不内联返回，以避免上下文膨胀）。MCP 工具响应包括路径和摘要 — 协调器在需要完整输出时读取文件。
| 调用 | 输出文件 |
|---|---|
| `agent_prompt` | `outputs/oneshot-{timestamp}.md` |
| `agent_session_new` / `agent_session_prompt` | `outputs/{sessionId}-turn-{N}.md` |
一次性文件：保留最近 10 个。会话输出：与会话一起删除。
会话：自动修剪到最近 20 个。日志：`.acp-as-mcp/logs/`，也是最近 20 个。
## 烟雾测试
```bash
npm run build && node scripts/smoke-test.mjs
```
测试 MCP 连接、所有 9+ 工具、顺序一次性提示、会话创建/继续/列出/关闭。
## 规格
完整设计文档：[docs/spec.md](docs/spec.md)。
上游 ACP 协议文档：[docs/upstream/acp/](docs/upstream/acp/).
