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]

- Turn the two-tier OPS-PTC publication rule into a data-driven acceptance matrix (#992): `test/ptc-two-tier-matrix.test.mjs` runs eight canonical rows (legacy default, the four legacy-off variants, on-demand first step, on-demand after loading, the explicit full first round, read-only, a narrow pool and a custom `profile: 'ptc'` integration) through one shared comparator across three views — the SDK text the model reads, the step admission the loop resolves and the `run_code` program bindings — plus a separately collected no-toolSet diagnostic view that is a registration superset, never an admission proof. Every row executes a real no-side-effect sentinel through the real worker (the read-only row's inspect runs under read-only) and write authority is asserted with a safe rejection naming the refused API. The drift property is itself asserted: removing any single expected name — or reading the diagnostic view where a step view is required — fails at least one cell with the missing/extra names printed, and the unified acceptance holds: the loaded business set equals the full first round on both publication paths. The official `read`/`glob`/`grep` trio is pinned as visible under both `hideOfficialTools` states while #961 is out of baseline, so its landing flips a reviewable pin. No publication behaviour changes.
- 把两档 OPS-PTC 发布规则做成数据驱动验收矩阵(#992):`test/ptc-two-tier-matrix.test.mjs` 用同一比较器跑八个规范行(旧缺省、四个旧关闭变体、按需首步、按需加载后、显式全量首轮、只读、窄池、自定义 `profile: 'ptc'` integration)的三个视角——模型读到的 SDK 文本、循环解析的当步准入、`run_code` 程序绑定——外加单列采集的无 toolSet 诊断视图(注册超集,绝非准入证据)。每行都经真实 worker 执行无副作用哨兵(只读行的 inspect 在只读沙箱下真跑),写权限以点名被拒 API 的安全拒绝断言。漂移性质本身被断言:删任一期望名或错读诊断视角,至少一格失败并打印缺失/多余名字;统一口径成立:按需加载完毕的业务集合与全量首轮在两条发布路径上一致。官方 `read`/`glob`/`grep` 三件在 #961 未入基线期间钉为两种 `hideOfficialTools` 状态下均可见,其合入将翻转可评审的钉子。发布行为不变。
- Publish the explicit full PTC disclosure tier (#987): with `disclosurePolicy: 'full'` the `ptc` and `ops-ptc` rows' first round now carries the whole permitted `allowedTools` pool plus `ops_result` (the D1 sign-off item 1 decision, taken conservatively per #979 §3 so refs spilled this step stay consumable — and forced by the unified rule, since on-demand can always load `result`) with no `ops_load_sdk`. The first program can call the permitted pool directly; read-only sessions still exclude every write 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 veto (the row publishes its legacy surface letter for letter) and a row that also turns its loader off keeps the tier. `PtcConfig.disclosurePolicy` stays optional because custom integrations keep the legacy on-demand default until #988; the builtin plan carries the parsed value. On-demand (default) behaviour is letter-identical; the settings-page entry is #989.
- 发布显式 PTC 全量披露档位(#987):`disclosurePolicy: 'full'` 的 `ptc` 与 `ops-ptc` 行首轮现在携带整个获准 `allowedTools` 池外加 `ops_result`(D1 签字项 1 的保守决定,依 #979 §3 让本步落盘的 ref 仍可消费——统一口径也逼出同一结论,因为按需档永远可加载 `result`),且无 `ops_load_sdk`。第一个程序即可直接调用获准池;只读会话仍排除全部写 API,空上限停在 常驻 + `result`,`residentTools:false` 丢常驻面但不丢档位,重复名只注册一次,`global.dynamicTools:false` 保持否决(该行逐字发布旧面),同时关掉 loader 的行保留档位。`PtcConfig.disclosurePolicy` 保持可选,因为自定义 integration 在 #988 之前维持旧 on-demand 缺省;内置计划携带解析值。按需档(缺省)行为逐字不变;设置页入口归 #989。
- Parse an explicit PTC disclosure policy without changing any legacy behaviour: the `ptc` and `ops-ptc` rows accept a YAML-only `disclosurePolicy` key, `'on-demand'` (default, the legacy progressive path) or `'full'`. Illegal values are errors naming the key and the received value or type, and non-PTC rows reject the key with a readable diagnostic. The choice survives read → save-unrelated-setting → read through the settings serializer, and no upgrade, settings save or `global.dynamicTools` flip ever writes or erases it. The D1 sign-off item on precedence is resolved conservatively: while `global.dynamicTools` is off the full tier is not applied — the row keeps its legacy resident/alwaysLoaded surface — and the saved choice re-applies when the switch returns on; the row-level `dynamicTools` keeps its loader-only meaning because the full tier publishes no loader. Publishing the full tier remains the D3 slice; no publication behaviour or settings UI changes (#986).
Expand Down
77 changes: 77 additions & 0 deletions docs/design-decisions-20261119.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,3 +264,80 @@ unchanged — ptc-config-truth 13/0/0, resident-switch 24/0/0, ptc-disclosure-po
note, not a regression: `ptc.test.mjs`'s installed-runtime check asserts precedence
over `DSH_OPS_WORKER_BIN`, so it runs without that env override (it fails identically
on the base commit with the override set).

## V3 addendum — the data-driven acceptance matrix (#992, 2026-11-19)

Card [#992](https://github.com/T-Auto/dsh-ops/issues/992). This slice adds tests and
assertion helpers only: no publication behaviour changes. One new suite,
`test/ptc-two-tier-matrix.test.mjs` (16 checks), drives every configuration as data.

**The matrix.** Eight canonical rows — legacy default, legacy off (the
`global.dynamicTools:false`, row-level `dynamicTools:false`, that row plus
`alwaysLoaded:[stat]`, and `residentTools:false` variants), on-demand first step,
on-demand after loading, the explicit full first round, read-only, a narrow pool,
and a custom `profile: 'ptc'` integration — each carrying its config inputs and the
exact business names it must publish. Every row is measured in three views with one
shared comparator: the SDK text the model reads (declared), the step admission the
loop resolves (admitted), and the `run_code` program bindings (callable). A fourth,
clearly separate view collects the no-toolSet diagnostic assembly: a host assembly
that omits the step tool set reads every registered definition, so it is a
registration superset, never an admission proof — the default row's diagnostic shows
all sixteen pool APIs plus inspect and the loader while its step admits exactly
inspect + loader.

**Sentinels and safe rejections.** Every row executes a real no-side-effect sentinel
through the real worker (`ops_inspect_local_file`, `ops_stat`, or `ops_grep` over a
fixture file); the read-only row's inspect runs with the sandbox in read-only mode.
Write authority is asserted with a safe rejection: under read-only,
`ops_load_sdk({tools:['write_file']})` answers `INVALID_ARGUMENT` naming the refused
API with `effectState: 'none'` — no worker spawn, no side effect — and the
`ops_write_file` binding stays absent in all three step views while remaining visible
in the registration diagnostic.

**The drift property is itself asserted.** Removing any single expected name from a
row's collected set fails exactly its cell and prints the culprit; inventing a name
fails as extra; and reading the diagnostic registry view where a step view is
required fails with the pool named. Demonstrated live for the PR: corrupting the
global-off row's expected set (as if the dynamic gate had been removed) fails with
`global-off:first/declared(ops) drifted: missing [ops_load_sdk]`, and restoring the
row returns the suite to green.

**Unified acceptance.** With the same permission tier, the on-demand loaded business
set equals the full first round on both publication paths (preset and custom
integration) — the load set must include `result`, forced by the D3 sign-off item 1
rule, so the comparison is exact including `ops_result`. A loaded API becomes
callable only in the next program; an unloaded or permission-revoked one never
pretends to be executable (`typeof` stays `'undefined'` in every row's probe).

**#961 pinning.** [#961](https://github.com/T-Auto/dsh-ops/issues/961) (hide replaced
official file tools under PTC presets) is not in this baseline, so the matrix pins
today's truth: the official `read`/`glob`/`grep` trio is declared (in the `: `
SDK shape, next to the `: {` ops shape) and admitted beside the ops surface under
both `global.hideOfficialTools` states — the switch is inert for PTC rows today, and
the `official-swap-off` row records it letter for letter. When #961 lands, these pins
go red for its on state and must be updated together with it; they exist so that flip
is a reviewable diff, not a silent drift.

**Platform note.** The matrix is measured on Linux with the real worker, no Windows
simulation; POSIX rows keep the host shell, so `ops_bash` is absent from every
expected set. The Windows surface keeps its own suites on real Windows machines.

**Current-state facts recorded along the way.** The custom integration path admits
its own `ops_status` diagnostics reader — admitted and callable beside the pool, but
never declared (it has no SDK projection) and not part of the two-tier kernel, so the
unified comparison excludes it. The loader description carries the configured cap
(`Configured raw names (current authority may narrow this pool): …`), not the
sandbox-narrowed one; a narrow pool narrows it correctly. The directory
recommendation text disappears once the configured pool is exhausted. Byte budgets
are V2 and real-model rounds are V5; the loader-less declaration half owned by
`test/ptc-declaration-surface.test.mjs` belongs to P5 and is untouched.

**Verification.** `npm run build`; red first (the honest sequence): the first run
failed 5 rows on boot mechanics and 3 on wrong expectations — every correction
matched shipped behaviour or fixed the suite's own probe (the raw-name `tools.glob`
vs `ops_glob` binding typo, the lossless-JSON sentinel, the loader-less host set).
Green after: `DSH_OPS_WORKER_BIN=runtime/linux-x64/dsh-ops-worker` (sha256 2b5f988d)
`node test/run.mjs ptc-two-tier-matrix` → all 16 checks passed in ~11 s; regressions
unchanged: ptc-full-disclosure 8/0/0, ptc-declaration-surface 5/0/0,
ptc-config-truth 13/0/0, resident-switch 24/0/0; `npm run check:size` clean.

59 changes: 59 additions & 0 deletions docs/设计决策-20261119.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,3 +219,62 @@ ptc-disclosure-policy 8/0/0、settings-rows 14/0/0;worker 用
`DSH_OPS_WORKER_BIN=runtime/linux-x64/dsh-ops-worker`(sha256 2b5f988d)。环境备注,
非回归:`ptc.test.mjs` 的安装包解析检查断言优先于 `DSH_OPS_WORKER_BIN`,因此该项
在不设该环境变量时运行(在基准 commit 上设同样的变量,失败方式相同)。

## V3 附录——数据驱动验收矩阵(#992,2026-11-19)

卡 [#992](https://github.com/T-Auto/dsh-ops/issues/992)。本切片只加测试与断言
helper,发布行为不变。新套件 `test/ptc-two-tier-matrix.test.mjs`(16 项检查)把
每行配置当作数据驱动。

**矩阵。** 八个规范行——旧缺省、旧关闭(`global.dynamicTools:false`、行级
`dynamicTools:false`、该行加 `alwaysLoaded:[stat]`、`residentTools:false` 四个变体)、
按需首步、按需加载后、显式全量首轮、只读、窄池、自定义 `profile: 'ptc'`
integration——每行写明输入与必须发布的精确业务名。每行用同一比较器测三个视角:
模型读到的 SDK 文本(声明)、循环解析的当步准入(准入)、`run_code` 程序绑定
(可调)。第四个明确分列的视角采集无 toolSet 的诊断装配:省略当步工具集的宿主
装配读出全部已注册定义,它是注册超集,绝非准入证据——缺省行的诊断视图显示十六
个池 API 加 inspect 与 loader,而其当步只准入 inspect + loader。

**哨兵与安全拒绝。** 每行都通过真实 worker 执行一个无副作用哨兵(对固定文件跑
`ops_inspect_local_file`、`ops_stat` 或 `ops_grep`);只读行的 inspect 在只读沙箱下
真跑。写权限用安全拒绝断言:只读下 `ops_load_sdk({tools:['write_file']})` 回
`INVALID_ARGUMENT` 并点名被拒 API,`effectState: 'none'`——不 spawn worker、无副作用
——且 `ops_write_file` 绑定在三个当步视角全部缺席,仅在注册诊断视图中可见。

**漂移性质本身被断言。** 从任一行已采集的集合里删掉任何一个期望名,恰好那一格
失败并打印缺失名;凭空捏造名以多余报红;在该读当步视角处读注册诊断视角,则以池
名报红。为 PR 现场演示过:把 global-off 行的期望集改坏(如同动态门被删),
失败信息为 `global-off:first/declared(ops) drifted: missing [ops_load_sdk]`,
还原后套件恢复全绿。

**统一口径。** 同权限档下,按需加载完毕的业务集合与全量首轮在两条发布路径
(预设与自定义 integration)上都一致——加载集必须包含 `result`(D3 签字项 1 规则
逼出),因此比较含 `ops_result` 逐名精确。加载的 API 只在下一个程序可调;未加载
或被撤销权限的 API 绝不假装可执行(每行探针里 `typeof` 恒为 `'undefined'`)。

**#961 现状钉法。** [#961](https://github.com/T-Auto/dsh-ops/issues/961)(PTC 预设下
隐藏被替代的官方文件工具)不在本基线,矩阵钉住今天的实况:官方
`read`/`glob`/`grep` 三件以 `: ` 的 SDK 形状(并列于 ops 的 `: {` 形状)声明并
准入,与 ops 面同在,且两种 `global.hideOfficialTools` 状态完全一致——该开关今天
对 PTC 行无效,`official-swap-off` 行逐字记录。#961 合入时其开状态的钉子变红,
必须与它一并更新;钉子存在的意义就是让这次翻转成为可评审的 diff,而非静默漂移。

**平台说明。** 矩阵在 Linux 上以真实 worker 实测,不做 Windows 模拟;POSIX 行保留
宿主 shell,所有期望集都不含 `ops_bash`。Windows 面由真实 Windows 机器上的独立
套件负责。

**顺带钉住的现状事实。** 自定义 integration 路径额外准入自带的 `ops_status` 诊断
读取器——与池并列地被准入且可调,但从不被声明(无 SDK 投影),不属两档内核,
统一比较将其排除。loader 描述携带配置上限(`Configured raw names (current
authority may narrow this pool): …`)而非沙箱收窄后的集合;窄池时正确收窄。配置池
耗尽后目录推荐文本正确消失。字节分账归 V2、真实模型轮次归 V5;
`test/ptc-declaration-surface.test.mjs` 的无 loader 声明半边归 P5,未触碰。

**验证。** `npm run build`;先红(如实记录):首跑 5 行因引导机制失败、3 行因期望
集错误——每处修正要么对齐已发布行为,要么修套件自身的探针(原始名 `tools.glob`
与 `ops_glob` 绑定笔误、无损 JSON 哨兵、无 loader 行的宿主集合)。后绿:
`DSH_OPS_WORKER_BIN=runtime/linux-x64/dsh-ops-worker`(sha256 2b5f988d)
`node test/run.mjs ptc-two-tier-matrix` → 16 项全过(约 11 秒);回归不变:
ptc-full-disclosure 8/0/0、ptc-declaration-surface 5/0/0、ptc-config-truth 13/0/0、
resident-switch 24/0/0;`npm run check:size` 干净。

Loading
Loading