lark-channel-bridge

把飞书 / Lark 消息和本地 Claude Code 或 Codex CLI 打通的轻量 bot。用一条命令启动，扫码绑定 PersonalAgent 应用，然后在飞书里和本机编程助手对话，让它读图、处理文件、改代码。

**Fork 声明：**本仓库是 zarazhangrui/lark-coding-agent-bridge 的定制 fork。原项目与本 fork 均按 MIT License 发布；归属和许可说明见 NOTICE.md 与 LICENSE。

上游集成记录

最近一次经过验证的上游集成于 2026-07-23 通过 Fork PR #4 完成，选择性纳入原仓库从 c0caa10 到 021b774 的 6 个 commit；原仓库对应的 release merge commit 为 36f7d382。

这里记录的是上游来源范围，不表示两边的 tree 或 patch 等价。上述变更通过 cherry-pick 并处理冲突后集成，以保留本 Fork 已有的群响应策略、配置与访问控制行为、 Codex 最终回复恢复机制和维护版 Channel 打包方式。在 Fork 当前改写后的提交历史中， 对应的集成范围是 ffae698 到 3a2540c， 之后还有仅属于本 Fork 的兼容性修复与发布提交。

该次集成通过 macOS、Ubuntu、Windows CI，以及 991 个通过、3 个跳过的测试、 typecheck/build、release/npm clean-install 校验。

**后续同步锚点：**将原仓库 commit 36f7d382 作为不包含在新范围内的下界；下次待检查范围是 36f7d382..upstream/main。由于已纳入的修改在本 Fork 中经过冲突适配，这里记录的是 上游来源历史边界，不是两仓库的 Git merge base。只有下一批上游修改完成集成并通过 验证后，才能更新这个锚点。

English README

本 Fork 维护的增强能力

这个 Fork 不只是重新打包上游代码。面向多 Bot 项目协作和长时间运行的 飞书 / Lark 编程任务，我们新增并持续维护了以下能力：

| 领域 | 本 Fork 新增的能力 | 解决的问题 | |---|---|---| | 共享 Bot Registry | 已连接的 profile 会把观测到的 Bot 身份自动登记到安装级共享 registry；CLI 可以补充别名和非本机 Bot entry，并保证精确名称、别名和 App ID 全局唯一。 | 项目准备过去依赖 profile 本地或人工复制的身份事实，同一个 Bot 名在不同 profile 或主机上可能解析不一致。 | | 多 Bot 项目环境准备 | /botAdmin 和 /project bootstrap 通过显式 --plan-writer 与 --implementer 角色发现并邀请指定 Bridge Bot、准备工作目录并保存群级基础角色，但不会自动启动工作流。 | 过去准备多 Bot 项目需要人工逐个拉 Bot、改权限、切目录和记录角色，没有一个经过校验的统一入口。 | | 原生 Bot-to-Bot 交接 | lark-channel-bridge at-bot 会用当前群实时 Bot 列表校验目标，并以当前 profile 的 Bot 身份发送飞书原生结构化 mention。 | 纯文本 @名字、手拼 mention JSON、过期的 open_id 或选错回传对象，都可能让交接静默丢失，但 Agent 仍误以为已经通知成功。 | | 按群定制行为 | 支持按群加载 operator prompt，并提供 mention-only、owner-default、all-messages、按群 owner-allowlist 四种响应模式，不需要为了免 @ 而向所有群成员开放 Bot。 | 一套全局 Prompt 和全局 @ 策略无法满足不同项目群的角色分工；Bot 可能在 owner 希望它响应时保持沉默，或响应范围过大。 | | 结构化 Agent 上下文 | Bridge 会注入消息、发送者/Bot 身份、引用消息、交互卡片和回传路由信息，并在每次 Codex run 中用 developer instructions 传递 Bridge 规则。 | 把协议规则混在普通用户文本里更容易被忽略或误解，尤其是在引用回复、卡片、Bot 发送者和 Codex 恢复会话场景。 | | Reaction 驱动控制 | 对相关消息添加 Reaction，可以同意下一步、要求进一步解释、确认手动步骤已完成，或停止当前工作链。Bridge 会把目标消息与校准后的 Reaction 状态一并交给 Agent，持久化防重状态，并保留未预埋 emoji 供 Agent 结合上下文判断。 | 若把 Reaction 当成孤立 emoji，可能重复旧任务、丢失被回应消息，或把停止信号错误地启动成新一轮 Agent。 | | 可靠的过程消息与最终回复 | COT/过程输出和最终答案彻底分开，卡片与纯文本模式都单独发送最终回复；同时补齐话题路由、CardKit 流过期、陈旧回读、Codex 空终态/持久化终态和 Markdown 渲染失败的恢复路径。 | 长任务可能留下陈旧卡片或运行中 footer、重复旧内容、误触发 fallback、回复跑出话题，或者本地已经结束却没有把最终答案送到飞书。 | | 延后自重启与结果回执 | 同 profile 自重启会等待当前回复和活跃任务排空，再由 detached helper 重启，并向原群、原话题或原私聊发送且只发送一条成功/失败回执。 | Bot 自部署时可能在回复中途把自己终止，重启后用户也无法确定新进程是否真正连接成功。 | | 维护版 Channel 与可安装产物 | Release 内置维护版 @larksuite/channel 0.4.0-qp.1，修复 CardKit stream rollover，并以自包含的 @penn.qp/lark-channel-bridge npm 包和对应 GitHub Release 发布。 | rollover 可能先把前一张卡完整重发一遍再创建下一张卡，形成重复消息；file dependency 也可能在发布产物中丢失。 |

Fork 扩展能力速查

共享 Bot Registry 属于安装级能力，所有 profile 共用。已连接的 profile 会自动登记观测 到的 Bot 身份；运维人员可以补充别名或非本机项目 Bot。名称和别名采用 NFC 归一化后的 精确匹配，名称、别名和 App ID 全局唯一，本机 profile 仍在使用的 entry 不能删除：

lark-channel-bridge bot-registry list
lark-channel-bridge bot-registry add --name <bot-name> --app-id <cli_xxx>
lark-channel-bridge bot-registry add --name <bot-name> --app-id <cli_xxx> --alias <other-name>
lark-channel-bridge bot-registry remove --name <canonical-bot-name>

App Secret 按 profile 加密保存。secrets set、list、remove 供运维人员使用； secrets get 是 profile 本地 lark-cli binding 使用的 provider 协议：

lark-channel-bridge secrets set --app-id <cli_xxx> [--profile <name>]
lark-channel-bridge secrets list [--profile <name>]
lark-channel-bridge secrets remove --app-id <cli_xxx> [--profile <name>]

Reaction 输入会经过权限校验、状态校准和持久化，并与目标消息一起交给 Agent。11 个预埋 飞书 emoji type 映射为 4 类意图：

| 意图 | 预埋 emoji type | 行为 | |---|---|---| | 同意并继续 | OK, LGTM, Yes, CheckMark, JIAYI（+1） | 仅当目标消息提出下一步时继续 | | 进一步解释 | WHAT, THINKING | 展开或澄清目标消息 | | 手动步骤已完成 | DONE | 从目标消息要求的手动步骤继续 | | 停止当前工作 | No, CrossMark, MinusOne（-1） | 按 /stop 语义中断匹配的工作链 |

未预埋 emoji 仍会交给 Agent 结合上下文判断。重复事件、重试、重启和仍显示在消息上的 旧 Reaction 不会重放已完成工作；移除 Reaction 也不会回滚已完成的外部操作。

其他已经落地、但容易遗漏的 Fork 能力：

• /new chat [name] 会新建群、邀请命令发送者、继承当前工作目录，并开启全新会话。
• /resume [N] 在私聊中列出兼容历史；/account 和 /account change 用于查看或 更换当前应用凭据。
• /stop comment:<scopeHash> 与 /timeout comment:<scopeHash> <N|off|default> 允许管理员控制云文档评论任务； /doc 用于说明无需绑定的评论模型。
• 当 bridge-aware lark-cli 支持回调签名时，Agent 创建的 CardKit 2.0 按钮可以把签名 载荷送回同一 session。
• 可把 reviewed Group Prompt 安装到 ~/.lark-channel/profiles/<profile>/prompts/groups/<chatId>.md。它必须是普通 UTF-8 文件、不能超过 64 KiB；在目标群或目标话题 scope 执行 /new 后，Bridge 会在那里 固定并激活新的不可变快照。

关于能实现的效果，详情可以阅读飞书文档

主要功能

• 在飞书私聊直接发消息，或在群里 @bot，把任务转给本机 Claude Code / Codex CLI。
• 流式卡片：文本回复和工具调用实时更新在同一张卡片上。
• COT 过程消息：可选先发一条过程消息展示 agent 的阶段性文本和工具调用，再单独发送最终答案。
• 会话延续：每个聊天、话题或文档评论有自己的会话，不会互相串。
• 排队与消息合并：短时间连续发送的消息会合并处理；任务运行中收到的普通消息会排队到下一轮，/new、/cd、/ws use、/stop 这类命令可以中断当前任务。
• 多工作空间：用 /cd 切换当前项目，用 /ws 保存和复用常用项目目录。
• 图片 / 文件：直接发给 bot，bridge 下载到本地后交给本机 agent 处理。
• 卡片按钮：/help、/ws list、/status 返回可点击的交互卡片。

前置条件

• Node.js >= 20.12.0
• 本机至少安装并登录一个 agent：
  • Claude Code：claude，安装说明：https://docs.anthropic.com/en/docs/claude-code/quickstart
  • Codex CLI：codex，安装说明：https://developers.openai.com/codex/cli
• 一个飞书 / Lark PersonalAgent 应用。首次启动的扫码向导可以帮你创建并绑定。

安装

npm i -g @penn.qp/lark-channel-bridge
# 或
pnpm add -g @penn.qp/lark-channel-bridge

该包由本 fork 通过 @penn.qp scope 发布；安装后的 CLI 命令仍为 lark-channel-bridge。

首次启动

lark-channel-bridge run

第一次运行会进入扫码向导：

1. 终端渲染二维码。
2. 用飞书 App 扫码。
3. 选择或创建 PersonalAgent 应用。
4. 如果终端提示，选择本次要初始化的 agent。
5. 成功后配置写入 ~/.lark-channel/config.json。

没有指定项目目录也可以启动。bridge 会创建一个 profile 托管的默认工作目录；启动后在飞书里发送 /cd <path> 切到实际项目。

如果已经有 PersonalAgent app，可以在初始化时传 --app-id 跳过创建应用流程；命令会提示输入 App Secret。

lark-channel-bridge run --app-id cli_xxx
# 或直接初始化并启动后台服务
lark-channel-bridge start --app-id cli_xxx

Lark 国际版应用可加 --tenant lark。

后台运行

run 适合首次配置和前台调试。确认 bot 能正常收发消息后，先用 Ctrl-C 停掉前台进程，再用系统服务常驻后台：

lark-channel-bridge start
lark-channel-bridge status
lark-channel-bridge stop

服务层命令必须先全局安装，不能直接用 npx。daemon 的 launchd plist / systemd unit / Windows 任务会记录 bridge CLI 的路径；如果这个路径来自 npm 临时缓存，缓存清掉后 daemon 就起不来。run 用 npx 单次启动没问题。

服务层命令按 profile 注册，每个 profile 有独立服务：

lark-channel-bridge start [--profile <name>]
lark-channel-bridge stop [--profile <name>]
lark-channel-bridge restart [--profile <name>]
lark-channel-bridge status [--profile <name>]
lark-channel-bridge unregister [--profile <name>]

平台映射：

• macOS：launchd 用户代理 ai.lark-channel-bridge.bot.<profile>
• Linux：systemd 用户单元 lark-channel-bridge.bot.<profile>.service
• Windows：Task Scheduler 任务 LarkChannelBridge.Bot.<profile>，launcher 是 .cmd

daemon 日志在 ~/.lark-channel/profiles/<profile>/logs/daemon/。

多 profile：分别运行 Claude 和 Codex

默认情况下，bridge 使用当前激活的 profile；可以通过 profile use <name> 切换。每个 profile 会维护独立的应用凭据、会话、工作目录和日志。只有在需要同时连接多个 PersonalAgent 应用，或分别运行 Claude 和 Codex 时，才需要创建多个 profile：

lark-channel-bridge start --profile claude --agent claude
lark-channel-bridge start --profile codex --agent codex

例如只重启 Codex bot：

lark-channel-bridge restart --profile codex
lark-channel-bridge status --profile codex

延后自重启与回执（deferred self-restart + receipt）

当 bot 重启自身所在的 profile 时（同 profile 自重启），bridge 采用延后重启流程：

1. Agent 调用 lark-channel-bridge restart --profile <当前 profile>。
2. Bridge 记录一条待处理重启请求，让 agent 先完成本轮回复。
3. 所有活跃任务排空、最终回复发送完毕后，detached helper 执行操作系统层面的服务重启。
4. Helper 等待新 bridge 实例连接成功。若新 bridge 在超时内连接，由新 bridge 在原会话中发送成功回执。
5. 若服务操作失败或新 bridge 超时未出现，由 helper 发送失败回执，并注明具体原因（service-action-failure / startup-timeout）。

以上保证：

• Agent 的最终回复不会被中断。
• 每次重启请求只会收到恰好一条回执（成功或失败），通过稳定幂等键（uuid）去重。
• 同 profile 自重启禁止直接调用 launchctl、systemctl、schtasks 或 kill bridge PID，必须走延后路径。

对其它 profile 的外部重启（以及常规 start / stop 操作）不受影响，仍走原有 service-manager 路径。

命令速查

宿主 CLI

lark-channel-bridge run [--profile <name>] [--agent claude|codex] [--workspace <path>] [-c <config>]
lark-channel-bridge migrate [--profile <name>] [--agent claude|codex]
lark-channel-bridge at-bot --chat-id <chat_id> --bot-id <open_id> --message <text>
lark-channel-bridge ps
lark-channel-bridge kill <id|#>
lark-channel-bridge --help

profile use <name> 会切换后续默认启动使用的 profile。需要同时跑 Claude / Codex 两个 bot、连接多套 PersonalAgent 应用，或做脚本化部署时，再使用这些 profile 管理命令：

lark-channel-bridge profile create claude --agent claude
lark-channel-bridge profile create codex --agent codex
lark-channel-bridge profile list
lark-channel-bridge profile use <name>
lark-channel-bridge profile remove <name>
lark-channel-bridge profile remove <name> --purge --yes
lark-channel-bridge profile export <name> [--output ./profile.json] [--force]
lark-channel-bridge profile export <name> --include-secrets --yes

profile remove 默认归档本地状态，也可以删除当前激活的 profile。若还剩其他 profile，会自动切到下一个；若这是最后一个 profile，会清空 root config，之后可以用同名重新创建。只有加 --purge --yes 才会永久删除。profile export 默认脱敏 app secret；只有加 --include-secrets --yes 才会导出敏感配置。

如果某个 profile 被建成了错误的 agent 类型，先 stop 或 unregister --profile <name> 清理对应后台服务，再 profile remove <name>，然后用正确的 --agent 重新创建。

飞书内斜杠命令

| 命令 | 作用 | |---|---| | /new, /reset | 清空当前会话 | | /cd <path> | 切换工作目录并重置会话 | | /ws list | 列出命名工作空间 | | /ws save <name> | 把当前工作目录保存为命名工作空间 | | /ws use <name> | 切换到命名工作空间 | | /ws remove <name> | 删除命名工作空间 | | /resume | 恢复同 agent、工作目录、权限模式兼容的历史会话 | | /status | 查看 profile、agent、工作目录、会话、lark-cli 身份和运行状态 | | /config | 调整展示偏好、访问控制和 lark-cli 身份策略 | | /invite user @某人 | 允许用户私聊使用 bot | | /invite admin @某人 | 添加访问控制管理员 | | /invite group | 允许当前群使用 bot | | /invite all group | 允许 bot 所在的所有群使用 | | /invite owner-default group | 允许当前 Bot 在本群响应 owner 未 @ 任何账号的消息 | | /remove user @某人, /remove admin @某人, /remove group | 移除访问控制条目 | | /remove owner-default group | 从 owner 无 @ 响应名单中移除当前群 | | /botAdmin add <Bot>, /botAdmin remove <Bot>, /botAdmin list | 管理可以执行群运维命令的 Bot | | /project bootstrap <workspace> --plan-writer <bot-name> --implementer <bot-name> | 在普通群中准备 chat 级 workspace，并保存 Decision Owner、命令接收 Coordinator、显式指定的 Implementer 和 Plan Writer；两个角色 flag 顺序任意，Topic 群会被拒绝，也不会自动启动工作流 | | /stop | 停止当前 run，也可点卡片停止按钮 | | /timeout [N\|off\|default] | 设置或清除当前会话的 idle watchdog | | /ps | 列出本机 bridge 进程 | | /exit <id\|#> | 停止指定 bridge 进程 | | /reconnect | 强制 WebSocket 重连 | | /doctor [描述] | 执行低敏诊断 | | /help | 帮助卡片 |

私聊不需要 @。群和话题群默认必须 @bot；@all 会被忽略。支持的云文档评论里 @bot 就会触发回复。

回复展示与 COT

/config 可以调整三类展示选项：

• 消息回复方式：消息卡片 流式更新最终回复；纯文本 在 run 完成后一次性发送。
• 工具调用显示：控制最终回复卡片 / markdown 中是否展示工具块。
• COT 过程消息：关闭 只发送最终回复；简略 先用 COT 消息展示 agent 的过程文本和工具摘要；详细 还会展示工具参数和截断后的输出。

开启 COT 后，bridge 会把过程消息和最终答案拆成两条消息。过程消息用于追踪 agent 做了什么；最终答案仍由 agent 原始文本生成，bridge 不做启发式过滤。若 agent 把最终答案也作为普通流式文本输出，COT 过程消息中可能会出现对应片段。

lark-cli 身份策略

每个 profile 都使用当前 profile 的 lark-cli 目录：~/.lark-channel/profiles/<profile>/lark-cli。agent 子进程会收到指向这个目录的 LARKSUITE_CLI_CONFIG_DIR，所以一个 profile 里的个人授权不会共享给另一个 profile。

默认策略是 bot-only：lark-cli 使用应用 / bot 身份，不访问个人资源。当用户为了日历、邮箱、云盘等个人资源完成授权后，当前 profile 可以切到 user-default，保留应用身份，同时允许已授权的用户身份。owner/admin 可以在 /config 查看或切换这个策略；/status 会用 lark-cli: app 或 lark-cli: user-ready 展示当前摘要。

工作目录

每个 profile 都可以有一个默认工作目录：workspaces.default。新建 profile 时可以传 --workspace <path> 作为初始目录；没传时 bridge 会创建一个 profile 托管的默认工作目录。

下面只是 profile 里的字段片段，不要整段覆盖 config.json；请改对应 profile 下的 workspaces 字段。

{
  "workspaces": {
    "default": "/Users/me/.lark-channel-workspaces/claude/default"
  }
}

bridge 会检查所选目录存在、是目录，并且不是 /、Home 根、系统目录或临时目录根这类范围过大的位置。工作目录只是 agent run 的当前目录，不是文件系统 sandbox；agent 实际能访问哪些文件仍取决于本机 agent 进程及其权限模式。

权限模式

推荐给用户配置的是 permissions.defaultAccess 和 permissions.maxAccess。新 profile 默认两项都是 full，以保持 bridge 的本地工具、授权流程、文件写入等能力完整可用。如需收紧权限，可以改成 workspace 或 read-only；收紧后本地工具执行、登录 / 授权流程、文件写入等能力可能受限。

下面只是 profile 里的字段片段，不要整段覆盖 config.json；请改对应 profile 下的 permissions 字段。

{
  "permissions": {
    "defaultAccess": "full",
    "maxAccess": "full"
  }
}

模式映射：

| Bridge access | Claude permission mode | Codex mode | |---|---|---| | full | bypassPermissions | danger-full-access | | workspace | acceptEdits | workspace-write | | read-only | plan | read-only |

旧版 sandbox 字段仍可读取。bridge 保存 profile 后，会把该设置迁移为 canonical permissions。

数据目录

| 路径 | 内容 | |---|---| | ~/.lark-channel/config.json | root config，包含 profiles 和 active profile | | ~/.lark-channel/active-profile | 最近选择的 profile | | ~/.lark-channel/profiles/<profile>/sessions.json | 会话状态 | | ~/.lark-channel/profiles/<profile>/sessions.json.catalog.json | agent-aware 会话索引 | | ~/.lark-channel/profiles/<profile>/workspaces.json | 当前和命名工作空间绑定 | | ~/.lark-channel/profiles/<profile>/projects.json | 按普通群保存的项目 workspace 与角色记录，并记录不完整准备后的注入禁用状态 | | ~/.lark-channel/profiles/<profile>/secrets.enc | profile 本地加密 secret | | ~/.lark-channel/profiles/<profile>/lark-cli/ | 当前 profile 的 lark-cli 目录 | | ~/.lark-channel/profiles/<profile>/media/ | 附件缓存 | | ~/.lark-channel/profiles/<profile>/logs/ | 结构化运行日志 | | ~/.lark-channel/registry/processes.json | 本机进程注册表 | | ~/.lark-channel/registry/locks/ | profile lock 和 app lock |

设置 LARK_CHANNEL_HOME=/path/to/state 可以迁移整棵本地状态目录。LARK_CHANNEL_LOG_DAYS 可以调整日志保留天数。

访问控制

聊天访问默认是私有的：开箱即用时，只有"你"能在私聊和群聊里用这个 bot。 这里的"你" = 创建 / 拥有这个飞书应用的人（也就是扫码把 bot 建起来的那位）。bot 会自动从飞书查出谁是应用 owner，所以一个人用聊天入口完全不用配置——你私聊它、在任意群里 @它都正常工作，其他人的聊天消息会被静默忽略（bot 不会回"你没权限"，免得暴露自己的存在）。云文档评论按文档权限生效，见下文。

想让别的同事或某些群也能用，就把他们加进下面三类名单：

| 名单 | 控制谁 | 加入 | 移除 | |------|--------|------|------| | 允许私聊的用户 | 谁可以私聊 bot | /invite user @某人 | /remove user @某人 | | 响应的群 | bot 在哪些群里对群内所有人响应 | /invite group（当前群）/ /invite all group（bot 所在的全部群） | /remove group（当前群） | | 管理员 | 谁能改设置、并能在任意群用 bot | /invite admin @某人 | /remove admin @某人 |

/invite、/remove 这些命令只有你（创建者）和管理员能发。命令里 @ 的是对方（不是 @ bot），bot 会自动把 @ 解析成对应的人，你不用手动去找 ID。

两种"畅通无阻"的身份

• 你（创建者）：不受任何名单限制——私聊、任意群、所有命令都能用，而且永远锁不死自己：哪怕名单配乱了，回到 bot 私聊发 /config 总能进来。在飞书后台把应用 owner 转给别人后，bot 也会自动跟着切换。
• 管理员：能私聊、能用 /config 等管理命令，而且不受"响应的群"名单限制——无论群在不在名单里，bot 都会回他们。适合给一起维护 bot 的同事。

几种常见配置

• 只给自己用 → 什么都不用做，默认就是。
• 让某个同事能私聊 bot → /invite user @他
• 让某个工作群里所有人都能用 → 在那个群里发 /invite group
• 第一次配，想把 bot 已经在的群一次性全开放 → 发 /invite all group 一键拉取 bot 所在的全部群加入名单，之后再用 /remove group 删掉不想要的
• 再拉个人一起当管理员 → /invite admin @他

还需要知道的

• 改完下一条消息就生效，不用重启。
• 群里默认只响应明确 @bot（私聊不用 @）。这是独立的群响应方式（/config →“群消息响应方式”），也可以选择“应用所有者未 @ 任何账号时响应”、“响应所有消息”或“仅在指定群响应 owner 无 @ 消息”，和上面的名单是两回事。
• 陌生人发消息一律静默丢弃，不会有任何回复。唯一的例外：有人在一个还没开放的群里 @bot，bot 会回一句友好提示，告诉他可以让管理员发 /invite group 开放这个群。
• 云文档评论按文档权限生效：能在支持的文档里评论并 @bot 的人可以触发回复。

高级：直接改配置文件

不想在飞书里点的话，/invite、/config 背后写的是 ~/.lark-channel/config.json 中对应 profile 的 access 字段。空白名单表示这个名单没人，不表示所有人都能用。下面只是 profile 里的字段片段，不要整段覆盖 config.json：

{
  "schemaVersion": 2,
  "profiles": {
    "claude": {
      "agentKind": "claude",
      "access": {
        "allowedUsers": ["ou_xxxxxxxxxxxxx"],
        "allowedChats": ["oc_xxxxxxxxxxxxx"],
        "admins": ["ou_xxxxxxxxxxxxx"],
        "groupResponseMode": "mention-only",
        "requireMentionInGroup": true
      }
    }
  }
}

groupResponseMode 支持 mention-only（仅显式 @bot，默认）、owner-default（应用所有者未 @ 任何账号时默认响应）、all-messages（响应所有群消息）和 owner-allowlist（仅在指定群响应 owner 无 @ 消息）。requireMentionInGroup 是兼容旧版本的降级字段：all-messages 写 false，其他写 true。建议通过 /config 修改，避免字段不一致。

owner-allowlist 模式下，需配合 ownerNoMentionChats 指定生效的群聊。该字段独立于 allowedChats，只对 owner 的无 @ 消息生效。维护命令（需在目标群 @ 当前 Bot）：/invite owner-default group 和 /remove owner-default group。多 Bot 各自独立配置，不做中央互斥。

allowedUsers / admins 填用户 open_id，allowedChats 填群 chat_id。手动找 ID 最简单的办法：让对方给 bot 发条消息（群里就 @ 它一下），然后看当前 profile 的日志：

grep '"event":"enter"' ~/.lark-channel/profiles/<profile>/logs/bridge-$(date +%Y%m%d).jsonl | tail -5

每行都带 chatId（群 / 私聊 ID）和 senderId（用户 open_id）。手改完后重启 bridge，或在允许的 admin 上下文里发 /reconnect 让它生效。日常调整还是 /invite / /config 更省事，直接改文件主要用于部署脚本预填。

云文档评论

云文档评论不再需要单独绑定工作目录或维护文档白名单。支持的文档评论里 @bot 后，bridge 会在同一个评论线程里回复。评论运行复用文档级 session key；没有记录过文档 cwd 时回退到用户 home 目录。

Codex profile 会读取触发 @ 的那条评论回复中附带的图片：bridge 通过 Drive 素材接口下载图片，执行与普通消息附件相同的限制检查，再作为图像输入交给 Codex。如果图片已声明但下载失败或未通过检查，bridge 会明确报错，不会在缺少图片的情况下继续运行。Claude profile 目前需要把图片内容改为文字后再发送。

常见问题

bot 没反应 / agent 不回复：通常是本机 claude 或 codex CLI 没登录，或者当前会话指向了不存在的工作目录。发 /status 看当前状态；/new 重开会话往往就好。

agent 子进程假死（卡片停在最后一帧不动）：支持 idle 探活。agent 一段时间没输出就会被 SIGTERM kill，卡片末尾会标出自动终止原因。默认关闭。开启方式：/config 设全局值（分钟），或 /timeout 10 只对当前会话生效；/timeout off 关掉当前会话的探活；/timeout default 清掉会话覆盖，回退到全局设置。

图片发过去 agent 说看不到：升级到最新版，0.1.0 之前的版本有文件名去重 bug。

测试与 CI

本地检查：

pnpm test
pnpm typecheck
pnpm build

pnpm test 包含 unit、integration 和 process-level adapter 测试。CI 在 macOS、Ubuntu、Windows 上执行 pnpm install --frozen-lockfile、pnpm test、pnpm typecheck 和 pnpm build。

可选：遥测（Telemetry）

默认情况下 bridge 不上报任何数据：没有指标、没有日志离开你的机器，也不引入任何遥测依赖。下面这个钩子在你主动开启前完全是空操作。

想接自己的监控时，用环境变量指向一个 default export（或导出 createAdapter）AdapterFactory 的模块：

LARK_CHANNEL_TELEMETRY_MODULE=your-telemetry-package lark-channel-bridge start

该模块会收到每一条 log.* 事件，以及错误 / 指标钩子，转发到任何你想要的地方。接口从包根导出：

import type { AdapterFactory, TelemetryAdapter, TelemetryEvent } from 'lark-channel-bridge';

const createAdapter: AdapterFactory = (meta) => ({
  emit(event) {/* 上报事件 */},
  recordError(err, ctx) {/* 上报异常 */},
  recordMetric(name, value, tags) {/* 上报指标 */},
  flush(timeoutMs) {/* 冲刷缓冲事件 */},
});
export default createAdapter;

模块不存在、工厂函数不合法、或者 adapter 抛错，都会降级为空操作——遥测永远不会阻止 bridge 启动，也不会打断日志。

许可

MIT