create-windy 0.5.2 → 0.6.1

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

@@ -68,6 +68,21 @@ export interface ModuleProviderDefinition {
   featureKey?: string;
 }
 
+/**
+ * 模块可请求的逻辑 Secret。
+ *
+ * Manifest 只声明稳定业务标识与治理能力，不允许携带 env/file Provider 或物理 locator。
+ * 物理绑定由 project-owned Server Composition 持有。
+ */
+export interface ModuleSecretDefinition {
+  handle: string;
+  connection: string;
+  purpose: string;
+  permissionKey: string;
+  featureKey: string;
+  auditAction: AuditActionType;
+}
+
 export interface ModuleSchemaExportDefinition {
   key: string;
   exportName: string;
@@ -152,6 +167,34 @@ export interface AiOperationLimits {
   maxPixelsPerArtifact?: number;
 }
 
+/**
+ * 可选的 Runtime readiness V1 声明。缺失时保留旧 Operation 的兼容语义；
+ * 一旦声明，Host 必须以真实 downstream probe 投影后才允许执行。
+ */
+export interface AiOperationReadinessContractV1 {
+  readonly contractVersion: 1;
+  readonly variant: string;
+  readonly inputModalities: readonly AiOperationInputModality[];
+  readonly outputModalities: readonly (
+    | AiOperationInputModality
+    | "embedding"
+  )[];
+  readonly expectedDeployment: {
+    readonly key: string;
+    readonly identity: string;
+    readonly releaseDigest: `sha256:${string}`;
+    readonly offersDigest: `sha256:${string}`;
+  };
+  readonly minConcurrentRuns: number;
+  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;
@@ -162,6 +205,10 @@ export interface ModuleAiOperationDefinition {
   outputSchemaKey: string;
   /** 缺省为 text；声明 image 后才能提交图片 Artifact。 */
   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;
@@ -193,6 +240,7 @@ export interface ModuleManifest {
   tools: ModuleToolDefinition[];
   aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
+  secrets?: ModuleSecretDefinition[];
   dataPolicies?: DataGovernancePolicyDefinition[];
   auditActions: AuditActionRegistration[];
   metadata?: Record<string, unknown>;

package/template/packages/modules/src/secret-composition.test.ts

@@ -0,0 +1,308 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import { fixture } from "./composition-fixtures.test-support.js";
+import { validateModuleComposition } from "./composition.js";
+
+function withSecret(name = "archive") {
+  const module = fixture(name);
+  const auditAction = `${name}.secret.resolve`;
+  module.secrets = [
+    {
+      handle: `${name}.smb.password`,
+      connection: `${name}.smb.primary`,
+      purpose: `${name}.smb.read`,
+      featureKey: featureKey(`${name}.feature`),
+      permissionKey: `${name}.feature.read`,
+      auditAction,
+    },
+  ];
+  module.auditActions.push({
+    key: auditAction,
+    label: "解析连接凭据",
+    description: "为已授权连接解析凭据。",
+  });
+  return module;
+}
+
+describe("Module Secret Manifest 组合契约", () => {
+  test("只接受模块命名空间内的逻辑三元组", () => {
+    expect(() => validateModuleComposition([withSecret()])).not.toThrow();
+
+    for (const field of ["handle", "connection", "purpose"] as const) {
+      const module = withSecret();
+      module.secrets![0]![field] = `other.${field}`;
+      expect(() => validateModuleComposition([module])).toThrow(
+        `Secret ${field}不属于模块 archive：other.${field}`,
+      );
+    }
+  });
+
+  test("逻辑三元组必须使用 bounded stable key", () => {
+    const invalidValues = [
+      " archive.smb.password",
+      "archive.smb.password ",
+      "archive.smb\npassword",
+      "archive.smb\0password",
+      "archive/smb/password",
+      "file:/run/secrets/password",
+      "ARCHIVE_SMB_PASSWORD",
+      "archive..password",
+      `archive.${"x".repeat(121)}`,
+    ];
+
+    for (const field of ["handle", "connection", "purpose"] as const) {
+      for (const value of invalidValues) {
+        const module = withSecret();
+        module.secrets![0]![field] = value;
+        expect(() => validateModuleComposition([module])).toThrow(
+          `Secret ${field}必须是最多 128 字符的小写稳定 Key`,
+        );
+      }
+    }
+  });
+
+  test("拒绝物理 locator、重复 handle 与未知治理引用", () => {
+    const locator = withSecret();
+    Object.assign(locator.secrets![0]!, {
+      provider: "env",
+      locator: "ARCHIVE_PASSWORD",
+    });
+    expect(() => validateModuleComposition([locator])).toThrow(
+      "Manifest Secret 声明结构非法",
+    );
+
+    const duplicate = withSecret();
+    duplicate.secrets!.push({ ...duplicate.secrets![0]! });
+    expect(() => validateModuleComposition([duplicate])).toThrow(
+      "Secret handle Key 重复",
+    );
+
+    const unknown = withSecret();
+    unknown.secrets![0]!.permissionKey = "archive.missing.read";
+    expect(() => validateModuleComposition([unknown])).toThrow(
+      "引用了非本模块权限",
+    );
+  });
+
+  test("拒绝 symbol、non-enumerable、accessor 与 Proxy 隐藏字段", () => {
+    const marker = "file:/run/secrets/archive-password";
+    let reads = 0;
+    const candidates = [
+      defineHiddenSecret("locator", marker),
+      defineHiddenSecret(Symbol("locator"), marker, true),
+      defineAccessorSecret(marker, () => {
+        reads += 1;
+      }),
+      new Proxy(withSecret().secrets![0]!, {
+        ownKeys() {
+          reads += 1;
+          throw new Error(marker);
+        },
+      }),
+    ];
+
+    for (const candidate of candidates) {
+      const module = withSecret();
+      module.secrets = [candidate];
+      expect(() => validateModuleComposition([module])).toThrow(
+        "Manifest Secret 声明结构非法",
+      );
+    }
+    expect(reads).toBe(0);
+  });
+
+  test("拒绝 Secret 容器 accessor、Proxy、稀疏与额外字段且不执行 trap", () => {
+    const marker = "RAW_MARKER_SECRET_ARRAY";
+    let reads = 0;
+    const accessor = withSecret();
+    Object.defineProperty(accessor, "secrets", {
+      enumerable: true,
+      get() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const proxied = withSecret();
+    proxied.secrets = new Proxy(proxied.secrets!, {
+      ownKeys() {
+        reads += 1;
+        throw new Error(marker);
+      },
+    });
+    const sparse = withSecret();
+    sparse.secrets = Array(1);
+    const extra = withSecret();
+    Object.defineProperty(extra.secrets!, "locator", {
+      value: marker,
+      enumerable: false,
+    });
+
+    for (const module of [accessor, proxied, sparse, extra]) {
+      expect(() => validateModuleComposition([module])).toThrow(
+        "Manifest Secret 声明结构非法",
+      );
+      try {
+        validateModuleComposition([module]);
+      } catch (error) {
+        expect(String(error)).not.toContain(marker);
+      }
+    }
+    expect(reads).toBe(0);
+  });
+
+  test("组合结果持有不可变声明快照而非 live Manifest 对象", () => {
+    const module = withSecret();
+    const liveSecret = module.secrets![0]!;
+    const validated = validateModuleComposition([module]);
+    liveSecret.handle = "archive.changed.password";
+
+    const snapshot = validated.modules[0]!.secrets![0]!;
+    expect(snapshot.handle).toBe("archive.smb.password");
+    expect(Object.getPrototypeOf(snapshot)).toBeNull();
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(validated.modules[0]!.secrets)).toBe(true);
+  });
+
+  test("Secret 必须绑定同基础 Key Feature 与已注册 Audit Action", () => {
+    const feature = withSecret();
+    feature.features.push({
+      ...feature.features[0]!,
+      key: featureKey("archive.other"),
+    });
+    feature.secrets![0]!.featureKey = "archive.other";
+    expect(() => validateModuleComposition([feature])).toThrow(
+      "Secret archive.smb.password 的 Permission 基础 Key archive.feature 与 Feature archive.other 不一致",
+    );
+
+    const audit = withSecret();
+    audit.secrets![0]!.auditAction = "archive.secret.unregistered";
+    expect(() => validateModuleComposition([audit])).toThrow(
+      "引用了未注册审计动作",
+    );
+  });
+
+  test("多模块组合不能借用其它 Manifest 注册的治理能力", () => {
+    const borrowedFeature = featureKey("alpha.borrowed");
+    const borrowedPermission = "alpha.borrowed.read";
+    const borrowedAudit = "alpha.secret.borrowed";
+    const alpha = withSecret("alpha");
+    const beta = fixture("beta");
+    beta.features.push({
+      key: borrowedFeature,
+      label: "错误归属 Feature",
+      module: "beta",
+      visible: "visible",
+      enabled: true,
+      stage: "stable",
+    });
+    beta.permissions.push({
+      key: borrowedPermission,
+      label: "错误归属权限",
+      module: "beta",
+      resource: "connection",
+      action: "read",
+    });
+    beta.auditActions.push({
+      key: borrowedAudit,
+      label: "错误归属审计",
+      description: "由另一个 Manifest 注册。",
+    });
+
+    const borrowed = alpha.secrets![0]!;
+    borrowed.featureKey = borrowedFeature;
+    borrowed.permissionKey = borrowedPermission;
+
+    expect(() => validateModuleComposition([alpha, beta])).toThrow(
+      "Secret alpha.smb.password 引用了非本模块权限：alpha.borrowed.read",
+    );
+  });
+
+  test("分别拒绝只借用其它 Manifest 的 Permission 或 Feature", () => {
+    const borrowedFeature = featureKey("alpha.borrowed");
+    const borrowedPermission = "alpha.borrowed.read";
+
+    const permissionOwner = withSecret("alpha");
+    permissionOwner.features.push({
+      key: borrowedFeature,
+      label: "Alpha 自有 Feature",
+      module: "alpha",
+      visible: "visible",
+      enabled: true,
+      stage: "stable",
+    });
+    permissionOwner.secrets![0]!.featureKey = borrowedFeature;
+    permissionOwner.secrets![0]!.permissionKey = borrowedPermission;
+    const permissionLender = fixture("beta");
+    permissionLender.permissions.push({
+      key: borrowedPermission,
+      label: "错误归属权限",
+      module: "beta",
+      resource: "connection",
+      action: "read",
+    });
+    expect(() =>
+      validateModuleComposition([permissionOwner, permissionLender]),
+    ).toThrow("引用了非本模块权限：alpha.borrowed.read");
+
+    const featureOwner = withSecret("alpha");
+    featureOwner.permissions.push({
+      key: borrowedPermission,
+      label: "Alpha 自有权限",
+      module: "alpha",
+      resource: "connection",
+      action: "read",
+    });
+    featureOwner.secrets![0]!.featureKey = borrowedFeature;
+    featureOwner.secrets![0]!.permissionKey = borrowedPermission;
+    const featureLender = fixture("beta");
+    featureLender.features.push({
+      key: borrowedFeature,
+      label: "错误归属 Feature",
+      module: "beta",
+      visible: "visible",
+      enabled: true,
+      stage: "stable",
+    });
+    expect(() =>
+      validateModuleComposition([featureOwner, featureLender]),
+    ).toThrow("引用了非本模块 Feature：alpha.borrowed");
+  });
+
+  test("Secret Audit Action 即使全局存在也必须由本 Manifest 注册", () => {
+    const alpha = withSecret("alpha");
+    const beta = fixture("beta");
+    const borrowedAudit = "alpha.secret.borrowed";
+    beta.auditActions.push({
+      key: borrowedAudit,
+      label: "错误归属审计",
+      description: "由另一个 Manifest 注册。",
+    });
+    alpha.secrets![0]!.auditAction = borrowedAudit;
+
+    expect(() => validateModuleComposition([alpha, beta])).toThrow(
+      "Secret alpha.smb.password 引用了未注册审计动作：alpha.secret.borrowed",
+    );
+  });
+});
+
+function defineHiddenSecret(
+  key: PropertyKey,
+  value: string,
+  enumerable = false,
+) {
+  const secret = withSecret().secrets![0]!;
+  Object.defineProperty(secret, key, { value, enumerable });
+  return secret;
+}
+
+function defineAccessorSecret(marker: string, onRead: () => void) {
+  const secret = withSecret().secrets![0]!;
+  Object.defineProperty(secret, "handle", {
+    enumerable: true,
+    get() {
+      onRead();
+      throw new Error(marker);
+    },
+  });
+  return secret;
+}

package/template/packages/modules/src/secret-composition.ts

@@ -0,0 +1,176 @@
+import { requireStableModuleKey } from "@southwind-ai/shared";
+import type { ModuleManifest, ModuleSecretDefinition } from "./manifest.js";
+import { validateOwnedAuditAction } from "./capability-audit-validation.js";
+import { validateOwnedCapabilityGuard } from "./capability-guard-validation.js";
+
+const invalidSecretMessage = "Manifest Secret 声明结构非法";
+const maxSecretDeclarations = 256;
+const isRuntimeProxy = runtimeProxyDetector();
+const allowedSecretFields = new Set([
+  "handle",
+  "connection",
+  "purpose",
+  "permissionKey",
+  "featureKey",
+  "auditAction",
+]);
+
+export function validateSecretDeclarations(module: ModuleManifest): void {
+  for (const secret of snapshotModuleSecretDeclarations(module)) {
+    requireStableModuleKey("Secret handle", secret.handle, module.name);
+    requireStableModuleKey("Secret connection", secret.connection, module.name);
+    requireStableModuleKey("Secret purpose", secret.purpose, module.name);
+    requireStableModuleKey("Secret Feature", secret.featureKey, module.name);
+    requireStableModuleKey(
+      "Secret Permission",
+      secret.permissionKey,
+      module.name,
+    );
+    requireStableModuleKey(
+      "Secret Audit Action",
+      secret.auditAction,
+      module.name,
+    );
+    validateOwnedCapabilityGuard(module, `Secret ${secret.handle}`, secret);
+    validateOwnedAuditAction(
+      module,
+      `Secret ${secret.handle}`,
+      secret.auditAction,
+    );
+  }
+}
+
+export function snapshotModuleManifestSecrets(
+  module: ModuleManifest,
+): ModuleManifest {
+  try {
+    if (!module || typeof module !== "object" || isRuntimeProxy(module)) {
+      invalidSecret();
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(module);
+    const secrets = snapshotSecretArray(descriptors.secrets);
+    const snapshot = Object.create(
+      Object.getPrototypeOf(module),
+    ) as ModuleManifest;
+    Object.defineProperties(snapshot, descriptors);
+    Object.defineProperty(snapshot, "secrets", {
+      value: secrets,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+    return Object.freeze(snapshot);
+  } catch {
+    throw new Error(invalidSecretMessage);
+  }
+}
+
+export function snapshotModuleSecretDeclarations(
+  module: ModuleManifest,
+): readonly ModuleSecretDefinition[] {
+  try {
+    if (!module || typeof module !== "object" || isRuntimeProxy(module)) {
+      invalidSecret();
+    }
+    return snapshotSecretArray(
+      Object.getOwnPropertyDescriptor(module, "secrets"),
+    );
+  } catch {
+    throw new Error(invalidSecretMessage);
+  }
+}
+
+function snapshotSecretArray(
+  descriptor: PropertyDescriptor | undefined,
+): readonly ModuleSecretDefinition[] {
+  if (!descriptor) return Object.freeze([]);
+  if (!isEnumerableDataDescriptor(descriptor)) invalidSecret();
+  const value = descriptor.value;
+  if (!Array.isArray(value) || isRuntimeProxy(value)) invalidSecret();
+  if (Object.getPrototypeOf(value) !== Array.prototype) invalidSecret();
+  const length = value.length;
+  if (length > maxSecretDeclarations) invalidSecret();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  if (
+    keys.length !== length + 1 ||
+    keys.some((key) => typeof key === "symbol")
+  ) {
+    invalidSecret();
+  }
+  const snapshot: ModuleSecretDefinition[] = [];
+  for (let index = 0; index < length; index += 1) {
+    const item = descriptors[String(index)];
+    if (!isEnumerableDataDescriptor(item)) invalidSecret();
+    snapshot[index] = snapshotSecret(item.value);
+  }
+  return Object.freeze(snapshot);
+}
+
+function snapshotSecret(candidate: unknown): ModuleSecretDefinition {
+  if (
+    !candidate ||
+    typeof candidate !== "object" ||
+    isRuntimeProxy(candidate)
+  ) {
+    invalidSecret();
+  }
+  const prototype = Object.getPrototypeOf(candidate);
+  if (prototype !== Object.prototype && prototype !== null) invalidSecret();
+  const descriptors = Object.getOwnPropertyDescriptors(candidate);
+  const keys = Reflect.ownKeys(descriptors);
+  if (
+    keys.length !== allowedSecretFields.size ||
+    keys.some((key) => typeof key !== "string" || !allowedSecretFields.has(key))
+  ) {
+    invalidSecret();
+  }
+  const snapshot = Object.create(null) as Record<string, string>;
+  for (const key of keys) {
+    if (
+      typeof key !== "string" ||
+      !isEnumerableDataDescriptor(descriptors[key]) ||
+      typeof descriptors[key].value !== "string"
+    ) {
+      invalidSecret();
+    }
+    Object.defineProperty(snapshot, key, {
+      value: descriptors[key].value,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  return Object.freeze(snapshot) as unknown as ModuleSecretDefinition;
+}
+
+function isEnumerableDataDescriptor(
+  descriptor: PropertyDescriptor | undefined,
+): descriptor is PropertyDescriptor & { value: unknown } {
+  return Boolean(
+    descriptor && descriptor.enumerable === true && "value" in descriptor,
+  );
+}
+
+function invalidSecret(): never {
+  throw new Error(invalidSecretMessage);
+}
+
+function runtimeProxyDetector(): (value: unknown) => boolean {
+  const runtimeProcess = (
+    globalThis as {
+      readonly process?: {
+        getBuiltinModule?(id: string): unknown;
+      };
+    }
+  ).process;
+  const utility = runtimeProcess?.getBuiltinModule?.("node:util") as
+    | {
+        readonly types?: {
+          isProxy?(value: unknown): boolean;
+        };
+      }
+    | undefined;
+  const detector = utility?.types?.isProxy;
+  return detector ? (value) => detector(value) : () => false;
+}

package/template/packages/modules/src/system-api-control-plane.ts

@@ -74,6 +74,9 @@ function aiRuntimeBindings(): ApiPermissionBinding[] {
     "/api/speech/runs/:runId/events",
     "/api/speech/runs/:runId/result",
     "/api/speech/runs/:runId/artifact",
+    "/api/embeddings/runs/:runId/events",
+    "/api/embeddings/runs/:runId/result",
+    "/api/internal/embeddings/runs/:runId/artifacts/:itemId",
     "/api/agent/runs/:runId/events",
     "/api/agent/runs/:runId/result",
   ].map((path) =>
@@ -92,9 +95,13 @@ function aiRuntimeBindings(): ApiPermissionBinding[] {
     "/api/speech/runs",
     "/api/speech/runs/:runId/cancel",
     "/api/embeddings",
+    "/api/embeddings/runs",
+    "/api/embeddings/runs/:runId/cancel",
     "/api/agent/runs",
     "/api/agent/runs/:runId/cancel",
     "/api/agent/runs/:runId/attach",
+    "/api/agent/screenshots",
+    "/api/agent/screenshots/:token/cancel",
     "/api/internal/agent/tools/execute",
   ].map((path) =>
     binding(
@@ -106,7 +113,16 @@ function aiRuntimeBindings(): ApiPermissionBinding[] {
       path.startsWith("/api/internal/"),
     ),
   );
-  return [...reports, ...read, ...execute];
+  const uploads = ["/api/agent/screenshots/:token"].map((path) =>
+    binding(
+      "PUT",
+      path,
+      "system.agent.read",
+      "system.agent",
+      "agent.operation.execute",
+    ),
+  );
+  return [...reports, ...read, ...execute, ...uploads];
 }
 // @windy-module system.agent end
 

package/template/packages/modules/src/system-module-catalog.test.ts

@@ -158,6 +158,58 @@ describe("系统能力模块目录", () => {
       ]),
     );
   });
+
+  test("Embedding Run API 声明用户 Guard 与内部 Artifact 边界", () => {
+    const agent = systemModuleManifests().find(
+      ({ name }) => name === "system.agent",
+    );
+    const bindings = new Map(
+      agent?.apiPermissions.map((binding) => [
+        `${binding.method} ${binding.path}`,
+        binding,
+      ]),
+    );
+    const guarded = {
+      permissionKey: "system.agent.read",
+      featureKey: "system.agent",
+      anonymous: false,
+    };
+
+    for (const route of [
+      "POST /api/embeddings/runs",
+      "POST /api/embeddings/runs/:runId/cancel",
+    ]) {
+      expect(bindings.get(route)).toEqual({
+        method: "POST",
+        path: route.slice("POST ".length),
+        ...guarded,
+        auditAction: "agent.operation.execute",
+      });
+    }
+    for (const route of [
+      "GET /api/embeddings/runs/:runId/result",
+      "GET /api/embeddings/runs/:runId/events",
+    ]) {
+      expect(bindings.get(route)).toEqual({
+        method: "GET",
+        path: route.slice("GET ".length),
+        ...guarded,
+        auditAction: "data.read",
+      });
+    }
+    expect(
+      bindings.get(
+        "GET /api/internal/embeddings/runs/:runId/artifacts/:itemId",
+      ),
+    ).toEqual({
+      method: "GET",
+      path: "/api/internal/embeddings/runs/:runId/artifacts/:itemId",
+      permissionKey: "system.agent.read",
+      featureKey: "system.agent",
+      auditAction: "data.read",
+      anonymous: true,
+    });
+  });
   // @windy-module system.agent end
 
   // @windy-module system.data-governance begin

package/template/packages/modules/src/system-module-catalog.ts

@@ -108,7 +108,7 @@ export const systemModuleDefinitions = [
     version: "0.1.0",
     label: "文件存储",
     description: "上传、续传、下载与对象生命周期管理。",
-    dependencies: ["system", "system.settings"],
+    dependencies: ["system", "system.settings", "system.scheduler"],
     resources: ["storage"],
     featureKeys: ["system.storage"],
     runtimeActivation: "physical-only",

package/template/packages/server-sdk/contracts/ai-runtime-readiness/v1/document-python-parity.json

@@ -0,0 +1,12 @@
+{
+  "maxOffers": 16,
+  "maxCapabilitiesPerOffer": 32,
+  "maxModalities": 6,
+  "maxSafeInteger": 9007199254740991,
+  "firstUnsafeInteger": 9007199254740992,
+  "integerNumbers": {
+    "acceptedJson": [1, 1.0, 9007199254740991],
+    "rejectedJson": [true, false, 1.5],
+    "rejectedNonFinite": ["NaN", "Infinity", "-Infinity"]
+  }
+}