@southwind-ai/shared 0.2.4 → 0.2.6

package/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/audit.js";
+export * from "./src/ai-operation-readiness.js";
 // @windy-module system.agent begin
 export * from "./src/ai-runtime-report.js";
 // @windy-module system.agent end
@@ -22,4 +23,8 @@ export * from "./src/rbac.js";
 export * from "./src/ruoyi.js";
 export * from "./src/scheduler.js";
 export * from "./src/search-provider.js";
+// @windy-module system.agent begin
+export * from "./src/screenshot-context-digest.js";
+// @windy-module system.agent end
+export * from "./src/stable-key.js";
 export * from "./src/workflow.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -11,6 +11,9 @@
     "src/**/*.ts",
     "!src/**/*.test.ts"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
   "exports": {
     ".": "./index.ts"
   },

package/src/ai-operation-readiness.ts

@@ -0,0 +1,170 @@
+export const AI_RUNTIME_READINESS_SCHEMA_VERSION = 1 as const;
+export const AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1 = 16 as const;
+
+export const AI_RUNTIME_KINDS_V1 = [
+  "agent",
+  "document",
+  "speech",
+  "embedding",
+] as const;
+
+export type AiRuntimeKindV1 = (typeof AI_RUNTIME_KINDS_V1)[number];
+
+export const AI_RUNTIME_MODALITIES_V1 = [
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document",
+  "embedding",
+] as const;
+
+export type AiRuntimeModalityV1 = (typeof AI_RUNTIME_MODALITIES_V1)[number];
+export type AiRuntimeReleaseDigestV1 = `sha256:${string}`;
+export type AiRuntimeOffersDigestV1 = `sha256:${string}`;
+
+export interface AiRuntimeDeploymentV1 {
+  readonly key: string;
+  readonly identity: string;
+  readonly releaseDigest: AiRuntimeReleaseDigestV1;
+  readonly offersDigest: AiRuntimeOffersDigestV1;
+}
+
+export interface AiOperationRequiredLimitsV1 {
+  readonly maxDurationSeconds: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+  readonly maxUnits?: number;
+  readonly maxMediaDurationSeconds?: number;
+  readonly maxArtifacts?: number;
+  readonly maxPixelsPerArtifact?: number;
+}
+
+export interface AiOperationRequiredResourcesV1 {
+  readonly minConcurrentRuns: number;
+  readonly minQueueDepth: number;
+}
+
+export interface AiOperationReadinessRequirementV1 {
+  readonly schemaVersion: typeof AI_RUNTIME_READINESS_SCHEMA_VERSION;
+  readonly operationKey: string;
+  readonly runtimeKind: AiRuntimeKindV1;
+  readonly expectedDeployment: AiRuntimeDeploymentV1;
+  readonly variant?: string;
+  readonly requiredCapabilities: readonly string[];
+  readonly inputModalities: readonly AiRuntimeModalityV1[];
+  readonly outputModalities: readonly AiRuntimeModalityV1[];
+  readonly limits: AiOperationRequiredLimitsV1;
+  readonly resources: AiOperationRequiredResourcesV1;
+}
+
+const stableKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const deploymentIdentityPattern =
+  /^windy-deployment-v1_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+const runtimeKinds = new Set<string>(AI_RUNTIME_KINDS_V1);
+const runtimeModalities = new Set<string>(AI_RUNTIME_MODALITIES_V1);
+const requiredLimitKeys = [
+  "maxDurationSeconds",
+  "maxInputBytes",
+  "maxOutputBytes",
+] as const;
+const optionalLimitKeys = [
+  "maxUnits",
+  "maxMediaDurationSeconds",
+  "maxArtifacts",
+  "maxPixelsPerArtifact",
+] as const;
+
+/** Pure contract guard shared by Manifest composition and Host projection. */
+export function validAiOperationReadinessRequirementV1(
+  requirement: unknown,
+): requirement is AiOperationReadinessRequirementV1 {
+  if (!isRecord(requirement)) return false;
+  return (
+    requirement.schemaVersion === AI_RUNTIME_READINESS_SCHEMA_VERSION &&
+    validStableKey(requirement.operationKey) &&
+    typeof requirement.runtimeKind === "string" &&
+    runtimeKinds.has(requirement.runtimeKind) &&
+    validDeployment(requirement.expectedDeployment) &&
+    (requirement.variant === undefined ||
+      validStableKey(requirement.variant)) &&
+    validStableKeyList(
+      requirement.requiredCapabilities,
+      AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1,
+    ) &&
+    validModalities(requirement.inputModalities) &&
+    validModalities(requirement.outputModalities) &&
+    validLimits(requirement.limits) &&
+    validResources(requirement.resources)
+  );
+}
+
+function validDeployment(value: unknown): value is AiRuntimeDeploymentV1 {
+  return (
+    isRecord(value) &&
+    validStableKey(value.key) &&
+    typeof value.identity === "string" &&
+    deploymentIdentityPattern.test(value.identity) &&
+    typeof value.releaseDigest === "string" &&
+    digestPattern.test(value.releaseDigest) &&
+    typeof value.offersDigest === "string" &&
+    digestPattern.test(value.offersDigest)
+  );
+}
+
+function validStableKey(value: unknown): value is string {
+  return typeof value === "string" && stableKeyPattern.test(value);
+}
+
+function validStableKeyList(value: unknown, maximum: number): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= maximum &&
+    value.every(validStableKey) &&
+    new Set(value).size === value.length
+  );
+}
+
+function validModalities(value: unknown): boolean {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.length <= AI_RUNTIME_MODALITIES_V1.length &&
+    value.every(
+      (item) => typeof item === "string" && runtimeModalities.has(item),
+    ) &&
+    new Set(value).size === value.length
+  );
+}
+
+function validLimits(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return (
+    requiredLimitKeys.every((key) => positiveSafeInteger(value[key])) &&
+    optionalLimitKeys.every(
+      (key) => value[key] === undefined || positiveSafeInteger(value[key]),
+    )
+  );
+}
+
+function validResources(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    positiveSafeInteger(value.minConcurrentRuns) &&
+    nonNegativeSafeInteger(value.minQueueDepth)
+  );
+}
+
+function positiveSafeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && Number(value) > 0;
+}
+
+function nonNegativeSafeInteger(value: unknown): boolean {
+  return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/license-catalog.ts

@@ -81,20 +81,25 @@ export function parseLicenseCatalog(
     if (unknownField) {
       throw new Error(`License 版本目录包含未知字段：${unknownField}`);
     }
+    const description = record.description;
+    const key = record.key;
+    const label = record.label;
+    const order = record.order;
     if (
-      typeof record.key !== "string" ||
-      typeof record.label !== "string" ||
-      (record.description !== undefined &&
-        typeof record.description !== "string") ||
-      typeof record.order !== "number"
+      typeof key !== "string" ||
+      typeof label !== "string" ||
+      (description !== undefined && typeof description !== "string") ||
+      typeof order !== "number"
     ) {
       throw new Error(`License 版本目录第 ${index + 1} 项字段类型无效`);
     }
+    const normalizedDescription =
+      typeof description === "string" ? description.trim() : "";
     return {
-      key: licenseVersionKey(record.key.trim()),
-      label: record.label.trim(),
-      description: record.description?.trim() ?? "",
-      order: record.order,
+      key: licenseVersionKey(key.trim()),
+      label: label.trim(),
+      description: normalizedDescription,
+      order,
     };
   });
   validateLicenseCatalog(catalog);

package/src/screenshot-context-digest.ts

@@ -0,0 +1,72 @@
+import type { JsonValue } from "./json.js";
+
+const MAX_DEPTH = 32;
+const MAX_NODES = 4_096;
+const MAX_CANONICAL_BYTES = 256 * 1_024;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+
+export type ScreenshotContextDigestV1 = `sha256:${string}`;
+
+/** Web/Host 共用的稳定 JSON：object key 排序，array 顺序与 JSON 数值语义保持不变。 */
+export function canonicalizeScreenshotContextV1(value: JsonValue): string {
+  let nodes = 0;
+  const visit = (item: JsonValue, depth: number): string => {
+    nodes += 1;
+    if (nodes > MAX_NODES || depth > MAX_DEPTH) {
+      throw new Error("Screenshot context 超过稳定摘要边界");
+    }
+    if (
+      item === null ||
+      typeof item === "boolean" ||
+      typeof item === "string"
+    ) {
+      return JSON.stringify(item);
+    }
+    if (typeof item === "number") {
+      if (!Number.isFinite(item))
+        throw new Error("Screenshot context 数值无效");
+      return JSON.stringify(item);
+    }
+    if (Array.isArray(item)) {
+      if (item.length > MAX_NODES) {
+        throw new Error("Screenshot context 数组超过稳定摘要边界");
+      }
+      return `[${item.map((entry) => visit(entry, depth + 1)).join(",")}]`;
+    }
+    const prototype = Object.getPrototypeOf(item);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error("Screenshot context 必须是 plain JSON");
+    }
+    const keys = Object.keys(item).sort();
+    return `{${keys
+      .map(
+        (key) =>
+          `${JSON.stringify(key)}:${visit(item[key] as JsonValue, depth + 1)}`,
+      )
+      .join(",")}}`;
+  };
+  const canonical = visit(value, 0);
+  if (new TextEncoder().encode(canonical).byteLength > MAX_CANONICAL_BYTES) {
+    throw new Error("Screenshot context 超过稳定摘要字节边界");
+  }
+  return canonical;
+}
+
+export async function computeScreenshotContextDigestV1(
+  value: JsonValue,
+): Promise<ScreenshotContextDigestV1> {
+  const bytes = new TextEncoder().encode(
+    canonicalizeScreenshotContextV1(value),
+  );
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  const hex = [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+  return `sha256:${hex}`;
+}
+
+export function isScreenshotContextDigestV1(
+  value: unknown,
+): value is ScreenshotContextDigestV1 {
+  return typeof value === "string" && DIGEST_PATTERN.test(value);
+}

package/src/stable-key.ts

@@ -0,0 +1,26 @@
+const STABLE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+
+export const STABLE_KEY_MAX_LENGTH = 128;
+
+export function isStableKey(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= STABLE_KEY_MAX_LENGTH &&
+    STABLE_KEY_PATTERN.test(value)
+  );
+}
+
+export function requireStableModuleKey(
+  kind: string,
+  value: unknown,
+  moduleName: string,
+): asserts value is string {
+  if (!isStableKey(value)) {
+    throw new Error(
+      `${kind}必须是最多 ${STABLE_KEY_MAX_LENGTH} 字符的小写稳定 Key`,
+    );
+  }
+  if (value !== moduleName && !value.startsWith(`${moduleName}.`)) {
+    throw new Error(`${kind}不属于模块 ${moduleName}：${value}`);
+  }
+}