@southwind-ai/shared 0.2.5 → 0.2.6

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.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

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