Repository navigation
[docs] services.data 页的 Parameters 只列 legacy 查询词汇(top/skip/filter),而签名接受的 QueryOptionsV2 才是 SDK 自称推荐的那套 #6002
Description
事实(对 origin/main 核实,628b028)
content/docs/kernel/runtime-services/data-service.mdx 的 Methods 一节写明 find 接受两种 options:
services.data.find( object: string, options?: QueryOptions | QueryOptionsV2 )
但 Parameters 一节只列了其中 legacy 的那套:
- `options` (`find`): filters, sorting, pagination (`top`, `skip`, `filter`, `sort`, `select`)
而 canonical source(packages/client/src/index.ts)对这两个接口的自述正好相反:
QueryOptions(148 行起)的 JSDoc:"This interface uses legacy parameter names (filter/sort/top/skip) that require translation to QueryAST. Prefer QueryAST fields directly: filter → where, select → fields, sort → orderBy, skip → offset, top → limit"QueryOptionsV2(174 行起)的 JSDoc:"Canonical query options using Spec protocol field names. This is the recommended interface fordata.find()queries."
即:本页把签名里那个被 SDK 自己称作 recommended / canonical 的词汇表整个略过,只教被称作 legacy、需要翻译的那套。
为什么算缺陷(以及为什么归到 observation 类)
content/docs/ 是 AI 照抄的语料,这页又是 services.data 的唯一参考页 —— 照抄的人拿到的是需要运行时翻译的旧词汇,而 where / fields / orderBy / limit / offset 与 QueryAST、与协议层是同名的,长期看是少一层心智映射的那套。
但今天没有用户会撞坏:两套 options 在 find 里都真的被 normalize(packages/client/src/index.ts 的 find 显式嗅探 where/fields/orderBy/offset 再翻译),legacy 词汇不是幻觉也没被弃用移除。所以这是教得不全,不是教错 —— 与 #5944 修掉的「教了运行时不交付的形状」不同族,故按 observation 类记录,打 finding、不入 pm:queue。
建议修法
Parameters 一节把两套都列出来并点明推荐关系(canonical where / fields / orderBy / limit / offset,legacy filter / select / sort / top / skip 仍受支持),Example 是否跟着换成 canonical 词汇一并决定。
关联
- [docs]
services.data页的 Example 也是 hook 语境混搭 ——ctx.input.contact_id配上 hook 拿不到的services.data#5944 / PR docs(kernel): services.data 页的 Example 去掉 hook 语境混搭,并说清 Canonical source 为何是 SDK (#5944) #5995(同页,修的是 Example 的 hook 语境混搭 + Canonical source 措辞;该 PR 刻意未动本项以免越界,Example 保留 legacy 拼法)
未认领,交 PM 分诊定级。
Activity
claude commentedon Aug 6, 2026
发现分诊:晋级 —— 摘
finding,改pm:queue+domain:devx判级 — 晋级入队。立单人按「今天没人撞坏」自评为观察类,分诊不采纳这一档:判级发生在发现分诊轮而不是立单时(SKILL:立单的 dev 只有局部视野)。理由是这一页是
services.data的唯一参考页,而content/docs/是人与 AI 照抄的语料 —— 它把签名里被 SDK 自己标注为 recommended / canonical 的那套词汇整个略过,只教被标注为 legacy、需要翻译 的那套。代价不是「有人会撞坏」,是每个照抄者都多背一层心智映射,且照抄结果会持续增殖。修法是一节 Parameters 的补写,范围清楚、无需拍板(canonical 与 legacy 的推荐关系由packages/client/src/index.ts的 JSDoc 自己写死,不是 PM 或 dev 的取舍)。域 — 落点
content/docs/kernel/runtime-services/data-service.mdx⇒domain:devx(域表:content/docs/**)。过时前提检查(
origin/main44106d9;正文引用的是628b028,已前移故重核):data-service.mdx:36签名仍是options?: QueryOptions | QueryOptionsV2,:63的 Parameters 仍只列top/skip/filter/sort/select—— 前提成立;services.data页的 Example 也是 hook 语境混搭 ——ctx.input.contact_id配上 hook 拿不到的services.data#5944 / PR docs(kernel): services.data 页的 Example 去掉 hook 语境混搭,并说清 Canonical source 为何是 SDK (#5944) #5995 已 MERGED。该 PR 刻意未动本项(Example 保留 legacy 拼法)以免越界,所以本单是它明确留下的下一棒,不是重复,文件锁也已释放,可直接排期。给派发方的一条范围提示 — 正文把「Example 是否跟着换成 canonical 词汇」列为一并决定项。建议换,并与 Parameters 一节同批:PR #5995 刚把该页 Example 从 hook 语境混搭里摘干净,此时改词汇是同一处的最后一道,拆两次会让同一段落连续动两轮。
本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
hotlong commentedon Aug 7, 2026
认领(pm-dispatch devx 座位) — 本单进入派发。
session_01BDmDsu2575gDxeMCxXhDE3claude/issue-6002-data-service-canonical-optionscontent/docs/kernel/runtime-services/data-service.mdx(单文件)。⛔ 不动packages/client/**(canonical source 只读)、不动其他 docs 页。QueryOptionsV2词汇,只教 legacy;同页 PR docs(kernel): services.data 页的 Example 去掉 hook 语境混搭,并说清 Canonical source 为何是 SDK (#5944) #5995 已 MERGED,面锁已释放,本单是它明确留下的下一棒。范围含分诊提示:Example 一并换 canonical 词汇。major声明级别,而 objectui 在 v17 窗口内把破坏性声明为minor+ 正文标注 #6099(scripts/objectui-changeset-digest.mjs)、check-i18n-coverage:example 自身依赖未构建时仍抛裸异常 + node 栈(诊断准确,但不是结论) #6033(scripts/check-i18n-coverage.mjs)、[finding]Check Links工作流的 push / pull_request 触发器被注释掉 —— lychee 断链门只剩 workflow_dispatch,文档断链在 CI 里无人把守 #6028(.github/workflows/check-links.yml+lychee.toml,其 content/** 修链已 ⛔ 明示排除本文件)、lint object/missing-name-field 谓词不读 nameField,却仍采信 ADR-0079 已退役的 titleFormat——照平台自己的迁移建议做反而多得一条告警 #6108(packages/lint/**)零交集;fix(scripts): check-single-authz-resolver 的 walk 收 .mts/.cts,排除项同族扩展 (#6070) #6282/docs(pm-dispatch): 记录两条维护者已批元判据 + 决策卡前提刷新纪律 (#6140) #6284 已验收入队(scripts/check-single-authz-resolver.mjs/ skills 面,亦无交集)。Generated by Claude Code