@acp-agent/cli

将即时通讯软件桥接到 ACP（Agent Client Protocol）编码 Agent — 在飞书/ Lark 中直接与 Claude、Cursor、Codex、OpenCode、Aider 等对话。

English | 中文

安装

需要 Node.js ≥ 22。

npm install -g @acp-agent/cli
# or
pnpm add -g @acp-agent/cli

设置

运行交互式设置添加飞书/ Lark 账号：

acp-agent setup

命令

acp-agent start          # 启动桥接服务
acp-agent start --setup  # 启动时若无账号则进入交互式设置
acp-agent clean          # 清理数据库文件

架构

Account (IM 账号)
└── Chat (external_chat_id + 可选的 thread_id)
    └── Binding (1:1 — 将 Chat 绑定到一个 Agent)
        ├── Agent (运行时解析：预设或自定义)
        └── Session (多个，同时只有一个 active)
            └── Message (聊天记录)

话题隔离： 相同的 external_chat_id 搭配不同的 external_thread_id 会创建独立的 Chat 记录，各自拥有独立的 Binding、Agent 和 Session 历史。

群聊 oc_123
├── 普通消息 (thread="")
│   └── Chat(c1) → Binding(b1) → Agent(claude) → Session(s1)
└── 话题回复 (thread="t456")
    └── Chat(c2) → Binding(b2) → Agent(cursor) → Session(s2)

支持的 Agent

内置预设 Agent（已测试验证）：

| Agent | 命令 | 说明 | |-------|------|------| | claude | claude-agent-acp | Anthropic Claude | | cursor | agent acp | Cursor Agent | | opencode | opencode acp | OpenCode Agent |

在聊天中使用 /agents 或在 CLI 中运行 acp-agent agent list 可查看所有可用 Agent。

注意： claude Agent 需要额外安装 @agentclientprotocol/claude-agent-acp 包：

npm install -g @agentclientprotocol/claude-agent-acp
# or
pnpm add -g @agentclientprotocol/claude-agent-acp

cursor Agent 需要安装 Cursor CLI。详见 Cursor CLI 安装指南。

IM 内置指令

在飞书/ Lark 与 Bot 的聊天中输入（以 / 或 \ 开头）：

| 指令 | 别名 | 说明 | |------|------|------| | /help | ?, 帮助 | 显示可用指令 | | /agents | 列出agent | 列出可用 Agent（预设 + 自定义） | | /use-agent <id> | agent, 切换agent | 切换当前 Chat 的 Agent | | /new | 创建, restart | 创建新会话（可选 --cwd <路径>） | | /switch <id> | 切换 | 切换到已有会话 | | /sessions | 会话列表 | 列出当前 Agent 的所有会话 | | /cancel | 取消, stop, 停止 | 取消当前运行的任务 |

渠道设置

飞书 / Lark

提供两种方式将 acp-agent 接入飞书 / Lark：

飞书 APP 扫码（推荐）

运行交互式设置并选择 通过 lark-cli 创建新应用，使用飞书 APP 扫描终端二维码完成应用创建。lark-cli 会自动开启 Bot 能力、所需消息权限、事件订阅以及卡片回传交互。

扫码创建完成后，仍需手动获取 App Secret：

• 访问 https://open.feishu.cn/app。
• 进入刚创建的智能体应用。
• 在 凭证与基础信息 中复制 App Secret。

手动配置

如果你已有自建应用，或希望手动创建应用：

1. 访问 https://open.feishu.cn/app，创建或打开你的自建应用（智能体应用）。
2. 启用 机器人（Bot） 能力。
3. 进入 权限管理，切换到批量导入模式，导入以下权限列表：

{
  "scopes": {
    "tenant": [
      "application:application:self_manage",
      "application:bot.basic_info:read",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "docs:document.comment:create",
      "docs:document.comment:delete",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.comment:write_only",
      "docx:document.block:convert",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "im:chat.members:bot_access",
      "im:chat:create",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "wiki:node:read"
    ],
    "user": [
      "offline_access"
    ]
  }
}

4. 进入 事件与回调，将订阅方式设置为 长连接，订阅 im.message.receive_v1，并启用卡片回传交互 card.action.trigger。
5. 进入 凭证与基础信息，复制 App ID 和 App Secret。
6. 创建并发布新版本。

许可证

MIT