deduplicate

去重

**唯一目标：**通过建立一个规范实现并让所有使用方都使用它，消除重复知识。

不要扩展到一般性清理、重命名、布局重写或代码异味排查。如果某项内容并非重复（或并非正确去重所必需），就保持原样。

核心规则

• 保持行为、公共 API 和数据格式不变，除非用户授权更改。
• 去重的是会逐渐产生差异的知识，而不是偶然相似的结构。
• 与其做出错误的抽象，不如保留少量有意重复的内容。仅当多个副本共享一个稳定的概念、名称和变更原因时，才将其提取出来。
• 如果已有合适的概念归属位置，就优先复用。不要另建一个竞争性的 utils / helpers / shared 大杂烩。
• 让改动易于审查：范围较大时，每次处理一个重复项集群（或紧密相关的集群）。
• 保留与本任务无关的用户改动。

确定范围

• **指定目标：**仅处理指定的文件、目录、模块、功能或重复项集群。为了解情况，可以追踪目标外部的引用；只有在接入共享来源时才修改这些位置。
• **整个代码库：**先搜索一方代码中的重复热点。排除生成文件、供应商代码、构建输出、缓存、锁文件、快照和迁移文件，除非它们就是明确指出的问题。

如果边界不明确，且会影响编辑范围，请提出一个聚焦的范围问题。否则，说明推断出的边界并继续。

工作流

1. 梳理候选项

搜索重复的以下内容：

• 逻辑 / 算法 / 验证 / 映射
• 类型、接口、架构、常量、枚举、配置
• 表达相同产品概念的 UI 片段
• 编码了相同领域测试夹具的测试设置

为每个集群记录：位置、重复的知识、置信度和建议的规范归属位置。

跳过那些只是形态相似但含义不同的集群，以及出于合理原因会产生差异的集群。详情见：when-not-to.md。

2. 选择唯一事实来源

对每个接受的集群，使用 ssot-placement.md 选择一个归属位置。

决策顺序：

1. 是否已有模块负责这个概念？优先使用它。
2. 否则，将其放在所有使用方共同归属的最窄范围内（功能 → 包 → 工作区包）。
3. 按照概念命名，而不是按“共享辅助工具”命名。
4. 优先采用一个清晰的导出，而不是一个大杂烩文件。

提取之前（或提取时）说明所选路径及原因。

3. 提取并重新接入

1. 在选定的归属位置移动或创建规范实现。
2. 用导入 / 组合该来源的方式替换所有重复项。
3. 删除现已无用的副本。
4. 更新测试：通过共享来源进行断言；仅保留使用方特有的本地覆盖。
5. 不要留下仅重新导出而没有增加意义的“薄封装”——除非公共边界需要稳定的门面。

4. 验证

针对已修改的部分，运行现有的、范围最小的格式检查 / lint / 类型检查 / 测试。只有当共享模块位于横切边界时，才扩大验证范围。

如果无法运行检查，请说明跳过了哪些检查以及原因。

完成报告

保持简短：

• 检查范围
• 已去重的集群：概念 → 规范路径 → 原位置
• 保留未处理的集群（并说明原因：有意保持差异、相似性不成立、超出范围、置信度较低）
• 已运行的验证及结果