AIRI 的 xsAI 包选型指南细粒度 xsai/* 包与 xsai 伞包如何取舍【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI 的 LLM、语音、工具调用等能力构建在 xsAI 这套 OpenAI 兼容运行时之上而选对包决定了安装体积、导入面与维护成本。本文基于仓库内的选型参考文档 .agents/skills/xsai/references/package-selection.md 展开完整继承其中的通用规则、逐包推荐与导入建议并结合同仓库各包的package.json、pnpm catalog 与实际源码调用给出在 AIRI 这类多包前端工程中可复制、可验证的选型方法。核心原则优先最小包伞包是例外参考文档给出的第一条通用规则General rule是优先选择能解决问题的最小包Prefer the smallest package that solves the task。只有当用户同时需要多种功能或希望保持单一导入面single import surface时才推荐伞包umbrellaxsai。这条规则在仓库顶层的技能说明 .agents/skills/xsai/SKILL.md 中被再次强化默认工作流要求“先检查现有仓库的依赖与导入风格保留xsai或细粒度xsai/*的既有写法”“当用户以 bundle 或安装体积为优化目标时明确优先xsai/generate-text这类细粒度包而非xsai”。换句话说在 AIRI 生态的语境里细粒度包是默认解伞包是需要理由才启用的备选解。逐包推荐xsAI 包家族一览参考文档列出了 10 个细粒度包加 1 个伞包。下表完整继承原推荐清单并结合对仓库内所有packages/、apps/、integrations/、services/下package.json的扫描补充了每个包在 AIRI 中的实际引用情况引用次数为依赖声明行数统计可据此判断哪些包是工程主力包名官方推荐用途引自参考文档AIRI 仓库中的引用情况xsai/generate-text最简单的单程unary文本生成10 处覆盖面最广的主力包xsai/stream-text流式文本或工具事件6 处如 packages/core-agent/src/runtime/llm-service.tsxsai/generate-object带校验的结构化输出当前扫描范围内未发现直接依赖声明xsai/stream-object增量式结构化输出当前扫描范围内未发现直接依赖声明xsai/tool工具定义与原始 JSON Schema 工具7 处tool()与rawTool()均有使用xsai/embed文本嵌入embeddings2 处xsai/generate-image图像生成当前扫描范围内未发现直接依赖声明xsai/generate-speech文本转语音TTS8 处如 packages/stage-ui/src/stores/modules/speech.tsxsai/generate-transcription单程语音转写2 处xsai/stream-transcription流式语音转写6 处如 packages/stage-ui/src/libs/providers/stream-transcription/index.tsxsai伞包重新导出以上所有包仓库内各package.json均未直接依赖伞包从上表可以得到一个直接结论AIRI 是一个彻底的“细粒度派”仓库——没有任何一个子包声明了对伞包xsai的依赖每个包只引入自己真正用到的 API。这正是参考文档“优先最小包”规则在一个大型 monorepo 中被完整执行的样本。此外从仓库结构看AIRI 实际使用的依赖面比参考文档清单更细还包含若干支撑型包xsai/shared-chat11 处共享的Message、Tool、Usage等类型与stepCountAtLeast等停止条件工具xsai/model5 处如listModels模型列表查询见 packages/stage-ui/src/stores/ai/chat-llm/llm.tsxsai/shared、xsai/utils-chat各 56 处通用请求选项与聊天工具函数。参考文档的清单聚焦“功能入口包”而支撑型包通常作为类型依赖伴随出现选型时若只需某一功能入口功能包是决策主体支撑包随类型引用自动进入依赖图。版本统一pnpm catalog 锁定全部 xsai/* 版本细粒度包数量较多时版本漂移是常见风险。AIRI 用 pnpm workspace 的 catalog 机制规避了这个问题pnpm-workspace.yaml 将全部xsai/*包统一钉在0.5.0-beta.8xsai/embed: 0.5.0-beta.8 xsai/generate-speech: 0.5.0-beta.8 xsai/generate-text: 0.5.0-beta.8 xsai/generate-transcription: 0.5.0-beta.8 xsai/model: 0.5.0-beta.8 xsai/shared: 0.5.0-beta.8 xsai/shared-chat: 0.5.0-beta.8 xsai/stream-text: 0.5.0-beta.8 xsai/stream-transcription: 0.5.0-beta.8 xsai/tool: 0.5.0-beta.8 xsai/utils-chat: 0.5.0-beta.8各子包的package.json中依赖项一律写作catalog:例如 packages/core-agent/package.jsonxsai-ext/providers: catalog:, xsai/generate-speech: catalog:, xsai/generate-text: catalog:, xsai/model: catalog:, xsai/shared: catalog:, xsai/shared-chat: catalog:, xsai/stream-text: catalog:, xsai/tool: catalog:这意味着即便选择了多个细粒度包它们在工程内也保证来自同一版本线不存在“xsai/stream-text与xsai/shared-chat类型不兼容”这类隐患。这是“多包细粒度选型”在工程上成立的前提值得在自己的项目中照搬。同一 catalog 中还登记了 xsAI 生态的扩展包pnpm-workspace.yamlxsai-apple-speech/*0.1.3Apple 平台转写、xsai-ext/providers预定义 provider0.5.0-beta.8、xsai-transformers/*^0.1.0transformers.js 后端。参考文档本身不涵盖这些扩展包但它们印证了 xsAI 的边界核心包保持 OpenAI 兼容的最小面平台特定能力以xsai-*/扩展包形式外挂。导入建议三条规则与 AIRI 中的对应实践参考文档的 Import advice 部分给出三条建议逐条对应到仓库事实“如果用户明确在意体积从细粒度包导入。”AIRI 全部 30 处xsai/*导入都来自细粒度包没有一处import ... from xsai。例如语音模块只取所需的一个函数// packages/stage-ui/src/stores/modules/speech.ts#L9 import { generateSpeech } from xsai/generate-speech这样打包器只会把generateSpeech所在的模块图拉进 bundle伞包中其余 9 个功能的代码不会进入产物。“如果用户在写文档示例或希望只依赖一个包xsai是可接受的。”这是对伞包的定位面向示例、教程与轻量项目xsai提供更简洁的单一导入面。AIRI 主仓库因为追求体积与边界清晰没有采用它但该豁免条件真实存在不要把它视为错误用法。“编辑既有代码库时遵循仓库已使用的包风格除非有充分理由改变。”这条在 AIRI 里体现为风格一致性工具定义统一从xsai/tool导入且按场景选择tool()与rawTool()// packages/stage-ui/src/tools/debug.ts#L1 import { tool } from xsai/tool // packages/stage-ui/src/tools/web-search.ts#L3 import { rawTool } from xsai/tool // packages/core-agent/src/agents/spark-notify/tools.ts#L7 import { rawTool } from xsai/tool从 SKILL.md 的 API selection rules 可以推断出两者的分工tool()面向 Zod、Valibot 这类 Standard Schema 库rawTool()面向已有原始 JSON Schema 的场景直接传裸Tool对象仅在仓库已使用该形状时采用。AIRI 中既有tool()如 mcp.ts也有rawTool()并存正是“遵循既有形状”规则的落地。源码实证每个细粒度包在 AIRI 里被如何使用以下摘录均出自仓库源码可直接点击路径继续深入用于印证上表的选型逻辑xsai/stream-text流式对话主干。packages/core-agent/src/runtime/llm-service.ts 同时导入stepCountAtLeast来自xsai/shared-chat与streamText把 xsAI 的流事件text.delta、reasoning.delta、tool-call.done、tool-result.done等映射为 AIRI 内部的StreamEvent契约。源码注释还提到stopWhen控制带显式停止谓词的工具循环——这是流式包选型时容易被忽略的配套能力。xsai/generate-speechTTS 入口。packages/stage-ui/src/stores/modules/speech.ts 的 Pinia store 只依赖generateSpeech一个函数其余能力由 AIRI 自己的 provider 层补齐。xsai/stream-transcription流式转写类型。packages/stage-ui/src/libs/providers/stream-transcription/index.ts 基于StreamTranscriptionDelta、StreamTranscriptionResult类型扩展出 AIRI 的“可替换快照”事件transcript.text.snapshot并用自实现的 SSE 解析器归一化音频块。这说明选包选的是类型契约 运行时原语上层协议仍由工程自行编排。xsai/embed嵌入能力。packages/stage-ui/src/components/scenes/Stage.vue 直接引用xsai/embed配合 catalog 中登记的xsai-transformers/embed提供本地嵌入后端。xsai/generate-text/xsai/model文本生成与模型列表查询分别散见于各 provider 与设置模块如 packages/stage-ui/src/stores/ai/chat-llm/llm.ts 的listModels引用面最广对应“最常用功能配最小包”的选型结果。定位边界OpenAI 兼容优先而非通用 provider 抽象层参考文档末尾的 Positioning reminder 只有一句但约束力很强xsAI 是有意为之的 OpenAI-compatible-firstOpenAI 兼容优先不要把 xsAI 当作通用 provider 抽象层来推荐。这与 SKILL.md 中“不适用场景”完全一致当任务需要超出 OpenAI 兼容面的 provider 抽象、需要“全家桶”式 AI 应用框架、或依赖未通过 OpenAI 兼容接口暴露的 provider 专有 API 时不应选择 xsAI。AIRI 的做法也印证了这一点它需要多 provider 管理时引入的是xsai-ext/providers这类显式扩展包见 packages/core-agent/package.json而不是期待核心包提供万能抽象。对读者而言这条边界直接影响选型决策如果你的目标 API 是 OpenAI 兼容端点含大量自托管网关按本文前述规则选最小包即可如果不是xsAI 包家族就不在候选集内选型讨论应另起。选型自检清单综合参考文档与仓库实践在 AIRI 或同类工程中做包决策时可按以下顺序自检目标 API 是否 OpenAI 兼容否 → 停止xsAI 不适用。需要几种能力只有一种 → 选对应最小功能包对照“逐包推荐”表。同时需要多种能力且希望单一导入面→ 可评估伞包xsai若体积敏感仍应保持细粒度包。是既有代码库吗→ 沿用仓库现有导入风格AIRI 全仓为细粒度包 pnpm catalog 统一版本不轻易切换。需要工具调用→xsai/tool下的tool()Standard Schema 库或rawTool()原始 JSON Schema。多包并存时是否用 catalog/lockfile 统一版本AIRI 的答案见 pnpm-workspace.yaml。按此清单执行既能继承参考文档的选型骨架也能保证与 AIRI 仓库当前 0.5.0-beta.8 版本线下的真实依赖结构一致。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AIRI 的 xsAI 包选型指南：细粒度 @xsai/* 包与 xsai 伞包如何取舍
AIRI 的 xsAI 包选型指南细粒度 xsai/* 包与 xsai 伞包如何取舍【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airiAIRI 的 LLM、语音、工具调用等能力构建在 xsAI 这套 OpenAI 兼容运行时之上而选对包决定了安装体积、导入面与维护成本。本文基于仓库内的选型参考文档 .agents/skills/xsai/references/package-selection.md 展开完整继承其中的通用规则、逐包推荐与导入建议并结合同仓库各包的package.json、pnpm catalog 与实际源码调用给出在 AIRI 这类多包前端工程中可复制、可验证的选型方法。核心原则优先最小包伞包是例外参考文档给出的第一条通用规则General rule是优先选择能解决问题的最小包Prefer the smallest package that solves the task。只有当用户同时需要多种功能或希望保持单一导入面single import surface时才推荐伞包umbrellaxsai。这条规则在仓库顶层的技能说明 .agents/skills/xsai/SKILL.md 中被再次强化默认工作流要求“先检查现有仓库的依赖与导入风格保留xsai或细粒度xsai/*的既有写法”“当用户以 bundle 或安装体积为优化目标时明确优先xsai/generate-text这类细粒度包而非xsai”。换句话说在 AIRI 生态的语境里细粒度包是默认解伞包是需要理由才启用的备选解。逐包推荐xsAI 包家族一览参考文档列出了 10 个细粒度包加 1 个伞包。下表完整继承原推荐清单并结合对仓库内所有packages/、apps/、integrations/、services/下package.json的扫描补充了每个包在 AIRI 中的实际引用情况引用次数为依赖声明行数统计可据此判断哪些包是工程主力包名官方推荐用途引自参考文档AIRI 仓库中的引用情况xsai/generate-text最简单的单程unary文本生成10 处覆盖面最广的主力包xsai/stream-text流式文本或工具事件6 处如 packages/core-agent/src/runtime/llm-service.tsxsai/generate-object带校验的结构化输出当前扫描范围内未发现直接依赖声明xsai/stream-object增量式结构化输出当前扫描范围内未发现直接依赖声明xsai/tool工具定义与原始 JSON Schema 工具7 处tool()与rawTool()均有使用xsai/embed文本嵌入embeddings2 处xsai/generate-image图像生成当前扫描范围内未发现直接依赖声明xsai/generate-speech文本转语音TTS8 处如 packages/stage-ui/src/stores/modules/speech.tsxsai/generate-transcription单程语音转写2 处xsai/stream-transcription流式语音转写6 处如 packages/stage-ui/src/libs/providers/stream-transcription/index.tsxsai伞包重新导出以上所有包仓库内各package.json均未直接依赖伞包从上表可以得到一个直接结论AIRI 是一个彻底的“细粒度派”仓库——没有任何一个子包声明了对伞包xsai的依赖每个包只引入自己真正用到的 API。这正是参考文档“优先最小包”规则在一个大型 monorepo 中被完整执行的样本。此外从仓库结构看AIRI 实际使用的依赖面比参考文档清单更细还包含若干支撑型包xsai/shared-chat11 处共享的Message、Tool、Usage等类型与stepCountAtLeast等停止条件工具xsai/model5 处如listModels模型列表查询见 packages/stage-ui/src/stores/ai/chat-llm/llm.tsxsai/shared、xsai/utils-chat各 56 处通用请求选项与聊天工具函数。参考文档的清单聚焦“功能入口包”而支撑型包通常作为类型依赖伴随出现选型时若只需某一功能入口功能包是决策主体支撑包随类型引用自动进入依赖图。版本统一pnpm catalog 锁定全部 xsai/* 版本细粒度包数量较多时版本漂移是常见风险。AIRI 用 pnpm workspace 的 catalog 机制规避了这个问题pnpm-workspace.yaml 将全部xsai/*包统一钉在0.5.0-beta.8xsai/embed: 0.5.0-beta.8 xsai/generate-speech: 0.5.0-beta.8 xsai/generate-text: 0.5.0-beta.8 xsai/generate-transcription: 0.5.0-beta.8 xsai/model: 0.5.0-beta.8 xsai/shared: 0.5.0-beta.8 xsai/shared-chat: 0.5.0-beta.8 xsai/stream-text: 0.5.0-beta.8 xsai/stream-transcription: 0.5.0-beta.8 xsai/tool: 0.5.0-beta.8 xsai/utils-chat: 0.5.0-beta.8各子包的package.json中依赖项一律写作catalog:例如 packages/core-agent/package.jsonxsai-ext/providers: catalog:, xsai/generate-speech: catalog:, xsai/generate-text: catalog:, xsai/model: catalog:, xsai/shared: catalog:, xsai/shared-chat: catalog:, xsai/stream-text: catalog:, xsai/tool: catalog:这意味着即便选择了多个细粒度包它们在工程内也保证来自同一版本线不存在“xsai/stream-text与xsai/shared-chat类型不兼容”这类隐患。这是“多包细粒度选型”在工程上成立的前提值得在自己的项目中照搬。同一 catalog 中还登记了 xsAI 生态的扩展包pnpm-workspace.yamlxsai-apple-speech/*0.1.3Apple 平台转写、xsai-ext/providers预定义 provider0.5.0-beta.8、xsai-transformers/*^0.1.0transformers.js 后端。参考文档本身不涵盖这些扩展包但它们印证了 xsAI 的边界核心包保持 OpenAI 兼容的最小面平台特定能力以xsai-*/扩展包形式外挂。导入建议三条规则与 AIRI 中的对应实践参考文档的 Import advice 部分给出三条建议逐条对应到仓库事实“如果用户明确在意体积从细粒度包导入。”AIRI 全部 30 处xsai/*导入都来自细粒度包没有一处import ... from xsai。例如语音模块只取所需的一个函数// packages/stage-ui/src/stores/modules/speech.ts#L9 import { generateSpeech } from xsai/generate-speech这样打包器只会把generateSpeech所在的模块图拉进 bundle伞包中其余 9 个功能的代码不会进入产物。“如果用户在写文档示例或希望只依赖一个包xsai是可接受的。”这是对伞包的定位面向示例、教程与轻量项目xsai提供更简洁的单一导入面。AIRI 主仓库因为追求体积与边界清晰没有采用它但该豁免条件真实存在不要把它视为错误用法。“编辑既有代码库时遵循仓库已使用的包风格除非有充分理由改变。”这条在 AIRI 里体现为风格一致性工具定义统一从xsai/tool导入且按场景选择tool()与rawTool()// packages/stage-ui/src/tools/debug.ts#L1 import { tool } from xsai/tool // packages/stage-ui/src/tools/web-search.ts#L3 import { rawTool } from xsai/tool // packages/core-agent/src/agents/spark-notify/tools.ts#L7 import { rawTool } from xsai/tool从 SKILL.md 的 API selection rules 可以推断出两者的分工tool()面向 Zod、Valibot 这类 Standard Schema 库rawTool()面向已有原始 JSON Schema 的场景直接传裸Tool对象仅在仓库已使用该形状时采用。AIRI 中既有tool()如 mcp.ts也有rawTool()并存正是“遵循既有形状”规则的落地。源码实证每个细粒度包在 AIRI 里被如何使用以下摘录均出自仓库源码可直接点击路径继续深入用于印证上表的选型逻辑xsai/stream-text流式对话主干。packages/core-agent/src/runtime/llm-service.ts 同时导入stepCountAtLeast来自xsai/shared-chat与streamText把 xsAI 的流事件text.delta、reasoning.delta、tool-call.done、tool-result.done等映射为 AIRI 内部的StreamEvent契约。源码注释还提到stopWhen控制带显式停止谓词的工具循环——这是流式包选型时容易被忽略的配套能力。xsai/generate-speechTTS 入口。packages/stage-ui/src/stores/modules/speech.ts 的 Pinia store 只依赖generateSpeech一个函数其余能力由 AIRI 自己的 provider 层补齐。xsai/stream-transcription流式转写类型。packages/stage-ui/src/libs/providers/stream-transcription/index.ts 基于StreamTranscriptionDelta、StreamTranscriptionResult类型扩展出 AIRI 的“可替换快照”事件transcript.text.snapshot并用自实现的 SSE 解析器归一化音频块。这说明选包选的是类型契约 运行时原语上层协议仍由工程自行编排。xsai/embed嵌入能力。packages/stage-ui/src/components/scenes/Stage.vue 直接引用xsai/embed配合 catalog 中登记的xsai-transformers/embed提供本地嵌入后端。xsai/generate-text/xsai/model文本生成与模型列表查询分别散见于各 provider 与设置模块如 packages/stage-ui/src/stores/ai/chat-llm/llm.ts 的listModels引用面最广对应“最常用功能配最小包”的选型结果。定位边界OpenAI 兼容优先而非通用 provider 抽象层参考文档末尾的 Positioning reminder 只有一句但约束力很强xsAI 是有意为之的 OpenAI-compatible-firstOpenAI 兼容优先不要把 xsAI 当作通用 provider 抽象层来推荐。这与 SKILL.md 中“不适用场景”完全一致当任务需要超出 OpenAI 兼容面的 provider 抽象、需要“全家桶”式 AI 应用框架、或依赖未通过 OpenAI 兼容接口暴露的 provider 专有 API 时不应选择 xsAI。AIRI 的做法也印证了这一点它需要多 provider 管理时引入的是xsai-ext/providers这类显式扩展包见 packages/core-agent/package.json而不是期待核心包提供万能抽象。对读者而言这条边界直接影响选型决策如果你的目标 API 是 OpenAI 兼容端点含大量自托管网关按本文前述规则选最小包即可如果不是xsAI 包家族就不在候选集内选型讨论应另起。选型自检清单综合参考文档与仓库实践在 AIRI 或同类工程中做包决策时可按以下顺序自检目标 API 是否 OpenAI 兼容否 → 停止xsAI 不适用。需要几种能力只有一种 → 选对应最小功能包对照“逐包推荐”表。同时需要多种能力且希望单一导入面→ 可评估伞包xsai若体积敏感仍应保持细粒度包。是既有代码库吗→ 沿用仓库现有导入风格AIRI 全仓为细粒度包 pnpm catalog 统一版本不轻易切换。需要工具调用→xsai/tool下的tool()Standard Schema 库或rawTool()原始 JSON Schema。多包并存时是否用 catalog/lockfile 统一版本AIRI 的答案见 pnpm-workspace.yaml。按此清单执行既能继承参考文档的选型骨架也能保证与 AIRI 仓库当前 0.5.0-beta.8 版本线下的真实依赖结构一致。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考