@codehz/ai 0.4.4 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ai",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "type": "module",
   "module": "dist/index.mjs",
   "exports": {
@@ -9,6 +9,14 @@
       "types": "./dist/index.d.mts"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codehz/nano-ai.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "lint": "oxlint",

package/src/adapters/chat-completions.ts

@@ -27,6 +27,9 @@ import {
   openProviderJsonStream,
   iterateProviderStreamBatches,
   createCompletionGate,
+  mergeProviderHeaders,
+  applyExtraBody,
+  mapChatCompletionsReasoningEffort,
 } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn, StopReason } from "../index.js";
@@ -37,6 +40,10 @@ export type ChatCompletionsAdapterOptions = {
   apiKey: string;
   baseUrl?: string;
   fetch?: FetchFn;
+  /** 额外请求头；后写覆盖内置 Authorization / Content-Type */
+  headers?: Record<string, string>;
+  /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 
 // ── Chat API 请求类型 ─────────────────────────────────────────
@@ -49,6 +56,8 @@ type ChatRequest = {
   metadata?: Record<string, string>;
   temperature?: number;
   max_tokens?: number;
+  /** Portable reasoningLevel → reasoning_effort */
+  reasoning_effort?: string;
   stream: true;
   n: 1;
 };
@@ -242,12 +251,16 @@ export class ChatCompletionsAdapter extends AdapterBase {
   private apiKey: string;
   private baseUrl: string;
   private fetchFn: FetchFn;
+  private headers: Record<string, string> | undefined;
+  private extraBody: Record<string, unknown> | undefined;
 
   constructor(options: ChatCompletionsAdapterOptions) {
     super();
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
     this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers;
+    this.extraBody = options.extraBody;
   }
 
   // ── buildRequest ──────────────────────────────────────────
@@ -356,8 +369,11 @@ export class ChatCompletionsAdapter extends AdapterBase {
     if (request.temperature !== undefined) body.temperature = request.temperature;
     if (request.maxOutputTokens !== undefined) body.max_tokens = request.maxOutputTokens;
     if (request.metadata) body.metadata = request.metadata;
+    if (request.reasoningLevel !== undefined) {
+      body.reasoning_effort = mapChatCompletionsReasoningEffort(request.reasoningLevel);
+    }
 
-    return body;
+    return applyExtraBody(body, this.extraBody);
   }
 
   // ── runStream ─────────────────────────────────────────────
@@ -373,10 +389,13 @@ export class ChatCompletionsAdapter extends AdapterBase {
     const { reader } = await openProviderJsonStream({
       fetchFn: this.fetchFn,
       url: `${this.baseUrl}/chat/completions`,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
+      headers: mergeProviderHeaders(
+        {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        this.headers,
+      ),
       body: providerRequest,
       signal: request.signal,
     });

package/src/adapters/messages.ts

@@ -30,6 +30,9 @@ import {
   openProviderJsonStream,
   iterateProviderStreamBatches,
   createCompletionGate,
+  mergeProviderHeaders,
+  applyExtraBody,
+  mapMessagesThinking,
 } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
@@ -42,6 +45,10 @@ export type MessagesAdapterOptions = {
   baseUrl?: string;
   /** 可注入自定义 fetch 实现（用于测试／代理） */
   fetch?: FetchFn;
+  /** 额外请求头；后写覆盖内置 x-api-key / Content-Type / anthropic-version */
+  headers?: Record<string, string>;
+  /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 
 // ── Messages API 请求类型 ────────────────────────────────────
@@ -54,7 +61,7 @@ type MessagesAPIRequest = {
   tools?: MessagesAPITool[];
   tool_choice?: { type: "auto" | "none" } | { type: "tool"; name: string };
   temperature?: number;
-  thinking?: { type: "enabled"; budget_tokens: number };
+  thinking?: { type: "enabled"; budget_tokens: number } | { type: "disabled" };
   stream: true;
 };
 
@@ -243,6 +250,8 @@ export class MessagesAdapter extends AdapterBase {
   private apiVersion: string;
   private baseUrl: string;
   private fetchFn: FetchFn;
+  private headers: Record<string, string> | undefined;
+  private extraBody: Record<string, unknown> | undefined;
 
   constructor(options: MessagesAdapterOptions) {
     super();
@@ -250,6 +259,8 @@ export class MessagesAdapter extends AdapterBase {
     this.apiVersion = options.apiVersion ?? "2023-06-01";
     this.baseUrl = options.baseUrl ?? "https://api.anthropic.com/v1";
     this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers;
+    this.extraBody = options.extraBody;
   }
 
   // ── buildRequest ──────────────────────────────────────────
@@ -369,8 +380,11 @@ export class MessagesAdapter extends AdapterBase {
     });
 
     if (request.temperature !== undefined) body.temperature = request.temperature;
+    if (request.reasoningLevel !== undefined) {
+      body.thinking = mapMessagesThinking(request.reasoningLevel, body.max_tokens);
+    }
 
-    return body;
+    return applyExtraBody(body, this.extraBody);
   }
 
   // ── runStream ─────────────────────────────────────────────
@@ -393,11 +407,14 @@ export class MessagesAdapter extends AdapterBase {
     const { reader, headers } = await openProviderJsonStream({
       fetchFn: this.fetchFn,
       url: `${this.baseUrl}/messages`,
-      headers: {
-        "Content-Type": "application/json",
-        "x-api-key": this.apiKey,
-        "anthropic-version": this.apiVersion,
-      },
+      headers: mergeProviderHeaders(
+        {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": this.apiVersion,
+        },
+        this.headers,
+      ),
       body: providerRequest,
       signal: request.signal,
     });

package/src/adapters/mock.ts

@@ -24,6 +24,7 @@ import type {
   MessageItem,
   NormalizedRequest,
   OutputItem,
+  ReasoningLevel,
   ReplayItem,
   StopReason,
   ToolCallItem,
@@ -70,6 +71,8 @@ export type MockHandlerContext = {
   history: readonly MockHistoryRecord[];
   /** 请求的 AbortSignal，handler 可检查 signal.aborted 提前退出。 */
   signal?: AbortSignal;
+  /** 当前请求的 portable reasoningLevel（若设置）。 */
+  reasoningLevel?: ReasoningLevel;
 };
 
 export type MockWarningStep = {
@@ -284,7 +287,7 @@ export class MockAdapter extends AdapterBase {
 
   protected async buildRequest(request: NormalizedRequest): Promise<MockProviderRequest> {
     const turnIndex = this.cursor;
-    const context = this.buildHandlerContext(turnIndex, request.signal);
+    const context = this.buildHandlerContext(turnIndex, request);
     const remainingPendingToolCalls = consumePendingToolCalls(this.pendingToolCalls, request.input);
     const handlerResult = this.handler(request, context);
 
@@ -476,7 +479,7 @@ export class MockAdapter extends AdapterBase {
     );
   }
 
-  private buildHandlerContext(turnIndex: number, signal?: AbortSignal): MockHandlerContext {
+  private buildHandlerContext(turnIndex: number, request: NormalizedRequest): MockHandlerContext {
     return {
       turnIndex,
       previousReplay: this.previousReplay.map(cloneItem),
@@ -486,7 +489,8 @@ export class MockAdapter extends AdapterBase {
         replay: record.replay.map(cloneItem),
         toolCalls: record.toolCalls.map(cloneItem),
       })),
-      signal,
+      signal: request.signal,
+      reasoningLevel: request.reasoningLevel,
     };
   }
 }

package/src/adapters/ollama.ts

@@ -34,6 +34,9 @@ import {
   openProviderJsonStream,
   iterateProviderStreamBatches,
   createCompletionGate,
+  mergeProviderHeaders,
+  applyExtraBody,
+  mapOllamaThink,
 } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn, StopReason } from "../index.js";
@@ -47,6 +50,10 @@ export type OllamaAdapterOptions = {
   apiKey?: string;
   /** 可注入自定义 fetch 实现 */
   fetch?: FetchFn;
+  /** 额外请求头；后写覆盖内置 Content-Type / Authorization */
+  headers?: Record<string, string>;
+  /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 
 // ── Ollama Chat API 类型 ──────────────────────────────────────
@@ -56,6 +63,8 @@ type OllamaChatRequest = {
   messages: OllamaMessage[];
   stream: true;
   tools?: OllamaTool[];
+  /** Portable reasoningLevel → think；minimal/xhigh 不支持 */
+  think?: boolean | "low" | "medium" | "high";
   options?: {
     temperature?: number;
     num_predict?: number;
@@ -151,12 +160,16 @@ export class OllamaAdapter extends AdapterBase {
   private baseUrl: string;
   private apiKey: string | undefined;
   private fetchFn: FetchFn;
+  private headers: Record<string, string> | undefined;
+  private extraBody: Record<string, unknown> | undefined;
 
   constructor(options: OllamaAdapterOptions = {}) {
     super();
     this.baseUrl = options.baseUrl ?? "http://localhost:11434";
     this.apiKey = options.apiKey;
     this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers;
+    this.extraBody = options.extraBody;
   }
 
   // ── buildRequest ──────────────────────────────────────────
@@ -291,7 +304,11 @@ export class OllamaAdapter extends AdapterBase {
       if (request.maxOutputTokens !== undefined) body.options.num_predict = request.maxOutputTokens;
     }
 
-    return body;
+    if (request.reasoningLevel !== undefined) {
+      body.think = mapOllamaThink(request.reasoningLevel);
+    }
+
+    return applyExtraBody(body, this.extraBody);
   }
 
   // ── runStream ─────────────────────────────────────────────
@@ -326,7 +343,7 @@ export class OllamaAdapter extends AdapterBase {
     const { reader } = await openProviderJsonStream({
       fetchFn: this.fetchFn,
       url: `${this.baseUrl}/api/chat`,
-      headers,
+      headers: mergeProviderHeaders(headers, this.headers),
       body: providerRequest,
       signal: request.signal,
     });

package/src/adapters/responses.ts

@@ -27,6 +27,9 @@ import {
   openProviderJsonStream,
   iterateProviderStreamBatches,
   createCompletionGate,
+  mergeProviderHeaders,
+  applyExtraBody,
+  mapResponsesReasoning,
 } from "../helpers/index.js";
 
 import type { NormalizedRequest, AIStreamEvent, EventFactory, OutputItem, FetchFn } from "../index.js";
@@ -38,6 +41,10 @@ export type ResponsesAdapterOptions = {
   baseUrl?: string;
   /** 可注入自定义 fetch 实现（用于测试／代理） */
   fetch?: FetchFn;
+  /** 额外请求头；后写覆盖内置 Authorization / Content-Type */
+  headers?: Record<string, string>;
+  /** 额外 body 顶层字段；浅层合并，同名键可覆盖 */
+  extraBody?: Record<string, unknown>;
 };
 
 // ── Responses API 请求类型（对齐 OpenAI Responses schema）────
@@ -55,6 +62,8 @@ type ResponsesAPIRequest = {
   metadata?: Record<string, string>;
   temperature?: number;
   max_output_tokens?: number;
+  /** Portable reasoningLevel → effort；summary 等特化字段不在此层 */
+  reasoning?: { effort: string };
   /** 服务端多轮续写；opaque replay 的 response id 映射到此字段，而非 item_reference */
   previous_response_id?: string;
   stream: true;
@@ -341,12 +350,16 @@ export class ResponsesAdapter extends AdapterBase {
   private apiKey: string;
   private baseUrl: string;
   private fetchFn: FetchFn;
+  private headers: Record<string, string> | undefined;
+  private extraBody: Record<string, unknown> | undefined;
 
   constructor(options: ResponsesAdapterOptions) {
     super();
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
     this.fetchFn = options.fetch ?? globalThis.fetch;
+    this.headers = options.headers;
+    this.extraBody = options.extraBody;
   }
 
   // ── buildRequest ──────────────────────────────────────────
@@ -457,8 +470,11 @@ export class ResponsesAdapter extends AdapterBase {
     if (request.temperature !== undefined) body.temperature = request.temperature;
     if (request.maxOutputTokens !== undefined) body.max_output_tokens = request.maxOutputTokens;
     if (request.metadata) body.metadata = request.metadata;
+    if (request.reasoningLevel !== undefined) {
+      body.reasoning = mapResponsesReasoning(request.reasoningLevel);
+    }
 
-    return body;
+    return applyExtraBody(body, this.extraBody);
   }
 
   // ── runStream ─────────────────────────────────────────────
@@ -474,10 +490,13 @@ export class ResponsesAdapter extends AdapterBase {
     const { reader } = await openProviderJsonStream({
       fetchFn: this.fetchFn,
       url: `${this.baseUrl}/responses`,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-      },
+      headers: mergeProviderHeaders(
+        {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        this.headers,
+      ),
       body: providerRequest,
       signal: request.signal,
     });

package/src/core/validation.ts

@@ -18,6 +18,7 @@ const MESSAGE_ROLES = new Set(["user", "assistant"]);
 const REASONING_VISIBILITIES = new Set(["full", "summary", "redacted", "opaque"]);
 const TOOL_RESULT_OUTCOMES = new Set(["success", "error", "rejected"]);
 const INCLUDE_MODES = new Set(["off", "best_effort"]);
+const REASONING_LEVELS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -333,6 +334,18 @@ export function validateRequest(request: AIRequest): ValidationIssue[] {
     }
   }
 
+  // reasoningLevel 枚举
+  if (request.reasoningLevel !== undefined) {
+    if (typeof request.reasoningLevel !== "string" || !REASONING_LEVELS.has(request.reasoningLevel)) {
+      pushIssue(
+        issues,
+        "reasoningLevel",
+        "REASONING_LEVEL_INVALID",
+        'reasoningLevel must be one of: none, minimal, low, medium, high, xhigh',
+      );
+    }
+  }
+
   if (request.include !== undefined) {
     validateInclude(request.include, issues);
   }

package/src/helpers/index.ts

@@ -70,4 +70,18 @@ export type {
   ProviderStreamBatchOptions,
 } from "./provider-stream.js";
 
+export { mergeProviderHeaders, applyExtraBody } from "./provider-request-options.js";
+
+export {
+  REASONING_LEVELS,
+  REASONING_LEVEL_SET,
+  assertSupportedReasoningLevel,
+  mapResponsesReasoning,
+  mapChatCompletionsReasoningEffort,
+  mapMessagesThinkingBudget,
+  mapMessagesThinking,
+  mapOllamaThink,
+} from "./reasoning-level.js";
+export type { OpenAIReasoningEffort, MessagesThinkingConfig, OllamaThinkValue } from "./reasoning-level.js";
+
 export { NormalizedRequestMapper } from "./request-mapper.js";

package/src/helpers/provider-request-options.ts

@@ -0,0 +1,25 @@
+/**
+ * Provider 请求 headers / body 扩展合并
+ *
+ * 供真实后端 adapter 构造选项 `headers` / `extraBody` 使用：
+ * - headers：内置鉴权头为基，自定义后写覆盖
+ * - extraBody：已构建 body 为基，额外字段浅层 spread，同名顶层键可覆盖
+ */
+
+/** 合并内置 headers 与自定义 headers；自定义后写覆盖同名键。 */
+export function mergeProviderHeaders(
+  base: Record<string, string>,
+  custom?: Record<string, string>,
+): Record<string, string> {
+  if (!custom) return base;
+  return { ...base, ...custom };
+}
+
+/**
+ * 将构造期 extraBody 浅层合并到已构建的 provider body。
+ * 无 extraBody 时原样返回；有则允许覆盖同名顶层键。
+ */
+export function applyExtraBody<T extends object>(body: T, extraBody?: Record<string, unknown>): T {
+  if (!extraBody) return body;
+  return { ...body, ...extraBody };
+}

package/src/helpers/reasoning-level.ts

@@ -0,0 +1,85 @@
+/**
+ * Portable reasoningLevel → provider wire 字段映射
+ *
+ * 第一版只处理 level 枚举；budget/summary 等特化字段不在此层。
+ * 无法映射的 level 抛 AIRequestError(UNSUPPORTED_REASONING_LEVEL)。
+ */
+
+import { AIRequestError } from "../core/errors.js";
+import type { ReasoningLevel } from "../types/request.js";
+
+export const REASONING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly ReasoningLevel[];
+
+export const REASONING_LEVEL_SET: ReadonlySet<string> = new Set(REASONING_LEVELS);
+
+const MESSAGES_BUDGET_RATIOS: Record<Exclude<ReasoningLevel, "none">, number> = {
+  minimal: 0.02,
+  low: 0.1,
+  medium: 0.3,
+  high: 0.6,
+  xhigh: 0.9,
+};
+
+const OLLAMA_SUPPORTED = new Set<ReasoningLevel>(["none", "low", "medium", "high"]);
+
+export type OpenAIReasoningEffort = ReasoningLevel;
+
+export type MessagesThinkingConfig =
+  | { type: "disabled" }
+  | { type: "enabled"; budget_tokens: number };
+
+export type OllamaThinkValue = false | "low" | "medium" | "high";
+
+/** 若 level 不在 supported 集合内则抛 AIRequestError。 */
+export function assertSupportedReasoningLevel(
+  level: ReasoningLevel,
+  supported: ReadonlySet<ReasoningLevel>,
+  adapterKind: string,
+): void {
+  if (supported.has(level)) return;
+  throw new AIRequestError(
+    `reasoningLevel "${level}" is not supported by the ${adapterKind} adapter`,
+    "UNSUPPORTED_REASONING_LEVEL",
+  );
+}
+
+/** Responses API：`reasoning: { effort }` */
+export function mapResponsesReasoning(level: ReasoningLevel): { effort: OpenAIReasoningEffort } {
+  return { effort: level };
+}
+
+/** Chat Completions：顶层 `reasoning_effort` */
+export function mapChatCompletionsReasoningEffort(level: ReasoningLevel): OpenAIReasoningEffort {
+  return level;
+}
+
+/**
+ * Messages thinking budget。
+ * 基于 maxTokens 按比例推导，clamp 到 [1024, max(1024, maxTokens - 1)]，
+ * 满足 Anthropic budget_tokens < max_tokens。
+ */
+export function mapMessagesThinkingBudget(level: Exclude<ReasoningLevel, "none">, maxTokens: number): number {
+  const ratio = MESSAGES_BUDGET_RATIOS[level];
+  const raw = Math.round(maxTokens * ratio);
+  const upper = Math.max(1024, maxTokens - 1);
+  return Math.min(Math.max(raw, 1024), upper);
+}
+
+/** Messages API：`thinking` 字段 */
+export function mapMessagesThinking(level: ReasoningLevel, maxTokens: number): MessagesThinkingConfig {
+  if (level === "none") {
+    return { type: "disabled" };
+  }
+  return {
+    type: "enabled",
+    budget_tokens: mapMessagesThinkingBudget(level, maxTokens),
+  };
+}
+
+/** Ollama：`think` 字段；minimal/xhigh 不支持 */
+export function mapOllamaThink(level: ReasoningLevel): OllamaThinkValue {
+  assertSupportedReasoningLevel(level, OLLAMA_SUPPORTED, "ollama");
+  if (level === "none") return false;
+  // narrow after assert: only low|medium|high remain
+  return level as Exclude<OllamaThinkValue, false>;
+}

package/src/types/index.ts

@@ -21,7 +21,7 @@ export type {
 } from "./items.js";
 
 // 请求模型
-export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings } from "./request.js";
+export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings, ReasoningLevel } from "./request.js";
 
 // 响应模型
 export type { AIResponse, StopReason, Usage, BillingInfo, AuxiliaryInfo, BackendTrace } from "./response.js";

package/src/types/request.ts

@@ -25,6 +25,11 @@ export type IncludeSettings = {
   providerMetadata?: "off" | "best_effort";
 };
 
+// ── reasoning level ───────────────────────────────────────────
+
+/** Portable reasoning / thinking effort. Mapped per-adapter to provider wire fields. */
+export type ReasoningLevel = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
 // ── 统一请求 ──────────────────────────────────────────────────
 
 export type AIRequest = {
@@ -36,6 +41,12 @@ export type AIRequest = {
   metadata?: Record<string, string>;
   temperature?: number;
   maxOutputTokens?: number;
+  /**
+   * Portable reasoning effort. Adapters map this to provider-native fields
+   * (e.g. Responses `reasoning.effort`, Chat Completions `reasoning_effort`,
+   * Messages `thinking`, Ollama `think`). Unsupported levels throw.
+   */
+  reasoningLevel?: ReasoningLevel;
   /** AbortSignal 用于打断请求。abort 时 fetch 调用会被取消，流迭代器抛出 AbortError。 */
   signal?: AbortSignal;
 };