Skip to content

feat: globalPtcSdk row switch (default OFF) + agent/created bash readiness - #44

Merged
KannaKuron merged 4 commits into
KannaKuron:mainfrom
MYCF711:feat/global-ptc-sdk-toggle
Nov 9, 2026
Merged

KannaKuron merged 4 commits into
KannaKuron:mainfrom
MYCF711:feat/global-ptc-sdk-toggle

Conversation

@MYCF711

@MYCF711 MYCF711 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

概要

新增 globalPtcSdk 行配置开关(默认 OFF):打开时本插件把 root executor 切换为 PTC,让所有未显式挂 scoped native executor 的 agent 通过 run_code SDK 调用工具——SDK 内含本插件的 Git Bash,不含独立 pwsh。默认行为完全不变,OFF 不写任何东西。

附带一个前置修复:agent/created 监听器现在返回 in-flight 的挂载任务,使串行事件等待 bash 就位。没有它,全局 PTC executor 在创建后的首次 admission 会看到一个没有 bash 的工具面(step 1 缺 bash、step 2 才有)。

为什么需要

希望整个部署统一走 PTC 的场景,需要 tool-executor-native 关、tool-executor-ptc 开。这是 profile patch 层面的决定(bundle patch 先于 profile patch 读取),并且是 configEditor 写不了的行级 disabled。

preset-minimal 还需一并重述:它的 persona.complete: true 会在 prompt 组装后只留 persona、抹掉 PTC SDK 段,于是 minimal 会发布一个背后没有可用 SDK 的 run_code。

改动

  • 新增 src/global-ptc.js:plan 矩阵(纯函数)+ patch 写入器(parseDocument、原子写、回读校验、失败回滚、lift)。
  • src/index.js:Config 增 globalPtcSdk(非 volatile,改动即时重挂载插件——patch 写入的正确重量);ctx.inject(['profileContext']) 接线,与既有 terminal 采用共用同一把 withFileLock。
  • 新增 tests/global-ptc.mjs:19 例(plan 12 + writer 7)。

为什么直接编辑 profile patch 而不是 configEditor

沿用 src/terminal-bundle.js 已有的实测结论(packages/boot/config-editor):entries() 只看 include-mounted 顶层行,edit() 只写 config 键、从不写行级 disabled。安全轨道与之相同:parseDocument 保住注释与 !!js、定向编辑、原子写、回读校验、任何不符即回滚到原字节。

安全约束

  • 开关 OFF:不写;同时只移除本开关写下的行(按值精确匹配),用户改过的行一律保留。
  • 用户显式写了相反值(native: disabled false / ptc: disabled true / minimal: complete true):一律 kept-user-choice 退让,不覆盖。
  • 非字面量行(!!js 等):绝不替换成字面量。
  • 坏 YAML / 非 sequence:拒绝编辑,零写入。

验证

  • npm test:396 项 / 396 pass / 0 fail / 0 skip(含新增 19 例)。
  • 新增 writer 用例覆盖:空 patch 采用、二次运行幂等(字节不变)、注释与结构保留、坏文档拒绝、lift 只删本开关写的行、lift 保留用户异值行、无本开关行时 lift 零变更。

未验证

  • 真实 Windows 桌面 GUI 整轮与真实模型调用。
  • minimal 变体在真实会话中的行为(本轮只在文档模块层验证了行形状)。
  • 与 dsh-ops / FastCtx / ptc-cordis-preset 叠加时的所有权交互。

需要维护者判断的一点

AGENTS.md §4l 记载「restatement 会冻结官方行集,禁走」——那条结论针对的是改 preset 组合内的 tool-bash/tool-pwsh 行。这里重述 preset-minimal 是为了改它自身的 persona.complete,没有别的通道能到达(configEditor 写不了行级字段,bundle patch 按 id 够不到 preset 声明内的行)。代价是每次 DSH 升级要重新对齐这块。如果维护者认为该代价不可接受,请指路替代形态,我可以把 minimal 部分拆出去,只保留两个 executor 行。

A global PTC executor resolves its SDK right after agent creation. The
listener returned nothing, so the first admission could see a face
without bash (step 1 missing, step 2 present). Return the in-flight
reconcile task so the serial agent/created emission waits for it.
A deployment that wants every agent to reach its tools through the PTC
run_code SDK needs the ROOT executor switched. That is a profile-patch
decision (bundle patches are read before the profile patch file) and a
row-level `disabled` that configEditor cannot write, so the switch writes
it the way the persistent-terminal adoption already does: parseDocument,
targeted edits, an atomic write, verify-by-reread and rollback.

Default OFF writes nothing and never removes rows the user added. Turning
it OFF again lifts only the rows this switch wrote, matched by exact
value; a row the user shaped differently is left alone.

What it writes:
  - tool-executor-native: disabled true
  - tool-executor-ptc:    disabled false
  - preset-minimal restated with persona.complete:false, because a
    complete persona erases the PTC SDK at assembly (re-align that block
    when DSH is upgraded).
@KannaKuron

Copy link
Copy Markdown
Owner

感谢 PR,方向我认可。我本地跑完并检查了 writer,发现一个当前测试没覆盖的阻断项,先说明,辛苦确认:

P0:OFF 会删除用户手写的同值行(数据丢失)

src/global-ptc.js:300-310 的 lift 只按 disabled / complete 的值匹配,没有记录“哪几行是本开关写的”。我用只含用户手写三行的 patch 复现:

- id: tool-executor-native
  disabled: true
- id: tool-executor-ptc
  disabled: false
- id: preset-minimal
  name: '@deepseek-ai/dsh-agent-preset'
  config:
    plugins:
      - id: persona
        name: '@deepseek-ai/dsh-persona'
        config:
          complete: false

调用 adoptGlobalPtcPatch({ enabled: false, lift: true }) 返回 lifted,文件直接变成 []。这正好会影响已经手写过 global PTC 配置的用户。即使行是本开关写的,用户后来在同一行加了 config 或注释,只要受控字段仍相同,整行也会被删。

建议:在 patch 旁加 ownership receipt(可参考 src/ops-ownership.js),记录实际写入的行及整行指纹;OFF 只在 receipt 存在且当前整行仍等于写入内容时删除;没有 receipt 时不动任何行。补测试:用户同值行、用户整行修改、receipt 生命周期。

P1:设置页没有开关

globalPtcSdk 只在 src/index.js 的 Config/liveReader 里,src/client.js 设置卡和 src/client.locales.js 都没有对应行和词典,用户只能手改配置。请补设置行和 21 门文案,并注明“写入 profile patch,重启后生效”。

P1:preset-minimal 复述

fragment 漏了 persistent-bash / persistent-pwsh 的 description(官方 minimal.patch.yml:52-59、:71-78),注释里的 “byte-for-byte aligned” 不准确。另外 AGENTS §4l 明确反对 restatement;complete: false 会让 minimal 恢复所有普通 prompt section,已经超出“补 PTC SDK”的范围。建议运行时读取官方 preset 再只改 complete,或明确不覆盖 minimal 并说明限制,避免 DSH 升级漂移。

P2:空 face 的 created 重试

src/inline-tools.js:549-556 设置 timer 后直接 return undefined,agent/created 等不到重试链;tests/global-ptc-created.mjs 的 BASE_FACE 含 pwsh,没有覆盖这个分支。常规“有 pwsh 缺 bash”的路径已经修好,这个边缘建议补等待或补测试说明不可达。

本地 npm test 为 395 pass / 1 platform skip;以上 P0/P1 修好前我先不合。需要的话我可以提供复现脚本。

…it the retry chain

Review P0 — OFF no longer deletes user-written rows. add
src/global-ptc-ownership.js: a receipt beside the patch records exactly which
row ids this switch wrote and each written row's canonical fingerprint.
Lift deletes a row only when the receipt names it AND the row still
fingerprints to the recorded value. No receipt means nothing is owned, so a
patch the user hand-wrote before ever toggling the switch is byte-identical
after OFF. Covered by the reviewer's reproducer plus an edited-after-write
case and an adopt→lift round-trip.

Review P1 (minimal) — the preset-minimal restatement is GONE. AGENTS §4l
rejects it (freezes the official row set, and the fragment had drifted from
minimal.patch.yml's persistent-bash/persistent-pwsh descriptions). The
switch now writes only the two executor rows; the module header and CHANGELOG
say minimal needs the deployment to own its own restatement.

Review P1 (settings) — the settings card grows a Global PTC SDK row with 21
locale entries, labelled "restart to apply".

Review P2 — the empty-face retry in inline-tools now returns the retry
promise, so the SERIAL agent/created emission waits for the composed face
instead of admitting an agent with no shell at all.

npm test: 397 pass / 0 fail / 0 skip.
@MYCF711

MYCF711 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

四条都已处理,已推 9b9a657。

P0 — 数据丢失(已修)

新增 src/global-ptc-ownership.js:patch 旁的 ownership receipt 记录本开关写过的行 id + 每行规范化指纹(键序无关)。lift 只在「receipt 认领该 id」且「当前行指纹仍等于写入值」时删除。

  • 你的复现器直接进了测试:writer: P0 — OFF never deletes a user-handwritten same-value row,断言返回 unchanged 且文件 byte-identical。
  • 另补 writer: P0 — OFF leaves a row the user edited after the switch wrote it(改值后返回 kept-user-choice,行保留)。
  • 再加 writer: adopt then lift round-trips to the original bytes。
  • receipt 损坏时 fail-closed(refusing to guess ownership),不猜所有权。

P1 — preset-minimal 复述(已移除)

按你给的第二个选项:不再覆盖 minimal。fragment 整个删掉,开关只写两个 executor 行。模块头与提交信息写明:minimal 的 persona.complete: true 会抹掉 PTC SDK,这块 restatement 需要部署方自己承担,插件不代为冻结官方行集。

P1 — 设置页(已补)

src/client.js 的 inline 分组新增 Global PTC SDK 行,21 个语言块各补 gptc.label / gptc.hint,文案注明「写入 profile patch,重启后生效」。

P2 — 空 face 重试链(已修)

src/inline-tools.js 的重试分支现在返回 promise,等重试的 reconcile 落定后才 resolve,agent/created 能等到组装完成,不再在空工具面上放行 agent。

验证

npm test:397 pass / 0 fail / 0 skip(较上一版 +2)。

一点如实说明:空 face 那条边缘没有单独补成用例——tests/global-ptc-created.mjs 的 BASE_FACE 仍含 pwsh,要覆盖它需要构造「两工具皆无」的夹具。如果你希望它进 CI,我下一轮补上。

@KannaKuron

KannaKuron commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

感谢更新。P0 的 ownership receipt 方向正确;四条主项我也复跑了(本地 397 项 / 396 pass / 1 platform skip,CI 4/4 success)。复核后还有几个需要处理:

P1 — 注释仍会被当成“无变化”而删除

src/global-ptc-ownership.js:38-43 的注释说 comment-bearing sibling 会改变指纹,但 rowFingerprint 只 hash toJSON,YAML 注释不在其中。复现:adopt ON 后给 tool-executor-native 行加一行 # keep this note,再 OFF,返回 lifted,注释和整行一起消失。这是原 P0 的同类数据丢失,只是范围缩到注释。建议把 row 的 comment / commentBefore(或原始片段)纳入指纹,并补“只改注释 → kept-user-choice、行与注释保留”的用例。

P1 — 一行被用户改过之后,OFF 不再移除另一条仍归开关所有的行

src/global-ptc.js:221-223 遇到第一个指纹不符就 return,导致 receipt 里另一条仍归开关所有的行也不删。复现:adopt 后把 native 改成 disabled: false,OFF 返回 kept-user-choice,ptc 行仍是 disabled: false;UI 显示关闭,但 root 组合仍是 PTC。建议逐行删除可安全删除的行,或至少返回一个用户可见的“需要手动处理”状态,不要静默保留。

P1 — 卸载/禁用插件没有恢复 patch

terminal/ops adoption 都有 dispose 恢复;global PTC 没有。开关 ON 时卸载或禁用插件,profile patch 里的两个 executor 行会永久留下,而插件自己的 bash 也随卸载消失,用户没有 UI 可以再关掉。建议在 dispose 时按 receipt 执行一次 lift(同一把锁;失败只 log),或在 README/设置里明确写出持久配置不会随卸载恢复及迁移步骤。

P1 — minimal 的限制没有告诉用户

现在只写两个 executor 行,模块注释也承认 minimal 的 persona.complete: true 会让 run_code 没有可用 SDK;但 src/client.js:151 的 hint 仍说“every agent ... reaches its tools through the run_code SDK”,没有排除 minimal。请补 UI/README/AGENTS 的限制说明。

P2 — 21 门词典实际没有翻译

gptc.label 的 21 个语言块全是 Global PTC SDK (restart to apply);gptc.hint 有 18 块英文,zh-CN/zh-HK/zh-MO 3 块是简体(zh-HK/MO 应为繁体,zh-TW 也是英文)。请按既有词典风格补齐,至少不要把整段英文塞进非英文语言块。

P2 — 注释/文档与实现不一致

  • src/index.js:513-515 仍说会写 preset-minimal restatement,但已删除。
  • src/index.js:1876-1877 仍说 lift 是“matched by exact value”,现在是 receipt + 指纹。
  • 模块注释说“CHANGELOG says so explicitly”,但本 PR 没有 CHANGELOG/README/AGENTS 改动,版本仍是 0.51.0。合入时至少需要 CHANGELOG 与 README/AGENTS;版本我可以到时统一 bump。

P2 — 空 face 仍没有用例

承认的测试缺口还在;另外 src/inline-tools.js:555-568 的 timer 被下一次 reconcile clearTimeout 时,先前返回的 promise 永远不会 resolve。若同一 agent 在等待期间发生第二次 reconcile 或 dispose,可能挂住 serial 事件。建议补“两工具皆无”的用例,并在取消 timer 时 resolve 旧 promise。

以上不影响 receipt 的主体设计;前四项修好我再合。

Address the second PR review round.

- Receipt fingerprints now include YAML comment/commentBefore tokens as
  well as canonical row data, so a comment-only user edit blocks lifting.
- Lift simulates the base composition (native ON, PTC OFF) plus retained
  rows before every splice. It never creates zero/two root executors;
  opaque rows fail closed. Safe partial lifts remain possible, missing
  siblings work in both directions, and stale receipt entries are pruned.
- Disable/uninstall awaits in-flight adoption and lifts under the same
  profile lock, logging rather than failing host shutdown.
- Empty-face retries use per-attempt records. A superseding reconcile
  chains the old created promise to its replacement (including the Bash
  mount); dispose settles directly. Timer firing cannot resolve early.
- Settings copy is genuinely localized in all 21 locales and documents
  the minimal limitation. README/README_EN/AGENTS/CHANGELOG now describe
  ownership, disposal and composition safety; stale comments are fixed.

Validation: npm test 410/410, node --check, git diff --check and
npm pack --dry-run. Independent read-only re-review: APPROVE, no blockers.
@MYCF711

MYCF711 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

七项都已处理,已推 567cb1d。

P1 — 注释所有权

rowFingerprint 现在同时 hash 规范化数据与 YAML AST 上递归收集的 comment / commentBefore(row、pair、key、value)。toJSON() 丢失的注释不再被当成“无变化”。

新增「adopt 后只加注释 → OFF 保留行与注释」用例;另补 native / PTC 两个 comment-only 方向,防止恢复过程破坏 executor 组合。

P1 — 部分 lift / root executor 不变量

没有简单逐行删除:splice 前按 base 默认(native ON / PTC OFF)+ 将保留的行模拟最终组合,必须能证明恰好一个 enabled executor;opaque 行 fail-closed。

  • native 被改成 disabled:false 时,仍会安全移除我们的 PTC 行,返回 lifted-partial。
  • 只改注释但保留 native disabled / PTC enabled 时,不删对应另一行,返回 kept-user-choice,避免「无 executor」或「双 executor」。
  • native / PTC 任一行已被用户删除时,另一行可安全 lift,两个方向都有回归;missing 与 lifted 的 receipt 项同步清理。

P1 — 禁用 / 卸载恢复

dispose 先 await pending(正在进行的 adopt),再通过同一把 atomic.withFileLock(.../package.json) 调 write(true) 按 receipt lift。失败只 log,不阻断宿主关闭;日志给出需人工检查的 patch 路径。

P1 — minimal 限制

21 门设置卡 hint、README、README_EN、AGENTS、CHANGELOG 均明确:本开关不支持 preset-minimal,其 persona.complete:true 会抹掉 SDK;需要 minimal + PTC 的部署自行维护 preset 覆盖。

P2 — 21 门词典

21 个 label / hint 均已本地化,不再复用英文占位;zh-CN 为简体,zh-HK / zh-MO / zh-TW 为繁体。测试锁定 21 块、文本多样性与每块 minimal 限制。

P2 — 注释 / 文档一致性

src/index.js 已删除 minimal restatement 的旧描述,改为 receipt + 数据/注释指纹;补齐 CHANGELOG Unreleased、README / README_EN / AGENTS。版本号未 bump,留给你发版时统一处理。

P2 — 空 face 重试链

每次 attempt 有独立 retry record,区分 detach 与 settle:

  • superseding reconcile 清 timer,但旧 created Promise 会 followRetry 到本次 reconcile / Bash mount 后才 settle;
  • agent dispose 直接 settle,避免 serial 事件悬挂;
  • timer 正常 firing 先按 identity 摘除当前 record,再递归,最终才 settle,不能提前完成下一 attempt。

现有 4 个空 face 用例:正常重试、foreign bash 取消、替代 reconcile 需要挂 Bash(created 返回时 Bash 必须 ready)、agent dispose 取消。

验证

  • Windows / Node 24:npm test 410 pass / 0 fail / 0 skip。
  • node --check、git diff --check、npm pack --dry-run(39 files)通过。
  • 独立只读复审对原始复现与补充边界做了两轮回查,最终 APPROVE,无遗留 blocker。

未验证:真实 Desktop GUI / 模型调用,以及完整桌面实例卸载时的 patch 回滚;这些没有写成已通过。

@KannaKuron
KannaKuron merged commit 552ff62 into KannaKuron:main Nov 9, 2026
4 checks passed
@KannaKuron

Copy link
Copy Markdown
Owner

已合并并随 v0.52.0 发布:关闭开关时设置卡显示 21 语言可见提示,README/README_EN/AGENTS 补充 CLI 停服卸载的 dispose 盲区。感谢修复与配合。

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.

2 participants