prelude

初始化 TypeScript Prelude

Prelude 是显式导入的模块，用于提供环境级辅助函数和类型：这些构件用途广泛、与领域无关，且没有更适合的归属。使用随附的 prelude.ts 作为基础，然后根据目标代码仓库中的实际情况进行调整。全程遵循 ../coding-standards/SKILL.md。

“环境级”描述的是辅助函数的作用，而不是 TypeScript 全局变量。Prelude 的导出应通过普通导入使用；不要添加全局声明或全局扩展。

1. 梳理代码仓库

阅读代码仓库说明、包清单、TypeScript 配置、源代码布局和导入惯例。定位以下内容：

• 已有的 prelude 或等效共享模块；
• 名称为 utils、helpers、common、types、result、errors 或类似名称的文件；
• 在多个模块中重复出现的泛型类型别名和简短泛型函数；
• 用于结果、架构、脱敏、品牌化、集合和穷尽匹配的既有库；
• 所有可能调用环境级辅助函数的代码。

同时按文件名和概念搜索。将编码标准中的常见泛型辅助函数和类型类别作为搜索词，然后检查定义和调用处，不要仅凭名称进行分类。

完成标准： 通过全代码仓库的文件名、符号和重复项扫描发现的每个可能属于环境级的定义，都已列入清单，并记录其归属、调用方、依赖项和当前行为。

2. 对每个候选项进行分类

满足以下所有条件时，符号才应放入 prelude：

• 与领域无关，且对互不相关的模块都有用；
• 没有领域模块、应用服务、适配器、协议或专门的泛型模块更适合作为其归属；
• 集中管理能够减少重复，或为常见概念提供唯一规范实现；
• 依赖项极少、稳定，且已得到项目认可；
• 行为足够简单，能在导入处理解，或由精确的类型封装。

如果符号承载领域含义、应用策略、边界转换、框架行为、I/O，或字符串大小写转换、非简单集合操作等连贯的泛型概念，则应保留在其专属归属处。优先使用成熟库，而非本地重复实现。Prelude 应是经过筛选的基础模块，而非聚合导出模块或杂项堆放处。

为每个候选项记录一项决策：使用成熟库、保留当前归属、移入 prelude、与模板中的符号合并，或作为未使用的重复项删除。

完成标准： 每个已列入清单的候选项都根据其语义和调用方做出一项决策；没有候选项仅根据文件名或名称进行分类。

3. 从模板开始

完整阅读随附的 prelude.ts。将其复制到项目既定的共享模块位置，作为起点。如果已有 prelude，应谨慎合并，而非直接覆盖。

准确选择一种预期失败的基础方案：

1. 如果项目使用 Effect，则使用 Effect 的结果/错误处理功能，并移除模板中的本地 Result 备用实现。
2. 如果项目使用 better-result，则使用它，并移除本地备用实现。
3. 如果项目两者都未使用，则询问是否安装 better-result。
   • 如果同意，则安装它并移除本地备用实现。
   • 如果不同意，则启用模板中的本地 Result 类型和辅助函数。

仅当代码仓库中的用法、编码标准或所需基础方案有明确依据时，才保留其他模板导出。合并等效辅助函数时，应保留兼容的现有行为；如有语义冲突，应明确指出，而不是默默选用某种实现。

完成标准： 目标文件以模板为基础，且仅采用一种结果处理方案；每个保留的模板导出都有明确依据。

4. 整合环境辅助工具和类型

将获准的仓库候选项移入或合并到前导模块中。对于每个迁移的符号：

• 除非要求更改行为，否则保留其行为；
• 保留其公开名称和类型契约，或有意进行迁移；
• 更新所有调用方，使其直接从前导模块导入；
• 保留必需的 JSDoc、安全注释和针对性的 lint 禁用项；
• 调用方迁移后，移除已被取代的定义和兼容性重新导出。

确保生成的模块没有副作用。它不得读取配置、获取资源、注册处理程序、执行 I/O、包含领域或应用策略，也不得重新导出无关模块。

完成标准： 每个获准的候选项都只有一个规范定义，所有调用方都使用该定义，且已删除的源代码不再作为第二个事实来源。

5. 验证基础

运行仓库的格式化程序、类型检查器、代码检查工具和针对性测试。再次搜索旧符号、重复定义、过时的导入路径，以及清单中涉及的宽泛工具文件。检查每个前导模块导出项是否仍在使用，或是否有明确的基础性理由。

报告：

• 选择的结果策略；
• 保留或移除的模板导出项；
• 已迁移、已合并、保留原位或已删除的仓库辅助工具；
• 验证命令和结果。

完成标准： 仓库检查全部通过，清单中的每项决策都已落实到代码中，重复的环境定义已移除，且每个前导模块导出项都有合理依据。