@easbot/llm 0.3.19

package/README.md

@@ -0,0 +1,420 @@
+# @easbot/llm
+
+[English](./README.en.md) | 中文
+
+`@easbot/llm` 是 EASBot 生态系统的 **AI 模型聚合层**，负责多厂商 SDK 的动态加载、模型路由、配置管理与高层 Model Provider 的能力封装。给业务包（agent / codebase / memory / note / skills / gateway）提供统一的 LLM 调用抽象，避免每个工具包重复实现 provider 路由、auth 管理和错误归一化。
+
+## 当前状态（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 内部模块的所有依赖
+  - `getI<X>Provider()` 便捷访问器 —— 未注入时 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 + 关键常量
+
+## 安装
+
+```bash
+pnpm add @easbot/llm
+```
+
+## 快速上手
+
+### 1. 列出所有已配置的 provider
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const allProviders = await Provider.list();
+// { openai: { id, name, source, env, models, ... }, anthropic: {...}, ... }
+```
+
+### 2. 获取特定模型（按 `provider/model` 字符串路由）
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const gpt4 = await Provider.getModel('openai/gpt-4');
+// gpt4: LanguageModelV3（AI SDK v6 规范）
+
+const embed = await Provider.getModel('openai/text-embedding-3-small');
+// embed: EmbeddingModelV3
+
+const rerank = await Provider.getModel('easbot-local/rerank-proxy');
+// rerank: RerankingModelV3
+```
+
+### 3. 解析模型 ID（安全拆分，不抛错）
+
+```typescript
+import { Provider } from '@easbot/llm';
+
+const { providerId, modelId } = Provider.parseModel('openai/gpt-4o');
+// { providerId: 'openai', modelId: 'gpt-4o' }
+```
+
+### 4. 解析 API 错误（含 context overflow 识别）
+
+```typescript
+import { ProviderError, APICallError } from 'ai';
+
+try {
+  await someProvider.doCall(...);
+} catch (e) {
+  if (e instanceof APICallError) {
+    const parsed = ProviderError.parseAPICallError({ providerId: 'openai', error: e });
+    if (parsed.type === 'context_overflow') {
+      // UI: "上下文超限，请缩短输入或切换模型"
+    }
+  }
+}
+```
+
+### 5. 高层 Model Provider 直接调用
+
+```typescript
+import { RerankProvider, GraphProvider, SummaryProvider } from '@easbot/llm';
+
+// 文档重排序
+const reranked = await RerankProvider.rerank({
+  query: '...',
+  documents: ['...', '...'],
+});
+
+// 图谱实体提取
+const graph = await GraphProvider.generateGraph({
+  chunks: ['chunk1...', 'chunk2...', '...'],  // 任意长度数组
+  prompt: { maxChunks: 5, maxConcurrency: 3 }, // v0.8：per-call 切片 + 3 并发
+});
+// graph.entities / relations / summary 直接入库
+```
+
+**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 不被切碎。
+
+```typescript
+// Note 知识库摘要
+const summary = await SummaryProvider.summarizeNote({
+  query: '...',
+  chunks: [...],
+});
+```
+
+### 6. 文本嵌入（EmbeddingProvider）
+
+```typescript
+import { EmbeddingProvider } from '@easbot/llm';
+
+// 单文本嵌入 — 返回 EmbedOutput（含 embedding + usage.tokens）
+const single = await EmbeddingProvider.embedText({ value: '一段中文文本' });
+// single.embedding: number[]（默认 bge-base-zh-v1.5 输出 512 维）
+// single.usage.tokens: number
+
+// 批量嵌入（推荐：单次 API 调用比 N 次 aiEmbed 更高效）
+const batch = await EmbeddingProvider.embedTexts({ values: ['a', 'b', 'c'] });
+// batch.embeddings: number[][]（与 values 一一对应）
+// batch.usage.tokens: number
+
+// 显式指定模型（跳过 Provider.defaultModel）
+import { Provider } from '@easbot/llm';
+const customModel = Provider.parseModel('openai/text-embedding-3-small');
+const r = await EmbeddingProvider.embedText({ value: 'hi', model: customModel });
+```
+
+### 7. 使用自研 GitHub Copilot SDK
+
+```typescript
+import { createOpenaiCompatible, openaiCompatible } from '@easbot/llm';
+
+const copilot = createOpenaiCompatible({
+  apiKey: process.env.GITHUB_TOKEN,
+});
+const model = copilot('gpt-4o');
+// 或使用默认实例
+const model2 = openaiCompatible('gpt-4o');
+```
+
+## 顶层导出清单
+
+```typescript
+// Provider 核心命名空间
+export * as Provider from './provider/provider';
+export * as ProviderError from './provider/error';
+export * as ProviderAuth from './provider/auth';
+export * as ProviderTransform from './provider/transform';
+export * as ModelsDev from './provider/models';
+
+// Provider 常量
+export {
+  DEFAULT_ENABLED_PROVIDERS,
+  CUSTOM_PROVIDER_DEFINITIONS,
+  PROVIDER_DISPLAY_NAMES,
+} from './provider/definition';
+
+// 顶层函数
+export { initModelsRefresh } from './provider/models';
+
+// 自研 GitHub Copilot SDK
+export {
+  createOpenaiCompatible,
+  openaiCompatible,
+} from './provider/sdk/copilot';
+export type {
+  OpenaiCompatibleProvider,
+  OpenaiCompatibleProviderSettings,
+  OpenaiCompatibleModelId,
+} from './provider/sdk/copilot';
+
+// 高层 Model Provider 命名空间
+export * as RerankProvider from './model/rerank';
+export * as GraphProvider from './model/graph';
+export * as SummaryProvider from './model/summary';
+export * as EmbeddingProvider from './model/embedding';
+```
+
+**EmbeddingProvider 公开契约**（`packages/llm/src/model/embedding.ts`）：
+
+- `embedText(input, abortSignal?) → Promise<EmbedOutput>`
+  - `EmbedOutput = { embedding: number[]; usage: { tokens: number } }`
+  - 空 `value` 返回 `{ embedding: [], usage: { tokens: 0 } }`，**不**调用 `ai.embed`
+- `embedTexts(inputs, abortSignal?) → Promise<EmbedBatchOutput>`
+  - `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 实现:
+
+```typescript
+import {
+  setAdapterRegistry,
+  type AdapterRegistry,
+} from '@easbot/llm';
+
+// 在 agent 包启动入口处(例如 Instance.provide 之前)
+setAdapterRegistry({
+  config: Config,                // IConfigProvider       — get / provider
+  instance: Instance,            // IInstanceProvider     — getDirectory / getWorktree
+  global: Global.Path,           // IGlobalPathProvider   — cache / data / config
+  installation: Installation,    // IInstallationProvider — getVersion
+  // V4 起 Auth 已下沉到 `@easbot/utils.Auth`，不再通过 AdapterRegistry 注入。
+  // LLM 包内部直接 `import { Auth } from '@easbot/utils'` 调用即可。
+} satisfies AdapterRegistry);
+```
+
+**未注入时,所有 `getI<X>Provider()` 会 fail-fast 抛错**:
+
+```
+[LLM] adapter 'config' (IConfigProvider) not registered.
+Call setAdapterRegistry({ config: ... }) before using LLM.
+```
+
+> 设计意图:**不静默退化**。若忘注入就抛错,避免线上"undefined config"导致模型路由静默失效。
+
+### 2. 4 个 Provider 接口契约
+
+| 接口 | 方法 | 原 agent 模块 | 用途 |
+|------|------|---------------|------|
+| `IConfigProvider` | `get<T>(): Promise<T>` / `provider<T>(id): Promise<T \| undefined>` | `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<providerId, methods[]>` + `ProviderAuth.registerPluginAuthProvider()` 入口注入
+
+### 3. LLM Config(独立工作 + 集成工作)
+
+V3 新增 `src/config/` 模块,仿 `packages/gateway/src/config/` 模式:
+
+- **独立工作**:从 `easbot.json` / `easbot.jsonc` 直接读 `llm` 字段(模型、provider、auth 等)
+- **集成工作**:当 AdapterRegistry 已注入时,`Config.get()` 优先走注入的实现(让 agent 包能复用)
+
+```typescript
+import { Config, LLMConfig } from '@easbot/llm';
+
+const cfg = await Config.get();           // 走注入或 fallback loader
+const openaiCfg = await Config.provider('openai');
+
+// Schema 校验(可单独使用)
+const parsed = LLMConfig.parse({
+  model: 'openai/gpt-4o',
+  provider: {
+    openai: {
+      npm: '@ai-sdk/openai',
+      options: { apiKey: 'sk-...' },
+    },
+  },
+});
+```
+
+### 4. Env / Flag namespace(镜像 process.env)
+
+`Flag` namespace 与读取函数 (`readEnvString` / `readFlagBool`) 仍由 llm 包提供；`Env` 已下沉到 `@easbot/utils`，llm 仅透传 re-export，调用方也可直接 import `@easbot/utils` 的 `Env`:
+
+```typescript
+import { Flag, readEnvString, readFlagBool } from '@easbot/llm';
+import { Env } from '@easbot/llm';        // 等价于 import { Env } from '@easbot/utils'
+
+Flag.EASBOT_OUTPUT_TOKEN_MAX;       // 数值字段,内部动态计算
+readEnvString('OPENAI_API_KEY');    // 包装 process.env
+```
+
+### 5. 调用点改造对照表
+
+| 模块 | V3 之前 | V3 | V4(本次重构) |
+|------|--------|----|----------------|
+| `provider/auth.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(init)` + `_pluginAuthRegistry` 模块级 list |
+| `provider/auth.ts` | `Auth.set(providerId, info)` | `Auth.set(...)` 直接调用 `@easbot/utils.Auth`(下沉到 utils) | `Auth.set(...)` 直接调用 `@easbot/utils.Auth`(下沉到 utils) |
+| `provider/auth.ts` | `Plugin.definitions()` | `getIPluginProvider().definitions()` | 删除依赖,改用 `registerPluginAuthProvider()` 入口注入 |
+| `provider/provider.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(createState)`(模块级 per-process 单例) |
+| `config/loader.ts` | `Instance.state(...)` | `getIInstanceProvider().state(init)` | `lazyAsync(createState)`(模块级 per-process 单例) |
+| `provider/models.ts` | `Global.Path.cache` | `getIGlobalPathProvider().cache` | (同 V3) |
+| `config/index.ts` | `Config.get()` | `getIConfigProvider().get()` | (同 V3) |
+
+**V4 重构动机**:`IInstanceProvider.state(init)` 把 "缓存" 与 "Instance 抽象" 耦合在一起,
+但 state 缓存本质上是 **per-process 单例 + 显式 reset**,与 Instance.directory 无关。
+下层到 `@easbot/utils.lazyAsync()` 后:
+- **解耦**:`IInstanceProvider` 只剩 2 个方法(getDirectory / getWorktree),职责清晰
+- **统一**:Project 所有需要 state 缓存的子系统(skills / mcp / plugin 等)复用同一工具
+- **可测**:`lazyAsync().reset()` 比 mock 一个 state factory 更直接
+
+### 6. 架构优势
+
+- **零硬编码依赖**:`provider/*` 与 `model/*` 文件不直接 `import` agent 包的任何模块
+- **测试友好**:测试用例用 mock AdapterRegistry 注入,无需启动 agent 实例(`tests/setup.ts` 已提供完整 mock 范例)
+- **多入口复用**:同一套 LLM 实现可被 web / cli / gateway / monitor 等任何进程复用,只需各自注入 AdapterRegistry
+- **契约清晰**:与 ADR 0044 (skills) / 0045 (mcp) / 0046 (plugin) 的 AdapterRegistry 模式完全一致
+- **fail-fast 安全**:未注入立即抛错,避免线上静默退化
+
+## Provider 路由优先级
+
+`Provider` 在 `createState` 时按以下顺序合并 provider 注册表：
+
+1. **models.dev 远程 catalog**：启动时若 `Flag.EASBOT_MODELS_FETCH` 开启，从 `https://models.dev/api.json` 拉取（带本地缓存）
+2. **构建时 snapshot**：若远程拉取失败或缓存不存在，使用 `models-snapshot.ts`（构建时静态注入）
+3. **CUSTOM_PROVIDER_DEFINITIONS**：本仓自研 SDK（`@easbot/ollama-sdk` / `@easbot/local-model-sdk`）的本地定义快照
+4. **config.provider**：用户 `~/.config/easbot/config.json` 中的 provider 块覆盖（如自定义 baseURL / model options）
+5. **环境变量 + Auth 持久化**：env vars + `easbot auth login` 持久化的 API key
+6. **Plugin 注入**：插件可通过 `plugin.auth.loader` 注入特殊 provider（如 github-copilot 的 OAuth）
+7. **CUSTOM_LOADERS**：每个 provider 的特殊初始化（anthropic headers、azure baseURL、amazon-bedrock AWS credentials 等）
+
+## 测试
+
+```bash
+pnpm --filter @easbot/llm test:run
+```
+
+测试文件位于 `tests/`：
+
+- `provider-smoke.test.ts` —— 验证 `definition.ts` 的纯常量（白名单 / 本地 SDK 快照 / 友好名映射）+ **AdapterRegistry 注入/读取/fail-fast 抛错** + Env/Flag 静态字段 + LLMConfig/ProviderConfig/ProviderAuthMethod zod schema
+- `interfaces.test.ts` —— V4 后新增 AdapterRegistry 接口 5 个 + 静态读取函数（`readEnvString` / `readFlagBool` / `readFlagNumber`）+ `lazyAsync()` reset 行为
+- `model-smoke.test.ts` —— 验证 `model/types.ts` 的类型导出路径稳定性
+- `setup.ts` —— 全局测试环境（设 NODE_ENV=development + **注入 mock AdapterRegistry 全套**,避免 chain import 触发 fail-fast）
+
+**当前 75 个测试全绿**（3 test files）。覆盖范围:
+
+| 测试大类 | 覆盖 case 数 | 验证要点 |
+|---------|-------------|----------|
+| AdapterRegistry 接口（V4 新增） | 11 | 4 Provider 接口契约 / `setAdapterRegistry` 注入 / `hasAdapterRegistry` 布尔 / fail-fast 抛错 / 静态读取函数 |
+| Provider 常量纯函数 | 11 | DEFAULT_ENABLED_PROVIDERS / CUSTOM_PROVIDER_DEFINITIONS / PROVIDER_DISPLAY_NAMES |
+| ProviderAuth lazyAsync 行为（V4 新增） | 3 | `registerPluginAuthProvider` 触发 `_state.reset()` / `clearPluginAuthProviders` 重置缓存 / `ProviderAuth.resetState()` 清空缓存 |
+| 模型类型导出稳定性 | 6 | RerankInput/Result/Response + Entity/Relation/GraphInput + Note/MemorySummary |
+| Env / Flag namespace 静态字段 | 6 | Env 镜像 process.env / Flag 包含 LLM 包内部 flag / 读取函数签名（空字符串 vs undefined） |
+| LLMConfig schema | 4 | 空对象通过 / 完整字段通过 / 非法 model 拒绝 / 非数组 enabled_providers 拒绝 |
+| ProviderConfig schema | 3 | 最小 config 通过 / partial 设计(所有字段可选) / options.apiKey 类型校验 |
+| ProviderAuthMethod schema | 4 | api / oauth 类型通过 / 非法 type 拒绝 / 缺 label 拒绝 |
+
+**完整集成测试边界**:AdapterRegistry 解耦后,llm 包可独立 mock 全部 4 个 Provider,完整跑 `Provider.list / getModel / parseModel` 的端到端流程不依赖 agent 包。后续任务:在 agent 包切换 LLM 实现时,补跨包集成测试(验证 setAdapterRegistry 真实注入的 Provider 与 llm 包契约匹配)。
+
+## 开发命令
+
+```bash
+# 构建（tsup，输出 ESM + CJS + DTS）
+pnpm --filter @easbot/llm build
+
+# 监听模式构建
+pnpm --filter @easbot/llm dev
+
+# 重新生成 models.dev snapshot（需联网）
+pnpm --filter @easbot/llm build:snapshot
+
+# 类型检查
+pnpm --filter @easbot/llm type-check
+
+# Lint（biome）
+pnpm --filter @easbot/llm lint
+
+# Lint fix
+pnpm --filter @easbot/llm lint:fix
+
+# 单测
+pnpm --filter @easbot/llm test:run
+```
+
+## 设计原则
+
+1. **Provider namespace 是唯一入口**：业务代码不应直接 import `@ai-sdk/openai` 等具体 SDK，统一通过 `Provider.getModel('openai/gpt-4')` 取模型
+2. **配置 vs 注入分离**：`Config`（持久化配置）和 `Env/Auth/Plugin`（运行时注入）互不混用
+3. **错误归一化**：`ProviderError.parseAPICallError` 把 25+ 厂商的不同错误格式统一成 `context_overflow | api_error` 二分类
+4. **本地 SDK 优先于远程**：本仓自研 SDK（ollama / easbot-local）不出现在 models.dev，因此用 `CUSTOM_PROVIDER_DEFINITIONS` 静态注入，避免远程 catalog 漂移
+5. **懒加载 SDK**：每个 provider 的 `BUNDLED_PROVIDERS[].loader()` 是 `() => import('@ai-sdk/openai')` 形式的动态 import，业务代码不引用某 provider 时不下载其 SDK
+
+## 与历史版本的差异
+
+| 版本 | 关键差异 |
+|------|----------|
+| **早期占位（@easbot/types 残留）** | 仅 5 行注释的 index.ts，无业务能力 |
+| **V3（ADR 0070）** | 新增 `src/interfaces.ts`（6 Provider 接口 + AdapterRegistry）+ `src/config/` 三文件模块；重构 provider/{auth,models,provider,transform}.ts 全部走 AdapterRegistry |
+| **V4（ADR 0071）** | 删除 `IInstanceProvider.state()`（下沉到 `@easbot/utils.lazyAsync()`）+ 删除 `IPluginProvider` 依赖（改用模块级 `_pluginAuthRegistry` + `ProviderAuth.registerPluginAuthProvider()` 入口）；Provider 接口 6→5 个 |
+
+**V3 → V4 重构动机**：
+- `IInstanceProvider.state()` 把"per-process 单例 + 显式 reset"与 `Instance.directory` 抽象耦合在一起，但 state 缓存与 Instance 路径无关
+- 缓存下沉到 `@easbot/utils.lazyAsync()` 后，`IInstanceProvider` 收缩为 2 个方法（`getDirectory` / `getWorktree`），职责清晰
+- `ProviderAuth` 不再依赖 `IPluginProvider`，改用模块级 list + 注册入口，概念清晰化（plugin 注册 = 推入 list）
+
+详见：
+- [ADR 0070 llm-adapter-registry](../../docs/decisions/0070-llm-adapter-registry.md) —— AdapterRegistry 注入模式
+- [ADR 0071 llm-instance-state-decompose](../../docs/decisions/0071-llm-instance-state-decompose.md) —— state 拆分下沉

package/dist/assets/txt/model/graph-summary.txt

@@ -0,0 +1,54 @@
+# Knowledge Graph Summary Prompt
+
+## Task
+Generate ONE combined summary from MULTIPLE knowledge graph entities.
+
+**CRITICAL RULES:**
+- NEVER generate relationships not present in the input
+- NEVER invent connections or attributes
+- NEVER elaborate beyond provided information
+- NEVER guess entity properties
+- If input has no valuable information: ONLY output "No relevant knowledge found."
+
+## Input Format
+```
+[Entity 1]
+Entity: {entity1}
+Type: {entity_type1}
+Description: {description1}
+Related Entities: {related_entities1}
+Relation Types: {relation_types1}
+
+[Entity 2]
+Entity: {entity2}
+...
+```
+
+## Output Format
+**Length: 1-3 entities maximum**
+- Lead with most relevant entities
+- Group information clearly
+- Cite source as "Knowledge Graph"
+
+```markdown
+## [Entity Name] (Priority: {priority})
+**Type:** {entity_type}
+**Source:** Knowledge Graph
+**Description:** ...
+**Related Entities:**
+  → [{relation}] → {target_entity}
+```
+
+## Fixed Response
+If entities are irrelevant or insufficient:
+```
+No relevant knowledge found.
+```
+**DO NOT generate any other content.**
+
+## Rules
+- Output ONE combined summary only
+- Never separate summaries per entity
+- Never invent attributes or relationships
+- Never exceed provided information
+- If uncertain: "No relevant knowledge found."

package/dist/assets/txt/model/knowledge-summary.txt

@@ -0,0 +1,81 @@
+# Knowledge Summary Prompt
+
+## Task
+Synthesize document chunks into a concise summary relevant to the query.
+
+**CRITICAL RULES:**
+- NEVER generate content not present in the input
+- NEVER invent relationships or connections
+- NEVER elaborate beyond provided information
+- NEVER guess or assume user needs
+- If input has no valuable information: ONLY output "No relevant knowledge found."
+
+## Priority Score
+Priority = 0.6 × relevance + 0.4 × recency
+- Priority > 0.6: high-priority (include)
+- Priority < 0.3: low-priority (skip unless unique value)
+
+## Input Format
+[Chunk N] Priority: {priority}
+Source: [{filename}](./{filename}#{startLine}-{endLine})
+{content}
+Graph Nodes:
+  Node: {name} ({type}) | {properties}
+    → [{relation}] → target={targetType}:{targetName}
+
+## Output Format
+
+### Content Summary (REQUIRED)
+**Length: 1-3 sentences maximum**
+- Lead with highest-priority chunks ONLY
+- Skip chunks Priority < 0.3
+- Include lower-priority chunks only if they add unique value
+- Cite sources: [{filename}](./{filename}#{startLine})
+
+### Entity & Relation Map (CONDITIONAL)
+Only include if:
+1. Graph nodes are present AND
+2. They add meaningful connections not in Content Summary
+
+Format:
+**{EntityName}** ({type})
+  → [{relation}] → {TargetEntity} ({targetType})
+
+### Key Insights (CONDITIONAL)
+Only include if:
+1. Notable patterns exist AND
+2. They are NOT already covered in Content Summary
+
+Format:
+- 1-2 bullets maximum
+
+## Fixed Response
+If no chunks have Priority > 0.3 or all chunks are irrelevant:
+```
+No relevant knowledge found.
+```
+**DO NOT generate any other content.**
+
+## Examples
+
+### Good Output (relevant chunks)
+```
+The codebase uses React for frontend (Priority: 0.78).
+Source: [frontend/index.tsx](./frontend/index.tsx#L10-L50)
+```
+
+### Bad Output (NEVER generate)
+```
+Hello! Based on the documents, I can help you with React setup.
+The project structure follows a standard pattern.
+You should use TypeScript for type safety.
+```
+(These weren't in the input!)
+
+## Strict Rules
+- Output ONLY content from input chunks
+- Skip all sections with no data
+- Maximum 3 sentences in Content Summary
+- NEVER exceed provided information
+- Cite sources when including facts
+- If uncertain: "No relevant knowledge found."

package/dist/assets/txt/model/memory-summary.txt

@@ -0,0 +1,80 @@
+# Memory Summary Prompt
+
+## Task
+Synthesize memory facts into a concise summary relevant to the query.
+
+**CRITICAL RULES:**
+- NEVER generate facts not present in the input
+- NEVER invent content or relationships
+- NEVER elaborate beyond provided information
+- NEVER guess or assume user intent
+- If input has no valuable information: ONLY output "No relevant memory found."
+
+## Priority Score
+Priority = 0.4 × relevance + 0.3 × recency + 0.3 × importance
+- Priority > 0.6: high-priority (include)
+- Priority < 0.3: low-priority (skip unless unique value)
+
+## Input Format
+[Fact N] Priority: {priority}
+Category: {category} | Importance: {importance} | Source: {source}
+{content}
+Graph Nodes:
+  Node: {name} ({type})
+    → [{relation}] → target={targetType}:{targetName}
+
+## Output Format
+
+### Content Summary (REQUIRED)
+**Length: 1-3 sentences maximum**
+- Lead with highest-priority facts ONLY
+- Skip facts Priority < 0.3
+- Include low-priority facts only if they add unique value not in high-priority facts
+- State contradictions clearly: "High-priority fact X contradicts low-priority fact Y. Current truth: X."
+
+### Entity & Relation Map (CONDITIONAL)
+Only include if:
+1. Graph nodes are present AND
+2. They add meaningful connections not in Content Summary
+
+Format:
+**{EntityName}** ({type})
+  → [{relation}] → {TargetEntity} ({targetType})
+
+### Key Insights (CONDITIONAL)
+Only include if:
+1. Meaningful patterns exist AND
+2. They are NOT already covered in Content Summary
+
+Format:
+- 1-2 bullets maximum
+
+## Fixed Response
+If no facts have Priority > 0.3 or all facts are irrelevant:
+```
+No relevant memory found.
+```
+**DO NOT generate any other content.**
+
+## Examples
+
+### Good Output (relevant facts)
+```
+The user prefers dark mode (Priority: 0.72).
+High-priority fact contradicts earlier light mode preference.
+```
+
+### Bad Output (NEVER generate)
+```
+Hello! I can help you with dark mode settings.
+The user's name is John and they work at Company X.
+They like TypeScript and use VSCode daily.
+```
+(These facts weren't in the input!)
+
+## Strict Rules
+- Output ONLY facts from input
+- Skip all sections with no data
+- Maximum 3 sentences in Content Summary
+- NEVER exceed provided information
+- If uncertain: "No relevant memory found."