# 全项目重构质量与验收要求

## 用户确认的目标与授权

2026-09-10，用户进一步明确：使用 TypeScript 重构时必须拆清文件和模块，持续维护方便后续 AI 接续维护与迭代的文档；允许主动修改项目中不合理的设计，并增加足够的测试用例。既有前提继续有效：大量用户正在使用，暴露接口必须兼容旧版本。

本要求适用于全部核心、插件、proxy、工具及相关工程流程，是每项实施任务的共同验收条件。任务表不构成修改范围的上限；发现新问题时补充或拆分任务，记录证据后继续推进已授权的内部改造，无需逐项重新询问常规文件拆分、内部重命名、类型和测试设计。

这项授权允许修复和改进内部实现，包括消除重复逻辑、整理依赖、调整目录、明确异步状态、资源回收和工程流程；不能把改变公开接口、默认产品行为或未经验证的依赖大升级当作内部整理。遇到实际兼容冲突，优先使用兼容门面、旧入口转发或能力 fallback，无法兼容时明确记录取舍。

用户还明确授权：可以自主选择并安装重构需要的新依赖，新增或改进合理的开发、构建、类型、测试、文档及维护脚本，无需为常规工具选择逐项询问。按实际任务引入，记录用途、版本、所属包和运行环境，并验证旧接口及分发兼容；具体执行规则见 toolchain-release.md。这是依赖和脚本改造授权，不要求提前安装所有可能用到的工具。

## 1. TypeScript 与文件拆分

- 迁移覆盖自有生产源码；同时整理职责、依赖和状态归属，不以改扩展名或补类型断言作为完成。
- 文件按职责划分：纯计算/解析、状态与调度、媒体/SDK adapter、DOM 渲染、事件与资源管理分别审查。
- 公共入口清楚，内部依赖方向可解释；避免循环依赖、所有模块都接收整个 art、含义不清的公共 utils 堆积。
- 不按固定行数机械拆文件。简单功能可以保留在一个文件，复杂文件必须解释边界，避免过度抽象和大量只有转发的碎文件。
- 将公开 API 与内部实现分开，使后续更换内部实现时无需改变用户调用。
- 为遗留 JS、vendored 文件、必要类型断言登记原因与边界；例外不意味着可以隐藏未完成迁移。

## 2. 不合理设计的主动审查

每个模块审查：重复代码、隐式全局状态、初始化依赖、异常处理、竞态、资源泄漏、陈旧回调、类型与实现漂移、不可测试的依赖、无依据的性能开销和失效文档。

发现的问题分成已复现缺陷、可验证的设计改进、待取证疑点。前两类可在兼容边界内自主解决，必要时扩展 tasks.json；疑点先验证，不把猜测写成已修复缺陷。范围较大的调整分批交付，保留可回退边界。

## 3. 面向后续 AI 的模块文档

每个迁移包必须在包内 README 或 ARCHITECTURE.md 维护实现地图。复杂核心/插件需要单独的架构文档；简单包用 README 的维护章节即可，避免复制无意义模板。

文档必须解释：

1. 主要文件各自负责什么、公开入口在哪里、内部依赖方向。
2. 关键数据流、状态转换、事件/Promise 的重要顺序。
3. DOM/监听器/定时器/请求/worker/媒体资源由谁创建、谁释放。
4. 哪些历史接口、类型、别名、样式和行为是兼容边界，为什么保留。
5. 修改某项能力通常应从哪个模块开始，哪些组合需要回归。
6. 可以实际执行的测试、类型检查、构建和 demo 命令。
7. 已知限制、未验证环境、遗留事项及对应任务/决策链接。

实现变更必须在同一批更新相关文档，不把维护说明留到最后集中补写。refactor 下记录迁移过程，包内文档记录最终实际架构；两者用途不同，避免维护两份相互冲突的文件地图。

## 4. 足够且有效的测试

- 以风险和公开行为决定测试范围，不以测试数量或统一覆盖率数字作为唯一完成标准。
- 每个被修复缺陷有复现用例；每个迁移边界有正常、边界、失败和必要生命周期测试。
- 异步能力重点覆盖连续操作、乱序完成、取消、重复调用、销毁中回调和异常传播。
- 对 API/事件/返回值/类型/入口的兼容建立消费者用例，包含新核心旧插件和原支持范围旧核心新插件。
- 媒体播放、DOM 交互、跨窗口及 codec/SDK 能力需要对应浏览器或真实环境证据，mock 只验证可控部分。
- 纯目录移动、文案和低影响格式修改复用现有检查，不添加只重复实现的测试。
- 不通过删除失败用例、无理由跳过、宽泛断言、全量更新快照或扩大超时制造通过结果。

## 5. 完成门槛

实施任务标为 done 前，在变更记录中逐项说明：

| 项目 | 所需证据 |
| --- | --- |
| 结构 | 职责与依赖清楚，拆分理由明确，不合理设计已处理或链接后续任务 |
| 类型 | 对应严格检查和消费者样例通过，类型声明与运行时一致 |
| 兼容 | 旧 API、类型、事件/Promise、DOM/CSS 和分发路径没有未经处理的回归 |
| 测试 | 风险对应的用例、运行结果和限制；修复问题有可重跑复现 |
| 文档 | 实际模块地图、维护入口、命令和决策随实现更新 |
| 交接 | 变更、任务状态、剩余问题、下一步及回退方法可追溯 |
| 提交 | 每个完成任务已有独立本地 commit，包含任务 ID 与实现/测试/文档/状态，提交结果已核实 |

只有文档或计划变更时，如实记录文档验证，不能声称上述生产代码和浏览器验收已经完成。

用户补充要求：每完成一个任务就提交一个 commit。本地提交是任务交付的一部分，不能只改状态而不提交，也不能积累多个已完成任务后合并提交；执行方式见 ai-workflow.md。