Skip to content

文档关系与高频问题说明.md

Latest commit

 

History

History
351 lines (235 loc) · 10.3 KB

文档关系与高频问题说明.md

File metadata and controls

351 lines (235 loc) · 10.3 KB
Raw

文档关系与高频问题说明

这份文档解决两类问题：

  1. 这套教程里每份文档分别负责什么，文档之间怎么配合
  2. 飞书多机器人接入和 knowledge-sweet 工作区复现时，最常见的问题应该看哪份文档、改哪份文档、保持什么配置、为什么要这么配

一、先看懂文档关系

1. 根目录文档各自负责什么

文档 作用 适合什么时候看
README.md 总入口、阅读顺序、总原则 第一次打开仓库时
FEISHU_CONFIG_README.md 解释飞书 channels / accounts / bindings 的概念 不清楚飞书配置结构时
OpenClaw-Windows-安装教程.md Windows / WSL2 安装与飞书接入 在 Windows 环境部署时
文档关系与高频问题说明.md 解释文档之间的联系，并集中回答高频问题 碰到“到底该改哪”时
10分钟复现清单.md 最短落地路径 只想快速复现时
部署说明-knowledge-sweet.md 解释为什么要这样部署 想理解结构设计时
分发规则-knowledge-sweet.md 解释 dispatcher、队列、共享层 想理解自动分发时
详细使用教程.md 按步骤落地 需要完整执行时
AI提示词-复现knowledge-sweet.md 给 AI 的执行约束 想让 AI 代做时
映射表示例模板.md 盘点机器人和账号映射 开始改配置前

2. docs/ 目录负责什么

文档 作用
docs/CONFIG.md 工作区结构与落库方式
docs/SKILL.md 知识库处理与分类规则
docs/TEAM_CONTEXT.md 共享层与协作上下文
docs/ACTIVE_CONTEXT_SPEC.md 轻量共享摘要怎么写
docs/PROJECT_BOOTSTRAP_FLOW.md 项目初始化流程

3. configs/ 和 scripts/ 负责什么

目录 作用
configs/ 模板配置，定义 OpenClaw 和 dispatcher 的最小配置
scripts/ 运行脚本，真正负责启动、分发、同步

二、必须保持的几个核心配置原则

原则 1：一个飞书账号只绑定一个主入口 agent

建议保持：

  • 一个 accountId 对应一个主要 agentId
  • 一个群的默认入口只交给一个清晰的主 agent

原因：

  • 否则最容易出现串身份
  • 也最容易出现一个群里多个机器人抢答

相关文档：

  • FEISHU_CONFIG_README.md
  • 映射表示例模板.md
  • 详细使用教程.md

原则 2：最小稳定方案优先用 channels + bindings

建议保持：

  • channels.feishu.accounts
  • bindings
  • groups.<groupId>.requireMention

作为第一层稳定配置。

原因：

  • 这是这套包里最稳定、最容易复现的部分
  • 也是飞书机器人“能不能接消息”的最基础层

相关文档：

  • FEISHU_CONFIG_README.md
  • 详细使用教程.md

原则 3：当前公开包不要把顶层 agentToAgent 当成主方案

建议保持：

  • 以 dispatcher + queue + 共享工作区 作为可见协作链路

不要默认保持：

  • 顶层 agentToAgent 作为主配置入口

原因：

  • 不同 OpenClaw 版本对 agentToAgent schema 兼容性不一致
  • 当前公开包强调的是“稳定复现”，不是“版本敏感配置试验”
  • 如果直接加了不兼容的 agentToAgent，OpenClaw 可能直接启动失败

相关文档：

  • 分发规则-knowledge-sweet.md
  • 部署说明-knowledge-sweet.md
  • FEISHU_CONFIG_README.md

原则 4：共享记忆走共享工作区，不走私有记忆直读

建议保持：

  • 共享状态写到 TEAM_CONTEXT.md
  • 轻量摘要写到 ACTIVE_CONTEXT.json
  • 交接写到 HANDOFF_LOG.md

原因：

  • 私有 MEMORY.md 不是给别的 agent 直接读取的
  • 共享工作区更容易审计、排错和迁移

相关文档：

  • 部署说明-knowledge-sweet.md
  • 分发规则-knowledge-sweet.md
  • docs/TEAM_CONTEXT.md

三、高频问题逐条说明

问题 1：飞书机器人不回复，应该怎么设置？

先看哪几份文档

  • FEISHU_CONFIG_README.md
  • 详细使用教程.md
  • 映射表示例模板.md

重点检查或修改哪里

  1. configs/openclaw.knowledge-sweet.template.json
  2. 目标环境里的 openclaw.json
  3. bindings
  4. channels.feishu.accounts.<accountId>.groups.<groupId>

应该保持什么配置

  • bindings.match.channel = "feishu"
  • bindings.match.accountId 必须真实存在
  • channels.feishu.accounts.<accountId> 必须存在
  • groups.<YOUR_GROUP_ID> 必须挂在正确账号下
  • 默认入口机器人先保持 requireMention: false

为什么要这么配

  • 机器人能不能回复，首先不是看 prompt，而是看账号和 binding 是否对上
  • accountId 没对上，消息根本不会送到正确 agent
  • 群 ID 挂错账号，机器人看起来在线，但目标群不会响应

问题 2：飞书不支持群聊 agent 互相 @，怎么设置？

先看哪几份文档

  • 分发规则-knowledge-sweet.md
  • 部署说明-knowledge-sweet.md
  • 文档关系与高频问题说明.md

重点检查或修改哪里

  1. configs/DISPATCHER_CONFIG.template.json
  2. scripts/dispatch-daemon.mjs
  3. scripts/enqueue-dispatch.mjs

应该保持什么配置

  • 不把“机器人互相自然聊天”作为主链路
  • 任务交接尽量走 DISPATCH_QUEUE.jsonl
  • 共享上下文走 TEAM_CONTEXT.md / HANDOFF_LOG.md / ACTIVE_CONTEXT.json

为什么要这么配

  • 飞书群里机器人互相 @ 和自然对话并不是最稳定的协作模式
  • 稳定方案不是依赖“它们看见彼此消息”，而是依赖：
    • 队列
    • 分发器
    • 共享工作区

问题 3：群里的文件机器人不能读，是什么原因？

先看哪几份文档

  • FEISHU_CONFIG_README.md
  • 部署说明-knowledge-sweet.md
  • docs/SKILL.md

重点检查或修改哪里

  1. 飞书应用权限是否包含文件/文档相关 scope
  2. 工作区是否已经有该文件的本地副本
  3. 当前流程是否假设“群里上传的文件会自动进入工作区”

应该保持什么配置

  • 飞书权限只解决“有没有读取资格”
  • 工作区规则要明确“文件要么通过 API 拉取，要么先落到本地 workspace”

为什么要这么配

  • 群里上传的文件，不会自动变成 agent 本地文件
  • OpenClaw / workspace 读文件，本质上读的是本地路径或已接入的数据源
  • 所以常见误区不是权限本身，而是误以为“群文件 = 本地可读文件”

问题 4：群聊机器人相互通信配置 agentToAgent 好像有问题，重启时报没有这个配置项，启动失败

先看哪几份文档

  • FEISHU_CONFIG_README.md
  • 分发规则-knowledge-sweet.md
  • 部署说明-knowledge-sweet.md

重点检查或修改哪里

  1. 目标环境的 openclaw.json
  2. 是否手动加入了顶层 agentToAgent
  3. 当前方案是否已经有 dispatcher

应该保持什么配置

  • 当前这套公开包保持：
    • channels.feishu
    • bindings
    • DISPATCHER_CONFIG.json
    • dispatch-daemon.mjs
  • 不要求必须写顶层 agentToAgent

为什么要这么配

  • agentToAgent 在不同版本的 schema 上兼容性不稳定
  • 当前公开包的稳定策略是“显式分发”，不是“依赖内建 agentToAgent schema”
  • 所以如果加了就启动失败，说明应该退回到这套包提供的稳定基线

问题 5：机器人在群里看不到相互的消息，是什么原因？

先看哪几份文档

  • 部署说明-knowledge-sweet.md
  • 分发规则-knowledge-sweet.md
  • 映射表示例模板.md

重点检查或修改哪里

  1. requireMention
  2. 群里到底有几个机器人账号
  3. 当前账号绑定到哪个 agentId
  4. 是否误把“看见消息”当成“能稳定协作”

应该保持什么配置

  • 默认入口机器人可 requireMention: false
  • 非默认入口机器人在扩展场景下优先 requireMention: true
  • 协作主链路仍然是分发器和共享工作区

为什么要这么配

  • “看见彼此消息”不是系统稳定协作的前提
  • 真正稳定的是：
    • 消息先进入正确入口
    • 入口决定是否分发
    • 下游通过共享层接任务

问题 6：怎么把机器人拉到一个群里？

先看哪几份文档

  • OpenClaw-Windows-安装教程.md
  • FEISHU_CONFIG_README.md
  • 详细使用教程.md

重点检查或修改哪里

  1. 飞书开放平台中应用是否已创建
  2. Bot 能力是否启用
  3. 应用是否已发布
  4. 群是否已在 groups 下配置

应该保持什么配置

  • 飞书侧先把机器人应用建好并发布
  • OpenClaw 侧再把 accountId -> groupId -> agentId 接上

为什么要这么配

  • “把机器人拉进群”是飞书平台动作
  • “让群消息进入某个 agent”是 OpenClaw 配置动作
  • 这两层缺一不可

问题 7：多个 Agent 会串身份，很烦人，怎么办？

先看哪几份文档

  • 映射表示例模板.md
  • FEISHU_CONFIG_README.md
  • 详细使用教程.md

重点检查或修改哪里

  1. bindings
  2. agents.list
  3. channels.feishu.accounts
  4. identity.name

应该保持什么配置

  • 一个 accountId 对应一个主 agentId
  • 一个 agentId 对应一套稳定 identity
  • 不要让多个角色共用一个飞书账号又希望它们在群里看起来完全独立

为什么要这么配

  • 串身份通常不是模型问题，而是账号绑定关系混了
  • 共享一个飞书账号时，外显身份天然更容易混
  • 最稳的办法是：
    • 先做映射表
    • 再按映射表落 binding
    • 再检查每个 agent 的 identity.name

四、最推荐的排查顺序

如果只想最快定位问题，建议按这个顺序：

  1. 先看 README.md
  2. 再看 文档关系与高频问题说明.md
  3. 再填 映射表示例模板.md
  4. 再回到 FEISHU_CONFIG_README.md 看概念
  5. 再看 详细使用教程.md 做实际修改
  6. 涉及分发时，再看 分发规则-knowledge-sweet.md

五、最容易误解的 3 个点

1. 误以为 prompt 能解决绑定问题

不能。
绑定、群路由、accountId、groupId、requireMention 都属于配置层，不属于 prompt 层。

2. 误以为群文件天然就是本地文件

不是。
飞书文件需要权限，也需要明确的拉取或落地流程。

3. 误以为机器人看见彼此消息就等于稳定协作

不是。
稳定协作依赖的是：

  • 正确的入口路由
  • 明确的任务分发
  • 共享工作区留痕