botmux 文档
  • 简体中文

      • 飞书文档评论监听（/watch-comment）

      把一篇飞书云文档变成会话的输入 / 输出通道：订阅文档后，文档里的评论会作为消息喂进会话，机器人的回复直接发表回该评论的讨论串里。

      不用离开正在写的文档，在评论里 @机器人 提个问题、让它改点东西，回复就出现在评论区——适合「边看文档边让 AI 干活」「在文档里就地协作」。

      怎么用

      最直接的入口是在文档评论里直接 @机器人：

      • bot owner 第一次 @ 时，botmux 自动以 mention-only 模式接入文档，并创建一条以 doc:<fileToken> 为锚点的会话；
      • 非 owner 第一次 @ 时，botmux 同样自动接入并立即回复，但前提是先成功私信 bot owner 一条审计通知（谁在哪个文档 @ 了 bot）；若该通知发送失败、或未配置 owner，则拒绝回复并回滚本次自动接入。这是「通知而非审批」模型：owner 始终被告知，但回复不会被挂起等待批准。owner 用 /watch-comment off <文档链接> 即可停止在某文档回复。

      如果希望把文档评论明确绑定到某条飞书话题，可直接在该话题内发送：

      /watch-comment <飞书文档链接> [--dir <本地项目路径>] [--all]

      显式执行 /watch-comment <文档链接> 时，即使这个话题还没有 AI 会话，botmux 也会立即创建话题会话并启动 CLI，注入会前预热 prompt：AI 先读取文档、建立会议上下文，然后进入评论待命。之后评论到来时可直接增量回答；机器人的回复发表回原评论讨论串。使用 --all 后无需 @机器人。

      只有“未执行命令、直接在陌生文档里第一次 @机器人”的零命令入口，才会创建以 doc:<fileToken> 为锚点的文档原生会话。

      /watch-comment 与 /subscribe-lark-doc

      • /watch-comment 是 botmux 的产品能力：监听评论、创建/绑定 AI 会话、把回复发回评论串。其管理子命令（list/off）仅 owner 可用。
      • /subscribe-lark-doc 保留原有语义：要求文档 scope 的 User Token，调用飞书逐文件 subscribe API，并把订阅绑定到当前会话。它不承载 Watch 模式。
      命令说明
      `/watch-comment <文档链接> [--dir <路径>] [--all--mentions-only]`
      /watch-comment list有会话时查当前会话；无会话时查当前 bot 的全部文档监听
      `/watch-comment off [文档链接all]`
      /subscribe-lark-doc <文档链接>使用文档 User Token 调飞书 API 订阅文档
      /subscribe-lark-doc list / off查看或取消当前会话的 API 订阅

      支持飞书云文档（docx）与知识库 wiki 链接。

      交互形式

      • 输入：文档评论（默认需 @机器人 才触发）→ 当作消息喂进绑定的会话，和在群里发消息等价。
        • Botmux 会同时注入文档链接 / file token、局部评论选中的原文和当前评论串先前的讨论；若问题依赖完整正文，会要求 agent 先用可用的飞书文档工具读取，而不是凭空猜测。
      • 输出（回复）：机器人对「来自文档评论的那一轮」的回复，发回到该评论的讨论串里——
        • 以机器人身份发表（不是你的身份）；
        • 默认 @ 回评论发起人；
        • 超长回复自动分段成多条。
      • 状态卡 / 终端链接卡 / 按钮：绑定真实飞书话题时仍发在该话题；doc: 文档原生会话不发卡片，只在评论串里回复。

      一条会话可订阅多个文档；一个文档同时只绑一条活跃会话。

      触发范围（per-bot，可在 Dashboard 配）

      新订阅默认的评论触发范围，可在 Dashboard → 机器人默认设置 里按机器人配置：

      取值含义
      仅 @ 我的评论（默认）只有评论里 @机器人 才触发，防刷屏
      所有新评论该文档任何新评论都触发，适合专用文档

      对应 bots.json 字段 docSubscribeDefaultMode（"all" 开启「所有新评论」；缺省为「仅 @」）。

      从未监听文档里第一次 @机器人 触发的自动接入始终使用 mention-only；需要接收全部评论时，重新执行 /watch-comment <链接> --all 或在 Dashboard 修改。

      授权

      对 /watch-comment，不需要 User Token，也不调用逐文档 subscribe API。mention-only 通过应用长连接接收 @机器人 通知；all 由 botmux 使用应用身份每 5 秒增量读取评论列表，因此普通评论不需要 @机器人 也能触发。评论读取游标会持久化，登记或首次升级时只建立历史基线，不会重放旧评论。

      对 /subscribe-lark-doc，文档 scope 的 User Token 是旧流程的硬前置；缺少时命令会生成专用 OAuth 链接，引导用户授权后重试。

      此外需要在飞书开放平台后台为该应用做两件事（一次性）：

      1. 「权限管理」里开通文档评论相关权限（docs:document.comment:read / docs:document.comment:create / docs:document.subscription 等）并发布版本；
      2. 「事件订阅」里添加 drive.notice.comment_add_v1（云文档新增评论） 事件，订阅方式用长连接。

      缺权限或没订阅事件时，机器人在启动自检里会私信管理员提示。

      生命周期

      • /close 关闭会话时，自动移除其绑定的 /watch-comment 监听；旧 /subscribe-lark-doc 仍调用飞书退订 API。
      • daemon 重启后自动恢复仍活跃会话的文档监听及 --all 增量游标。

      限制 & 说明

      • 一个文档只绑定一条会话：对同一文档重新执行 /watch-comment 或 /subscribe-lark-doc，会把它改绑到当前会话。
      • --all 有最多约 5 秒延迟：普通评论靠应用身份轮询发现；真正 @机器人 的评论仍可由长连接即时触发，二者在 daemon 内去重。
      • 零命令入口依赖事件可达：如果开放平台没有把未监听文档的评论事件推送给应用，第一次 @机器人 不会被 daemon 看见；此时可显式执行 /watch-comment <文档链接>，并检查后台权限与事件订阅；需要强制调用飞书逐文件订阅 API 时使用 /subscribe-lark-doc。
      • 嵌套回复的兜底：极少数评论（如某些已解决 / 受限的评论）飞书不允许 API 回复，此时机器人会自动改为新建一条全文评论作为答复，保证回复总能落到文档评论区。
      • 文档评论是纯文本通道，富交互（卡片 / 按钮 / 终端链接）仍走飞书话题。