每次 AI Agent 执行到需要人工授权的步骤你都要从手机前走回电脑边点一下确认这种体验用多了非常消耗耐心。botmux 要解决的问题正是让飞书里的消息和按钮直接变成 Agent 的授权指令让远程任务在手机上完成审批后继续跑。严格说botmux 是一个位于飞书开放平台和 Agent 服务之间的授权桥接层它监听飞书机器人收到的消息解析出“同意”“拒绝”、补充参数等意图再以 HTTP 回调方式把结果交给 Agent。这样用户不需要登录 Agent 控制台不需要回电脑也不需要看到任何终端界面只要在飞书会话里回复一条消息任务就能恢复执行。下面会从授权链路讲起然后按环境准备、配置、运行验证、排错这条路径把 botmux 的一个最小可运行方案拆开说明。整体思路适用于大多数需要人在环审批的 Agent 框架落地时根据具体工程的接口和部署方式调整即可。1. 先搞清楚 botmux 要解决的授权链路问题1.1 Agent 授权为什么不能完全自动化Agent 能做很多事但不代表它应该对每一个高风险操作都拥有自动放行权限。生产发布、资金操作、删除数据、对外发送关键消息这几类动作一旦出错影响范围往往远超单次调用本身。因此实际工程里普遍采用“人在环”机制Agent 运行到高风险步骤时暂停把自己的意图、关联参数和任务标识提交给授权服务等待人工决策后继续。为什么不能完全自动化第一个原因是权限失控风险。如果 Agent 的凭据拥有全部权限一次误调用、一个被污染的上下文都可能触发不可控操作。第二个原因是审计要求。关键操作需要明确的人工审批记录而不是只有一条自动化日志。第三个原因是业务上下文。很多决策只有人知道比如“这条公告能不能对外发”“这次发布是否走紧急通道”模型无法可靠判断这类开放式问题。在具体场景里Agent 通常会有一个任务状态机。执行到需要审批的节点时状态从 RUNNING 变成 WAITING_APPROVAL并生成一个唯一的 request_id。后续所有授权回复都围绕这个 request_id 展开避免“同意”或“拒绝”落到错误的任务上。这一步是整个授权链路的地基。1.2 botmux 在飞书与 Agent 之间扮演什么角色可以先用一句话理解 botmux它是飞书和 Agent 之间的“翻译官”和“门卫”。飞书的用户不关心 Agent 内部接口长什么样Agent 也不需要理解飞书的事件协议。botmux 在中间完成两件事一是把飞书回调翻译成 Agent 能识别的授权请求二是校验发送者身份和操作权限。从技术定义看botmux 是一个消息桥接服务。它接收飞书开放平台推送的事件回调完成签名校验、消息内容解析和用户身份映射然后把解析结果 POST 到 Agent 的授权接口。这种方式带来的好处很明显解耦。Agent 只需要暴露 REST 接口不需要引入飞书 SDK。复用。不同的 Agent 框架可以通过同一个 botmux 接入飞书侧逻辑不随框架变化。审计集中。所有人工授权决策都经过 botmux日志可以统一记录和存储。更安全。飞书侧应用只拿到 botmux 的权限不直接触碰 Agent 的密钥和内部接口。需要注意的是botmux 不应该被当作“自动放行工具”来用。它的目标是减少人机交互摩擦而不是绕开权限控制。审批动作仍然由人发起botmux 只负责可靠地传递这个决策。1.3 一条授权消息的完整流转链路先看整体链路后面的配置和代码都围绕这条链路展开。Agent 任务进入高风险步骤调用授权服务生成唯一 request_id任务状态变为 WAITING_APPROVAL。botmux 或 Agent 通过飞书机器人接口向指定用户发送待审批通知。通知里包含 request_id、操作描述和回复指令。用户在飞书聊天窗口回复“同意”或“拒绝”。飞书开放平台把im.message.receive_v1事件推送到 botmux 的订阅地址。botmux 校验签名解析消息内容识别发送者身份。botmux 根据发送者 ID 和消息文本确定决策动作和对应的 request_id。botmux 调用 Agent 的确认接口提交决策结果。Agent 更新任务状态恢复执行或终止并把结果记录到日志和审计系统。第 6 步最容易出问题。request_id 不能靠用户手输因为手输容易出错。生产环境推荐的做法是botmux 在发送待审批通知时把 request_id 连同请求内容暂存在内存、Redis 或数据库里用户回复时通过 user_id 加时间窗口找到对应的待审批记录。如果同一用户同时有多个待审批任务需要在通知消息里明确要求用户带上任务标识或者使用飞书卡片按钮把 request_id 绑定到按钮的 value 上。2. 部署前准备飞书应用、Agent 回调接口和运行环境2.1 创建飞书自建应用并开启机器人能力要使用 botmux第一步是在飞书开放平台创建一个应用。流程如下进入飞书开放平台创建“企业自建应用”。在“应用能力”中启用“机器人”能力填写机器人名称和头像。在“事件与回调”中配置事件订阅。添加事件im.message.receive_v1用于接收用户发给机器人的消息。根据部署方式选择“回调”或“长连接”接收模式。获取 App ID、App Secret、Encrypt Key、Verification Token。如果选择回调模式需要提供一个公网可访问的 HTTPS 地址。本地调试时可以使用开发调试用的公网转发工具把本地的 botmux 端口暴露出去。生产环境建议直接把服务部署到有正式域名的服务器上不要长期依赖临时调试地址。回调模式适合集中管理botmux 作为统一的回调入口。长连接模式适合本地开发和测试不需要暴露公网地址但生产环境多实例部署时回调模式通常更容易和现有网关、日志系统集成。2.2 Agent 侧需要暴露哪些授权接口Agent 不需要感知飞书协议只需要暴露两个接口botmux 才能完成授权闭环。查询待授权请求的接口用于 botmux 转发前校验 request_id 是否存在、是否属于当前操作人。GET /api/v1/authorizations/{request_id}提交授权决定的接口用于接收 botmux 转发的审批结果。POST /api/v1/authorizations/confirm Content-Type: application/json请求体示例{ request_id: req_20250607_001, decision: approve, operator: zhangsanexample.com, operator_name: 张三, comment: 确认发布到预发环境, ts: 1717000000 }Agent 返回示例{ success: true, request_id: req_20250607_001, task_id: task_12345, status: resumed }这里有几个字段值得重点关注。request_id 必须由 Agent 侧生成并保证全局唯一不能由 botmux 临时拼接否则并发场景下很容易冲突。decision 建议只取approve和reject两种枚举值不要依赖自然语言里的模糊词。operator 是 botmux 根据用户映射表填写的操作人标识不能直接用飞书昵称因为昵称可能重复也可能被随意修改。comment 是可选的用于补充审批说明。2.3 botmux 运行环境与配置结构botmux 本身可以看成一个轻量服务。下面以 Python 和 FastAPI 为例给出一个最小可运行的基础环境。依赖版本建议用途Python3.11 及以上示例服务运行环境FastAPI0.111 及以上接收飞书回调、暴露健康检查uvicorn0.30 及以上ASGI 服务启动器httpx0.27 及以上调用 Agent 授权接口PyYAML6.0 及以上读取配置文件cryptography42 及以上处理飞书回调加密字段推荐目录结构botmux/ ├── config/ │ └── config.yaml ├── src/ │ ├── main.py │ ├── config.py │ ├── feishu/ │ │ ├── event.py │ │ └── signature.py │ └── agent/ │ └── client.py ├── logs/ │ └── botmux.log └── requirements.txt拆分成feishu和agent两个模块是为了让协议接入和业务调用互相独立。以后如果要替换成其他 IM 平台只需要改feishu层如果 Agent 接口有变化只需要改agent层。main.py只负责把两个模块串起来不承载具体逻辑。3. 配置 botmux事件订阅、用户映射和授权动作路由3.1 基础配置示例下面这个 YAML 配置用于说明设计思路。实际项目里字段名称和结构可以根据自己的实现调整但核心要素一般包括飞书应用信息、Agent 接口地址、用户映射和动作映射。server: host: 0.0.0.0 port: 8000 feishu: app_id: cli_xxxx app_secret: xxxx encrypt_key: xxxx verification_token: xxxx event_path: /api/feishu/event agent: base_url: http://agent-service:8080 query_path: /api/v1/authorizations confirm_path: /api/v1/authorizations/confirm timeout_seconds: 10 user_mappings: - feishu_id: ou_7a3f... operator_id: zhangsanexample.com operator_name: 张三 role: operator allowed_decisions: [approve, reject, comment] action_rules: - decision: approve keywords: [同意, 批准, approve, y, yes] - decision: reject keywords: [拒绝, 取消, reject, n, no] - decision: comment keywords: [补充, comment:]feishu段的配置项和飞书开放平台后台一一对应任一项不一致都会导致签名校验失败。agent段配置的是 Agent 服务的地址和路径。user_mappings里feishu_id是用户在飞书侧的稳定标识operator_id是 Agent 侧的操作人标识。action_rules的作用是把飞书消息里的不同自然语言表述统一成固定的决策枚举。3.2 用户与会话的映射逻辑不要只信任飞书消息文本。原因有三个第一飞书消息可能是文本、图片、卡片按钮回调不能只靠正则第二发送消息的人未必有审批权限第三同一个用户在飞书里的昵称和 Agent 里操作人标识不一定一致。简单做法是在 botmux 启动时加载一份用户映射表收到消息后先根据feishu_id找到对应用户。参考实现如下def resolve_operator(feishu_id: str, mappings: list) - dict | None: for m in mappings: if m[feishu_id] feishu_id: return m return None找到用户后还要做一层业务判断这个用户是否被允许审批当前 request_id 对应的任务。映射表只解决“你是谁”的问题不解决“你能不能操作这个任务”的问题。后者建议在 Agent 侧查询接口里完成由 Agent 根据任务归属判断并返回权限结果。生产环境里用户映射表不应该写在配置文件里。推荐放到数据库或权限服务里由管理后台维护。这样人员变动时不需要重新发布 botmux。3.3 关键参数说明表参数含义推荐值注意事项feishu.verification_token飞书事件签名校验令牌飞书后台生成后台修改后必须同步到配置feishu.encrypt_key回调消息加密密钥飞书后台生成开启后代码里要处理解密feishu.app_secret应用密钥按密钥规范保管不要提交到代码仓库agent.timeout_secondsbotmux 到 Agent 的请求超时5 到 10太短误判失败太长占用连接user_mappings飞书用户到操作人映射按最小权限集配置默认拒绝不配置不放行action_rules消息文本到决策动作映射覆盖中英文关键词避免语气词误触发审批agent.timeout_seconds是一个看似不起眼但很关键的参数。设置过短Agent 内部状态稍慢就会返回超时设置过长飞书回调线程会被长时间占用并发一高就可能堆积。建议先设 5 秒观察 Agent 接口的 P99 响应时间后再调整。4. 让飞书授权真正生效本地运行与端到端验证4.1 启动 botmux 和 Agent先准备依赖文件fastapi0.111.0 uvicorn[standard]0.30.1 httpx0.27.0 pyyaml6.0.1 python-dotenv1.0.1安装依赖pip install -r requirements.txt启动 botmuxuvicorn src.main:app --host 0.0.0.0 --port 8000为了本地端到端验证再准备一个最小 Agent 模拟服务。这个服务用一个字典保存待授权任务收到 confirm 请求后更新任务状态。from fastapi import FastAPI, Request import threading app FastAPI() pending {} app.post(/api/v1/tasks) def create_task(req: dict): task_id req[task_id] request_id req[request_id] pending[request_id] { task_id: task_id, status: waiting_approval, } return {request_id: request_id, status: waiting_approval} app.post(/api/v1/authorizations/confirm) async def confirm(req: Request): body await req.json() request_id body[request_id] decision body[decision] if request_id not in pending: return {success: False, message: request_id not found} pending[request_id][status] approved if decision approve else rejected return { success: True, request_id: request_id, task_id: pending[request_id][task_id], status: pending[request_id][status], }这个模拟服务的重点是验证“状态从 waiting_approval 变成 approved”证明授权链路真正生效。实际 Agent 内部会有完整的状态机但验证思路一致确认接口被调用后任务恢复执行。4.2 在飞书中发出同意指令本地验证阶段可以走一个简化流程先把飞书应用发布给测试企业成员。调用 Agent 的创建任务接口生成一个 request_id。在飞书机器人会话里给用户发一条待审批通知。用户在飞书里回复“同意”。待审批通知的文本可以这样设计任务 task_12345 正在等待授权 request_id: req_20250607_001 操作在预发环境执行发布脚本 回复“同意”继续回复“拒绝”终止最小验证阶段用纯文本消息就够了。生产环境建议升级为飞书卡片把 request_id 绑定到按钮的 value 上用户点按钮即可避免手动输入和复制出错。4.3 用日志和 Agent 状态确认链路botmux 侧日志应该出现这样的关键信息2025-06-07 10:00:01 INFO 收到飞书回调 event_idev_001 2025-06-07 10:00:02 INFO 签名校验通过 2025-06-07 10:00:02 INFO 解析消息 senderou_7a3f text同意 2025-06-07 10:00:02 INFO 匹配用户映射 operator_idzhangsanexample.com 2025-06-07 10:00:03 INFO 转发授权 request_idreq_20250607_001 decisionapprove 2025-06-07 10:00:03 INFO Agent 回调成功 statusresumedAgent 侧日志应该出现2025-06-07 10:00:03 INFO 授权确认收到 request_idreq_20250607_001 decisionapprove 2025-06-07 10:00:03 INFO 任务 task_12345 状态更新为 approved 2025-06-07 10:00:03 INFO 任务继续执行验证时不要只看接口是否返回 200。更完整的检查是Agent 任务的最终状态是否真的从waiting_approval切到了approved。如果接口返回成功但状态没变说明问题出在 Agent 内部状态机而不是 botmux。注意不要只验证程序能启动还要验证飞书回调是否真的被处理、Agent 任务是否真的从挂起状态恢复。最直接的证据是两侧日志里的 request_id 一致且状态发生了预期变化。4.4 学习环境与生产环境的差异维度学习环境生产环境回调地址临时调试地址正式域名 HTTPS用户映射配置文件写死数据库或权限服务密钥管理明文 YAML环境变量或密钥管理服务审计日志控制台或本地文件集中式日志系统重试与幂等手动处理消息队列 消费端幂等部署方式单进程 uvicorn多实例 健康检查 容器编排学习环境的核心目标是快速跑通链路所以很多环节可以简化。生产环境则要额外考虑异常恢复、权限收敛和可观测性。比如 botmux 重启后内存里暂存的待审批信息会丢失这就要求生产实现改用 Redis 或数据库保存待审批状态。5. 常见问题排查从飞书消息到 Agent 回调的完整链路5.1 飞书事件回调收不到现象是飞书后台测试事件时提示回调发送失败botmux 日志里完全没有请求记录。优先检查四个点回调 URL 是否填写正确是否使用 HTTPS。是否真的订阅了im.message.receive_v1事件。botmux 服务是否启动端口是否被占用。回调地址是否公网可达。可以用 curl 手动向本机 botmux 地址发送一个模拟事件先确认服务本身能处理请求。如果本机能通而飞书后台不通问题基本出在公网可达性上。飞书后台的事件订阅页面通常会有重试记录可以直接看到飞书侧的重试原因。5.2 签名校验失败现象是botmux 返回 401 或 403飞书后台提示校验失败。常见原因包括 Verification Token 不一致、Encrypt Key 不一致、时间戳差超过允许范围。排查时对比配置文件和飞书后台的“事件订阅”页面注意环境变量是不是覆盖了配置文件里的值。如果开启了加密还要检查解密的 base64