unified-llm-provider 0.1.0

package/README.md

@@ -0,0 +1,463 @@
+# unified-llm-provider
+
+统一 LLM 接口 npm 包。
+
+它的目标不是让用户自己处理各家格式差异，而是：
+
+- 你可以只维护一种输入/输出格式
+- 你可以显式指定要把请求体**转成什么格式**
+- `thoughtSignature` / `thoughtSignatures` 会跟着请求体格式一起处理
+- 不需要单独再指定“签名格式类型”
+
+---
+
+## 当前内置支持
+
+- `unified`：包的统一格式（推荐用户长期维护这个）
+- `gemini`
+- `claude`
+- `openai-compatible`
+- `openai-responses`
+- `deepseek`（wire format 视为 `openai-compatible`）
+
+---
+
+## 设计原则
+
+### 1. 用户主要关心的是“格式 from/to”
+
+不是：
+- 我该把签名声明成 Gemini 还是 Claude？
+
+而是：
+- 我现在手里的请求体是什么格式？
+- 我要把它转成什么格式？
+
+签名会随格式转换一起处理。
+
+### 1.1 一个最重要的例子
+
+假设：
+
+- 用户维护的是 `claude` 格式历史
+- 历史里已有 `claude` 原生签名
+- 这次实际要调用的是 `gemini`
+
+那么规则是：
+
+1. `from = claude`
+2. 实际 provider = `gemini`
+3. 组装 Gemini 请求时，只找 **Gemini 可用签名**
+4. 如果当前历史里没有 `gemini:` 对应签名，就等价于 **这轮不传签名**
+5. 模型返回后，如果你要继续返回 `claude` 格式给用户，那么 `signature` 字段会写成 `gemini:xxxx`，因为这条签名实际属于 Gemini
+
+### 2. 不伪造跨 provider 原生签名
+
+### 2.1 OpenAI 系前缀现在明确拆分
+
+为了避免歧义，这个包不再把 OpenAI 系签名统称成 `openai:`。
+
+现在公开前缀建议是：
+
+- `openai-compatible:`
+- `openai-responses:`
+
+旧的 `openai:` 输入已删除。
+如果你之前使用过 `openai:`，现在必须明确改成 `openai-compatible:` 或 `openai-responses:`。
+
+
+这个包会：
+- 自动识别签名
+- 自动归一化
+- 自动带上统一前缀（在 `unified` 输出里）
+- 自动放回目标格式对应的位置
+
+但**不会**做这种错误事情：
+- 把 Gemini 原生签名“变成”Claude 原生签名
+- 把 Claude 原生签名“变成”OpenAI 原生签名
+
+也就是说：
+- Claude 签名仍然是 Claude 签名
+- OpenAI Compatible 扩展签名仍然是 `openai-compatible` 签名
+- OpenAI Responses `encrypted_content` 仍然是 `openai-responses` 签名
+- Gemini thought signature 仍然是 Gemini 签名
+
+---
+
+## `unified` 格式是什么
+
+`unified` 是这个包对外推荐的统一格式。
+
+它基于 Gemini-like message 结构，但额外兼容：
+
+- `thoughtSignature: string`
+- `thoughtSignatures: { [provider]: string }`
+
+其中 `provider` 推荐使用完整命名空间：`gemini | claude | openai-compatible | openai-responses`
+
+典型例子：
+
+```ts
+const request = {
+  contents: [
+    { role: 'user', parts: [{ text: 'hello' }] },
+    {
+      role: 'model',
+      parts: [
+        {
+          text: 'thinking...',
+          thought: true,
+          thoughtSignature: 'claude:sig_xxx',
+        },
+        { text: 'final answer' },
+      ],
+    },
+  ],
+};
+```
+
+---
+
+## 安装
+
+```bash
+npm install unified-llm-provider
+```
+
+---
+
+## 最常用的两种方式
+
+## 方式 1：直接做格式转换
+
+### `convertRequest`
+
+把一个请求体从 A 格式转成 B 格式。
+
+```ts
+import { convertRequest } from 'unified-llm-provider';
+
+const claudeRequest = convertRequest({
+  contents: [
+    { role: 'user', parts: [{ text: 'hello' }] },
+    {
+      role: 'model',
+      parts: [
+        {
+          text: 'deep thought',
+          thought: true,
+          thoughtSignature: 'claude:sig_req_1',
+        },
+      ],
+    },
+  ],
+}, {
+  from: 'unified',
+  to: 'claude',
+  model: 'claude-sonnet-4',
+});
+```
+
+这里你只指定：
+- `from: 'unified'`
+- `to: 'claude'`
+
+签名会自动跟着请求体转换到 Claude 的 `thinking.signature` 位置。
+
+---
+
+### `convertResponse`
+
+把一个响应体从 A 格式转成 B 格式。
+
+```ts
+import { convertResponse } from 'unified-llm-provider';
+
+const unifiedResponse = convertResponse({
+  content: [
+    { type: 'thinking', thinking: 'let me think', signature: 'sig_resp_1' },
+    { type: 'text', text: 'done' },
+  ],
+  stop_reason: 'end_turn',
+}, {
+  from: 'claude',
+  to: 'unified',
+});
+```
+
+输出里会自动变成：
+
+```ts
+thoughtSignature: 'claude:sig_resp_1'
+```
+
+---
+
+### `createStreamConverter`
+
+把流式 chunk / event 从一种格式转成另一种格式。
+
+```ts
+import { createStreamConverter } from 'unified-llm-provider';
+
+const converter = createStreamConverter({
+  from: 'claude',
+  to: 'unified',
+});
+
+const chunk = converter.convert({
+  type: 'content_block_delta',
+  delta: { type: 'signature_delta', signature: 'sig_stream_1' },
+});
+```
+
+---
+
+## 方式 2：直接调用 provider，但输入输出格式可自选
+
+### `provider.chat()`
+
+你可以调用一个实际 provider，但输入和输出不一定要等于它自己的原生格式。
+
+比如：
+- 实际调用的是 Claude
+- 输入给包的是 `openai-compatible`
+- 输出要回 `unified`
+
+```ts
+import { createClaudeProvider } from 'unified-llm-provider';
+
+const provider = createClaudeProvider({
+  provider: 'claude',
+  model: 'claude-sonnet-4',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const response = await provider.chat({
+  model: 'gpt-4o',
+  messages: [
+    { role: 'system', content: 'You are helpful' },
+    { role: 'user', content: 'hello' },
+  ],
+}, {
+  inputFormat: 'openai-compatible',
+  outputFormat: 'unified',
+});
+```
+
+流程会是：
+
+```text
+openai-compatible request
+  -> decode to unified canonical
+  -> encode to claude request
+  -> call Claude API
+  -> decode Claude response
+  -> encode back to unified response
+```
+
+签名也跟着这条链一起走，不用你单独声明“签名转成什么格式”。
+
+---
+
+## Router / Factory
+
+### 创建内置注册表
+
+```ts
+import { createBootstrapExtensionRegistry } from 'unified-llm-provider';
+
+const registry = createBootstrapExtensionRegistry();
+```
+
+### 通过 factory 创建 provider
+
+```ts
+import { createBootstrapExtensionRegistry, createLLMFromConfig } from 'unified-llm-provider';
+
+const registry = createBootstrapExtensionRegistry();
+const provider = createLLMFromConfig({
+  provider: 'claude',
+  model: 'claude-sonnet-4',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  endpoint: {
+    url: 'https://example.com/custom/messages',
+    headers: {
+      'x-endpoint-header': 'demo',
+    },
+  },
+  headers: {
+    'x-top-header': 'top',
+  },
+  requestBody: {
+    metadata: { source: 'my-app' },
+  },
+}, registry.llmProviders);
+```
+
+支持：
+- 自定义 `url`
+- 自定义 `streamUrl`
+- 自定义 `headers`
+- 自定义 `requestBody`
+- 自定义 `fetch`
+- 自定义超时
+
+---
+
+### 创建 router
+
+```ts
+import { createBootstrapExtensionRegistry, createLLMRouter } from 'unified-llm-provider';
+
+const registry = createBootstrapExtensionRegistry();
+
+const router = createLLMRouter({
+  defaultModelName: 'main',
+  models: [
+    {
+      modelName: 'main',
+      provider: 'gemini',
+      model: 'gemini-2.0-flash',
+      apiKey: process.env.GEMINI_API_KEY,
+    },
+    {
+      modelName: 'backup',
+      provider: 'claude',
+      model: 'claude-sonnet-4',
+      apiKey: process.env.ANTHROPIC_API_KEY,
+    },
+  ],
+}, undefined, registry.llmProviders);
+```
+
+---
+
+## thought signature 规则
+
+## 输入兼容两种写法
+
+### 字符串写法
+
+```ts
+thoughtSignature: 'claude:sig_xxx'
+```
+
+### 对象写法
+
+```ts
+thoughtSignatures: {
+  claude: 'sig_xxx'
+}
+```
+
+---
+
+## 你现在不需要再单独指定“签名格式类型”
+
+你主要只需要指定：
+
+- `from`
+- `to`
+
+或者：
+
+- `inputFormat`
+- `outputFormat`
+
+签名会跟着格式走。
+
+### 具体来说是什么意思？
+
+比如你传入的是 `claude` 格式：
+
+```ts
+await provider.chat(claudeLikeHistory, {
+  inputFormat: 'claude',
+  // 实际 provider 是 gemini
+  // outputFormat 不写时，默认回到 inputFormat，也就是 claude
+});
+```
+
+此时：
+
+- 请求发给 Gemini 之前，会先检查历史里有没有 `gemini` 可用签名
+- 如果只有 `claude` 原生签名，没有 `gemini:` 前缀签名，那么就**不把 Claude 签名错误地发给 Gemini**
+- Gemini 返回后，再编码回 `claude` 格式
+- 但返回给你的 `claude` thinking block 里的 `signature` 会是：
+
+```ts
+signature: 'gemini:xxxx'
+```
+
+同理，如果实际调用的是 `openai-responses`，那么回到其他结构时会写成 `openai-responses:xxxx`，不会再写成模糊的 `openai:xxxx`。
+
+这样你下次继续把这份 `claude` 格式历史传回来时，包就能知道：这不是 Claude 原生签名，而是 Gemini 原生签名，只是被保存在 Claude 风格结构里。
+
+---
+
+## `unified` 输出时的默认策略
+
+### 默认优先字符串
+
+如果结果里只有一个可明确归属的签名，`unified` 输出默认会是：
+
+```ts
+thoughtSignature: 'claude:sig_xxx'
+```
+
+### 如果你的 `unified` 输入本来就是对象签名
+
+在 `provider.chat(..., { inputFormat: 'unified', outputFormat: 'unified' })` 这类场景里，
+如果你原本传的是：
+
+```ts
+thoughtSignatures: { claude: 'sig_xxx' }
+```
+
+包会尽量延续对象形式。
+
+### 高级场景仍可手动控制
+
+底层 `encode* / convert*` API 仍然保留 `signatureMode` 这样的高级参数，
+但正常使用时，你通常不需要碰它。
+
+---
+
+## 推荐实践
+
+### 最推荐
+
+- 长期维护 `unified`
+- 真正发请求时按需转成目标 provider 格式
+- 返回时再转回 `unified`
+
+这样用户业务代码最稳定。
+
+### 适合中转网关 / 兼容层
+
+- 上游输入 `openai-compatible`
+- 下游实际调用 `claude`
+- 输出再转回 `openai-compatible` 或 `unified`
+
+---
+
+## 当前状态
+
+当前 `新项目/` 里的独立包已经完成：
+
+- 独立 `package.json`
+- TypeScript 构建
+- Vitest 测试
+- 内置 provider / format 注册表
+- request / response / stream from-to 转换
+- provider 调用桥接
+- thought signature 跟随格式自动处理
+
+已验证通过：
+
+```bash
+cd 新项目
+npm run test
+npm run build
+```

package/dist/bootstrap/extensions.d.ts

@@ -0,0 +1,12 @@
+import { FormatRegistry } from '../registry/formats.js';
+import { LLMProviderFactoryRegistry } from '../registry/providers.js';
+export { FormatRegistry, LLMProviderFactoryRegistry };
+export type { FormatAdapterFactory } from '../registry/formats.js';
+export type { LLMProviderFactory } from '../registry/providers.js';
+export interface BootstrapExtensionRegistry {
+    formats: FormatRegistry;
+    llmProviders: LLMProviderFactoryRegistry;
+}
+export declare function createBootstrapExtensionRegistry(): BootstrapExtensionRegistry;
+export declare function createBuiltinRegistry(): BootstrapExtensionRegistry;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/bootstrap/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/bootstrap/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAiC,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAErG,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,cAAc,CAAC;IACxB,YAAY,EAAE,0BAA0B,CAAC;CAC1C;AAED,wBAAgB,gCAAgC,IAAI,0BAA0B,CAK7E;AAED,wBAAgB,qBAAqB,IAAI,0BAA0B,CAElE"}

package/dist/bootstrap/extensions.js

@@ -0,0 +1,13 @@
+import { createBuiltinFormatRegistry, FormatRegistry } from '../registry/formats.js';
+import { createBuiltinProviderRegistry, LLMProviderFactoryRegistry } from '../registry/providers.js';
+export { FormatRegistry, LLMProviderFactoryRegistry };
+export function createBootstrapExtensionRegistry() {
+    return {
+        formats: createBuiltinFormatRegistry(),
+        llmProviders: createBuiltinProviderRegistry(),
+    };
+}
+export function createBuiltinRegistry() {
+    return createBootstrapExtensionRegistry();
+}
+//# sourceMappingURL=extensions.js.map

package/dist/bootstrap/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/bootstrap/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAErG,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,CAAC;AAStD,MAAM,UAAU,gCAAgC;IAC9C,OAAO;QACL,OAAO,EAAE,2BAA2B,EAAE;QACtC,YAAY,EAAE,6BAA6B,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,OAAO,gCAAgC,EAAE,CAAC;AAC5C,CAAC"}

package/dist/config/llm.d.ts

@@ -0,0 +1,8 @@
+import type { LLMConfig, LLMRegistryConfig } from './types.js';
+export declare const DEFAULT_MODEL_NAME = "default";
+export declare const DEFAULTS: Record<string, Partial<LLMConfig> & {
+    contextWindow?: number;
+}>;
+export declare function parseSingleLLMConfig(raw?: unknown): LLMConfig;
+export declare function parseLLMConfig(raw?: unknown): LLMRegistryConfig;
+//# sourceMappingURL=llm.d.ts.map

package/dist/config/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/config/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE5E,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CA+BpF,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,OAAY,GAAG,SAAS,CAqCjE;AAmBD,wBAAgB,cAAc,CAAC,GAAG,GAAE,OAAY,GAAG,iBAAiB,CAuBnE"}

package/dist/config/llm.js

@@ -0,0 +1,108 @@
+export const DEFAULT_MODEL_NAME = 'default';
+export const DEFAULTS = {
+    deepseek: {
+        format: 'openai-compatible',
+        model: 'deepseek-v4-flash',
+        baseUrl: 'https://api.deepseek.com/v1',
+        contextWindow: 1_000_000,
+    },
+    gemini: {
+        format: 'gemini',
+        model: 'gemini-2.0-flash',
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+        contextWindow: 1_048_576,
+    },
+    'openai-compatible': {
+        format: 'openai-compatible',
+        model: 'gpt-4o',
+        baseUrl: 'https://api.openai.com/v1',
+        contextWindow: 128_000,
+    },
+    claude: {
+        format: 'claude',
+        model: 'claude-sonnet-4-6',
+        baseUrl: 'https://api.anthropic.com/v1',
+        contextWindow: 200_000,
+    },
+    'openai-responses': {
+        format: 'openai-responses',
+        model: 'gpt-4o',
+        baseUrl: 'https://api.openai.com/v1',
+        contextWindow: 128_000,
+    },
+};
+export function parseSingleLLMConfig(raw = {}) {
+    const source = raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? raw
+        : {};
+    const provider = String(source.provider ?? 'gemini');
+    const defaults = DEFAULTS[provider] ?? {};
+    return {
+        ...source,
+        provider,
+        format: typeof source.format === 'string' ? source.format : defaults.format,
+        apiKey: typeof source.apiKey === 'string' ? source.apiKey : undefined,
+        model: typeof source.model === 'string' && source.model.trim() ? source.model : String(defaults.model ?? ''),
+        baseUrl: typeof source.baseUrl === 'string' && source.baseUrl.trim()
+            ? source.baseUrl
+            : defaults.baseUrl,
+        contextWindow: typeof source.contextWindow === 'number' ? source.contextWindow : defaults.contextWindow,
+        supportsVision: typeof source.supportsVision === 'boolean' ? source.supportsVision : undefined,
+        headers: source.headers && typeof source.headers === 'object' && !Array.isArray(source.headers)
+            ? source.headers
+            : undefined,
+        requestBody: source.requestBody && typeof source.requestBody === 'object' && !Array.isArray(source.requestBody)
+            ? source.requestBody
+            : undefined,
+        endpoint: source.endpoint && typeof source.endpoint === 'object' && !Array.isArray(source.endpoint)
+            ? source.endpoint
+            : undefined,
+        promptCaching: source.promptCaching === true ? true : undefined,
+        autoCaching: source.autoCaching === true ? true : undefined,
+        timeoutMs: typeof source.timeoutMs === 'number' ? source.timeoutMs : undefined,
+        streamTimeoutMs: typeof source.streamTimeoutMs === 'number' ? source.streamTimeoutMs : undefined,
+        fetch: typeof source.fetch === 'function' ? source.fetch : undefined,
+        debug: source.debug && typeof source.debug === 'object' && !Array.isArray(source.debug)
+            ? source.debug
+            : undefined,
+        name: typeof source.name === 'string' ? source.name : undefined,
+    };
+}
+function normalizeModelName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function toModelDef(modelName, raw) {
+    return {
+        modelName,
+        ...parseSingleLLMConfig(raw),
+    };
+}
+function hasObjectModels(raw) {
+    return !!raw && typeof raw === 'object' && !Array.isArray(raw) && !!raw.models && typeof raw.models === 'object' && !Array.isArray(raw.models);
+}
+export function parseLLMConfig(raw = {}) {
+    if (hasObjectModels(raw)) {
+        const source = raw;
+        const models = Object.entries(source.models)
+            .map(([modelName, value]) => ({ modelName: normalizeModelName(modelName), value }))
+            .filter(({ modelName, value }) => !!modelName && value && typeof value === 'object' && !Array.isArray(value))
+            .map(({ modelName, value }) => toModelDef(modelName, value));
+        if (models.length > 0) {
+            const defaultModel = normalizeModelName(source.defaultModelName ?? source.defaultModel);
+            return {
+                defaultModelName: defaultModel && models.some(model => model.modelName === defaultModel)
+                    ? defaultModel
+                    : models[0].modelName,
+                models,
+            };
+        }
+    }
+    return {
+        defaultModelName: DEFAULT_MODEL_NAME,
+        models: [toModelDef(DEFAULT_MODEL_NAME, raw)],
+    };
+}
+//# sourceMappingURL=llm.js.map

package/dist/config/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../src/config/llm.ts"],"names":[],"mappings":"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"}

package/dist/config/types.d.ts

@@ -0,0 +1,69 @@
+export type FetchLike = typeof fetch;
+export interface LLMRequestDebugEvent {
+    url: string;
+    stream: boolean;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface LLMResponseDebugEvent {
+    url: string;
+    stream: boolean;
+    status?: number;
+    headers?: Record<string, string>;
+    bodyText?: string;
+    error?: string;
+}
+export interface LLMDebugHooks {
+    onRequest?(event: LLMRequestDebugEvent): void | Promise<void>;
+    onResponse?(event: LLMResponseDebugEvent): void | Promise<void>;
+}
+export interface LLMEndpointOverride {
+    url?: string;
+    streamUrl?: string;
+    headers?: Record<string, string>;
+}
+export interface LLMConfig {
+    provider: string;
+    /** 默认使用哪个 wire format；未填则由 provider 自身决定 */
+    format?: string;
+    apiKey?: string;
+    /** 提供商真实模型 id */
+    model: string;
+    /** 默认 baseUrl。若 endpoint.url 已给定，则可不依赖 baseUrl */
+    baseUrl?: string;
+    /** 直接覆盖最终 endpoint（优先级高于 provider 默认拼接规则） */
+    endpoint?: LLMEndpointOverride;
+    /** 模型上下文窗口大小（token 数） */
+    contextWindow?: number;
+    /** 显式声明当前模型是否支持图片输入 */
+    supportsVision?: boolean;
+    /** 自定义请求头，会覆盖 provider 内置同名 header */
+    headers?: Record<string, string>;
+    /** 预留给上层 UI 或客户端的思考控制标记 */
+    thinkingControl?: boolean;
+    /** 自定义请求体，会深合并到 provider 编码后的最终请求体 */
+    requestBody?: Record<string, unknown>;
+    /** [Claude] 手动 Prompt Caching */
+    promptCaching?: boolean;
+    /** [Claude] 顶层自动缓存 */
+    autoCaching?: boolean;
+    /** 非流式请求超时（毫秒） */
+    timeoutMs?: number;
+    /** 流式请求超时（毫秒） */
+    streamTimeoutMs?: number;
+    /** 自定义 fetch 实现 */
+    fetch?: FetchLike;
+    /** 调试钩子 */
+    debug?: LLMDebugHooks;
+    /** 友好名称，可选 */
+    name?: string;
+    [key: string]: unknown;
+}
+export interface LLMModelDef extends LLMConfig {
+    modelName: string;
+}
+export interface LLMRegistryConfig {
+    defaultModelName: string;
+    models: LLMModelDef[];
+}
+//# sourceMappingURL=types.d.ts.map