把一篇飞书云文档变成会话的输入/输出通道：订阅文档后，文档里的评论作为消息喂进会话，机器人的回复直接发表回该评论的讨论串。适合「边看文档边让 AI 干活」「在文档里就地协作」。支持 docx 与知识库 wiki 链接。
两种接入方式
零命令入口：在文档评论里直接 @机器人。
- bot owner 第一次
@：botmux 自动以mention-only模式接入，创建以doc:<fileToken>为锚点的文档原生会话。 - 非 owner 第一次
@：同样自动接入并立即回复，但前提是先成功私信 owner 一条审计通知（谁在哪个文档 @ 了 bot）；通知发送失败或未配置 owner 则拒绝回复并回滚接入。这是「通知而非审批」模型：owner 始终被告知，但回复不挂起等待批准。owner 用/watch-comment off <文档链接>停止。
显式绑定：在飞书话题内发送 /watch-comment <文档链接> [--dir <本地项目路径>] [--all]。即使话题还没有 AI 会话，也会立即创建话题会话并启动 CLI，注入会前预热 prompt（先读文档、建立上下文，再进入评论待命）。--all 后无需 @机器人。只有零命令入口才会创建 doc:<fileToken> 锚点的文档原生会话。
与 /subscribe-lark-doc 的区别
| 命令 | 语义 |
|---|---|
/watch-comment <链接> [--dir] [--all|--mentions-only] | botmux 产品能力：监听评论、创建/绑定会话、回复发回评论串；不需要 User Token |
/watch-comment list | 有会话查当前会话，无会话查当前 bot 的全部文档监听 |
/watch-comment off [链接|all] | 停止监听一篇或全部（管理子命令仅 owner 可用） |
/subscribe-lark-doc <链接> / list / off | 旧语义：要求文档 scope 的 User Token，调飞书逐文件 subscribe API，绑定当前会话，不承载 Watch 模式 |
交互形式
- 输入：文档评论（默认需
@机器人）当作消息喂进绑定会话，与群里发消息等价。同时注入文档链接/file token、局部评论选中的原文和当前评论串先前的讨论；问题依赖完整正文时会要求 agent 先用飞书文档工具读取，而不是凭空猜测。 - 输出：对「来自文档评论的那一轮」的回复发回该评论的讨论串——以机器人身份发表（不是用户身份）、默认 @ 回评论发起人、超长自动分段。
- 卡片：绑定真实话题时状态卡/终端链接卡/按钮仍发在该话题；
doc:文档原生会话不发卡片，只在评论串回复。 - 一条会话可订阅多个文档；一个文档同时只绑一条活跃会话（重复订阅会改绑到当前会话）。
触发范围与授权
新订阅默认触发范围在 Dashboard → 机器人默认设置按 bot 配置（见 dashboard）：「仅 @ 我的评论」（默认，防刷屏）或「所有新评论」（适合专用文档）。对应 bots.json 字段 docSubscribeDefaultMode（"all" 开启全部评论；见 bots-json）。零命令自动接入始终用 mention-only，要全部评论需重新 /watch-comment <链接> --all 或改 Dashboard。
授权机制：
/watch-comment不需要 User Token：mention-only通过应用长连接接收 @ 通知；all由 botmux 用应用身份每 5 秒增量读取评论列表，读取游标持久化，登记/首次升级只建历史基线、不重放旧评论。/subscribe-lark-doc仍以文档 scope User Token 为硬前置，缺少时生成专用 OAuth 链接引导授权。- 飞书开放平台一次性配置：开通文档评论权限（
docs:document.comment:read/docs:document.comment:create/docs:document.subscription等）并发布版本；「事件订阅」添加drive.notice.comment_add_v1（云文档新增评论），订阅方式用长连接。缺权限/缺事件时启动自检会私信管理员提示。
生命周期与限制
/close关闭会话时自动移除其/watch-comment监听（旧/subscribe-lark-doc仍调飞书退订 API）；daemon 重启后自动恢复活跃会话的监听及--all增量游标。--all最多约 5 秒延迟（轮询发现）；真正 @ 机器人的评论仍由长连接即时触发，二者在 daemon 内去重。- 零命令入口依赖事件可达：若开放平台未推送未监听文档的评论事件，第一次 @ 不会被看见——改用显式
/watch-comment并检查后台权限与事件订阅。 - 嵌套回复兜底：飞书不允许 API 回复的评论（如已解决/受限评论），机器人自动改为新建一条全文评论作答。
- 文档评论是纯文本通道，富交互（卡片/按钮/终端链接）仍走飞书话题。
相关页面
- session-model — 会话锚定模型（
doc:<fileToken>锚点） - slash-commands — 斜杠命令参考
- dashboard — 机器人默认触发范围配置
- im-routing — 飞书消息路由源码分析