资料库不是网盘（上）：七种节点、三层 block 与 database

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

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

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

资料库 vs 本地文件：不是「另一个存放位置」

误解

「资料库和本地文件夹本质上是一样的，都是输入输出文件的存放位置。」

真相

方向对，性质错。 从「AI 读写的输入输出」这个视角两者确实都是内容源；但性质完全不同：

正确表述：资料库是可发布、可结构化、可协作的内容平台；本地是大容量、可程序处理、零依赖的存储。

资料库有、本地完全没有的能力

调用成本：方便有代价

由此得到的一条可用性建议

资料库依赖网络与短期凭证。重要内容应在资料库之外保留本地副本或镜像，不要把资料库作为唯一存放处。

这与「涉密不进资料库」并不矛盾——前者是可用性问题，后者是安全性问题。

判据表

一句话：要「被访问」的进资料库，要「被计算」的留本地。

七种节点：先看清「容器」

核心机制一：所有节点底层统一是「块」

与直觉相反的发现

逐个查各类型节点，folder / doc / web / database / link 全部底层是同一种存储表。

⇒ kind 只是逻辑类型标记，不是不同的存储表。 这跟「每种节点一张表」的直觉相反——底层统一，kind 只决定上层渲染和可用操作。

核心机制二：三层 block

「块」这个词在资料库里有两个层次，这是理解「内容怎么存」的钥匙。加上检索用的切片，合起来是三层：

由这个模型直接推出的两个结论（都很重要）

1. 有正文 ≠ 能搜到。 写入正文和建索引是两步，不是一步。
2. 检索到切片 ≠ 拿到原文。 切片带加工（可能含 AI 概括），要原文得回到中间层读。

⇒ 检索走底层（切片），读取走中层（正文块），是两条独立通道。

核心机制三：database 挂在 web 节点下面

误解（初版文档就是这么写错的）

「database 不在目录树里，靠横向引用。」

真相

逐个查 database 的父节点，发现它们全部指向 web 节点。也就是说：web.nodes（从父看子）和 database.parentId（从子看父）是同一个关系的两个方向。

database 在目录树里，位置是「web 节点的子节点」，只是它的父是 web 而不是 folder，所以在 folder 的直接子节点列表里看不到它们。

教训：下「不在树里」这类结论前，要把引用链展开到最底层。 当时只展开 folder 一层就下了结论。

核心机制四：上传按扩展名分流

同一个动作「上传文件」，系统按扩展名路由到不同的节点类型：

实用推论

扩展名决定它变成什么能力。 想把一个压缩包当「文件」存进网盘，就不能用 .zip 后缀——它会被导入成页面。改个后缀（如 .dat）即可走网盘通道。 这是实测中反复用到的一个技巧。

三个数字对不上：前端 5 项 ≠ 后端 8 种

很多人会注意到：前端新建菜单只有 5 项，和「七种节点」对不上。原因是三个数字各数各的：

对不上的三个原因：① 「上传和导入」一项分流出 4 种 kind；② smh 历史遗留禁止新建，前端根本没有入口；③ web(page) 没有独立新建按钮，只能靠上传 html 得到。

database：带 schema 的轻量数据库

误解

「database 就是一个在线版的 CSV。」

真相

它是「带 schema 的轻量数据库」——差别在于字段有类型约束，筛选是类型感知的。这是它碾压本地表格的地方。

但也要知道它的短板：没有聚合能力（见 6.8）。

接口按「管什么」分三组

单次批量写入上限约 1–100 条。

字段类型：这是它最强的地方

筛选也是类型感知的——筛选条件是一棵可任意嵌套的树形结构，且每类字段有专属操作符：

三个实测踩到的坑（文档不会明说）

坑 1 · 写入结构 ≠ 读取结构（读写不对称）

写入：{"名称": {"text": "甲任务"}, "数量": {"number": 3}}   ← 每个值是 {类型: 值}
读取：{"_id": "xxx...", "名称": "甲任务", "数量": 3}        ← 直接是值，且 id 字段名不同

坑 2 · 记录 id 的字段名，读和写不一样

读回来的记录 id 字段名、更新时传参的字段名、以及实际的记录主键名——三者在不同接口里的叫法并不一致。

实测：用错误的字段名会报「id is empty」，只有正确那个名字才通过。踩一次记一次，别照着读到的结构去写。

（本条在不同版本 / 不同接口上出现过变化，是全文被推翻次数最多的一条——务必以当场实测为准，不要照抄记忆。）

坑 3 · 选项 id 由服务端生成

新增选项可省略 id，但成功响应的 schema 才是最终结构与 id 的唯一可信来源；已有选项的 id 永久不变，改字段时必须原样复用，禁止更换。

坑 4 · 写入时值的类型必须与字段类型匹配

实测：给 select / date 类型传了对象或数组，服务端报解析错误。按字段类型给对的形态是硬要求。

硬边界：字段和记录能删，表不能删

原因（一条贯穿全文的规律）

表是节点（壳），节点删不掉；字段和记录是内容，内容可删。

⇒ 壳不可删，内容可删。 这与「API 建的节点删不掉」是同一条规律的两种表现。

推论：建表前想清楚——它跟建文档、建链接一样，是不可逆写操作。

page 与发布：托管站点 + 版本 + 发布三件套

一句话定位

page 不是「资料库里的一个 HTML 文件」，是「托管在平台上的一个可运行站点」，外加一整套版本 / 发布机制。

三处 URL，别再混为一谈

同一个页面节点，实测能拿到三个不同的地址：

三个是三套东西：域名不同、权限不同、命中的版本也可能不同。

两套版本号：节点版本 ≠ 页面版本

节点信息      → version: 8    ← 节点版本
页面产物列表  → version: 25   ← 页面产物版本

8 ≠ 25。 页面每改一次，产物版本 +1；节点版本只在节点元数据变化时动。 ⇒ 看「页面改到第几版」要看产物版本，不是节点版本。

页面怎么读到数据：SDK 契约（本节最实用的一段）

页面里读数的写法（从真实产物里抠出来的）：

var DATABASE_ID = "<databaseId>";            // 必须硬编码
var db = window.__SMART_PAGE__.database;

db.query({ databaseId: DATABASE_ID, pageSize: 200, startCursor: cursor })
//  → { results: [...], nextCursor: "...", hasMore: true }

实测页面用到的 SDK 方法共 6 个：query() / getSchema() / addRecord() / updateRecord() / deleteRecord() / onUpdated()。

两条硬规则

1. databaseId 必须硬编码（不能动态推断），但字段列表 / 选项要在运行时读 schema——这样以后加字段页面自动生效，不用改代码。
2. 查询是游标分页，不是一次拿全。少数据一页够，几百条就得递归翻页，且要加死循环保护。

另外：页面产物每个 DOM 元素都带 data-page-node-id 标记，这是给增量编辑做 diff 用的（改一个按钮时只传那一个块，不整包覆盖）。页面头部引用的 SDK 由平台运行时注入，页面源码里没有它的实现。

发布周期：五步实测

关键安全事实：发布 = 公网免登录可见

实测直接抓取已发布的短链：能抓到内容、无需登录。

⇒ 发布不是「发给指定的人」，是「挂到公网上」。 发布 = 公开。

涉密内容一律不发布。要分享给特定的人，用「加协作者」，不用发布。

一个容易误判的现象

「手机上能打开看板」不等于「已经发布了」——实测某看板从未发布过，手机上看的是资料库内打开（节点页）。这是对的，数据没有暴露到公网。

覆盖同一个页面，而不是新建

关键操作纪律

导入页面时必须指定「覆盖哪个节点」。 不指定就会新建一个节点——而资料库没有删除节点的接口，每跑一次建一个新的会永久堆积。

实测：首次是「新建」，第二次是「覆盖」，节点 id 不变，目录下只有一个看板节点。

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

原创声明

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

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