内容
# lark-acp
[](https://www.npmjs.com/package/lark-acp-bridge)
[](https://www.npmjs.com/package/lark-acp-bridge)
[](https://www.npmjs.com/package/lark-acp-bridge)
[](./LICENSE)
**English** | **[中文](docs/README_CN.md)**
> 💡 **致谢**: 本项目大量修改和扩展了原有的 [4t145/lark-acp](https://github.com/4t145/lark-acp) —— 添加了对 Kiro 和 Amazon Q 代理的原生支持、飞书/ Lark 区域（域名）切换、Windows 构建支持等。感谢 [@4t145](https://github.com/4t145) 提供了优秀的基础。
**将您的飞书 / Lark 机器人转变为 AI 编程代理。** `lark-acp` 将 [飞书/Lark](https://open.larksuite.com/) 机器人桥接到 **任何支持 Agent Client Protocol (ACP) 的 AI 代理** —— Claude Code、Kiro CLI、OpenAI Codex、Google Gemini CLI、GitHub Copilot CLI、OpenCode、Amazon Q Developer CLI 或您自己的 ACP 服务器。
您在飞书/Lark中发送消息；代理在您的机器上运行；其思考、工具调用和答案流进入一个交互式的飞书卡片。工具调用授权、任务中断和跨重启会话恢复都在卡片中处理。
> 💖 觉得这个项目有用吗？在右上角给作者一个 ⭐ 星星是最直接的鼓励。
> ⚠️ **进行中**: 仍在迭代中 —— CLI 选项和配置字段可能会在 1.0 之前更改。
建议将本项目与 [Lark CLI](https://github.com/larksuite/cli) 及其技能结合使用 —— 桥接器将聊天上下文（聊天 ID、发送者姓名、群组名称）注入提示中，以便代理可以通过 Lark CLI 进入各种 Lark 操作。
<p align="center">
<img src="docs/mock-example.png" alt="lark-acp demo — an AI agent streaming thoughts, tool calls and results into an interactive Feishu/Lark card" width="640">
</p>
## 目录
- [工作原理](#工作原理)
- [快速开始](#快速开始)
- [CLI 参考](#cli-参考) — [预设](#内置代理预设) · [选项](#全局选项) · [聊天命令](#聊天命令) · [配置文件](#配置文件) · [环境变量](#环境变量)
- [连接特定代理](#连接特定代理) — [Kiro](#连接kiro) · [Gemini](#连接gemini) · [Amazon Q](#连接amazon-q)
- [飞书/Lark 开发者控制台设置](#飞书lark-开发者控制台设置)
- [部署](#部署)
- [作为库使用](#作为库使用)
- [故障排除](#故障排除)
## 工作原理
```
飞书 / Lark 云 您的机器
┌─────────────────────┐ ┌─────────────────────────────────────────┐
│ 用户消息 │ WebSocket │ lark-acp 桥 │
│ 卡片按钮点击 │ ◄────────────► │ ├─ 解释器 (消息 → ACP 块) │
│ │ (长连接, │ ├─ 展示器 (ACP → Lark 卡片) │
│ 交互式卡片 │ 无需公开 │ ├─ 会话存储 (跨重启恢复) │
│ (流式更新) │ IP 地址) │ │ 重启) │
└─────────────────────┘ │ └─ ACP 客户端 ──► 代理子进程 │
│ JSON-RPC 2.0 (claude / kiro │
│ 通过标准输入输出 / codex / ...) │
└─────────────────────────────────────────┘
```
- **无需公开端点** —— 事件通过 Lark 的持久 WebSocket 连接到达，因此桥接器可以在 NAT 后、笔记本电脑或容器中正常运行。
- **每个任务一张卡片** —— 思考、工具调用和最终答案合并为一张不断更新的卡片，而不是用消息淹没聊天（尤其是群聊）。
- **每个工具的权限卡片** —— 当代理想要运行工具时，桥接器会弹出授权卡片并暂停代理，直到您回答（未回答的请求在 5 分钟后自动取消；策略可通过 [`--permission-mode`](#全局选项) 配置）。
- **会话持久性** —— 聊天 → 会话映射存储在磁盘上；支持 ACP `session/load` / resume 的代理在桥接器重启后从中断的地方继续。
- **并发聊天** —— 每个飞书聊天都有自己的代理会话，空闲时自动释放（`--idle-timeout`，`--max-chats`）。
## 快速开始
**前提条件**: Node.js ≥ 20，一个飞书/Lark 自定义应用（[设置如下](#飞书lark-开发者控制台设置)），以及至少一个已安装并认证的代理 CLI。
**1. 安装** （无需克隆仓库）：
```bash
npm i -g lark-acp-bridge
# 或直接从 GitHub（安装时构建）：
npm i -g github:wthislifehuh/lark-acp-bridge
```
两者都将 `lark-acp` 命令放入您的 `$PATH` 中 —— 本 README 中的所有示例都使用它。
**2. 编写您的应用凭证** （一次性）：
```bash
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp"
cat > "${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp/config.json" <<'EOF'
{
"credentials": {
"appId": "cli_a1b2c3d4e5f60001",
"appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"domain": "feishu"
}
}
EOF
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/lark-acp/config.json"
```
在 Windows（PowerShell）上，配置文件位于 `~\.config\lark-acp\config.json` —— 创建相同的 JSON 文件。
**3. 启动桥接器**:
```bash
lark-acp proxy --agent claude # 飞书应用（open.feishu.cn）
lark-acp proxy --domain lark --agent gemini # Lark 国际应用（open.larksuite.com）
```
然后在飞书/Lark中找到机器人 —— 给它发送消息，或将其添加到群组并 @ 提及它。
> ⚠️ **区域很重要**: 如果您的应用是在 **Lark 国际**（`open.larksuite.com`）创建的，请在配置文件中设置 `"domain": "lark"`（或传递 `--domain lark`）—— 否则握手将被拒绝，错误代码为 `1000040351`（“域名不正确”）。默认 `feishu` 适用于 `open.feishu.cn` 上的应用。
<details>
<summary>在桥接器本身上开发？请从检出开始运行。</summary>
```bash
git clone https://github.com/wthislifehuh/lark-acp-bridge
cd lark-acp-bridge
npm install && npm run build
node dist/bin/lark-acp.js proxy --agent claude
# 可选：npm link → 使裸 `lark-acp` 命令指向此检出
```
</details>
## CLI 参考
### 命令格式
```
lark-acp [全局选项] proxy --agent <预设> [-- <额外参数>...]
lark-acp [全局选项] proxy -- <代理命令> [代理参数...]
lark-acp agents
lark-acp help
lark-acp version
```
选择代理的两种方式：
- **`--agent <预设>`** — 使用内置预设（最常见）。运行 `lark-acp agents` 获取完整列表。
- **`-- <代理命令>`** — 原始命令； `--` 之后的所有内容都会原样传递给代理。
它们组合使用：`proxy --agent claude -- --debug` 在启动前将 `--debug` 附加到预设的参数中。
全局选项必须位于 `proxy` 子命令之前（ `--domain` 也接受在 `proxy` 之后以方便使用）。
### 内置代理预设
| 预设 | 描述 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claude` | 通过 Zed 的 ACP 适配器使用 Claude Code。运行 `claude` 一次以登录。 |
| `claude-agent` | Claude Agent SDK 适配器 — 直接 Anthropic API。需要 `ANTHROPIC_API_KEY`。 |
| `codex` | 通过 Zed 的 ACP 适配器使用 OpenAI Codex。 |
| `copilot` | GitHub Copilot CLI（原生 `--acp`）。 |
| `gemini` | Google Gemini CLI（实验性 `--acp`）。个人“使用 Google 登录”已停止 — 改用 API 密钥，参见 [连接 Gemini](#连接gemini)。 |
| `opencode` | OpenCode。假设 `opencode` 位于 `$PATH`。 |
| `kiro` | Kiro CLI（原生 ACP via `kiro-cli acp`）。假设 `kiro-cli` 位于 `$PATH` 并已登录。参见 [连接 Kiro](#连接kiro)。 |
| `q` | Amazon Q Developer CLI 通过捆绑的适配器（`q` 没有原生 ACP）。需要 `q` 位于 `$PATH` 并已运行 `q login`。参见 [连接 Amazon Q](#连接amazon-q)。 |
| `mock` | 内置脚本代理（思考 / 工具调用 / 权限卡片 / Markdown）用于本地端到端调试。 |
不受预设涵盖的代理可以作为原始命令启动：
```bash
lark-acp proxy -- node ./my-acp-server.js --port 9000
```
您也可以在配置文件中的 `agents` 字段中持久化您自己的预设（参见 [配置文件](#配置文件)）。
### 全局选项
| 选项 | 描述 |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cwd <目录>` | 代理工作目录（默认：当前目录） |
| `--config <路径>` | 覆盖配置文件路径 |
| `--data-dir <目录>` | 覆盖会话存储目录 |
| `--domain <区域>` | 部署区域：`feishu`（默认，`open.feishu.cn`）/ `lark`（国际，`open.larksuite.com`），或自托管部署的完整基准 URL |
| `--idle-timeout <分钟>` | 在 N 分钟空闲后释放聊天的代理会话（`0` = 永不，默认 1440） |
| `--max-chats <数量>` | 最大并发聊天会话（默认 10） |
| `--hide-thoughts` | 不要在卡片中渲染代理的思考过程 |
| `--hide-tools` | 不要在卡片中渲染工具调用 |
| `--hide-cancel-button` | 不要在卡片底部渲染“取消当前任务”按钮 |
| `--permission-mode <模式>` | 工具授权策略：`alwaysAsk`（默认，弹出卡片供用户选择）/ `alwaysAllow`（自动批准）/ `alwaysDeny`（自动拒绝） |
| `-h`， `--help` | 显示帮助 |
| `-v`， `--version` | 显示版本 |
### 聊天命令
直接发送这些命令到机器人（在群组中，先 @ 提及机器人）：
| 命令 | 效果 |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `/cancel` / `/stop` / `取消` / `停止` | 中断当前任务（代理进程保持活动；会话继续） |
| `/new` / `/restart` | 重置会话 — 下一条消息开始一个全新的代理会话 |
### 配置文件
CLI 读取一个配置文件（默认 `~/.config/lark-acp/config.json`），其中包含凭证和运行时默认值。优先级：**CLI 标志 > 环境变量 > 配置文件 > 内置默认值**。
所有字段都是可选的：
```jsonc
{
"credentials": {
"appId": "cli_xxxxxxxxxxxxxxxx",
"appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
// 部署区域：feishu（默认）/ lark（国际），
// 或自托管部署的完整基准 URL
"domain": "feishu",
},
"dataDir": "./var/lark-acp",
"runtime": {
"cwd": "/work/project",
"idleTimeoutMinutes": 1440,
"maxChats": 10,
"hideThoughts": false,
"hideTools": false,
"hideCancelButton": false,
"permissionMode": "alwaysAsk",
},
"agents": {
// 补丁现有内置预设 — 只需编写您更改的字段
"claude": {
"env": { "ANTHROPIC_BASE_URL": "https://my-proxy.example.com" },
},
// 添加您自己的预设 — 必须定义 `label` 和 `command`
"my-agent": {
"label": "My ACP Agent",
"command": "node",
"args": ["./my-agent.js", "--acp"],
"description": "本地开发的代理",
"env": { "FOO": "bar" },
},
},
}
```
`lark-acp agents` 列出当前配置下可用的所有预设，并标记其来源（`[built-in]` / `[user]` / `[overridden]`）。
### 环境变量
| 变量 | 效果 |
| -------------------------- | ---------------------------------- |
| `LARK_ACP_APP_ID` | 覆盖 `credentials.appId` |
| `LARK_ACP_APP_SECRET` | 覆盖 `credentials.appSecret` |
| `LARK_ACP_DOMAIN` | 覆盖 `credentials.domain` |
| `LARK_ACP_CONFIG` | 覆盖配置文件路径 |
| `LARK_ACP_DATA_DIR` | 覆盖会话存储目录 |
| `LARK_ACP_PERMISSION_MODE` | 覆盖 `runtime.permissionMode` |
## 连接特定代理
### 连接 Kiro
Kiro CLI（AWS 官方的 Amazon Q Developer CLI 继任者）通过 `kiro-cli acp` 原生支持 ACP — 无需适配器。安装 [Kiro CLI](https://kiro.dev/docs/cli/)，登录一次，然后：
```bash
lark-acp proxy --agent kiro
```
您获得完整的体验：每个工具的权限卡片、思维/工具时间线和桥接器重启后的会话恢复（Kiro 广告 ACP `loadSession`）。
### 连接 Gemini
2026-06-18 Google 停止了 Gemini CLI 的免费“使用 Google 登录” OAuth 登录功能，适用于**个人账户**（Gemini Code Assist for individuals / Google AI Pro / Ultra），并引导用户使用 [Antigravity](https://antigravity.google) 代替。运行 `gemini` 时，选择 **1. 使用 Google 登录** 现在会失败：
```text
登录失败。此客户端不再支持 Gemini Code Assist
适用于个人的。 要继续使用 Gemini，请迁移到
Antigravity 套件：https://antigravity.google
```
Gemini CLI 本身（Apache-2.0，仍在维护）通过 **Gemini API 密钥** 继续工作 — 无需 Antigravity 迁移。由于该项目将 `gemini` 作为子进程启动（`npx -y @google/gemini-cli --experimental-acp`），**请将 API 密钥放入配置文件中**，以便子进程非交互式地进行身份验证：
**1. 获取 API 密钥**: 打开 [Google AI Studio](https://aistudio.google.com/apikey)，登录并点击 **创建 API 密钥**（免费层覆盖 Flash 模型；密钥类似于 `AIza...`）。
**2. 编写到 `agents.gemini.env` 中** （修补内置 `gemini` 预设）：
```jsonc
{
"agents": {
"gemini": {
// 注入 API 密钥，以便桥接的子进程跳过交互式 OAuth
"env": { "GEMINI_API_KEY": "AIza..." },
},
},
}
```
设置 `GEMINI_API_KEY` 后，`gemini` 自动选择 API 密钥身份验证，并且永远不会显示登录菜单：
```bash
lark-acp proxy --agent gemini
```
> **登录菜单在首次运行时仍出现？** 一些版本仍在全新机器上显示身份验证菜单。手动在终端中运行 `gemini` 一次，选择 **2. 使用 Gemini API 密钥** 并粘贴密钥 — 选择将保留到 `~/.gemini/settings.json`，之后桥接的子进程将不再提示。
**注意**:
- `GOOGLE_API_KEY` 和 `GEMINI_API_KEY` 等效；当两者都设置时，前者优先。
- 免费层速率限制较低（每天大约几百次请求，Flash 模型）。 **Google One / AI Pro 订阅不会自动解锁付费 API 配额** — 如果您遇到 429 且 `limit: 0`，请在 Google Cloud 中附加计费账户。
- 企业/团队可以使用 **3. Vertex AI** 而不是身份验证菜单（不受关闭影响）；设置 `GOOGLE_GENAI_USE_VERTEXAI=true` 和 `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION`。
### 连接 Amazon Q
Amazon Q Developer CLI（`q`）**没有原生的 ACP** — AWS 已将该功能转移到其继任者 Kiro CLI（通过 `kiro-cli acp` 提供原生 ACP，参见上面的 `kiro` 预设），并表示不会为 `q` 实现此功能（[功能请求 #2703](https://github.com/aws/amazon-q-developer-cli/issues/2703)）。因此，该项目提供了一个轻量级适配器 `lark-acp-q`，它将 ACP 翻译为 `q chat` 调用，以便经典的 `q` 仍然可以连接。
**用法**（确保 `q` 在 `$PATH` 上并且已执行 `q login`）：
```bash
lark-acp proxy --agent q
```
**工作原理**：每个飞书聊天室都拥有一个适配器进程，该进程在内存中维护该聊天室的对话记录。每条消息时，适配器将历史记录重放为上下文，并调用一个新的 `q chat --no-interactive --trust-all-tools` 命令，将 ANSI 过滤后的 stdout 流回作为 `agent_message_chunk`，然后将该回合追加到对话记录中。这样，即使多个飞书聊天室共享同一个工作目录（`q` 自身的 `--resume` 是按目录键入的，可能会相互污染，因此不使用），也能保持并发飞书聊天室的隔离。对话记录按 sessionId 持久化，因此桥可以在重启后通过 `session/load` 恢复它们。
**两个固有局限性**（`q` 自身的能力边界，而非错误）：
1. 非交互式 `q` 必须事先信任工具（否则会阻塞等待 TTY 输入），因此 **无法弹出每个工具的授权卡** — 工具会自动批准。如果需要每个工具的授权，请改用像 `kiro` / `claude` 这样的原生 ACP 代理。
2. `q chat` 发出非结构化文本（无 JSON 事件流），因此 **思想和工具调用不会分离** 进入卡片时间线 — 答案会作为一条消息流出。
**可选环境变量**（在 `agents.q.env` 下的配置文件中设置，或直接导出）：
| 变量 | 默认值 | 描述 |
| ------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Q_ACP_BIN` | `q` | Amazon Q 可执行文件名称 / 绝对路径 |
| `Q_ACP_MODEL` | — | 传递给 `q chat --model` |
| `Q_ACP_AGENT` | — | 传递给 `q chat --agent`（Amazon Q 自定义代理 / 配置文件） |
| `Q_ACP_TRUST_TOOLS` | —（即 `--trust-all-tools`） | 设置为逗号分隔的列表，以 `--trust-tools` 仅使用那些 |
| `Q_ACP_WRAP` | `never` | 传递给 `q chat --wrap`；设置为空字符串以省略它 |
| `Q_ACP_EXTRA_ARGS` | — | 附加到 `q chat` 的额外参数（按空格分隔；不支持引用参数） |
| `Q_ACP_DATA_DIR` | `~/.lark-acp/q-sessions` | 对话记录存储目录 |
| `Q_ACP_MAX_HISTORY` | `24` | 每次调用重放的最大历史消息 |
| `Q_ACP_MAX_HISTORY_CHARS` | `24000` | 重放历史的字符预算 — 整个输入作为单个 argv 元素，因此必须保持在 OS 命令行限制内 |
示例 — 固定模型并仅信任只读工具：
```jsonc
{
"agents": {
"q": {
"env": {
"Q_ACP_MODEL": "claude-sonnet-4",
"Q_ACP_TRUST_TOOLS": "fs_read",
},
},
},
}
```
> **Windows 注意**：Amazon Q CLI 本身不支持 Windows 原生运行 — 需要 WSL / Linux / macOS。在 Windows 主机上，请在 WSL 中运行整个桥（`lark-acp proxy --agent q`），其中 `q` 已安装并登录。
**在没有真实 `q` 的情况下测试**：存储库的测试套件通过真实的 ACP 驱动适配器端到端，针对一个伪造的 `q` — 运行 `npm test`（首先构建，然后使用 vitest：适配器核心的单元测试加上 `tests/` 中的黑盒 e2e）。
> **想要每个工具的授权和完整的时间线？** Kiro CLI 是 Amazon Q 的官方继任者，带有原生 ACP — 只需使用 `--agent kiro`（参见 <https://kiro.dev/docs/cli/acp/>）。
## 飞书/ Lark 开发者控制台设置
在 [飞书开放平台](https://open.feishu.cn/app)（国际版：[Lark 开发者](https://open.larksuite.com/app)）上创建一个**自定义应用**，然后配置三个事项 — **权限**、**事件**和**回调** — 并发布一个版本。
### 1. 添加权限
前往 _权限与范围 → 批量导入/导出范围 → 导入_，粘贴此 JSON 并保存：
```json
{
"scopes": {
"tenant": [
"im:message",
"im:message.group_msg",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:message:update",
"im:message.reactions:write_only",
"im:resource",
"im:chat:readonly",
"cardkit:card:write",
"contact:user.base:readonly"
],
"user": []
}
}
```
每个范围的作用：
| 范围 | 目的 |
| --------------------------------------- | ------------------------------------------------------------------------ |
| `im:message` / `im:message:send_as_bot` | 以机器人身份回复用户消息 |
| `im:message.group_msg` | 接收群聊消息 |
| `im:message.p2p_msg:readonly` | 接收直接（P2P）聊天消息 |
| `im:message:readonly` | 获取消息上下文（@提及解析，富文本扩展） |
| `im:message:update` | 更新交互式卡片（流式思维 / 工具调用 / 最终状态） |
| `im:message.reactions:write_only` | 添加 / 删除表情符号反应以标记任务进度 |
| `im:resource` | 下载用户上传的图像 / 文件二进制（按 `message_id`） |
| `im:chat:readonly` | 读取群组信息（注入提示上下文：群组名称，群组 ID） |
| `cardkit:card:write` | 发送 / 修补 v2 交互式卡片 |
| `contact:user.base:readonly` | 读取用户名（注入提示上下文：发送者名称） |
### 2. 添加事件
在 _事件与回调 → 事件配置_ 下，将**订阅模式**切换为**通过持久连接接收事件**（无需回调 URL）。然后添加此事件，作为**应用身份**订阅：
| 事件 | event_type | 目的 |
| --------------- | ----------------------- | ------------------------------------ |
| 接收消息 | `im.message.receive_v1` | 每个用户消息进入桥 |
### 3. 添加回调
在同一页面上，在下面的“卡片回调”部分中添加：
| 回调 | event_type | 目的 |
| ----------------------- | --------------------- | ------------------------------------------------------------ |
| 卡片动作交互 | `card.action.trigger` | 用户点击卡片按钮（权限选项 / 取消任务） |
### 4. 发布版本
_版本管理与发布 → 创建版本_，填写详细信息并提交审核 / 发布。选择所需的**应用可用性范围** — 只有在其中，用户才能找到并与机器人聊天。
### 5. 开始
将 `App ID` / `App Secret` 放入 `config.json`（或环境变量 `LARK_ACP_APP_ID` / `LARK_ACP_APP_SECRET`）并运行：
```bash
lark-acp proxy --agent claude
```
然后在飞书/Lark中搜索机器人，发送私信，或将其添加到群组并发送消息。
## 部署
### 完整配置示例
在文件中持久化您通常的默认值，以便命令行缩小为 `proxy --agent`:
```jsonc
{
"credentials": {
"appId": "cli_a1b2c3d4e5f60001",
"appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
// Lark 国际版应用（open.larksuite.com）：使用 "lark"
"domain": "feishu",
},
"runtime": {
"cwd": "/srv/projects/main",
"idleTimeoutMinutes": 60,
"maxChats": 20,
"hideThoughts": true,
},
}
```
CLI 标志暂时覆盖同名文件条目。
### systemd
`lark-acp` 是一个前台进程 — 将其放在任何进程管理器下：
```ini
[Service]
Environment=LARK_ACP_APP_ID=cli_a1b2c3d4e5f60001
Environment=LARK_ACP_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ExecStart=/usr/local/bin/lark-acp --cwd /srv/projects/main proxy --agent claude
Restart=on-failure
```
### 快速示例
```bash
# 1. Claude Code（最常见）— 会话在重启后持续
lark-acp proxy --agent claude
# 2. Kiro CLI（原生 ACP，Amazon Q 的官方继任者）
lark-acp proxy --agent kiro
# 3. OpenCode，指向特定项目的工作目录
lark-acp --cwd /work/project proxy --agent opencode
# 4. GitHub Copilot CLI，隐藏思维输出
lark-acp --hide-thoughts proxy --agent copilot
# 5. 自动批准所有工具调用（受信任的沙箱）
lark-acp --permission-mode alwaysAllow proxy --agent claude
# 6. 您自己的 ACP 服务器
lark-acp proxy -- node ./my-acp-server.js --port 9000
```
## 作为库使用
该软件包还导出一个编程 API，用于在其基础上构建：
```ts
import { LarkBridge, FileSessionStore } from "lark-acp-bridge";
const bridge = new LarkBridge({
lark: { appId: "cli_...", appSecret: "...", domain: "lark" },
agent: {
command: "kiro-cli",
args: ["acp"],
cwd: "/work/project",
permissionMode: "alwaysAsk",
},
session: { idleTimeoutMs: 60 * 60_000, maxConcurrentChats: 20 },
sessionStore: new FileSessionStore("./var/lark-acp"),
});
await bridge.start();
// ... 稍后：await bridge.stop();
```
主要导出：
- `LarkBridge` — 协调器；每个进程一个实例。
- `LarkPresenter` / `LarkCardPresenter` — 可插拔的 UI 界面（交换您自己的卡片渲染）。
- `SessionStore` / `FileSessionStore` — 持久的聊天 → 会话映射。
- `LarkLogger` / `createPinoLogger` — 结构化日志记录。
- `LarkHttpClient`，`LARK_DOMAINS`，`resolveLarkDomain` — Lark HTTP 客户端和区域助手。
## 故障排除
** `[ws] code: 1000040351, Incorrect domain name`** — 您的应用位于 Lark 国际版（`open.larksuite.com`），但桥接器正在连接到飞书（默认）。设置 `--domain lark`，`credentials.domain: "lark"` 或 `LARK_ACP_DOMAIN=lark`。（反之亦然：带有 `domain: "lark"` 的飞书应用会以相同的方式失败。）注意：上游 `@4t145/lark-acp` npm 包 **没有** 此设置 — 确保您已安装 **此** 软件包（`lark-acp-bridge`）。
** `Failed to initialize agent (...). Is the agent installed?` ** — 代理子进程未完成 ACP 握手。错误包括代理的最近 stderr；常见原因是 CLI 未安装 / 不在 `$PATH` 上，或尚未登录。手动运行预设的命令（例如 `kiro-cli acp`，`npx -y @zed-industries/claude-code-acp`）以查看原始失败。
**Gemini: `Failed to sign in. This client is no longer supported...` ** — Google 停止了 Gemini CLI 的个人账户 OAuth；按照 [Connecting Gemini](#connecting-gemini) 中的描述切换到 API 密钥。
**飞书中机器人无反应** — 检查，按顺序：应用版本已发布且您在可用性范围内；事件订阅模式为 **持久连接** 并添加了 `im.message.receive_v1`；所有 [权限](#1-add-permissions) 都已导入并批准。
## 致谢与类似项目
该项目是 [4t145/lark-acp](https://github.com/4t145/lark-acp) 的分支（它本身是从 [JiaqiZhang-Dev/lark-acp](https://github.com/JiaqiZhang-Dev/lark-acp) 重构而来）。相关实现：
1. 原始分支基于：<https://github.com/4t145/lark-acp>
2. 一个 Go 实现，也相当完整：<https://github.com/ri-char/Lark-ACP>
3. 另一个 Node 实现：<https://github.com/JiaqiZhang-Dev/lark-acp>
### 此分支在原基础上添加的内容
1. `kiro` 预设（通过 `kiro-cli acp` 原生 ACP）和捆绑的 `lark-acp-q` 适配器，用于 Amazon Q。
2. 飞书/ Lark 区域切换（ `--domain` / `credentials.domain` / `LARK_ACP_DOMAIN`）— 适用于 Lark 国际版的应用。
3. 跨平台（Windows 安全）构建，以及各种修复和文档修改。
---
## 参考资料
- ACP 协议：<https://agentcommunicationprotocol.dev/core-concepts/architecture>
- 飞书/ Lark 开放平台：<https://open.larksuite.com/document/server-docs/getting-started/getting-started>
许可证：MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器