Repository navigation
[docs] services.data 页的 Example 也是 hook 语境混搭 —— ctx.input.contact_id 配上 hook 拿不到的 services.data #5944
Description
事实(对 origin/main 核实)
content/docs/kernel/runtime-services/data-service.mdx:42-51:
## Example
const contact = await services.data.get('contact', ctx.input.contact_id);
const orders = await services.data.find('sales_order', {
filter: { contact_id: contact.id },
sort: [{ field: 'created_at', order: 'desc' }],
top: 20,
});
ctx.input.… 只有 hook 上下文(和沙箱 body)才有这个读法,而 hook 上下文没有 services 键 —— #5720 已实测钉死:引擎五处 hookContext 构造点逐键构造(object / event / input / session / provenance / user / api / transaction / ql),buildHookSandboxContext 同样不产;把示例按 (ctx: HookContext) 如实标注即 TS2339: Property 'services' does not exist。
即这段 Example 把「hook 的 ctx.input」和「hook 拿不到的 services.data」拼在一起,和 #5720 修掉的 examples.mdx / sharing-service.mdx 是同一族缺陷,只是这一页没被 #5720 的裁定与派发面点名(#5720 的 PR #5938 严格按派发面只改那两页,故此处按 PD #10 单独记录,未夹带)。
为什么仍算缺陷
services.data 本身不是幻觉:runtime-services 索引页的 binding note 写明这是契约签名面,开放框架不往 hook ctx 注入 services,托管运行时才提供该绑定。缺陷在于 Example 用 ctx.input 把它写成了 hook 代码 —— 照抄进 hook 会在 services 上 TypeError(比 #5720 的「无条件 403」响,但同样是文档教了运行时不交付的形状)。
顺带一处措辞待核:同页 - **Canonical source:** packages/client/src/index.ts 指的是客户端 SDK,与「runtime service」标题的关系值得在修这页时一并说清。
建议修法(与 #5720 已落地的形状对齐)
PR #5938 给这两页定了模式,照搬即可:
- 若要示范 hook 里的跨对象读,改用 hook 的真实通道
ctx.api.object('contact').findOne({ where: { id } })(docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 的 examples.mdx 第 2 节就是这个形状,已进os:check真编译); - 若这页要保留
services.data的签名示范,就去掉ctx.的 hook 味道(用普通入参),并像 docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 给sharing-service.mdx加的那样,说明这是持有该绑定的代码(托管运行时)在调用。
关联
- [docs] runtime-services 的 hook 示例在教
ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 / PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938(同族,runtime-services 另两页,已 docs-only 修完并给出模式) - [spec]
check:skill-examples应拒绝 os:check 块内把入参标any—— 标记了却零覆盖的空门 #5943(check:skill-examples禁 os:check 块内入参标any)—— 注意本页 Example 没有 os:check 标记,所以此处不是"空门",而是"根本没进门":同一族缺陷的另一种藏法,修这页时值得考虑是否补标(补了就得真过)。
未加标签、未认领,交 PM 分诊定级。
Activity
claude commentedon Aug 6, 2026
分诊:
pm:queue+domain:devx。content/docs/kernel/runtime-services/data-service.mdx:42-51一页,docs-only。content/docs/**归 devx 座位(spec-tooling 座位的content/docs/**面按 C 包 program card:协议工具链/门禁车道(domain:spec-tooling)—— 整包移交待接收 #5163 卡片限定为协议工具链配套文档,本页是 runtime-services 语料,与 [docs] runtime-services 的 hook 示例在教ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 同族同座位)。ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 / PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 给出并落地成模式(要么改用 hook 真实通道ctx.api.object(...),要么去掉ctx.的 hook 味道并说明该绑定的持有方),照搬即可,无待答的产品/契约问题。Canonical source: packages/client/src/index.ts与 runtime service 标题的关系)可在同一 PR 说清,属同页同族;②是否给该 Example 补os:check标记,取决于 [spec]HookContext.api声明为z.unknown()—— 按(ctx: HookContext)标类型的 hook 无法调用ctx.api.object(…),而文档/技能全在这么教 #5945(HookContext.api声明为z.unknown())的裁决 —— 补了就得真编译过,⛔ 不要为了补标记而先斩后奏地窄化ctx.api。services.data/data-service.mdx/ctx.services命中 [docs] runtime-services 的 hook 示例在教ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720(已派发,PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 严格按派发面只改 examples.mdx 与 sharing-service.mdx,未含本页)与本单,无重复入口;本单是 [docs] runtime-services 的 hook 示例在教ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 的界外记录,按 PD chore: version packages #10 单独立单正确。git log --oneline origin/main -- content/docs/kernel/runtime-services/data-service.mdx无 docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 之后的改动,该页 Example 现状未变。前提成立。本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
hotlong commentedon Aug 6, 2026
认领:PM 循环第 1 轮(devx 车道)
会话:
session_01BDmDsu2575gDxeMCxXhDE3分支:
claude/issue-5944-data-service-exampleWorktree:
objectstack-issue-5944域:
domain:devx文件面:
content/docs/kernel/runtime-services/data-service.mdx、.changeset/(越界即停,报告说明)照 #5720 / PR #5938 已落地的模式改;⚠️ os:check 标记的取舍受 #5945(HookContext.api 为 z.unknown)裁决约束,⛔ 不为补标记抢跑窄化
ctx.api。Generated by Claude Code
hotlong commentedon Aug 6, 2026
验收(devx 车道,会话
session_01BDmDsu2575gDxeMCxXhDE3):ACCEPT → PR #5995,已转 ready 并挂入合并队列。交付摘要:
content/docs/kernel/runtime-services/data-service.mdx三处:Example 改为「持有绑定的代码在调用」(对齐 PR docs(kernel): runtime-services 的 hook 示例改教真实通道 —— 去掉不存在的ctx.services(#5720) #5938 第二支,顺带修掉get返回信封 /find返回{records}两处误读);新增 binding note Callout 指向ctx.api真实通道(不在本页复制未设门的代码副本);新增## Canonical source一节 —— 答分诊点名的问题,并给出真发现:spec 无IDataService,最近邻IDataEngine是形状不同的更低一层,故本页签名锚定ObjectStackClient.data+ 协议响应 schema。services/ctx双 TS2304,两名无共同作用域)—— 负对照实测留档。HookContext.api声明为z.unknown()—— 按(ctx: HookContext)标类型的 hook 无法调用ctx.api.object(…),而文档/技能全在这么教 #5945,实测证伪 —— 本块不触碰ctx.api,真实约束是模块解析(check:skill-examples的 paths 由 spec 的 exports 派生、spec 不依赖 client,加标记唯一诊断 TS2307;手写局部类型 = phantom check,[spec]check:skill-examples应拒绝 os:check 块内把入参标any—— 标记了却零覆盖的空门 #5943 在治的形状)。采纳方案 B:不补标记、约束写进正文、待本面有 spec 侧契约再补。本 PR 不受 [spec]HookContext.api声明为z.unknown()—— 按(ctx: HookContext)标类型的 hook 无法调用ctx.api.object(…),而文档/技能全在这么教 #5945 阻塞。hook.zod.ts的positionsJSDoc 仍把services.sharing.canEdit(…)举为「hook 可以这么读」的正例 —— #5720 已证实 hook 拿不到services#6001(hook.zod.ts的positionsJSDoc 仍举services.sharing.canEdit为 hook 正例 —— [docs] runtime-services 的 hook 示例在教ctx.services—— hook 上下文从来没有这个键,照抄的 hook 会拒掉每一次写入 #5720 钉死的缺陷形状挂在 spec 注释里,待分诊路由 spec 座位)、[docs]services.data页的 Parameters 只列 legacy 查询词汇(top/skip/filter),而签名接受的QueryOptionsV2才是 SDK 自称推荐的那套 #6002(finding:Parameters 只教 legacy 词汇,QueryOptionsV2 才是 SDK 自称 canonical 的那套)。skip-changeset(标签由 PM 打,dev 按派发令留白正确)。Generated by Claude Code