修改类型化单体仓库时不弄坏它，并让项目 Wiki 保持最新

## 改动前先找出涉及的包、测试和文档 将根级代理指南视为所有编码代理共同遵守的约定。任何工具专用指令文件都应保持精简并以该约定为准，而不是重复其中的内容。 - 确定核心包、可选集成、开发者工具、生态模块、示例、文档和测试所在的位置。 - 除非仓库另有规定，否则测试和测试固件应位于其所验证的软件包附近。 - 编辑子系统前，先阅读距离该子系统最近的软件包指南。 - 接触文件前，先追踪所请求的更改归属哪个软件包、公共接口、测试和文档。 - 优先选择受影响的最小范围；不要把聚焦的任务变成整个仓库的重写。 ## 使用仓库规定的包管理器和脚本 使用仓库声明的软件包管理器、工作区定义、运行时版本和脚本。不要仅因本地安装了熟悉的替代工具就擅自替换它们。 - 使用文档规定的安装命令为工作区准备依赖项。 - 使用根级构建、测试、代码检查和类型检查脚本进行完整检查。 - 针对特定软件包作业时，使用受支持的工作区筛选器。 - 当包装脚本向底层工具传递选项时，必须原样保留参数转发方式。 - 更改对软件包管理器或运行时的假设前，先检查仓库配置文件。 - 记录范围更窄的命令所依赖的任何前置条件。 ## 按 CI 的顺序运行测试，不混入陈旧构建产物 复现持续集成的执行顺序，不要自行设计本地流程。如果 CI 安装依赖后未先构建就运行验证命令，本地测试也应采用相同方式。 - 如果生成的产物可能与源文件一同被发现，就不要先执行构建。 - 出现重复注册、重复模式定义或重复装饰类错误时，应考虑源文件和生成文件可能都已被加载。 - 仅移除文档规定的源代码根目录下的生成产物目录，同时排除依赖项、测试和测试固件。 - 为清除生成产物导致的故障，绝不能删除源代码目录。 - 清理后先重新运行失败的测试，再更改实现代码。 - 如果清理未改变故障，则根据新获得的证据恢复常规调试。 ## 遵循现有代码写法，不把应用状态放进全局 优先采用仓库已有的模式，而不是引入新的抽象。使用代码库已经采用的模块系统、类型化语言约定、格式化工具、代码检查工具和文件命名样式。 - 如果仓库采用小写字母和连字符的文件名约定，就保持该约定。 - 对公共 API 的更改应经过审慎决策、测试覆盖并记录在文档中。 - 将应用专用的可变运行时状态保存在应用自身拥有的作用域中，而不是进程级全局单例中。 - 为生命周期工具和其他每个应用各自独立的服务使用框架的作用域存储机制。 - 对计时器、事件监听器、代理处理程序和模块级逸出点等脱离原调用链的回调，重新进入其所属应用的作用域。 - 不要在已经固定到正确应用上下文的访问器外重复添加作用域包装。 ## 让启动时加载的模块不破坏启动快照 如果运行时可以序列化启动快照，应假定构建时启动过程可能在应用正常启动之前停止。在该阶段加载的任何模块都必须能够安全序列化。 - 如果导入时或启动时的工作会创建不可序列化的原生状态，请将相关模块保留为外部模块。 - 将 HTTP 解析器、HTTP/2 绑定、TLS 上下文、DNS 通道、WebAssembly 实例、文件监视器、原生附加组件和开放套接字视为高风险快照依赖项。 - 通过运行时的恢复阶段加载桥接机制载入外部化模块。 - 维护一份有文档说明的默认模块列表，列出必须保持延迟加载或外部化的模块。 - 通过仓库支持的配置扩展该列表，而不是修补生成的产物。 - 区分直接创建原生状态与间接使用网络：延迟外部化的内置模块可能已能保护间接依赖项，而直接创建原生状态或 WebAssembly 状态的软件包仍需明确处理。 - 如果框架依赖项在启动期间可能接触原生或网络栈，请添加快照构建测试。 ## 把全局类型扩展放进专用的类型模块 将软件包范围的全局类型扩展放在专用的全局类型模块中。服务于多个软件包的共享扩展应放在共享类型定义包中，而不是放在某个消费方中。 - 通过导入、仅类型导入或空导出，使声明文件保持为模块。 - 从需要该类型接口的软件包入口点导入共享扩展。 - 避免使用仅因文件缺少模块语法而意外成为全局声明的环境声明。 - 移动共享类型后，同时测试定义该类型的软件包和至少一个使用它的软件包。 - 记录公共类型接口的任何更改。 ## 运行相关测试并检查最终差异后再报告 先运行能够证明所更改行为的最有针对性的检查，仅在受影响边界确有需要时才扩大范围。 - 对加载器、应用生命周期、集群、代理、HTTP 处理或进程行为的更改添加回归测试覆盖。 - 通过仓库脚本运行格式化、代码检查、类型检查和相关测试。 - 遵循仓库的提交消息约定，并准确标明范围。 - 在更改说明中解释动机、行为变化、风险和测试证据。 - 审查最终差异，检查无关编辑、生成内容噪声和未记录的公共更改。 - 在相关命令成功完成之前，不要声称任务成功。 ## 不提交密钥，公开漏洞细节前先停下 处理漏洞相关工作前，先阅读仓库的安全策略。绝不要提交秘密、凭据、私有端点或特定于某台机器的配置。 - 使本地运行时和软件包管理器版本与仓库声明保持一致。 - 将锁文件和工作区配置视为相互协调的输入；只有在有意更新依赖项或工具链时才能更改它们。 - 在示例和文档中使用占位符，而不是真实凭据或私有 URL。 - 将安全敏感型更改严格限制在必要范围，并为受保护的边界添加回归测试覆盖。 - 除非任务明确授权该操作，否则在发布漏洞详情或更改受保护的外部系统前必须停止。 ## 把代码等原始资料、Wiki 和 AI 规则分开 维护三个不同的知识层。原始来源是权威证据，Wiki 存储持久的综合结论，根级代理指南定义共享工作流程规则。 - 将代码、面向用户的文档、根项目文件、明确的外部产物和导入的原始材料视为来源证据。 - 查找方向时先从 Wiki 摘要入手，但当细节、冲突或时效性很重要时，必须对照原始来源验证。 - 除非任务要求，否则不要重写原始来源。 - 将反复使用的外部证据收录到仓库知识库中。 - 记录冲突，不要为了形成虚假的共识而抹平冲突。 - 保持工具专用代理文件精简，并让其指向共享模式。 ## 每个 Wiki 页面只写一个主题并注明来源文件 每个有实质内容的知识页面都应只有一个明确主题，并声明页面类型，例如软件包、概念、工作流程、决策或来源。 - 使用小写字母和连字符组成的文件名。 - 在前置元数据中包含易读的标题、页面类型、单行摘要、主要来源路径、本地日历日期和时效状态。 - 为重要且并非显而易见的主张列出可追溯的源文件。 - 将并非显而易见的综合结论标记为推断。 - 当时效性不确定时，标记过时或尚未解决的主张。 - 保持 Wiki 索引简洁，并按类别组织。 - 对重要的资料导入、持久发现、实质性重构和改变既有认知的更改使用仅追加日志。 - 不要记录仅修正微小拼写错误的编辑。 ## 导入资料或回答问题前先读 Wiki 索引 在摄取来源、回答仓库问题或检查知识库时，使用可预测的工作流程。 - 摄取资料时，先阅读索引，查找应吸收该资料的现有页面；有必要时创建或更新来源页面，然后更新受影响的页面、刷新索引，并为实质性更改追加日志条目。 - 回答查询时，先阅读索引和相关 Wiki 页面，再对照原始来源验证；写回具有持久价值的新发现，并记录实质性的知识更改。 - 检查知识库时，查找孤立页面、过时主张、重复概念、缺少来源引用、常用领域缺少页面以及相互矛盾的内容。 - 对存在重叠的页面，优先重新组织结构，而不是让页面无限变长。 - 优先为基础软件包、集成、工具、生命周期行为、加载、测试、发布工作和文档维护建立持久覆盖。 ## 只在 API 或工作流程变化时更新 Wiki 当工作实质性改变公共 API、文档结构、软件包职责、架构、反复使用的贡献者工作流程、测试预期或发布流程时，请更新知识库。 - 如果纯代码更改没有改变持久认知，应避免造成 Wiki 内容频繁变动。 - 当新规则开始广泛适用时，在同一次更改中更新贡献者指南。 - 使来源路径和时效日期与其支持的事实保持同步。 - 只有当知识更改足够实质、能帮助未来工作时，才添加日志条目。 - 报告完成前，对照已实现的行为验证最终文档。