create-windy 0.6.0 → 0.6.2

package/template/apps/server/src/embedding/remote-runtime.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { computeAiRuntimeOffersDigestV1 } from "@southwind-ai/server-sdk";
 import {
   RemoteEmbeddingRuntime,
   unavailableEmbeddingRuntime,
@@ -81,4 +82,88 @@ describe("RemoteEmbeddingRuntime", () => {
       runtime.start(operation, "run-key", "embedding_server_bound"),
     ).resolves.toEqual({ runId: "embedding_server_bound" });
   });
+
+  test("deployment pin 漂移时在创建远端 Run 前失败关闭", async () => {
+    const pin = embeddingPin();
+    let starts = 0;
+    const runtime = new RemoteEmbeddingRuntime({
+      baseUrl: "http://embedding.internal",
+      internalToken: "token",
+      fetch: async (input) => {
+        const url = String(input);
+        if (url.endsWith("/health/ready")) {
+          return Response.json(
+            readinessSnapshot(pin, `sha256:${"f".repeat(64)}`),
+          );
+        }
+        starts += 1;
+        return Response.json({ runId: "embedding_server_bound" });
+      },
+    });
+
+    await expect(
+      runtime.start(
+        { ...operation, readinessPin: pin },
+        "run-key",
+        "embedding_server_bound",
+      ),
+    ).rejects.toMatchObject({ code: "RUNTIME_UNAVAILABLE" });
+    expect(starts).toBe(0);
+  });
 });
+
+function embeddingPin() {
+  const offersDigest = computeAiRuntimeOffersDigestV1([embeddingOffer()]);
+  return {
+    key: "embedding.primary",
+    identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+    releaseDigest: `sha256:${"a".repeat(64)}` as const,
+    offersDigest,
+  };
+}
+
+function readinessSnapshot(
+  pin: ReturnType<typeof embeddingPin>,
+  offersDigest = pin.offersDigest,
+) {
+  const now = new Date();
+  const checkedAt = now.toISOString();
+  const validUntil = new Date(now.getTime() + 60_000).toISOString();
+  const deployment = { ...pin, offersDigest };
+  return {
+    schemaVersion: 1,
+    status: "ready",
+    configured: true,
+    runtimeKind: "embedding",
+    observedAt: checkedAt,
+    downstreamProbe: {
+      status: "passed",
+      checkedAt,
+      validUntil,
+      latencyMs: 1,
+      deploymentIdentity: pin.identity,
+      releaseDigest: pin.releaseDigest,
+      offersDigest,
+    },
+    deployment,
+    offers: [embeddingOffer()],
+    unavailableReasons: [],
+  };
+}
+
+function embeddingOffer() {
+  return {
+    variant: "text",
+    capabilities: ["embedding.text"],
+    inputModalities: ["text"] as const,
+    outputModalities: ["embedding"] as const,
+    limits: {
+      maxDurationSeconds: 30,
+      maxInputBytes: 1024,
+      maxOutputBytes: 1024,
+      maxUnits: 10,
+      maxConcurrentRuns: 1,
+      maxQueueDepth: 0,
+    },
+  };
+}

package/template/apps/server/src/embedding/remote-runtime.ts

@@ -4,6 +4,7 @@ import {
   type EmbeddingRuntimeOperation,
   type EmbeddingRuntimePort,
 } from "./contracts.js";
+import { assertAiRuntimeReadinessPin } from "../ai-runtime-readiness/deployment-pin.js";
 
 export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
   readonly #baseUrl: string;
@@ -32,6 +33,7 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     idempotencyKey: string,
     signal?: AbortSignal,
   ): Promise<EmbeddingBatchResponse> {
+    await this.assertReadiness(request, signal);
     const response = await this.request("/api/embeddings", {
       method: "POST",
       headers: {
@@ -55,6 +57,7 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     runId: string,
     signal?: AbortSignal,
   ) {
+    await this.assertReadiness(request, signal);
     const response = await this.request("/api/embeddings/runs", {
       method: "POST",
       headers: {
@@ -125,6 +128,24 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
       return response;
     });
   }
+
+  private async assertReadiness(
+    request: EmbeddingRuntimeOperation,
+    signal?: AbortSignal,
+  ) {
+    if (!request.readinessPin) return;
+    try {
+      await assertAiRuntimeReadinessPin(request.readinessPin, () =>
+        this.health(signal),
+      );
+    } catch {
+      throw new EmbeddingRuntimeError(
+        "RUNTIME_UNAVAILABLE",
+        "Embedding Runtime readiness 已漂移",
+        true,
+      );
+    }
+  }
 }
 
 export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {

package/template/apps/server/src/embedding/run-fingerprint.test.ts

@@ -2,6 +2,12 @@ import { expect, test } from "bun:test";
 import { embeddingRunFingerprint } from "./run-fingerprint.js";
 
 test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与 options", async () => {
+  const pin = {
+    key: "embedding.primary",
+    identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+    releaseDigest: `sha256:${"a".repeat(64)}` as const,
+    offersDigest: `sha256:${"b".repeat(64)}` as const,
+  };
   const first = await embeddingRunFingerprint(
     "analysis.embedding.image",
     [
@@ -16,6 +22,7 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    pin,
   );
   const retry = await embeddingRunFingerprint(
     "analysis.embedding.image",
@@ -31,6 +38,7 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    pin,
   );
   const changed = await embeddingRunFingerprint(
     "analysis.embedding.image",
@@ -46,7 +54,25 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
+  );
+  const deploymentChanged = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-four",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
   );
   expect(retry).toBe(first);
   expect(changed).not.toBe(first);
+  expect(deploymentChanged).not.toBe(first);
 });

package/template/apps/server/src/embedding/run-fingerprint.ts

@@ -1,15 +1,24 @@
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
 import type { EmbeddingRuntimeItem } from "./contracts.js";
 
 export async function embeddingRunFingerprint(
   operationKey: string,
   items: readonly EmbeddingRuntimeItem[],
   options: ModuleAiJsonValue,
+  readinessPin?: AiRuntimeDeploymentV1,
 ) {
   const digest = await crypto.subtle.digest(
     "SHA-256",
     new TextEncoder().encode(
-      stableJson({ operationKey, items: items.map(stableItem), options }),
+      stableJson({
+        operationKey,
+        items: items.map(stableItem),
+        options,
+        ...(readinessPin ? { readinessPin } : {}),
+      }),
     ),
   );
   return [...new Uint8Array(digest)]

package/template/apps/server/src/module-host/ai-operation-port.test.ts

@@ -2,6 +2,65 @@ import { describe, expect, test } from "bun:test";
 import { createModuleAiOperationPort } from "./ai-operation-port.js";
 
 describe("Module AI Operation canonical result", () => {
+  test("Speech contract 只从 Manifest 重建 normalize 变体", async () => {
+    let received: unknown;
+    const port = createModuleAiOperationPort(
+      "analysis",
+      {} as never,
+      AbortSignal.timeout(1_000),
+      {
+        modules: [speechModule("normalize")],
+        speechFacade: {
+          async start(...args: unknown[]) {
+            received = args.at(-1);
+            return {
+              runId: "speech-1",
+              status: "accepted",
+              eventsUrl: "/events",
+            };
+          },
+        },
+      } as never,
+    );
+
+    await port.startSpeech({
+      operationKey: "analysis.audio.normalize",
+      source: {} as never,
+      options: { contractVersion: 2, variant: "translate" },
+      idempotencyKey: "speech-1",
+    });
+
+    expect(received).toEqual({ contractVersion: 2, variant: "normalize" });
+  });
+
+  test("Manifest Speech 变体未知时不触达 facade", async () => {
+    let called = false;
+    const port = createModuleAiOperationPort(
+      "analysis",
+      {} as never,
+      AbortSignal.timeout(1_000),
+      {
+        modules: [speechModule("forged")],
+        speechFacade: {
+          async start() {
+            called = true;
+            throw new Error("unreachable");
+          },
+        },
+      } as never,
+    );
+
+    await expect(
+      port.startSpeech({
+        operationKey: "analysis.audio.normalize",
+        source: {} as never,
+        options: {},
+        idempotencyKey: "speech-1",
+      }),
+    ).rejects.toMatchObject({ code: "AI_OPERATION_UNAVAILABLE" });
+    expect(called).toBe(false);
+  });
+
   test("只把尚未完成的 RUN_CONFLICT 映射为 pending", async () => {
     const port = agentPort(() =>
       Response.json(
@@ -50,6 +109,19 @@ describe("Module AI Operation canonical result", () => {
   });
 });
 
+function speechModule(variant: string) {
+  return {
+    name: "analysis",
+    aiOperations: [
+      {
+        key: "analysis.audio.normalize",
+        kind: "speech",
+        readiness: { contractVersion: 1, variant },
+      },
+    ],
+  } as never;
+}
+
 function agentPort(result: () => Response) {
   return createModuleAiOperationPort(
     "analysis",

package/template/apps/server/src/module-host/ai-operation-port.ts

@@ -1,4 +1,8 @@
 // @windy-module system.agent begin
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
 import type {
   ModuleAiJsonValue,
   ModuleAiOperationPort,
@@ -21,6 +25,7 @@ export interface ModuleAiRuntimeServices {
   readonly speechFacade: SpeechRunFacade;
   readonly speechRemote: SpeechRuntimePort;
   readonly embeddingFacade: EmbeddingFacade;
+  readonly modules: readonly ModuleManifest[];
 }
 
 export function createModuleAiOperationPort(
@@ -71,6 +76,11 @@ export function createModuleAiOperationPort(
     },
     async startSpeech(input) {
       own(input.operationKey);
+      const definition = ownSpeechDefinition(
+        services.modules,
+        moduleName,
+        input.operationKey,
+      );
       return services.speechFacade.start(
         input.operationKey,
         input.source,
@@ -78,6 +88,7 @@ export function createModuleAiOperationPort(
         input.idempotencyKey,
         context,
         signal,
+        speechContract(definition),
       );
     },
     async embed(input) {
@@ -150,6 +161,38 @@ export function createModuleAiOperationPort(
   };
 }
 
+function ownSpeechDefinition(
+  modules: readonly ModuleManifest[],
+  moduleName: string,
+  operationKey: string,
+): ModuleAiOperationDefinition {
+  const definition = modules
+    .find((module) => module.name === moduleName)
+    ?.aiOperations?.find((operation) => operation.key === operationKey);
+  if (!definition || definition.kind !== "speech") {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      "Speech Operation 当前不可用",
+    );
+  }
+  return definition;
+}
+
+function speechContract(definition: ModuleAiOperationDefinition) {
+  const variant = definition.readiness?.variant;
+  if (!variant) return {};
+  if (!["normalize", "transcribe", "translate"].includes(variant)) {
+    throw new ModuleAiOperationError(
+      "AI_OPERATION_UNAVAILABLE",
+      "Speech Operation contract 当前不可用",
+    );
+  }
+  return {
+    contractVersion: 2 as const,
+    variant: variant as "normalize" | "transcribe" | "translate",
+  };
+}
+
 async function responseJson(response: Response): Promise<ModuleAiJsonValue> {
   if (!response.ok) throw await responseError(response);
   return jsonValue(await response.json());

package/template/apps/server/src/module-host/ai-operation-speech-normalize.test.ts

@@ -0,0 +1,186 @@
+// @windy-module system.agent begin
+import { expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleAiOperationReadinessV1 } from "@southwind-ai/server-sdk";
+import { ExecutionGrantStore } from "../agent/execution-grants.js";
+import { createRequestGuardContext } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import type { SpeechRuntimeOperation } from "../speech/contracts.js";
+import { SpeechRunFacade } from "../speech/facade.js";
+import { speechOutputManifest } from "../speech/output-artifact-host.test-support.js";
+import type { SpeechOutputArtifactHost } from "../speech/output-artifact-host.js";
+import { createModuleAiOperationPort } from "./ai-operation-port.js";
+
+const operationKey = "evidence.audio.normalize";
+const deployment = {
+  key: "speech.primary",
+  identity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+  releaseDigest: `sha256:${"b".repeat(64)}` as const,
+  offersDigest: `sha256:${"c".repeat(64)}` as const,
+};
+
+test("Module Speech normalize 启用 Output Artifact 且调用方不能切换变体", async () => {
+  const module = normalizeModule();
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            { operationKey, prepareSpeech: (options) => ({ options }) },
+          ]);
+        },
+      },
+    ],
+  });
+  let invocation: SpeechRuntimeOperation | undefined;
+  let begun = 0;
+  const remote = {
+    async start(value: SpeechRuntimeOperation) {
+      invocation = value;
+      return { runId: value.runId!, status: "accepted", eventsUrl: "/events" };
+    },
+  } as never;
+  const output = {
+    hasBinding: () => true,
+    async begin(input: { invocation: SpeechRuntimeOperation }) {
+      begun += 1;
+      return {
+        runId: input.invocation.runId!,
+        scopeId: `outscope_${"a".repeat(32)}`,
+        grantGeneration: 1,
+        grant: "output-grant",
+        descriptor: {
+          contractVersion: 1,
+          scope: `outscope_${"a".repeat(32)}`,
+          outputKind: "normalized-audio",
+          deploymentIdentity: deployment.identity,
+          releaseDigest: deployment.releaseDigest,
+          offersDigest: deployment.offersDigest,
+          policyDigest: "d".repeat(64),
+          grantGeneration: 1,
+          allowedMediaTypes: ["audio/wav"],
+          expiresAt: "2030-01-01T00:00:00.000Z",
+          limits: {
+            maxArtifactBytes: 4_096,
+            maxArtifacts: 1,
+            maxTotalBytes: 4_096,
+          },
+        },
+      };
+    },
+    async confirmGrant() {
+      return true;
+    },
+  } as unknown as SpeechOutputArtifactHost;
+  const facade = new SpeechRunFacade(
+    [module],
+    hosts,
+    createServerRuntime({}, { featureCatalog: module.features }),
+    remote,
+    {
+      async rotate() {
+        return source("rotated");
+      },
+    } as never,
+    new ExecutionGrantStore(),
+    { inspect: async () => readyProjection() },
+    output,
+  );
+  const context = createRequestGuardContext(new Request("http://localhost"), {
+    resolveActor: () => ({
+      id: "actor-1",
+      type: "user",
+      name: "分析员",
+      roleCodes: [],
+      permissionKeys: [`${operationKey}.execute`],
+    }),
+    resolveLicense: () => ({ status: "valid" }),
+  });
+  const port = createModuleAiOperationPort(
+    "evidence",
+    context,
+    AbortSignal.timeout(1_000),
+    { modules: [module], speechFacade: facade } as never,
+  );
+
+  await port.startSpeech({
+    operationKey,
+    source: source("submitted"),
+    options: { contractVersion: 2, variant: "translate" },
+    idempotencyKey: "normalize-1",
+  });
+
+  expect(begun).toBe(1);
+  expect(invocation).toMatchObject({
+    contractVersion: 2,
+    variant: "normalize",
+    outputArtifactSink: { outputKind: "normalized-audio" },
+  });
+});
+
+function normalizeModule(): ModuleManifest {
+  const base = speechOutputManifest(operationKey);
+  const operation = base.aiOperations![0]!;
+  return {
+    ...base,
+    aiOperations: [
+      {
+        ...operation,
+        readiness: {
+          contractVersion: 1,
+          variant: "normalize",
+          inputModalities: ["audio"],
+          outputModalities: ["audio"],
+          expectedDeployment: deployment,
+          minConcurrentRuns: 1,
+          minQueueDepth: 0,
+        },
+      },
+    ],
+  };
+}
+
+function source(value: string) {
+  return {
+    value,
+    mediaType: "audio/wav",
+    byteSize: 128,
+    sha256: "e".repeat(64),
+    expiresAt: "2030-01-01T00:00:00.000Z",
+  };
+}
+
+function readyProjection(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "speech",
+    observedAt: new Date().toISOString(),
+    status: "ready",
+    validUntil: new Date(Date.now() + 60_000).toISOString(),
+    deployment,
+    offers: [
+      {
+        variant: "normalize",
+        capabilities: ["speech.normalize", "speech.output-artifact.v1"],
+        inputModalities: ["audio"],
+        outputModalities: ["audio"],
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxMediaDurationSeconds: 60,
+          maxArtifacts: 1,
+          maxConcurrentRuns: 1,
+          maxQueueDepth: 0,
+        },
+      },
+    ],
+    unavailableReasons: [],
+  };
+}
+// @windy-module system.agent end

package/template/apps/web/Dockerfile

@@ -23,7 +23,7 @@ COPY packages/server-sdk/package.json packages/server-sdk/package.json
 COPY packages/shared/package.json packages/shared/package.json
 COPY packages/storage/package.json packages/storage/package.json
 # windy-copy:deps end
-RUN --mount=type=cache,id=windy-bun-1.3.14,target=/root/.bun/install/cache,sharing=shared bun -e 'const child=Bun.spawn(["bun","install","--frozen-lockfile","--no-progress"],{stdin:"inherit",stdout:"inherit",stderr:"inherit"});const heartbeat=setInterval(()=>console.log("[windy] Bun 依赖安装仍在进行"),15000);const exitCode=await child.exited;clearInterval(heartbeat);process.exit(exitCode)'
+RUN --mount=type=cache,id=windy-bun-1.3.14,target=/root/.bun/install/cache,sharing=shared bun -e 'const child=Bun.spawn(["bun","install","--frozen-lockfile","--no-progress","--backend=copyfile","--linker=hoisted"],{stdin:"inherit",stdout:"inherit",stderr:"inherit"});const heartbeat=setInterval(()=>console.log("[windy] Bun 依赖安装仍在进行"),15000);const exitCode=await child.exited;clearInterval(heartbeat);process.exit(exitCode)'
 
 FROM deps AS build
 # windy-copy:build begin

package/template/docker-compose.yml

@@ -249,6 +249,9 @@ services:
       EMBEDDING_ADAPTER_URL: ${EMBEDDING_ADAPTER_URL:-}
       EMBEDDING_ADAPTER_TOKEN: ${EMBEDDING_ADAPTER_TOKEN:-}
       EMBEDDING_DEPLOYMENT_KEY: ${EMBEDDING_DEPLOYMENT_KEY:-}
+      EMBEDDING_DEPLOYMENT_IDENTITY: ${EMBEDDING_DEPLOYMENT_IDENTITY:-}
+      EMBEDDING_RELEASE_DIGEST: ${EMBEDDING_RELEASE_DIGEST:-}
+      EMBEDDING_OFFERS_DIGEST: ${EMBEDDING_OFFERS_DIGEST:-}
       EMBEDDING_DEPLOYMENT_ALIAS: ${EMBEDDING_DEPLOYMENT_ALIAS:-}
       EMBEDDING_MODEL: ${EMBEDDING_MODEL:-}
       EMBEDDING_MODEL_VERSION: ${EMBEDDING_MODEL_VERSION:-}
@@ -256,8 +259,16 @@ services:
       EMBEDDING_NORMALIZED: ${EMBEDDING_NORMALIZED:-true}
       EMBEDDING_CAPABILITIES: ${EMBEDDING_CAPABILITIES:-embedding.text}
       EMBEDDING_MAX_UNITS: ${EMBEDDING_MAX_UNITS:-256}
+      EMBEDDING_MAX_DURATION_SECONDS: ${EMBEDDING_MAX_DURATION_SECONDS:-600}
+      EMBEDDING_MAX_INPUT_BYTES: ${EMBEDDING_MAX_INPUT_BYTES:-268435456}
+      EMBEDDING_MAX_OUTPUT_BYTES: ${EMBEDDING_MAX_OUTPUT_BYTES:-268435456}
+      EMBEDDING_MAX_ARTIFACTS: ${EMBEDDING_MAX_ARTIFACTS:-16}
+      EMBEDDING_MAX_PIXELS_PER_ARTIFACT: ${EMBEDDING_MAX_PIXELS_PER_ARTIFACT:-100000000}
       EMBEDDING_RUN_ENCRYPTION_SECRET: ${EMBEDDING_RUN_ENCRYPTION_SECRET:-}
       EMBEDDING_MAX_CONCURRENT_RUNS: ${EMBEDDING_MAX_CONCURRENT_RUNS:-1}
+      EMBEDDING_MAX_QUEUE_DEPTH: ${EMBEDDING_MAX_QUEUE_DEPTH:-0}
+      EMBEDDING_READINESS_TIMEOUT_SECONDS: ${EMBEDDING_READINESS_TIMEOUT_SECONDS:-5}
+      EMBEDDING_READINESS_TTL_SECONDS: ${EMBEDDING_READINESS_TTL_SECONDS:-60}
       EMBEDDING_RUN_TERMINAL_TTL_SECONDS: ${EMBEDDING_RUN_TERMINAL_TTL_SECONDS:-604800}
     volumes:
       - embedding-run-data:/app/data/embedding

package/template/docs/architecture/ai-runtime-readiness.md

@@ -376,6 +376,12 @@ pin。Run admission 在 `remote.start` 前取得新的 VLM readiness pin；只
 以真实 canonical Run ID 终结绑定。上传重放、取消、未使用 TTL、scope/Operation/pin 漂移、
 factory 缺失或 producer 异常均会取消并失败关闭。
 
+Operation 可 additive 声明 Screenshot context V1 binding，把一个固定 JSON Pointer 指向
+schema-owned 的结构化 Run input。开启后，Host 使用 Web-safe canonical digest helper 对该值
+重算 `sha256:<64 lowercase hex>`，并与 intake 中持久化 digest 恒时比较；客户端单独提交的
+digest 或“verified”标志都不构成证明。缺失、非 object、漂移或重放只返回稳定安全 code，
+不会把页面或输入内容写入日志/审计。未 opt-in 的既有 V2 Operation 保留原安全边界。
+
 ## 四类 Runtime 的统一投影
 
 ### Document

package/template/docs/platform/vision-ai-runtime.md

@@ -1,6 +1,6 @@
 # Vision AI Runtime
 
-更新时间：2026-07-27。
+更新时间：2026-08-06。
 
 Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的图片 Artifact 输入，
 用于图片内容理解和结构化视觉提取。它不新增由业务选择模型的 `vision` kind：
@@ -28,6 +28,27 @@ Operation。Windy 不解析业务 DOM、Modal、表单正文或 URL，也不接
 Artifact、Run ID、文件路径或 Provider 信息；未知页面、上下文摘要漂移及未声明
 Operation 一律失败关闭。
 
+新 Operation 可通过 `screenshotContext.contractVersion=1` 和固定
+`contextInputPointer` 显式启用上下文同源证明。Web 对锁定时冻结的结构化 JSON 调用
+`@southwind-ai/shared` 的 `computeScreenshotContextDigestV1` 创建 intake；Run admission 不读取客户端自报的
+“已验证”字段，而是从 Manifest pointer 指向的 Run input 取值，用同一套 key 排序、array
+保序、UTF-8、SHA-256 算法重算，再与 token 中的 digest 恒时比较。pointer 缺失、值不是
+结构化 object、格式无效或内容漂移都会消费计划并返回稳定不可用错误；日志与审计不记录
+page、Modal、form 或 input 内容。
+
+```ts
+{
+  screenshotContext: {
+    contractVersion: 1,
+    contextInputPointer: "/uiContext"
+  }
+}
+```
+
+该字段是 additive opt-in：未声明它的 0.6.0 Screenshot Operation 仍保留原有
+Actor/scope/purpose/pin/TTL/一次性 token 边界；声明后的 Operation 才额外强制结构化上下文
+证明。项目迁移时应先让 Web 与 Run input 复用同一个冻结对象，再打开 Manifest binding。
+
 Host 以 60 秒 TTL 持久化 token 哈希、Actor/scope 绑定、Operation、专用 purpose、
 Deployment pin 与 Storage file binding。数据库不保存截图字节、Blob locator、Secret、
 页面正文或表单值。Server/Route 重启后，Host 会按当前 Actor/scope、Feature、Permission

package/template/package.json

@@ -83,10 +83,12 @@
     "@types/bun": "^1.3.14",
     "@types/pg": "^8.20.0",
     "drizzle-kit": "^0.31.10",
+    "drizzle-orm": "^0.45.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.1.1",
     "oxfmt": "^0.59.0",
     "oxlint": "^1.74.0",
+    "pg": "^8.22.0",
     "typescript": "5.9.3"
   },
   "dependencies": {}

package/template/packages/config/package.json

@@ -13,7 +13,7 @@
     "!src/**/*.test.ts"
   ],
   "dependencies": {
-    "@southwind-ai/shared": "workspace:^",
+    "@southwind-ai/shared": "workspace:^0.2.5",
     "zod": "^4.4.3"
   },
   "exports": {