在正确的层里修改由 JavaScript 和原生代码组成的 Web 开发 CLI

## 找出负责 CLI 行为的层，并分别追踪全局与本地路径 编辑前，将需求映射到拥有该行为的组件： - JavaScript或TypeScript入口负责上层local CLI行为和package export； - native crate负责独立global binary、runtime bootstrap、package manager集成、installer、migration以及共享process utility； - native binding负责连接local JavaScript CLI与native command实现； - core package提供集成后的build、test、documentation和packaging功能界面； - 仓库tooling负责local registry、build helper、fixture和release support； - documentation与生成的project guidance是来源不同的独立产品。 当global和local命令路径都能实现同一用户命令时，应分别追踪两条路径。如果另一条路径仍不一致，只修复其中一条并不完整。 如果任务只涉及仓库贡献者指引，不要编辑生成的project guidance。应优先引用权威的架构和配置文档，而不是复制说明。 ## 区分内置命令和任务运行器中的任务 区分工具链内置命令和任务运行器。内置的test、build、lint或format命令可能调用打包在工具链中的实现，而run命令则执行同名的package script或已配置task。 将package script视为正式的run target。只有当task需要依赖关系、缓存、命令配置、输入跟踪或环境跟踪时，才使用显式task config。 一个task名称只能有一个归属方。不得在package script和tool config中同时定义同名task。task config应保存在当前权威config file中，不要重新引入已停用的standalone config format。 公共test import必须保留在受支持的package surface上，compatibility shim应由所属build script生成。不得重建已停用的package，也不得假设external dependency是local workspace member。 更改routing前，应检查command help、打包工具版本、package export以及最接近的task documentation。 ## 按变更类型选择够用的最少测试 使用能够覆盖变更行为的最小验证集合： - documentation或agent guidance：检查引用path、command、link和whitespace； - JavaScript CLI行为：运行仓库check、unit test和针对性package test； - native CLI或crate行为：运行native check、test和lint； - command output或interaction design：运行针对性的pseudo-terminal snapshot test并审查diff； - global CLI行为：重新build并install本地global binary，再验证其version和目标command； - release或packaging行为：运行release build； - merge前integration：bootstrap CLI，运行全部test，并检查repository status。 只有当format或lint重写明确属于任务范围时，才使用fix mode。对于行为变更，编辑前应找到最近的现有test，并在同一区域添加coverage。 documentation变更不得运行无关的大范围suite。涉及bundled tool dispatch时，也不得仅凭unit test就宣称CLI routing正确。 ## 添加在 Unix 和 Windows 上都能运行的伪终端快照测试 将新的command-line case和interactive flow case放入仓库的pseudo-terminal snapshot harness。每个case都用明确的argument array定义，而不是shell string。 使用harness helper command，不使用平台专用core utility，使同一个fixture在Unix和Windows上行为一致。声明case面向local CLI、global CLI还是两者；local case需要最新的local distribution build。 snapshot不一致必须以可审查的diff失败，并生成candidate output file。只能通过显式record mode更新snapshot，记录结果必须像代码一样经过审查后才能commit。 command UX发生变化时，应同时测试目标行为和transcript。对于install或migration行为，应通过仓库local registry interface提供打包后的checkout，不得绕过真实package manager行为。 明确interactive milestone和keystroke step，使失败能够指出产生差异的phase。 ## 遵守各语言的 lint 规则，生成文件只通过生成器修改 native code应遵循仓库lint限制、共享output helper、environment config、path handling以及附近的command style。TypeScript应使用权威compiler、terminal output helper和repository task config。 如果linter、compiler config或source reference已经是权威来源，就不要在贡献者指引中重复语言规则。 将生成的binding、shim、agent file、distribution和snapshot output视为有明确归属的artifact。只能通过其generator或显式snapshot acceptance flow进行变更。 diff必须限制在需求指定的归属层，不得触碰无关的tracked file或untracked file。如果生成文件意外变化，应调查source或generator，而不是直接修补派生物。 验证已install的global CLI时，使用已文档化的bootstrap路径并确认解析到的version。不得推断package build也刷新了已install binary。 ## 对比全局原生路径与本地 JavaScript 路径来调试 首先记录打包组件的version，并检查top-level help和command-specific help。 对于routing缺陷，比较global native路径与local JavaScript加binding路径。对于config缺陷，比较static extraction与JavaScript resolver fallback。对于package manager缺陷，同时检查command surface、install layer以及相关terminal snapshot。 对于check、lint、format、type-check或test缺陷，应验证end-to-end command。bundled tool routing可能使独立package test通过，同时悄然忽略用户config。 如果失败取决于local与global之间的差异，应明确复现两种情况。如果失败取决于generated output，应重新build准确的派生物，然后再判断source修复是否无效。 使用navigation guidance定位权威文件；不要让简短的agent guide取代详细的architecture、migration、task或snapshot documentation。