From 15e7e838889ef238dabefbb705cb1df4af1f3f03 Mon Sep 17 00:00:00 2001 From: Nicholas023 <498594526@qq.com> Date: Sat, 21 Nov 2026 17:14:03 +0800 Subject: [PATCH] fix(ptc): file batching guidance under its producer source The pre-step batch delivered the lesson and every corrective notice with `source: { kind: 'user' }`, so Chat drew them as user bubbles and a session looked like the user had typed dozens of English instructions nobody wrote (#1040). Deliver them under the plugin's own source kind instead. Each message keeps `role: 'user'` and carries no plugin envelope, so the model still reads it as the instruction that governs the task; the client files an unknown kind under its producer and draws no user bubble. Pinned by the prompt-user-teaching, resident-switch and ptc-cost-accounts suites; the bilingual docs and CHANGELOG describe the new source. --- docs/CHANGELOG.md | 22 ++++++++++-------- docs/component-reference.md | 2 +- docs/configuration-reference.md | 8 +++---- docs/presets.md | 2 +- docs/ptc-cost-accounts.md | 4 ++-- docs/usage.md | 5 ++-- ...77\347\224\250\346\214\207\345\215\227.md" | 2 +- ...20\346\234\254\345\210\206\350\264\246.md" | 4 ++-- ...15\347\275\256\345\217\202\350\200\203.md" | 12 +++++----- ...30\350\256\244\346\250\241\345\274\217.md" | 2 +- src/ptc/batching-guidance.ts | 23 +++++++++++++++++++ src/publication/ptc.ts | 23 ++++++++++++++----- test/prompt-user-teaching.test.mjs | 18 ++++++++------- test/ptc-cost-accounts.test.mjs | 6 ++--- test/resident-switch.test.mjs | 11 +++++---- 15 files changed, 92 insertions(+), 52 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ae4f8a63..186b8e21 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -15,17 +15,19 @@ this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm - ops-ptc 的批量调用教师轨迹新增沙箱权限教学:按宿主报告的当前模式只保留对应档位, `danger-full-access` 下明确「绝不发送 `sandbox_permissions`/`justification`」,并钉住 合法值只有 `workspace-write` 与 `danger-full-access`,避免模型编造更宽的目标(#963)。 -- OPS-PTC batch-call guidance now rides the pre-step user batch as plain user text: the opening lesson - and every `bypass`/`plan`/`shape` notice are ordinary user messages with source kind `user`, no - `[Plugin context ...]` envelope and no "not a user instruction" disclaimer. The lesson is delivered on - the first accepted pre-step (and counts as taught only after the host commits it), notices are queued by - the root `run_code` result and delivered on the next pre-step, and the tool result itself is untouched. - This deliberately supersedes the #929 same-step-inbox route so the model reads the guidance as the user's - instruction. -- OPS-PTC 批量调用提示改走 pre-step 用户消息:开局教学与每条 `bypass`/`plan`/`shape` 提醒都是 - source kind 为 `user` 的普通用户消息,不再带 `[Plugin context ...]` 信封,也不再声明"不是用户指令"。 +- OPS-PTC batch-call guidance now rides the pre-step batch as user-role text: the opening lesson and + every `bypass`/`plan`/`shape` notice are `role: 'user'` messages carrying the plugin source kind + `dsh-ops:batching-guidance`, no `[Plugin context ...]` envelope and no "not a user instruction" + disclaimer. The model still reads them as the user's instruction, while Chat files them under their + producer instead of drawing a user bubble. The lesson is delivered on the first accepted pre-step (and + counts as taught only after the host commits it), notices are queued by the root `run_code` result and + delivered on the next pre-step, and the tool result itself is untouched. This deliberately supersedes + the #929 same-step-inbox route (#1040). +- OPS-PTC 批量调用提示改走 pre-step 用户角色消息:开局教学与每条 `bypass`/`plan`/`shape` 提醒都是 + `role: 'user'`、来源为插件 kind `dsh-ops:batching-guidance` 的消息,不再带 `[Plugin context ...]` + 信封,也不再声明"不是用户指令"。模型仍把它当用户指令来读,Chat 则按生产者归类、不画用户气泡。 教学在首个被接受的 pre-step 投递(宿主提交后才算兑现),提醒由根 `run_code` 结果排队、在下一个 - pre-step 投递,工具结果本身不被改写。这是对 #929 同一步收件箱路线的有意取代,让模型把提示当作用户指令来读。 + pre-step 投递,工具结果本身不被改写。这是对 #929 同一步收件箱路线的有意取代(#1040)。 - Niubash no longer refuses to prepare its runtime when a full-access session's workspace contains the default `~/.dsh` home (#870). The workspace boundary stays armed in read-only and workspace-write modes, where host workspace labeling and write gating could otherwise reach the diff --git a/docs/component-reference.md b/docs/component-reference.md index feca5306..3ca344a3 100644 --- a/docs/component-reference.md +++ b/docs/component-reference.md @@ -19,7 +19,7 @@ The `dsh-ops` row owns built-in and explicitly configured consumer plans. Native `dsh-ops/shell`, `dsh-ops/file`, `dsh-ops/ptc` and `dsh-ops/hide-official` modules remain as unsupported legacy exports for old profiles and are not part of the bundle. -`ops-ptc` is the merged row's fifth built-in mode: the plugin registers the preset at runtime through the host `agentPresets.register` (definition from the shipped `presets/ops-ptc.patch.yml` fragment parsed by the host's `loadOverlayPatches`), so the plugin manager has no matching preset row; disabling or unloading the plugin row removes the preset together with the tool surface. The default preset is never written automatically: the detail page's button makes `ops-ptc` the default once (`applied`/`no-update`/`unavailable`/`failed`), while apply, remount and unload leave the operator's own choice alone; see [Presets and the default mode](presets.md). It publishes the same surface as `ptc` and adds the YAML-only `batchingGuidance`: the English lesson arrives once as a plain user message on the first accepted pre-step batch (from `prompts/batching-guidance.md`; source kind `user`, no plugin envelope, never the system prompt), and a **root** `run_code` program that breaks one of the three latched shape categories — `bypass`, `plan` or `shape` — queues one short notice that the next pre-step appends the same way; each category latches once per turn, a compliant program re-arms it, priority is `bypass` → `plan` → `shape`, and the program is never blocked or rewritten. A legacy profile that still names `dsh-ops/mode-ops-ptc` loads that module; under the merged bundle it only warns and stays inert, and its configuration belongs in the merged row's `ops-ptc` section. +`ops-ptc` is the merged row's fifth built-in mode: the plugin registers the preset at runtime through the host `agentPresets.register` (definition from the shipped `presets/ops-ptc.patch.yml` fragment parsed by the host's `loadOverlayPatches`), so the plugin manager has no matching preset row; disabling or unloading the plugin row removes the preset together with the tool surface. The default preset is never written automatically: the detail page's button makes `ops-ptc` the default once (`applied`/`no-update`/`unavailable`/`failed`), while apply, remount and unload leave the operator's own choice alone; see [Presets and the default mode](presets.md). It publishes the same surface as `ptc` and adds the YAML-only `batchingGuidance`: the English lesson arrives once as a user-role message on the first accepted pre-step batch (from `prompts/batching-guidance.md`; source kind `dsh-ops:batching-guidance`, no plugin envelope, never the system prompt), and a **root** `run_code` program that breaks one of the three latched shape categories — `bypass`, `plan` or `shape` — queues one short notice that the next pre-step appends the same way; each category latches once per turn, a compliant program re-arms it, priority is `bypass` → `plan` → `shape`, and the program is never blocked or rewritten. A legacy profile that still names `dsh-ops/mode-ops-ptc` loads that module; under the merged bundle it only warns and stays inert, and its configuration belongs in the merged row's `ops-ptc` section. The former `dsh-ops/background` component (FastCtx background jobs: `ops_run`, `ops_run_background`, `ops_job_output`, `ops_job_list`, `ops_job_kill`) has been removed. A profile row that still names it loads as a no-op: it accepts any config, publishes nothing, and logs one warning that the row can be deleted. diff --git a/docs/configuration-reference.md b/docs/configuration-reference.md index 7aec604c..8cd06450 100644 --- a/docs/configuration-reference.md +++ b/docs/configuration-reference.md @@ -75,7 +75,7 @@ the row's status card, which sets it once when pressed. Generation and the manua | `hideOfficialTools` | true | Hide the official file tools this mode replaces, including PTC presentation: when the projection can serve the matching `ops_*` API, official `read/glob/grep` leave the tool surface and the SDK declaration. `write`/`edit`/`read_image` stay; a name the projection cannot serve keeps its official tool (an unattached projection, `glob`/`grep` under `dynamicTools: false`, or a name excluded by a narrowed `allowedTools`). Disabled entirely when `global.hideOfficialTools` is false | | `dynamicTools` | true | Publish the progressive SDK loader `ops_load_sdk`; effective only while `global.dynamicTools` is also on (AND gate) | | `disclosurePolicy` | `on-demand` | YAML-only explicit first-round disclosure tier: `on-demand` keeps the legacy progressive path (resident + loader); `full` publishes the whole `allowedTools` pool plus `result` in the first round with no loader (implemented; see the D3 addendum in docs/design-decisions-20261119.md). Effective only while `global.dynamicTools` is on — the explicit opt-in never overrides the bundle switch; while it is off the row keeps its legacy resident/always-loaded surface and the saved choice is preserved. Rejected on non-PTC rows; illegal values are errors naming the key and the received value or type. No upgrade, settings save or switch flip ever writes this key for you | -| `batchingGuidance` | true for `ops-ptc`, false otherwise | Teach once, as a plain user message on the first accepted pre-step batch (source kind `user`, no plugin envelope, logged history; system prompt untouched), then correct the shape of root `run_code` programs: `bypass`, `plan` and `shape` each latch once per turn and re-arm when the program complies; the notice is queued by the triggering result and appended to the next pre-step as a plain user message, and never blocks or rewrites the program. Text lives in the editable `prompts/batching-guidance.md`. YAML-only; an omitted `ops-ptc` section in a legacy whole-row profile override retains true; explicit false disables it | +| `batchingGuidance` | true for `ops-ptc`, false otherwise | Teach once, as a user-role message on the first accepted pre-step batch (source kind `dsh-ops:batching-guidance`, `role: user`, no plugin envelope, logged history; system prompt untouched), then correct the shape of root `run_code` programs: `bypass`, `plan` and `shape` each latch once per turn and re-arm when the program complies; the notice is queued by the triggering result and appended to the next pre-step as a plain user message, and never blocks or rewrites the program. Text lives in the editable `prompts/batching-guidance.md`. YAML-only; an omitted `ops-ptc` section in a legacy whole-row profile override retains true; explicit false disables it | | `spillRetentionDays` | 30 | Host subprocess spill retention window; `0` reports only and never deletes | | `spillTotalBudgetMiB` | 256 | Total retained spill budget in MiB; `0` disables the budget | | `spillSweepEnabled` | true | Run one bounded sweep on activation and every 256 settlements | @@ -96,17 +96,17 @@ recorded in the same document's D2 addendum, with publication owned by the D3 sl ### Batch-call guidance (`batchingGuidance`) -Off contributes no extra context. The code default is on for `ops-ptc` only, even when a legacy profile replaces the whole row config without that section; explicit `batchingGuidance: false` still disables it. On, two kinds of guidance ride the pre-step batch as plain user messages, rendered from one +Off contributes no extra context. The code default is on for `ops-ptc` only, even when a legacy profile replaces the whole row config without that section; explicit `batchingGuidance: false` still disables it. On, two kinds of guidance ride the pre-step batch as user-role messages carrying the plugin source, rendered from one external English Markdown file: -- **Once per agent entry**: one plain user message rides the first accepted pre-step batch (source kind `user`, no plugin envelope) +- **Once per agent entry**: one user-role message rides the first accepted pre-step batch (source kind `dsh-ops:batching-guidance`, no plugin envelope) and enters logged history, so the model sees the whole procedure on the first request: the first-line `// plan:` comment, the dependency split, the load-before-call step (only while dynamic loading publishes the loader) and four copyable trajectories. The first-round text teaches each rule once (revision 8): 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 queued by that call and appended to the next pre-step as a plain user message. The tool result keeps + notice is queued by that call and appended to the next pre-step as a user-role message. The tool result keeps its value, its content and its existing contexts; the program is never blocked or rewritten. - The three categories are `bypass` (file work through the shell or `node:fs`), `plan` (no `// plan:` on the first physical line) and `shape` (a single operation in its own round trip). Each is latched once per turn, diff --git a/docs/presets.md b/docs/presets.md index 709baf6e..c01a9bc5 100644 --- a/docs/presets.md +++ b/docs/presets.md @@ -128,7 +128,7 @@ default comes from that profile's own composition. | Plugin-manager row | a dedicated preset row | no preset row; lives and dies with the `dsh-ops` row | | Publication surface | official PTC tools | same as the `ptc` section: `run_code` under real PTC presentation plus the same-stack typed SDK file tools | | Compaction | official `compaction-basic` | official `compaction-basic` as well; no `dsh-compress-codex` | -| Batch-call guidance | none | `batchingGuidance`: defaults true in code and the packaged `ops-ptc` section, including legacy whole-row overrides that omit the section; explicit false disables it; one lesson riding the first accepted pre-step batch, then shape notices for root `run_code` programs (`bypass`/`plan`/`shape`, each latched per turn and re-armed by compliance); both are delivered as plain user messages (source kind `user`, no plugin envelope) that enter logged history; text in the editable `prompts/batching-guidance.md` | +| Batch-call guidance | none | `batchingGuidance`: defaults true in code and the packaged `ops-ptc` section, including legacy whole-row overrides that omit the section; explicit false disables it; one lesson riding the first accepted pre-step batch, then shape notices for root `run_code` programs (`bypass`/`plan`/`shape`, each latched per turn and re-armed by compliance); both are delivered as user-role messages (source kind `dsh-ops:batching-guidance`, no plugin envelope) that enter logged history; text in the editable `prompts/batching-guidance.md` | | Single-row section | `ptc` | `ops-ptc` (same keys plus `batchingGuidance`) | | Default preset | decided by the host/operator | set once by the detail page's button (`applied`/`no-update`); never forced; unloading restores the host default only when the current selection is still `ops-ptc` | | Ordering | order 2 | order 6, sorted after the official rows | diff --git a/docs/ptc-cost-accounts.md b/docs/ptc-cost-accounts.md index 5feff907..4737a635 100644 --- a/docs/ptc-cost-accounts.md +++ b/docs/ptc-cost-accounts.md @@ -49,8 +49,8 @@ history; its two byte sizes below are measured on the current guidance text. assembly's wire. - **history** is the dsh-ops guidance the suite records from the messages delivered on each request: the opening lesson (7,538 B in the current text) on the first request, - then the plan notice the thin program earns (200 B). Both are plain user messages - (source kind `user`, no plugin envelope) on the pre-step batch. The suite asserts + then the plan notice the thin program earns (200 B). Both are user-role messages + (source kind `dsh-ops:batching-guidance`, no plugin envelope) on the pre-step batch. The suite asserts neither touches the system account — the post-notice system sha equals the baseline. ## The arithmetic that must hold diff --git a/docs/usage.md b/docs/usage.md index 0662837c..2d59c8df 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -26,8 +26,9 @@ Standard and Cordis publish resident Native tools; Minimal has no file baseline; typed APIs with a separate SDK loader; OPS PTC (`ops-ptc`) is registered at plugin runtime and keeps that surface, adding the batch-call guidance from the editable `prompts/batching-guidance.md`: one lesson on the first accepted pre-step batch, then shape notices for root `run_code` programs -(`bypass`/`plan`/`shape`, each latched per turn), all delivered as plain user messages (source kind `user`, -no plugin envelope) that enter logged history (on in the packaged bundle; see [presets](presets.md)). +(`bypass`/`plan`/`shape`, each latched per turn), all delivered as user-role messages carrying the plugin +source kind `dsh-ops:batching-guidance` (no plugin envelope) that enter logged history (on in the packaged +bundle; see [presets](presets.md)). The default preset is set by one button on the row's detail page; nothing forces or restores it automatically. Residency, dynamic loading, Bash, file replacement and Windows host-shell hiding are independently controlled. Global gates preserve saved per-preset diff --git "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" index 4010b18b..6a0cf851 100644 --- "a/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" +++ "b/docs/\344\275\277\347\224\250\346\214\207\345\215\227.md" @@ -16,7 +16,7 @@ Native 文件路径(含 copy/move 的目标)、省略的搜索路径,以 本检出是未发布候选。Bundle 只声明一行 `dsh-ops`:五个预设、动态加载、数据采集、TUI 联动与伴随插件联动都在这一行的插件页里配置(其中第五个预设 `ops-ptc` 由插件运行时注册,定义来自随包片段 `presets/ops-ptc.patch.yml`,不是插件管理器行)。五个预设与 discovery 默认开启,数据采集与 TUI 联动默认关闭。已移除的 `mode-*`、`discovery`、`compat`、`panel`、`tui`、`shell`、`file`、`ptc`、`hide-official` 行的已保存覆盖必须删除,它们在新 bundle 中没有对应行。 -消费者只为匹配预设发布工具。Standard/Cordis 提供 Native 常驻文件工具,Minimal 没有文件常驻基线;PTC 提供类型化 API 与独立 SDK loader;`ops-ptc` 继承同一工具面并默认开启批量调用提示(`batchingGuidance`:在首个被接受的 pre-step batch 上以普通用户消息英文教学一次 + 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮一次、合规解锁)纠偏,均以普通用户消息投递(source kind `user`、无插件信封)、进入会话历史;文案在可编辑的 `prompts/batching-guidance.md`;YAML 可关;默认预设不自动强制:详情页按钮点一次即设为 `ops-ptc`,apply/重挂载/卸载都不改你自己选的默认,详见[预设与默认模式](预设与默认模式.md))。常驻、动态、Bash、文件替换和 Windows 宿主 Shell 隐藏独立控制,总开关保留各预设保存意图。显式消费者共用装配器,未列出的预设保持原样;内置 Native discovery 可独立于常驻面启用。[配置参考](配置参考.md)说明原生开关页、精确自定义 id 与默认值;迁移见[升级说明](升级与卸载.md#从-04x-迁移到-05x)。 +消费者只为匹配预设发布工具。Standard/Cordis 提供 Native 常驻文件工具,Minimal 没有文件常驻基线;PTC 提供类型化 API 与独立 SDK loader;`ops-ptc` 继承同一工具面并默认开启批量调用提示(`batchingGuidance`:在首个被接受的 pre-step batch 上以用户角色消息(插件来源 `dsh-ops:batching-guidance`)英文教学一次 + 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮一次、合规解锁)纠偏,均以普通用户消息投递(source kind `user`、无插件信封)、进入会话历史;文案在可编辑的 `prompts/batching-guidance.md`;YAML 可关;默认预设不自动强制:详情页按钮点一次即设为 `ops-ptc`,apply/重挂载/卸载都不改你自己选的默认,详见[预设与默认模式](预设与默认模式.md))。常驻、动态、Bash、文件替换和 Windows 宿主 Shell 隐藏独立控制,总开关保留各预设保存意图。显式消费者共用装配器,未列出的预设保持原样;内置 Native discovery 可独立于常驻面启用。[配置参考](配置参考.md)说明原生开关页、精确自定义 id 与默认值;迁移见[升级说明](升级与卸载.md#从-04x-迁移到-05x)。 0.5 中,开启原版工具替换不保证条件性工具从模型工具表消失。OPS 对应项采用条件准入时,原版注册仍可见;只有同一已捕获步骤 toolSet 准入该对应项且消费者当前仍有权限时,OPS 才在分派时拒绝原版调用。对应项缺失、撤销或尚未就绪时,不得连带禁用原版工具。安全的无条件常驻替换仍可使用宿主限制。OPS 不包装原版定义,也不在准入条件或提示词组装中隐藏工具。 diff --git "a/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md" "b/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md" index a9dd7eef..1957ea10 100644 --- "a/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md" +++ "b/docs/\346\210\220\346\234\254\345\210\206\350\264\246.md" @@ -2,7 +2,7 @@ ## 为什么要有这本账 -OPS-PTC 计量常见的错误是结构性的:把 `tools:sdk` 在已包含它的 system 总量上再加一遍造成双计;把 Native 的工具 schema 混进 PTC 测量;或者放错 dsh-ops 引导的位置:一次性教学与形状提醒都是 pre-step batch 上的普通用户消息、都进入会话历史,两者都不是系统提示。V1(#990,`test/lib/ptc-entry.mjs`)已经保证被测组真正进入 OPS-PTC;本套件在那条入口上补齐字节分账,四本账永远不互相混同。 +OPS-PTC 计量常见的错误是结构性的:把 `tools:sdk` 在已包含它的 system 总量上再加一遍造成双计;把 Native 的工具 schema 混进 PTC 测量;或者放错 dsh-ops 引导的位置:一次性教学与形状提醒都是 pre-step batch 上的用户角色消息(插件来源 `dsh-ops:batching-guidance`)、都进入会话历史,两者都不是系统提示。V1(#990,`test/lib/ptc-entry.mjs`)已经保证被测组真正进入 OPS-PTC;本套件在那条入口上补齐字节分账,四本账永远不互相混同。 `test/ptc-cost-accounts.test.mjs` 用 `bootEntryGroup` 启动一个隔离组,先用 `enterPtc` 证明路由,再走一段脚本化场景——首次教学、一个引来 plan 提醒的薄程序、一次合规的 `ops_load_sdk` 加载(`glob`/`grep`/`read_files`)、以及同配置重复请求——每本账都以原始 UTF-8 字节加各项名字清单输出。 @@ -20,7 +20,7 @@ OPS-PTC 计量常见的错误是结构性的:把 `tools:sdk` 在已包含它 - **system** 是投递出去的渲染提示,按 provider 请求实际携带的口径计字节;套件断言每个配置点的请求 system 消息与空闲快照的渲染结果一致。首次请求的逐项清单:`harness:identity` 48、`tools:ptc-only` 159、`tool:read` 130、`tool:write` 92、`tool:edit` 83、`tool:glob` 75、`tool:grep` 133、`dsh-ops:repository-tooling:mode-ptc` 307、`tools:sdk` 11,739。 - **sdk** 是 system 内唯一的一个 `tools:sdk` 小节——严格子集,绝不是另立账目。归一化规则由断言钉死:system = 逐小节字节按 `\n\n` 连接,即 12,766 + 8 个连接 × 2 B = 12,782,可用上表清单手工复核。 - **wire** 是请求外层工具 schema 的 `JSON.stringify`——本场景恒为 `run_code` 一项,每个请求字节一致,且等于空闲装配的 wire。 -- **history** 是套件按每次请求实际投递的消息记录的 dsh-ops 引导:首个请求上的完整教学(当前文案 7,538 B),随后是薄程序引来的 plan 提醒(200 B)。两者都是 pre-step batch 上的普通用户消息(source kind `user`、无插件信封)。套件断言两者都不进 system 账——提醒之后的 system sha 与基线相同。 +- **history** 是套件按每次请求实际投递的消息记录的 dsh-ops 引导:首个请求上的完整教学(当前文案 7,538 B),随后是薄程序引来的 plan 提醒(200 B)。两者都是 pre-step batch 上的用户角色消息(source kind `dsh-ops:batching-guidance`、无插件信封)。套件断言两者都不进 system 账——提醒之后的 system sha 与基线相同。 ## 必须成立的算术 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 ed65eb14..5d2606b0 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" @@ -48,7 +48,7 @@ OPS 沿用单行插件页:bundle 只插入一个 `dsh-ops` 行。内置预设 | `hideOfficialTools` | true | 隐藏本模式替代的官方文件工具,含 PTC 呈现:PTC 投影能服务对应 `ops_*` 时,官方 `read/glob/grep` 从工具面与 SDK 声明移除;`write/edit/read_image` 保留;投影无法服务某个名字时保留该名字的官方工具(如未就绪、`dynamicTools:false` 下的 `glob/grep`,或 `allowedTools` 收窄排除的名字);`global.hideOfficialTools` 为 false 时整体失效 | | `dynamicTools` | true | 发布渐进式 SDK 加载器 `ops_load_sdk`;与 `global.dynamicTools` 同时开启才生效(与门) | | `disclosurePolicy` | `on-demand` | YAML-only 显式首轮披露档位:`on-demand` 保持旧渐进路径(常驻 + loader);`full` 首轮直接发布整个 `allowedTools` 池外加 `result`,且无 loader(已实现,详见 docs/设计决策-20261119.md 的 D3 附录)。仅在 `global.dynamicTools` 开启时生效——显式 opt-in 不压过总开关;关闭期间该行保持旧 resident/alwaysLoaded 面,已保存的选择原样保留。非 PTC 行拒绝该键;非法值报错点名键与收到的值或类型。升级、保存设置与开关翻转都不会替你写入该键 | -| `batchingGuidance` | `ops-ptc` 为 true,其它模式为 false | 在首个被接受的 pre-step batch 上以普通用户消息投递一次完整教学(source kind `user`、无插件信封、进入会话历史、不改系统提示词),之后按根 `run_code` 程序形状纠偏:`bypass`/`plan`/`shape` 三类每类每轮各锁一次、合规即解锁;提醒由触发调用排队、在下一个 pre-step 以普通用户消息追加,不阻断也不改写程序。文案来自可编辑的 `prompts/batching-guidance.md`。仅 YAML 可配;旧 profile 整行覆盖配置且缺少 `ops-ptc` 节时仍默认 true,显式 false 可关闭 | +| `batchingGuidance` | `ops-ptc` 为 true,其它模式为 false | 在首个被接受的 pre-step batch 上以用户角色消息投递一次完整教学(source kind `dsh-ops:batching-guidance`、`role: user`、无插件信封、进入会话历史、不改系统提示词),之后按根 `run_code` 程序形状纠偏:`bypass`/`plan`/`shape` 三类每类每轮各锁一次、合规即解锁;提醒由触发调用排队、在下一个 pre-step 以用户角色消息追加,不阻断也不改写程序。文案来自可编辑的 `prompts/batching-guidance.md`。仅 YAML 可配;旧 profile 整行覆盖配置且缺少 `ops-ptc` 节时仍默认 true,显式 false 可关闭 | | `spillRetentionDays` | 30 | 宿主 subprocess spill 保留窗口;`0` 只报告、永不删除 | | `spillTotalBudgetMiB` | 256 | 保留总字节预算(MiB);`0` 关闭预算 | | `spillSweepEnabled` | true | 组件激活时与每 256 次结算后执行一次有界清扫 | @@ -67,14 +67,14 @@ opt-in,其解析契约与保守优先级记录在同一文档的 D2 附录, ### 批量调用提示(`batchingGuidance`) -关闭时不产生任何额外上下文。代码仅对 `ops-ptc` 默认开启,旧 profile 整行覆盖配置且缺少该节时也保留此默认值;显式 `batchingGuidance: false` 仍可关闭。开启后两类提示都以普通用户消息(source kind `user`、无插件信封)追加到 pre-step batch 上并进入会话历史,文案来自外置英文 Markdown: +关闭时不产生任何额外上下文。代码仅对 `ops-ptc` 默认开启,旧 profile 整行覆盖配置且缺少该节时也保留此默认值;显式 `batchingGuidance: false` 仍可关闭。开启后两类提示都以用户角色消息(`role: user`、source kind `dsh-ops:batching-guidance`、无插件信封)追加到 pre-step batch 上并进入会话历史,文案来自外置英文 Markdown: -- **每个 agent 一次**:在第一个被接受的 pre-step batch 上追加一条普通用户消息 - (source kind `user`、无插件信封),进入会话历史,模型在首个请求即可看到完整范式:首行 +- **每个 agent 一次**:在第一个被接受的 pre-step batch 上追加一条用户角色消息 + (`role: user`、source kind `dsh-ops:batching-guidance`、无插件信封),进入会话历史,模型在首个请求即可看到完整范式:首行 `// plan:` 指令、按依赖拆分、先加载再调用(仅动态加载发布加载器时),以及四条可照抄的轨迹。首轮 文案按「每条规则只讲一次」精简(修订号 8):反例改写与重复依赖拆分的散文已删,「只加载缺失 API」 与「模式变化后重查 SDK」升为核心规则,四条轨迹逐字节保留。 -- **薄程序触发**:**根** `run_code` 程序命中三类锁中的一类时,由该次调用排队、在下一个 pre-step 以普通用户消息 +- **薄程序触发**:**根** `run_code` 程序命中三类锁中的一类时,由该次调用排队、在下一个 pre-step 以用户角色消息 追加一条短提醒。工具结果的值、正文与既有上下文都不变,程序既不阻断也不改写。 - 三类分别是 `bypass`(用 shell 或 `node:fs` 做文件工作)、`plan`(第一物理行没有 `// plan:`)与 `shape` (一次往返只做一件事)。每类每轮各锁一次;某个类别一旦合规即解锁,所以同一轮内先改对再退回还会再次 @@ -83,7 +83,7 @@ opt-in,其解析契约与保守优先级记录在同一文档的 D2 附录, - 只检查根调用(`exec.parent === undefined`)。嵌套的 `tools.ops_*` 属于 PTC 执行层,说明不了这一步的形状。 - 分析是对程序文本的字面启发式:循环或 `map` 只算一个调用站点,不是运行时扇出;字符串与注释也可能误导。 提醒文案会说明这一点,不宣称实测的 dispatch 数;被取消或从未派发的调用不参与分析。 -- 提示全部随 pre-step 用户消息投递,tool schema 不变,系统提示词与其缓存因此不受影响。教学在宿主提交 +- 提示全部随 pre-step 用户角色消息投递,tool schema 不变,系统提示词与其缓存因此不受影响。教学在宿主提交 投递消息后才算兑现;被拒绝或取消的 batch 不提交,下一个被接受的 batch 仍会教学。 - 文案跟随实际发布面。动态加载发布 `ops_load_sdk` 时,教学文本逐字节照发,含"先加载再调用"这一步;`dynamicTools: false` 时该作用域没有加载器,这一步与其表格行会被替换成"直接调用"一节,并列出本作用域实际发布的 API;一个 diff --git "a/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md" "b/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md" index 717f7177..745dedca 100644 --- "a/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md" +++ "b/docs/\351\242\204\350\256\276\344\270\216\351\273\230\350\256\244\346\250\241\345\274\217.md" @@ -113,7 +113,7 @@ node scripts/sync-preset-ops-ptc.mjs --source [--ou | 插件管理器行 | 有独立的 preset 行 | 无预设行,随 `dsh-ops` 行启停 | | 发布面 | 官方 PTC 工具 | 与 `ptc` 分区相同:真实 PTC 呈现下的 `run_code` 加同栈类型化 SDK 文件工具 | | 压缩 | 官方 `compaction-basic` | 同为官方 `compaction-basic`,不引入 `dsh-compress-codex` | -| 批量调用提示 | 无 | `batchingGuidance`:代码与随包 `ops-ptc` 节均默认 true,旧配置整行覆盖且缺少该节也保留默认值,显式 false 可关闭;在首个被接受的 pre-step batch 上以普通用户消息教学一次(source kind `user`、无插件信封、进入会话历史)+ 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮各锁一次、合规解锁)纠偏;文案在可编辑的 `prompts/batching-guidance.md` | +| 批量调用提示 | 无 | `batchingGuidance`:代码与随包 `ops-ptc` 节均默认 true,旧配置整行覆盖且缺少该节也保留默认值,显式 false 可关闭;在首个被接受的 pre-step batch 上以用户角色消息教学一次(source kind `dsh-ops:batching-guidance`、无插件信封、进入会话历史)+ 按根 `run_code` 程序形状(`bypass`/`plan`/`shape`,每类每轮各锁一次、合规解锁)纠偏;文案在可编辑的 `prompts/batching-guidance.md` | | 单行配置分区 | `ptc` | `ops-ptc`(键与 `ptc` 相同,另加 `batchingGuidance`) | | 默认预设 | 由宿主/操作者决定 | 由详情页按钮点一次设定(`applied`/`no-update`),不再自动强制或回退 | | 排序 | order 2 | order 6,排在官方行之后 | diff --git a/src/ptc/batching-guidance.ts b/src/ptc/batching-guidance.ts index 4e5ea210..d427d05d 100644 --- a/src/ptc/batching-guidance.ts +++ b/src/ptc/batching-guidance.ts @@ -16,6 +16,29 @@ import { literalShellFileWork } from './shell-file-work.js' 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 = '8' +/** + * Host source kind for guidance delivered as a user-role message. + * + * The message keeps `role: 'user'`, so the model still reads it as the + * instruction that governs the task. The plugin kind is what tells the client + * this injection is not human input: Chat files an unknown kind under its + * producer and draws no user bubble for it. + */ +export const BATCHING_GUIDANCE_SOURCE_KIND = 'dsh-ops:batching-guidance' + +// Merge-extensible host sum type: declare the producer's own kind once, so +// createUserMessage accepts it without widening the host's known sources. +declare module '@deepseek-ai/dsh-llm' { + interface MessageSourceMap { + 'dsh-ops:batching-guidance': { + readonly kind: 'dsh-ops:batching-guidance' + readonly contributor: string + readonly revision: string + readonly turn: number + readonly step: number + } + } +} /** 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/src/publication/ptc.ts b/src/publication/ptc.ts index bbc9a172..91d75c77 100644 --- a/src/publication/ptc.ts +++ b/src/publication/ptc.ts @@ -13,7 +13,10 @@ import { renderSdkDirectory } from '../projections/ptc/directory.js' import type { ApiName } from '../ptc/config.js' import { disclosurePlan } from '../ptc/disclosure.js' import { ownPtcScopes } from '../ptc/ownership.js' -import { createProgramLatch, loadBatchingGuidance, renderBatchingGuidance } from '../ptc/batching-guidance.js' +import { + BATCHING_GUIDANCE_ID, BATCHING_GUIDANCE_REVISION, BATCHING_GUIDANCE_SOURCE_KIND, + createProgramLatch, loadBatchingGuidance, renderBatchingGuidance, +} from '../ptc/batching-guidance.js' import type { GuidanceSurface } from '../ptc/batching-guidance.js' import { InvocationLifetime, InvocationNotStarted } from '../lifecycle/invocations.js' import { monitoredInvoke } from '../execution/monitored.js' @@ -280,9 +283,11 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al // A new host turn starts a fresh repeated-write window. This listener is // agent-scoped and unwinds with the entry's other disposers. if (gate.batching === true) { - // Deliver the one-time lesson and every corrective notice as plain user - // text on the pre-step batch: the same role, source and shape as a real - // user instruction, with no plugin envelope that discounts it. + // Deliver the one-time lesson and every corrective notice as user-role + // text on the pre-step batch: `role: 'user'` with no plugin envelope, so + // the model reads it as the instruction that governs the task. The source + // kind is the plugin's own, never `user`, so the client files the injection + // under its producer instead of drawing a user bubble. entry.disposers.push(agent.ctx!.on('agent/pre-step', async (payload, next) => { if (payload.agent === agent) shapeLatch.noteTurn(agent, payload.turn) const decision = await next() @@ -316,7 +321,13 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al const createUserMessage = await loadUserMessage() if (stopped || entries.get(agent) !== entry) return decision const messages = texts.map(text => createUserMessage({ - source: { kind: 'user' }, + source: { + kind: BATCHING_GUIDANCE_SOURCE_KIND, + contributor: BATCHING_GUIDANCE_ID, + revision: BATCHING_GUIDANCE_REVISION, + turn: payload.turn, + step: payload.step, + }, content: [{ type: 'text', text }], })) // Count the lesson as taught only once the host commits that exact @@ -336,7 +347,7 @@ export function mountPtc(root: Context, rawConfig: unknown, gate: PtcGate = { al const code = (exec.arguments as { code?: unknown } | undefined)?.code try { // Queue the corrective notice for the next pre-step, where it is - // delivered as plain user text; the tool result keeps its own value, + // delivered as user-role text; the tool result keeps its own value, // content and contexts untouched. const notice = shapeLatch.observe(agent, code) if (notice !== undefined) { diff --git a/test/prompt-user-teaching.test.mjs b/test/prompt-user-teaching.test.mjs index 1fa4e892..0c4fa652 100644 --- a/test/prompt-user-teaching.test.mjs +++ b/test/prompt-user-teaching.test.mjs @@ -1,12 +1,13 @@ /** - * The batching lesson and the corrective notices ride the pre-step batch as plain - * user text. + * The batching lesson and the corrective notices ride the pre-step batch as + * user-role text carrying the plugin source. * * The lesson is one user-role message on the first accepted batch, before the * model's first request; a violation queues one short notice that the next * pre-step appends the same way. Neither carries a plugin envelope or a - * tool-result context, so the model reads them exactly as the user's own - * instructions. + * tool-result context, so the model reads them as the instruction that governs + * the task. The source kind is the plugin's own, never `user`, so Chat files + * them under their producer instead of drawing a user bubble. */ import { createScope, scopeOf, scopeParentOf } from '@deepseek-ai/dsh-scope' import Subprocess from '@deepseek-ai/dsh-subprocess-local' @@ -66,8 +67,8 @@ const drivePreStep = async (agent, turn) => { }, async () => ({ kind: 'enter', messages: [accepted] })) return { accepted, decision } } -/** Guidance appended to the accepted batch as plain user text; never the accepted message itself. */ -const guidanceOf = ({ accepted, decision }) => decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'user') +/** Guidance appended to the accepted batch as user-role text under the plugin source; never the accepted message itself. */ +const guidanceOf = ({ accepted, decision }) => decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'dsh-ops:batching-guidance') const textsOf = messages => messages.map(message => message.content.map(part => part.text ?? '').join('')).join('\n') /** A compliant root program: plan line, two dispatches under Promise.all, no bypass. */ @@ -76,14 +77,15 @@ const thinProgram = 'const r = await tools.ops_stat({ path: "x" })\nreturn r.sta const rootCall = (ctx, agent, callId, code = compliantProgram) => executeCall(ctx, { agent, toolSet: agent.prepared.toolSet, name: 'run_code', arguments: { description: 'Fixture program', code }, callId, signal: new AbortController().signal }) -await test('the opening lesson rides the first accepted pre-step as plain user text', () => withTempDir('user-teach-open', async cwd => { +await test('the opening lesson rides the first accepted pre-step as user-role text', () => withTempDir('user-teach-open', async cwd => { const { ctx, agent } = await setup(cwd) try { await waitFor(() => names(ctx, agent).includes(publicToolName('stat'))) const first = await drivePreStep(agent, 1) const taught = guidanceOf(first) assert.equal(taught.length, 1, JSON.stringify(first.decision.messages)) - assert.equal(taught[0].source.kind, 'user', 'the guidance carries the user source, not a plugin context') + assert.equal(taught[0].source.kind, 'dsh-ops:batching-guidance', 'the guidance carries its producer source, never the user source') + assert.equal(taught[0].role, 'user', 'the model still receives it as user-role text') const text = textsOf(taught) assert.match(text, /^# Batch tool calls/, 'the lesson opens the message, with no envelope') assert.equal(text.includes('not a user instruction'), false, 'no plugin self-narration') diff --git a/test/ptc-cost-accounts.test.mjs b/test/ptc-cost-accounts.test.mjs index 908262b9..01daccfc 100644 --- a/test/ptc-cost-accounts.test.mjs +++ b/test/ptc-cost-accounts.test.mjs @@ -11,7 +11,7 @@ * by assertion) and proves a one-section change lands in system exactly once; * - wire: the outer tool schemas each provider request carries (`run_code`); * - history: the dsh-ops lesson and program-shape notices that entered session - * history as plain user messages on the pre-step batch. + * history as user-role messages carrying the plugin source on the pre-step batch. * * The official read/glob/grep schemas are mounted for real (the same host * plugins the budget suite mounts), because SDK names are only meaningful @@ -80,7 +80,7 @@ function officialFacts(ctx, agent) { function historyItemsOf(messages) { const items = [] for (const message of messages) { - if (message.source?.kind !== 'user') continue + if (message.source?.kind !== 'dsh-ops:batching-guidance') continue const text = textOf(message) // The lesson is rendered for the reported sandbox mode, so identify it by its // opening heading instead of comparing against the shipped file (#963). @@ -192,7 +192,7 @@ await test('the four accounts of one OPS-PTC group: system, its SDK subset, the 'normalization pinned: system = per-section bytes joined by \'\n\n\', exactly renderPrompt') assert.ok(snapshot.sdk.bytes > 0 && snapshot.sdk.bytes < snapshot.system.bytes, 'SDK is a strict subset of system') } - // The lesson and the notices are plain user messages on the pre-step batch, so + // The lesson and the notices are user-role messages on the pre-step batch, so // both enter history; the system account never moves either way. assert.equal(snapshots.steady.system.sha, snapshots.baseline.system.sha, 'the guidance is history, not a prompt change') assert.equal(snapshots.steady.sdk.sha, snapshots.baseline.sdk.sha) diff --git a/test/resident-switch.test.mjs b/test/resident-switch.test.mjs index 3d5df800..19386a9c 100644 --- a/test/resident-switch.test.mjs +++ b/test/resident-switch.test.mjs @@ -180,9 +180,9 @@ async function drivePreStep(agent, turn) { }, async () => ({ kind: 'enter', messages: [accepted] })) return { accepted, decision } } -/** Guidance appended to the accepted batch as plain user text; never the accepted message itself. */ +/** Guidance appended to the accepted batch as user-role text under the plugin source; never the accepted message itself. */ function guidanceOf({ accepted, decision }) { - return decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'user') + return decision.messages.filter(message => message.id !== accepted.id && message.source?.kind === 'dsh-ops:batching-guidance') } /** The one-time full lesson, told from a per-violation notice by its first line. */ function lessonMessage(message) { @@ -196,13 +196,14 @@ function commitGuidance(ctx, agent, messages) { /** Join the text of a list of messages. */ const textsOf = messages => messages.map(message => message.content.map(part => part.text ?? '').join('')).join('\n') -await test('ops-ptc batchingGuidance teaches once on the first pre-step as plain user text', () => withTempDir('batching-teach', async cwd => { +await test('ops-ptc batchingGuidance teaches once on the first pre-step as user-role text', () => withTempDir('batching-teach', async cwd => { const { ctx, agent } = await setup(cwd, 'ops-ptc', { residentTools: true, dynamicTools: true, batchingGuidance: true, alwaysLoaded: ['stat'], allowedTools: ['stat'] }) try { await waitFor(() => names(ctx, agent).includes(publicToolName('stat'))) - // The lesson is a plain user message on the first accepted batch: the same - // role, source and shape as the user's own instruction, with no envelope. + // The lesson is a user-role message on the first accepted batch: the same + // role and shape as the user's own instruction, no envelope, and a plugin + // source so Chat never draws a user bubble for it. const first = await drivePreStep(agent, 1) const guided = guidanceOf(first) assert.equal(guided.length, 1, JSON.stringify(first.decision.messages))