create-windy 0.3.2 → 0.3.5

package/template/packages/ai-client/src/document/client.ts

@@ -0,0 +1,134 @@
+import type {
+  DocumentAiClient,
+  DocumentFetch,
+  DocumentOperation,
+  DocumentRun,
+  SubmitDocumentRunInput,
+} from "./contracts.js";
+import { DocumentClientError, documentHttpError } from "./error.js";
+import { HttpDocumentRun } from "./run.js";
+import { parseArtifactRef, parseCreatedRun } from "./validation.js";
+
+export interface DocumentClientOptions {
+  readonly baseUrl: string | URL;
+  readonly runsPath?: string;
+  readonly fetch?: DocumentFetch;
+}
+
+export class HttpDocumentAiClient implements DocumentAiClient {
+  private readonly baseUrl: URL;
+  private readonly runsPath: string;
+  private readonly fetch: DocumentFetch;
+
+  constructor(options: DocumentClientOptions) {
+    this.baseUrl = new URL(options.baseUrl);
+    if (!["http:", "https:"].includes(this.baseUrl.protocol)) {
+      throw new DocumentClientError(
+        "INVALID_CONFIGURATION",
+        "Document Client 只允许 HTTP 或 HTTPS",
+        false,
+      );
+    }
+    this.runsPath = options.runsPath ?? "/api/document/runs";
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  async submit<Options, Output>(
+    operation: DocumentOperation<Options, Output>,
+    input: SubmitDocumentRunInput<Options>,
+    context: { idempotencyKey: string; signal?: AbortSignal },
+  ): Promise<DocumentRun<Output>> {
+    if (!operation.key.trim() || !context.idempotencyKey.trim()) {
+      throw new DocumentClientError(
+        "INVALID_CONFIGURATION",
+        "Document Operation 与幂等键不能为空",
+        false,
+      );
+    }
+    const sources = parseSources(input);
+    const options = input.options
+      ? (operation.parseOptions?.(input.options) ?? input.options)
+      : undefined;
+    let response: Response;
+    try {
+      response = await this.fetch(this.endpoint(this.runsPath), {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "idempotency-key": context.idempotencyKey,
+        },
+        body: JSON.stringify({
+          operationKey: operation.key,
+          ...(sources.length === 1 && input.source
+            ? { source: sources[0] }
+            : { sources }),
+          options,
+        }),
+        signal: context.signal,
+      });
+    } catch (error) {
+      throw new DocumentClientError(
+        context.signal?.aborted ? "RUN_CANCELLED" : "RUNTIME_UNAVAILABLE",
+        context.signal?.aborted
+          ? "创建文档任务已取消"
+          : "Document Runtime 暂不可用",
+        !context.signal?.aborted,
+        undefined,
+        { cause: error },
+      );
+    }
+    if (!response.ok)
+      throw await documentHttpError(response, "创建文档任务失败");
+    const created = parseCreatedRun(await response.json());
+    return new HttpDocumentRun({
+      id: created.runId,
+      eventsUrl: this.endpoint(created.eventsUrl),
+      resultUrl: this.endpoint(
+        `${this.runsPath}/${encodeURIComponent(created.runId)}/result`,
+      ),
+      cancelUrl: this.endpoint(
+        `${this.runsPath}/${encodeURIComponent(created.runId)}/cancel`,
+      ),
+      fetch: this.fetch,
+      signal: context.signal,
+      parseOutput: operation.parseOutput,
+    });
+  }
+
+  private endpoint(path: string): URL {
+    const endpoint = new URL(path, this.baseUrl);
+    if (endpoint.origin !== this.baseUrl.origin) {
+      throw new DocumentClientError(
+        "INVALID_RESPONSE",
+        "Document Runtime 返回了不受信任的 Endpoint",
+        false,
+      );
+    }
+    return endpoint;
+  }
+}
+
+function parseSources<Options>(
+  input: SubmitDocumentRunInput<Options>,
+): readonly ReturnType<typeof parseArtifactRef>[] {
+  if (input.source && input.sources) {
+    throw new DocumentClientError(
+      "INVALID_CONFIGURATION",
+      "Document source 与 sources 不能同时提供",
+      false,
+    );
+  }
+  const values = input.source ? [input.source] : input.sources;
+  if (!values?.length || values.length > 100) {
+    throw new DocumentClientError(
+      "INVALID_CONFIGURATION",
+      "Document 输入文件数量必须为 1 至 100",
+      false,
+    );
+  }
+  return values.map(parseArtifactRef);
+}
+
+export function createDocumentAiClient(options: DocumentClientOptions) {
+  return new HttpDocumentAiClient(options);
+}

package/template/packages/ai-client/src/document/contracts.ts

@@ -0,0 +1,152 @@
+export type { ArtifactRef } from "../artifact-ref.js";
+import type { ArtifactRef } from "../artifact-ref.js";
+
+export type DocumentFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface DocumentProcessingOptions {
+  readonly languages?: readonly string[];
+  readonly pageRange?: {
+    readonly from: number;
+    readonly to: number;
+  };
+  readonly outputs?: readonly DocumentOutputKind[];
+}
+
+export type DocumentOutputKind =
+  | "pages"
+  | "layout"
+  | "tables"
+  | "searchable-pdf"
+  | "json";
+
+export interface DocumentOperation<Options, Output> {
+  readonly key: string;
+  parseOutput(value: unknown): Output;
+  parseOptions?(value: Options): Options;
+}
+
+export interface SubmitDocumentRunInput<Options> {
+  /** 单文档处理使用 source；图片合并等多源任务使用 sources，二者只能提供一个。 */
+  readonly source?: ArtifactRef;
+  readonly sources?: readonly ArtifactRef[];
+  readonly options?: Options & DocumentProcessingOptions;
+}
+
+export interface DocumentTextBlock {
+  readonly id: string;
+  readonly text: string;
+  readonly confidence?: number;
+  readonly bounds?: DocumentBounds;
+}
+
+export interface DocumentBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly unit: "pixel" | "normalized";
+}
+
+export interface DocumentPage {
+  readonly pageNumber: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly text: string;
+  readonly blocks: readonly DocumentTextBlock[];
+  readonly layout?: readonly DocumentLayoutNode[];
+}
+
+export interface DocumentLayoutNode {
+  readonly id: string;
+  readonly type: string;
+  readonly text?: string;
+  readonly bounds?: DocumentBounds;
+  readonly children?: readonly DocumentLayoutNode[];
+}
+
+export interface DocumentTable {
+  readonly pageNumber: number;
+  readonly bounds?: DocumentBounds;
+  readonly rows: readonly (readonly string[])[];
+}
+
+export interface DocumentResult {
+  readonly pages: readonly DocumentPage[];
+  readonly tables: readonly DocumentTable[];
+  readonly artifacts: readonly ArtifactRef[];
+  readonly metadata: Readonly<Record<string, string | number | boolean>>;
+}
+
+export type DocumentRunStatus =
+  | "accepted"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export type DocumentEvent =
+  | {
+      readonly type: "run.started";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "document.page.completed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly pageNumber: number;
+      readonly completedPages: number;
+      readonly totalPages?: number;
+    }
+  | {
+      readonly type: "run.completed" | "run.cancelled";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "run.failed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly error: DocumentErrorPayload;
+    };
+
+export interface DocumentErrorPayload {
+  readonly code: DocumentErrorCode;
+  readonly message: string;
+  readonly requestId: string;
+  readonly retryable: boolean;
+}
+
+export type DocumentErrorCode =
+  | "OPERATION_NOT_FOUND"
+  | "OPERATION_DISABLED"
+  | "INVALID_INPUT"
+  | "FORBIDDEN"
+  | "LICENSE_NOT_ALLOWED"
+  | "ARTIFACT_UNAVAILABLE"
+  | "ARTIFACT_EXPIRED"
+  | "CAPABILITY_UNAVAILABLE"
+  | "RUNTIME_UNAVAILABLE"
+  | "BUDGET_EXCEEDED"
+  | "OUTPUT_VALIDATION_FAILED"
+  | "RUN_CONFLICT"
+  | "RUN_TIMEOUT"
+  | "RUN_CANCELLED";
+
+export interface DocumentRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<DocumentEvent>;
+  result(): Promise<Output>;
+  cancel(reason?: string): Promise<void>;
+}
+
+export interface DocumentAiClient {
+  submit<Options, Output>(
+    operation: DocumentOperation<Options, Output>,
+    input: SubmitDocumentRunInput<Options>,
+    context: { idempotencyKey: string; signal?: AbortSignal },
+  ): Promise<DocumentRun<Output>>;
+}

package/template/packages/ai-client/src/document/error.ts

@@ -0,0 +1,43 @@
+import type { DocumentErrorCode } from "./contracts.js";
+
+export class DocumentClientError extends Error {
+  constructor(
+    readonly code:
+      | DocumentErrorCode
+      | "INVALID_CONFIGURATION"
+      | "INVALID_RESPONSE",
+    message: string,
+    readonly retryable: boolean,
+    readonly requestId?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "DocumentClientError";
+  }
+}
+
+export async function documentHttpError(response: Response, fallback: string) {
+  try {
+    const value = (await response.json()) as Record<string, unknown>;
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
+      value.message.length <= 200
+    ) {
+      return new DocumentClientError(
+        value.code as DocumentErrorCode,
+        value.message,
+        value.retryable,
+        typeof value.requestId === "string" ? value.requestId : undefined,
+      );
+    }
+  } catch {
+    // Runtime 响应正文不可信，不向业务透传。
+  }
+  return new DocumentClientError(
+    "RUNTIME_UNAVAILABLE",
+    `${fallback}（HTTP ${response.status}）`,
+    response.status >= 500,
+  );
+}

package/template/packages/ai-client/src/document/index.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./contracts.js";
+export * from "./error.js";

package/template/packages/ai-client/src/document/run.ts

@@ -0,0 +1,104 @@
+import type { DocumentEvent, DocumentFetch, DocumentRun } from "./contracts.js";
+import { DocumentClientError, documentHttpError } from "./error.js";
+import { parseDocumentEvent, record } from "./validation.js";
+
+export interface HttpDocumentRunInput<Output> {
+  id: string;
+  eventsUrl: URL;
+  resultUrl: URL;
+  cancelUrl: URL;
+  fetch: DocumentFetch;
+  signal?: AbortSignal;
+  parseOutput(value: unknown): Output;
+}
+
+export class HttpDocumentRun<Output> implements DocumentRun<Output> {
+  readonly id: string;
+  readonly events: AsyncIterable<DocumentEvent>;
+
+  constructor(private readonly input: HttpDocumentRunInput<Output>) {
+    this.id = input.id;
+    this.events = streamEvents(input);
+  }
+
+  async result(): Promise<Output> {
+    const response = await this.input.fetch(this.input.resultUrl, {
+      signal: this.input.signal,
+    });
+    if (!response.ok)
+      throw await documentHttpError(response, "读取文档结果失败");
+    const body = record(await response.json(), "DocumentResult");
+    return this.input.parseOutput(body.output);
+  }
+
+  async cancel(reason?: string): Promise<void> {
+    const response = await this.input.fetch(this.input.cancelUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ reason: reason?.slice(0, 200) }),
+      signal: this.input.signal,
+    });
+    if (!response.ok)
+      throw await documentHttpError(response, "取消文档任务失败");
+  }
+}
+
+async function* streamEvents<Output>(
+  input: HttpDocumentRunInput<Output>,
+): AsyncIterable<DocumentEvent> {
+  let cursor = 0;
+  while (true) {
+    const url = new URL(input.eventsUrl);
+    url.searchParams.set("after", String(cursor));
+    const response = await input.fetch(url, { signal: input.signal });
+    if (!response.ok)
+      throw await documentHttpError(response, "读取文档事件失败");
+    if (!response.body) {
+      throw new DocumentClientError(
+        "INVALID_RESPONSE",
+        "Document Runtime 未返回事件流",
+        true,
+      );
+    }
+    for await (const event of decodeSse(response.body)) {
+      const parsed = parseDocumentEvent(event);
+      if (parsed.sequence <= cursor) continue;
+      cursor = parsed.sequence;
+      yield parsed;
+      if (
+        ["run.completed", "run.failed", "run.cancelled"].includes(parsed.type)
+      ) {
+        return;
+      }
+    }
+  }
+}
+
+async function* decodeSse(body: ReadableStream<Uint8Array>) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) return;
+      buffer += decoder
+        .decode(chunk.value, { stream: true })
+        .replaceAll("\r\n", "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary >= 0) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const data = frame
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trimStart())
+          .join("\n");
+        if (data) yield JSON.parse(data) as unknown;
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/template/packages/ai-client/src/document/validation.ts

@@ -0,0 +1,115 @@
+import { DocumentClientError } from "./error.js";
+import type {
+  DocumentErrorPayload,
+  DocumentEvent,
+  DocumentRunStatus,
+} from "./contracts.js";
+import type { ArtifactRef } from "../artifact-ref.js";
+
+export function parseArtifactRef(value: unknown): ArtifactRef {
+  const item = record(value, "ArtifactRef");
+  const byteSize = integer(item.byteSize, "ArtifactRef.byteSize", 0);
+  const sha256 = text(item.sha256, "ArtifactRef.sha256");
+  if (!/^[a-f0-9]{64}$/.test(sha256)) invalid("ArtifactRef.sha256");
+  return {
+    value: text(item.value, "ArtifactRef.value"),
+    mediaType: text(item.mediaType, "ArtifactRef.mediaType"),
+    byteSize,
+    sha256,
+    ...(item.expiresAt === undefined
+      ? {}
+      : { expiresAt: text(item.expiresAt, "ArtifactRef.expiresAt") }),
+  };
+}
+
+export function parseDocumentEvent(value: unknown): DocumentEvent {
+  const item = record(value, "DocumentEvent");
+  const type = text(item.type, "DocumentEvent.type");
+  const base = {
+    runId: text(item.runId, "DocumentEvent.runId"),
+    sequence: integer(item.sequence, "DocumentEvent.sequence", 1),
+  };
+  if (
+    type === "run.started" ||
+    type === "run.completed" ||
+    type === "run.cancelled"
+  ) {
+    return { type, ...base };
+  }
+  if (type === "document.page.completed") {
+    return {
+      type,
+      ...base,
+      pageNumber: integer(item.pageNumber, "DocumentEvent.pageNumber", 1),
+      completedPages: integer(
+        item.completedPages,
+        "DocumentEvent.completedPages",
+        1,
+      ),
+      ...(item.totalPages === undefined
+        ? {}
+        : {
+            totalPages: integer(item.totalPages, "DocumentEvent.totalPages", 1),
+          }),
+    };
+  }
+  if (type === "run.failed") {
+    return { type, ...base, error: parseError(item.error) };
+  }
+  invalid("DocumentEvent.type");
+}
+
+export function parseCreatedRun(value: unknown): {
+  runId: string;
+  status: DocumentRunStatus;
+  eventsUrl: string;
+} {
+  const item = record(value, "DocumentRun");
+  const status = text(item.status, "DocumentRun.status");
+  if (
+    !["accepted", "running", "completed", "failed", "cancelled"].includes(
+      status,
+    )
+  ) {
+    invalid("DocumentRun.status");
+  }
+  return {
+    runId: text(item.runId, "DocumentRun.runId"),
+    status: status as DocumentRunStatus,
+    eventsUrl: text(item.eventsUrl, "DocumentRun.eventsUrl"),
+  };
+}
+
+function parseError(value: unknown): DocumentErrorPayload {
+  const item = record(value, "DocumentError");
+  return {
+    code: text(item.code, "DocumentError.code") as DocumentErrorPayload["code"],
+    message: text(item.message, "DocumentError.message"),
+    requestId: text(item.requestId, "DocumentError.requestId"),
+    retryable: item.retryable === true,
+  };
+}
+
+export function record(value: unknown, path: string) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid(path);
+  return value as Record<string, unknown>;
+}
+
+export function text(value: unknown, path: string) {
+  if (typeof value !== "string" || !value.trim()) invalid(path);
+  return value;
+}
+
+function integer(value: unknown, path: string, minimum: number) {
+  if (!Number.isSafeInteger(value) || Number(value) < minimum) invalid(path);
+  return Number(value);
+}
+
+function invalid(path: string): never {
+  throw new DocumentClientError(
+    "INVALID_RESPONSE",
+    `Document Runtime 响应字段无效：${path}`,
+    false,
+  );
+}

package/template/packages/ai-client/src/embedding/client.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import { createEmbeddingClient } from "./client.js";
+import { EmbeddingClientError } from "./error.js";
+
+describe("Embedding Client", () => {
+  test("提交稳定批次并验证固定部署元数据", async () => {
+    let body: unknown;
+    const client = createEmbeddingClient({
+      baseUrl: "https://windy.example",
+      fetch: async (_input, init) => {
+        body = JSON.parse(String(init?.body));
+        return Response.json({
+          batchId: "embed_1",
+          items: [
+            {
+              id: "text-1",
+              vector: [1, 0],
+              inputSha256: "a".repeat(64),
+            },
+          ],
+          metadata: {
+            deploymentAlias: "intranet-text-v1",
+            model: "local-model",
+            version: "2026-07",
+            dimensions: 2,
+            normalized: true,
+          },
+        });
+      },
+    });
+
+    const result = await client.embed(
+      { key: "analysis.embedding.text" },
+      { items: [{ id: "text-1", text: "测试" }] },
+      { idempotencyKey: "batch-1" },
+    );
+
+    expect(body).toEqual({
+      operationKey: "analysis.embedding.text",
+      items: [{ id: "text-1", text: "测试" }],
+    });
+    expect(result.metadata.deploymentAlias).toBe("intranet-text-v1");
+    expect(result.items[0]?.vector).toEqual([1, 0]);
+  });
+
+  test("拒绝响应顺序和归一化元数据漂移", async () => {
+    const response = {
+      batchId: "embed_1",
+      items: [
+        {
+          id: "other",
+          vector: [1],
+          inputSha256: "a".repeat(64),
+        },
+      ],
+      metadata: {
+        deploymentAlias: "local",
+        model: "model",
+        version: "v1",
+        dimensions: 1,
+        normalized: "true",
+      },
+    };
+    const client = createEmbeddingClient({
+      baseUrl: "https://windy.example",
+      fetch: async () => Response.json(response),
+    });
+
+    await expect(
+      client.embed(
+        { key: "analysis.embedding.text" },
+        { items: [{ id: "text-1", text: "测试" }] },
+        { idempotencyKey: "batch-1" },
+      ),
+    ).rejects.toBeInstanceOf(EmbeddingClientError);
+  });
+});