@codehz/ai 0.1.0

package/src/types/adapter.ts

@@ -0,0 +1,109 @@
+/**
+ * BackendAdapter — adapter 内部协议和 client 公开类型
+ *
+ * adapter 对前台只暴露一个统一适配点。
+ * 能力矩阵在此落成代码而非仅存在于文档。
+ */
+
+import type { AIRequest } from "./request.js";
+import type { AIStreamEvent } from "./events.js";
+
+// ── 公共工具类型 ──────────────────────────────────────────────
+
+/** HTTP fetch 函数签名，用于注入自定义请求实现（测试／代理） */
+export type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
+
+// ── 归一化请求 ────────────────────────────────────────────────
+
+export type NormalizedRequest = AIRequest & {
+  model: string;
+  requestId: string;
+};
+
+// ── 能力矩阵 ──────────────────────────────────────────────────
+
+export type AdapterCapabilities = {
+  nativeStreaming: boolean;
+  messageStreaming: boolean;
+  reasoningStreaming: boolean;
+  toolCallStreaming: boolean;
+  hiddenReasoningReplay: "full" | "partial" | "none";
+  replayFidelity: "high" | "medium" | "low";
+  tools: boolean;
+  usage: "full" | "partial" | "none";
+  billing: "direct" | "lookup" | "derived" | "none";
+  providerMetadata: boolean;
+};
+
+// ── 能力矩阵常量（文档中的能力表在此落代码） ────────────────
+
+export const CAPABILITY_MATRIX = {
+  responses: {
+    nativeStreaming: true,
+    messageStreaming: true,
+    reasoningStreaming: true,
+    toolCallStreaming: true,
+    hiddenReasoningReplay: "full" as const,
+    replayFidelity: "high" as const,
+    tools: true,
+    usage: "full" as const,
+    billing: "lookup" as const,
+    providerMetadata: true,
+  },
+  messages: {
+    nativeStreaming: true,
+    messageStreaming: true,
+    reasoningStreaming: false, // 条件支持，默认 false
+    toolCallStreaming: true,
+    hiddenReasoningReplay: "partial" as const,
+    replayFidelity: "medium" as const,
+    tools: true,
+    usage: "full" as const,
+    billing: "lookup" as const,
+    providerMetadata: true,
+  },
+  "chat.completions": {
+    nativeStreaming: true,
+    messageStreaming: true,
+    reasoningStreaming: false,
+    toolCallStreaming: false, // 中，默认 false
+    hiddenReasoningReplay: "none" as const,
+    replayFidelity: "low" as const,
+    tools: true,
+    usage: "full" as const,
+    billing: "derived" as const,
+    providerMetadata: false,
+  },
+  ollama: {
+    nativeStreaming: true,
+    messageStreaming: true,
+    reasoningStreaming: false,
+    toolCallStreaming: false,
+    hiddenReasoningReplay: "none" as const,
+    replayFidelity: "low" as const,
+    tools: true,
+    usage: "partial" as const,
+    billing: "none" as const,
+    providerMetadata: false,
+  },
+} as const satisfies Record<string, AdapterCapabilities>;
+
+// ── Adapter 接口 ──────────────────────────────────────────────
+
+export interface BackendAdapter {
+  readonly kind: "chat-completions" | "messages" | "responses" | "ollama";
+  readonly capabilities: AdapterCapabilities;
+  stream(request: NormalizedRequest): AsyncIterable<AIStreamEvent>;
+}
+
+// ── Client 公开类型 ───────────────────────────────────────────
+
+export type CreateAIClientOptions = {
+  adapter: BackendAdapter;
+  model: string;
+  defaults?: Partial<AIRequest>;
+};
+
+export interface AIClient {
+  stream(request: AIRequest): AsyncIterable<AIStreamEvent>;
+}

package/src/types/content.ts

@@ -0,0 +1,12 @@
+/**
+ * ContentBlock — 统一内容块类型
+ *
+ * 覆盖文本、JSON、图片、二进制引用和后端私有内容。
+ */
+
+export type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "json"; json: unknown }
+  | { type: "image"; imageUrl: string }
+  | { type: "binary_ref"; ref: string }
+  | { type: "opaque"; payload: unknown };

package/src/types/events.ts

@@ -0,0 +1,134 @@
+/**
+ * AIStreamEvent — 统一流事件模型
+ *
+ * 所有 adapter 都必须产出 AsyncIterable<AIStreamEvent>。
+ * 无论后端是否支持原生流式，调用方看到的事件语义都一致：
+ *   响应级开始 → item 级开始/增量/完成 → 响应级完成
+ */
+
+import type { ContentBlock } from "./content.js";
+import type { MessageItem, ReasoningItem, ToolCallItem } from "./items.js";
+import type { AIResponse, Usage, BillingInfo, AuxiliaryInfo } from "./response.js";
+
+// ── 事件基类 ──────────────────────────────────────────────────
+
+export type StreamEventBase = {
+  type: string;
+  responseId?: string;
+  sequence: number;
+  timestamp: string;
+  backend: {
+    kind: "chat-completions" | "messages" | "responses" | "ollama";
+    isSynthetic: boolean;
+  };
+};
+
+// ── 响应级事件 ────────────────────────────────────────────────
+
+export type ResponseStartedEvent = StreamEventBase & {
+  type: "response.started";
+  model: string;
+};
+
+export type ResponseWarningEvent = StreamEventBase & {
+  type: "response.warning";
+  message: string;
+  code?: string;
+};
+
+export type ResponseAuxiliaryEvent = StreamEventBase & {
+  type: "response.auxiliary";
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: Partial<AuxiliaryInfo>;
+};
+
+export type ResponseCompletedEvent = StreamEventBase & {
+  type: "response.completed";
+  response: AIResponse;
+};
+
+// ── 消息流事件 ────────────────────────────────────────────────
+
+export type MessageStartedEvent = StreamEventBase & {
+  type: "message.started";
+  item: {
+    id: string;
+    role: "assistant";
+  };
+};
+
+export type MessageDeltaEvent = StreamEventBase & {
+  type: "message.delta";
+  itemId: string;
+  delta: {
+    type: "text";
+    text: string;
+  };
+};
+
+export type MessageCompletedEvent = StreamEventBase & {
+  type: "message.completed";
+  item: MessageItem;
+};
+
+// ── 思维链流事件 ──────────────────────────────────────────────
+
+export type ReasoningStartedEvent = StreamEventBase & {
+  type: "reasoning.started";
+  item: {
+    id: string;
+    visibility: "full" | "summary" | "redacted" | "opaque";
+  };
+};
+
+export type ReasoningDeltaEvent = StreamEventBase & {
+  type: "reasoning.delta";
+  itemId: string;
+  delta: ContentBlock;
+};
+
+export type ReasoningCompletedEvent = StreamEventBase & {
+  type: "reasoning.completed";
+  item: ReasoningItem;
+};
+
+// ── 工具调用流事件 ────────────────────────────────────────────
+
+export type ToolCallStartedEvent = StreamEventBase & {
+  type: "tool_call.started";
+  item: {
+    id: string;
+    name: string;
+  };
+};
+
+export type ToolCallDeltaEvent = StreamEventBase & {
+  type: "tool_call.delta";
+  itemId: string;
+  delta: {
+    argumentsText?: string;
+  };
+};
+
+export type ToolCallCompletedEvent = StreamEventBase & {
+  type: "tool_call.completed";
+  item: ToolCallItem;
+};
+
+// ── 统一事件联合 ──────────────────────────────────────────────
+
+export type AIStreamEvent =
+  | ResponseStartedEvent
+  | ResponseWarningEvent
+  | ResponseAuxiliaryEvent
+  | MessageStartedEvent
+  | MessageDeltaEvent
+  | MessageCompletedEvent
+  | ReasoningStartedEvent
+  | ReasoningDeltaEvent
+  | ReasoningCompletedEvent
+  | ToolCallStartedEvent
+  | ToolCallDeltaEvent
+  | ToolCallCompletedEvent
+  | ResponseCompletedEvent;

package/src/types/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Canonical 类型系统
+ *
+ * 模块边界：统一请求、事件、响应模型的核心类型定义。
+ * 所有公开类型最终从这里导出。
+ */
+
+// 基础内容块
+export type { ContentBlock } from "./content.js";
+
+// Item 类型体系
+export type {
+  MessageItem,
+  ReasoningItem,
+  ToolCallItem,
+  ToolResultItem,
+  OpaqueItem,
+  InputItem,
+  OutputItem,
+  ReplayItem,
+} from "./items.js";
+
+// 请求模型
+export type { AIRequest, ToolDefinition, ToolChoice, IncludeSettings } from "./request.js";
+
+// 响应模型
+export type { AIResponse, StopReason, Usage, BillingInfo, AuxiliaryInfo, BackendTrace } from "./response.js";
+
+// 流事件模型
+export type {
+  AIStreamEvent,
+  StreamEventBase,
+  ResponseStartedEvent,
+  ResponseWarningEvent,
+  ResponseAuxiliaryEvent,
+  ResponseCompletedEvent,
+  MessageStartedEvent,
+  MessageDeltaEvent,
+  MessageCompletedEvent,
+  ReasoningStartedEvent,
+  ReasoningDeltaEvent,
+  ReasoningCompletedEvent,
+  ToolCallStartedEvent,
+  ToolCallDeltaEvent,
+  ToolCallCompletedEvent,
+} from "./events.js";
+
+// Adapter 协议和 client 类型
+export type {
+  BackendAdapter,
+  AdapterCapabilities,
+  FetchFn,
+  NormalizedRequest,
+  CreateAIClientOptions,
+  AIClient,
+} from "./adapter.js";
+
+// 能力矩阵常量
+export { CAPABILITY_MATRIX } from "./adapter.js";

package/src/types/items.ts

@@ -0,0 +1,58 @@
+/**
+ * Canonical Item 类型体系
+ *
+ * 覆盖统一请求/响应中的所有 item 类型。
+ */
+
+import type { ContentBlock } from "./content.js";
+
+// ── Input item types ──────────────────────────────────────────
+
+export type MessageItem = {
+  type: "message";
+  id?: string;
+  role: "user" | "assistant" | "system" | "developer";
+  content: ContentBlock[];
+};
+
+export type ReasoningItem = {
+  type: "reasoning";
+  id?: string;
+  visibility: "full" | "summary" | "redacted" | "opaque";
+  content: ContentBlock[];
+};
+
+export type ToolCallItem = {
+  type: "tool_call";
+  id: string;
+  name: string;
+  argumentsText: string;
+  argumentsJson?: unknown;
+};
+
+export type ToolResultItem = {
+  type: "tool_result";
+  callId: string;
+  toolName: string;
+  outcome: "success" | "error" | "rejected";
+  content: ContentBlock[];
+};
+
+export type OpaqueItem = {
+  type: "opaque";
+  id?: string;
+  source: "responses" | "messages" | "chat.completions" | string;
+  purpose: "replay" | "provider_state" | "unknown";
+  payload: unknown;
+};
+
+// ── Aliases ───────────────────────────────────────────────────
+
+/** 可出现在请求 input 中的 item 类型 */
+export type InputItem = MessageItem | ReasoningItem | ToolCallItem | ToolResultItem | OpaqueItem;
+
+/** 可出现在响应 output 中的 item 类型（不含 ToolResultItem） */
+export type OutputItem = MessageItem | ReasoningItem | ToolCallItem | OpaqueItem;
+
+/** replay 材料的类型等价于 InputItem */
+export type ReplayItem = InputItem;

package/src/types/request.ts

@@ -0,0 +1,39 @@
+/**
+ * AIRequest — 统一请求模型
+ *
+ * 所有 adapter 都接受同一形状的 canonical request。
+ */
+
+import type { ContentBlock } from "./content.js";
+import type { InputItem } from "./items.js";
+
+// ── 工具定义 ──────────────────────────────────────────────────
+
+export type ToolDefinition = {
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>;
+};
+
+export type ToolChoice = "auto" | "none" | { type: "tool"; name: string };
+
+// ── include 控制 ──────────────────────────────────────────────
+
+export type IncludeSettings = {
+  usage?: "off" | "best_effort";
+  billing?: "off" | "best_effort";
+  providerMetadata?: "off" | "best_effort";
+};
+
+// ── 统一请求 ──────────────────────────────────────────────────
+
+export type AIRequest = {
+  instructions?: string | ContentBlock[];
+  input: InputItem[];
+  tools?: ToolDefinition[];
+  toolChoice?: ToolChoice;
+  include?: IncludeSettings;
+  metadata?: Record<string, string>;
+  temperature?: number;
+  maxOutputTokens?: number;
+};

package/src/types/response.ts

@@ -0,0 +1,65 @@
+/**
+ * AIResponse — 统一终结结果模型
+ *
+ * 流结束后由聚合器产出，用于承载当前轮的规范化输出、replay 材料及辅助信息。
+ */
+
+import type { OutputItem, ReplayItem, ToolCallItem } from "./items.js";
+
+// ── StopReason ────────────────────────────────────────────────
+
+export type StopReason = "end_turn" | "tool_call" | "max_output_tokens" | "content_filter" | "error" | "unknown";
+
+// ── 辅助信息类型 ──────────────────────────────────────────────
+
+export type Usage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  totalTokens?: number;
+  cachedInputTokens?: number;
+  cacheWriteInputTokens?: number;
+  billableInputTokens?: number;
+  billableOutputTokens?: number;
+};
+
+export type BillingInfo = {
+  amount?: number;
+  currency?: string;
+  isEstimated: boolean;
+  source: "provider" | "lookup" | "derived" | "unknown";
+  raw?: unknown;
+};
+
+export type AuxiliaryInfo = {
+  usageSource?: "stream" | "final" | "header" | "lookup" | "derived";
+  billingSource?: "stream" | "final" | "header" | "lookup" | "derived";
+  providerUsage?: unknown;
+  providerBilling?: unknown;
+  providerMetadata?: Record<string, unknown>;
+};
+
+export type BackendTrace = {
+  requestId?: string;
+  rawResponseId?: string;
+  adapter: "chat-completions" | "messages" | "responses" | "ollama";
+  isSyntheticStream: boolean;
+  metadataSources?: string[];
+  warnings?: string[];
+};
+
+// ── 统一响应 ──────────────────────────────────────────────────
+
+export type AIResponse = {
+  id?: string;
+  output: OutputItem[];
+  replay: ReplayItem[];
+  text: string;
+  toolCalls: ToolCallItem[];
+  stopReason?: StopReason;
+  usage?: Usage;
+  billing?: BillingInfo;
+  auxiliary?: AuxiliaryInfo;
+  warnings?: string[];
+  backend: BackendTrace;
+};

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  platform: "node",
+  clean: true,
+  sourcemap: true,
+});