Aider 实战：TaoToken 跑通 NumPy 2.x 兼容迁移

🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度

把仍依赖 NumPy 1.x 的开源仓库交给 Aider 做 2.x 兼容迁移，第一件事不是急着改代码，而是把默认供应商切到 TaoToken，再把 Base URL 填成 https://taotoken.net/api。Aider 在终端里工作，会读 repo map、改本地文件、生成 diff，也会按你的 prompt 去跑测试；它不会替你做“这个 np.int_ 到底该换成 int64 还是 intp”的业务判断，只会把候选 patch 摆出来。为了不让一次迁移直接污染生产 checkout，我先把目标仓库 clone 到临时目录，开一个 migrate/numpy2 分支，再让 Aider 只在这个副本里活动。本文记录的是 Agent 实战流程：Aider 启动命令、迁移 prompt、diff 统计和验证方法；不评价榜单分数，也不把任何公榜数字拼进来。迁移任务本身很具体：把 np.float_、np.complex_、np.string_、np.unicode_、np.Inf、np.NaN、np.int_ 等 NumPy 1.x 别名替换成 NumPy 2.x 可接受的写法，并让仓库的测试在 NumPy 2.x 下重新跑通。

1. 任务目标：把 NumPy 1.x 仓库交给 Aider 做 2.x 兼容迁移

NumPy 2.0 的兼容迁移不是一次全局查找替换就能收工的。它移除了大量旧别名，也在 dtype 语义、字符串类型、标量类型上做了收紧。一个仍依赖 NumPy 1.x 的仓库，常见问题是：代码里写了 np.float_，在 NumPy 1.x 下能用，到了 NumPy 2.x 直接 AttributeError；写了 np.complex_ 或 np.string_，同样在导入阶段就炸；写了 np.Inf、np.NaN，运行时才报错；写了 np.int_，在 64 位 Linux 上看起来等价于 np.int64，但在 Windows 上底层 C long 是 32 位，直接换成 np.int64 会改变行为。这些问题混在一起，如果让人工一行行翻，很容易漏掉测试文件、脚本目录、Notebook 导出文件里的残留。

Aider 适合这个任务的原因在于，它本身就是一个终端里的结对编程 Agent。你给它一个仓库路径和模型，它会先构建 repo map，把文件结构、符号位置、关键函数压缩成上下文；你让它扫描，它可以只读不改；你让它改，它可以按文件分批出 patch；你让它跑测试，它可以把失败输出再贴回对话。整个过程发生在本地 checkout 里，改动的文件、生成的 diff、执行的测试命令都留在本地，不会直接打到远端生产分支。这一点对迁移任务很重要：兼容迁移本质上是“先看清单，再分批改，再验证”，而不是让 Agent 一口气重写整个仓库。

迁移范围可以先列成一张表，让 Aider 按表执行，而不是自由发挥。下面这张表是我在 prompt 里会直接贴给 Aider 的规则，具体到仓库时再让它先扫描确认。

NumPy 1.x 写法	NumPy 2.x 建议写法	需要人工确认的点
np.float_	np.float64	原本是否依赖平台相关的 float 宽度
np.complex_	np.complex128	是否与 C 扩展的 complex 类型对齐
np.string_	np.bytes_	是否用于固定宽度字节串
np.unicode_	np.str_	是否用于固定宽度 Unicode
np.Inf、np.infty	np.inf	是否在比较或初始化中使用
np.NaN	np.nan	是否在测试断言里直接比较
np.int_	np.int64 或 np.intp	索引/指针算术用 intp，普通整数 dtype 用 int64
np.int0	np.intp	是否用于索引数组
np.bool8	np.bool_	是否在旧测试里当布尔 dtype

这张表的重点不是“全部替换”，而是“先分类”。np.float_ 这类被移除的别名可以直接换；np.int_ 这类语义依赖平台的符号不能盲目换。Aider 的 prompt 里我会明确要求：遇到 np.int_ 先列出使用上下文，再决定是 np.intp 还是 np.int64；遇到 np.NaN 先看是否在 assert 里，如果是，建议改成 np.isnan 判断，而不是简单换 np.nan 后继续用等号比较。这样 Aider 产出的就不是一堆机械替换，而是一份可以 review 的迁移清单。

任务目标也要定得可验证：迁移完成后，仓库在 NumPy 2.x 下能 import，能跑 pytest，能把原来因别名移除而失败的用例转绿；同时 diff 里不出现无关重命名、不出现格式大改、不出现依赖升级。Aider 的 /run 和 --test-cmd 可以帮忙把测试命令固定下来，但最终判断仍然由人做。为了可复现，我会把目标仓库固定到一个 commit，把 NumPy 版本固定到 2.x 的某个小版本，把 Aider 的启动命令和 prompt 都写进一个迁移记录文件，避免下次换机器时又要靠记忆重来。

2. Aider Harness 与 TaoToken 默认供应商配置

Aider 的安装方式比较简单，用 pip 或 pipx 都行。我这次的 Harness 是 Python 3.11 虚拟环境加 aider-chat，命令行里先确认版本，再配供应商。Aider 底层走 LiteLLM，所以接 OpenAI 兼容端点时，核心是三样：Base URL、API Key、模型 ID。Base URL 这一项要用 https://taotoken.net/api，末尾不带 /v1；API Key 用从 Taotoken 控制台创建的 YOUR_API_KEY；模型 ID 写 Qwen3.8 Max，实际接入时以模型广场展示的 ID 为准。把这三样固定下来之后，Aider 就不会在 provider 解析里来回猜，也不会把请求发到默认的 OpenAI 域名上去。

安装与版本确认可以先跑这两条：

python -m pip install -U aider-chat
aider --version

接下来是默认供应商配置。最直接的方式是用环境变量，把 Aider 的 OpenAI 兼容端点指向 Taotoken：

export OPENAI_API_BASE=https://taotoken.net/api
export OPENAI_API_KEY=YOUR_API_KEY
export AIDER_MODEL="openai/Qwen3.8 Max"

如果你不想把变量写进 shell 配置，也可以在启动 Aider 时用参数传入：

aider --openai-api-base https://taotoken.net/api \
  --openai-api-key YOUR_API_KEY \
  --model "openai/Qwen3.8 Max" \
  --no-auto-commits \
  --yes-always

这里有几个细节值得写清楚。第一，Aider 的模型名用 openai/ 前缀，是因为它会把请求按 OpenAI 兼容协议发到 OPENAI_API_BASE，而不是真的去连 OpenAI 官方。第二，--no-auto-commits 建议打开，迁移过程中 Aider 可能分多轮改文件，自动提交会把中间态也写进历史，后面 review 反而麻烦。第三，--yes-always 只在你确认仓库在临时副本里时再用，它可以减少交互确认，但也会让 Aider 更“敢”改文件，所以生产 checkout 上不要这么干。第四，API Key 不要写进仓库里的 .aider.conf.yml，配置文件适合放模型名和 Base URL，Key 走环境变量或本地密钥管理。

如果团队习惯用配置文件，可以在项目根目录放 .aider.conf.yml，但只放非敏感项：

openai-api-base: https://taotoken.net/api
model: openai/Qwen3.8 Max

Key 仍然用 OPENAI_API_KEY 环境变量注入。这样在共享机器上不会把密钥带进 git。模型 ID 这里写 Qwen3.8 Max，如果模型广场上展示的是带连字符或大小写不同的版本，就按广场实际 ID 替换，并保留引号，避免空格被 shell 拆开。创建 Key 的入口在控制台，登录后可以按项目建不同 Key，迁移任务单独用一个 Key，后面在用量页看这次 Aider 调用消耗了多少 token，也方便和别的任务区分。

默认供应商设好之后，可以先让 Aider 做一次最短连通性检查：在一个空目录里启动 Aider，输入 /ask 只回复 ok，看它是否正常返回。这一步比直接上大仓库更省事，因为大仓库的 repo map 构建会把 Base URL 配置错误、Key 错误、模型 ID 错误混在一起，排障反而慢。连通性没问题，再进入目标仓库。关于模型广场当前的 ID、计费单位和上下文长度，以 Taotoken 展示为准，不要凭记忆写死。

3. 迁移 prompt 与 Token/上下文控制

Aider 的迁移效果，七成看 prompt。NumPy 2.x 兼容迁移最怕的是“一口气全改”，因为 Aider 在单轮里能看到的上下文有限，仓库越大，repo map 越容易被截断，模型就越可能只改到它眼前那几个文件。我的做法是把 prompt 拆成三个阶段：只读扫描、分批修改、回归验证。每个阶段都用单独一轮对话，改完一批就停下来看 diff，而不是让 Aider 连续改到测试全绿为止。

第一阶段是只读扫描，prompt 要明确“不要改文件”。可以这样写：

先不要改任何文件。请扫描当前仓库，列出所有仍使用 NumPy 1.x 兼容别名的位置，按文件路径和行号输出，并给每个符号标注建议的 NumPy 2.x 替代。重点检查：np.float_、np.complex_、np.string_、np.unicode_、np.Inf、np.infty、np.NaN、np.int_、np.int0、np.bool8。不要执行 git 写操作，不要修改文件，只输出清单。对于 np.int_，先不要给最终建议，只列出它出现的上下文。

这一轮的作用是拿到迁移清单。Aider 会读 repo map，也可能用 grep 方式找符号，输出一个按文件分组的列表。你拿到列表后，先人工确认哪些文件在迁移范围内，哪些是第三方 vendored 代码、自动生成文件、历史归档，不应该动。然后进入第二阶段。

第二阶段是分批修改，一次只给 Aider 几个文件。prompt 可以这样写：

现在按你上一步列出的清单做第一批替换，只处理 <文件A> 和 <文件B>。规则：np.float_ -> np.float64；np.complex_ -> np.complex128；np.string_ -> np.bytes_；np.unicode_ -> np.str_；np.Inf、np.infty -> np.inf；np.NaN -> np.nan；np.bool8 -> np.bool_。遇到 np.int_ 不要全局替换，先列出使用上下文；如果用于索引或指针算术，候选是 np.intp；如果用于普通整数 dtype，候选是 np.int64。每改完一个文件，先展示 diff，不要自动提交。

这一轮里 Aider 会调用编辑工具改文件。你可以在 Aider 里用 /diff 看当前改动，用 /add 把相关测试文件加进上下文，用 /drop 移除不相关文件。对于 np.NaN 在断言里出现的场景，prompt 里最好加一句“如果原代码用 == np.NaN 或 assert x == np.NaN，改成 np.isnan(x) 判断，不要只换符号”。这样能避免迁移后测试仍然失败但错误信息变了。

第三阶段是回归验证，prompt 可以写：

现在运行 pytest -q，把失败输出贴回来。只根据失败信息做最小修改，不要顺便重构无关代码，不要改测试预期来绕过失败，除非测试预期本身就是 NumPy 1.x 的旧行为。每次修改后重新运行对应测试文件。

Token 与上下文控制是这个任务里很容易被忽略的一环。Aider 的 repo map 会占用上下文预算，仓库越大，留给代码修改的空间越小。可以用 --map-tokens 控制 repo map 的预算，比如先给 2048，如果 Aider 找不到文件再往上调。也可以在 Aider 里用 /tokens 看当前 token 使用情况，用 /context 看上下文里到底有哪些文件。对于迁移任务，我通常会把测试文件和目标模块加进上下文，把文档、示例数据、大型二进制资源排除在外。Aider 的 /drop 可以移除文件，/add 可以添加文件，/read 可以把文件设为只读参考。模型 ID 用 Qwen3.8 Max，上下文长度和计费单位以模型广场为准；如果仓库特别大，宁可多分几批，也不要为了让 Aider “看全”而硬塞上下文，截断后的 repo map 反而更容易让模型漏改。

还有一个实用技巧：把迁移规则写成一个 MIGRATION_NOTES.md，用 --read 让 Aider 只读引用。这样每轮 prompt 不用重复粘贴大段映射表，Aider 也能在修改时引用同一份规则。规则文件里可以放这张别名映射表、测试命令、不允许改的目录列表。Aider 不会自动修改只读文件，但会把它作为上下文参考。这样做的另一个好处是，迁移结束后这份文件本身就是审计记录，说明每个替换决策的依据。

4. 用 Aider 跑通 NumPy 2.x 替换的步骤

真正跑迁移时，我建议把步骤固定成可重复的清单，每一步都有命令和检查点。下面按顺序写一遍，命令里的仓库路径、虚拟环境名可以按实际情况替换，但 Base URL 和模型 ID 的写法保持不变。

先准备临时 checkout 和独立环境：

git clone <repo-url> /tmp/numpy2-migration
cd /tmp/numpy2-migration
git checkout -b migrate/numpy2
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -U "numpy>=2.0" pytest
python -m pip install -e .

然后确认迁移前的基线。先看 NumPy 版本，再跑一次测试，把失败记录下来：

python -c "import numpy as np; print(np.__version__)"
pytest -q

基线很重要，因为有些失败是仓库原有问题，不是 NumPy 2.x 迁移造成的。把基线失败清单保存到本地文件，后面 Aider 跑完后再对比，能区分“迁移引入的失败”和“本来就坏的测试”。

接着启动 Aider，把默认供应商指向 Taotoken：

export OPENAI_API_BASE=https://taotoken.net/api
export OPENAI_API_KEY=YOUR_API_KEY
aider --model "openai/Qwen3.8 Max" \
  --no-auto-commits \
  --yes-always \
  --map-tokens 2048 \
  --test-cmd "pytest -q"

进入 Aider 交互界面后，先把迁移规则文件加进去，再跑第一阶段扫描。可以按 /add MIGRATION_NOTES.md，然后粘贴上一节的“只读扫描”prompt。扫描结果出来后，把清单复制到本地，人工筛一遍。筛完后按文件分批，每批两到四个文件，跑第二阶段修改 prompt。每批结束后在 Aider 里用 /diff 看改动，确认没有无关重命名、没有格式大改、没有把测试断言改成永远为真。

分批修改的节奏可以这样控制：第一批处理被移除的别名，比如 np.float_、np.complex_、np.string_、np.unicode_；第二批处理常量和标量，比如 np.Inf、np.NaN、np.bool8；第三批单独处理 np.int_，因为这一批需要看上下文，不能和别名替换混在一起。每批改完都跑一次对应测试，不要攒到最后一起跑。Aider 的 /run pytest tests/test_ops.py -q 可以直接在会话里执行测试，失败输出会进入上下文，方便下一轮修改。

所有批次完成后，退出 Aider，在 shell 里跑全量测试和编译检查：

pytest -q
python -m compileall -q .

然后统计迁移 diff。用 git diff --stat 对比主分支和迁移分支，可以得到文件级改动统计。下面是一份示例输出，数字来自本机一次运行，只代表当时那个仓库，不同仓库的数字会不同，也不代表任何公榜：

numpy_compat/__init__.py |  6 +++---
numpy_compat/ops.py      | 42 +++++++++++++++++++++---------------------
tests/test_ops.py        | 18 +++++++++---------
3 files changed, 33 insertions(+), 33 deletions(-)

如果只看改动行数还不够，可以再跑一次 git diff --numstat，把新增和删除行数分开记录；也可以用 git diff --word-diff 检查是否有符号被误替换。diff 统计的目的不是追求“改得越多越好”，而是确认迁移范围可控：被移除的别名是否全部消失，np.int_ 的每一处是否都有明确决策，测试文件是否只改了必要的断言。Aider 生成的提交信息可以统一写成 migrate: numpy 2.x compatibility，但提交前一定人工过一遍 diff，不要让 --yes-always 替你按下确认键。

最后把迁移记录写回仓库外的笔记，包括目标 commit、NumPy 版本、Aider 版本、模型 ID、启动命令、每批 prompt、测试结果、diff 统计。下次换仓库时，先把这份记录复制过去，只改仓库路径和文件清单，就能复现同一套流程。本文里没有排行分数，也不把这次本地 diff 当成 benchmark；它只是一次 Agent 迁移的运行记录。

5. 验证迁移 diff 与回归测试

迁移完成后，验证要分三层：符号残留、行为回归、用量对账。第一层是符号残留检查，直接在仓库根目录跑 grep，确认被移除的别名不再出现。命令可以写成：

grep -RIn --exclude-dir=.git --exclude-dir=.venv \
  -E "np\.(float_|complex_|string_|unicode_|Inf|infty|NaN|int0|bool8)" .

如果还有输出，逐条看是漏改还是故意保留。比如某些 vendored 第三方代码不在迁移范围内，可以在迁移记录里注明豁免，而不是让 Aider 去改别人维护的文件。对于 np.int_，grep 不到它不代表迁移完成，因为可能已经被替换成 np.int64，需要再检查替换后的位宽是否符合原意。这一步可以用 git diff -U0 | grep -n "int_" 看替换位置，再对照上下文。

第二层是行为回归。pytest 全绿只是最低要求，还要看 NumPy 2.x 下 dtype、标量、字符串行为是否变化。可以写几个最小检查脚本，让 Aider 生成后由你本地执行，再把结果贴回对话。比如检查浮点 dtype：

import numpy as np

a = np.array([1, 2, 3], dtype=np.float64)
print(a.dtype)
print(np.issubdtype(a.dtype, np.floating))

检查整数位宽：

import numpy as np

print(np.dtype(np.int_).itemsize)
print(np.dtype(np.intp).itemsize)
print(np.dtype(np.int64).itemsize)

在 64 位 Linux 上，np.int_ 和 np.int64 的 itemsize 通常都是 8，但 Windows 上 np.int_ 可能是 4。如果原仓库有跨平台测试，直接把 np.int_ 换成 np.int64 可能改变 Windows 行为。这里是迁移里比较隐蔽的坑：Aider 会按你给的规则替换，但规则本身要写清楚“先判断用途”。如果原代码用 np.int_ 做数组索引，更稳的是 np.intp；如果明确需要 64 位整数 dtype，才用 np.int64。验证时可以把这两类位置分别列出来，确认替换策略一致。

NaN 断言也要单独看。NumPy 1.x 代码里可能写 assert x == np.NaN，这在 NumPy 2.x 下即使换成 np.nan 也不会变成 True，因为 NaN 不等于自身。正确的写法是 np.isnan(x) 或 np.isclose 配合 equal_nan=True。Aider 如果只做符号替换，这类测试会继续失败；prompt 里明确要求把断言改成 np.isnan 判断，验证时再搜一遍 == np.nan 和 == np.NaN 的残留。

第三层是用量对账。Aider 跑完迁移后，回到 Taotoken 控制台看这次任务的调用记录，确认 Key、模型 ID、时间范围和 token 用量。对账的意义有两个：一是确认所有 Aider 请求都走了统一入口，没有落到别的 provider；二是为下次迁移估算预算，比如扫描阶段用多少 token、分批修改阶段用多少、全量测试重跑阶段用多少。用量页还能看到失败请求或限流记录，如果 Aider 中途报 401 或模型不存在，先回控制台确认 Key 状态和模型 ID，而不是反复改 Base URL。

如果迁移结果不理想，回滚要简单：在临时 checkout 里用 git checkout -- . 撤销未提交改动，或者 git reset --hard 回到迁移前 commit，再重新开分支。不要在生产 checkout 上直接让 Aider 改文件，也不要让 Aider 执行部署脚本、数据库迁移或任何会打到生产环境的命令。Aider 可以生成和解释 SQL、shell 命令，但执行动作要由你在本地或隔离环境完成，再把输出贴回对话。验证通过后，把迁移分支推到远端，走正常的 code review 流程，而不是直接合入主干。

6. 创建 Key 复现 NumPy 2.x 迁移对照表

这次迁移跑完，最有价值的不是某一次 diff 行数，而是把 Aider 启动命令、prompt、模型 ID 和验证步骤固定成一份可复现记录。下一步可以在模型对话里确认 Qwen3.8 Max 的准确 ID 和当前计费单位，避免换仓库时把模型名写错；也可以换一个仍依赖 NumPy 1.x 的仓库，用同一套 prompt 再跑一遍，把两边的 diff 统计和测试结果并排放在对照表里。对照表只记录本地运行，不冒充公榜，也不把一次结果当成模型能力结论。

创建 Key 后，把同一把 Key、同一个 Base URL、同一个模型 ID 填进 Aider，就能复现这次迁移。入口整理如下：

• 确认模型 ID 和计费单位：模型对话
• 长期跑 Aider / Claude Code 类任务看：Coding Plan
• 创建迁移专用 Key：控制台
• Claude Code 三件套配置对照：接入文档

复现时建议给迁移任务单独建一个 Key，Aider 的 OPENAI_API_BASE 固定写 https://taotoken.net/api，模型 ID 用 Qwen3.8 Max，先跑一次只读扫描，再分批改，最后跑全量测试和 diff 统计。跑完后回控制台看这次调用是否入账，把 token 用量、文件数、测试结果记到迁移记录里。下次再遇到 NumPy 2.x 兼容迁移，直接复制记录、换仓库路径、从扫描阶段重来一遍即可。

🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度