# Aio ## Description Aio 模块提供围绕 AI IO（Artificial Intelligence Input / Output，人工智能输入输出）的基础能力，用于组织与 AI 交互时的提示内容、结构化文本输出，以及与这些输入输出直接相关的稳定公共语义。 ## For Understanding 理解 Aio 模块时，应先把它视为一个围绕“如何把人类与 AI 之间交换的内容整理为更稳定、更可组合的输入输出结构”而建立的问题域模块，而不是一个泛化的 AI 工具箱，也不是任何与模型调用沾边的能力都能放进来的收纳层。 这里的重点不在于“是否和 AI 有关”，而在于“是否直接服务于 AI 交互内容本身的输入或输出组织”。例如，提示词块（prompt block）组合、结构化响应文本的提取与校验、与 LLM 返回文本直接相连的内容修复入口，都属于这个边界；而模型提供商适配、请求重试策略、会话编排、业务语义解释、工具调用协议实现，则通常属于更上层或其它模块的问题。 当前模块的公共能力可以从三个方向理解： - 内容侧（Content）：把流式或分段到达的文本、数值等内容变化表示为可累计、可重建的增量序列。 - 输入侧（Input）：把提示内容组织成可稳定拼接、易于维护和复用的字符串结构。 - 输出侧（Output）：把 AI 返回的文本进一步提取、修复、解析并校验成更可用的结构化结果。 因此，Aio 模块关注的是“交互内容的表达与落地”，而不是“模型本身如何运行”。如果某项能力的核心问题已经转向模型供应商差异、请求生命周期控制、业务工作流状态管理或领域结果解释，那么它通常不应直接落在这里。 ## For Using 当你需要把 AI 交互中的输入或输出整理成更稳定的基础模型能力，而不是在业务代码里零散拼接 prompt 字符串、手动提取代码块、或临时校验 LLM 返回 JSON 时，可以使用这个模块。 当前公共能力大致可以按使用意图理解为三类： - 内容增量能力：把一段内容的变化表示为 delta（增量），并在已有内容快照上继续应用这些变化，得到新的总结果。 - Prompt 组织能力：把文本、空行、作用域内容（scope content）以及简单列表项组合成一段可直接交给 AI 的提示词文本。 - 结构化响应处理能力：从响应文本中提取 JSON 代码块，必要时进行有限修复，并结合标准 schema 做同步校验，得到可继续使用的结构化结果。 这种能力尤其适合以下场景： - 需要消费流式返回的文本或数值片段，并在过程中维护一份可回放、可重建的累计内容状态。 - 需要在应用或库中统一构造 prompt，而不希望各处手写拼接规则。 - 需要消费 LLM 输出的 JSON 文本，但又希望把“提取、修复、解析、校验”这条链路收敛到一个稳定入口。 - 希望让 AI 输入输出的处理方式可测试、可复用，并尽量减少散落在业务层的文本处理细节。 使用时也应保持边界意识：Aio 模块可以帮助你组织输入输出内容，但它并不负责定义某个业务领域的最终语义。若你的问题已经进入工作流编排、工具调用路由、上下文生命周期管理或业务对象解释，应在更上层继续分层。 ## For Contributing 贡献 Aio 模块时，应优先判断新增能力是否直接围绕 AI 交互内容本身的输入或输出展开，而不是因为名称里带有 AI 就把调用链路、业务逻辑或平台适配一起塞进来。这个模块可以继续增长，但增长方向应始终围绕“输入输出内容如何被稳定表达与处理”这一核心边界。 在扩展时，应优先遵守以下边界： - 公共能力应直接服务于内容增量表示、prompt 组织、响应文本提取、结构化输出修复与校验等输入输出问题。 - 不要把模型供应商适配、请求调度、网络重试、会话状态机、工具调用编排等能力直接放进 Aio 模块。 - 若某项能力主要解决的是业务语义解释，而不是 AI 输入输出本身，则应放在更合适的上层模块中。 - 对于具有容错性质的输出处理能力，应保持失败语义清楚；当文本超出可稳定修复或可稳定解析的范围时，抛错通常比返回含糊结果更符合该模块边界。 - Prompt 相关能力应优先保持组合规则简单、可预期；如果某种格式规则已经复杂到依赖强上下文或业务协议，通常说明它不再只是 Aio 模块内的基础块。 - Content 相关能力应优先保持增量语义清楚、可回放且可预测；如果某种“内容”抽象已经转向业务级 patch 协议或复杂协同编辑语义，则应考虑放在更专门的模块中。 ### JSDoc 注释格式要求 - 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。 - JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。 - 如果描述后还有其他内容，应在描述后加一个空行。 - 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。 - 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。 - 如果有示例，应使用注释格式说明每个场景：`// Expect: `。 - 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。 - 如果有示例，`// Expect: ` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。 - 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。 - 如果函数返回结构化字符串，应展示其预期格式特征。 - 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。 ### 实现规范要求 - 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。 - 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。 - 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。 - 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。 - 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。 - 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。 - 辅助元素永远不要公开导出。 - 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/aio/internal.ts`；若当前共享逻辑很小，则不必为了形式拆出没有稳定价值的文件。 - 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。 - 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。 - 子模块不需要有自己的 `README.md`。 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。 - 实现时应优先保持 AI 输入输出处理规则的显式性与可预期性，避免堆叠过多隐式格式修复规则，导致外部难以理解模块到底承诺了什么。 ### 导出策略要求 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。 - 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的 Aio 模块语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。 ### 测试要求 - 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。 - 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。 - 模块的单元测试文件目录是 `./tests/unit/aio`；若未来出现子模块，则子模块的单元测试文件目录为 `./tests/unit/aio/`。 - 测试应覆盖内容增量应用、prompt 组合、结构化响应提取与解析等公共能力的稳定语义，重点验证可预期输入下的结果，以及超出承诺边界时是否以明确失败结束。