Relay Coding Agent (JS)

面向 IDEA/JetBrains ACP 的 Node.js 版 Coding Agent，支持：

• OpenAI-compatible 中转 API（/chat/completions）
• 交互式对话
• 自动改代码（tool calling：read_file/write_file）
• 白名单命令执行（run_command）
• ACP stdio 协议接入（可在 AI Chat 里作为自定义 Agent）

项目结构

• src/config.js：环境变量配置
• src/relayClient.js：中转 API 客户端
• src/tools.js：文件与命令工具
• src/agent.js：Agent 推理与工具循环
• src/acpServer.js：ACP JSON-RPC 服务（newline-delimited）
• src/cli.js：本地 CLI
• bin/relay-agent.js：命令行入口
• bin/relay-agent-acp.js：ACP 独立入口

本地运行

1. 配置环境变量（参考 .env.example）。 也可以直接复制一份 .env：

Copy-Item .env.example .env

然后填入你的 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL。程序会自动加载项目根目录 .env（可用 RELAY_AGENT_ENV_FILE 指定其他路径）。 2. 安装依赖（当前仅 Node 内置模块，无额外依赖）：

npm install

3. 启动交互式 CLI：

npm start

4. 单次执行：

node ./bin/relay-agent.js --workspace-root . --prompt "读取 main.py 并给出改进建议"

5. 安装

npm i -g relay-coding-agent --registry https://registry.npmmirror.com

6. 更新

# 查看版本
npm view relay-coding-agent version
# 更新
npm update -g relay-coding-agent --registry https://registry.npmmirror.com

IDEA 接入 ACP

将 acp.json.template 内容复制到 ~/.jetbrains/acp.json，按需修改：

• LLM_BASE_URL
• LLM_API_KEY
• LLM_MODEL
• WORKSPACE_ROOT

模板默认通过本地 node + 绝对脚本路径启动（Windows + IDEA 更稳定）：

"command": "node",
"args": ["D:/project/temp/bin/relay-agent-acp.js"]

这样可以避开 IDEA 子进程环境中常见的 npx/PATH 初始化问题，降低 Failed to initialize ACP session / Process cancelled 的概率。

如果你希望走在线安装方式，也可以改回：

"command": "npx",
"args": ["-y", "relay-coding-agent", "acp"]

发布流程（Automation Token / 2FA）

当 npm 账号启用了 2FA 或组织策略要求使用 automation/granular token 时，按下面流程发布。

1) 创建自动化令牌（automation token）

• 登录 npm 网站进入令牌管理页：https://www.npmjs.com/settings/<你的用户名>/tokens

复制生成的令牌字符串（形如 npm_xxxxxx）。

2) 配置到本地环境

项目目录创建 .npmrc

//registry.npmjs.org/:_authToken=你的令牌字符串

Swarm 配置（新增）

可在 .env 中设置：

• SWARM_ENABLED=true
• SWARM_PARALLEL_MAX_TASKS=2
• SWARM_REVIEW_TESTER_SEQUENTIAL=true

回归测试命令：

npm run test:swarm

建议同时把 .npmrc 加入 .gitignore，并只在 CI 中通过 Secret 注入。

3) 检查 package.json 配置

npm pkg verify

4) 更新版本号（SemVer 规范）

# 补丁版本（修复 bug，如 1.0.0 → 1.0.1）
npm version patch
# 次版本（新增功能，如 1.0.1 → 1.1.0）
npm version minor
# 主版本（不兼容更新，如 1.1.0 → 2.0.0）
npm version major

5) 立即测试发布

npm publish --access public --dry-run
npm publish --access public

安全策略

• 文件访问限制在 WORKSPACE_ROOT
• 命令执行白名单：ALLOWED_COMMANDS
• 阻断控制操作符：&& || | ;
• 权限模型采用二维抽象：AGENT_SANDBOX_MODE + AGENT_APPROVAL_POLICY
• 兼容旧配置：AGENT_PERMISSION_MODE + AGENT_OPTION_STRATEGY（仅作为新字段缺省时的回退）

当前能力边界

已实现：

• initialize
• authenticate
• session/new
• session/prompt
• session/cancel（通知）

未实现：

• session/load
• MCP server 透传执行

AI Chat 中转范围说明

• ~/.jetbrains/acp.json 中建议只保留 agent_servers，不要设置 default_mcp_settings.use_custom_mcp=true 这类全局默认。
• 本项目的中转只在 Relay Coding Agent 这个 ACP 智能体内生效。
• IDEA AI Chat 内置模型（非该 ACP 智能体）会继续走 IDE 自带的模型通道。

Session Persistence (SQLite)

• The SQLite database is application-level storage, not only for sessions.
• Session data is persisted there and restored on restart.
• Default path on Windows: C:\Users\<username>\.relay\relay.db.
• Default path on Linux/macOS: ~/.relay/relay.db.
• You can override with env var: RELAY_AGENT_DB_FILE (legacy RELAY_AGENT_SESSIONS_DB_FILE is still supported).