内容
# 代理本地 ACP 桥接器
[中文文档](README.zh-CN.md)
这是一个非官方的 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 适配器，用于 Cursor 代理本地。它允许 ACP 客户端（如 JetBrains IDE）连接到 Cursor 的本地编码代理，同时代理本地向您配置的兼容 OpenAI 的提供商发送模型请求。
```text
ACP 客户端
| ACP 通过 stdio
v
agent-local-acp-桥接器
| agent-local --print --output-format stream-json
v
Cursor 代理本地 -----> 兼容 OpenAI 的提供商
```
本项目与 Cursor、Anysphere、xAI 或任何模型提供商无关。
## 本桥接器功能
Cursor 代理本地可以通过 `agent-local --print` 运行，并发出机器可读的 `stream-json` 事件。本桥接器：
1. 为 JetBrains IDE 等客户端实现 ACP 服务器。
2. 在后台启动 `agent-local --print --output-format stream-json`。
3. 将代理本地事件映射到 ACP 消息、工具调用、状态更新和使用数据。
这样可以避免在使用某些自带密钥（BYOK）或无身份验证设置的本地环境中，`agent-local acp` 启动失败的问题，同时保持代理本地的上下文、工具执行和图像输入行为。
## `agent-local` 与常规 Cursor CLI
这两者容易混淆：
| 命令 | 来源 | 主要用途 | 本项目使用 |
| --- | --- | --- | --- |
| `agent` | 公共 Cursor CLI，显示在 Cursor 的 CLI 页面上 | 终端 Cursor 代理和自动化脚本 | 否 |
| `agent-local` / `cursor-agent-local` | Cursor 代理本地包 | 本地代理本地入口点，带有 `--print`、`stream-json`、`--image` 和相关标志 | 是 |
仅安装常规 Cursor CLI 可能不会安装 `agent-local`。本桥接器依赖于 `agent-local`，因为它发出 `stream-json` 事件，而桥接器会解析这些事件。
## 功能特点
- 使用官方 ACP TypeScript SDK 实现 ACP stdio 服务器。
- 兼容 OpenAI 的提供商基准 URL、API 密钥和任意模型 ID。
- Cursor 无身份验证 BYOK 模式，可选使用现有的 Cursor 登录。
- 流式传输助手文本、推理块、工具调用、后台任务状态和令牌使用情况。
- 会话创建、加载、恢复、列出、关闭、删除和元数据持久性。
- 用于代码、计划和询问工作流的 ACP 模式。
- 模型的运行时 ACP 配置、无身份验证模式和强制模式。
- 支持文本、图像、资源链接和嵌入资源的提示内容。
- 处理内联 ACP 图像、嵌入式图像资源、`file://` 本地路径图像链接和 Markdown 文本中嵌入的图像链接。
- ACP 提供的 stdio、HTTP 和 SSE MCP 服务器转换为每个回合的临时 Cursor 插件。
- 输出清理，去除重复的部分消息、原始 `<think>` 块和嘈杂的连接状态事件。
- Windows 安全进程启动，无需通过 `cmd.exe` 插入提示。
## 快速入门
按照以下步骤进行。
### 1. 安装 Node.js
需要 Node.js 20 或更高版本：
```bash
node --version
npm --version
```
### 2. 安装代理本地
此桥接器需要 `agent-local` 命令。
Windows PowerShell:
```powershell
irm 'https://cursor.com/internal-local-install-nHZIc6RZgTXIfai0aO?win32=true&channel=prod' | iex
```
macOS / Linux:
```bash
curl -fsSL 'https://cursor.com/internal-local-install-nHZIc6RZgTXIfai0aO?darwin=true&channel=prod' | bash
```
注意：
- 在 Windows 上，安装程序安装 `cursor-agent-local` 并创建 `agent-local.exe`、`agent-local.cmd` 和 `agent-local.ps1` 别名。
- 在 Windows 上，默认安装目录为 `%LOCALAPPDATA%\cursor-agent-local`，安装程序尝试将其添加到用户 `PATH` 中。
- 在 macOS/Linux 上，安装程序使用 `~/.local/share/cursor-agent-local` 并在 `~/.local/bin` 中创建 `agent-local` 和 `cursor-agent-local` 符号链接。
- 如果新终端无法找到 `agent-local`，请将相关目录添加到 `PATH` 中或重启终端。
- 这些命令执行远程安装脚本。如果您的环境需要更严格的控制，请在运行前下载并检查脚本。
验证命令是否可用：
```bash
agent-local --help
```
### 3. 验证代理本地可以访问您的提供商
这验证了代理本地和您的模型提供商，而不是桥接器。
Windows PowerShell:
```powershell
$env:CURSOR_LOCAL_AGENT_BASE_URL = "https://api.example.com/v1"
$env:CURSOR_LOCAL_AGENT_API_KEY = "your-provider-key"
agent-local --authless --model "grok-4.5" --print "Only reply OK"
```
如果此操作失败，请先修复代理本地、基准 URL、API 密钥或模型 ID。然后桥接器不会重写提供商的 HTTP 行为，无法使不支持的提供商兼容。
### 4. 构建桥接器
```bash
git clone <repository-url>
cd agent-local-acp-bridge
npm ci
npm run build
```
`dist/cli.js` 是 ACP 客户端启动的入口点。在更改 TypeScript 源文件后，请重新运行 `npm run build`。
### 5. 可选的桥接器自我检查
```bash
node dist/cli.js --doctor --model "grok-4.5" --authless
```
`--doctor` 有助于捕获本地设置错误：
- `dist/cli.js` 是否启动；
- CLI 参数是否正确解析；
- `agent-local` 是否可解析；
- 提供的 `--base-url` 是否在语法上有效；
- 选定的模型、无身份验证标志、状态目录、临时目录和 API 密钥存在情况是否符合预期。
它不会调用模型提供商、消耗令牌、验证 API 密钥或证明模型 ID 受支持。请将其视为推荐的本地健全性检查，而不是必需的模型测试。
### 6. 配置您的 ACP 客户端
JetBrains 自定义 ACP 代理示例：
```json
{
"Cursor 代理本地": {
"command": "node",
"args": [
"C:\\path\\to\\agent-local-acp-bridge\\dist\\cli.js",
"--model",
"grok-4.5",
"--authless"
],
"env": {
"CURSOR_LOCAL_AGENT_BASE_URL": "https://api.example.com/v1",
"CURSOR_LOCAL_AGENT_API_KEY": "REPLACE_WITH_YOUR_KEY",
"AGENT_LOCAL_MODELS": "grok-4.5"
}
}
}
```
在 macOS/Linux 上，请将脚本路径替换为 POSIX 路径，例如 `/path/to/agent-local-acp-bridge/dist/cli.js`。
一个现成的示例位于 [`examples/jetbrains.openai-compatible.json`](examples/jetbrains.openai-compatible.json) 中。请将实际的 API 密钥保存在 ACP 客户端的环境映射或秘密管理器中。不要提交凭证。
## Cursor 登录模式
模型提供商和 Cursor 登录是独立的设置：
| 设置 | 行为 |
| --- | --- |
| `AGENT_LOCAL_AUTHLESS=true` | 不使用 Cursor 账户支持的会话服务。建议纯 BYOK。 |
| `AGENT_LOCAL_AUTHLESS=false` | 允许现有的代理本地/Cursor 登录提供辅助服务。提供商变量仍由代理本地继承。 |
在启动 ACP 进程之前，通过交互方式完成任何 Cursor 登录。桥接器故意不收集或代理 Cursor 凭证。
## 常见配置
环境变量是首选的配置机制。CLI 标志覆盖相应的环境值。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `CURSOR_LOCAL_AGENT_BASE_URL` | 代理本地默认值 | 兼容 OpenAI 的 `/v1` 基准 URL。 |
| `CURSOR_LOCAL_AGENT_API_KEY` | 未设置 | 提供商 API 密钥。 |
| `AGENT_LOCAL_COMMAND` | `agent-local` | 可执行文件名称或绝对 `agent-local.ps1` 路径。 |
| `AGENT_LOCAL_MODEL` | `gpt-5.5` | 默认模型 ID。 |
| `AGENT_LOCAL_MODELS` | 默认模型 | ACP 中显示的逗号分隔模型 ID。 |
| `AGENT_LOCAL_AUTHLESS` | `true` | 添加 `--authless`。 |
| `AGENT_LOCAL_FORCE` | `false` | 为非交互式工具执行添加 `--force`。 |
| `AGENT_LOCAL_TRUST` | `true` | 添加 `--trust` 以避免工作区信任提示。 |
| `AGENT_LOCAL_APPROVE_MCPS` | `true` | 为客户端 MCP 服务器添加 `--approve-mcps`。 |
| `AGENT_LOCAL_SINGLE_TURN` | `false` | 添加 `--single-turn`。 |
| `AGENT_LOCAL_STREAM_PARTIAL_OUTPUT` | `true` | 流式传输令牌级输出并删除聚合重复项。 |
| `AGENT_LOCAL_DISABLE_AUTO_UPDATE` | `true` | 保持 ACP 启动的二进制文件稳定。 |
| `AGENT_LOCAL_SANDBOX` | 未设置 | `enabled` 或 `disabled`。 |
| `AGENT_LOCAL_BRIDGE_STATE_DIR` | `~/.agent-local-acp-bridge` | 会话元数据目录。 |
| `AGENT_LOCAL_BRIDGE_TEMP_DIR` | 操作系统临时目录 | 临时图像和 MCP 插件目录。 |
| `AGENT_LOCAL_BRIDGE_LOG_LEVEL` | `info` | `silent`、`error`、`warn`、`info` 或 `debug`。 |
| `AGENT_LOCAL_MAX_STDERR_BYTES` | `131072` | 每个代理本地运行保留的最大 stderr。 |
运行 `node dist/cli.js --help` 获取所有标志。
## 权限模型
代理本地的 `stream-json` 打印接口可以发出交互查询事件，但它不公开支持的输入通道，以便将 ACP 权限响应反馈到正在运行的回合中。因此，桥接器无法为各个 Cursor 工具调用提供原生的 ACP 权限对话框。
默认启用工作区信任，以防止启动提示导致无头 ACP 进程退出。默认情况下，`force` 保持禁用。仅为受信任的仓库和 MCP 服务器启用 `AGENT_LOCAL_FORCE=true`。
## 隐私和仓库卫生
- 桥接器不会保留提供商 API 密钥或 Cursor 凭证。
- 临时 MCP 插件文件可以在提示回合期间包含 MCP 环境值和标头，然后它们将被删除。
- 会话元数据存储工作区路径、模型/模式标志、时间戳、标题和上一个请求 ID。不要发布本地状态目录。
- 将 `.env`、IDE 元数据、构建输出、日志和临时状态排除在源代码控制之外。包含的 `.gitignore` 涵盖常见的本地文件。
发布前，运行类似的扫描：
```powershell
rg -n --hidden --glob '!node_modules/**' --glob '!dist/**' `
"C:\\Users|AppData|file:///|sk-[A-Za-z0-9]|api[_-]?key|https://your-private-host" .
```
## 已知限制
- 加载或恢复继续代理本地会话，但无法通过打印接口将之前的聊天消息重播到 ACP 客户端。
- ACP 传输的 MCP 服务器无法转换为 Cursor 插件。支持 stdio、HTTP 和 SSE 传输。
- 工具描述源自 Cursor 的不断演变的流事件有效载体；未知工具变体被报告为 `other` 而不是丢弃。
- 兼容性取决于安装的代理本地 CLI，可能需要在 Cursor 更改其私有流格式后更新适配器。
## 开发
```bash
npm run typecheck
npm test
npm run build
npm run check
```
测试包括使用官方 SDK 和假冒代理本地流的进程内 ACP 客户端/服务器协商，因此在不调用付费模型端点的情况下验证协议行为。
参见 [架构](docs/ARCHITECTURE.md)、[贡献](CONTRIBUTING.md) 和 [安全策略](SECURITY.md) 以获取更多详细信息。
## 许可证
MIT
## 社区
该开源项目已被链接并得到 [LINUX DO 社区](https://linux.do) 的认可。
