Buildify Cursor Agent
Buildify 对 Cursor 的封装。buildify-cursor-agent 连接 Buildify Agent Broker，拉取 cursor.task 任务，通过 Cursor agent acp 在本地执行，并将结果、Token 用量与错误回传 Broker。
npm 包： @buildify-cli/cursor-agent
官网下载： buildify.cn/download
环境要求
- Node.js 18 或更高版本
- 本地已安装 Cursor CLI（
agent命令可用） - Cursor API Key（用于任务所用模型）
- Agent 机器能访问 Buildify Agent Broker
检查 Cursor CLI：
bash
agent --version
agent --help若 agent 不可用，可执行：
bash
buildify-cursor-agent install-cursor安装
bash
npm install -g @buildify-cli/cursor-agent验证安装：
bash
buildify-cursor-agent --version
buildify-cursor-agent --help快速开始
1. 初始化配置文件
bash
buildify-cursor-agent config init2. 设置 Broker 连接
bash
buildify-cursor-agent config set \
server=http://localhost:8080 \
token=<broker-token> \
clientId=<agent-client-id>3.（可选）设置默认 Cursor API Key
用于模型发现等场景：
bash
buildify-cursor-agent config set cursorApiKey=<cursor-api-key>4. 启动 Agent
前台运行（便于调试）：
bash
buildify-cursor-agent start --logs后台守护进程：
bash
buildify-cursor-agent start --daemon
buildify-cursor-agent status
buildify-cursor-agent stop5.（可选）安装为 macOS 系统服务
bash
buildify-cursor-agent install-service
buildify-cursor-agent status
buildify-cursor-agent uninstall-service配置文件
配置文件路径：
text
~/.buildify/cursor-agent.json查看当前配置：
bash
buildify-cursor-agent config show设置配置项：
bash
buildify-cursor-agent config set key=value [key=value ...]常用配置项
| 键 | 默认值 | 说明 |
|---|---|---|
server | http://localhost:8080 | Buildify Agent Broker 地址 |
clientId | 主机名 | 在 Broker 注册的 Agent Client ID |
token | 空 | Broker 认证 Token |
defaultCwd | ~/projects | Agent 机器上的默认工作目录 |
maxConcurrent | 2 | 最大并行 Cursor 任务数 |
cursorApiKey | 空 | 用于模型发现的 Cursor API Key |
cursorBin | agent | Cursor CLI 可执行文件路径 |
defaultModel | composer-2.5 | 模型发现失败时的回退模型 |
usageProbe | true | ACP 未返回用量时，是否探测 print 模式用量 |
logs | false | 是否打印本地 Agent 日志 |
配置优先级（高 → 低）：
- CLI 参数
- 环境变量
~/.buildify/cursor-agent.json- 内置默认值
环境变量
| 变量 | 说明 |
|---|---|
BUILDIFY_SERVER | Broker 服务地址 |
BUILDIFY_TOKEN | Broker 认证 Token |
BUILDIFY_CLIENT_ID | Agent Client ID |
BUILDIFY_LOGS | 启用本地日志 |
CURSOR_API_KEY | Cursor API Key |
BUILDIFY_CURSOR_API_KEY | Cursor API Key 别名 |
BUILDIFY_CURSOR_BIN | Cursor agent 可执行文件路径 |
BUILDIFY_CURSOR_USAGE_PROBE | 启用/禁用用量探测 |
示例：
bash
BUILDIFY_SERVER=http://localhost:8080 \
BUILDIFY_TOKEN=<broker-token> \
BUILDIFY_CLIENT_ID=cursor-local \
CURSOR_API_KEY=<cursor-api-key> \
buildify-cursor-agent start --logsCLI 命令
bash
buildify-cursor-agent start [options]
buildify-cursor-agent stop
buildify-cursor-agent status
buildify-cursor-agent install-service
buildify-cursor-agent uninstall-service
buildify-cursor-agent install-cursor
buildify-cursor-agent config init
buildify-cursor-agent config show
buildify-cursor-agent config set key=value [key=value ...]start 常用参数：
| 参数 | 说明 |
|---|---|
--daemon | 后台运行 |
--foreground | 前台运行 |
--server <url> | 覆盖 Broker 地址 |
--token <token> | 覆盖 Broker Token |
--client-id <id> | 覆盖 Client ID |
--logs | 启用本地日志 |
--request-timeout-ms <ms> | HTTP 请求超时 |
在 Buildify 中使用
使用 AgentCursorSubmitTaskNode 节点提交 Cursor 任务。
必填字段：
- Broker 实例
- Client ID（须与本地运行的
buildify-cursor-agent一致） - Cursor 模型
- Cursor API Key
- Prompt（任务指令）
- 工作目录
cwd（Agent 机器上的本地路径）
WARNING
cwd 是 Agent 所在机器上的路径，不是 Buildify 服务器路径。若目录可能不存在，请启用「目录不存在时自动创建」。
任务字段说明
Buildify 下发的任务支持以下字段：
| 字段 | 说明 |
|---|---|
prompt | 发送给 Cursor 的用户指令 |
cwd | Agent 机器上的本地工作目录 |
model | Cursor 模型，如 composer-2.5 |
cursorApiKey | 任务使用的 Cursor API Key |
conversationId | 可选，用于恢复 ACP 会话 |
mcpServers | 可选，传给 Cursor ACP 的 MCP 服务定义 |
createCwdIfMissing | 是否允许 Agent 自动创建 cwd |
每个任务会启动独立的 Cursor ACP 子进程：
bash
agent --api-key <cursor-api-key> --model <model> acpToken 用量上报
Cursor ACP 不一定直接返回 Token 用量。当 usageProbe=true 时，Agent 会在任务结束后尽力探测用量。
上报内容可包括：
- input / output / reasoning tokens
- cache read/write tokens
- 来源元数据（如
acp、print-probe、estimated）
若无法从 Cursor 读取用量，Agent 会回退到估算值，确保 Broker 仍能收到可用数据。
调试
启用日志：
bash
buildify-cursor-agent start --logs查看守护进程/服务状态：
bash
buildify-cursor-agent status安装或验证 Cursor CLI：
bash
buildify-cursor-agent install-cursor本地 ACP 调试（开发用）：
bash
node debug-acp.mjs \
--model composer-2.5 \
--api-key <cursor-api-key> \
--prompt "say hello"常见错误
Task is missing cursorApiKey
任务未包含 Cursor API Key。请在 Buildify 的 ModelSelect 中配置 Key，或在任务 payload 中传入 cursorApiKey。
Cursor API key is invalid
API Key 无效或被脱敏。任务须传递真实 Key 值，不能是掩码占位符。
Cursor usage limit reached
所选 Cursor 账号或模型已达用量上限。请更换模型或等待配额重置。
Working directory does not exist
cwd 在 Agent 机器上不存在，且未启用 createCwdIfMissing。请使用 Agent 机器上的有效路径，或启用自动创建目录。
Cursor CLI not found
找不到 agent 可执行文件。可执行：
bash
buildify-cursor-agent install-cursor或手动指定路径：
bash
buildify-cursor-agent config set cursorBin=/path/to/agent