Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion docs/configuration-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
4 changes: 3 additions & 1 deletion docs/配置参考.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
36 changes: 5 additions & 31 deletions prompts/batching-guidance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/ptc/batching-guidance.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
29 changes: 28 additions & 1 deletion test/batching-guidance.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down Expand Up @@ -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()
Expand Down
Loading