create-windy 0.6.0 → 0.6.2

package/template/packages/database/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/shared": "workspace:^",
+    "@southwind-ai/shared": "workspace:^0.2.5",
     "drizzle-orm": "^0.45.2"
   },
   "exports": {

package/template/packages/jobs/package.json

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/shared": "workspace:^",
+    "@southwind-ai/shared": "workspace:^0.2.5",
     "@southwind-ai/storage": "workspace:^"
   },
   "exports": {

package/template/packages/modules/index.ts

@@ -9,6 +9,7 @@ export * from "./src/system-module-catalog.js";
 export * from "./src/system-api-permissions.js";
 export * from "./src/tool-composition.js";
 export * from "./src/ai-network-policy.js";
+export * from "./src/ai-screenshot-context.js";
 export * from "./src/project-module-assembly.js";
 export * from "./src/module-host-range.js";
 export * from "./src/admin-ui-manifest.js";

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/src/ai-operation-composition.ts

@@ -4,6 +4,7 @@ import type {
 } from "./manifest.js";
 import { validateAiNetworkPolicy } from "./ai-network-policy.js";
 import { validateAiOperationReadinessContract } from "./ai-operation-readiness-contract.js";
+import { validateAiScreenshotContext } from "./ai-screenshot-context.js";
 
 interface AiOperationCatalogs {
   permissions: ReadonlySet<string>;
@@ -106,6 +107,7 @@ function validateOperation(
   validateProviderDataPolicy(operation);
   validateLimits(operation);
   validateAiOperationReadinessContract(operation);
+  validateAiScreenshotContext(operation);
 }
 
 const providerDataFields = new Set([

package/template/packages/modules/src/ai-screenshot-context.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { validateModuleComposition } from "./composition.js";
+import { fixture, operation } from "./ai-operation-composition.test-support.js";
+
+describe("AI Screenshot context composition", () => {
+  test("只允许 readiness Vision Operation 固定结构化 input pointer", () => {
+    const module = fixture("business");
+    const definition = operation("business.vision");
+    module.aiOperations = [
+      {
+        ...definition,
+        inputModalities: ["text", "image"],
+        requiredCapabilities: ["text-generation", "vision"],
+        limits: {
+          ...definition.limits,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 20_000_000,
+        },
+        readiness: readiness(),
+        screenshotContext: {
+          contractVersion: 1,
+          contextInputPointer: "/uiContext",
+        },
+      },
+    ];
+
+    expect(() => validateModuleComposition([module])).not.toThrow();
+    module.aiOperations[0] = {
+      ...module.aiOperations[0]!,
+      screenshotContext: {
+        contractVersion: 1,
+        contextInputPointer: "/uiContext/__proto__",
+      },
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "Screenshot context input JSON Pointer 无效",
+    );
+  });
+
+  test("文本 Operation 不能伪装 Screenshot context opt-in", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      {
+        ...operation("business.answer"),
+        screenshotContext: {
+          contractVersion: 1,
+          contextInputPointer: "/uiContext",
+        },
+      },
+    ];
+    expect(() => validateModuleComposition([module])).toThrow(
+      "只能绑定 readiness Vision Operation",
+    );
+  });
+});
+
+function readiness() {
+  return {
+    contractVersion: 1 as const,
+    variant: "vision",
+    inputModalities: ["text", "image"] as const,
+    outputModalities: ["text"] as const,
+    expectedDeployment: {
+      key: "ai.openai-compatible",
+      identity: "windy-deployment-v1_f31e8a65-92cb-4d03-8a77-3c1b5e9d4f04",
+      releaseDigest: `sha256:${"d".repeat(64)}` as const,
+      offersDigest: `sha256:${"e".repeat(64)}` as const,
+    },
+    minConcurrentRuns: 1,
+    minQueueDepth: 0,
+  };
+}

package/template/packages/modules/src/ai-screenshot-context.ts

@@ -0,0 +1,50 @@
+import type { ModuleAiOperationDefinition } from "./manifest.js";
+
+const MAX_POINTER_LENGTH = 256;
+
+export function validateAiScreenshotContext(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const binding = operation.screenshotContext;
+  if (!binding) return;
+  if (
+    binding.contractVersion !== 1 ||
+    operation.kind !== "agent" ||
+    !operation.inputModalities?.includes("image") ||
+    !operation.requiredCapabilities.includes("vision") ||
+    !operation.readiness
+  ) {
+    throw new Error(
+      `${operation.key} Screenshot context 只能绑定 readiness Vision Operation`,
+    );
+  }
+  parseAiScreenshotContextInputPointer(binding.contextInputPointer);
+}
+
+export function parseAiScreenshotContextInputPointer(
+  pointer: string,
+): readonly string[] {
+  if (
+    pointer.length > MAX_POINTER_LENGTH ||
+    !pointer.startsWith("/") ||
+    pointer === "/" ||
+    pointer.endsWith("/") ||
+    pointer.includes("//") ||
+    /~(?:[^01]|$)/u.test(pointer)
+  ) {
+    throw new Error("Screenshot context input JSON Pointer 无效");
+  }
+  const segments = pointer
+    .slice(1)
+    .split("/")
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+  if (
+    segments.some(
+      (segment) =>
+        !segment || ["__proto__", "prototype", "constructor"].includes(segment),
+    )
+  ) {
+    throw new Error("Screenshot context input JSON Pointer 无效");
+  }
+  return segments;
+}

package/template/packages/modules/src/manifest.ts

@@ -189,6 +189,12 @@ export interface AiOperationReadinessContractV1 {
   readonly minQueueDepth: number;
 }
 
+/** Host 对该 pointer 指向的结构化 Run input 重算 Screenshot context digest。 */
+export interface AiScreenshotContextBindingV1 {
+  readonly contractVersion: 1;
+  readonly contextInputPointer: string;
+}
+
 export interface ModuleAiOperationDefinition {
   key: string;
   kind: AiOperationKind;
@@ -201,6 +207,8 @@ export interface ModuleAiOperationDefinition {
   inputModalities?: readonly AiOperationInputModality[];
   /** additive V1：固定 variant、模态与不可变 deployment pin。 */
   readiness?: AiOperationReadinessContractV1;
+  /** 仅显式 opt-in 的 Vision Operation 可把 Screenshot Intake 绑定到结构化上下文。 */
+  screenshotContext?: AiScreenshotContextBindingV1;
   requiredCapabilities: readonly string[];
   allowedToolKeys: readonly string[];
   dataClassification: AiOperationDataClassification;

package/template/packages/server-sdk/package.json

@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@southwind-ai/jobs": "workspace:^",
-    "@southwind-ai/shared": "workspace:^",
+    "@southwind-ai/shared": "workspace:^0.2.5",
     "@southwind-ai/storage": "workspace:^"
   },
   "exports": {

package/template/packages/shared/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/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/screenshot-context-digest.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import {
+  canonicalizeScreenshotContextV1,
+  computeScreenshotContextDigestV1,
+  isScreenshotContextDigestV1,
+} from "./screenshot-context-digest.js";
+
+describe("Screenshot context digest V1", () => {
+  test("Web 与 Host 对 key 顺序不同的结构化上下文得到同一摘要", async () => {
+    const first = {
+      version: 1,
+      pageKey: "case.detail",
+      overlayStack: [{ title: "导入物证", kind: "dialog" }],
+    };
+    const reordered = {
+      overlayStack: [{ kind: "dialog", title: "导入物证" }],
+      pageKey: "case.detail",
+      version: 1,
+    };
+
+    expect(canonicalizeScreenshotContextV1(first)).toBe(
+      '{"overlayStack":[{"kind":"dialog","title":"导入物证"}],"pageKey":"case.detail","version":1}',
+    );
+    expect(await computeScreenshotContextDigestV1(first)).toBe(
+      "sha256:3e274a367806437443ac78bb6955445c5af2ba924f89d113ba6f652c1d6a3905",
+    );
+    expect(await computeScreenshotContextDigestV1(reordered)).toBe(
+      await computeScreenshotContextDigestV1(first),
+    );
+    expect(
+      isScreenshotContextDigestV1(
+        await computeScreenshotContextDigestV1(first),
+      ),
+    ).toBe(true);
+  });
+
+  test("拒绝非有限数值与非 plain JSON", async () => {
+    expect(() => canonicalizeScreenshotContextV1(Number.NaN)).toThrow(
+      "数值无效",
+    );
+    expect(() => canonicalizeScreenshotContextV1(new Date() as never)).toThrow(
+      "plain JSON",
+    );
+    expect(isScreenshotContextDigestV1(`sha256:${"A".repeat(64)}`)).toBe(false);
+  });
+});

package/template/packages/shared/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);
+}