create-windy 0.3.17 → 0.3.18

package/template/apps/server/src/module-host/durable-context.test.ts

@@ -5,7 +5,9 @@ import { buildActorScopeContexts } from "../data-access/context.js";
 import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
 import type { RequestActor } from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
+// @windy-module system.storage begin
 import { createStorageRuntime } from "../storage/runtime.js";
+// @windy-module system.storage end
 import { createModuleDurableContextualizer } from "./durable-context.js";
 import { initializeModuleHosts } from "./initialize.js";
 import { manifest } from "./test-fixtures.js";
@@ -82,6 +84,7 @@ describe("模块 Durable Handler 授权上下文", () => {
     ]);
   });
 
+  // @windy-module system.storage begin
   test("重启后按 requestedBy 重建 Actor 并允许同案跨上传者读取", async () => {
     const { contextualize, storage, actor, resolverCalls, runtime } =
       await setup();
@@ -131,7 +134,9 @@ describe("模块 Durable Handler 授权上下文", () => {
       }),
     );
   });
+  // @windy-module system.storage end
 
+  // @windy-module system.storage begin
   test("Scope 变化、权限撤销与资源绑定漂移均 fail-closed", async () => {
     const stable = currentActor();
     const scopeChanged = currentActor("self");
@@ -182,6 +187,7 @@ describe("模块 Durable Handler 授权上下文", () => {
       }),
     );
   });
+  // @windy-module system.storage end
 });
 
 async function setup(
@@ -220,7 +226,9 @@ async function setup(
       },
     ],
   });
+  // @windy-module system.storage begin
   const storage = createStorageRuntime({}, undefined, hosts.uploadPolicies);
+  // @windy-module system.storage end
   const runtime = createServerRuntime(
     { NODE_ENV: "test" },
     { featureCatalog: [evidenceFeature] },
@@ -228,14 +236,18 @@ async function setup(
   let calls = 0;
   return {
     actor: currentActor(),
+    // @windy-module system.storage begin
     storage,
+    // @windy-module system.storage end
     runtime,
     resolverCalls: () => calls,
     contextualize: createModuleDurableContextualizer({
       hosts,
       runtime,
       features: [evidenceFeature],
+      // @windy-module system.storage begin
       storage,
+      // @windy-module system.storage end
       backgroundAi,
       async resolveActor() {
         calls += 1;
@@ -283,6 +295,7 @@ function baseContext(attemptNumber: number): DurableHandlerContext {
   };
 }
 
+// @windy-module system.storage begin
 async function seedFile(storage: ReturnType<typeof createStorageRuntime>) {
   const bytes = new TextEncoder().encode("evidence");
   const sha256 = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
@@ -310,3 +323,4 @@ async function seedFile(storage: ReturnType<typeof createStorageRuntime>) {
   });
   return storage.uploads.complete(session.id, "user-uploader");
 }
+// @windy-module system.storage end

package/template/apps/server/src/module-host/durable-context.ts

@@ -21,6 +21,7 @@ import type { InitializedModuleHosts } from "./initialize.js";
 import {
   createModuleStoragePort,
   type ModuleStorageServices,
+  unavailableModuleStoragePort,
 } from "./storage-port.js";
 import { createModuleStorageScope } from "./storage-scope.js";
 import { toModuleActor } from "./request-context.js";
@@ -29,7 +30,7 @@ export interface ModuleDurableContextServices {
   readonly hosts: InitializedModuleHosts;
   readonly runtime: ReturnType<typeof createServerRuntime>;
   readonly features: readonly FeatureFlagDefinition[];
-  readonly storage: ModuleStorageServices;
+  readonly storage?: ModuleStorageServices;
   readonly backgroundAi?: {
     create(
       moduleName: string,
@@ -75,20 +76,21 @@ export function createModuleDurableContextualizer(
       request,
       actor,
     );
-    const storage = createModuleStoragePort(
-      services.storage,
-      createModuleStorageScope({
-        moduleName: input.moduleName,
-        purposes: services.hosts.uploadPurposesOf(input.moduleName),
-        resourceFileAccessPolicies: services.hosts.resourceFileAccessPoliciesOf(
-          input.moduleName,
-        ),
-        guardContext,
-        runtime: services.runtime,
-        features: services.features,
-        signal: input.context.signal,
-      }),
-    );
+    const storage = services.storage
+      ? createModuleStoragePort(
+          services.storage,
+          createModuleStorageScope({
+            moduleName: input.moduleName,
+            purposes: services.hosts.uploadPurposesOf(input.moduleName),
+            resourceFileAccessPolicies:
+              services.hosts.resourceFileAccessPoliciesOf(input.moduleName),
+            guardContext,
+            runtime: services.runtime,
+            features: services.features,
+            signal: input.context.signal,
+          }),
+        )
+      : unavailableModuleStoragePort(input.moduleName);
     const moduleContext: ModuleDurableHandlerContext = {
       ...input.context,
       actor: toModuleActor(actor),

package/template/apps/server/src/module-host/request-context.test.ts

@@ -3,7 +3,12 @@ import {
   buildActorScopeContexts,
   buildScopeContext,
 } from "../data-access/context.js";
-import type { RequestActor } from "../guards.js";
+import {
+  // @windy-module system.agent begin
+  bindModuleUserProjection,
+  // @windy-module system.agent end
+  type RequestActor,
+} from "../guards.js";
 import { createServerRuntime } from "../runtime.js";
 import { manifest } from "./test-fixtures.js";
 import {
@@ -73,6 +78,30 @@ describe("模块 Actor 运行时边界", () => {
     ).toThrow("不是由当前宿主颁发");
   });
 
+  // @windy-module system.agent begin
+  test("开发调试委托只向业务 Module 投影真实用户，核心主体保持不变", () => {
+    const requestActor = bindModuleUserProjection(
+      {
+        id: "service_adk_debug",
+        type: "service",
+        name: "ADK 开发调试",
+        roleCodes: ["adk-debug"],
+        permissionKeys: ["analysis.copilot.execute"],
+      },
+      "user_dev_admin",
+    );
+
+    const actor = toModuleActor(requestActor);
+
+    expect(actor).toMatchObject({
+      id: "user_dev_admin",
+      type: "user",
+      name: "ADK 开发调试",
+    });
+    expect(requestActorFromModule(actor)).toBe(requestActor);
+  });
+  // @windy-module system.agent end
+
   test("模块提交任务时由宿主持久化 Actor 与 nominal Scope 快照", async () => {
     const submissions: unknown[] = [];
     const actor: RequestActor = {

package/template/apps/server/src/module-host/request-context.ts

@@ -19,6 +19,9 @@ import type { AuditEvent } from "@southwind-ai/shared";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import {
   auditActor,
+  // @windy-module system.agent begin
+  projectedModuleUserId,
+  // @windy-module system.agent end
   type RequestActor,
   type RequestGuardContext,
 } from "../guards.js";
@@ -38,9 +41,9 @@ const requestActorByModuleView = new WeakMap<object, RequestActor>();
  * 联系方式与数据范围令牌在运行时通过属性枚举泄漏给业务模块。
  */
 export function toModuleActor(actor: RequestActor): ModuleActor {
+  const identity = moduleActorIdentity(actor);
   const view: ModuleActor = Object.freeze({
-    id: actor.id,
-    type: actor.type,
+    ...identity,
     name: actor.name,
     ...(actor.username ? { username: actor.username } : {}),
     ...(actor.displayName ? { displayName: actor.displayName } : {}),
@@ -51,6 +54,16 @@ export function toModuleActor(actor: RequestActor): ModuleActor {
   return view;
 }
 
+function moduleActorIdentity(
+  actor: RequestActor,
+): Pick<ModuleActor, "id" | "type"> {
+  // @windy-module system.agent begin
+  const userId = projectedModuleUserId(actor);
+  if (userId) return { id: userId, type: "user" };
+  // @windy-module system.agent end
+  return { id: actor.id, type: actor.type };
+}
+
 /**
  * Host 内部适配器通过对象身份恢复原始 Actor，使平台内置模块仍能复用宿主的数据
  * 范围执行链；原始 Actor 不作为 SDK 字段下发，外部业务包也无法访问该映射。

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

@@ -180,7 +180,7 @@ function forbiddenResourceFile(): UploadError {
 export function unavailableModuleStoragePort(
   moduleName: string,
 ): ModuleStoragePort {
-  const fail = (): never => {
+  const fail = async (): Promise<never> => {
     throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
   };
   return {

package/template/apps/server/src/platform-bootstrap.ts

@@ -0,0 +1,16 @@
+import { loadPlatformConfig } from "@southwind-ai/config";
+import pino from "pino";
+import { createServerPersistence } from "./persistence.js";
+
+export function createPlatformBootstrap() {
+  const logger = pino({ name: "windy-server" });
+  const platformConfig = loadPlatformConfig();
+  const persistence = createServerPersistence(
+    process.env,
+    (status) => {
+      logger.error({ audit: status }, "审计持久化进入降级状态");
+    },
+    platformConfig,
+  );
+  return { logger, persistence, platformConfig };
+}

package/template/apps/server/src/runtime-adk-debug.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { buildActorScopeContexts } from "./data-access/context.js";
+import { projectedModuleUserId, type RequestActor } from "./guards.js";
+import { createAdkDebugRuntime } from "./runtime-adk-debug.js";
+
+const token = "debug-token-012345678901234567890123";
+
+describe("ADK Web 专用调试身份", () => {
+  test("只在 canonical Run 路径委托真实用户并收窄权限", async () => {
+    const runtime = createRuntime();
+    expect(
+      runtime.claimsRequest(request("/api/foundation", "GET", token)),
+    ).toBeTrue();
+    const actor = await runtime.resolveRequest(
+      request("/api/agent/runs", "POST", token),
+    );
+
+    expect(actor).toMatchObject({
+      id: "service_adk_debug",
+      type: "service",
+      roleCodes: ["adk-debug"],
+      permissionKeys: ["customer.copilot.execute", "customer.records.read"],
+    });
+    expect(actor && projectedModuleUserId(actor)).toBe("user_dev_admin");
+    expect(actor?.scopeContext?.actorId).toBe("user_dev_admin");
+    expect(actor?.permissionKeys).not.toContain("customer.admin.manage");
+    expect(
+      await runtime.resolveRequest(request("/api/foundation", "GET", token)),
+    ).toBeUndefined();
+    expect(
+      await runtime.resolveRequest(
+        request("/api/agent/runs/run_1/result", "GET"),
+      ),
+    ).toBeUndefined();
+  });
+
+  test("持久 Run 的 Tool Host 可恢复同一个受限身份", async () => {
+    const runtime = createRuntime();
+
+    expect(
+      (await runtime.resolveActor("service_adk_debug"))?.permissionKeys,
+    ).toEqual(["customer.copilot.execute", "customer.records.read"]);
+    expect(runtime.operationForActor("service_adk_debug")).toBe(
+      "customer.copilot.global",
+    );
+    expect(await runtime.resolveActor("user_dev_admin")).toBeUndefined();
+  });
+
+  test("数据用户不存在或本身缺少闭包权限时拒绝委托", async () => {
+    expect(
+      await createRuntime({ dataActor: undefined }).resolveRequest(
+        request("/api/agent/runs", "POST", token),
+      ),
+    ).toBeUndefined();
+    expect(
+      await createRuntime({
+        dataActor: actor(["customer.copilot.execute"]),
+      }).resolveRequest(request("/api/agent/runs", "POST", token)),
+    ).toBeUndefined();
+    expect(
+      await createRuntime({
+        dataActor: { ...actor(), id: "user_other" },
+      }).resolveRequest(request("/api/agent/runs", "POST", token)),
+    ).toBeUndefined();
+  });
+
+  test("非开发环境、短 Token、未知 Operation 和未知 Tool 均 fail closed", async () => {
+    expect(
+      await createAdkDebugRuntime(
+        {
+          NODE_ENV: "production",
+          WINDY_ADK_DEBUG_OPERATION_KEY: "customer.copilot.global",
+          WINDY_ADK_DEBUG_DATA_ACTOR_ID: "user_dev_admin",
+          WINDY_ADK_DEBUG_TOKEN: token,
+        },
+        [manifest()],
+      ).resolveRequest(request("/api/agent/runs", "POST", token)),
+    ).toBeUndefined();
+    expect(() =>
+      createAdkDebugRuntime(
+        {
+          NODE_ENV: "development",
+          WINDY_ADK_DEBUG_OPERATION_KEY: "customer.copilot.global",
+          WINDY_ADK_DEBUG_DATA_ACTOR_ID: "user_dev_admin",
+          WINDY_ADK_DEBUG_TOKEN: "short",
+        },
+        [manifest()],
+        () => actor(),
+      ),
+    ).toThrow("至少 32");
+    expect(() =>
+      createAdkDebugRuntime(
+        {
+          NODE_ENV: "development",
+          WINDY_ADK_DEBUG_OPERATION_KEY: "customer.copilot.global",
+          WINDY_ADK_DEBUG_DATA_ACTOR_ID: "user_dev_admin",
+          WINDY_ADK_DEBUG_TOKEN: token,
+          AGENT_SERVER_INTERNAL_TOKEN: token,
+        },
+        [manifest()],
+        () => actor(),
+      ),
+    ).toThrow("内部服务 Token");
+    expect(() => createRuntime({ operationKey: "customer.unknown" })).toThrow(
+      "Operation 必须唯一存在",
+    );
+    expect(() =>
+      createRuntime({ allowedToolKeys: ["customer.unknown"] }),
+    ).toThrow("Tool 必须唯一存在");
+  });
+});
+
+function createRuntime(
+  overrides: {
+    operationKey?: string;
+    allowedToolKeys?: string[];
+    dataActor?: RequestActor;
+  } = {},
+) {
+  const dataActor = Object.hasOwn(overrides, "dataActor")
+    ? overrides.dataActor
+    : actor();
+  return createAdkDebugRuntime(
+    {
+      NODE_ENV: "development",
+      WINDY_ADK_DEBUG_OPERATION_KEY:
+        overrides.operationKey ?? "customer.copilot.global",
+      WINDY_ADK_DEBUG_DATA_ACTOR_ID: "user_dev_admin",
+      WINDY_ADK_DEBUG_TOKEN: token,
+    },
+    [manifest(overrides.allowedToolKeys)],
+    (actorId) => (actorId === "user_dev_admin" ? dataActor : undefined),
+  );
+}
+
+function actor(
+  permissionKeys = [
+    "customer.copilot.execute",
+    "customer.records.read",
+    "customer.admin.manage",
+  ],
+): RequestActor {
+  return {
+    id: "user_dev_admin",
+    type: "user",
+    name: "开发管理员",
+    displayName: "开发管理员",
+    roleCodes: ["super-admin"],
+    permissionKeys,
+    ...buildActorScopeContexts("user_dev_admin", "dept_platform", [
+      {
+        id: "role_super_admin",
+        code: "super-admin",
+        dataScope: "all",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function request(path: string, method: string, bearer = "") {
+  return new Request(`http://localhost${path}`, {
+    method,
+    headers: bearer ? { authorization: `Bearer ${bearer}` } : undefined,
+  });
+}
+
+function manifest(
+  allowedToolKeys = ["customer.records.search"],
+): ModuleManifest {
+  return {
+    name: "customer",
+    version: "0.1.0",
+    label: "客户",
+    description: "客户",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      permission("customer.copilot.execute"),
+      permission("customer.records.read"),
+      permission("customer.admin.manage"),
+    ],
+    apiPermissions: [],
+    features: [],
+    migrations: [],
+    schemaExports: [],
+    tasks: [],
+    tools: [
+      {
+        key: "customer.records.search",
+        label: "查询记录",
+        description: "查询记录",
+        inputSchemaKey: "customer.records.input.v1",
+        outputSchemaKey: "customer.records.output.v1",
+        operation: "query",
+        permissionKey: "customer.records.read",
+        featureKey: "customer.records",
+        auditAction: "customer.records.read",
+        scopeMode: "request",
+        dataClassification: "internal",
+        idempotency: "none",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 10,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
+      },
+    ],
+    aiOperations: [
+      {
+        key: "customer.copilot.global",
+        kind: "agent",
+        featureKey: "customer.copilot",
+        permissionKey: "customer.copilot.execute",
+        auditAction: "customer.copilot.execute",
+        inputSchemaKey: "customer.copilot.input.v1",
+        outputSchemaKey: "customer.copilot.output.v1",
+        requiredCapabilities: ["text-generation"],
+        allowedToolKeys,
+        dataClassification: "internal",
+        execution: "streaming",
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4096,
+          maxOutputBytes: 4096,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: [],
+  };
+}
+
+function permission(key: string) {
+  return {
+    key,
+    label: key,
+    module: "customer",
+    moduleLabel: "客户",
+    resource: key,
+    resourceLabel: key,
+    action: "manage" as const,
+  };
+}

package/template/apps/server/src/runtime-adk-debug.ts

@@ -0,0 +1,158 @@
+import { timingSafeEqual } from "node:crypto";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { readBearerToken } from "./auth/bearer-token.js";
+import { isServerScopeContext } from "./data-access/context.js";
+import { loadFoundationModules } from "./foundation.js";
+import { bindModuleUserProjection, type RequestActor } from "./guards.js";
+
+const debugActorId = "service_adk_debug";
+const minimumTokenBytes = 32;
+
+export type AdkDebugActorResolver = (
+  actorId: string,
+) => Promise<RequestActor | undefined> | RequestActor | undefined;
+
+export function createAdkDebugRuntime(
+  env: Record<string, string | undefined>,
+  modules: readonly ModuleManifest[] = loadFoundationModules(),
+  actorResolver?: AdkDebugActorResolver,
+) {
+  const operationKey = env.WINDY_ADK_DEBUG_OPERATION_KEY?.trim();
+  if (env.NODE_ENV !== "development" || !operationKey) {
+    return disabledRuntime();
+  }
+  const dataActorId = env.WINDY_ADK_DEBUG_DATA_ACTOR_ID?.trim();
+  if (!dataActorId) {
+    throw new Error("ADK Web 调试必须选择真实开发数据用户");
+  }
+  if (!actorResolver) {
+    throw new Error("ADK Web 调试数据用户解析器未配置");
+  }
+  const token = env.WINDY_ADK_DEBUG_TOKEN?.trim();
+  if (!token || Buffer.byteLength(token) < minimumTokenBytes) {
+    throw new Error("ADK Web 调试 Token 必须至少 32 字节");
+  }
+  const internalToken = env.AGENT_SERVER_INTERNAL_TOKEN?.trim();
+  if (internalToken && secureEqual(token, internalToken)) {
+    throw new Error("ADK Web 调试 Token 不能复用 Agent 内部服务 Token");
+  }
+  const permissionKeys = resolvePermissionClosure(modules, operationKey);
+  const claimsRequest = (request: Request) => {
+    const provided = readBearerToken(request);
+    return Boolean(provided && secureEqual(provided, token));
+  };
+
+  return {
+    claimsRequest,
+    async resolveRequest(request: Request): Promise<RequestActor | undefined> {
+      if (!claimsRequest(request) || !isCanonicalRunRequest(request)) {
+        return undefined;
+      }
+      return resolveDelegatedActor(actorResolver, dataActorId, permissionKeys);
+    },
+    async resolveActor(actorId: string): Promise<RequestActor | undefined> {
+      return actorId === debugActorId
+        ? resolveDelegatedActor(actorResolver, dataActorId, permissionKeys)
+        : undefined;
+    },
+    operationForActor(actorId: string): string | undefined {
+      return actorId === debugActorId ? operationKey : undefined;
+    },
+    usesToken(candidate: string | undefined): boolean {
+      return Boolean(candidate && secureEqual(candidate, token));
+    },
+  };
+}
+
+async function resolveDelegatedActor(
+  resolver: AdkDebugActorResolver,
+  dataActorId: string,
+  permissionKeys: string[],
+): Promise<RequestActor | undefined> {
+  const user = await resolver(dataActorId);
+  if (
+    !user ||
+    user.id !== dataActorId ||
+    user.type !== "user" ||
+    !isServerScopeContext(user.scopeContext) ||
+    user.scopeContext.actorId !== user.id ||
+    !permissionKeys.every((key) => user.permissionKeys.includes(key))
+  ) {
+    return undefined;
+  }
+  return bindModuleUserProjection(
+    {
+      id: debugActorId,
+      type: "service",
+      name: "ADK 开发调试",
+      displayName: `ADK 开发调试（${user.displayName || user.name}）`,
+      roleCodes: ["adk-debug"],
+      permissionKeys: [...permissionKeys],
+      dataAccess: user.dataAccess,
+      scopeContext: user.scopeContext,
+    },
+    user.id,
+  );
+}
+
+function resolvePermissionClosure(
+  modules: readonly ModuleManifest[],
+  operationKey: string,
+): string[] {
+  const operations = modules.flatMap((module) =>
+    (module.aiOperations ?? [])
+      .filter(({ key }) => key === operationKey)
+      .map((operation) => ({ module, operation })),
+  );
+  if (operations.length !== 1) {
+    throw new Error(`ADK Web 调试 Operation 必须唯一存在：${operationKey}`);
+  }
+  const [{ operation }] = operations;
+  if (operation.kind !== "agent") {
+    throw new Error(`ADK Web 只能调试 Agent Operation：${operationKey}`);
+  }
+  const toolPermissions = operation.allowedToolKeys.map((toolKey) => {
+    const tools = modules.flatMap((module) =>
+      module.tools.filter(({ key }) => key === toolKey),
+    );
+    if (tools.length !== 1) {
+      throw new Error(`ADK Web 调试 Tool 必须唯一存在：${toolKey}`);
+    }
+    return tools[0]!.permissionKey;
+  });
+  return [...new Set([operation.permissionKey, ...toolPermissions])];
+}
+
+function isCanonicalRunRequest(request: Request): boolean {
+  const path = new URL(request.url).pathname.replace(/\/+$/, "");
+  if (request.method === "POST" && path === "/api/agent/runs") return true;
+  const match = path.match(
+    /^\/api\/agent\/runs\/[^/]+\/(events|result|cancel|attach)$/,
+  );
+  if (!match) return false;
+  return match[1] === "events" || match[1] === "result"
+    ? request.method === "GET"
+    : request.method === "POST";
+}
+
+function secureEqual(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  return (
+    leftBytes.length === rightBytes.length &&
+    timingSafeEqual(leftBytes, rightBytes)
+  );
+}
+
+function disabledRuntime() {
+  return {
+    claimsRequest: (_request: Request): boolean => false,
+    resolveRequest: async (
+      _request: Request,
+    ): Promise<RequestActor | undefined> => undefined,
+    resolveActor: async (_actorId: string): Promise<RequestActor | undefined> =>
+      undefined,
+    operationForActor: (_actorId: string): string | undefined => undefined,
+    usesToken: (_candidate: string | undefined) => false,
+  };
+}