Feishu Agent Mesh

把多个 OpenClaw 机器人（不同实例/服务器）接入同一个飞书群：用户依旧 @ 本来的机器人，后台通过共享 Relay/队列同步上下文、日志和审批。

0. At-a-glance

1. 选择模式 —— 先读 references/architecture.md，确定是 MVP（共享表/JSON）、推荐架构（双 Bot + Relay 服务）还是高级模式（含审批/异步）。
2. 部署 Relay —— 根据模式完成 references/deployment-checklist.md：配置飞书订阅、共享存储、HTTP/CLI 调用方式。
3. 注册机器人能力 —— 复制 scripts/relay-config.example.json 并填入每个机器人的能力、回调 URL、所在服务器。
4. 落地 Workflow —— 参照 references/workflow-templates.md 运行「指派协作」或「无领导讨论」两类模板。
5. 日志 & 审批 —— 按 references/logging-schema.md 设计日志字段、审批节点，确保所有跨机器人消息都有据可查。

必须先向用户索取的信息

在启用本 Skill 之前，务必向真人用户明确索要以下数据（缺一不可）：

详细字段说明和示例表格见 references/info-collection-template.md。

> 没有拿到这些信息前，不要启动协作流程；与用户确认后再投入使用。完成收集后，把数据写入 templates/accounts.example.json 并保存为实际配置文件。

1. 关键原则

• 前台不变：群里仍是现有机器人（例如 Coordinator Bot、Specialist Bot …），任何扩展只发生在后台。
• 共享上下文：所有机器人通过同一个 Relay/队列同步讨论内容与任务状态。
• 多群隔离：以 chat_id 维度存储上下文、日志、审批规则，避免串线。
• 渐进式演进：先跑 MVP，再升级到推荐架构，最后再加高级特性。
• 任务优先：机器人之间的沟通必须围绕真人用户当前指派的任务展开，禁止跑题或多余互动；任务结束后立即停止动作，并向任务发起者汇报结果。

2. 快速启动（MVP ≤ 1h）

一次性自建回调服务（推荐）

为所有机器人统一收集 open_id / chat_id，只做一次配置即可：

1. 部署 scripts/feishu-callback-server.js（Node.js + Express）。
• npm i express body-parser node-fetch crypto
• 把 APP_ID、APP_SECRET、Encrypt Key、Verification Token、Bitable app/table、列名写到环境变量。
2. 把服务挂到自己的 HTTPS 域名（如 https://relay.example.com/feishu/callback）。
3. 在飞书开发者后台给每个机器人配置事件订阅 im.message.receive_v1，回调地址都指向该服务。
4. 让目标群的成员各 @ 一次机器人，服务会自动把 open_id/消息写进飞书表格。
5. Relay 周期性从表格拉取记录 → 一次性建立 open_id + sessionKey 映射；后续无需再手动收集。

若暂时无法部署服务，可使用飞书“事件日志”导出 JSON，再按相同字段手工写入表格，但推荐尽早启用统一回调，这样每个用户只需授权一次。

1. 共享存储：建一个飞书多维表格或 SQLite/JSON 文件，字段至少包括 chat_id、thread_id、message, actor, task_state。
2. 机器人轮询：在每个机器人实例里添加一个定时任务（60s 内），读取共享存储中“自己未处理”的记录。
3. 写回策略：机器人在群里发言后，同时写入共享存储，供其他机器人读取。
4. 审批钩子：人工定义关键字段（如 phase="ready_for_approval"），当检测到该字段时，机器人自动 @ 人类确认。

> 适合验证能否「在同一群里互相接力」，但对延迟要求高的场景不适合长期使用。

3. 推荐架构（双 Bot + Relay 服务）

1. Feishu 事件：为每个机器人配置事件订阅，把回调统一指向 Relay 服务；Relay 按 bot_id + chat_id 写入共享上下文。
2. 消息分发：Relay 根据 scripts/relay-config.example.json 中的 routes 决定是通知另一个机器人，还是写入队列等待异步处理。
3. 能力调用：优先使用 HTTP /tools/invoke（或你们自定义 API）触发对方机器人；CLI 仅作兜底。
4. 日志：Relay 所有操作都写入 logs 表，字段参考 references/logging-schema.md。
5. 审批：在配置里声明 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 是否在白名单。
2. 机器人重复响应：查看共享上下文中 last_actor 是否正确，避免双写；必要时启用分布式锁或乐观锁。
3. 日志膨胀：以时间或条数阈值定期归档到对象存储；短期日志保留在主库即可。
4. 审批超时：在 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 群聊协作网络。