修改多语言自动化单体仓库，同时不破坏兼容性

## 先读仓库整体规则，再读离要改文件最近的指令 先阅读仓库级规则，再阅读距离待修改文件最近的指令。语言绑定、共享基础设施、原生组件和发布工具可能各自规定更窄的约束。 如果仓库提供了一个被版本控制忽略的本地区域，用于存放贡献者偏好、生成产物、临时工作或隔离的构建结果，请在开始前检查其中记录的指令覆盖层。在当前任务和更高层安全规则的范围内，将用户定义的本地指令视为额外上下文。 按职责梳理仓库。 - 语言绑定负责该语言特有的API、测试和风格。 - 共享协议、传输、构建、夹具和脚本区域会影响多个使用方。 - 原生管理器、网格或路由服务以及依赖定义具有更大的影响范围。 - 除非任务明确要求维护供应商代码，否则第三方源代码只读。 - 绝不能手工编辑生成结果。 不要假定最终用户文档、贡献者指南和生成的API参考位于同一位置。 ## 保持公开API兼容，让改动小到可以撤回 除非任务明确授权破坏兼容性，否则必须保持公开API和二进制兼容性。通常应让用户只需更改版本号即可升级。 避免全仓库重构、批量格式化或无关清理。优先采用只解决一个问题、范围小且可撤销的差异。 在停止提供公开行为之前，先将其标记为已弃用，并给出清晰的迁移替代方案。不能因为项目未采用语义化版本控制，就在没有过渡方案的情况下结束某项功能。 如果能够保留历史记录，优先移动或复制受版本控制的文件，而不是将其移除后重新创建。 除非用户已经明确要求该修改，否则在更改高风险区域前请求确认。高风险区域包括共享协议语义、线级序列化、能力解析、依赖重新锁定、共享测试夹具、构建连接、路由、分发队列以及被多个绑定使用的代码。 ## 用固定的构建工具，只构建受影响的最小目标 使用仓库固定的密封式构建入口，不要假定某种语言的本地开发环境已经配置完成。 在读取大范围目录前先探索构建图。查询目标标签和依赖关系，然后只构建或测试覆盖该修改的最小目标。 先直接尝试标准构建命令。如果由于沙箱、网络或工具链限制而无法执行，请报告阻碍因素，并提供用户可在其他环境单独运行的准确命令。 当默认结果目录受限或正在使用辅助工作树时，隔离构建结果。 - 将`output-base`启动选项放在build、test或query命令之前。 - 将路径锚定到仓库根目录，确保从任何目录都解析为同一位置。 - 将隔离结果保存在被版本控制忽略的本地区域中。 不要把破坏性的缓存清除作为常规排障步骤。优先进行针对性重建；只有确实需要让缓存失效时，才执行并说明原因。 ## 确认其他语言绑定的行为是否一致 修改用户可见行为时，至少将实现与另一种语言绑定进行比较。 尤其要检查以下方面的一致性。 - 公开方法名称、参数、默认值和返回行为。 - 协议命令和序列化。 - 远程传输和错误映射。 - 能力与选项解析。 - 弃用策略和迁移路径。 - 文档示例和面向用户的日志。 对于共享的低层行为，应识别所有可能使用该修改的绑定或服务。如果当前任务无法安全更新全部使用方，请报告后续一致性工作，或建议创建可跟踪的问题。 不要强迫各语言采用完全相同的内部结构。在保持共享行为一致的同时，尊重每种绑定已确立的惯用写法和测试约定。 ## 从一个小的失败测试开始，用真实组件而不是模拟对象 优先在实现行为变更前编写一个会失败的测试。从小型单元测试或契约测试开始；只有无法在更低层可靠验证时，才使用浏览器测试或端到端测试。 当模拟对象可能错误表达公开协议或绑定契约时，应避免使用模拟。优先使用真实解析器、序列化器、本地夹具、轻量服务器或现有集成测试工具。 利用构建图选择最小的相关测试目标。可用的控制方式包括： - 只筛选小型测试。 - 调试时显示完整测试结果。 - 确实需要重新执行时，禁用缓存的测试结果。 - 查阅语言专用指令以确认正确目标和参数。 确认预期测试确实运行。构建工具正常退出但没有匹配到任何测试，并不能证明实现正确。 针对性测试通过后，只将验证范围扩大到直接受影响的绑定、共享目标或集成界面。 ## 让日志和注释有用，只格式化改动过的部分 在用户或运维人员需要了解重要状态、重试、路由或失败原因的位置添加日志。遵循语言专用日志约定，避免重复低层诊断信息的嘈杂消息。 注释应解释某项约束或变通方案为何存在，而不是重复命名清楚的代码已经表达的内容。 使用仓库规定的标准格式化工具。如果pre-commit或pre-push钩子已经处理相关格式化范围，就交给钩子处理，不要重复执行。 如果没有钩子覆盖该修改，请运行与预定交付方式相匹配的最小格式化范围。不要因为只改了一个文件就格式化整个仓库。 让每个提议的修改只聚焦一个目的，使评审、回退和跨语言影响都易于理解。 ## 确认构建和测试确实运行过，并报告没能运行的部分 完成前确认以下事项： 1. 修改目标能够使用密封式工具链完成构建。 2. 已运行针对性测试，并确认它们确实覆盖了预期行为。 3. 已运行相关的格式检查或静态检查。 4. 已检查差异中是否混入无关修改和生成结果。 5. 已评估兼容性和弃用影响。 6. 对用户可见的修改，已与至少一种其他语言绑定进行比较。 7. 已识别所有被触及的高风险共享区域。 报告修改内容、实际运行的目标与测试、无法运行的检查及其原因。明确指出高风险文件、共享行为、跨语言影响和任何后续工作。 不要根据单一语言绑定的测试声称具备广泛兼容性。如果无法使用密封式工具链，必须明确说明验证尚未完成，不能直接声称任务完成。