OmX Issue 3257 Windows 命令可行性测试台（Phase-0 Harness）：冻结契约、路径解析模型与 Only-Receipt 验证实践

OmX Issue 3257 Windows 命令可行性测试台Phase-0 Harness冻结契约、路径解析模型与 Only-Receipt 验证实践【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex本篇文章围绕 OmXOh My codeX仓库中docs/reports/issue-3257/windows-command-harness/目录的 Phase-0 可行性测试台展开。该测试台用于在 Windows 平台上验证 npm 全局安装流程中命令解析的安全性严格遵循冻结的 Revision 8 命令契约只产出“收据”receipt而不执行任何安装、生命周期脚本或外部命令。读完本文你将掌握该 harness 的命令行用法、双模式noop/disposable与双来源stable/dev的收据形状、Windows 命令解析威胁模型PATH 顺序 .com/.exe/.bat/.cmd优先级、嵌套调度器白名单机制以及确定性语料 所有者评审门的验收边界。背景Issue 3257 要解决什么问题OmX 作为 codex 的能力增强工具其发布链路依赖 npm 全局安装参见 package.json 中的prepack与postpack脚本。在 Windows 上npm 以npm.cmd批处理形式存在安装时执行的生命周期脚本、嵌套的npm run边edge都可能被路径中预先存在的同名命令遮蔽shadow从而引发命令劫持风险。Issue 3257 的目标是在不执行任何命令的前提下用确定性的方式评估命令遮蔽威胁是否可被建模与检测。为此团队创建了这个Phase-0、仅收据receipt-only的 Node 测试台用于冻结 Revision 8 命令契约为后续真实 Windows 环境实证Phase 1提供依据。契约冻结的 Revision 8 命令契约测试台的核心约束记录在 README.md 中契约指纹命令契约 SHA-256 为4cacc4a13de4f6d53c54c9237aa4c1df6b9582cf824aa19d4911e12a57d447df任何语料或策略与之不符即视为违反冻结策略。Windows 模型只考虑启动前已存在的命令影子command shadow解析规则为 PATH 顺序优先扩展名优先级为.com、.exe、.bat、.cmd。明确排除启动后的替换post-launch replacement、TOCTOU 竞态、启动后 PATH 变更以及任何产品代码执行。嵌套调度器白名单仅允许五条嵌套边npm run build、npm run verify:native-agents、npm run sync:plugin、npm run verify:plugin-bundle、npm run clean:native-package-assets。这五条边与 package.json 中的真实脚本一一对应build为编译主流程verify:native-agentsnode dist/scripts/verify-native-agents.js、sync:pluginnode dist/scripts/sync-plugin-mirror.js、verify:plugin-bundlesync-plugin-mirror.js --check与clean:native-package-assetsnode dist/scripts/cleanup-explore-harness.js共同构成 package.json 中prepack的发布前校验链。白名单冻结的不是任意命令而是与发布流水线真实行为一致的最小边集。分层防护dispatcher.cmd 与 dispatcher.mjsdispatcher.cmd只做一件事委托给 Node 白名单检查器自身不参与判断echo off setlocal DisableDelayedExpansion node %~dp0dispatcher.mjs %* exit /b %ERRORLEVEL%其中的setlocal DisableDelayedExpansion是有意为之——批处理中若启用了延迟扩展!字符可能被吞掉或展开导致传入参数失真禁用后保证%*原样传递给 Node。dispatcher.mjs则是唯一裁决者见 dispatcher.mjsconst APPROVED_EDGES new Set([ npm run build, npm run verify:native-agents, npm run sync:plugin, npm run verify:plugin-bundle, npm run clean:native-package-assets, ]); const requestedEdge process.argv.slice(2).join( ); if (!APPROVED_EDGES.has(requestedEdge)) { process.stderr.write(issue-3257 dispatcher rejected nested edge: ${requestedEdge || empty}\n); process.exitCode 64; } else { process.stdout.write(${requestedEdge}\n); }注意白名单命中也只是打印该边process.stdout.write绝不会调用 npm 或任何外部命令——这正是receipt-only原则在调度器层的体现。收据形状noop / disposable × stable / dev测试台入口 harness.mjs 的用法为node harness.mjs --mode noop|disposable --source stable|dev [--root disposable-temp-root]参数校验逻辑harness.mjs--mode与--source必填选项不可重复缺失值或未知选项都会输出 usage 并以退出码 64 结束noop模式下传--root会被拒绝。两条安装画像install profile来源画像stableinstall --global --ignore-scripts --no-audit --no-progress --prefix FROZEN_PREFIX oh-my-codexlatestdevinstall --global --ignore-scripts --no-audit --no-progress --prefix FROZEN_PREFIX VALIDATED_ABSOLUTE_CONTAINED_TARBALL两个画像都显式携带--ignore-scripts抑制生命周期脚本、--no-audit跳过审计、--no-progress关闭进度输出并使用FROZEN_PREFIX占位符表示冻结的前缀路径dev来源额外要求一个经过校验的绝对路径且被包含的 tarball。这两个画像与 issue-3257-update-owner-verification-manifest.json 中installProfiles的CONTROLLER_INSTALL_ENV_V1.windows/CONTROLLER_INSTALL_ENV_V1.posix一一对应。fail-closed 的 disposable 根目录校验disposable模式必须满足两个条件否则一律 fail closed见 harness.mjs解析后的根目录必须是系统临时目录os.tmpdir()的直接子目录relative()结果不含..、不含/或\分隔符目录名必须以issue-3257-disposable-前缀开头。这一设计杜绝了把任意目录当作一次性根传入的可能确保测试台永远不会触碰仓库、用户目录或全局环境。收据字段无论哪种组合收据receiptType: ISSUE_3257_PHASE_0_FEASIBILITY_RECEIPT都会原样报告contractRevision: 8、契约 SHA-256、mode、source、disposableRoot、installProfile以及一组恒为NOT_EXECUTED或SUPPRESSED的执行类字段installScripts: SUPPRESSED—— 安装脚本被--ignore-scripts抑制productExecution、packageManagerMutation、globalOrUserMutation、externalLifecycleExecution、empiricalResult全部NOT_EXECUTEDownerReview: REQUIRED—— 收据必须交由所有者评审。也就是说收据是建议性的永远不能自行关闭所有者门owner gate。Windows 解析模型与确定性语料解析算法核心解析函数windowsResolveharness.mjs精确模拟 Windows 的cmd查找规则按 PATH 目录顺序遍历在每个目录内按.com、.exe、.bat、.cmd的扩展名顺序查找命中即返回全部未命中返回null。所有比较均做小写归一化与 Windows 文件系统不区分大小写的语义一致。判定分类verifyCorpusharness.mjs先做三重冻结策略校验——契约版本必须为 8、契约哈希必须匹配、扩展名顺序必须是.com,.exe,.bat,.cmd、白名单边必须逐字一致——任何不一致直接抛错。随后对每个场景计算解析结果与处置disposition处置含义ALLOW解析命中且不在\disposable\shadow\路径下REJECT_SHADOW解析命中了\disposable\shadow\下的影子命令REJECT_UNRESOLVED未解析到任何命令语料中的四个场景resolution-corpus.json 提供确定性 fixtureclean-pathnpm只存在于C:\Program Files\nodejs\npm.cmd解析为该路径ALLOWearlier-cmd-shadowC:\disposable\shadow位于 PATH 更前npm.cmd影子优先命中REJECT_SHADOWextension-precedence-shadow同一目录下同时存在npm.bat与npm.cmd按扩展名优先级命中npm.batREJECT_SHADOW——验证了先目录后扩展名、目录内扩展名有序的双重优先级missing-command目录为空解析结果为nullREJECT_UNRESOLVED。语料的 schema 由 policy-schema.json 约束command仅允许[A-Za-z0-9_-]expectedDisposition枚举严格限定为三种处置且additionalProperties: false从结构上杜绝语料漂移。证据边界与限制必须如实说明README 明确强调该语料是确定性 fixture 数据不是一次 Windows 运行的记录。测试台的能力边界是只覆盖启动前命令解析不能建立包管理器所有权package-manager ownership、生命周期安全性、Bun 行为、npm 行为或对启动后竞态的保护收据输出是建议性的不能关闭所有者门。这一点在 issue-3257-update-owner-verification-manifest.json 中得到呼应ownerGate.requiredBeforeClosure列出的关闭前提包括所有者评审实证执行证据Bun 必须事务化或 fail closed 的证据Bun dev 必须判定为不支持fail unsupported的证据而residualWindowsThreatModel也再次列出被覆盖与排除的威胁面。Phase-0 产物清单本次 Phase-0 产出的文件全部位于docs/reports/issue-3257/windows-command-harness/外加一份所有者验证清单harness.mjs —— 主测试台输出 JSON 收据dispatcher.cmd —— 批处理委托入口dispatcher.mjs —— 嵌套边白名单裁决器resolution-corpus.json —— 确定性解析语料policy-schema.json —— 策略 JSON SchemaREADME.md —— 本文所依据的契约文档issue-3257-update-owner-verification-manifest.json —— 所有者验证清单含 review 链的 SHA-256 审计痕迹。实践启示如何将仅收据验证推广到你的发布流水线从该 harness 可以提炼出三条可复用的工程原则验证与执行分离在无法安全实证的环境如跨平台 CI 矩阵、无 Windows runner 时先做确定性建模验证纯函数 fixture把可能危险的执行推迟到有实证条件的阶段收据中显式标记NOT_EXECUTED绝不假装执行过。冻结契约 双重校验契约哈希、schema 约束、解析器内嵌断言三层校验相互印证harness.mjs任何一层漂移都会让验证失败而非静默通过。fail-closed 边界无论是 disposable 根目录的前缀 直接子目录双重校验还是白名单外边一律以退出码 64 拒绝核心都是无法证明安全即拒绝这与 package.json 中prepack串联五条校验边的发布纪律一脉相承。总体而言这个测试台是安全验证不落地执行理念的范本它用确定性模型回答Windows 命令遮蔽是否可检测同时把结论的最终裁决权明确保留给所有者评审门。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考