1. 百万行代码迁移为什么单靠一个 Agent 会崩大型项目做跨语言或跨框架迁移最直观的痛点不是“翻译”本身而是翻译之后没人能保证行为一致。一个几十万行的 Python 服务要迁到 TypeScript或者一个 Zig 写的运行时迁到 Rust代码量摆在那里人工逐文件改写基本不现实。Claude Code 的 Agent 与 Subagent 机制之所以适合这类场景是因为它能把“迁移”拆成可并行、可验证、可回滚的任务单元而不是让一个模型从头到尾硬扛。我试过把一个小型 Node 项目整体丢给单个 Agent 做框架迁移结果前 20 个文件还算正常到第 30 个文件开始出现命名风格漂移、错误处理方式不一致、部分工具函数被重复实现。问题根源在于单个 Agent 的上下文里没有一份稳定的“规则手册”它每处理一个新文件都在重新做判断。大规模迁移必须解决三件事——规则统一、任务可拆分、结果可机械验证。这也是 Claude Code 的 Agent 与 Subagent 分工协作的核心价值。这篇文章面向正在做或准备做跨语言/跨框架迁移的团队给出一份可复用的迁移规则手册目录骨架、Subagent 任务拆分模板以及一次小范围迁移的验证步骤与检查清单。你可以把它当成一套可跟做的工程流程而不是某个模型的评测。2. TaoToken 前置把 Claude Code 的模型调用接进来Claude Code 本身是一个命令行编码工具它需要能访问 Claude 系列模型。TaoToken 提供的是模型 API 接入能力你可以把它理解为“让 Claude Code 能稳定调用模型的通道”。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。接入前你需要先拿到 API Key。打开控制台页面 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 管理里创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。拿到 Key 之后Claude Code 的配置通常通过环境变量注入。下面是一份可复制的配置示例把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY填你刚创建的 Keyexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key如果你用的是 Claude Code 的配置文件方式可以在项目根目录或用户目录下写入对应配置。配置完成后先做一次最小验证确认通道可用claude --version claude -p 用一句话说明什么是代码迁移如果第二条命令能正常返回内容说明模型调用已经打通。这一步很关键因为后面所有 Agent 和 Subagent 的调度都依赖这条通道。如果这里报 401 或连接超时先检查 Key 是否复制完整、Base URL 是否写成了https://taotoken.net/api不要多加路径。对于需要长期跑迁移任务的团队建议关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的编码与 Agent 调度场景。模型对话能力可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 查看接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。3. 迁移规则手册的目录骨架规则手册是整个迁移流程的“宪法”。它的作用是当两个 Agent 面对同一个转换问题时必须给出同一个答案。只要存在两种合理答案就应该提前定死写进手册。下面是一份可直接落地的目录骨架适用于保留原架构的迁移比如 Zig 到 Rust、Python 到 TypeScript# 迁移规则手册 v1 ## 1. 语言映射总则 ### 1.1 类型系统对应表 ### 1.2 错误处理与异常模型 ### 1.3 内存/资源管理约定 ### 1.4 命名与目录结构约定 ## 2. 惯用写法替换 ### 2.1 循环与迭代 ### 2.2 集合与容器 ### 2.3 字符串与编码 ### 2.4 并发与异步 ## 3. 差距清单无法直接转换项 ### 3.1 运行时隐含行为 ### 3.2 动态类型/反射相关 ### 3.3 平台相关 API ## 4. 禁止事项 ### 4.1 不允许的临时绕过 ### 4.2 TODO 标记规范 ## 5. 验证与验收 ### 5.1 编译检查 ### 5.2 测试套件 ### 5.3 行为 diff 规则差距清单是手册里最容易被忽略、但最关键的部分。源语言里有些知识藏在运行时行为、动态类型或内存管理方式中目标语言要求你显式写出来。比如 Zig 里调用方需要手动释放内存Rust 里所有权转移后自动释放这类差异必须逐条记录供实现 Agent 查询。一个实用的判断标准只要两个 Agent 对同一个转换可能给出不同答案就写进手册。手册不是一次写完的它会在压力测试和批量迁移中不断回写。4. Subagent 任务拆分模板Subagent 的价值在于“上下文隔离”。每个 Subagent 只负责一个明确的迁移单元不共享彼此的中间状态这样可以避免错误在 Agent 之间传染。下面是一份任务拆分模板你可以直接套用## Subagent 任务卡 - 任务 ID: port-模块名-批次号 - 输入文件: src/模块/文件列表 - 目标文件: dst/模块/文件列表 - 依赖前置: 必须先完成的模块 - 适用规则: 手册第 1.2、2.3 节 - 差距条目: gap-007, gap-012 - 验收命令: 编译命令 测试命令 - 失败处理: 标记 TODO(port): 原因不阻塞其他单元 - 审查要求: 两个独立上下文审查 Agent冲突时第三人裁决拆分粒度建议按“文件或小模块”为单位不要按函数拆太碎会导致调度开销超过收益也不要按整个子系统拆太大则单次失败成本高。一个批次控制在 10 到 30 个文件比较合适。任务队列最好由脚本自动维护而不是手工维护。脚本通过检查目标文件是否存在来判断哪些单元已完成再把剩余文件划分成新批次。这样迁移流程可以随时暂停和恢复Agent 中断后也能从已有进度继续。# 伪代码根据磁盘状态生成待迁移批次 for f in $(find src -name *.zig); do targetdst/${f#src/} target${target%.zig}.rs if [ ! -f $target ]; then echo $f fi done | split -l 20 - batch_5. 一次小范围迁移的验证步骤在正式批量迁移前必须先做一次小范围压力测试。这一步生成的代码不保留它的唯一任务是暴露规则和流程中的问题。第一步选 3 个有代表性的文件覆盖简单、中等、复杂三种情况。第二步让第一个 Agent 严格按规则手册翻译让第二个 Agent 以“资深目标语言工程师”的方式独立翻译同样的文件。第三步让第三个 Agent 对比两份结果根据 diff 补充规则手册。# 启动双翻译对比 claude -p 按规则手册翻译 src/a.zig 到 dst/a.rs只输出代码 claude -p 以资深 Rust 工程师身份翻译 src/a.zig只输出代码 claude -p 对比两份实现列出差异并指出规则手册缺失项如果两份实现差异集中在某几类问题上说明规则手册在这些点上不够明确。把差异回写进手册再重新跑一轮。只有当双翻译结果高度收敛才说明规则足够稳定可以扩展到全量文件。验证检查清单编译是否通过错误是否可归类原有测试套件是否全部运行新旧实现的输出 diff 是否为空错误码、退出码是否一致是否存在未标记的 TODO是否有 Agent 绕过了规则手册6. 批量迁移与编译验证循环进入批量阶段后流程基本固定实现、独立审查、修复。高吞吐的实现任务可以交给较小模型审查和规则修改交给更强模型。每个迁移单元由两个上下文独立的审查 Agent 检查意见冲突时交给第三个 Agent 裁决。编译验证要遵循“廉价检查高频运行昂贵检查集中处理”的原则。TypeScript 编译只要几秒可以在每个单元内运行Rust 工作区编译要几分钟统一留到批次结束后进行。# 批次编译并生成错误队列 cargo build --workspace 2 build_errors.log grep -E ^error build_errors.log | sort | uniq -c | sort -rn如果错误队列里出现大量重复错误说明迁移流程本身有问题而不是单个文件的问题。这时候应该停下来修改规则手册重新生成受影响的批次而不是围绕错误代码逐个打补丁。行为一致性验证是最后一道关。每个失败测试分配给一个修复 Agent由它同时检查新旧实现定位差异并提交补丁再由对抗式审查 Agent 复核。构建操作建议串行执行避免多个 Agent 重复构建相互干扰。7. 本篇常见错排查报错一401 Unauthorized。通常是 API Key 没配好。检查ANTHROPIC_API_KEY是否完整是否有多余空格。重新在控制台创建一个 Key 再试。报错二连接超时或 DNS 失败。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api不要多加/v1之类的路径。网络环境本身要能正常访问该地址。报错三Agent 输出风格漂移。说明规则手册覆盖不足。把漂移的案例回写进手册重新跑压力测试不要直接进入批量阶段。报错四编译错误大量重复。不要逐个修。先归类根因如果是规则问题就改手册如果是依赖顺序问题就调整依赖图然后重新生成批次。报错五测试通过但行为不一致。说明验收体系不够严。补充输出 diff、退出码、文件变化对比确保测试能识别真实差异。报错六任务队列卡住不推进。检查脚本判断“完成”的条件是否过于严格比如目标文件存在但内容为空也被算作完成。建议加上文件非空和编译通过双重判断。8. 把迁移变成可重复的工程流程大规模迁移真正难的从来不是写代码而是让每一轮生成的结果都可验证、可回滚、可修正。规则手册统一实现边界依赖图安排执行顺序差距清单记录例外任务队列和独立审查负责推进与校验。人类判断集中在前期——划定边界、设计验收体系、识别系统性偏差Agent 承担大规模重复性的实现和修复。如果你准备开始建议先从一个小模块跑通完整流程配置好 TaoToken 通道写好规则手册骨架用双翻译对比做压力测试再进入批量迁移。接入相关的 Key 和文档在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 和接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 需要长期跑 Agent 调度的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 更合适想先验证模型对话效果可以从模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 入手。Claude Code 相关的接入细节可以参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的说明。