pi-ai：统一 LLM API消息、流式与模型目录 —— Messages · EventStream · Catalog

src/
├── types.ts            # 全部核心类型：Model / Provider / Message / Usage / 事件
├── models.ts           # Models 注册表、Provider 接口、createModels / createProvider
├── model-catalog.ts    # 目录类型工具：ChatModelCatalog 等 flatten 函数
├── models-store.ts     # 目录持久化接口 ModelsStore + InMemoryModelsStore
├── models.generated.ts # 【自动生成】注册全部内置厂商目录
├── api/                # 协议实现，每模块导出 stream / streamSimple
├── providers/          # 厂商工厂：目录 + 认证 + 懒加载 api
├── catalog/            # 构建期目录生成脚本（npm run generate-models）
└── utils/              # event-stream.ts / transcript.ts 等

/** Fields shared by every catalog entry. */
export interface BaseModel<TApi extends string> {
  id: string;
  name: string;
  api: TApi;
  provider: ProviderId;
  baseUrl: string;
  input: ModelInputModality[];
  inputLimits?: ModelInputLimits;
  cost: ModelCost;
  headers?: Record<string, string>;
}

/** Chat model: usable with `stream()` and friends. */
export interface Model<TApi extends Api> extends BaseModel<TApi> {
  type?: "chat";              // 可省略：缺省即 chat 模型
  reasoning: boolean;                // 是否支持思考/推理输出
  thinkingLevelMap?: ThinkingLevelMap;
  promptCache?: ModelPromptCache;    // 各档缓存保留时长
  contextWindow: number;
  maxTokens: number;
  samplingParams?: SamplingParams;
  compat?: …;                        // 按协议分支的兼容性覆盖
}

export interface Provider<TApi extends Api = Api> {
  readonly id: string;
  readonly name: string;
  readonly baseUrl?: string;
  readonly headers?: ProviderHeaders;
  readonly auth: ProviderAuth;        // apiKey / oauth 语义，getAuth() 据此判定可用性

  getModels(): readonly Model<TApi>[];              // 同步读 last-known 目录
  getAllModels?(): readonly ProviderModel<TApi>[];  // 含 image / classifier 全类型
  refreshModels?(context: RefreshModelsContext): Promise<void>;  // 动态目录
  filterModels?(models, credential): readonly Model<TApi>[];      // 按凭据过滤

  stream<T extends TApi>(model, context: TranscriptContext,
                          options?: ApiStreamOptions<T>): AssistantMessageEventStream;
  streamSimple(model, context: TranscriptContext,
               options?: SimpleStreamOptions): AssistantMessageEventStream;
  fetchDeferred?(model, handle, options?): AssistantMessageEventStream;
  cancelDeferred?(model, handle, options?): Promise<void>;
  generateImages?(model, context, options?): Promise<AssistantImages>;
  classify?(model, context, options?): Promise<ClassifierResult>;
}

export function anthropicProvider(): Provider<"anthropic-messages"> {
  return createProvider({
    id: "anthropic",
    name: "Anthropic",
    baseUrl: "https://api.anthropic.com",
    auth: {
      apiKey: anthropicApiKeyAuth(),
      oauth: lazyOAuth({ name: "Anthropic (Claude Pro/Max)",
                         isSubscription: true, load: loadAnthropicOAuth }),
    },
    models: Object.values(ANTHROPIC_MODELS),   // 生成目录（见 §4.5）
    api: anthropicMessagesApi(),               // 懒加载协议实现，不提前引入 SDK
  });
}

export interface SystemMessage {
  role: "system";
  content: string | TextContent[];           // 首条 = 基础 prompt；后续 = 追加指令
  sections?: Record<string, string | null>; // 命名 prompt 段：按名替换，null 删除
  toolsAdded?: Tool[];                       // 此刻起可用的工具完整定义
  toolsRemoved?: ToolReference[];
  timestamp: number;
}

export interface UserMessage {
  role: "user";
  content: string | (TextContent | ImageContent)[];
  timestamp: number;
}

export interface AssistantMessage {
  role: "assistant";
  content: (TextContent | ThinkingContent | ToolCall)[];
  api: Api;  provider: ProviderId;  model: string;
  responseModel?: string;  responseId?: string;
  thinkingLevel?: ModelThinkingLevel;
  usage: Usage;
  stopReason: StopReason;
  deferred?: DeferredHandle;
  errorMessage?: string;
  endTurn?: boolean;
  timestamp: number;
  durationMs?: number;   // 由 AssistantMessageEventStream 用单调时钟计时
}

export type ToolResultMessage<TDetails = JsonValue> = … {
  role: "toolResult";
  toolCallId: string;  toolName: string;
  content: (TextContent | ImageContent)[];   // 支持文本与图片
  details?: JsonRepresentation<TDetails>;     // 结构化明细（不发给模型正文）
  usage?: Usage;        // 工具自身消耗；不计入主 LLM 上下文计量
  nestedCalls?: NestedToolCalls;  // 工具内嵌套调用记录（codemode）
  isError: boolean;
  timestamp: number;  durationMs?: number;
};

export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;

export class EventStream<T, R = T> implements AsyncIterable<T> {
  push(event: T): void;          // 完成事件到达时置 done 并 resolve 最终结果
  end(result?: R): void;         // 无终止事件时直接收尾
  async *[Symbol.asyncIterator](): AsyncIterator<T> { … }
  result(): Promise<R>;          // 最终结果（不消费事件也可 await）
}

export class AssistantMessageEventStream
  extends EventStream<AssistantMessageEvent, AssistantMessage> {
  // done/error 事件 → 取出最终 AssistantMessage 并用单调时钟补 durationMs
}

export type AssistantMessageEvent =
  | { type: "start"; partial: AssistantMessage }
  | { type: "text_start"; contentIndex: number; partial: AssistantMessage }
  | { type: "text_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
  | { type: "text_end"; contentIndex: number; content: string; partial: AssistantMessage }
  | { type: "thinking_start"; contentIndex: number; partial: AssistantMessage }
  | { type: "thinking_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
  | { type: "thinking_end"; contentIndex: number; content: string; partial: AssistantMessage }
  | { type: "toolcall_start"; contentIndex: number; partial: AssistantMessage }
  | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
  | { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage }
  | { type: "done";   reason: Extract<StopReason, "stop" | "length" | "toolUse" | "deferred">;
            message: AssistantMessage }
  | { type: "error"; reason: Extract<StopReason, "aborted" | "error">;
            error: AssistantMessage };

const s = models.stream(model, context);

for await (const event of s) {
  switch (event.type) {
    case 'start':        console.log(`Starting with ${event.partial.model}`); break;
    case 'text_delta':   process.stdout.write(event.delta); break;
    case 'toolcall_end': console.log(`Tool called: ${event.toolCall.name}`);  break;
    case 'done':         console.log(`Finished: ${event.reason}`);            break;
    case 'error':        console.error(`Error: ${event.error.errorMessage}`); break;
  }
}

const finalMessage = await s.result();   // 最终 AssistantMessage（含 usage / stopReason）
context.messages.push(finalMessage);

// This file is auto-generated by catalog/generate.ts
// Do not edit manually - run 'npm run generate-models' to update

import values from "./data/anthropic.json" with { type: "json" };
import { flattenChatModelCatalog, … } from "../model-catalog.ts";

export const ANTHROPIC_MODELS: ChatModelCatalog<typeof values, "anthropic"> =
  flattenChatModelCatalog("anthropic", values);

export const ANTHROPIC_IMAGE_MODELS: ImageModelCatalog<typeof values, "anthropic"> =
  flattenImageModelCatalog("anthropic", values);

export const ANTHROPIC_CLASSIFIER_MODELS: ClassifierModelCatalog<typeof values, "anthropic"> =
  flattenClassifierModelCatalog("anthropic", values);

export interface ModelsStoreEntry {
  models: readonly AnyModel[];   // 持久化的全类型模型列表
  lastModified?: number;         // 远端目录 Last-Modified 的时间戳
  checkedAt?: number;            // 上次完成远端检查的时间
  etag?: string;                 // ETag 原样保存（含引号），回传作 If-None-Match
}

/** Persistent model catalogs keyed by provider ID. */
export interface ModelsStore {
  read(providerId: string, options?): Promise<ModelsStoreEntry | undefined>;
  write(providerId: string, entry: ModelsStoreEntry, options?): Promise<void>;
  delete(providerId: string, options?): Promise<void>;
}

function mergeModels<TModel extends AnyModel>(baseline, dynamic): TModel[] {
  const merged = new Map<string, TModel>();
  for (const model of [...baseline, ...dynamic])
    merged.set(`${getModelType(model)}\0${model.id}`, model);   // 后写覆盖 = 叠加
  return [...merged.values()];
}

export function withRemoteCatalog(provider, catalogBaseUrl = "https://pi.dev",
                                   localGeneratedAt?) {
  let dynamicModels: readonly AnyModel[] = [];
  return {
    ...provider,
    getModels: () => mergeModels(provider.getModels(),
                    dynamicModels.filter((m) => isModelType(m, "chat"))),
    refreshModelsAuth: "configured",     // pi.dev 服务目录，过期登录不得阻塞刷新
    refreshModels: async (context) => { /* 恢复缓存 → 协商请求 → publish 持久化 */ },
  };
}

export interface Context {           // 公开入口的请求形状
  systemPrompt?: string;
  messages: Message[];
  tools?: Tool[];
}

declare const transcriptContextBrand: unique symbol;

/**
 * Normalized request context passed to providers and API implementations.
 * …Only `normalizeContext()` produces this type, so a raw `Context`
 * cannot reach provider code by accident.
 */
export type TranscriptContext = {
  messages: Message[];
  readonly [transcriptContextBrand]: true;
};

export function normalizeContext(context: Context): TranscriptContext {
  const initialMessage = createInitialSystemMessage(context.systemPrompt, context.tools);
  const messages = initialMessage
    ? [initialMessage, ...context.messages] : context.messages;
  return { messages } as TranscriptContext;
}

/**
 * Contract:
 * - Must not throw or return a rejected promise for request/model/runtime failures.
 * - Must return an AssistantMessageEventStream.
 * - Failures must be encoded in the returned stream via protocol events and a
 *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
 */
export type StreamFn = (
  model: Model<Api>,
  context: TranscriptContext,
  options?: SimpleStreamOptions,
) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;