Repository navigation
AGENTS.md 的 ObjectQL 范例教的是 broker.find(name, { filters }) —— 本仓无此调用面,谓词键也不是 filters,且对象名没带 crm_ 前缀 #855
Description
Activity
[PM 认领 · R20] session_01VHrPAGEgFDoHjphqYG4BMa · 分支
claude/issue-855-agents-md-objectql-example· 文件面:AGENTS.md(仅 ObjectQL 范例及其直接说明)+ changeset裁定与边界(与 #852/PR #857 同处置逻辑:binding 指令文件的硬错误,最小事实修复,措辞维护者可否决):
- 范例按真实读路径改写:三处失真逐一修——
broker→ 实测的真实调用形状(hook/action 上下文的ctx.api.object('crm_x').find({ where: … }),以你在src/**实测的主流写法为准);谓词键filters→where(filters只是 HTTP query-param 的已弃用别名,进程内静默错读,本仓.changeset/hook-query-where-not-filter.md记过账);对象名补crm_前缀(同文件第 59 行的强制规则)。 - 实测为据:PR body 需给出
broker在 src/ 零命中、真实调用形状的 grep 样本(≥2 处真实文件行)、以及filters别名出处(protocol.zod.ts:326-327)。 - 最小改动:只动范例块及直接说明句;AGENTS.md 里 action 文件后缀自相矛盾：目录图写
*.actions.ts,协议与流程写*.action.ts,磁盘上 6:0 全是复数 #856(后缀 3:1)已立单勿动;其它疑似过期指令 out_of_scope_findings 报回。 ⚠️ 基线取最新 main(docs(agents): 把 Schema Validation 清单第 3 条指向真实存在的 schema (#852) #857 刚改过 AGENTS.md 的 Schema Validation 清单,确认无块重叠后再动手)。
⛔ 不升级 @objectstack/*;不动
content/docs/releases/、src/**、content/**;changeset 站内路径反引号;控制字节自扫;JSON 报告按标准 schema。
Generated by Claude Code
- 范例按真实读路径改写:三处失真逐一修——
[PM 验收] PR #862 ACCEPT — 已转 ready 并挂 auto-merge(session_01VHrPAGEgFDoHjphqYG4BMa)
复核结论:
- 三处失真的证据链完整:
broker零命中带 60 命中反空跑对照(hook 43 + action body 17,含 issue 点名两处的现行行号);filters追到protocol.zod.ts:326的已弃用 HTTP 别名(值是 JSON 字符串,连单数filter都不是进程内键),叠加 TS2353 探针证明HookQuery编译期拒绝;crm_前缀与 5 行外的规则自洽。 - 谓词值形状的判断披露得当:AST 数组形平台层合法故不列为第四处失真,但
ctx.api60 处调用零使用、且不可赋给HookQuery['where']——范例职责是给 agent 抄,取实际在用的形状,论证成立。 - 三次自我更正全部留档,且最要紧的一次改对了方向:最终措辞把
where-only 规则限定在ctx.apisurface,并点名 flow 节点 config(filter:×44,schema-unvalidated bag)与 page 组件(AST 数组形)是不同拼法的合法面、明令「不要把一个面的拼法修进另一个面」——不限定作用域的版本会诱发下一个 agent 的批量误修,这一步避免了新的 AGENTS.md 的 ObjectQL 范例教的是broker.find(name, { filters })—— 本仓无此调用面,谓词键也不是filters,且对象名没带crm_前缀 #855。curl 403 假阳性的公开更正也记一笔诚实分。 - CI 实测 8/8 绿(最终 head 7005824,含三次修正提交);文件面 2 个与申报一致;与 docs(agents): 把 Schema Validation 清单第 3 条指向真实存在的 schema (#852) #857 改动块无重叠。
无新增越界发现(#856 去重正确)。
Generated by Claude Code
- 三处失真的证据链完整:
- added a commit that references this issue
on Sep 6, 2026
来源：#852 实施过程中通读
AGENTS.md时发现（只报不改，#852 的边界是「只动 Schema Validation 清单第 3 条」）。基线origin/main= 9d2c787。事实
AGENTS.md§「💻 Tech Stack & Protocol」第 2 条（约第 61-64 行）：这一行同时踩了三点，全部实测于 17.0.0-rc.2 + 当前
src/：调用面不存在于本仓：
grep -rn "broker" src/ --include=*.ts→ 0 命中。本仓的真实读路径是ctx.api.object('crm_x').find({ ... })（例：src/objects/campaign.hook.ts:68、src/objects/lead.hook.ts:84）。谓词键不是
filters：本仓自己的.changeset/hook-query-where-not-filter.md记录了这条教训——17 处 hook 侧调用曾把谓词写成filter:，findOne把 query 直接摊进 AST 从不做别名，谓词整个消失并返回该对象第一行；count只读query.where，于是统计全表。既不报错也不返回null。规范侧的filters（复数）确实存在，但那是 HTTP query-param 的已弃用别名（spec/src/api/protocol.zod.ts:326-327，值是 JSON 字符串），不是进程内 query 对象的键。范例给的恰是进程内调用。对象名违反同文件第 59 行的强制前缀：
'opportunity'没有crm_前缀，而同一份 AGENTS.md 第 59 行写着「All HotCRM business object names MUST use thecrm_prefix and the prefix MUST be written explicitly in source」，真实对象名是crm_opportunity（pnpm validate报 17 Objects，全部crm_*）。影响
与 #852 同类：这是给 agent 看的 binding 指令，且是它给出的唯一一条 ObjectQL 调用范例。照抄的失败方式分两档——
broker和crm_前缀会在 typecheck/运行时立刻炸（吵闹、可发现）；而filters谓词键是静默的：按.changeset/hook-query-where-not-filter.md实测，findOne会返回错的记录、count会数错，不报错不抛异常。本仓已经为同一形状的错误付过一次账。建议改法（未做）
把范例换成本仓实际在用、且已被测试覆盖的形状，例如
ctx.api.object('crm_opportunity').find({ where: [['amount', '>', 50000]] })（以改动时实测的 hook 调用为准，不要照抄本行）。属于 binding 指令文件改动，措辞留给维护者定。Refs #852