@easbot/llm weekly downloads statistics

@easbot/llm

English | 中文

@easbot/llm 是 EASBot 生态系统的 AI 模型聚合层，负责多厂商 SDK 的动态加载、模型路由、配置管理与高层 Model Provider 的能力封装。给业务包（agent / codebase / memory / note / skills / gateway）提供统一的 LLM 调用抽象，避免每个工具包重复实现 provider 路由、auth 管理和错误归一化。

版本

v0.3.29

当前状态（V4 重构后）

本包已从 @easbot/types 的早期占位实现演化为承载 provider/ + model/ 两套核心模块** 的生产级 AI 网关层：

• ✅ src/provider/（7 文件）：完整的工业级 provider 抽象 • Provider 命名空间 —— 25+ 内置 SDK（OpenAI / Anthropic / Azure / Bedrock / Vertex / OpenRouter / Copilot / Ollama / 本地模型等）的动态加载器、ModelsDev catalog 合并、模型缓存、SDK 实例池化 • ProviderError 命名空间 —— APICallError 解析（含 25+ 种"上下文溢出"模式正则识别） • ProviderAuth 命名空间 —— OAuth + API key 双轨认证 • ProviderTransform 命名空间 —— 模型 variant / tool / 限制处理 • ModelsDev 命名空间 —— models.dev catalog 的 zod schema + 加载 + 远程刷新 • definition.ts —— DEFAULT_ENABLED_PROVIDERS 白名单 + CUSTOM_PROVIDER_DEFINITIONS 本地 SDK 快照 + PROVIDER_DISPLAY_NAMES 友好名映射 • sdk/copilot/ —— 自研 GitHub Copilot 兼容 SDK（chat + responses + 6 个 tool） • ✅ src/model/（4 命名空间）：高层 Model Provider • RerankProvider 命名空间 —— LLM 驱动的文档重排序（与 Memory 混合搜索权重统一） • GraphProvider 命名空间 —— 从非结构化文本提取实体关系（11 类 EntityType + 9 类 RelationType） • SummaryProvider 命名空间 —— note / memory 摘要（LLM-based） • EmbeddingProvider 命名空间 —— 文本嵌入（单文本 / 批量；走 AI SDK 标准 embed / embedMany；默认模型 easbot-local/bge-base-zh-v1.5） • ✅ src/config/（V3 新增）：独立 LLM Config 模块，仿 packages/gateway/src/config/ 模式 • LLMConfig / ProviderConfig / ProviderAuthMethod —— zod schema（独立可用，也可作为注入 Config 的实现来源） • Config namespace —— get() / provider(id)（优先走注入，降级到本地 loader） • ✅ src/interfaces.ts（V3 新增 / V4 精简）：Adapter Registry + Env / Flag namespace • 4 个 Provider 接口（IConfigProvider / IInstanceProvider / IGlobalPathProvider / IInstallationProvider；Auth 已下沉到 @easbot/utils.Auth） • setAdapterRegistry(...) —— agent 包启动时一次注入，完全解耦本包对 agent 内部模块的所有依赖 • getIProvider() 便捷访问器 —— 未注入时 fail-fast 抛错（不静默退化） • readEnvString / readFlagBool / readFlagNumber —— 静态读取，避免对注入的依赖 • Env / Flag namespace —— 镜像 process.env 的静态字面（用于 IDE 提示 / 文档生成 / 配置检查） • ✅ src/index.ts —— 聚合导出入口（4 provider 命名空间 + 3 model 命名空间 + 自研 Copilot SDK + 3 常量 + Config / interfaces 接入点 + AdapterRegistry + 4 Provider 接口）

核心特性

• 25+ 内置 AI SDK 动态加载：按需 import，避免打包产物膨胀 • 三层数据源融合：models.dev 远程 catalog + 构建时 snapshot + 本地 CUSTOM_PROVIDER_DEFINITIONS（用于 ollama / easbot-local 这类不出现在 models.dev 的本仓自研 SDK） • 统一 Provider 命名空间：Provider.list() / getModel() / parseModel() 一行调用，与具体 SDK 解耦 • OAuth + API key 双轨：ProviderAuth namespace 管理 OAuth flow / API key 持久化 / 注入到 SDK options • Context Overflow 自动识别：跨厂商统一的"上下文超限"语义（25+ 正则模式 + 4 种 HTTP status 兜底） • 自研 GitHub Copilot 兼容 SDK：完整实现 chat + responses API + 6 个 tool（code-interpreter / file-search / web-search / image-generation / local-shell / web-search-preview） • 持久化模型缓存：构建时生成 models-snapshot.ts，运行时优先用本地，避免冷启动连网 • 极简聚合导出：@easbot/llm 一行引入 5+3 个命名空间 + 自研 SDK + 关键常量

安装

快速上手

1. 列出所有已配置的 provider

2. 获取特定模型（按 provider/model 字符串路由）

3. 解析模型 ID（安全拆分，不抛错）

4. 解析 API 错误（含 context overflow 识别）

5. 高层 Model Provider 直接调用

v0.8 行为契约（packages/llm/src/model/graph.ts）：

• 所有 chunks 都被尝试抽取：chunks 数组按 prompt.maxChunks（默认 5）切片成多组，每组调一次 LLM；不再像 v0.7 那样硬截断到前 5 个 chunk。 • chunk 级 3 并发：多组用轻量级 semaphore 并发跑（prompt.maxConcurrency，默认 3），避免触发 provider 限流。 • 局部失败容错：单组 LLM 失败 → 仅丢该组结果，其他组继续。不会因一次失败让整个文档 KG 留空。 • 边界感知截断：超长 chunk 走 splitByBoundary 进一步切分（按 \n\n / \n / 空白找最近边界），保证 entity name 不被切碎。

1. 文本嵌入（EmbeddingProvider）

2. 使用自研 GitHub Copilot SDK

顶层导出清单

EmbeddingProvider 公开契约（packages/llm/src/model/embedding.ts）：

• embedText(input, abortSignal?) → Promise • EmbedOutput = { embedding: number[]; usage: { tokens: number } } • 空 value 返回 { embedding: [], usage: { tokens: 0 } }，不调用 ai.embed • embedTexts(inputs, abortSignal?) → Promise • EmbedBatchOutput = { embeddings: number[][]; usage: { tokens: number } } • 空 values 返回 { embeddings: [], usage: { tokens: 0 } }，不调用 ai.embedMany • 默认模型：easbot-local/bge-base-zh-v1.5（导出常量 EmbeddingProvider.DEFAULT_MODEL） • model 入参支持三种形态：省略 → Provider.defaultModel 链路；Provider.Model → Provider.getEmbedding；直接传 EmbeddingModel 实例（duck-type 由 specificationVersion 字段判定）→ 跳过 Provider 链路

配置注入（切换 LLM 实现的迁移指南）

V4 重构后,Provider / ModelsDev / ProviderAuth / ProviderTransform 命名空间已通过 Adapter Registry 模式与 agent 包完全解耦,不再直接 import agent 包的任何模块。所有运行时依赖都通过 4 个 Provider 接口显式注入（Auth 已下沉到 @easbot/utils.Auth）。

1. Adapter Registry 总览

agent 包启动时调用一次 setAdapterRegistry(...),注入 4 个 Provider 实现:

未注入时,所有 getIProvider() 会 fail-fast 抛错:

设计意图:不静默退化。若忘注入就抛错,避免线上"undefined config"导致模型路由静默失效。

1. 4 个 Provider 接口契约

| 接口 | 方法 | 原 agent 模块 | 用途 |

| IConfigProvider | get(): Promise / provider(id): Promise | Config | 用户 ~/.config/easbot/config.json 的 llm 块(whitelist / blacklist / variant override) | | IInstanceProvider | getDirectory(): string / getWorktree(): string | Instance | 实例路径与 worktree 信息 | | IGlobalPathProvider | cache: string / data: string / config: string | Global.Path | 模型快照缓存目录 / 用户数据目录 / 全局配置目录 | | IInstallationProvider | getVersion(): string | Installation | User-Agent / 兼容性检查 / 版本信息 |

V4 变更:IInstanceProvider.state(init) 与 IPluginProvider 已被拆分下沉（ADR 0071）。

• Provider 内部 state 缓存改用 @easbot/utils.lazyAsync(init)（per-process 单例 + 显式 reset） - Plugin 注册通过模块级 _pluginAuthRegistry: Map + ProviderAuth.registerPluginAuthProvider() 入口注入

1. LLM Config(独立工作 + 集成工作)

V3 新增 src/config/ 模块,仿 packages/gateway/src/config/ 模式:

• 独立工作:从 easbot.json / easbot.jsonc 直接读 llm 字段(模型、provider、auth 等) • 集成工作:当 AdapterRegistry 已注入时,Config.get() 优先走注入的实现(让 agent 包能复用)

1. Env / Flag namespace(镜像 process.env)

Flag namespace 与读取函数 (readEnvString / readFlagBool) 仍由 llm 包提供；Env 已下沉到 @easbot/utils，llm 仅透传 re-export，调用方也可直接 import @easbot/utils 的 Env:

1. 调用点改造对照表

| 模块 | V3 之前 | V3 | V4(本次重构) |…