translate-programming-language

翻译编程语言

使用此技能将生产环境中的服务端或应用程序代码从一种语言／运行时迁移到另一种，同时不丢失外部可观察到的行为。首先确保行为一致，然后再于旧运行时移除后，按照目标语言的特点简化代码。

核心规则

• 将源运行时视为初始基准，但在有公开标准时，应查阅该标准。
• 切勿手动编写预期测试数据。应从固定版本的源运行时或标准符合性测试框架生成。
• 可复用的迁移文档中不得包含特定领域的名称、URL、模式、客户或产品事实。
• 将语言／运行时特性放入兼容层，而非领域逻辑。
• 为每个兼容层制定删除计划：记录源行为、目标行为、标准／规范参考、调用方，以及切换后的迁移目标。
• 不要只依赖单元测试来验证行为一致性。切换前，应使用影子流量／重放流量验证，并执行贴近生产环境的基准测试。

工作流

1. 界定迁移边界

   • 选择一个范围较小的契约：函数、模块、端点、消息类型或协议处理器。
   • 清点输入、输出、副作用、状态、时钟、随机性、区域设置、环境变量、文件系统／网络使用情况和错误行为。
   • 确定外部可见契约要求的是字节完全一致、结构等价，还是语义等价。

2. 生成基准

   • 阅读 oracle-driven-parity.md。
   • 固定源运行时和依赖版本。
   • 针对常见情况、边界值、格式错误的输入、错误和副作用，从源实现生成测试数据输出。
   • 如果存在标准，应添加基于标准的测试用例，并记录源／目标运行时的差异。

3. 生成迁移测试

   • 阅读 test-migration.md。
   • 根据源测试、测试名称、数据提供程序、示例或 API 契约，生成目标语言的行为一致性测试桩。
   • 在 CI 中明确显示尚未完成的测试桩，然后用基于测试数据的测试替换它们，直到跳过／待处理测试数量归零。
   • 针对发现的每项语言／运行时差异，添加面向分支的测试用例。

4. 积累迁移知识

   • 阅读 compatibility-knowledge.md。
   • 维护一份持续更新的跨语言差异目录，涵盖数值转换、真值判断、数组／映射／顺序、JSON、URL 编码、正则表达式、时间、加密、二进制协议、HTTP、异常和并发。
   • 对每项差异，记录源行为、目标行为、可用时的标准行为、选定的兼容方案、测试和删除路径。

5. 迁移领域代码

   • 先迁移叶子／纯模块，再迁移共享辅助代码，然后是 I/O 适配器，最后是编排／端点代码。
   • 保持目标语言中的领域代码易读，并通过兼容辅助函数处理旧有特性。
   • 优先使用结构化解析器、官方协议库和生成代码，而非临时的字符串处理。
   • 只有在行为一致性得到验证后才重构；否则，确保每项更改都能追溯到源行为。

6. 在真实环境中验证并切换

   • 阅读 rollout-and-cutover.md。
   • 执行完整的行为一致性检查、源测试数据重新生成检查、生成测试偏差检查、竞态／静态检查和基准测试。
   • 使用重放或影子流量，比较真实请求／响应、日志、指标、标头、二进制负载和副作用。
   • 按明确的回滚阈值逐步进行金丝雀发布，然后至少保留旧运行时一个回滚窗口。

发布门槛

在所有适用的门槛都通过之前，不要宣布迁移已就绪：

• 源端预期结果重新生成后，不应出现意外的测试样例差异。
• 生成的兼容性测试桩与源测试／契约保持同步。
• 待处理／跳过的兼容性测试数量为 0，失败数量也为 0。
• 每项有意为之的运行时差异都已记录在兼容性知识库中。
• 构建、Lint／静态分析、竞态／并发检查和安全检查均已通过。
• 基准测试显示，延迟、吞吐量、分配或资源方面没有不可接受的回退。
• 影子运行／回放／金丝雀对比结果达到约定的差异阈值。
• 回滚路径已测试，且旧运行时在回滚窗口内仍可部署。

报告模板

在 PR 正文、设计说明或迁移状态报告中使用以下格式：

## Scope
- Source boundary:
- Target boundary:
- Contract level: byte-exact / structural / semantic

## Oracle
- Source runtime/dependency versions:
- Fixture generation command:
- Standard/spec references:
- Boundary classes covered:

## Test Migration
- Source tests/contracts discovered:
- Generated stubs:
- Pending parity tests:
- Drift checks:

## Compatibility Knowledge
- New runtime differences:
- Compatibility helpers added:
- Deletion plan:

## Verification
- Unit/parity:
- Race/static/build:
- Benchmarks:
- Shadow/replay:
- Canary:
- Rollback: