Skip to content

[OPS-PTC P3] 逐项验证官方文件工具的替代和回退 #996

Closed

Description

@Thatgfsj

P3 · 逐项验证官方文件工具的替代和回退

总计划 #978,所属工作流 #978。

问题:PTC 内同类的官方与 OPS 文件工具同时出现。read、glob、grep 的替代关系要逐项判断,图像和写入并没有等价契约。

前置条件:先联系 #961 作者;按其当前分支核验。

从哪里读

  • src/publication/replacements.ts
  • src/publication/ptc.ts
  • test/mode-contract-audit.test.mjs

认领前记录当前 main SHA。以上为优先检查的范围,需要扩大写域时先说明文件与原因。

按顺序执行

  1. 在同一宿主挂载真实官方文件/搜索工具和 OPS。分别测试 loader 开、loader 关、allowedTools=[stat]。
  2. 逐项比对官方名字在 SDK、准入、程序绑定中的存在性。仅在替代可直接调用,或允许经可见 loader 加载时隐藏。
  3. 再测自定义 preset 默认和显式 opt-in,并保存未挂载、探测失败时的可用入口。记录搜索范围、分页等语义差异。

验收清单

  • 只有 inspect 可服务时可隐藏 read;glob/grep 应保留。替代方撤销后官方入口恢复。
  • write/edit/read_image 仍可用;用真实 schema 对比 SDK,空 schema 测试只用于证明成员变化。

范围边界与停手条件:不隐藏 bash/pwsh,不改权限,不把可发现等同于本步可调用;过期文字由 P4 处理。

验证与交付

先运行 npm run build;依赖 native worker 的测试先运行 npm run build:ptc。定向入口:node test/run.mjs replacements。确认过滤器命中目标套件,记录实际 pass / skip / fail。

认领模板:编号 / 当前 SHA / 目标文件 / 第一个失败样例。提交时贴修改前与修改后结果,以及撤掉改动后会失败的断言。已有 PR 请先在原讨论协作。行为及中英文文档同 PR。


原问题讨论:#960。本单与其指向同一交付,评论处保留原始复现记录。

Activity

  1. Thatgfsj commented on Nov 19, 2026

    @Thatgfsj
    CollaboratorAuthor

    996 / main@58f6e28 / test/ptc-hide-official.test.mjs、test/modes.test.mjs、test/mode-contract-audit.test.mjs、docs/file-contract-validation.md、docs/文件契约验收.md、docs/CHANGELOG.md(## [Unreleased])/ 第一个失败样例:自定义 PTC preset 未显式 opt-in(replaceOfficial 默认 false)时必须保留官方 read/glob/grep——#961 分支现无该断言,其 integration 用例只覆盖 opt-in true。

    按本卡前置条件,基于 #961(head 29db05c,base 88ecc72)在其分支上逐项核验,不重复实现;补充以追加 commit 交付到 fix-ptc-hide-official。基线(Linux x64,Node v24.21.0,staged worker sha256 2b5f988d…):ptc-hide-official 9 pass / mode-contract-audit 4 pass / modes 12 pass / replacements-admission 11 pass。注:run.mjs 的 modes 过滤同时命中 release-tar-modes,该套件在本机因非标准 npm 无 bundled tar 而失败(脚本自身按设计 fail-closed),PR 未触碰其任何文件,属环境问题。

  2. Thatgfsj commented on Nov 19, 2026

    @Thatgfsj
    CollaboratorAuthor

    Refs #961。P3 逐项核验完成:Nicholas023 的实现未发现缺陷,未改任何源码;补充以两个 commit fast-forward 追加到其分支 fix-ptc-hide-official(现为 2ad0985,未改写历史、未 rebase)。

    新增 commit 与目的:

    • d1d31c2 test(ptc):lock the PTC official-tool hiding fallback boundaries —— 自定义 preset 未显式 opt-in(replaceOfficial 默认 false)保留全部官方工具;模式行卸载后 read/glob/grep 恢复且经 SDK 绑定实际调用可用;投影未挂载(servable 未定)时官方保留可调;write/edit/read_image 以真实参数 schema 对比 tools:sdk 并实际调用证明可用;modes 行卸载恢复断言;audit 增加保留名的程序绑定存在性(与准入、SDK 三视图逐名比对)。
    • 2ad0985 docs:file-contract-validation/文件契约验收 双语补记回退侧验证结论,并指向替代语义差异成文处(符号链接/重解析点/隐藏/.git 不遍历、分页与完成字段、CAS expectedRevision 使 write/edit 保持官方)+ CHANGELOG Unreleased 中英条目。

    逐项核验结论(均以 #961 分支实际代码为准):

    • 仅当替代已注册(publicationAdmission 存在)且投影可服务(servable 集合含该名)才隐藏官方 read/glob/grep;dynamicTools:false、allowedTools 收窄、residentTools off、投影未挂载均保留官方;探测失败 fail-open 保留官方。
    • glob/grep 与 read 同标准逐名验证;回退侧(行卸载)恢复且可调用;加载 SDK 不复活官方名。
    • 自定义 preset 默认保留官方;write/edit/read_image 不受影响且可调用。
    • 符号链接/ignore/分页/CAS 差异:组件参考已详述,file-contract-validation 现补充指引,双语文档可查。

    红绿记录:新断言在作者分支上首跑即绿;突变「仅凭 PTC 呈现即隐藏」→ 4 条 keep-official 边界用例红;突变「replaceOfficial 默认翻 true」→ 自定义 preset 默认用例红;回退作者实现(回 88ecc72)→ ptc-hide-official 10/13 红、modes 2/12 红、mode-contract-audit 2/4 红,存活项恰为既有行为锁。另:突变「把未挂载计为可服务」下 unattached 用例仍绿——该状态中 counterpart 注册存在性检查独立兜底,此断言锁的是可观察契约,如实记录。

    定向测试(Linux x64,Node v24.21.0,worker staged sha256 2b5f988d…):

    • node test/run.mjs ptc-hide → 13 pass / 0 skip / 0 fail
    • node test/run.mjs mode-contract → 4 pass / 0 skip / 0 fail
    • node test/run.mjs replacements → 11 pass / 0 skip / 0 fail
    • node test/run.mjs modes 除命中 modes.test.mjs(12 pass)外还连带 release-tar-modes:本机非标准 npm 无 bundled tar,脚本按设计 fail-closed,与 fix(ptc): hide replaced official file tools under PTC presets #961 无关(base 上同样失败);单跑 DSH_HOME=$(mktemp -d) node test/modes.test.mjs → 12 pass / 0 skip / 0 fail
    • npm run check:size 823 个代码文件全部 ≤1000;tsc -p . --noEmit 通过;docs-facts 7 pass / 0 fail。

    提交说明:#961 head 位于作者 fork(Nicholas023/dsh-ops);按 maintainerCanModify 以 fast-forward 推送其分支成功。期间曾在 origin 误建同名分支(已删除)。遗留:本机 release-tar-modes 的失败为环境问题,建议构建阶段统一判定。

  3. Thatgfsj commented on Nov 20, 2026

    @Thatgfsj
    CollaboratorAuthor

    已由 #1033 合入 main 交付(18 张卡并集,见 PR 描述与 docs/CHANGELOG.md 的 Unreleased 条目)。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions