@southwind-ai/shared 0.2.5 → 0.2.7

package/index.ts

@@ -23,5 +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.5",
+  "version": "0.2.7",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/src/ai-runtime-report.ts

@@ -93,6 +93,18 @@ export interface AiRuntimeRunUsage {
   totalTokens: number | null;
 }
 
+/**
+ * 一个 Run 中实际观察到的模型与 deployment 组合。
+ *
+ * `model` 优先采用 Provider 回报的模型名；Provider 未回报时才保留请求模型。
+ * 排序遵循该组合首次出现的 Attempt 顺序，避免在报表投影时伪造执行顺序。
+ */
+export interface AiRuntimeRunModelDeployment {
+  deploymentKey: string;
+  model: string;
+  attemptCount: number;
+}
+
 export interface AiRuntimeRunListItem {
   runId: string;
   operationKey: string;
@@ -102,6 +114,8 @@ export interface AiRuntimeRunListItem {
   finishedAt: ISODateTime | null;
   durationMs: number | null;
   attemptCount: number;
+  modelDeployments: AiRuntimeRunModelDeployment[];
+  /** @deprecated 请使用包含 deployment 的 modelDeployments。 */
   models: string[];
   cacheStatus: AiRuntimeCacheStatus;
   usage: AiRuntimeRunUsage;
@@ -112,6 +126,11 @@ export interface AiRuntimeAttemptDetail extends AiRuntimeRunUsage {
   sequence: number;
   toolRound: number;
   deploymentKey: string;
+  /** 请求发送给 Provider 的模型名。 */
+  requestedModel: string;
+  /** Provider 响应中实际回报的模型名；缺失时不能推断。 */
+  reportedModel: string | null;
+  /** @deprecated 优先使用 reportedModel，缺失时使用 requestedModel。 */
   model: string;
   outcome: AiRuntimeAttemptOutcome;
   cacheStatus: AiRuntimeCacheStatus;

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);
+}