create-windy 0.3.16 → 0.3.18

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

package/template/apps/server/src/runtime-request-actor.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import type { RequestActor } from "./guards.js";
+import { resolveRequestActor } from "./runtime-request-actor.js";
+
+const debugActor: RequestActor = {
+  id: "service_adk_debug",
+  type: "service",
+  name: "ADK 开发调试",
+  roleCodes: ["adk-debug"],
+  permissionKeys: ["analysis.copilot.execute"],
+};
+
+test("保留凭据命中后不回退普通认证", async () => {
+  let standardCalls = 0;
+  const request = new Request("http://localhost/api/foundation");
+  const actor = await resolveRequestActor(
+    request,
+    () => {
+      standardCalls += 1;
+      return {
+        id: "user_regular",
+        type: "user",
+        name: "普通用户",
+        roleCodes: ["user"],
+        permissionKeys: [],
+      };
+    },
+    {
+      claimsRequest: () => true,
+      resolveRequest: () => undefined,
+    },
+  );
+
+  expect(actor).toBeUndefined();
+  expect(standardCalls).toBe(0);
+});
+
+test("保留凭据在 canonical 路径始终解析为专用主体", async () => {
+  const actor = await resolveRequestActor(
+    new Request("http://localhost/api/agent/runs", { method: "POST" }),
+    () => ({
+      id: "user_regular",
+      type: "user",
+      name: "普通用户",
+      roleCodes: ["user"],
+      permissionKeys: ["analysis.copilot.execute"],
+    }),
+    {
+      claimsRequest: () => true,
+      resolveRequest: () => debugActor,
+    },
+  );
+
+  expect(actor).toBe(debugActor);
+});

package/template/apps/server/src/runtime-request-actor.ts

@@ -0,0 +1,22 @@
+import type { RequestActor } from "./guards.js";
+
+export interface ReservedRequestActorResolver {
+  claimsRequest(request: Request): boolean;
+  resolveRequest(
+    request: Request,
+  ): Promise<RequestActor | undefined> | RequestActor | undefined;
+}
+
+export async function resolveRequestActor(
+  request: Request,
+  resolveStandard: () =>
+    | Promise<RequestActor | undefined>
+    | RequestActor
+    | undefined,
+  reserved?: ReservedRequestActorResolver,
+): Promise<RequestActor | undefined> {
+  if (reserved?.claimsRequest(request)) {
+    return reserved.resolveRequest(request);
+  }
+  return resolveStandard();
+}

package/template/apps/server/src/runtime.test.ts

@@ -22,6 +22,9 @@ describe("server runtime", () => {
 
     expect(context.actor.id).toBe("user_dev_admin");
     expect(context.actor.permissionKeys).toContain("system.menu.read");
+    // @windy-module work-order begin
+    expect(context.actor.permissionKeys).toContain("work-order.ticket.read");
+    // @windy-module work-order end
   });
 
   test("生产环境强制关闭开发管理员 token", async () => {

package/template/apps/server/src/runtime.ts

@@ -31,6 +31,13 @@ import {
   requestSourcePolicyFromEnv,
   resolveRequestSource,
 } from "./http/request-source.js";
+import { resolveRequestActor } from "./runtime-request-actor.js";
+// @windy-module system.agent begin
+import {
+  createAdkDebugRuntime,
+  type AdkDebugActorResolver,
+} from "./runtime-adk-debug.js";
+// @windy-module system.agent end
 
 export type {
   FeatureFlagRuntimeResolver,
@@ -78,6 +85,9 @@ export interface ServerRuntimeOptions {
   featureCatalog?: readonly FeatureFlagDefinition[];
   auditWriter?: AuditEventWriter;
   auditReader?: AuditEventReader;
+  // @windy-module system.agent begin
+  adkDebugActorResolver?: AdkDebugActorResolver;
+  // @windy-module system.agent end
 }
 
 export class InMemorySessionStore {
@@ -186,6 +196,19 @@ export function createServerRuntime(
   options: ServerRuntimeOptions = {},
 ) {
   const developmentAuth = readDevelopmentAuthBypass(env);
+  // @windy-module system.agent begin
+  const adkDebug = createAdkDebugRuntime(
+    env,
+    undefined,
+    options.adkDebugActorResolver,
+  );
+  if (adkDebug.usesToken(developmentAuth.token)) {
+    throw new Error("ADK Web 调试 Token 不能复用开发管理员 Token");
+  }
+  if (adkDebug.usesToken(env.AGENT_SERVER_INTERNAL_TOKEN?.trim())) {
+    throw new Error("ADK Web 调试 Token 不能复用 Agent 内部服务 Token");
+  }
+  // @windy-module system.agent end
   const sessionStore = new InMemorySessionStore(
     developmentAuth.token
       ? [{ token: developmentAuth.token, actor: developmentAdminActor() }]
@@ -216,9 +239,15 @@ export function createServerRuntime(
         metadata.clientIp,
         requestSourcePolicy,
       );
-      const actor =
-        (await options.actorResolver?.resolve(request)) ||
-        sessionStore.resolve(request);
+      const actor = await resolveRequestActor(
+        request,
+        async () =>
+          (await options.actorResolver?.resolve(request)) ||
+          sessionStore.resolve(request),
+        // @windy-module system.agent begin
+        adkDebug,
+        // @windy-module system.agent end
+      );
       const license =
         (await options.licenseResolver?.resolve()) || licenseStore.resolve();
       return createRequestGuardContext(request, {
@@ -227,6 +256,10 @@ export function createServerRuntime(
         resolveLicense: () => license,
       });
     },
+    // @windy-module system.agent begin
+    resolveEphemeralActor: adkDebug.resolveActor,
+    agentDebugOperationForActor: adkDebug.operationForActor,
+    // @windy-module system.agent end
     async createGuardContextForActor(
       request: Request,
       actor: RequestActor,