You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e516cf2
Browse filesBrowse the repository at this point in the historyBrowse files
docs(skills): objectstack-query examples under check:skill-examples (20 of 42 blocks marked) (#31507)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} -->
_Requested by **Steedos** · [project
thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbGpTJCNsaq61jSt8xxWSP4N)_
Refs #31112 (slice 1 of a per-skill split: item 4, objectstack-query
only; the card stays open)
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:objectstack-query 技能里 42 段 TypeScript 示例中,能独立成立的 20 段现在加了检查标记,CI
会把它们当真代码编译;其余 22 段(纯片段、故意写错的 ❌/✅ 对照)不标记,每个文件用一句话说明。
- 为什么改:AI 读技能写查询时照抄示例;以前这些示例没人编译,键名改了或被移除也不会报错。现在示例里写错键名、用已移除的键(如
`cursor`、`array_agg`)会在 CI 直接变红。
- 风险与回滚:只改技能文档,不动任何运行时代码;示例文字只多了两行类型声明或一行类型标注,教的规则不变。回滚即还原本 PR。
- 先看:`skills/objectstack-query/SKILL.md`(8
处标记与声明行)、`skills/objectstack-query/rules/pagination.md`(字面量改成带类型的
`const`)、`skills/objectstack-query/rules/filters.md`(token
余量为零,只换了一句开头)。
- 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为
`✅ 307 prose examples type-check across 3 surface(s)`。
- 需要你做的:受管面(skills/** 为 Tier H),请审阅后批准或亲手合并。
## What changes
- 20 of 42 fenced `ts`/`typescript` blocks in `skills/objectstack-query`
now carry the opt-in `check:skill-examples` marker on the line above the
fence.
- Engine-call blocks gain two lines, `import type { IDataEngine } from
'@objectstack/spec/contracts';` and `declare const engine: IDataEngine;`
(plus one `declare const` for a free variable in two blocks: `name`,
`pageNumber`).
- Standalone query literals become `const NAME: QueryInput = { ... };`
with `import type { QueryInput } from '@objectstack/spec/data';`.
- Left unmarked, said once per file: the bare `{ where: ... }` option
fragments in `SKILL.md`; all seven `where` fragments in
`rules/filters.md`; the ❌/✅ Common Mistakes pairs in
`rules/aggregation.md` and `rules/pagination.md` (the ❌ half is wrong on
purpose), plus pagination's OData `{ limit }` / `{ top }` pair and its
REST request/response sketch.
- Example fixes: none. Every marked block compiled as written; no rule's
teaching changed.
| File | marked / blocks before | after |
|:--|:--|:--|
| `SKILL.md` | 0 / 14 | 8 / 14 |
| `rules/aggregation.md` | 0 / 11 | 8 / 11 |
| `rules/filters.md` | 0 / 7 | 0 / 7 |
| `rules/pagination.md` | 0 / 10 | 4 / 10 |
### `skills/**` readings (repo `objectstack-ai/objectstack`,
`origin/main` a61ddc9 vs this head)
| File | lines before → after | tokens before → after (ceiling) |
|:--|:--|:--|
| `SKILL.md` | 413 → 439 | 4329 → 4596 (5547) |
| `rules/aggregation.md` | 241 → 262 | 1860 → 2096 (2357) |
| `rules/filters.md` | 211 → 211 | 2477 → 2482 (2482) |
| `rules/pagination.md` | 206 → 215 | 1158 → 1289 (1382) |
| whole bundle, sum of every `SKILL.md` | 4566 → 4592 | 232095 → 233164
bytes |
No ceiling is raised. `filters.md` pays its one sentence by replacing
its opening line ("Comprehensive guide for building ObjectStack query
filters."), which carried no rule; `aggregation.md` and `pagination.md`
replace their equivalent opening lines the same way.
## Tests
- `pnpm --filter @objectstack/spec check:skill-examples` exit 0: `✅ 307
prose examples type-check across 3 surface(s) — every marked block
parsed, so tsc ran the SEMANTIC pass on all of them`.
- Reverse check (committed first, restored with `git checkout HEAD --`,
`git status --porcelain` empty after): planting `bogusKey: 1` in the
SKILL.md search call, `cursor: 'abc'` in a pagination literal and
`function: 'array_agg'` in an aggregation literal turned the gate red
with exactly three diagnostics: TS2353 unknown key at `SKILL.md:326`,
TS2322 on `array_agg` at `aggregation.md:154`, TS2322 on the retired
`cursor` key at `pagination.md:132`.
## Acceptance notes
- `check:skill-examples` is not in this diff's derived gate list; it was
run by hand (above).
- `filters.md` now sits at token headroom 0, so the next edit there must
pay in the same file.
## Verification
Derived gates for this diff (46 commands, `dispatch-gates --commands
--repo objectstack-ai/objectstack`) are listed with exit codes in the
report comment on the card.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01QsR2jTUGktmEesT5GaV2gg)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
docs(skills): objectstack-query's self-contained examples are now type-checked by `check:skill-examples`
6
+
7
+
Clause-②: no
8
+
Metadata-protocol: none
9
+
10
+
Twenty of the forty-two fenced TypeScript blocks in `skills/objectstack-query` carry the opt-in check marker: 8 of 14 in `SKILL.md`, 8 of 11 in `rules/aggregation.md`, 4 of 10 in `rules/pagination.md`. Engine calls gain a two-line `IDataEngine` declaration from `@objectstack/spec/contracts`, and standalone query literals are typed as `QueryInput` from `@objectstack/spec/data`, so a renamed key, a removed key (`cursor`, `array_agg`) or an unknown option now fails the gate instead of shipping. Every marked example compiled as written; none needed a correction. The rest are left unmarked and each file says so once: the bare `{ where: … }` option fragments in `SKILL.md`, all seven `where` fragments in `rules/filters.md`, and the ❌/✅ pairs whose ❌ half is wrong on purpose. No rule's teaching changes.
0 commit comments