docs(kernel): services.data 的 Parameters 补上 canonical QueryOptionsV2 词汇,Example 同批换用 (#6002)

[hotlong]

Fixes #6002

content/docs/kernel/runtime-services/data-service.mdx 的 Methods 写明 find 接受两套
options,但 Parameters 只教了其中被 SDK 自己标注为 legacy 的那套。本 PR 把两套都列出来、
点明推荐关系,并按分诊提示把 Example 同批换成 canonical 词汇。

推荐关系不是本 PR 的取舍 —— 它由 packages/client/src/index.ts 的 JSDoc 写死,本 PR
只是把它如实转述到唯一的参考页上。

前提复核(在 worktree 实测,基线 origin/main a682670)

事实	位置(改动前)	结论
签名接受两套 options	data-service.mdx:36 — options?: QueryOptions | QueryOptionsV2	成立
Parameters 只列 legacy	data-service.mdx:63 — (`top`, `skip`, `filter`, `sort`, `select`)	成立
QueryOptions 自述 legacy	packages/client/src/index.ts:138-148	成立
QueryOptionsV2 自述 recommended	packages/client/src/index.ts:162-174	成立
同页 PR #5995 已 MERGED,面锁释放	commit f192981	成立

issue 正文引用的行号(148 / 174)与今天一致,四条陈述逐字复核无漂移。

字段名 ↔ 接口定义映射(逐字取证)

页面新表里的十个字段名,每一个都在 packages/client/src/index.ts 的对应接口里逐字存在:

页面列出的名字	所属接口	定义行
where	QueryOptionsV2(:174)	:176
fields	QueryOptionsV2	:178
orderBy	QueryOptionsV2	:180
limit	QueryOptionsV2	:182
offset	QueryOptionsV2	:184
filter	QueryOptions(:148)	:151
select	QueryOptions	:149
sort	QueryOptions	:154
top	QueryOptions	:155
skip	QueryOptions	:156

零个「页面写了但接口没有」,零个反向缺失。

「两列等价」是实测的,不是推断的

页面写下 "normalizes it into exactly the transport parameters the legacy names produce"
之前,用一次性探针(vitest + stub fetch,读 find 真正发出的 query string;跑完即删,
未入库)量过:

canonical  { where, orderBy, limit, offset, fields }
  -> top=20&skip=5&sort=-created_at&select=id%2Camount&contact_id=c1
legacy     { filter, sort, top, skip, select }
  -> top=20&skip=5&sort=-created_at&select=id%2Camount&contact_id=c1

两串逐字节相同 —— 所以"等价"这个词用得起。

同一次实测也支撑了页面第三段「Use one column per call」:

{ where, top: 20 }     -> contact_id=c1        (top 被丢)
{ filter, limit: 20 }  -> contact_id=c1        (limit 被丢)

混写会静默丢键,两个方向都会。页面因此只说"整个 options 对象一起迁移",没有教任何混合写法。

Example before / after

改动是三个 key 的同义替换,加一行说明注释;查询语义、字段、排序方向、条数全部不变:

before

    filter: { contact_id: contact.id },
    sort: [{ field: 'created_at', order: 'desc' }],
    top: 20,

after

    where: { contact_id: contact.id },
    orderBy: [{ field: 'created_at', order: 'desc' }],
    limit: 20,

orderBy 的元素形状不变 —— SortNode 是 { field, order }
(packages/spec/src/data/query.zod.ts:53-66),sort 与 orderBy 声明的是同一个类型。

与 #5944 / PR #5995 的边界

PR #5995 在本页新增 57 行(Callout、"不是 hook body" 的语境、ctx.api 指路、Canonical
source 一节、os:check 标记的说明段),并刻意保留了 Example 的 legacy 拼法。逐行核对本 PR
对这 57 行的影响:

• 53 行逐字存活;
• 4 行被本 PR 改动,全部落在 Example 的 options 对象内:三个 legacy key,以及紧邻其上
  那行注释(是扩写,不是回退)。

改这 4 行正是分诊 2026-08-06T14:56Z 的明确指示(「建议换,并与 Parameters 一节同批……拆两
次会让同一段落连续动两轮」)。#5995 落定的语境一处未动。

Parameters 里被替换的那条 options bullet 不是 #5995 写的,是它之前就存在的原文 —— 也就是
本 issue 的靶心。

门禁(均在 git add 之后跑)

门	EXIT	输出摘要
pnpm check:doc-authoring	0	365 files clean — no bare metadata literals
pnpm check:role-word	0	OK (44 baselined file(s), no new occurrences)
pnpm check:nul-bytes	0	OK (scanned 5965 tracked text file(s) ... no raw ASCII control bytes)
pnpm check:docs-audit-scope	0	scope is in sync with content/docs/: 178 hand-written doc(s)

另跑了一项不是仓内门禁的自查:用仓库自己的 @mdx-js/mdx@3.1.1 编译改后页面,
MDX_PARSE_OK(14455 bytes)。MDX 语法错误是这四道门都不覆盖的一类,值得单独证一次。

check:skill-examples 不适用:它只编译带 {/* os:check */} 标记的块,本页的 ts 块刻意
不带该标记(页面自己有一段解释为什么)。

实测出的代码漂移(已单独立单,不在本 PR 里修)

上面那次探针顺带量出两处 packages/client 的实现缺陷。本单文件面只有 content/docs/**,
且按 contract-first 不在文档侧糊补丁,故单独立单:

• [client] data.find 的 canonical options 探测漏掉 limit;QueryOptionsV2.expand 声明了但从不落到传输参数 #6322(具体缺陷,未打标待 PM 分诊)—— find 的 canonical 探测键只有
  where/fields/orderBy/offset,漏了 limit:data.find('task', { limit: 20 })
  这种单键调用走 legacy 分支后无人读 limit,静默丢弃,返回服务端默认页大小、HTTP 200。
  另 QueryOptionsV2.expand(:186)声明了但两条分支都不映射,一个字符到不了 wire。
• [docs] services.data 页把 find 当稳定主入口,而 canonical source 给 find 打了 @deprecated 指向本页未记载的 data.query() #6323(observation,finding 标签)—— 本页把 find 当稳定主入口记载,而 canonical
  source 给 find 和 QueryOptions 都打了 @deprecated 指向 data.query()(路线见已关闭的
  [讨论&决策] 前后端查询协议/OData vs QueryAST 规范化与长期归一方案 #986),而 data.query() 本页只字未提。改法需要先定性 find 是否退场,故不自动入队。

给 review 的一个判断点:#6322 的 A 项与本页有交互 —— 本页从此正面推荐 canonical 列,
照抄者会开始直接写 limit,命中面变大。本 PR 没有在页面上加这条 caveat,理由是分诊已
明确「按现状写并在 PR 正文记录漂移」,且在参考页里写下消费侧的规避写法正是 contract-first
要避免的形状。若 #6322 一时排不上,可以再补一条 #5638 式的实测注记(那种形状本页已有先例)。

不在本 PR 里

• 不动 packages/client/**(canonical source 只读)
• 不动本页其他章节(Callout / Methods / Canonical source / Returns / Typical Errors /
  os:check 说明段)
• 不动其他 docs 页(已核:content/docs 里没有第二处用 legacy option key 教 data.find 的
  页面;protocol/objectql/query-syntax.mdx 讲的是更低层的 IDataEngine.find,不同 surface)
• 不动 content/docs/releases/**
• 无 .changeset/:纯文档、不发布任何包 ⇒ skip-changeset

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 1:50pm