Feishu Agent Mesh
把多个 OpenClaw 机器人（不同实例/服务器）接入同一个飞书群：用户依旧 @ 本来的机器人，后台通过共享 Relay/队列同步上下文、日志和审批。
0. At-a-glance
- 1. 选择模式 —— 先读 references/architecture.md，确定是 MVP（共享表/JSON）、推荐架构（双 Bot + Relay 服务）还是高级模式（含审批/异步）。
- 部署 Relay —— 根据模式完成 references/deployment-checklist.md：配置飞书订阅、共享存储、HTTP/CLI 调用方式。
- 注册机器人能力 —— 复制 scripts/relay-config.example.json 并填入每个机器人的能力、回调 URL、所在服务器。
- 落地 Workflow —— 参照 references/workflow-templates.md 运行「指派协作」或「无领导讨论」两类模板。
- 日志 & 审批 —— 按 references/logging-schema.md 设计日志字段、审批节点，确保所有跨机器人消息都有据可查。
必须先向用户索取的信息
在启用本 Skill 之前，务必向真人用户明确索要以下数据（缺一不可）：
| 信息 | 用途 |
|---|
每个飞书机器人的 app_id、app_secret、verification token、 INLINECODE3 | 配置事件订阅、验证消息来源 |
机器人在目标群聊中的 open_id / INLINECODE5 |
让 Relay 正确 @ 到各机器人 |
| 可写入的飞书多维表格（日志存储）Base ID / Table ID / 字段名 | Phase 1 默认把日志落在该表格，满足“日志存储在飞书表格”的要求 |
| 机器人自身的调用入口（HTTP
/tools/invoke URL 或 CLI 命令）及鉴权方式 | 让 Relay 能够执行具体能力 |
| 任务审批/白名单配置（哪些群、哪些节点需要人类确认） | 限定机器人只针对授权任务行动 |
详细字段说明和示例表格见 references/info-collection-template.md。
没有拿到这些信息前，不要启动协作流程；与用户确认后再投入使用。完成收集后，把数据写入 templates/accounts.example.json 并保存为实际配置文件。
1. 关键原则
- - 前台不变：群里仍是现有机器人（例如 Coordinator Bot、Specialist Bot …），任何扩展只发生在后台。
- 共享上下文：所有机器人通过同一个 Relay/队列同步讨论内容与任务状态。
- 多群隔离：以
chat_id 维度存储上下文、日志、审批规则，避免串线。 - 渐进式演进：先跑 MVP，再升级到推荐架构，最后再加高级特性。
- 任务优先：机器人之间的沟通必须围绕真人用户当前指派的任务展开，禁止跑题或多余互动；任务结束后立即停止动作，并向任务发起者汇报结果。
2. 快速启动（MVP ≤ 1h）
一次性自建回调服务（推荐）
为所有机器人统一收集 open
id / chatid，只做一次配置即可：
- 1. 部署
scripts/feishu-callback-server.js（Node.js + Express）。
-
npm i express body-parser node-fetch crypto
- 把 APP
ID、APPSECRET、Encrypt Key、Verification Token、Bitable app/table、列名写到环境变量。
- 2. 把服务挂到自己的 HTTPS 域名（如
https://relay.example.com/feishu/callback）。 - 在飞书开发者后台给每个机器人配置事件订阅
im.message.receive_v1，回调地址都指向该服务。 - 让目标群的成员各 @ 一次机器人，服务会自动把 openid/消息写进飞书表格。
- Relay 周期性从表格拉取记录 → 一次性建立 openid + sessionKey 映射；后续无需再手动收集。
若暂时无法部署服务，可使用飞书“事件日志”导出 JSON，再按相同字段手工写入表格，但推荐尽早启用统一回调，这样每个用户只需授权一次。
- 1. 共享存储：建一个飞书多维表格或 SQLite/JSON 文件，字段至少包括
chat_id、thread_id、message, actor, task_state。 - 机器人轮询：在每个机器人实例里添加一个定时任务（60s 内），读取共享存储中“自己未处理”的记录。
- 写回策略：机器人在群里发言后，同时写入共享存储，供其他机器人读取。
- 审批钩子：人工定义关键字段（如
phase="ready_for_approval"），当检测到该字段时，机器人自动 @ 人类确认。
适合验证能否「在同一群里互相接力」，但对延迟要求高的场景不适合长期使用。
3. 推荐架构（双 Bot + Relay 服务）
- 1. Feishu 事件：为每个机器人配置事件订阅，把回调统一指向 Relay 服务；Relay 按
bot_id + chat_id 写入共享上下文。 - 消息分发：Relay 根据 scripts/relay-config.example.json 中的
routes 决定是通知另一个机器人，还是写入队列等待异步处理。 - 能力调用：优先使用 HTTP
/tools/invoke（或你们自定义 API）触发对方机器人；CLI 仅作兜底。 - 日志：Relay 所有操作都写入
logs 表，字段参考 references/logging-schema.md。 - 审批：在配置里声明
approval_hooks。当任务状态达到某个 hook，Relay 汇总信息，并由相应机器人账号 @ 人类确认。
4. 高级特性（可选）
- - 无领导讨论：按 references/workflow-templates.md 的流程，自动分配发言顺序、观点收敛、行动项指派。
- 异步任务队列：为长耗时任务配置 Redis / 消息队列；队列项最少包含
task_id、chat_id、origin_bot、assignee_bot、payload。 - 意图识别：Phase 1 使用关键词/显式 @；Phase 2 加入 LLM 分类或正则 DSL，并允许人工 fallback。
- 多群策略：在 Relay 配置中加入
chat_whitelist/blacklist、每群的审批和限流规则。
5. 运维 & 故障
- 1. 消息未到达：检查飞书订阅是否指向 Relay、签名是否一致；核对
chat_id 是否在白名单。 - 机器人重复响应：查看共享上下文中
last_actor 是否正确，避免双写；必要时启用分布式锁或乐观锁。 - 日志膨胀：以时间或条数阈值定期归档到对象存储；短期日志保留在主库即可。
- 审批超时：在 Relay 中为审批 hook 设置超时策略（例如 10 分钟未确认则自动降级为提醒）。
6. 交付物
- - 技能文件：本 SKILL.md + references + scripts，定义流程、配置、日志、审批、常见问题。
- 配置模板：
scripts/relay-config.example.json，作为机器人注册与路由的起点。 - 部署模板：
references/deployment-checklist.md，含 MVP → 推荐架构 → 高级特性 3 级清单。 - 动作模板：
references/workflow-templates.md，覆盖指派协作 / 无领导讨论。
Follow the references to implement the actual Relay/队列；有了这套 skill，任何新的 OpenClaw 机器人都能按统一流程被纳入 Feishu 群聊协作网络。
Feishu Agent Mesh
将多个OpenClaw机器人（不同实例/服务器）接入同一个飞书群：用户依旧@原有的机器人，后台通过共享Relay/队列同步上下文、日志和审批。
0. 概览
- 1. 选择模式 —— 先阅读references/architecture.md，确定是MVP（共享表/JSON）、推荐架构（双Bot + Relay服务）还是高级模式（含审批/异步）。
- 部署Relay —— 根据模式完成references/deployment-checklist.md：配置飞书订阅、共享存储、HTTP/CLI调用方式。
- 注册机器人能力 —— 复制scripts/relay-config.example.json并填入每个机器人的能力、回调URL、所在服务器。
- 落地工作流 —— 参照references/workflow-templates.md运行「指派协作」或「无领导讨论」两类模板。
- 日志与审批 —— 按references/logging-schema.md设计日志字段、审批节点，确保所有跨机器人消息都有据可查。
必须先向用户索取的信息
在启用本技能之前，务必向真人用户明确索要以下数据（缺一不可）：
| 信息 | 用途 |
|---|
| 每个飞书机器人的appid、appsecret、verification token、encrypt key | 配置事件订阅、验证消息来源 |
| 机器人在目标群聊中的open_id/sessionKey |
让Relay正确@到各机器人 |
| 可写入的飞书多维表格（日志存储）Base ID / Table ID / 字段名 | Phase 1默认将日志落在此表格，满足日志存储在飞书表格的要求 |
| 机器人自身的调用入口（HTTP /tools/invoke URL或CLI命令）及鉴权方式 | 让Relay能够执行具体能力 |
| 任务审批/白名单配置（哪些群、哪些节点需要人类确认） | 限定机器人只针对授权任务行动 |
详细字段说明和示例表格见references/info-collection-template.md。
在获取这些信息之前，不要启动协作流程；与用户确认后再投入使用。完成收集后，将数据写入templates/accounts.example.json并保存为实际配置文件。
1. 关键原则
- - 前台不变：群里仍是现有机器人（例如Coordinator Bot、Specialist Bot等），任何扩展只发生在后台。
- 共享上下文：所有机器人通过同一个Relay/队列同步讨论内容与任务状态。
- 多群隔离：以chat_id维度存储上下文、日志、审批规则，避免串线。
- 渐进式演进：先运行MVP，再升级到推荐架构，最后添加高级特性。
- 任务优先：机器人之间的沟通必须围绕真人用户当前指派的任务展开，禁止跑题或多余互动；任务结束后立即停止动作，并向任务发起者汇报结果。
2. 快速启动（MVP ≤ 1小时）
一次性自建回调服务（推荐）
为所有机器人统一收集open
id/chatid，只做一次配置即可：
- 1. 部署scripts/feishu-callback-server.js（Node.js + Express）。
- npm i express body-parser node-fetch crypto
- 将APP
ID、APPSECRET、Encrypt Key、Verification Token、Bitable app/table、列名写入环境变量。
- 2. 将服务挂载到自己的HTTPS域名（如https://relay.example.com/feishu/callback）。
- 在飞书开发者后台为每个机器人配置事件订阅im.message.receivev1，回调地址都指向该服务。
- 让目标群的成员各@一次机器人，服务会自动将openid/消息写入飞书表格。
- Relay周期性从表格拉取记录 → 一次性建立open_id + sessionKey映射；后续无需再手动收集。
若暂时无法部署服务，可使用飞书事件日志导出JSON，再按相同字段手工写入表格，但推荐尽早启用统一回调，这样每个用户只需授权一次。
- 1. 共享存储：创建一个飞书多维表格或SQLite/JSON文件，字段至少包括chatid、threadid、message、actor、taskstate。
- 机器人轮询：在每个机器人实例中添加一个定时任务（60秒内），读取共享存储中自己未处理的记录。
- 写回策略：机器人在群里发言后，同时写入共享存储，供其他机器人读取。
- 审批钩子：人工定义关键字段（如phase=readyfor_approval），当检测到该字段时，机器人自动@人类确认。
适合验证能否在同一群里互相接力，但对延迟要求高的场景不适合长期使用。
3. 推荐架构（双Bot + Relay服务）
- 1. 飞书事件：为每个机器人配置事件订阅，将回调统一指向Relay服务；Relay按botid + chatid写入共享上下文。
- 消息分发：Relay根据scripts/relay-config.example.json中的routes决定是通知另一个机器人，还是写入队列等待异步处理。
- 能力调用：优先使用HTTP /tools/invoke（或自定义API）触发对方机器人；CLI仅作兜底。
- 日志：Relay所有操作都写入logs表，字段参考references/logging-schema.md。
- 审批：在配置中声明approval_hooks。当任务状态达到某个hook时，Relay汇总信息，并由相应机器人账号@人类确认。
4. 高级特性（可选）
- - 无领导讨论：按references/workflow-templates.md的流程，自动分配发言顺序、观点收敛、行动项指派。
- 异步任务队列：为长耗时任务配置Redis/消息队列；队列项最少包含taskid、chatid、originbot、assigneebot、payload。
- 意图识别：Phase 1使用关键词/显式@；Phase 2加入LLM分类或正则DSL，并允许人工fallback。
- 多群策略：在Relay配置中加入chatwhitelist/blacklist、每群的审批和限流规则。
5. 运维与故障
- 1. 消息未到达：检查飞书订阅是否指向Relay、签名是否一致；核对chatid是否在白名单。
- 机器人重复响应：查看共享上下文中lastactor是否正确，避免双写；必要时启用分布式锁或乐观锁。
- 日志膨胀：以时间或条数阈值定期归档到对象存储；短期日志保留在主库即可。
- 审批超时：在Relay中为审批hook设置超时策略（例如10分钟未确认则自动降级为提醒）。
6. 交付物
- - 技能文件：本SKILL.md + references + scripts，定义流程、配置、日志、审批、常见问题。
- 配置模板：scripts/relay-config.example.json，作为机器人注册与路由的起点。
- 部署模板：references/deployment-checklist.md，包含MVP → 推荐架构 → 高级特性3级清单。
- 动作模板：references/workflow-templates.md，覆盖指派协作/无领导讨论。
按照参考资料实现实际的Relay/队列；有了这套技能，任何新的OpenClaw机器人都能按统一流程被纳入飞书群聊协作网络。
