@morlay/dsh-llm-openai-compatible 0.0.10 → 0.0.12

package/README.md

@@ -1,31 +1,20 @@
 # @morlay/dsh-llm-openai-compatible
 
-DeepSeek Harness 的 **OpenAI 兼容 LLM 适配器**插件。与内置 `llm-pi-ai` /
-`llm-deepseek` 不同，本插件的配置 schema 支持 **profile 级默认采样参数**
-（`temperature` / `topP` / `topK` / `presencePenalty` / `frequencyPenalty` /
-`seed`），请求级 `GenerateOptions.temperature` 优先于 profile 默认值；`providers`
-用 dict 多路由结构（与 `llm-pi-ai` 一致）。
+DeepSeek Harness 的 **OpenAI 兼容 LLM 适配器**：`providers` 是 dict 多路由（**key 就是 provider 路由键**），每个
+profile 除了端点与模型目录，还能声明 **profile 级默认采样参数**（`temperature` / `topP` / `topK` /
+`presencePenalty` / `frequencyPenalty` / `seed`）——请求级 `GenerateOptions.temperature` 优先于 profile 默认，缺省
+一律不发送（= 提供方默认）。传输层复用
+**[@ai-sdk/openai-compatible](https://www.npmjs.com/package/@ai-sdk/openai-compatible)**，本插件只做 harness
+适配：消息 → AI SDK prompt、采样合并、stream part → `StreamChunk`、错误归一化与凭据策略。
 
-## 可选：与官方 `llm-pi-ai` 二选一
+**与官方 `llm-pi-ai` 二选一**：两者都提供 openai-compatible 的 `providers` dict 与同名 provider 路由，同装会有
+两套适配器抢同一批路由，一个部署只装一个。本部署装的是官方那行——它的 `ollama` route 由
+[`@morlay/ollama-provider-profile`](../../bundles/ollama-provider-profile/cordis.patch.yml) 配置；只有需要 profile
+级采样默认值时才换成这一行。
 
-本包是**可选 bundle**，与官方 `llm-pi-ai` 覆盖同一块领域：两者都提供 openai-compatible 的 `providers` dict 与
-同名的 provider 路由。**同装会出现两套适配器抢同一批路由**，所以一个部署只装一个——本部署装的是官方那行
-（`@morlay/dsh-profile` 配它的 `ollama` route）；只有需要 profile 级采样默认值时才换成这一行。
+## 用法
 
-传输层复用 **[@ai-sdk/openai-compatible](https://www.npmjs.com/package/@ai-sdk/openai-compatible)**
-（wire 序列化与 SSE 解析由 SDK 负责）；本插件负责 harness 消息 → AI SDK prompt
-转换、采样默认合并、stream part → `StreamChunk` 翻译、错误归一化与凭据策略。
-
-本文件只给配置面与用法；每条规则与取舍的 home 是各自 ADR（见下）。
-
-## 配置
-
-`providers` 是 dict：**key 就是 provider 路由键**（选择器与
-`GenerateOptions.provider` 使用），值是 profile。它标了 `.volatile()`——**运行期可改**：
-值经 Loader 的引用读取，设置页（Models 页）改的就是它，不需要重挂这行插件（见
-[ADR-运行期改配置走volatile引用](./.agents/adrs/20260922-运行期改配置走volatile引用.md)）。
-
-配置写在**这行的 config** 里（bundle patch / profile patch / 设置页都落到这里）：
+配置写在这一行的 config 里（bundle patch / profile patch / 设置页都落到这里）：
 
 ```yaml
 - id: llm-openai-compatible
@@ -36,64 +25,18 @@ DeepSeek Harness 的 **OpenAI 兼容 LLM 适配器**插件。与内置 `llm-pi-a
         apiKeyEnv: OLLAMA_API_KEY
         baseURL: https://ollama.com/v1
         displayName: Ollama Gateway
-        # === 采样默认参数（请求级 temperature 优先）===
-        temperature: 1 # 0..2
-        topP: 0.95 # 0..1 → wire top_p
-        topK: 40 # 正整数 → wire top_k（非标准，仅网关支持时发送）
-        presencePenalty: 0 # -2..2 → wire presence_penalty
-        frequencyPenalty: 0 # -2..2 → wire frequency_penalty
-        seed: 42 # 正整数 → wire seed
-        # === 推理 ===
-        reasoning: high # 部署默认档位（省略 = 提供方默认）
-        # === 模型目录 ===
-        defaultContextWindow: 262144
-        defaultMaxTokens: 32768
+        temperature: 1
+        topP: 0.95
+        reasoning: high
         models:
           - id: deepseek-v4-flash:0731
             name: DeepSeek V4 Flash
             contextWindow: 1000000
             maxTokens: 65535
             inputModalities: [text, image]
-            reasoningEfforts:
-              off: # off 空值 = 不发送 reasoning_effort
-              high: high # 档位 → wire reasoning_effort 拼写
-              max: max
-        # === 传输 ===
-        maxRequestImageBytes: 20971520
-        streamIdleTimeoutMs: 300000
-        timeoutMs: 600000 # 整体请求超时；缺省不设
-        retryPolicy:
-          mode: normal
-          maxRetries: 5
+            reasoningEfforts: { off: null, high: high, max: max }
 ```
 
-> 旧 `$DSH_HOME/settings.yaml` 的 `llm-openai-compatible` 段由上游启动时一次性导入到同 id 的行 config。
-
-## 规则与取舍
-
-规则细节（合并表、wire 字段落点、端点与错误映射）在各自 ADR 里维护，这里只列结论：
-
-- **采样默认值与省略语义**：请求级优先于 profile 默认，缺省一律**不发送**（= 提供方
-  默认）——见 [ADR-采样默认值合并规则与省略语义](./.agents/adrs/20260917-采样默认值合并规则与省略语义.md)。
-- **模型目录缺省为空、描述模型绝不抛错**：未列出的 id 原样透传，不支持的能力配置推迟到
-  请求执行处失败——见 [ADR-模型目录缺省为空且描述模型绝不抛错](./.agents/adrs/20260917-模型目录缺省为空且描述模型绝不抛错.md)。
-- **传输层复用 SDK**：非标准字段（`top_k`）与用量方言在本层显式处理——见
-  [ADR-传输层复用ai-sdk-openai-compatible而非自研wire序列化](./.agents/adrs/20260917-传输层复用ai-sdk-openai-compatible而非自研wire序列化.md)。
-- **凭据经 `ctx.credentials` 解析**（服务缺失回退 launch environment）：见
-  [ADR-凭据经credentials服务解析而非直接读环境变量](./.agents/adrs/20260917-凭据经credentials服务解析而非直接读环境变量.md)。
-- **图片超预算报错交由 durable offload 重试**（本适配器不自行裁剪请求图片）：见
-  [ADR-图片超预算报错交由durable-offload重试](./.agents/adrs/20260917-图片超预算报错交由durable-offload重试.md)。
-- **多路由结构对齐 `llm-pi-ai`**（数组式 profiles 被拒绝）：见
-  [ADR-providers采用dict多路由结构对齐llm-pi-ai](./.agents/adrs/20260917-providers采用dict多路由结构对齐llm-pi-ai.md)
-  与 [ADR-起因llm-pi-ai的请求参数配置不完整](./.agents/adrs/20260917-起因llm-pi-ai的请求参数配置不完整.md)。
-- **未做（YAGNI）**：`modelOverrides`、模型 discovery（`GET /models`）、OAuth / 非
-  bearer 认证——理由见模型目录 ADR。
-
-## 从 `llm-pi-ai` 迁移
-
-把 `llm-pi-ai.providers.<route>` 的 `baseURL` / `models` / 采样字段平移到
-`llm-openai-compatible.providers.<route>`（无 `api` 字段——协议固定
-chat-completions），`apiKeyEnv` 与 `retryPolicy` 原样保留；`reasoningEfforts`
-的 `off` 空值语义一致。
-
-构建、测试与类型检查的命令见根 `justfile` 与 `mise.toml`。
+`providers` 标了 `.volatile()`——**运行期可改**：值经 Loader 的引用读取，设置页（Models 页）改的就是它，不需要
+重挂这行插件。字段清单（端点与请求头、采样、模型目录、传输与重试）、wire 落点与省略语义、错误映射、凭据与图片
+策略都在各自 ADR 里；`$DSH_HOME/settings.yaml` 里同名的段由上游在启动时导入同 id 的行 config。

package/dist/index.d.mts

@@ -7,12 +7,12 @@ import { Context, Volatile } from "@deepseek-ai/cordis";
 type Dict<T = any, K extends string | symbol = string> = { [key in K]: T; };
 //#endregion
 //#region src/index.d.ts
-declare const name = "llm-openai-compatible";
-declare const inject: string[];
-declare const NS = "llm-openai-compatible";
-declare const REASONING_LEVELS: readonly ["off", "low", "high", "max"];
-declare const MODEL_MODALITIES: readonly ["text", "image"];
-interface ModelProfileSource {
+export declare const name = "llm-openai-compatible";
+export declare const inject: string[];
+export declare const NS = "llm-openai-compatible";
+export declare const REASONING_LEVELS: readonly ["off", "low", "high", "max"];
+export declare const MODEL_MODALITIES: readonly ["text", "image"];
+export interface ModelProfileSource {
   id: string;
   name?: string;
   description?: string;
@@ -21,7 +21,7 @@ interface ModelProfileSource {
   inputModalities?: ModelModality[];
   reasoningEfforts?: false | Partial<Record<ReasoningEffort, string | null>>;
 }
-interface ProviderProfileSource {
+export interface ProviderProfileSource {
   apiKeyEnv?: string;
   displayName?: string;
   baseURL: string;
@@ -41,24 +41,18 @@ interface ProviderProfileSource {
   timeoutMs?: number;
   retryPolicy?: RetryPolicyConfig;
 }
-interface Config {
-  /**
-   * provider 路由，key 是路由键。**volatile**：值经 Loader 的引用读取
-   * （`config.providers.get()`），设置页改它时不需要重挂这行插件——上游 0.1.7 起
-   * 「运行期可改」只有这一条路（旧的 settings namespace section 覆盖已取消）。
-   */
+export interface Config {
   providers: Volatile<Record<string, ProviderProfileSource>>;
 }
-/** 解析成普通值之后的配置形状（校验与解析只认它）。 */
-type Options = { [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : never; };
-declare const Config: z<Schemastery.ObjectS<NoInfer<{
+export type Options = { [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : never; };
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
   providers: z<NoInfer<Dict<ProviderProfileSource, string>>, NoInfer<Dict<ProviderProfileSource, string>>, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
   providers: z<NoInfer<Dict<ProviderProfileSource, string>>, NoInfer<Dict<ProviderProfileSource, string>>, "volatile-defined">;
 }>>, "plain">;
-declare function resolveAdapterOptions(provider: string, source: ProviderProfileSource): ResolvedProviderProfile;
-declare function resolveProfiles(providers: Readonly<Record<string, ProviderProfileSource>> | undefined): Map<string, ResolvedProviderProfile>;
-declare function assertServiceable(config: Options): void;
-declare function apply(ctx: Context, config: Config): void;
+export declare function resolveAdapterOptions(provider: string, source: ProviderProfileSource): ResolvedProviderProfile;
+export declare function resolveProfiles(providers: Readonly<Record<string, ProviderProfileSource>> | undefined): Map<string, ResolvedProviderProfile>;
+export declare function assertServiceable(config: Options): void;
+export declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, MODEL_MODALITIES, ModelProfileSource, NS, OpenAICompatibleAdapter, type OpenAICompatibleAdapterOptions, Options, ProviderProfileSource, REASONING_LEVELS, type ReasoningEffort, type ResolvedModelProfile, type ResolvedProviderProfile, apply, assertServiceable, inject, name, resolveAdapterOptions, resolveProfiles };
+export { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, OpenAICompatibleAdapter, type OpenAICompatibleAdapterOptions, type ReasoningEffort, type ResolvedModelProfile, type ResolvedProviderProfile };

package/dist/index.mjs

@@ -259,10 +259,6 @@ const REASONING_LEVELS = [
 	"max"
 ];
 const MODEL_MODALITIES = ["text", "image"];
-/**
-* 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
-* （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
-*/
 const localized = (text) => text;
 const modelSchema = z.object({
 	id: z.string().required().description(localized({

package/dist/invariant.d.mts

@@ -1,7 +1,6 @@
 import { Context } from "@deepseek-ai/cordis";
 //#region src/invariant.d.ts
-declare const name = "llm-openai-compatible-invariant";
-declare const inject: string[];
-declare const apply: (ctx: Context) => Promise<() => void>;
-//#endregion
-export { apply, inject, name };
+export declare const name = "llm-openai-compatible-invariant";
+export declare const inject: string[];
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//#endregion

package/dist/wire.d.mts

@@ -3,13 +3,13 @@ import { FinishReason, GenerateOptions, StreamChunk, TokenUsage } from "@deepsee
 import { LanguageModelV4FinishReason, LanguageModelV4FunctionTool, LanguageModelV4Prompt, LanguageModelV4StreamPart, LanguageModelV4Usage, SharedV4ProviderOptions } from "@ai-sdk/provider";
 import { AttachmentStore } from "@deepseek-ai/dsh-attachment";
 //#region src/serialize.d.ts
-type OpenAICompatibleProviderOptions = SharedV4ProviderOptions & {
+export type OpenAICompatibleProviderOptions = SharedV4ProviderOptions & {
   "openai-compatible"?: {
     reasoningEffort?: string;
     top_k?: number;
   };
 };
-interface OpenAICompatibleCallOptions {
+export interface OpenAICompatibleCallOptions {
   prompt: LanguageModelV4Prompt;
   maxOutputTokens?: number;
   temperature?: number;
@@ -21,17 +21,16 @@ interface OpenAICompatibleCallOptions {
   tools?: LanguageModelV4FunctionTool[];
   providerOptions?: OpenAICompatibleProviderOptions;
 }
-declare function resolveReasoningWire(model: ResolvedModelProfile | undefined, effort: ResolvedProviderProfile["reasoning"] | undefined): string | undefined;
-declare function serializeCallOptions(options: GenerateOptions, profile: ResolvedProviderProfile, model: ResolvedModelProfile | undefined): Promise<OpenAICompatibleCallOptions>;
-declare function serializeCallOptionsWithImages(options: GenerateOptions, profile: ResolvedProviderProfile, model: ResolvedModelProfile | undefined, images: {
+export declare function resolveReasoningWire(model: ResolvedModelProfile | undefined, effort: ResolvedProviderProfile["reasoning"] | undefined): string | undefined;
+export declare function serializeCallOptions(options: GenerateOptions, profile: ResolvedProviderProfile, model: ResolvedModelProfile | undefined): Promise<OpenAICompatibleCallOptions>;
+export declare function serializeCallOptionsWithImages(options: GenerateOptions, profile: ResolvedProviderProfile, model: ResolvedModelProfile | undefined, images: {
   attachments: AttachmentStore;
   maxRequestImageBytes: number;
   signal?: AbortSignal;
 }): Promise<OpenAICompatibleCallOptions>;
 //#endregion
 //#region src/translate.d.ts
-declare function mapFinishReason(reason: LanguageModelV4FinishReason): FinishReason;
-declare function mapUsage(usage: LanguageModelV4Usage): TokenUsage;
-declare function translate(stream: ReadableStream<LanguageModelV4StreamPart>): AsyncGenerator<StreamChunk, void>;
-//#endregion
-export { OpenAICompatibleCallOptions, OpenAICompatibleProviderOptions, mapFinishReason, mapUsage, resolveReasoningWire, serializeCallOptions, serializeCallOptionsWithImages, translate };
+export declare function mapFinishReason(reason: LanguageModelV4FinishReason): FinishReason;
+export declare function mapUsage(usage: LanguageModelV4Usage): TokenUsage;
+export declare function translate(stream: ReadableStream<LanguageModelV4StreamPart>): AsyncGenerator<StreamChunk, void>;
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/dsh-llm-openai-compatible",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Optional OpenAI-compatible LLM adapter plugin for DeepSeek Harness with configurable default sampling parameters (temperature / topP / topK / penalties / seed) over a providers dict. Pick either this bundle or the built-in llm-pi-ai, never both.",
   "keywords": [
     "dsh",

package/src/index.ts

@@ -82,21 +82,16 @@ export interface ProviderProfileSource {
 }
 
 export interface Config {
-  /**
-   * provider 路由，key 是路由键。**volatile**：值经 Loader 的引用读取
-   * （`config.providers.get()`），设置页改它时不需要重挂这行插件——上游 0.1.7 起
-   * 「运行期可改」只有这一条路（旧的 settings namespace section 覆盖已取消）。
-   */
+  // provider 路由，key 是路由键。**volatile**：值经 Loader 的引用读取（`config.providers.get()`），
+  // 设置页改它不必重挂这行插件——运行期可改只有这一条路。
   providers: Volatile<Record<string, ProviderProfileSource>>;
 }
 
-/** 解析成普通值之后的配置形状（校验与解析只认它）。 */
+// 解析成普通值之后的配置形状（校验与解析只认它）。
 export type Options = { [K in keyof Config]?: Config[K] extends Volatile<infer T> ? T : never };
 
-/**
- * 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
- * （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
- */
+// 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
+// （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
 const localized = (text: { zh: string; en: string }): string => text as unknown as string;
 
 const modelSchema = z.object({
@@ -700,7 +695,7 @@ export function apply(ctx: Context, config: Config): void {
     }
   };
   // volatile 更新（设置页保存）只把新值提交进运行引用并广播，不重挂这一行：这里重算路由注册与
-  // 可配置 provider 目录（上游 0.1.7 的运行期改配置机制；`profiles()` 读的就是引用里的新值）。
+  // 可配置 provider 目录（`profiles()` 读的就是引用里的新值）。
   ctx.on("loader/volatile-update", refresh);
   // 候选配置在提交前先校验：无效更新被拒绝，运行引用保持原值（loader 只记录这次拒绝）。
   ctx.on("internal/config", function (this: Context["fiber"], _raw, next) {

package/src/serialize.ts

@@ -258,7 +258,7 @@ async function serializePrompt(
       continue;
     }
     if (message.role === "tool") {
-      // 结果消息自己带 `toolCallId` 与结果块（V4 起结果不再是 user 消息里的一个块）。
+      // 结果消息自己带 `toolCallId` 与结果块（结果不是 user 消息里的一个块）。
       const images: UserContentPart[] = [];
       if (resolveImage !== void 0) {
         for (const block of message.content) {