文件:content/docs/kernel/contracts/data-engine.mdx(手写文档,非自动生成)
发现于:核对 #4419 时(PR #4459)。文档漂移先于该 PR 存在,当时没混进一个破坏性 PR。
核实基线:main @ ec975f1
摘要
文档里的 IDataEngine 代码块把四个读方法都写成两个参数,漏掉了尾部的
options?: BaseEngineOptions。真实契约四个都有。
漏掉的恰恰是 #4251 修复的那个参数——当初正因为它缺失而出过 bug。
现状对照
content/docs/kernel/contracts/data-engine.mdx:33-38:
export interface IDataEngine {
// Query
find(objectName: string, query?: EngineQueryOptions): Promise<any[]>;
findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
count(objectName: string, query?: EngineCountOptions): Promise<number>;
aggregate(objectName: string, query: EngineAggregateOptions): Promise<any[]>;
真实契约 packages/spec/src/contracts/data-engine.ts:70 / 85 / 89 / 90:
find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
findOne(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any>;
count(objectName: string, query?: EngineCountOptions, options?: BaseEngineOptions): Promise<number>;
aggregate(objectName: string, query: EngineAggregateOptions, options?: BaseEngineOptions): Promise<any[]>;
同一代码块里的写方法(insert / update / delete)都带着各自的 options,
所以读者看到的是「写方法有 options、读方法没有」——这正是 #4251 之前那个错误认知。
为什么值得单独修
这个尾参不是可有可无的细节。契约里它自己的 TSDoc 记着它的来历:
同一个 { context } 对象作为 insert 的第 3 参是正确的,作为 find 的第 3 参却被
静默丢弃,于是一个本意为 isSystem 的绕过凭空消失(控制面读取在 org-scoping hook
落地后开始返回空)。契约当时只保留了 query.context,所以每个传尾参的调用方——
包括当前用户端点的 permission-set 加载器——都得靠 any 去够它。
也就是说:文档漏掉的,正是「当初因为缺失而出 bug、后来专门补上」的那个参数。
一个照着这段文档写代码的人(或 agent)会被引回旧写法。
修法
把那四行补齐即可,纯文档:
find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
findOne(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any>;
count(objectName: string, query?: EngineCountOptions, options?: BaseEngineOptions): Promise<number>;
aggregate(objectName: string, query: EngineAggregateOptions, options?: BaseEngineOptions): Promise<any[]>;
顺带值得加一句:query.context 与 options.context 同时给出时,后者胜(契约原文如此)。
content/docs/kernel/contracts/ 不在自动生成范围内(只有 content/docs/references/ 是),
所以这是手改,不需要跑生成器。
文件:
content/docs/kernel/contracts/data-engine.mdx(手写文档,非自动生成)发现于:核对 #4419 时(PR #4459)。文档漂移先于该 PR 存在,当时没混进一个破坏性 PR。
核实基线:
main@ec975f1摘要
文档里的
IDataEngine代码块把四个读方法都写成两个参数,漏掉了尾部的options?: BaseEngineOptions。真实契约四个都有。漏掉的恰恰是 #4251 修复的那个参数——当初正因为它缺失而出过 bug。
现状对照
content/docs/kernel/contracts/data-engine.mdx:33-38:真实契约
packages/spec/src/contracts/data-engine.ts:70 / 85 / 89 / 90:同一代码块里的写方法(
insert/update/delete)都带着各自的options,所以读者看到的是「写方法有 options、读方法没有」——这正是 #4251 之前那个错误认知。
为什么值得单独修
这个尾参不是可有可无的细节。契约里它自己的 TSDoc 记着它的来历:
也就是说:文档漏掉的,正是「当初因为缺失而出 bug、后来专门补上」的那个参数。
一个照着这段文档写代码的人(或 agent)会被引回旧写法。
修法
把那四行补齐即可,纯文档:
顺带值得加一句:
query.context与options.context同时给出时,后者胜(契约原文如此)。content/docs/kernel/contracts/不在自动生成范围内(只有content/docs/references/是),所以这是手改,不需要跑生成器。