ssotize

找到唯一真实来源的位置，获取对整合计划的批准，然后将内容归并到一个权威来源中。

目标

落实单一事实来源（SSOT）：一条事实 = 一个存放位置，其他所有需要它的地方都引用该来源，而不是复制内容。引用不会漂移，副本会。这会修改产物，因此操作应谨慎，并尽量避免信息丢失。

ssotize 从只读审计开始。它会明确范围内的事实，找出所有副本，选定权威来源，并报告确切的整合计划。只有在用户批准计划后，才会修改产物。

将其用于建立或修复 SSOT——无论状态混乱、陈旧，还是刚搭建完成。一旦 SSOT 已落实，就不要过度使用它：整合是一次性修复，而非持续维护。当只读检查器与会修改内容的后续步骤已成为密不可分的工作流时，将检查器并入整合器并保留审批关卡；将这个习惯拆开，只会让更安全的前半部分更容易被跳过。

工作流

1. 明确范围内的事实——要追踪的具体事实、值、规范、决策、状态或定义，而不是整份文档。
2. 先进行只读审计：枚举给定产物和平台中的每一处。
3. 用第二种方法重新枚举——使用不同的搜索词、同义词或工具——并确认没有遗漏第一轮未发现的内容。
4. 对每处内容进行分类：完全相同的副本、释义、部分内容、过时内容或相互矛盾的内容。
5. 选定权威来源——选择最具权威性、维护最频繁且最接近事实实际变更位置的地方。切勿仅因方便就将薄弱副本提升为权威来源；如果不存在合适来源，就提取并建立新的权威来源。
6. 为每处非权威内容决定处理方式：去重（冗余副本）、引用（文档应链接到权威来源，代码应导入／引用／包含该来源，配置应从共享来源读取），或协调（内容存在分歧，需要人工判断）。
7. 编辑前报告审计结果：列出各处内容的表格（位置 · 类型 · 操作）、拟定的权威来源及一句话说明、必须纳入该来源的独有细节、需要作出决定的矛盾之处，以及确切的修改计划。
8. 请求明确批准后再执行修改计划。如果未获批准，则在只读报告后停止。
9. 补全并更新权威来源——纳入仅存在于副本中的独有细节。整合时绝不丢失信息。
10. 先在权威来源中协调矛盾；如果正确值不明确，应先确认，再替换任何内容。
11. 将每处重复内容替换为指向权威来源的有效引用——文档可使用链接、“参见 ”、带链接的引用，或平台支持的 transclude；代码可导入／引用／包含共享来源；配置可从唯一维护的文件中读取。
12. 删除现已冗余的副本。如果删除会导致读者失去指引，则保留一行指向权威来源的说明，而不是直接删除。

规则

• 如果一轮检查未发现需要整合的分散内容，则不做任何更改。
• 审计阶段为只读。用户批准变更计划前，不要编辑、移动或删除任何内容。
• 发现项列表为空也是有效结果——绝不要为了证明需要整合而捏造内容漂移。
• 将矛盾与普通重复分开处理；绝不要擅自认定哪个冲突值才是“正确的”。
• 标记任何仅存在于非权威副本中的细节——在删除该副本前，必须将这些细节并入权威归属处。
• 未经明确确认，不要跨越信任／权限边界进行整合（私有 → 公开、面向客户 → 内部）。
• 修改时确保编辑安全：操作前断言每个替换目标都存在（报告 MISS，绝不静默跳过）；使用 PYTHONUTF8=1 确保 Unicode 安全；逐个处理出现位置，绝不批量替换；使用了解语言的工具或脚本化 AST／解析器编辑进行结构性代码移动，绝不使用脚本进行文本改写。
• 考虑平台特性：尽可能使用内容转引，否则链接到读者可以访问的稳定锚点；当平台无法提供回链时，优先保留引用而不是彻底删除。
• 当同一项项目信息分散在只读审计产物和可变更产物中，且审计产物没有独立的持久用途时，将其视为 SSOT 分散：建议将审计内容并入可变更产物，然后仅在获得批准后执行。

验证

完成前：

1. 变更前已报告审计结果并获得批准，除非此次操作始终保持只读。
2. 权威归属处独立包含完整、最新的事实。
3. 每个原有副本现在都引用该归属处，且每个引用都有效。
4. 没有丢失独有细节，也没有内容成为孤立项。
5. 矛盾已统一为一个值，而不是仍然重复存在。
6. 报告整合了哪些内容、权威归属处在哪里、哪些内容仅经过审计，以及还有哪些事项需要人工决定。