From b78fe656581a351958fb96383f76acf1c069c2de Mon Sep 17 00:00:00 2001 From: Thatgfsj <171755367+Thatgfsj@users.noreply.github.com> Date: Thu, 19 Nov 2026 12:58:55 +0800 Subject: [PATCH] docs(ptc): trim the first-round batching lesson to its rules and four 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. --- docs/CHANGELOG.md | 2 ++ docs/configuration-reference.md | 4 ++- ...15\347\275\256\345\217\202\350\200\203.md" | 4 ++- prompts/batching-guidance.md | 36 +++---------------- src/ptc/batching-guidance.ts | 2 +- test/batching-guidance.test.mjs | 29 ++++++++++++++- 6 files changed, 42 insertions(+), 35 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index eaf1f71c..18c36829 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,8 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased] +- The first-round `batchingGuidance` lesson is trimmed from 8645 to 7538 UTF-8 bytes (the 84 B delivery prefix is unchanged): the anti-pattern section and the trailing prose that restated Step 1's dependency split are removed — that lesson already lives in Core rule 2, Step 1, the `shape` notice and Trajectory 1's live example — while the four executable trajectories ship byte-identical. Two rules are restored as core rules: `Load only missing APIs` (was a Step 3 clause) and `Recheck the SDK after a mode change` (was a Step 3 sentence). The load step, its NEXT-program semantics, the paging cursor (`nextOffset`), `expectedRevision` and partial-failure reporting are untouched, and a scope with the loader still receives the file byte for byte. `BATCHING_GUIDANCE_REVISION` is bumped 6 → 7. +- 首轮 `batchingGuidance` 教学从 8645 精简到 7538 UTF-8 字节(84 B 投递来源前缀不变):删除反例示范一节与重复 Step 1 依赖拆分的收尾散文——该课已在核心规则 2、Step 1、`shape` 提醒与轨迹 1 的活例中——四条可执行轨迹逐字节保留。两条规则补回为核心规则:`Load only missing APIs`(原 Step 3 一句)与 `Recheck the SDK after a mode change`(原 Step 3 一句)。加载步骤、其 NEXT 程序生效语义、分页游标(`nextOffset`)、`expectedRevision` 与部分失败报告均未动,带加载器的作用域仍逐字节照发全文。`BATCHING_GUIDANCE_REVISION` 6 → 7。 - `batchingGuidance` no longer teaches `ops_load_sdk` in a scope that does not publish it. The guidance text and the `bypass` notice follow the published surface: with `dynamicTools: false` the load step and its table row are replaced by a direct-call section listing the published APIs, and a scope that publishes nothing says so. Every line of the notice names only what the scope can reach: a pool that cannot load `ops_edit_file` is no longer told to load it, and a resident name that is not a file API (such as the shell) is never offered as the way to do file work. A read-only session drops the mutating APIs from that list too. Previously every loader-less session spent a round trip calling `tools.ops_load_sdk` and failed with "is not a function". - `batchingGuidance` 不再在不发布加载器的作用域里教模型调用 `ops_load_sdk`:引导文本与 `bypass` 提醒改为跟随实际发布面,`dynamicTools: false` 时"先加载再调用"一步及其表格行被替换为列出现有 API 的直调一节,一个都不发布时明确说明。提醒里只点名该作用域真正可达的 API:可加载池里没有的(如 `ops_edit_file`)不再被告知去加载,常驻集合里的非文件 API(如 shell)也不会被当作做文件工作的手段;只读策略下还会去掉会改文件的 API(教学文本本身仍只在无加载器时替换,窄池不会改写随包的轨迹示例)。此前每个无加载器的会话都会白花一次往返并报 "is not a function"。 - A loader-less scope whose only published file API is `ops_inspect_local_file` now states its contract in the replaced step: it reads one file by exact path and rejects directories, and with no `ops_glob` or `ops_grep` published nothing can list or search, so file work needs concrete paths the model already knows. The narrow-pool `bypass` load line states the order too — published names load `for the next program` — matching the full-pool wording. Both configuration references now also state the read-only limit: the policy narrows the lists a scope composes, never the shipped trajectories. diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 59ecf593..e84e1028 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -93,7 +93,9 @@ external English Markdown file: user-message batch (step-tail, source `dsh-ops:step-tail` / `batching-guidance`). It enters logged history, so the model's first request already sees the whole procedure: the first-line `// plan:` comment, the dependency split, the load-before-call step (only while dynamic loading publishes the loader) and four - copyable trajectories. + copyable trajectories. The first-round text teaches each rule once (revision 7): the anti-pattern rewrite + and the prose that repeated the dependency split are gone, the core rules state load-only-missing and + recheck-after-a-mode-change explicitly, and the four trajectories ship byte-identical. - **On a thin program**: when a **root** `run_code` program breaks one of three latched categories, a short notice is appended to that call's own result as `additionalContexts`. The tool result keeps its value, its content and its existing contexts; the program is never blocked or rewritten. diff --git "a/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md" "b/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md" index ff568ab3..f8659084 100644 --- "a/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md" +++ "b/docs/\351\205\215\347\275\256\345\217\202\350\200\203.md" @@ -65,7 +65,9 @@ OPS 沿用单行插件页:bundle 只插入一个 `dsh-ops` 行。内置预设 - **会话首轮一次**:在会话第一个被接受的非空用户消息批次里追加一条插件上下文(step-tail,来源 `dsh-ops:step-tail` / `batching-guidance`),它进入会话历史,模型第一条请求即可看到完整范式:首行 - `// plan:` 指令、按依赖拆分、先加载再调用(仅动态加载发布加载器时),以及四条可照抄的轨迹。 + `// plan:` 指令、按依赖拆分、先加载再调用(仅动态加载发布加载器时),以及四条可照抄的轨迹。首轮 + 文案按「每条规则只讲一次」精简(修订号 7):反例改写与重复依赖拆分的散文已删,「只加载缺失 API」 + 与「模式变化后重查 SDK」升为核心规则,四条轨迹逐字节保留。 - **薄程序触发**:**根** `run_code` 程序命中三类锁中的一类时,在该次调用的结果上以 `additionalContexts` 追加一条短提醒。工具结果的值、正文与既有上下文都不变,程序既不阻断也不改写。 - 三类分别是 `bypass`(用 shell 或 `node:fs` 做文件工作)、`plan`(第一物理行没有 `// plan:`)与 `shape` diff --git a/prompts/batching-guidance.md b/prompts/batching-guidance.md index cf434b65..1e8b2385 100644 --- a/prompts/batching-guidance.md +++ b/prompts/batching-guidance.md @@ -16,7 +16,10 @@ Return enough status and completion facts for the next decision. ops_read_files or ops_inspect_local_file, edit with ops_edit_file. The shell starts processes and reads environment facts; node:fs and node:child_process bypass path policy, the sandbox and the audit trail, so they are never a workaround. -7. **Load before you call**: an unloaded ops_* name is loaded, never replaced. +7. **Load only missing APIs**: names already in the current SDK are callable; an + unloaded ops_* name is loaded, never replaced. +8. **Recheck the SDK after a mode change**: a mode or component switch can change + the pool; read the current SDK before planning the next call. ## Step 0 - the plan line @@ -57,8 +60,7 @@ return { loaded: load.data?.tools, headLines: head.data?.items?.length } Calling an unloaded name throws "tools.ops_read_files is not a function". That is not a reason to fall back to the shell; it is one step spent loading. Loaded names remain -selected in this live scope; recheck the current SDK after a mode or component change. -Programs need not share a process or local variables. +selected in this live scope, and programs need not share a process or local variables. ## Trajectory 1 - reconnaissance: independent probes in one program @@ -107,10 +109,6 @@ return { } ``` -The search is the dependency, so it is awaited first. The five reads depend on its -result but not on each other, so they fan out inside the same program instead of -across five steps. - ## Trajectory 3 - a verified edit: revision first, patch second ```ts @@ -130,9 +128,6 @@ return { status: edit.status, error: "error" in edit ? edit.error : undefined, context: context.data?.items?.length, changed: edit.data?.changed } ``` -The revision and the context are independent, so they share one program. The write -needs the revision, so it is a second await in the same program, not a second step. - ## Trajectory 4 - paging: a loop is still one program ```ts @@ -155,27 +150,6 @@ return { lines: rows.length, complete, error, nextOffset: complete ? undefined : ``` Advance by nextOffset, never by page count, and stop when the result reports complete. -A loop of dispatches is batched work, not repeated single steps. - -## Anti-pattern, and its rewrite - -```ts -// plan: list the source files <- one entry, one dispatch, one round trip -const files = await tools.ops_glob({ pattern: ["src/**/*.ts"], outputMode: "paths" }) -return files.data?.items?.length -// ... then a second program for the directories, a third for the manifest -``` - -```ts -// plan: source files; directories; manifest head <- same work, one program -const [files, dirs, manifest] = await Promise.all([ - tools.ops_glob({ pattern: ["src/**/*.ts"], outputMode: "paths" }), - tools.ops_glob({ pattern: ["*"], kind: "directory", outputMode: "paths", limit: 40 }), - tools.ops_read_files({ files: [{ path: "package.json", limit: 30 }] }), -]) -return { files: files.data?.items?.length, dirs: dirs.data?.items?.length, - manifestLines: manifest.data?.items?.[0]?.lineCount } -``` ## Common mistakes diff --git a/src/ptc/batching-guidance.ts b/src/ptc/batching-guidance.ts index 0cdbcbf5..29596aee 100644 --- a/src/ptc/batching-guidance.ts +++ b/src/ptc/batching-guidance.ts @@ -15,7 +15,7 @@ import { literalShellFileWork } from './shell-file-work.js' /** Identity of the guidance in the host message source. */ export const BATCHING_GUIDANCE_ID = 'batching-guidance' /** Revision of the guidance text; bump it when the wording or the file format changes. */ -export const BATCHING_GUIDANCE_REVISION = '6' +export const BATCHING_GUIDANCE_REVISION = '7' /** The shipped guidance file, resolved from this module's own location (src or lib). */ const DEFAULT_GUIDANCE_FILE = new URL('../../prompts/batching-guidance.md', import.meta.url) diff --git a/test/batching-guidance.test.mjs b/test/batching-guidance.test.mjs index a4b750e4..c97d5b98 100644 --- a/test/batching-guidance.test.mjs +++ b/test/batching-guidance.test.mjs @@ -20,7 +20,7 @@ await test('the shipped guidance is English Markdown with its host-source identi } assert.equal(BATCHING_GUIDANCE_ID, 'batching-guidance') // A wording or format change is a product change and must bump the revision. - assert.equal(BATCHING_GUIDANCE_REVISION, '6') + assert.equal(BATCHING_GUIDANCE_REVISION, '7') }) await test('the guidance loader returns exactly the shipped Markdown file', () => { @@ -106,6 +106,33 @@ await test('the teacher trajectory pins the first-line plan and a runnable load assert.ok(text.length > 2500 && text.length < 9000, 'guidance stays bounded: ' + text.length) }) +await test('the trim removed repeated prose and the anti-pattern demo', () => { + // The first-round lesson enters message history, so it must not repeat itself: the + // anti-pattern section and the trailing prose that restated Step 1 are gone, while + // the four executable trajectories and their contracts stay byte-identical. + const text = loadBatchingGuidance() + assert.equal(text.includes('## Anti-pattern, and its rewrite'), false, 'the anti-pattern demo is gone') + assert.equal(text.includes('The search is the dependency, so it is awaited first'), false) + assert.equal(text.includes('The revision and the context are independent'), false) + assert.equal(text.includes('A loop of dispatches is batched work'), false) +}) + +await test('the trimmed lesson keeps the four trajectories and restores the two rules', () => { + const text = loadBatchingGuidance() + for (const heading of [ + '## Trajectory 1 - reconnaissance', '## Trajectory 2 - search, then read the hits', + '## Trajectory 3 - a verified edit', '## Trajectory 4 - paging', + ]) assert.ok(text.includes(heading), heading) + assert.ok(text.includes('**Load only missing APIs**'), 'load only what the SDK lacks is a core rule') + assert.ok(text.includes('**Recheck the SDK after a mode change**'), 'the post-mode-change recheck is a core rule') +}) + +await test('the shipped lesson measures its declared trimmed size', () => { + // The trim record in the PR declares this size; a wording edit must bump the + // revision and this number together. The 84 B delivery prefix is counted separately. + assert.equal(Buffer.byteLength(loadBatchingGuidance(), 'utf8'), 7538) +}) + await test('a scope with the loader receives the shipped file unchanged', () => { // The default path must not pay for a branch it never needs: byte identity is the contract. const text = loadBatchingGuidance()