Skip to content

feat(ops-ptc): deliver the 18-card OPS-PTC optimization as one consolidated change (#1000) - #1023

Closed
Thatgfsj wants to merge 52 commits into
mainfrom
release/ops-ptc-18-cards
Closed

Thatgfsj wants to merge 52 commits into
mainfrom
release/ops-ptc-18-cards

Conversation

@Thatgfsj

@Thatgfsj Thatgfsj commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

这是什么

这是一张总 PR:把 OPS-PTC 优化总索引 #1000 下 18 张任务卡中已完成的 17 张的实现、测试与双语文档合并为单一可评审变更,便于整体合入 main。每张卡原本各自有 PR(见文末「被本 PR 取代」),本 PR 是它们的并集,建议只合这一个。

工作流父单:#978(提示/路由/恢复)、#979(两档披露)、#980(验收与成本)。

覆盖的任务卡(18/18,全)

组 卡 交付要点
D 两档披露 D1 #985 旧配置五行真值表 + 四个维护者签字项(docs/design-decisions-20261119.md 双语)
D2 #986 disclosurePolicy: on-demand | full 解析与往返,缺省逐字不变,非法值点名键
D3 #987 显式 full 档首轮直调获准池(无 loader),只读剔写;统一口径:按需加载完毕集合 = 全量首轮集合
D4 #988 新增 src/ptc/disclosure.ts 单一披露计划,发布与诊断共读;修掉合法配置被误诊 PUBLICATION_UNAVAILABLE: ops_result
D5 #989 设置页披露档位卡片 + 真实往返 e2e(保存 → 读取 → 首轮 SDK → 首次调用),旧 profile 不被迁成全量
V 验收成本 V1 #990 隔离 OPS-PTC 测试入口 + 环境摘要断言 + 四重路由判据(wire/SDK 声明/探针真执行/preset)
V2 #991 四本账分账(system / 其中 SDK 子集 / wire / 历史),子集算术自证,SDK 不双计
V3 #992 12 行配置 × 三视角数据驱动矩阵 + 无 toolSet 诊断视图,删任一准入条件即报红
V4 #993 分页/目录/未加载/等待四类 bench 任务与判定器,恢复率只计有纠偏机会的样例
P 提示路由 P1 #995 教学与纠偏按本步实际发布面渲染(loader 关不教加载、只读不教写)
P2 #982 首轮教学 8645 → 7538 UTF-8 字节,四条轨迹逐字节保留,补回两条核心规则,revision 6→7
P3 #996 官方文件工具替代/回退逐项核验(servable 才隐藏、fail-open、回退恢复)
P4 #983 清除指向已隐藏官方工具的系统指引,同位置补可执行替代(call ops_inspect_local_file instead)
P5 #997 未加载 / 权限禁止 / 已撤销 四类准入判定分离(SDK_NOT_LOADED 指 loader、POLICY_DENIED 不给加载建议)
P6 #984 分页 nextOffset 续读、目录/二进制替代、after-input-change 不诱导原样重试,推荐尊重本步可达集合
P7 #998 恢复会话重放同版教学新增 0 条;压缩移除后仅一条短提醒;撤回批次不消耗教学机会
P8 #999 等待/依赖派发/游标翻页不再被判成单操作,制度正则不误读注释与字符串

| V 验收成本 | V5 #994 | Flash 真实小规模对照(26 次真实会话):行为指标全部落在 A/A 噪声带内→写「未能区分」;输入侧成本差异明确——首轮提示 5.3k vs 30.0k tokens(约 5.7×)、提示总量中位约 2.2×。报告 docs/flash-comparison-v5.md 与中文本 |

验证

npm run build            # 通过
npm run check:size       # 838 files, all <= 1000 lines
node test/run.mjs        # 257 suites: 8 failed / 5 skipped

8 个失败均为本机环境/基线既有问题,不是本 PR 引入。已在纯净 origin/main 工作树上逐个复跑对照:

套件 本 PR origin/main 原因
hardening / pwsh-upgrade / release-scope 红 红 基线既有
bench-gates 红 红 钉住的基线对象 4b51b633 不在本仓库对象库
niubash-consumer / niubash-payload-integration / release-tar-modes 红 红 本机缺 npm bundled tar(fail-closed 设计)
ptc.test 红 红 isolated-package 断言对环境变量敏感(不设 DSH_OPS_WORKER_BIN 时整套 skip)

定向套件在 DSH_OPS_WORKER_BIN 指向 staged worker(sha256 前缀 2b5f988d)下全部通过:batching 4/4、resident-switch、progressive-loop、prompt-injection 2/2、ptc-declaration-surface、ptc-two-tier-matrix 16/16、ptc-cost-accounts、settings 6/6、ptc-outcome 等。

合并时请注意

被本 PR 取代的单卡 PR

#1010 D1 · #1012 D2 · #1016 D3 · #1018 D4 · #1022 D5 · #1011 V1 · #1013 V2 · #1020 V3 · #1014 V4 · #995 P1(载于 #930)· #1015 P2 · #996 P3(载于 #961)· #983 P4(载于 #961)· #997 P5 · #1019 P6 · #1021 P7 · #999 P8(载于 #938)· #1024 V5

这些单卡 PR 保留在原处作为逐卡评审记录;合入 main 请只合本 PR。

Nicholas023 and others added 30 commits November 14, 2026 05:19
A scope without the loader was still taught to call `tools.ops_load_sdk`,
so every such session spent a round trip on a call that cannot succeed and
failed with "is not a function".

The guidance and the `bypass` notice now render from the surface the scope
actually publishes:

- a loader-less scope gets a direct-call step in place of the load step, its
  table row, and any fenced example that teaches loading, and says so when
  nothing is published at all;
- the file-work line names only the file APIs that are loadable or resident,
  never the shell it just accused, and a read-only policy drops the mutating
  APIs from that list;
- the surface is resolved per agent at delivery time, so a narrow pool or a
  read-only session is never told to load what it cannot reach.

The loader-present path is byte-identical for a full pool. Two limits are
documented in the reference: the shipped lesson itself is substituted only
when the loader is absent, and the lists follow the configured pool and the
read-only policy without the per-agent ownership narrowing.

Closes #922
`hideOfficialTools` was inert for every PTC-based preset: `replacementTargets`
gated the file targets behind `plan.nativeFiles`, and PTC plans declare
`nativeFiles: false`, so the target map only ever contained the Windows shell
names. The PTC projection kept the official `read`/`glob`/`grep` SDK bindings
next to the `ops_*` ones.

The replacement controller now receives a `PtcServability` accessor from
`mountPtc`: `servable` is the set of raw APIs the publisher itself would admit
for the agent (`permitted ∧ (resident ∨ allowedApis)`), and `isPtc` is the same
per-activation presentation predicate the publisher already uses. The shadow
`when` hides an official name only when it is a reviewed replacement, the
activation is PTC, the name is servable, and the publisher registered a
counterpart. A presentation probe failure keeps the official tool (fail-open),
because a rejected `when` fails the whole step resolve on this host.

Both the built-in mode gate and the integration path now include the PTC
presentation. `write`/`edit`/`read_image` stay visible.
Lock defaults, global dynamicTools:false, row dynamicTools:false, that row plus alwaysLoaded:[stat] and residentTools:false as exact first-round sets, with the old-off-versus-full counterexample and input-sensitivity checks (#985).
Add the bilingual 2026-11-19 design decision pair with the five-input truth table, the target full-selection row marked unimplemented, and the result exception, global switch and alwaysLoaded-cap conflicts recorded as maintainer sign-off items; cross-link from the configuration reference and record the Unreleased entry (#985).
bootEntryGroup mounts the shipped single row on the real agent loop inside each suite's throwaway DSH_HOME and records the environment a measurement must name: plugin commit, host version, platform, the worker sha256 with its staged receipt, sandbox mode, the resolved row switches and the actual agentPreset. enterPtc runs one scripted provider request, proves the top-level transport is run_code before anything executes, and reports a group that lands on Standard, on a native executor or without an executable worker as invalid with its own reason and no comparable output. progressive-loop asserts all of this beside its existing loop checks.
Verify each replacement and its fallback on the #961 branch rather than
re-implement: a custom preset keeps every official tool until
replaceOfficial opts in, disposing the mode row restores the official
read/glob/grep and they stay callable through their SDK bindings, an
unattached projection keeps them usable, and the kept write/edit/
read_image are compared through real argument schemas and stay callable.
The mode row withdraw also restores the registry surface, and the audit
now checks the kept names' program bindings beside admission and SDK
presence.
The file-contract notes now state the verified fallback side of the PTC
hiding decision (kept names stay callable, withdrawal restores the
official entries, custom presets keep officials until replaceOfficial
opts in) and point to where the replacement workflow differences are
documented: no symlink/reparse/hidden/.git traversal in ops_glob and
ops_grep, paged coverage with explicit completion fields, and the CAS
expectedRevision contract that keeps write/edit official. CHANGELOG
records both languages.
A loader-less scope whose only file API is ops_inspect_local_file now says so in the replaced step: one file by exact path, directories rejected, and with no ops_glob or ops_grep published nothing lists or searches, so file work needs concrete paths. The narrow-pool bypass load line names the order too: published names load for the next program, matching the full-pool wording.

Both configuration references and the changelog state the limits, including that a read-only policy narrows the lists a scope composes, never the shipped trajectories.
The loader-less row that always loads a mutating API teaches it only outside a read-only session, and its bypass notice keeps the same narrowing; the writable counterpart pins that the filter is keyed on the policy. The loader-less live row also asserts the exact-path note the lesson now carries.
Record four verified facts alongside the delivered truth table, changing no row or existing assertion: the custom integration path rejects alwaysLoaded outside allowedTools (options.ts:100) while built-in rows accept it silently; the settings-page discovery-entry copy versus the typed ops_load_sdk the PTC row actually publishes; the legal custom ptc-profile integration misdiagnosed PUBLICATION_UNAVAILABLE: ops_result (fix owned by #988); and the loader 1-5-per-call cap with the uncapped resident startup list. Add the two matching assertions to test/ptc-config-truth.test.mjs (13 checks).
The Step 1 sentence taught the load entry in prose without naming ops_load_sdk, so the loader-less line filter kept it beside the replacement step that says there is no loader. The sentence now sits on its own line in the shipped file and the filter drops it outside a loader scope; the dependency-split lesson it rode on stays byte for byte, and the loader-less lesson test pins the absent wording red-first. The guidance revision is bumped for the reworded line layout.
Both configuration references claimed the composed lists follow the configured pool and the read-only policy without per-agent ownership narrowing. The loadable list is in fact allowedApis to permitted, which checks ownership and runtime availability, so it can only be narrower than the pool, never wider. Both references now say so in the batchingGuidance limits.
Add the YAML-only disclosurePolicy key ('on-demand' | 'full', default
'on-demand' = the legacy path) to the ptc and ops-ptc rows: PTC config
validation, mode-row routing with a readable rejection on non-PTC rows, and
settings serialization that preserves an explicit choice and never writes
the key for the user. Resolve the D1 sign-off item on precedence
conservatively per the workflow contract: while global.dynamicTools is off
the full tier is not applied and the saved choice stays untouched.
Publication of the full tier remains the D3 slice; no publication
behaviour or settings UI changes.
V2 of #991 measures what OPS-PTC costs in raw UTF-8 bytes through the V1
entry (#990), with the four answers never mixed:

- system, the delivered rendered prompt, split into named non-empty
  sections with per-section bytes;
- sdk, the single tools:sdk section inside it, asserted to be a strict
  subset whose bytes are never added on top of system;
- wire, the outer run_code schemas on every provider request;
- history, the batching-guidance step-tail messages: the first teaching
  and the plan notice a thin program earns.

The normalization is pinned by assertion: system equals the per-section
bytes joined by blank lines, so the subset arithmetic is hand-checkable,
and an ops_load_sdk load moves system by exactly its SDK-section delta
once — no other section may change. Two fresh groups must reproduce every
byte, and the same config repeated in a session is byte-identical.

bootLoop and bootEntryGroup accept hostPlugins, so the host's own
official read/glob/grep plugins load before the shipped row and the SDK
names are compared against real schemas; without the official provider
the comparison is marked unmeasurable, never a quiet pass. On this
baseline the officials stay declared beside their ops replacements (PR
#961 is open); the suite pins that on purpose so its landing forces a
re-measure. Every record carries the scripted/0 marker, and no token,
cache or cost number is derived from bytes.
Four bench/tasks samples whose prompts state only the business goal: paged
cursor continuation, catalog-error recovery, load-before-use and
wait/multi-dispatch. A new pagedLog fixture family puts the target on page 2
and derives its answer from the bytes. bench/lib/tracks.mjs judges a scripted
trajectory against each task's fixed facts (cursor advance in the next program
on the same path, complete-page stop, advertised-set recovery, load order,
revision-awaited edits) and names the fact that did not hold; verbatim re-issues
after a delivered or input-refused envelope are no-progress retries while
bounded-transient pauses count as real waits. The tracks CLI runs ten
should-pass / should-fail trajectories and exits non-zero on any disagreement;
the recovery rate counts only tracks that had a correction opportunity and says
no denominator instead of 100%. bench-tracks pins both states red first (#993).
… 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.
Consume the D2-parsed disclosurePolicy in the builtin plan slice and the
PTC publication: an explicit 'full' row publishes its whole permitted
allowedTools pool plus result in the first round with no ops_load_sdk
(#987, #979 SS2). Resolve the D1 sign-off item 1 conservatively per
#979 SS3 -- and per the unified acceptance rule, which on-demand loading
of result forces anyway: the full first round publishes ops_result so
refs spilled this step stay consumable. Read-only still removes every
mutating API; an empty cap stays at resident + result; residentTools
false drops the resident surface but not the tier; duplicated names
register once; global.dynamicTools:false keeps its D2 veto end to end
and a row that also turns its loader off keeps the tier. On-demand
(default) behaviour is letter-identical. PtcConfig.disclosurePolicy
stays optional because custom integrations keep the legacy default
until #988; the builtin plan carries the parsed value.
The custom-integration diagnostic hand-wrote its expected first-round names,
so the selectable-but-unselected result API read as PUBLICATION_UNAVAILABLE on a
legal profile:'ptc' row, and the explicit full tier (#987) was never expected at
all. Move the tier derivation into src/ptc/disclosure.ts, read it from both the
publication and the diagnostics, and teach resolveIntegrationConfig the same
disclosurePolicy key the builtin rows parse (omitted keeps on-demand; Native
presentation rows reject it). Pin the three #988 fixtures (discovery off, full
tier with an unfilled cap, full tier with a narrow cap), keep the custom
alwaysLoaded-outside-allowedTools rejection asserted beside the builtin rows'
silent acceptance, snapshot the native custom preset's visible tools, and flip
the D1 truth-table misdiagnosis pin to ready.
Add the custom-row disclosurePolicy option to both configuration references
and the integration API docs, state that PTC diagnostic expectations follow the
same disclosure plan the publication derives, append the D4 addendum to the
2026-11-19 design decisions, and add the changelog entry.
Add the row page's PTC disclosure tier card (#989): one choice unifies both PTC rows in a single revision-checked save. An untouched old profile is never written, on-demand returns both rows to the absent key, disagreeing rows are named mixed and unified by the next choice, and a cancelled edit writes nothing. The tier rides the merged row page as a volatile string beside bashPath; the legacy per-mode form stays YAML-only. While the dynamic-tools bundle switch is off the card names the suspension and keeps the saved choice. The end-to-end suite saves through the real host writer, boots the shipped apply from the loader-merged profile, and asserts the full tier's loader-less first round carries exactly the permitted pool; switching the tier between saves applies to the next session.
@Thatgfsj

Copy link
Copy Markdown
Collaborator Author

Superseded by #1033:按仓库约定把 #1023 与 #1002–#1008 合并为一个统一 PR(冲突已在 #1033 内解决,CI 在 #1033 上跑)。

@Thatgfsj Thatgfsj closed this Nov 20, 2026
Thatgfsj added a commit that referenced this pull request Nov 20, 2026
- cargo fmt: the three merged native branches had unformatted code (rust-lint red
  on #1005, #1006 and #1023); run rustfmt over the workspace.
- file_path_tests: pin the canonical temp path before walking, so macOS's
  /var -> /private/var symlink no longer turns the asar-member expectation into
  PATH_RESTRICTED (darwin legs were red on #1006).
- drop the dead imports/comments left by the superseded P7 step-tail provider
  (prompt-injection, resident-switch, ptc.ts).

Refs #1032, #1033.
@Thatgfsj
Thatgfsj deleted the release/ops-ptc-18-cards 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.

3 participants