---
name: aaalice-refactor-parity-loop
description: 对 Aaalice NAI Launcher 的大型文件拆分型重构执行多子代理等价性闭环。当任务目标是把大型业务文件按职责拆分、同时保持功能、交互与布局不变时自动使用；不用于普通重构、功能开发、单点 Bug 修复或常规代码审查。
---

# Aaalice 重构等价性闭环

运行环境需要 Git、Flutter/Dart 与可用的 Codex 多代理协作工具。

本 Skill 验证的是“重构前后行为等价”，不是代码是否看起来更整洁。当前主 Agent 对范围、结论、修改、验证和最终交付负责；子代理只提供独立证据或执行边界清晰的修复。

本 Skill 可以自动启用，也可以由用户通过 `$aaalice-refactor-parity-loop` 明确调用。

## 启动门禁

自动启用时，只有同时满足以下条件才执行后续流程：

1. 当前任务是大型业务文件的职责拆分或同等规模的拆分型重构；
2. 目标要求重构前后功能、交互和布局保持等价，而不是引入新行为。

任一条件不满足时，不执行本 Skill 的多子代理循环，并简要说明它只用于大型文件拆分等价性验证。

先阅读：

- [references/agent-prompts.md](references/agent-prompts.md)：各阶段子代理任务模板。
- [references/progress-template.md](references/progress-template.md)：被忽略的进度记录模板。

## 适用边界

在以下场景使用：

- 把超过 1000 行且经职责、内聚性和扩展成本评估后确有必要拆分的业务文件按职责拆分；
- 移动 Widget、Controller、Provider、Service、路由或平台适配代码，但不应改变行为；
- 重构后必须保持功能、状态、调用契约、响应式布局和平台行为；
- 用户要求多子代理循环审查、对抗性确认和修复。

不在以下场景使用：

- 有意改变产品行为的新功能；
- 单点 Bug 修复、普通命名整理或机械格式化；
- Changelog、Release Notes 或发布差异审查；
- 仅为了达到行数指标而继续拆分已经职责清楚的模块。

如果同一批改动同时包含功能变化和结构重构，先在记录中明确“允许变化”和“不允许变化”。任何未列入允许变化的差异都按潜在回归处理。

## 强制原则

1. 必须使用 Codex 内置多代理协作工具；不得用外部编排器、额外工作树、独立 Codex task 或外部 Agent 代替。项目开发 Runner 使用 `aaalice-dev-sessions` 管理的独立命令行窗口，不属于子代理替代方案。
2. 审查代理和确认代理必须是不同的新代理；任何代理不得确认自己的结论。
3. 审查默认只读；没有经过反证确认的问题不得进入修复。
4. 不把文件行数、个人风格、抽象偏好或“可能以后出错”单独当成回归。
5. 修复代理只能按互不重叠的问题簇并行。涉及同一文件、同一状态机或同一调用链时必须顺序执行。
6. 主 Agent 必须交叉核对所有子代理输出，不按多数票机械裁决，也不把交付责任转移给子代理。
7. 每次修复后必须开始新一轮完整审查；修复发生过的轮次不能直接判定通过。
8. 不设置为了快速结束而存在的轮次上限。遇到外部阻塞、证据不足或连续两轮没有实质进展时停止并如实报告，不伪造成功。

## 进度记录

为每个任务创建：

```text
tool/.tmp/refactor-parity/<task-slug>/progress.md
tool/.tmp/refactor-parity/<task-slug>/workers/
```

`tool/.tmp/` 已被 Git 忽略。首次创建时复制模板，再补全内容：

```powershell
$ErrorActionPreference = 'Stop'
$root = 'tool/.tmp/refactor-parity/<task-slug>'
New-Item -ItemType Directory -Force "$root/workers" | Out-Null
Copy-Item '.agents/skills/aaalice-refactor-parity-loop/references/progress-template.md' "$root/progress.md"
```

记录是审计轨迹，不是事实来源。后续代理必须重新检查代码、diff、测试和运行证据，不能因为 Markdown 中写了“已确认”就接受结论。

修复代理完成后，必须在以下唯一文件写自己的报告，避免并发修改主记录：

```text
tool/.tmp/refactor-parity/<task-slug>/workers/round-<N>-<worker-name>.md
```

报告至少包含：负责的问题 ID、修改文件、保持的契约、验证命令与结果、剩余疑点。主 Agent 将其摘要和实际 diff 核验结果写回 `progress.md`。

## 阶段 0：锁定基线与等价性契约

修改前先完成：

1. 记录仓库路径、当前分支、`HEAD`、比较基线 SHA 和工作区现有改动。
2. 基线优先使用用户指定提交；否则使用重构开始前的精确提交。不得默认用 `origin/main` 覆盖当前功能分支语义。
3. 如果重构已经发生但尚未提交，使用 `git diff` 与 `git show HEAD:<path>` 重建拆分前内容；明确哪些基线证据已经无法获取。
4. 列出目标文件、调用方、公共类型/方法/回调、Provider、路由、平台桥接、资源和测试。
5. 建立等价性矩阵，至少包含：
   - 输入、输出、异常和副作用；
   - 状态初始化、更新、销毁、取消和异步竞态；
   - 路由、返回、焦点、键盘、鼠标、触控和手势；
   - 空态、加载、错误、有数据、禁用和并发状态；
   - Windows、Android、桌面窄窗、手机、横屏和平板差异；
   - 文案、本地化键、语义、可访问性和快捷键；
   - 受影响布局的尺寸、顺序、显隐、滚动、Overlay 和 SafeArea。
6. 运行预计 60 秒内可完成的重构前针对性测试并记录结果。无法运行时记录原因，不能假定基线通过。

如果改动涉及 UI：

- 优先把关键尺寸和状态固化为确定性 widget/layout test。
- 只有用户明确要求自动化运行验收时，才加载 `aaalice-runtime-verify` 获取重构前后的真实截图、交互和日志证据。
- 没有运行态授权且没有直接覆盖受影响状态的确定性布局测试时，不得声称已经证明像素级或真实运行布局完全一致。

## 阶段 1：执行行为保持型拆分

1. 按职责拆分，不顺手改变交互、样式、文案、业务规则或平台能力。
2. 保持公共入口、调用顺序、Provider 生命周期、Widget key、语义和回调契约，除非等价性矩阵明确允许变化。
3. 每完成一个可编译边界就运行最小检查；不要积累大量未验证移动后再一次性修错。
4. 工作区已有改动默认属于用户，不回滚、不覆盖、不格式化无关文件。
5. 拆分完成后更新拆分清单：旧成员到新文件/新类型的映射，以及有意删除的死代码证据。

## 阶段 2：多代理独立审查

在当前可用并发槽内优先并行派发 3 个只读子代理；无法同时覆盖的维度在子代理完成后继续派发，范围尽量不重叠：

1. **功能与 API 契约**：调用链、输入输出、回调、副作用、错误和兼容性。
2. **状态与生命周期**：Provider/Controller/State、异步取消、初始化、销毁、导航和资源释放。
3. **UI 与布局**：Widget 树、constraints、响应式、Overlay、滚动、焦点、手势、语义和平台差异。
4. **接线完整性**：import/export、生成代码、路由、依赖注入、本地化、资源、测试入口和死代码。
5. **平台专项（按需）**：Windows、Android 或原生桥接的等价性。

所有审查代理必须独立比较基线与当前实现，不读取其他代理结论。每条发现必须包含：稳定 ID、基线行为、当前行为、准确路径/行号、可触发条件、影响、置信度和最小验证方式。

以下内容不得单独登记为问题：

- “文件仍然很长”；
- “我更喜欢另一种抽象”；
- 没有调用链或行为证据的假设性风险；
- 与本次 diff 无关的既有问题；
- 仅缺少额外测试但没有发现行为差异。

主 Agent 去重后把候选发现写入当前轮次，但此时状态只能是 `待确认`。

## 阶段 3：多代理对抗性确认

派发至少 2 个新的只读子代理。将候选发现按调用链或文件簇分配，重要问题至少由两个确认代理独立检查。

确认代理必须先尝试反证：

- 查找 guard、fallback、最近作用域处理、共享命令入口、测试和框架真实机制；
- 判断差异是否属于等价性矩阵允许变化；
- 构造最小反例或针对性测试思路；
- 区分“当前真实回归”“维护风险”“纯风格偏好”和“误报”。

分类规则：

- `已确认`：存在直接代码、测试、日志或运行证据，且能说明触发路径和行为差异。
- `已反证`：框架机制、现有 guard、测试或调用链证明原结论不成立。
- `未决`：证据不足或结论依赖未验证环境。

`未决` 不能进入修复。主 Agent必须追加只读检查或最小测试来解决；无法解决时本轮不能通过。

如果独立审查没有发现问题，确认代理仍要执行“清洁轮挑战”：尝试寻找审查遗漏、验证关键等价性矩阵和测试覆盖。只有挑战也没有产生 `已确认`/`未决` 问题，才算干净轮候选。

如果审查发现的问题全部被反证，且确认代理没有发现新问题，可以进入完成门禁，不需要为了“做点修改”而制造修复。

## 阶段 4：分组修复已确认问题

1. 只修复 `已确认` 且由本次重构引入的问题。
2. 按互不重叠的文件和调用链建立修复簇，派发多个修复子代理；强耦合问题由一个代理完整处理。
3. 每个修复代理获得：问题 ID、基线契约、允许修改文件、禁止范围、预期验证和独立报告路径。
4. 修复代理不得扩大功能、修改 Changelog、隐藏异常、降低测试或自行宣布整轮通过。
5. 主 Agent 逐个检查 worker 报告、实际 diff、调用方和测试，解决冲突并执行必要整合。
6. 修复完成后更新主记录，然后回到阶段 2，启动全新的完整审查轮。

## 阶段 5：完成门禁

只有同时满足以下条件才能把状态写为 `PASS`：

1. 最近一轮在所有相关审查维度上完成了独立审查。
2. 新确认代理完成了对抗性确认或清洁轮挑战。
3. 最近一轮没有 `已确认` 或 `未决` 问题；候选问题可以为空或全部被可靠反证。
4. 最近一轮之后没有再修改生产代码；如果修改过，必须重新开轮。
5. 等价性矩阵全部有代码、测试、日志或运行证据；不适用项有理由。
6. 针对性测试、相关集成测试和 scoped analyze 通过；既有或环境失败已区分并记录。
7. 最终 diff 只有任务范围内的结构变化和必要回归修复，没有第二事实来源、静默降级、宽泛吞错、死代码或无关格式化。
8. UI 重构具备直接布局证据。若既没有对应 widget/layout test，也没有经用户授权的运行态对比，状态必须保持 `BLOCKED_LAYOUT_EVIDENCE`，不能声称完整布局对齐。

完成时在 `progress.md` 写明：最终状态、干净轮编号、基线与最终 SHA/diff、验证命令、运行态是否执行、所有已反证问题及依据、剩余非阻塞事项。

## 最终回复

简洁报告：

- 拆分范围和新模块边界；
- 审查轮数、确认轮数和修复问题数量；
- 最终干净轮及进度记录路径；
- 实际执行的测试、分析和运行态验证；
- `PASS`、`BLOCKED_LAYOUT_EVIDENCE` 或其他阻塞状态。

没有满足完成门禁时不得使用“完全对齐”“已经成功”或“无回归”。