lark-agent-mux

中文 | English

lark-agent-mux 是一个个人飞书/Lark Agent Dock，用来从聊天里运行本地 Agent Client Protocol agent。

它面向一个可信 Owner：你可以在飞书里启动、对比、交接、监控和取消本地 agent 任务，同时保持本地优先执行，并通过 SQLite 任务记录、日志、会话和 artifacts 保持可观测。

项目状态

lark-agent-mux 现在是可用的 1.0 个人工作流工具。它不是多租户任务平台、托管 agent 平台，也不是代码执行沙箱。

适合这些场景：

• 你运行可信的本地 ACP-compatible agent，例如 Codex ACP adapter 或 OpenCode ACP。
• 你希望用飞书消息、卡片和云文档评论控制本地仓库。
• 你希望持久化任务和 session 状态，但不想额外部署一套远端服务。

需要谨慎的场景：

• 配置的项目、agent 命令或凭据不完全可信。
• 你需要多用户权限、租户隔离或远端执行沙箱。
• 你的运行环境不能接受 Node 当前的 node:sqlite 实验特性 warning。

功能概览

• 通过官方飞书/Lark Channel SDK 接收飞书消息、卡片操作和云文档评论。
• 将 slash command 和部分自然语言管理意图路由到已配置的项目和 ACP agent。
• 通过 ACP stdio 运行 agent，支持 session 复用、compare、handoff、retry、cancel 和 artifact 跟踪。
• 通过飞书卡片流式回传任务输出，并将任务状态持久化到 SQLite。
• 根据普通自然语言里的输出意图，将结果回到消息线程、导出为飞书文档报告，或同步到 Bitable 任务看板。
• 限制只有一个 Owner 和已配置的聊天可以使用。
• 对配置指定或检测到的高风险任务要求确认，支持允许一次、允许当前任务内后续权限请求、拒绝。
• 通过 validate 和 /doctor 输出 Owner 绑定、项目默认 agent、普通自然语言路由、聊天 allowlist、集成和命令助手诊断。
• 支持重启恢复和优雅退出，适合长期运行的本地服务。

快速开始

环境要求：

• Node.js 22.19 或更高版本
• 源码开发需要 pnpm 9
• 已启用 WebSocket 事件投递的飞书应用
• 一个或多个本地 ACP-compatible agent 命令

从 npm 安装：

npm install -g lark-agent-mux
lark-agent-mux setup
lark-agent-mux validate --config ~/.agentmux/config.yaml
lark-agent-mux start --config ~/.agentmux/config.yaml

包也会安装 agentmux 作为兼容别名，方便已有脚本继续使用。

setup 会优先打开飞书/Lark 扫码创建链接；如果扫码创建不可用、过期或被拒绝，会进入手动回退并提示 Manual Feishu App ID / Manual Feishu App Secret。此时在飞书开放平台创建或打开应用，启用 WebSocket 事件投递后粘贴 App ID 和 App Secret；Owner open_id 不知道可以留空，启动后由第一个授权发送者绑定。

也可以从源码运行：

npx [email protected] install
npx [email protected] build
node dist/cli.js setup
node dist/cli.js validate --config ~/.agentmux/config.yaml
node dist/cli.js start --config ~/.agentmux/config.yaml

启动后，从允许的飞书聊天向机器人发送 你好 或 /help。如果 owner.feishu_user_id 仍是 BOOTSTRAP_OWNER_REPLACE_ME，lark-agent-mux 会把第一个授权发送者的飞书 open_id 绑定为 Owner。

validate 会打印配置诊断摘要。start 会一直运行到 Ctrl+C 或 SIGTERM，然后停止维护任务、取消正在运行的本地 worker、在支持时断开飞书连接，并关闭 SQLite。

飞书应用配置、扫码创建、Owner 绑定、源码运行、Docker 和首次 smoke test 见 Setup。

常用命令

/help
/workspace
/projects
/project add backend /path/to/repo --default-agent acp_codex --safe-mode
/project use backend acp_codex
/session list
/use acp_codex backend
/acp_codex backend 修复登录接口偶发 500
/compare acp_codex,acp_opencode web 修复 checkout 测试失败
/handoff acp_codex -> acp_opencode backend 先分析再修复
/assist 让 acp_codex 检查 backend 登录测试
/do 让 acp_codex 检查 backend 登录测试
/status
/logs task_id
/cancel task_id

通过 /workspace、/project use 或 /use 选择聊天上下文后，可以直接发送普通文本给当前 agent/project。如果 prompt 本身以 / 开头，请使用 /prompt <text>。

普通自然语言可以要求消息回复、飞书文档报告或 Bitable/表格输出。请求的集成未启用或执行失败时，lark-agent-mux 会保留消息线程里的任务结果，并说明集成问题。

完整命令、session 控制、registry 命令、self-agent 意图以及 /assist 和 /do 的区别见 Commands。

文档地图

• Concepts：Owner、Project、Agent、Session、Task、飞书话题、安全模型和架构。
• Setup：安装、飞书连接、Owner bootstrap、校验、源码运行和 Docker。
• Configuration：YAML 配置段、ACP agents、registry install、运行时限制、飞书集成和命令助手。
• Commands：任务、workspace、project、session、registry、状态、artifact 和自然语言命令。
• Troubleshooting：启动、飞书、Owner、ACP、SQLite 和集成问题排查。
• Release Acceptance：发布前自动门禁和真实飞书 smoke test 证据清单。
• examples/config.yaml：带注释的配置模板。
• docs/lark-agent-mux-acp-only-prd.md：ACP-only 方向的产品/设计说明。

开发

npx [email protected] typecheck
npx [email protected] test
npx [email protected] build

如果依赖已经安装，也可以使用 pnpm scripts：

pnpm typecheck
pnpm test
pnpm build
pnpm check

贡献者参考：

• AGENTS.md：给 coding agents 和维护者的仓库工作指南。
• CONTRIBUTING.md：开发环境、PR 要求和发布检查清单。
• SECURITY.md：漏洞报告方式和安全说明。
• CODE_OF_CONDUCT.md：社区行为准则。
• test：Vitest 测试套件。

许可证

lark-agent-mux 使用 MIT License 发布。