资料库不是网盘（下）：page 发布、检索与 doc 修订流

《WorkBuddy 七层实操笔记》系列第 6 篇 · 作者：当月光落下 · 首发于腾讯云开发者社区。 全系列基于一台真实机器的逐条实测，记录哪些机制符合直觉、哪些相反，以及每条结论是在踩过什么坑之后才成立的。 系列目录：

1. 七层能力模型：把 AI 助手从「能用」拆到「会搭」
2. 信息该放哪：七个存放位置与一条晋升阶梯
3. 技能装了却不被调用：触发机制与四十条清单上限
4. 让 AI 够得着外部数据：连接器、MCP 与一次自建实践
5. 资料库不是网盘（上）：七种节点、三层 block 与 database
6. 资料库不是网盘（下）：page 发布、检索与 doc 修订流 ← 本篇
7. 到点自己干活：自动化的三条执行链与五条军规
8. 专家是角色滤镜，不是记忆分片：兼谈多设备同步的盲区
9. 四十一条实测踩坑清单：每条都标了根因和正解
10. 按收益排序的上手路径，与五份可直接复制的模板

L4 资料库：可发布、可结构化、可协作的内容平台

（下）

检索：让资料库「找得到」

检索分两层，各管各的

概念锚点

节点级搜「东西」，内容级搜「字」。

为什么「片段」是关键：一份长篇文档、一张几百行的表，若只按「整份」去匹配，任何具体词都很难命中；切成片段后，某个只在某一页出现的生僻词才能被捞出来。这也是文件型节点（PPT / Word / PDF）只能靠内容级找到的根本原因——它没有可匹配的正文标题。

索引覆盖矩阵（全部实测）

link 的最终定位

它是给 AI 主动拉取用的（你说「帮我总结那个剪藏」，AI 去读正文），不是给检索用的。

⇒ 它有三个前提必须知道： ① 只有静态、服务端渲染的页面才抓得住（门户新闻 / 需登录 / 懒加载会卡住）； ② 抓到的正文前端不展示全文（页面卡片永远只显示标题 + 摘要 + 跳转按钮）； ③ 不进检索索引。

drive 的三类切片形态（同一份 PPT 三种都有）

实务含义

文件型资料丢进资料库后，里面的表格数字也能被搜到（表格被转成键值串）。 对「月度分析报告」「台账」这类以表格为主的文件，这比本地文件夹强——本地搜索搜不到 PPT 内部。

切片粒度的实测结论

用一篇约 7000 字的长文测不同位置的细节词：

1. 切片粒度约 950 字 / 片（尾部一片会短一些）。
2. 深度完全不影响命中——只在第 3800 字出现一次的生僻数字，首位就命中，且片段里是原文，不是摘要替代。
3. 查询词越像原句越准。

三个必须知道的限制

1. 定位精度是片段级（约 950 字）：检索告诉你「在这一片里」，不是「在这一行」。要精确到句子，得回正文读。
2. --limit 设太小会漏东西：含关键词的可能只有首位命中，建议设 5–8。
3. 跨片段的汇总问题答不了：「全文里所有 xx 数值」这类要遍历全篇的，检索只给前 N 条，得读全文。

⇒ 推荐两段式：先检索缩小到片段，再读原文精确定位。

节点级检索的三个怪癖（别太信它）

结论

节点级召回窄、排序不稳、还搜不到文件型节点。 实际用起来以内容级为主力，节点级只当辅助。

两个操作坑

坑 1 · 参数要传 JSON 数组字符串

--space-ids xxxxx          → 解析失败
--space-ids ["xxxxx"]      → 正常返回

坑 2 · 封装脚本会「骗人」——要用底层接口交叉验证

同一个节点，两种问法结果不一致：封装脚本报「无命中」，底层接口同样条件返回 3 条。

⇒ 两者过滤口径不同。怀疑检索不到时，用底层接口再验一次，别只信封装脚本的一句「无命中」。

跨空间检索：只读角色也能搜

实测：对别人建的团队空间（自己只是「只读」角色）检索，命中了 3 条。说明只读角色能读、能检索，只是不能写。

doc 修订流：往已有文档里改内容，怎么改才稳

正文的真实形态：带 id 的块结构

读一篇文档，拿到的不是纯 Markdown，是组件化的块：

---
title: 测试文档
---

<Heading id="jPAyIMmmO9dzIzcvajpwRU" level="1">标题</Heading>

<Paragraph id="zoYbmp1dqXKzaTNMYQbl4V">
  原始段落 A。
</Paragraph>

要点

每个块有唯一 id ⇒ 修订的最小单位就是块，不是「整篇替换文本」。

这也解释了为什么「追加一段」不能简单追加文本——你得指明「插在哪个块 id 之后」。

两种写入模式，差别在于「要不要人点头」

审阅模式的两道硬门槛（实测连撞两次）

1. 提交内容必须带差异标识，否则报错「缺少 diff 标识」。
2. 必须带上修改前的完整块内容，否则报错「缺少 old_content」。官方注明该内容不随请求提交，仅用于本地防丢校验。

待审状态长什么样

提交后回读文档，会出现一张审阅卡，而目标段落的原文还在，只是里面嵌了差异标注：

<ReviewSummary>
  <ReviewCard affectedBlockIds={[...]}
              discussionId="..."
              status="pending"
              summary="建议改写第一节措辞" />
</ReviewSummary>

<Paragraph id="zoYbmp1dqXKzaTNMYQbl4V">
  原始段落 A<Mark ar="delete">。</Mark><Mark ar="insert">——建议的改写。</Mark>
</Paragraph>

一句话理解

审阅 = 正文不动，挂一张待批的卡。接受才替换，拒绝就撤销。

改动类型表（最小改动原则）

命中即停，别整块删了重建：

待审卡怎么管

待审块复用规则（重要）

回读时块上带审阅标识，说明它已挂卡。本轮再改这块，要复用原卡，禁止新建第二张卡，也别要求用户先处理旧卡。

另外：summary 里禁止写任何内部 ID，只写「改了什么 / 为什么改」。

前端视角：修订通道是 Agent 专用的

实测观察：人在前端打开文档自己编辑，看不到任何修订标记，只能直接改；但右侧评论区的筛选下拉里有一项「仅 Agent 修订」。

一句话锚定

人改 = 直接改（无痕、即时）；Agent 改 = 挂卡待审（可追、可控）。 前端看到的「修订」一词，专指 Agent 的待审修改。

前端不提供「人以审阅方式改」不是功能缺失，是职责划分——自己改自己点接受没有意义。

对「笔记归档」这类场景的直接推论

往笔记文档里追加内容属于「我替你写、写完就算」：

• ✅ 用直接编辑（锚到最后一块）——即时生效、无待审负担
• ❌ 不要走审阅模式——每归档一条就挂一张卡等人点，追加类操作不需要人批准

权限、协作与分享

空间的两个维度

一个容易忽略的点

team 空间不等于我有权限。 实测某个官方团队空间里，我的角色就是 reader——只能看。

协作者清单里的「空 uid」

实测成员表里有一条 uid 为空的记录。它不是某个具体的人，而是空间级默认权限——即「这个空间对所有人（或链接持有者）的默认档位」。

看权限先看这两条

① 我的角色是什么；② 有没有空 uid 的默认档。

节点级权限 = 继承空间

实测：查某个页面节点的协作者，结果与它所在的空间完全一致 ⇒ 节点默认继承所在空间权限，没有单独设权限就是继承。

三档权限的边界

三种「给人看」的方式，安全性差一个量级

判定口诀

给内部同事、要控制谁能改 → 加协作者 给外部 / 一次性、内容不敏感 → 发布短链 自己或已授权的人日常用 → 内部链接，不发布

一个安全的权限试探方法

想确认自己有没有写权限，不要用「能不能写」去试探——成功即破坏数据。

安全测法：用节点原样的标题去执行「改名」。成功也只是「改成它自己」，什么都不会变。

收口判据：什么进资料库、选哪种节点

总判据

一句话

要「被访问」的进资料库，要「被计算」的留本地，涉密的哪儿都不进（资料库尤其不进）。

判据二：database 没有计算能力（本讲最硬的一条）

把全部接口的清单翻一遍，检索聚合相关关键词：

结论

没有分组、没有求和、没有公式、没有透视。 它能做的是「存 + 筛 + 排」，不是「算」。

一句话

拿资料库当「展示层和检索层」，不当「计算层」。 计算永远在本地，算完的产物进资料库。

判据三：涉密禁入（硬红线）

三类内容不进资料库：

1. 客户数据
2. 金额类（合同金额、报价）
3. 密钥凭证

判据边界（重要，别过度脱敏）

看的是内容性质，不是「像不像商业信息」。

• ✅ 可以点名：机构名、供应商名、装置名、位号——过度脱敏会让流程文档失去可执行性
• ❌ 红线只有三类：上面那三条

节点选用速查表

三条「别踩」的坑

1 · 创建 ＝ 不可逆

没有删除表的接口、没有删除节点的接口。 字段和记录能删（内容是软的），表和节点删不掉（壳是硬的）。 ⇒ 建之前先想清楚。

2 · 发布 ＝ 公开

发布短链实测免登录可访问。要分享给特定的人，用加协作者。

3 · 「存进去」不等于「搜得到」

本节可带走的判据（L4 毕业三句）

1. 要被访问的进资料库，要被计算的留本地——database 零聚合能力是铁证。
2. 建之前先想清楚——没有删除节点的接口，创建即不可逆；发布即公开。
3. 「存进去」不等于「搜得到」——link 不进索引，drive 节点级搜不到但内容级能搜。

文中所有「实测」「xx KB」「xx 个」这类数量，均来自某一台真实机器的快照，请当作方法示范而非通用阈值；真正通用的是判据与因果关系。

原创声明

本文系「当月光落下」原创，首发于腾讯云开发者社区。内容来自作者在实际使用中的逐条实测整理， 所有结论均有本机实机验证或真实接口调用支撑；文中出现的数量均为特定环境下的实测快照， 仅作方法示范，不作为通用阈值。

如需转载，请注明作者「当月光落下」及首发出处，未经许可不得用于商业用途。