# Environment ## Description Environment 模块提供围绕运行环境（environment）进行识别、描述、访问和校验的基础能力，用于统一处理运行时（runtime）、宿主能力（feature）、设备信息（device）、地理信息（geo）、环境变量（environment variable）以及环境快照（snapshot）等问题域。 它关注的是“当前处于什么环境、可以读取哪些环境上下文、这些环境信息如何被安全表达”，而不是基于这些信息替调用方做业务决策。 ## For Understanding 理解 Environment 模块时，应先明确它的职责边界：它负责识别环境、描述环境、读取环境，而不负责操纵环境或消费环境事件。也就是说，这个模块可以帮助调用方判断当前是不是浏览器、Node.js、Bun、Deno、Web Worker 或 Service Worker，可以帮助访问 `navigator`、`document`、`process` 这类宿主对象，也可以帮助读取设备、地理、变量与快照信息；但它不应直接承担全局异常监听、事件订阅注册、日志上报、状态恢复或业务分支策略。 当前模块可以理解为几类相互关联但边界清楚的子问题域： - 运行时识别与上下文获取：用于检测当前运行时、暴露相应上下文，并为分支执行提供 `use...` 风格入口。 - 宿主能力访问：用于判断和获取 `process`、`navigator`、`document`、`CSS`、权限（permissions）等特定宿主能力。 - 设备与用户代理信息：用于从 `navigator`、`screen` 或传入的 user agent 中整理稳定的设备描述。 - 地理信息：用于从外部服务拉取 IP 或地理位置相关信息。 - 变量与配置：用于解析、加载、校验环境变量，并把变量读取与模式（schema）验证组合起来。 - 快照与诊断：用于把多种环境信息组合成更适合诊断或输出的快照视图。 只要问题的核心仍是“当前环境是什么、有哪些可用上下文、环境信息如何被读出并表达”，它就适合属于 Environment。反之，如果问题已经变成“拿到环境后如何驱动宿主行为”，那通常就应该交给其它模块。 ## For Using 当应用需要在跨运行时代码中做分支、访问宿主上下文、整理设备信息、读取环境变量或采集诊断快照时，可以使用这个模块。它尤其适合放在应用入口、基础设施层和适配层，而不是深入业务语义最内层。 当前公共能力大致可以按以下几类理解： - 运行时识别与条件执行：例如识别浏览器、Node.js、Bun、Deno、Worker 等运行时，并按运行时安全获取上下文或分发逻辑。 - 宿主能力访问：例如判断并获取 `process`、`navigator`、`clipboard`、`permissions`、`document`、`CSS` 等宿主对象。 - 设备与 user agent 分析：例如读取设备导航信息、屏幕信息，或把 user agent 解析为更稳定的设备描述。 - 地理信息查询：例如聚合外部服务提供的 IP 与地理位置信息，用于诊断、展示或环境补充。 - 环境变量读取与校验：例如解析变量文本、读取变量宿主、加载变量、结合 schema 做结构化验证。 - 环境快照：例如把当前运行时、设备、变量等信息整理成适合输出、调试或诊断的综合视图。 调用方在使用时仍应处理宿主差异与降级路径。Environment 的职责是让这些差异更容易被表达和访问，而不是假装所有环境都完全一致。 ## For Contributing 贡献 Environment 模块时，应优先判断新增能力是否真的表达了稳定、可复用、跨项目成立的环境语义。如果它只是某个业务流程中的一次性判断，或者它的核心已经变成宿主交互副作用，那么通常不应进入这个模块。 在扩展时，应优先遵守以下边界： - 这里负责识别环境、读取环境、描述环境，而不负责全局监听、日志发送、状态恢复或其它策略层行为。 - 运行时识别与宿主能力访问应保持清楚分层，不要把“能否访问某对象”和“拿到对象后做什么”混成一个入口。 - 设备、地理、变量、快照等子问题域可以共存，但都应回到统一的环境语义，而不是各自演变成独立杂项工具。 - 公共能力应优先让缺失环境时的失败语义清楚可见，而不是通过隐式降级掩盖上下文不可用的事实。 ### JSDoc 注释格式要求 - 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。 - JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。 - 如果描述后还有其他内容，应在描述后加一个空行。 - 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。 - 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。 - 如果有示例，应使用注释格式说明每个场景：`// Expect: `。 - 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。 - 如果有示例，`// Expect: ` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。 - 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。 - 如果函数返回结构化字符串，应展示其预期格式特征。 - 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。 ### 实现规范要求 - 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。 - 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。 - 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。 - 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。 - 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。 - 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。 - 辅助元素永远不要公开导出。 - 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/environment/internal.ts`；若共享仅存在于某个子问题域内部，也可以放在对应文件或子模块中。 - 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。 - 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。 - 子模块不需要有自己的 `README.md`。 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。 - 实现应优先保持检测逻辑、上下文获取逻辑与后续使用逻辑解耦，避免让单一入口同时承担过多副作用和策略判断。 ### 导出策略要求 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。 - 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的环境语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。 ### 测试要求 - 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。 - 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。 - 模块的单元测试文件目录是 `./tests/unit/environment`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/environment/`。 - 测试应重点覆盖运行时识别、宿主能力可用性、缺失上下文时的失败语义、变量校验路径，以及设备与快照输出是否保持稳定可解释。