在大型TypeScript单体仓库中，做经过测试的小范围修改

## 编辑前先了解仓库结构和所用工具 将仓库的规范代理指南视为唯一指令来源。其他代理入口应保持为指向该指南的简短引用；当架构、工具、版本、工作流程或贡献者规则变化时，应更新规范指南。 确定以下信息： - 实际的仓库根目录、主要源代码区域、构建脚本区域、文档、测试应用和生成的工作区； - 必需的基准分支、运行时版本、包管理器、任务编排器、检查器、格式化程序以及CI支持的操作系统； - 对外导出与明确标记为内部使用的导出； - 各包专用的类型检查器，以及仓库检查、编辑器工具和下游API使用者之间的编译器版本差异。 确保共享配置对所有受支持的编译器路径都有效。不得仅因为最新检查器接受某个选项或语法就采用它。 对于模块化UI工具，应区分运行时渲染器、打包引擎，以及将二者与框架配置结合的框架集成层。保留运行时加载前静态索引等快速启动架构；一个无效的用户模块不得导致整个导航或管理界面崩溃。 ## 只运行这次修改需要的构建和检查 从文档规定的工作目录运行命令；指定任务图时使用工作区项目名称，而不是发布包名称。 先执行可使用缓存、能识别依赖关系且非生产环境的任务： 1. 编译受影响的项目或包集合； 2. 执行范围限定的类型检查； 3. 格式化并检查已变更文件； 4. 运行最接近变更的相关测试； 5. 在内部开发UI中验证行为。 仅当变更依赖模板集成、生产任务连接或跨包行为时，才升级到生产配置、生成的沙盒或与CI一致的流程。除非有意从已验证的后续阶段恢复，否则必须遵守任务依赖关系。 不得默认启动长时间运行的开发服务器。需要模板、目标或环境的命令必须明确接收相应参数。 生成的沙盒失败时，在改变构建架构之前，先使用文档规定的内部UI作为诊断备用路径。 ## 按代码类型选择测试，避免测试之间互相影响 使测试形式与行为相匹配： - 通过同目录的组件示例和交互函数测试渲染组件，并覆盖可访问性和用户行为； - 对纯工具函数、钩子和非渲染模块使用单元测试； - 使用视觉工具检查外观； - 对集成契约使用端到端、冒烟或运行器测试套件。 测试导出的行为和可观察副作用，而不是私有实现细节。不得重复验证已由类型、检查规则、组件示例交互或上层浏览器测试保证的内容。 对于文件系统代码，优先使用内存文件系统，而不是真实的临时目录或整体替换模块。每次测试前重置虚拟状态，只重定向必要的文件系统方法，并在有价值时断言虚拟磁盘状态。 绝不能在测试中直接给环境级全局值赋值。使用测试框架跟踪的全局桩，并在每次测试后恢复它们，其中也包括此前不存在的键。直接赋值会在文件之间产生依赖执行顺序的状态泄漏。 使用运行时路径工具规范化预期路径，确保文件系统断言在Unix和Windows上都能通过。 ## 先确认假设，不添加多余的抽象 在将环境假设作为架构基础之前，先用一个小型、用后即弃的探测程序验证它。不得把关于打包器、元数据、加载器或生成输出的未经验证的看法变成永久注释或抽象层。 优先用类型和现有检查规则表达长期假设。如果难以静态强制执行，应在边界处添加低成本的运行时断言，使违规在靠近来源的位置失败。 与其为推测中的灵活性增加设计，不如优先移除无用内容并采用直接实现。不要为并不存在的使用者添加抽象、备用路径或扩展点。 注释是维护文档，而不是调查记录。用1到2句话说明长期有效的原因；省略工单编号、探测历史、字节比较过程以及容易失效的行号引用。 对安全敏感路径和旧版迁移使用广泛的边界情况覆盖。为兼容代码规定明确的版本范围，以便支持期结束时可以停止使用。 ## 不随意改动生成文件，使用仓库规定的格式化和日志工具 编辑后运行仓库的格式化程序，然后检查已变更文件并执行相关测试。使用配置好的工具；不得用已经停用的检查器替代它们，也不得手工格式化由格式化程序管理的代码。 通过仓库当前的正式路径执行新的TypeScript脚本，并在配置要求时使用显式的TypeScript导入扩展名。旧版加载器的迁移仅限于本次触及的范围。 普通服务端和客户端代码应使用项目的日志抽象。只有在引入日志工具明显不合理的独立脚本中，才可直接调用控制台。 绝不能提交对生成文件的意外改动。只有当生成制品是同一工作中有意源代码变更的确定性结果时，才允许它发生变化。否则应保持不动，并报告反复出现的生成器偏差。 路径、子进程和测试都要同时考虑Unix与Windows。将CI平台覆盖视为兼容性要求，而不是可选的整理工作。 ## 不只看编译通过，确认实际行为后再完成修改 对于普通变更： 1. 仅在需要时安装依赖项； 2. 编译相关的依赖关系图； 3. 实施最小且连贯的编辑； 4. 重新编译受影响的包； 5. 执行范围限定的类型检查、格式化、代码检查以及符合契约的测试； 6. 在内部UI中验证； 7. 仅在直接相关时增加沙盒或与生产环境一致的检查。 对于渲染器、框架、构建器或插件集成，应编辑负责该功能的包，先在非生产模式下编译，然后通过匹配的生成应用和相关运行器或端到端流程测试。 如果构建失败，应先刷新依赖项并重试范围限定的编译，再考虑增加内存或改变架构。当沙盒行为与内部UI不同时，应检查生成输出和缓存。 不得仅凭编译成功就宣称已准备就绪。所需证据是能够覆盖已变更的包边界、受支持的编译器路径、可观察行为、跨平台假设和直接受影响集成流程的最小集合。