高德搜索业务重构实践：用 Harness 驱动复杂工程演进

当 AI 进入真实工程场景后，挑战很快不再是“能不能生成代码”，而是“能不能接管一个长期、复杂、高风险的工程过程”。

在高德搜索业务的前端重构实践中，我们尝试把这个问题拆解为一套项目级 Harness 重构工作流。用户只需要给出一句目标，例如：帮我重构搜索结果页。系统就会进入项目级重构流程，围绕旧代码扫描、架构设计、模块出码、质量审查、修复迭代等持续推进。人工主要参与范围确认、架构方向、关键取舍和交付验收。

本文将结合一次真实落地过程，介绍信息业务中心团队如何完成 AJX「搜索结果页」的整洁架构重构，以及沉淀本次实践为一套可复用的 Harness 工程化方法。

**背景
**

搜索是一个大的业务方向，前端包含搜索首页、搜索列表、详情页，以及围绕核心页面展开的各类二级页。这些页面大多运行在 AJX 技术栈上，迭代历史长，承载过大量业务策略、框架迁移、线上修复和临时方案。

AJX 是高德 App 内用于承载动态业务页面的一套前端运行体系，可以把它理解成面向 App 场景的跨端页面技术栈。

时间久了之后，代码问题会从局部复杂演化成系统性难维护：历史逻辑背景不清晰，废弃功能无法安全下线，模块之间耦合严重，大文件越来越多，回归链路越来越长，AI 进入项目后也很难建立稳定上下文。

我们拿搜索结果页和详情页两个项目做粗略统计：

指标	搜索结果页	详情页	合计
文件数	1062	4401	5463
JS/TS 类文件	447	2219	2666
JS/TS 类代码行数	8.2 万	42.1 万	50.3 万
500 行以上大文件	32	151	183
1000 行以上超大文件	9	52	61

代码规模大、巨型文件多只是表层问题，更深层的是模块间耦合、发布订阅泛滥、全局方法使用不规范等问题。这些在两个项目中粗略命中近万处，一次看似普通的改动，可能会牵动很多隐性契约。

为此，我们希望通过架构规范来彻底解决维护成本高、AI不友好的问题。同时，希望沉淀出一套工程能力，能复用于其他项目。

**总体框架：Agent分工、状态资产和Harness工作流
**

多Agent协作架构

我们采用主协调器加专家 Agent 的协作架构。主协调器负责阶段推进、任务编排、进度管理、决策治理和门禁把关。专家 Agent 只处理边界清晰的专业任务：

角色	定位	主要职责
协调器	流程负责人	规划任务、分配工作、推进阶段、维护状态、汇总结果
代码分析 Agent	旧代码分析专家	深扫旧代码，将结构、依赖、动态耦合和项目特征写入依赖图
架构设计 Agent	方案设计专家	基于依赖图和决策产出设计文档、模块分配图和构建计划
出码 Agent	模块实现者	编写模块规格，按规格实现模块，更新映射和债务状态
质检 Agent	审查者	不改代码，只做质量审查、行为验证和保真核对

五阶段工作流

项目级重构通常跨多轮对话，靠聊天上下文维护状态，迟早会遇到压缩、遗忘和误判，因此需要做好过程管理，我们把一次项目级重构拆成五个阶段：发现、设计、构建、质检、交付。

每个阶段都有明确输入、输出、完成条件和「责任人」，让 AI 的工作从“生成代码”变成“持续推进一组可审计的工程资产”。让长期任务可恢复、可审计、可复用。

阶段	主要动作	作用
发现	初始化任务、确认范围、扫描入口、深扫旧代码	建立旧代码地图，收敛有效范围
设计	影响分析、顶层设计、模块分配、波次计划、规格编写	把架构目标转成可执行任务
构建	按波次委派出码、模块注册、债务记录、静态验证	让新架构逐步成型
质检	重复扫描、架构校验、保真核对、运行时回放、修复迭代	先低成本消化问题，再用真机闭环验证
交付	状态收口、文档更新、经验归档、交付确认	形成可维护、可复盘的交付结果

这套设计背后有三个关键取舍。

第一，主控和专家分离。 协调器负责流程和责任边界，专家 Agent 负责专业判断。这样可以避免一个 Agent 同时承担扫描、设计、出码、质检等互相干扰的任务。

第二，状态资产化。 长周期重构不能依赖聊天上下文，工作流把过程状态写入Harness资产：依赖图、变更集、分配图、构建计划、模块规格、保真账本、决策记录、质量报告、经验归档都成为可读取的项目资产。

第三，阶段门禁。 发现、设计、构建、质检、交付每个阶段都有明确产物和退出条件。AI 可以自动推进，但不能跳过关键检查点。

**上下文编排：按任务交付最小充分上下文
**

复杂项目里最容易犯的错，是把上下文问题理解成“给模型更多资料”。实践证明，资料塞得越多，模型注意力越容易分散。

给少了，Agent 会凭空补；给多了，Agent 会被无关信息干扰，甚至把旧代码里的坏结构原样搬到新代码里。因此我们把上下文管理做成控制面能力，核心原则有三条。

这套设计对应到实践里，就是每次委派任务时只打包“最小充分上下文”。

例如出码 Agent 拿到的是模块规格、相关旧代码原文、接口约束、必须保留的行为契约；质检 Agent 拿到的是验收标准、模块注册表、保真账本和旧代码证据。

这个机制有两个效果。

一是降低噪音。 子 Agent 不需要全仓漫游，只拿到完成任务所需的证据和规则。

二是保留责任边界，避免Agent越权操作。 出码Agent只能把任务标记为“已完成”，不能自己标记“已验证”；质检Agent只审查不改代码；架构问题由协调器汇总后进入决策。

**代码地图：用依赖与行为图谱建立旧代码地图
**

代码地图是整个工作流的核心基础。我们会在发现阶段，从入口文件出发，通过文件依赖及模式匹配，先把旧代码结构摸清楚，生成核心产物 dep-graph.json，而不是让 AI 根据「自己的理解」自行漫游仓库。

「dep-graph」可以理解成一份“旧代码地图”。它在文件清单之上记录节点、关系和线索，让后面的设计、出码、质检都能基于同一份事实工作。

这份地图主要回答六类问题：

换句话说，代码地图是发现阶段生成的机器可读索引：人可以通过它理解旧代码结构，Agent 可以通过它获取证据，后续每个设计结论和保真 claim 都能反查到旧代码来源。

**受控出码：按波次委派 Agent 出码
**

出码阶段的重点是受控交付。在这一阶段我们主要做三件事：沉淀代码范式、控制出码策略、记录出码账本。

代码风格保持锁定

AI 重构很容易出现一个问题：功能看起来对了，代码却像另一个项目。命名方式、目录习惯、状态组织、异常处理、工具函数写法一旦漂移，后续维护成本会指数级上升。

这里的风格锁定不依赖单段 prompt 约束。构建早期，出码Agent会先完成首批模块。模块完成后，工作流会从这些代码里提取稳定写法，写入 style-codex.md。

Style Codex 记录的是可复用的代码范式，例如：

• import / export 的组织方式。

• 组件、usecase的写法。

• 错误处理、函数声明和模块导出习惯。

• 每类范式首次出现时沉淀下来的表达方式。

默认完成 3 个模块后，Style Codex 会被标记为 LOCKED。后续模块出码时，工作流将这份 Codex 注入给出码Agent，让同一类模块沿用已经形成的项目范式。这个机制比单纯描述“请保持风格一致”更稳定，因为它把风格从抽象要求变成了可读取、可复用、可锁定的工程资产。

出码策略按模块推进

工作流将单个出码任务收敛到一个模块规格内。每个模块都有明确职责、输入输出、允许依赖、旧代码依据、保真 claims 和验收点。

出码时遵循几个原则：

• 自底向上。按照架构依赖自底向上构建。

• 小模块交付。一次只处理边界清楚的一组模块，降低上下文噪音，也方便失败时定位。

• 按波次推进。合理划定出码波次，避免上层模块依赖尚未稳定的下层能力。

• 可追溯修改。每个新模块都能反查到对应的旧代码依据、allocation 单元和保真 claim。

记账机制保证可审计

工作流要求出码 Agent 在写代码之外同步更新账本。这里的账本主要包括三类：

账本	记录内容	用途
module registry	新模块路径、模块职责、导出接口、构建状态	让Agent知道哪些模块已经生成，后续模块可以依赖什么
preservation claims	旧代码契约在新代码中的映射位置和处理状态	支撑代码保真检查，避免关键行为遗漏
build debt	暂缓处理、需要人工确认、需要运行时验证的问题	把风险显性化，避免问题混在代码里悄悄带到交付阶段

这个机制让 AI 的任务从“理解一个巨大项目”降维成“完成一个有规格、有旧代码证据、有验收点、有账本记录的模块”。规格对人可审阅，对 AI 可执行，账本对质检和交付可追溯。

**前置保真：把代码保真前置到低成本环节
**

早期探索时，我们基于 Harness 的思路，通过状态、边界和验证约束 AI 向目标收敛。这个思路在反馈快的环境里很自然，但在 AJX 这类依赖真机验证的「慢反馈」环境下却是低效的，自动化循环流程会被验证成本拖慢。

因此，在后续工作流中，我们把代码保真前移到设计、SPEC、出码和静态质检阶段。

这里的代码保真指的是契约保真。我们不追求逐行复制旧代码，也不会保留所有历史结构。需要保住的是旧代码里那些业务不可丢失的契约：

• 旧代码里哪些行为不能丢。

• 哪些开关能力必须保留。

• 哪些埋点和日志必须迁移。

• 哪些 Native 回调、生命周期逻辑是线上契约。

• 哪些历史框架集成关系需要映射，哪些应该根据新架构决策明确废弃。

我们用 Preservation Ledger 表达这些契约。把旧代码里的关键行为抽取成 claims，并跟踪每条 claim 的状态：mapped、verified 或 waived。模块SPEC、出码委派和质检过程都会围绕这些 claims 闭合。

这个机制让 AI 出码前知道必须覆盖哪些契约，出码中可以按规格对齐，出码后质检也有明确账本可查。相比把所有问题留到真机阶段，它更适合 AJX 这种验证链路昂贵的场景。

**运行时质检：录制、回放和自动修复循环
**

静态质检和行为保真只能提高首次出码质量，不能证明新代码在真实运行环境里一定可用。AJX 项目的质量最终还是要回到真机：页面能否进入、关键路径是否正常、控制台是否报错、网络请求和 Native 调用是否符合预期。

我们在工作流中设有一层运行时循环，把真机验证变成可记录、可回放、可修复的过程。

这条链路有五步：

1. 从设计阶段产物里提取验证场景。 场景来自代码地图、模块SPEC、设计文档和质量规则等，覆盖主链路、行业场景、卡关能力、异常分支等高风险点。

2. 在旧代码上做场景录制。 用户按提示操作真机，大禹记录路径、关键状态、日志、网络、控制台输出和可观察行为，形成 baseline。

3. 在新代码上做场景回放。 设备连上调试工具后，大禹编译新代码、更新运行包、触发回放和结果采集，用户主要配合必要的真机操作和路径确认。

4. 通过 CDP 抓取问题证据。 控制台错误、网络异常、页面状态、运行时日志会落盘，成为可复盘、可定位、可委派修复的证据，避免问题停留在一句“页面打不开”的描述里。

5. 自动进入修复和再验证。 大禹把运行时证据交给出码 Agent 修复，再触发编译、更新和回放，直到场景通过或形成明确的人工决策。

过程中人负责真机侧暂时无法稳定自动化的动作，例如授权、真机操作、路径确认、视觉和交互结果验收；协调器Agent负责把这些动作串成可恢复的验证会话，并持续完成编译更新、场景回放、证据采集、问题定位和修复委派。

运行时质检的价值不止于发现 bug。它把昂贵的真机循环纳入 harness 管理，让每次失败都有证据、每次修复都有目标、每次回放都有记录。对于 AJX 这类环境，前置保真减少循环次数，运行时闭环保证最终可信。

**案例：搜索结果页重构
**

「搜索结果页」是一次真实复杂业务重构。

重构目标包括：

• 将旧实现迁移到新架构。

• 新代码集中输出到独立目录，支持新旧并存，通过云控进行新旧切流。

• 移除旧Amix框架依赖，迁移到 FOXPage + 函数组件。

• 使用 TypeScript。

• 建立整洁架构分层。

• 保留 30 个云控开关，并下线已废弃/全量实验分支。

• 修复 PMT 协议使用不规范问题。

关键过程数据如下：

阶段	结果
发现	建立 3871 文件依赖图，收敛 177 个 in_scope 文件并完成深扫
设计	从 133 个潜在改动文件锁定到 16 个核心改动文件
分配	444 个旧代码 units 100% 分配到 63 个目标模块
规格	生成 62 份模块规格文档
构建	11 个波次，62 个生产模块
质检	47/47 P0 behavior claims verified，30 个 P0 cloud_switch claims mapped，3 个 P0 PMT claims verified，并进入真机运行时验证闭环
修复	Q4 修复 3 项 P0、5 项 P1、2 项 P2
交付	进入 delivery 阶段，模块注册和经验归档完成

这次实践把搜索结果页推进到了接近上线质量的交付状态，也验证了大禹设计上的几个判断：

• 大模型可以承担大量扫描、拆解、出码和质检工作，但需要阶段和门禁约束。

• 高成本验证环境需要控制运行时循环次数，首次出码质量要足够高，最后仍要通过真机闭环兜底。

• 代码保真需要显式建模，隐性契约才不容易丢。

• 重构后的项目结构更清楚，也更适合后续 AI 继续维护。

经验与方法论

模型负责理解和创造，工具负责校验和兜底

模型在处理大规模任务时，幻觉、失真、遗漏是不可避免的。我们不试图通过更长的提示词消除这种概率性，而是把关键状态结构化，让工具做确定性检查。

依赖图、Allocation Map、Preservation Ledger、构建债务都是 JSON，不是因为模型更喜欢 JSON，而是因为工具可以检查：旧代码 units 是否都有分配，P0 claims 是否全部关闭，是否还有未清偿的构建债务。阶段完成条件也写在门禁里，不满足就不能进入下一阶段。

代码保真要按成本模型设计

保真前置会增加设计阶段成本；保真不足会增加质检和真机循环成本。AJX 的编译、更新、真机复现和日志采集链路很长，所以大禹选择把高风险、高验证成本、高隐性契约的部分尽量前置，再把剩余问题交给运行时录制和回放闭环处理。

这是一种成本模型驱动的工程取舍。

AI 重构本质上是在整理历史知识

重构经常被理解为“换一批新代码”。这次实践给我们的感受更接近：重构是在整理历史知识。

旧代码里沉淀了业务决策、线上修复、平台约束和隐性契约。AI 只生成新结构，很容易丢掉这些知识。我们需要AI做到的是把这些知识抽出来，迁移到新结构里，并沉淀为后续可读取的资产。

后续 AI 维护能力应该成为重构目标的一部分

过去我们说重构是为了人维护。现在还要考虑 AI 维护。

如果一个项目没有清晰边界、没有规格、没有规则、没有决策记录，AI 每次进入都要重新猜。大禹希望重构后的项目更整洁，也更 AI-readable。

**结语
**

AI 进入复杂工程，关键不在于单次生成能力，而在于能否被纳入一套可约束、可验证、可沉淀的工程体系。

在搜索业务重构实践中，我们验证了这套思路在真实业务复杂度下的可行性。面对长期演进形成的历史包袱、隐性契约、运行时不确定性和高成本验证链路，AI 需要的不只是上下文，更需要结构化事实、明确边界、证据闭环和持续反馈。

当旧代码地图、上下文编排、阶段门禁、保真账本和运行时质检组合成一个 Harness，复杂重构就不再只是一次性工程战役，而成为可恢复、可审计、可复用的人机协同系统。这也是我们对 AI 工程化落地的一次阶段性探索。

#搜索业务 #Harness #前端重构实践 #高德 #高德技术

END