The Type去年底我接到一个头疼的活儿：把一个 800 多行的核心服务函数按业务域拆成小函数，纯手工改得在 800 行里来回扫。我花两个周末搭了一套自动化代码重构 Agent Harness，让大模型从一次性的聊天工具变成能跑完整重构流水线的执行单元。这篇文章就是这套 Harness 的实战记录：设计思路、核心代码、实测踩坑都在里面，适合手里有批量重构需求、又不想让模型裸跑改乱代码的团队参考。
1. 手工重构的痛苦与"给 Agent 套上缰绳"的解题思路
1.1 一个 800 行函数背后的重构成本
我接手那套遗留系统时，最难啃的骨头就是 process_order——订单校验、支付处理、库存预占、优惠计算、消息通知五件事全塞在一个函数里。任何一次需求变更都得先在大函数里定位，改完还要担心影响其他分支。重构它成了团队里的"政治正确"，但谁提谁头疼。
我粗略算过一笔账。纯手工提取方法的话，先把 800 行按业务域切分，光边界梳理就得两三个小时；提取过程中要处理局部变量穿越函数边界的问题——被提取的逻辑里可能引用外层 7 个变量，你得决定哪些作为参数传入、哪些作为返回值带回，这一步最容易改错；最后还要保证测试全绿。我当时的经验是一个 800 行函数的重构，从动手到全量回归完成至少需要半天，中间如果踩到隐式依赖的坑，加班到夜里也很正常。
重复性重构更折磨人。系统里还有十几个结构类似的"上帝函数"，它们形态相近但业务细节不同，意味着同样的分析过程要重复十几遍。这种工作放到人身上就是枯燥加高错率，放到大模型身上却正中下怀——恰恰是这种"有规律可循、细节繁琐、容忍度低"的任务，最应该交给自动化去做。这也是我决定搭建 Harness 的最初动机：不是想偷懒，而是这种工作手做太容易出错。
1.2 大模型擅长什么、不擅长什么：为什么不能裸跑
动工之前我做过一轮快速实验：把同一个重构任务分别用"直接甩给模型"和"放在约束框架里"两种方式跑，结果差异非常明显。
直接裸跑时，大模型确实能给出看起来像样的重构方案——函数拆分点选得合理，命名也贴切。但问题出在细节上。它在提取支付处理逻辑时漏掉了一个 except 分支，理由是"该分支在当前逻辑中不可达"；它在处理全局变量时擅自改了初始化顺序；最致命的是，它把原来抛出业务异常的地方改成了静默返回。这些错误在代码评审里很难一眼看出来，因为改动后的代码在正常路径下跑起来毫无问题，只有在特定异常路径上才会暴露行为不一致。
裸跑的第二个问题是缺乏验证闭环。它生成完补丁就结束了，没人跑测试、没人检查改动范围、没人确认它有没有顺手改掉无关代码。实际上我的第一次裸跑实验里，模型确实"顺手"给同一文件的另一个函数改了缩进风格。这种行为在人工操作时还能发现，在自动化的批处理场景里就完全不可接受。
所以结论很明确：大模型可以做重构的"手脚"，但必须给它套上缰绳。单独的模型调用不是一个可用的重构工具，模型外加一层控制框架才是。这层控制框架就是这篇文章要讲的 Agent Harness。
1.3 Harness 是什么：用"导演"来类比
很多人第一次听到 "Agent Harness" 会以为它是一个具体的开源库或者某个框架。其实这个词更准确的翻译是"代理执行约束框架"——一套把 Agent 的规划、执行、验证、回滚全部纳入管理的运行系统。模型是演员，Harness 是导演：演员负责贡献戏份，但剧本怎么拆、走位怎么定、演砸了怎么重来，都由导演说了算。
具体到代码重构这个场景，Harness 需要回答四个问题：做什么（任务解析）、改成什么（方案生成）、改完对不对（验证）、改错了怎么办（回滚与重试）。四个问题对应四个核心机制：任务规划、补丁生成、多层验证、安全门控。后面几节我会把每个机制的实现细节和踩坑过程一一展开。
这套东西适合谁？如果你只是偶尔用 AI 帮忙改一两处代码，不需要 Harness。但如果你手上有批量重构需求、要在一个周末内完成十几个同类函数的拆分，或者你打算把重构做成 CI 流程里的定时任务，那 Harness 就是必需品。它能把这套流程从"碰运气"变成"可预期"。
2. Harness 整体骨架：规划器、执行器、裁判员三个模块怎么分工
2.1 规划器：任务拆解与文件清单生成
Harness 的第一个模块是规划器（Planner），职责是把一个自然语言或结构化描述的重构任务拆解成可执行的工作流。
我一开始把规划器做得很重，希望它自己读全部代码库然后决定改哪里。结果发现这是最愚蠢的设计：让模型读整个仓库既浪费 token，又容易让它"发现"一堆不在范围内的"额外问题"。后来我改成轻量级规划器：只负责确定目标文件、目标函数、重构策略和改动边界，具体的代码阅读交给执行器按需进行。
任务描述我用的是 YAML 格式。比如拆分大函数的任务长这样：
yaml复制task: split_function
id: refactor-order-service-001
target_file: src/services/order_service.py
target_function: process_order
strategy: extract_method
split_plan:
- chunk_lines: [120, 260]
new_function: payment_processing
- chunk_lines: [261, 410]
new_function: inventory_reservation
- chunk_lines: [411, 530]
new_function: discount_apply
constraints:
untouched_files: ["src/services/order_service.py", "src/models/"]
behavior_preserve: true
max_retries: 3
规划器的核心工作是校验任务描述本身自洽：目标函数存在、行号范围没有超出函数边界、策略名称在支持列表里。这些校验不需要大模型，用 tree-sitter 解析一次 AST 就能完成。规划器越"笨"越好，因为它负责的是确定性和可靠性，留给模型的判断空间越小，最终结果越可控。
2.2 执行器：上下文组装与补丁生成
执行器（Executor）是真正和大模型打交道的模块。它的工作简单说就两步：把重构所需的上下文组装成一个高质量的提示词，然后拿到模型生成的补丁。
上下文组装是整个执行器里最容易出错、也最影响效果的环节。我第一版实现很粗暴，直接把整个 order_service.py 塞进提示词，结果碰到两个问题：一是文件超过模型上下文长度，二是模型容易注意到文件里和重构无关的部分。后来我换成了"按符号收集"的思路——用 tree-sitter 解析出 process_order 的完整 AST，把它调用的辅助函数、引用的模块级变量一并收集，再配合 LSP 拿到 process_order 的所有调用方，拼成一个"重构局部视图"。这个视图通常只有几百行，但包含了模型做出正确决策所需的全部要素。
补丁生成方面，我强烈建议让模型输出标准的 unified diff 格式，而不是"整文件重写"。原因有两个。第一，diff 文件天然自带改动范围的声明，方便后续做白名单校验；第二，diff 可以精确地逐段应用，允许只接受部分改动而回滚其他部分。如果你的模型输出整文件，你根本没有办法判断它改了哪些行。
生成补丁后，执行器还要做一次"格式净化"：很多模型会在 diff 之外附带解释文字，或者用 markdown 代码块包裹 diff。这一步我用正则剥掉代码块标记，再将剩余文本交给 patch 命令解析，解析失败就要求模型重新生成。
2.3 校验器：行为等价性判断的落点
校验器（Verifier）是整个 Harness 里最关键的模块，也是我的方案和"裸跑"最明显的区别。它的职责只有一个：判定改动前后的代码在行为上是否等价。
这里要强调一个容易被忽略的概念：代码重构的定义就是"行为等价的重组"，所以验证等价性不是可选步骤，而是重构的必要条件。但"行为等价"本身是个模糊概念，不可能靠某一次测试来完全证明。我在 Harness 里做的是分层逼近：编译层保证语法正确，测试层保证可观察行为一致，结构层保证控制流完整。三层合起来，才能把"看起来等价"和"真的等价"之间的缝隙尽量堵住。
3. 核心主循环的代码级实现：从任务输入到验证通过
3.1 任务定义与目标文件锁定
先看 Harness 的主循环代码。这套代码我在好几个类似项目里复用，核心思想是"小步走、每步验证"。
python复制from dataclasses import dataclass, field
from typing import List, Optional
@dataclass
class RefactorTask:
task_id: str
target_file: str
target_function: str
strategy: str
constraints: dict = field(default_factory=dict)
@dataclass
class StepResult:
step_name: str
patches: List[str]
verification: dict
applied: bool
feedback: Optional[str] = None
class RefactorHarness:
def __init__(self, planner, executor, verifier, safety):
self.planner = planner
self.executor = executor
self.verifier = verifier
self.safety = safety
def run(self, task: RefactorTask):
plan = self.planner.create_plan(task)
summary = []
for step in plan.steps:
# 1) 为这一步组装上下文并生成补丁
context = self.executor.gather_context(task, step)
patches = self.executor.generate_patches(step, context)
# 2) 改动范围校验，不过白名单就拦下
if not self.safety.validate_scope(patches):
return self._finish(summary, status="blocked",
reason="patches out of scope")
# 3) 应用补丁前先做快照，失败可以整体回滚
self.safety.snapshot()
# 4) 应用补丁
self.executor.apply(patches)
# 5) 跑验证，全绿才进入下一步
report = self.verifier.run_all()
if report.ok:
self.safety.commit()
summary.append(StepResult(step.name, patches,
report.dict(), applied=True))
else:
self.safety.rollback()
feedback = self._format_failure(report)
summary.append(StepResult(step.name, patches,
report.dict(), applied=False,
feedback=feedback))
if self._should_retry(step, summary):
step.attempts += 1
continue
else:
return self._finish(summary, status="failed",
reason=report.error)
return self._finish(summary, status="success")
这段代码看起来简单，但每一行都是踩坑后优化出来的。我重点解释几个关键设计。
第一，plan.steps 的粒度。我强制要求规划器把一次大规模重构拆成多个小步骤，每个步骤只做一件"原子级"的事情——比如"提取支付处理函数"是一个步骤，而不是"把这个大函数拆成五个小函数"当成一步。这样做的原因是，哪怕其中一个步骤失败需要人工介入，前面的步骤已经验证通过并提交，不会全部白费。
第二，快照的位置。snapshot() 必须在 apply() 之前调用。我的实现用的是 git 临时分支配合：执行器先把工作区干净地提交到一个临时分支，再应用补丁。验证失败后 rollback() 就是 git reset --hard 到临时分支的状态，干净利落。
第三，重试逻辑。_should_retry 不是简单地数次数，而是结合验证报告判断失败原因：如果是静态检查不过（比如变量名拼错），重试成功率较高；如果是测试失败且反馈信息指向同一段代码，可能是模型没理解需求，重试价值就很低。后面第 5 节我会单独讲这个止损策略。
3.2 补丁的生成、格式与安全应用
补丁生成这一步，我在实践中逐渐总结出一个提示词模板，核心是把"约束"前置：先告诉模型什么是禁区，再让它动手。模板里永远包含这几句话：
code复制你是一名资深工程师，正在对一个遗留系统做行为等价的重构。
规则：
1. 只允许修改目标函数及其直接相关代码，禁止改动无关代码。
2. 禁止改变任何可观察行为：异常类型、返回结构、副作用顺序都不许动。
3. 若原代码存在异常处理逻辑，必须原样保留。
4. 不要为代码添加新功能，不要顺手修 bug。
输出：仅输出 unified diff 格式的补丁，不要附加任何解释。
第 4 条特别重要。模型天然有"顺手改进"的冲动，看到不规范的代码忍不住想美化。但对重构任务来说，任何超出任务范围的改动都是隐患。
拿到模型输出的原始文本后，我做了两层处理。第一层剥掉 markdown 代码块标记，用一个简单的正则处理 ```diff ... ``` 这类包裹。第二层是调用系统 patch --dry-run 做一次预演，确认补丁能干净地应用，然后再真实应用。
安全应用补丁还有一个细节：统一处理行尾符。我遇到过一个很隐蔽的坑，模型生成的 diff 里把 CRLF 换行当作空格处理，导致 patch 命令报 "malformed patch"。后来我在生成 diff 之前统一把上下文内容按 \n 归一化，并在提示词里明确说明"文件使用 LF 换行"。如果你处理的是历史遗留的 Windows 工程，这一步绕不开。
3.3 三层验证门：编译、测试、差异审查
验证层的代码我拆成了三个独立步骤，任何一步失败都不会进入下一步。第一步是编译与静态检查，第二步是测试套件，第三步是结构差异审查。执行顺序有讲究：先跑最便宜、最确定性的检查，把明显低级的错误挡在前面，省下后面昂贵步骤的时间。
python复制class Verifier:
def run_all(self):
steps = [
("compile_check", self.compile_check),
("static_check", self.static_check),
("unit_tests", self.unit_tests),
("ast_compare", self.ast_compare),
]
results = {}
for name, fn in steps:
try:
results[name] = fn()
except VerificationFailure as exc:
return VerificationReport(ok=False, error=exc.message,
passed_steps=results)
if not results[name]:
return VerificationReport(
ok=False, error=f"{name} failed", passed_steps=results)
return VerificationReport(ok=True, results=results)
我要单独讲讲 ast_compare——这是我这套 Harness 里最有特色的部分，也是网上资料很少涉及的部分。
ast_compare 的做法是用 tree-sitter 分别解析改动前后的目标函数，然后做结构摘要对比。结构摘要不是逐 token 对比（那只适合判断完全没改），而是提取关键结构节点：if / elif / else 分支、for / while 循环、try / except / finally 块，以及 raise 语句的参数类型。把这些节点按出现顺序组织成一棵"控制流骨架树"，再做归一化比较。
归一化是什么意思？举个例子。从 process_order 里提取 payment_processing 之后，原来的函数体里那个 if payment.success: 分支会搬家，但这些控制流节点的类型和嵌套关系应该还完整地保留。AST 对比会把同一棵骨架树里的节点重新排列，如果提取后的代码里少了原函数的一个 except ValueError 分支，骨架树对比立刻能发现，哪怕编译检查和测试套件全部通过。
这个设计的灵感其实很简单：我在做"看起来等价"翻车事故复盘时发现，最容易出问题的是控制流而不是表达式。表达式算错还有测试兜底，控制流被悄悄删除，测试往往覆盖不到。所以我把有限的计算资源全部砸在控制流完整性上，收益非常明显。
4. 让 Agent 不敢乱改的安全设计：白名单、沙箱与回滚
4.1 文件级与函数级白名单
安全机制的第一层是改动范围控制，这在 Harness 里是硬约束而不是软约束。所谓硬约束，就是代码里强制校验，不靠提示词里的"请只改目标文件"这种软指令——模型可能忽略软指令，但代码逻辑不会。
我的做法是双白名单。文件级白名单是一组允许改动的路径模式；函数级白名单是在文件内部允许改动的函数符号。validate_scope() 拿到补丁后，解析出每个 hunk 所在的文件和函数名，逐条比对：
python复制def validate_scope(patches, allowed_files, allowed_funcs):
for patch in patches:
path = patch.path
normalized = path.replace("\\", "/")
if not any(normalized.startswith(f) or normalized == f
for f in allowed_files):
return False, f"file {path} not in allowed list"
funcs_touched = extract_directive_functions(patch)
if not funcs_touched.issubset(allowed_funcs):
return False, f"function {funcs_touched - allowed_funcs} not allowed"
return True, ""
函数级白名单的实现稍微麻烦一点，因为一个补丁 hunk 可能跨多个函数。我用 tree-sitter 解析改动文件，把补丁 hunk 的行范围和函数定义的行范围做交集，凡是相交的函数都记入 funcs_touched。
这里有个很实际的坑：白名单不能单独用"文件名前缀"来判断。我第一版写成允许路径前缀匹配，结果一个野补丁把 src/models/order.py.bak 当成了 src/models/order.py 放过。后来改成"精确匹配 + 目录前缀匹配"二选一，并禁止文件后缀被截断匹配。
双白名单的好处是，即使模型在提示词之外产生幻觉、或者上下文里混入了其他文件的内容，补丁也根本进不了应用环节，安全校验这块的成本几乎为零。
4.2 在 Docker 沙箱里跑验证，为什么比本地跑可靠
验证环节我一开始是在本地工作目录直接跑的。跑了两次就发现不对：模型的补丁可能引入依赖变更，或者它自己生成了测试文件，这些都会污染本地环境。更麻烦的是，如果项目里有预提交钩子或者构建脚本，验证过程本身可能触发代码修改，造成"验证通过但工作区已经变成另一个状态"的诡异情况。
所以我把验证全部搬进 Docker 沙箱。做法是做一个专门的验证镜像，镜像里装好项目的依赖和测试工具，验证时把当前工作区挂载进去，在容器内跑编译和测试：
bash复制docker run --rm \
--network none \
-v "$PWD":/workspace \
-w /workspace \
refactor-verify-env:latest \
bash -c "python -m compileall -q . && pytest -q --tb=short"
--network none 是刻意的：项目依赖已经打进镜像，验证过程中不允许访问外网，防止测试脚本偷偷拉取依赖或者连远程服务。这一点在自动化场景里很重要——你不希望验证结果受网络波动影响，更不希望测试套件因为在隔离环境里没有内网访问权限而莫名失败。
沙箱的另一个好处是资源隔离。重构循环可能连续跑十几轮，任何一次验证进程崩溃或内存泄漏都不会拖垮宿主机。我甚至遇到过模型生成的测试代码里有死循环，如果在本地跑，一个 pytest 进程能吃掉全部 CPU；在沙箱里它会被超时机制一起收拾掉。
每次验证的超时时间我设置在 5 分钟，超过就判定失败，并且记录超时点是哪个测试用例——这个信息后续会作为反馈喂回给模型，让它知道自己改出了死循环。
4.3 回滚时机与"验证失败但代码已污染"的处理
回滚的设计原则只有一条：凡是应用到工作区的改动，验证失败必须回滚到应用前的状态，宁可多回滚不可少回滚。
我之前用的是文件级别备份，每个文件应用补丁前先复制一份到临时目录。但很快发现这招在跨文件重构时不够用——一个步骤可能同时改了三个文件，任何一个文件的验证失败需要整体回滚，文件级备份恢复时间点不一致就会产生"混合状态"（三个文件里两个是新的一个是旧的），后续排查极其痛苦。
换成 git 快照方案之后干净多了。具体做法：Harness 启动时在项目根目录创建一个临时分支 harness-snapshot，每次应用补丁前把当前 HEAD 提交一次到该分支，验证通过就把结果提交到主分支，验证失败就 git reset --hard harness-snapshot 回到应用前。
这个方案有个前提：项目必须已经是 git 仓库，且 Harness 运行前工作区是干净的。我在 Harness 启动时用 git status --porcelain 检查工作区，如果有未提交的改动就直接拒绝运行——宁可让人先把本地改动手动提交，也不能让自动化和人的编辑混在一起。
还有一个容易漏掉的点：测试验证本身可能产生副作用，比如测试写入了临时数据库文件、生成了缓存目录。这些产物在回滚后仍然残留。所以我的 rollback() 函数除了 git reset 之外，还会清理一个记录在案的产物清单，通常是 .pytest_cache/、__pycache__/ 这类目录。
5. 实测翻车现场：三个典型失败模式与修复办法
5.1 "看起来等价"不等于行为等价：被吞掉的异常分支
第一个翻车案例来自一个平行测试，对象是另一个团队提供的 600 行函数。模型给出的重构方案非常漂亮，函数拆分合理、命名优雅，测试套件全绿。我差点就把补丁合入了。
好在当时 ast_compare 已经上线。骨架树对比报警：原函数里有一个 except TimeoutError 分支，在重构后的函数里消失了。我去翻模型的输出，发现它写了一行注释"该异常在当前调用链中不可能发生，故省略"。这个问题单看逻辑确实容易被忽略——TimeoutError 在大多数调用场景里确实不触发，但它是一个合法的、由外部系统状态决定的行为分支。重构合入后，某天外部服务超时，系统会直接抛未处理的异常，而不是走原来的降级逻辑。这就是典型的"看起来等价"。
这个坑给了我两个教训。第一，绝对不能信任模型对"不可达代码"的判断。判断可达性本身是全局程序分析问题，连静态分析工具都经常给出误报，模型凭局部视野下的判断更不可靠。第二，结构层验证（AST 对比）不是可有可无的补充，而是行为等价性的最后防线。
后来我把 ast_compare 的检查项加强了一层：不仅对比控制流节点，还对比每个节点上的"副作用关键词"。比如 except 分支里有没有 log、rollback、notify 这类调用。副作用关键词对比能发现更隐蔽的删改——有些模型会把异常分支里的日志代码合并掉，虽然控制流还在，语义却已经变了。
5.2 跨文件重构的上下文饥饿问题
第二个翻车案例是跨文件重构。任务是把一个调用关系很深的方法从源模块挪到另一个模块，同时所有调用方要改成调用新函数的签名。
问题出在执行器的上下文组装上。我把"重构局部视图"只限定在目标文件及其直接依赖文件，但这个方法的调用方分布在 9 个文件里，文件之间还通过中间层间接调用。上下文里只放了 3 个直接调用方的信息，模型在生成新签名时猜测了剩余调用方的用法，结果改出来的函数签名和某个间接调用方的实际传参对不上。
这个问题的本质是上下文窗口的信息密度不够，不是模型能力不够。解决思路不是加大窗口，而是提高信息密度。
我的修复方案分两步。第一步，上下文组装阶段加了一个"调用图裁剪"：用 LSP 的 findReferences 拿到全部调用方清单，但只把调用方的"调用点"代码片段放进上下文，而不是整个文件。一个调用点通常只有 5 到 10 行，信息密度极高，模型能清楚地看到每个调用方怎么传参、怎么处理返回值，十个调用方加起来也才几十行。
第二步是"签名一致性预检查"。让 Harness 在生成补丁前，先用 tree-sitter 列出目标函数当前所有调用点的参数模式，把这些模式写进提示词作为硬约束：新函数签名必须兼容以下参数模式：...。模型要改签名可以，但必须保证现有调用模式不破坏。
这两步做完之后，跨文件重构的成功率从大约 50% 提到了 90% 以上，而且模型的生成速度反而更快了——因为它不需要在巨大的上下文里自己找调用方了。
5.3 Agent 的"倔强重试"：如何在 3 次失败后止损
第三个翻车案例和模型能力无关，是 Harness 自身设计缺陷：重试逻辑没设止损线，导致一个任务在失败状态下循环了快两个小时。
现象是这样的：初始化重构步骤时，模型的输出一直在报同一个静态检查错误——某变量未定义。每次失败后我都把错误信息喂回去并让它重试，但模型每次都输出结构几乎相同的补丁，只是变量名微调一下，调完还是未定义。它就像一个倔强的实习生，明知道自己没搞懂需求，还是反复提交差不多的答卷。
复盘时我发现两个问题。第一个是反馈信息的格式问题。我把验证报告的错误文本原样作为反馈，但模型显然没有真正理解错误在哪里。第二个是缺少"失败模式的分类"：静态检查错误明明是最容易重试成功的，但如果连续两次错误完全相同，说明模型在死循环，这时候继续重试就是浪费。
修复方案是双重的。
首先是反馈结构化。验证失败后，我不再把原始错误文本塞给模型，而是让 Harness 生成一份结构化的"失败摘要"，包含：失败命令、失败测试模块、错误类型、涉及的文件和行号、以及建议的修正方向。这份摘要会明确告诉模型"不要修改范围，只修正此处错误"。
其次是重试策略调整。我给重试加了三个条件，满足任何一个就立刻停止重试并升级到人工：连续两次失败且错误类型相同；重试次数达到 3 次上限；累计失败超过 15 分钟。
重点是第一个条件，错误类型相同基本可以断定模型陷入局部死区，此时与其继续烧资源，不如把上下文和失败摘要打包成一个"求助单"推给人来审。这套止损机制上线后，Harness 的平均任务耗时明显下降。之前一个任务卡住可能浪费几百次调用，现在最多 3 次失败就交给人工，人工介入后通常 5 分钟就能判断是调整任务描述还是放过这个步骤。
6. 这套 Harness 还能往哪儿扩展：批量迁移、技术债治理与评审辅助
6.1 批量迁移：同一个模式应用到几百个调用点
Harness 的架构天然适合批量迁移。我后来接了一个任务：把系统里散落在十几个服务模块的"直接裸读数据库配置"的代码，全部迁移到统一的配置访问接口。这是典型的"结构化迁移"，每次改动模式完全一致，只是目标文件不同、字段名不同。
做法是给规划器加了一个"模式模板"字段：任务描述里不写具体文件，而是写迁移前模式的代码片段、迁移后模式的代码片段，以及候选文件目录。Harness 遍历候选目录，把每个文件里匹配上"迁移前模式"的位置作为独立任务排进队列，逐个走主循环。
这套模式迁移跑下来，两百多个调用点里大约 90% 是自动化的，剩下 10% 因为代码结构变形太大（有的在 lambda 里、有的在字符串拼接里）无法精确匹配，Harness 会把这些自动降级为"人工待办"并附上定位信息。这种"自动化优先 + 人工兜底"的混合模式，我认为是大型代码迁移最实用的形态。
6.2 技术债治理：把重构变成定时任务
另一个让我意外收获的扩展方向是技术债治理。以前技术债清理总是靠人肉排期，一旦业务高峰来了就被无限推迟。把 Harness 接入 CI 之后，重构变成了可以定时触发的后台任务：每周日凌晨跑一次，任务队列由代码扫描自动生成（比如"找出所有超过 300 行的函数，加入拆分队列"）。
定时任务场景下，安全机制反而更关键，因为没人每次都在场盯着。我的做法是把 Harness 的结果分成三个输出通道：全自动通过的改动直接生成合并请求；需要人工确认的改动生成合并请求草案并标注"需 review"；自动判定为"无法处理"的会转成 issue 附在代码库中。这样即使没有人在任务跑完后立即跟进，所有结论都有迹可循。
给团队做这套接入的时候我还学会了一件事：自动化重构的灰度策略比技术实现更重要。第一周只允许它处理测试覆盖率达到 90% 以上的模块，第二周才扩大到覆盖率中等的模块。测试覆盖率高意味着验证层能兜住更多行为等价性问题，这个灰度阶梯极大降低了团队对自动化重构的信任门槛。
6.3 评审辅助：给改动生成"为什么安全"的说明
最后一个扩展方向其实是无心插柳。Harness 在执行任务时会自动记录每个步骤的验证报告——哪些测试跑了、AST 对比结果、白名单校验通过的文件列表。这些信息本来是内部日志，但有一次同事要 review 一个 Harness 生成的合并请求，问我"你既然说它安全，证据呢"，我才意识到这正是 code review 里最稀缺的东西。
后来我给 Harness 加了一个"评审摘要生成器"：每个步骤完成后，把验证报告的关键信息组织成一段人可读的说明，比如：
本次改动仅涉及
order_service.py的函数process_order，提取了支付处理和库存预占两个子函数。验证通过：编译检查通过、项目 128 个测试全部通过、AST 结构对比确认控制流节点完整。改动范围与任务约束一致：未触碰其他文件。
这段摘要直接放进合并请求描述里，reviewer 可以在 30 秒内判断这次改动的安全边界。这比让 reviewer 自己打开 diff 一个个文件翻高效得多。我甚至觉得，对于自动化生成的所有代码变更，这类"安全说明"应该成为标配，而不是可有可无的附加品。
整篇文章里提到的所有设计，包括规划器、执行器、校验器、白名单、沙箱、快照回滚、重试止损，本质上都在回答同一个问题：如何让大模型的创造力和工程要求的确定性并存。自动化重构最难的地方从来不是模型能不能生成补丁，而是你能不能给它框出一个足够安全、可验证、可回退的活动空间。
根据我个人这几个项目的经验，如果你想在自己团队里落地类似的东西，我的建议是先从一个模块、一种重构策略开始，把验证层做到让你自己完全信任，再考虑扩大范围。别急着上批量任务，先把单次重构跑通到"敢合入"的程度，后面的一切水到渠成。