Skip to content

docs(ptc): trim the first-round batching lesson to its rules and four trajectories - #1015

Closed
Thatgfsj wants to merge 1 commit into
card/p1-lineagefrom
card/p2-teaching-trim
Closed

Thatgfsj wants to merge 1 commit into
card/p1-lineagefrom
card/p2-teaching-trim

Conversation

@Thatgfsj

Copy link
Copy Markdown
Collaborator

Closes #982

What was wrong

The first-round batchingGuidance lesson enters message history, so every repeated sentence is re-read on each request. The shipped text restated Step 1's dependency split after Trajectories 2 and 3, restated the batching lesson a third time after Trajectory 4, and carried a two-example anti-pattern section that taught the same batching rule a model had already seen three times. Meanwhile "load only missing APIs" and "recheck the SDK after a mode change" lived only as Step 3 clauses, not as the rules they are. Baseline measured with Buffer.byteLength(text, "utf8"): body 8645 B, delivery source prefix 84 B (unchanged, counted separately).

The change

Trim table (per section; prompts/batching-guidance.md on card/p1-lineage @ a277691):

Section Action Note
Header + intro keep
Core rules 1-6 keep argument/permission contracts unchanged
Core rule 7 rewrite → **Load only missing APIs** "loaded, never replaced" kept verbatim
Core rule 8 (new) add **Recheck the SDK after a mode change** absorbs the old Step 3 "recheck" clause
Step 0 plan line, Step 1, Step 2 keep SDK loading anchor line intact for the loader-less rendering
Step 3 - load before you call keep example + NEXT-program wording; merge trailing paragraph the recheck clause moved to rule 8; nothing else changed
Trajectory 1 - reconnaissance keep byte-identical result-shape prose and the partial-failure check stay
Trajectory 2 - search then read keep code byte-identical; drop 3-sentence trailing prose it repeated Step 1
Trajectory 3 - verified edit keep code byte-identical; drop 2-sentence trailing prose expectedRevision flow untouched
Trajectory 4 - paging keep code byte-identical; keep the nextOffset sentence; drop the repeat cursor/complete contract untouched
Anti-pattern, and its rewrite delete section the lesson already lives in Core rule 2, Step 1, the shape notice and Trajectory 1's live example; the human-facing description stays in both configuration references
Common mistakes keep loader table row (renderer anchor) intact

Measured result: body 8645 B → 7538 B (−1107 B, −12.8%); the 84 B delivery prefix is unchanged. BATCHING_GUIDANCE_REVISION 6 → 7. The full-pool + loader scope still receives the file byte for byte (unchanged renderer path, asserted by the existing suite), so the P1 publication contract is preserved. test/batching-guidance.test.mjs is outside the files #982 lists; it is where the revision pin lives, so the red/green assertions land there. Docs updated in the same PR: docs/CHANGELOG.md ## [Unreleased] (EN+ZH) and both configuration references (EN+ZH). Deliberately not done: no Outcome/schema changes for bytes, no rebase onto #938/#999 lineages (merge order is an integration-stage decision), and #869's additive "one session, one scope" content is untouched — coordination comment posted on #869.

Validation

Red first, then green. Reverting prompts/batching-guidance.md turns the trim/rules/size checks red; reverting the revision bump turns the identity check red.

$ node test/run.mjs batching-guidance            # RED, before implementation
dsh-ops batching-guidance: 4 of 22 check(s) failed
  FAIL the shipped guidance is English Markdown with its host-source identity   (revision '6' !== '7')
  FAIL the trim removed repeated prose and the anti-pattern demo               (anti-pattern still present)
  FAIL the trimmed lesson keeps the four trajectories and restores the two rules
  FAIL the shipped lesson measures its declared trimmed size                   (8645 !== 7538)

$ npm run build
build: compiled src/ to lib/ and copied 60 assets

$ node test/run.mjs batching-guidance            # GREEN, after implementation
dsh-ops batching-guidance: all 22 checks passed
dsh-ops test: 1 suite(s) passed in 0s

$ DSH_OPS_WORKER_BIN=$PWD/runtime/linux-x64/dsh-ops-worker node test/run.mjs batching-examples
dsh-ops batching-examples: all 5 checks passed          # 0 skipped; the four trajectories execute against the real worker
dsh-ops test: 1 suite(s) passed in 1s

$ sha256sum runtime/linux-x64/dsh-ops-worker
2b5f988d91150cddbf2706868fb0ef6ac25371dd52e6c91a98fdebd70c642263  runtime/linux-x64/dsh-ops-worker

$ npm run check:size
check-file-size: 822 code file(s) checked, all at or under 1000 lines (longest: native/crates/ops-search/src/search.rs (930))
  • 本 PR 有一次 pull_request 事件触发的 CI required run,且已把该 run 的 URL 贴到下方代码块 — 仓库约定不在每个 PR 上跑 CI,聚合 run 留到集成/构建阶段统一执行
  • npm run verify 的实际输出(或 DSH_OPS_REQUIRE_RUNTIME=1 npm run verify) — 未跑完整 gate,按 [OPS-PTC P2] 精简首轮教学并保留四条可执行示例 #982 定向验证入口只跑两个目标套件,读数如上
  • 撤掉本次实现后,相关检查会变红(行为级红绿,而非只看代码结构)— 见上方红阶段记录
  • docs/CHANGELOG.md 的 ## [Unreleased] 已加条目(EN+ZH)
  • 行为变化已同步相关 docs(两份配置参考 EN+ZH)
  • 未新增依赖,未改 package.json 的版本与 optionalDependencies
  • 改了面向模型的描述或参数时:说明它对 schema / 提示词字节的影响 — schema 不变;教学正文 8645→7538 B,84 B 前缀不变

Environment

Linux x64, Node 22 (repo toolchain), based on origin/card/p1-lineage @ a277691 (PR #930 head); claim posted on #982 with main@58f6e28. Worker: staged runtime/linux-x64/dsh-ops-worker (sha256 2b5f988d…).

… trajectories

The first-round lesson enters message history, so it must not repeat itself. Remove the anti-pattern section and the trailing prose that restated Step 1's dependency split; restore load-only-missing and recheck-after-a-mode-change as core rules; keep the four executable trajectories byte-identical. Bump BATCHING_GUIDANCE_REVISION 6 -> 7 and pin the measured trimmed size in the guidance suite.
@Thatgfsj

Copy link
Copy Markdown
Collaborator Author

Superseded by #1033:18 张 OPS-PTC 卡的实现已随统一 PR 合入 main(本 PR 的提交已在 main 中),保留为评审记录。

@Thatgfsj Thatgfsj closed this Nov 20, 2026
@Thatgfsj
Thatgfsj deleted the card/p2-teaching-trim branch November 20, 2026 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant