飞书文档接入 Agent:从账号授权到第一次安全写回

大家好，我是志在必得。

“把这些飞书文档整理成一个知识库。”

这句话发给 Agent 很容易。它背后却藏着好几个动作：去哪里找文档，允许读哪些页面，新内容建在哪里，能否修改旧页面，出了偏差什么时候停。

只看 Agent 返回一句“执行成功”，很难判断事情有没有做对。更稳妥的办法，是把过程拆成三次核对：接入时确认账号与权限，建库前确认空间和页面结构，发生写入后检查完整的变更记录。

这三次核对都通过，飞书文档才算有了一个可以交给 Agent 使用的入口。

整套方案有四个部分，各自承担不同工作。

飞书负责保存与协作，Lark CLI 打开操作通道，Agent 接受任务，规则把每轮执行限制在已确认范围内。后面的账号确认、建库方案和变更记录，就是用来检查这四个部分是否按预期配合。

这条路线适合原本就在飞书里写方案、记会议、保存项目记录的人。手机和电脑继续使用原来的页面，同事仍按已有方式协作，不必先把历史内容搬进本地目录。若你更在意离线、Git 版本和原文件控制，本地 Markdown 会更顺手。两种做法也可以分工，日常协作留在飞书，长期归档放回本地。

开始前还要准备一台能够运行 Node.js 与npx的电脑、一个正常使用的飞书账号，以及能够执行终端命令的 Agent。Windows 和 Mac 都可以，常见阻塞点集中在飞书应用配置、组织审批和授权范围。电脑环境反而通常不是最麻烦的部分。

Agent 要操作飞书，需要一条被授权的通道。Lark CLI 提供这条通道，它把文档、云盘和知识空间的部分能力变成命令，Agent 才能查找页面、读取正文或创建内容。

搭这套最小知识库，主要会用到三组能力：

一次任务可能连续调用多组能力。比如“找到某个项目的会议记录并整理成主题页”，通常先通过 Drive 定位，使用 Docs 读取正文，再由 Wiki 或 Docs 建立结果页面。读者不需要背下全部命令，但要看得懂执行结果中出现的能力是否与任务吻合。

安装工具本身不会打开整个组织的文档。最终可见范围取决于当前登录身份、应用配置、授权范围，以及这个身份原本拥有的页面权限。

第一次可以把下面这份任务单交给 Agent：

请安装并初始化飞书官方 Lark CLI，本轮只处理连接与身份确认。  依次执行： npx @larksuite/cli@latest install lark-cli config init --new lark-cli auth login --recommend lark-cli auth status  遇到以下情况请暂停： - 需要填写应用信息； - 浏览器要求登录或确认授权； - 当前身份与预期账号不一致； - 命令返回权限或配置错误。  完成后请返回“账号与权限确认结果”，写明： 1. 当前登录身份； 2. 认证是否有效； 3. 已获得的权限范围； 4. 尚未解决的配置问题。  禁止读取、搜索或修改任何文档。

这里会有一次人工接手。Agent 可以运行命令，把授权地址和报错信息整理出来；浏览器登录、应用信息和授权确认仍由本人完成。

拿到结果后，先核对账号。如果你原本要进入个人测试空间，返回信息里却出现另一个组织身份，就停在这里。不要带着错误身份继续建页，再靠删除来补救。

不同组织的管理员策略并不相同。有的应用可以直接授权，有的需要审批。教程无法替你跳过这一层，也不能据此承诺某个账号能看到全部知识空间。

这里还要区分“认证成功”和“权限够用”。lark-cli auth status返回有效，只能说明当前会话可以使用；它没有证明目标知识空间一定可见，也没有证明某个页面允许写入。接下来的建库方案会继续验证可见范围。

连接正常后，先别让 Agent 创建几十个分类。第一版只需要一个能收、能找、能产出的骨架。

可以从四个页面开始：

• 知识库说明：保存使用范围、命名方式和停止条件；
• 待整理：接收刚进入系统、还没有归位的内容；
• 主题知识：保存会反复使用的长期内容；
• 项目与输出：承接正在推进的任务和阶段结果。

飞书知识库负责空间与页面关系，飞书文档承载具体内容。Lark CLI 负责连接，Agent 按任务执行。页面再整齐，也替代不了操作规则，“知识库说明”应该先写。

里面至少说清几件事：只处理明确指定的页面；写入前先报计划；不删除或覆盖唯一原件；新内容保留来源名称和链接；现场情况与计划不一致时停止。

建页之前，让 Agent 先提交执行方案：

请为我指定的飞书知识空间规划一个最小知识库。  拟创建页面： 知识库说明、待整理、主题知识、项目与输出。  现在只做规划，不执行创建，也不读取现有页面正文。  请返回“建库执行方案”： - 当前身份可见的知识空间名称或标识； - 四个页面准备放置的位置和用途； - 是否发现同名页面； - 准备调用的 Lark CLI 能力； - 执行中可能需要我确认的事项。  如果无法确定目标知识空间，请停止，不要自行选择。

这份方案解决的是“它准备怎么做”。重点核对目标空间、页面层级和同名页面。确认以后，再发一次明确许可，让它只创建这四个页面。

建库执行方案已确认。  请只在我指定的知识空间中创建： 知识库说明、待整理、主题知识、项目与输出。  限制条件： - 不移动、覆盖或修改其他页面； - 遇到同名页面时停止，不自动添加后缀； - 页面位置与已确认方案不一致时停止； - 完成后返回四个页面的名称、位置和链接。

创建结束后回到飞书打开页面。命令返回成功，只能说明调用完成；页面是否建在正确位置、标题有没有写错、原有内容是否保持不变，还得看飞书里的实际结果。

页面关系先用普通链接或文档引用建立。第一版只要能从整理结果回到来源，已经足够支持验收。复杂的关系图、批量移动和反向引用查询可以晚一点处理。飞书界面能够展示文档引用关系，但当前公开说明没有明确保证 CLI 可以直接查询完整的反向引用列表，这部分需要结合具体版本验证。

“知识库说明”也不要只写一句禁止删除。建议把它写成长期操作合同，至少包含这些字段：可读取空间、默认写入位置、禁止修改的页面、命名规则、来源链接格式、需要人工确认的动作、出现差异时的停止方式。以后换一个 Agent，先让它读取这页规则，再处理任务。

空页面不能证明这套系统能用。准备两三篇没有敏感信息的测试文档，放进“待整理”。合同、客户信息、内部经营数据和无法恢复的唯一原件先不要参与。

第一轮只读。目标是确认 Agent 找到的是你指定的页面，并且能够把内容与来源对应起来。

请只读取我指定的飞书测试文档。  请返回： - 实际读取到的文档名称与链接； - 每篇文档的内容概括； - 重复信息与可能的关联； - 建议进入的主题页或项目页； - 后续拟新增、拟更新的页面。  本轮禁止创建、移动、覆盖、删除、分享或写回内容。 没有收到确认，不得进入下一步。

这时先看来源，不急着评价摘要写得漂不漂亮。文档名称是否正确，链接能否打开，重要条件有没有漏掉，决定了后面的整理是否值得继续。

只读结果还可以做一次交叉核对：同一份内容是否从多个位置被找到，两个页面里的数字是否互相冲突，日期、负责人和版本号有没有被摘要省略。遇到冲突时，让 Agent 把差异并排列出，不要自行选择一个版本当成正确答案。

建议通过以后，再批准一次很小的写回。比如只创建一个主题页，并更新一个指定索引。不要在第一次任务里同时迁移历史内容、调整目录和批量改写旧页面。

已确认本轮整理方案。  请只执行批准范围内的写入： - 创建已确认的主题页或结果页； - 每条整理内容保留来源文档链接； - 只更新我点名的索引页； - 不删除、不覆盖、不改写测试原文。  完成后请返回“变更记录”： 1. 新增页面的名称与链接； 2. 修改页面的名称与链接； 3. 每项变更对应的来源； 4. 计划与实际执行是否一致； 5. 未完成事项和停止原因。  执行条件发生变化时立即停止，不要扩大范围。

回到飞书逐项核对变更记录。新页面的位置和正文要对，来源链接要能返回原页面，测试原文也应保持原样。换一台设备再打开同一知识空间，可以顺便确认同步后的内容是否一致。

验收时可以沿着四类证据检查：

还有一类风险来自文档内容本身。页面里可能出现会影响 Agent 判断的命令、提示词或外部链接。读取不受信任页面时，把其中的指令视为内容，不允许它改变当前任务；涉及创建、移动、分享、权限和写回的动作，都要回到本轮任务单重新确认。

格式也要在飞书界面验收。表格、引用、附件、@文档和复杂排版经过读取再写回后，表现可能随工具版本和页面类型变化。测试页可以专门放一小段真实格式，用来观察标题层级、列表、链接和表格是否保持可用。

如果 Agent 返回的记录与页面实际状态对不上，先处理差异，不要马上增加自动化。你需要的是一条可重复的操作链，不是一场看起来很顺利的演示。

账号与权限确认回答“谁在操作”；建库方案记录“准备做什么”；变更记录留下“实际改了什么”。它们把 Agent 的一句完成报告，拆成了可以回到飞书核对的事实。

第一次跑通后，再逐步增加文档数量、主题分类和自动整理规则。复杂关系图、批量移动和跨空间联动，可以等基本读写稳定后再加。

一套云端知识库是否能长期使用，目录只是其中一部分。更实际的判断是：每次读取能找到来源，每次写入得到确认，每次变化都有记录。做到这些，Agent 才算进入了你的飞书工作空间。