create-windy 0.4.1 → 0.5.0

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

@@ -133,6 +133,7 @@ function unavailableModuleAiOperationPort(
   };
   return {
     startAgent: async () => unavailable(),
+    verifyAgentRun: async () => unavailable(),
     startDocument: async () => unavailable(),
     startSpeech: async () => unavailable(),
     embed: async () => unavailable(),

package/template/apps/server/src/module-host/scoped-host.ts

@@ -0,0 +1,214 @@
+import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  requireModuleNamespace,
+  type ModuleHost,
+  type ModuleResourceFileAccessPolicy,
+  type ModuleUploadPolicy,
+} from "@southwind-ai/server-sdk";
+import type {
+  RegisteredModuleAiOperationHandler,
+  RegisteredModuleDebugSessionProvider,
+  RegisteredModuleDurableHandler,
+  RegisteredModuleGovernedResource,
+  RegisteredModuleRolePreset,
+  RegisteredModuleRoute,
+  RegisteredModuleSandboxToolHandler,
+  RegisteredModuleSearchProvider,
+  RegisteredModuleTaskHandler,
+  RegisteredModuleToolHandler,
+} from "./initialize-contracts.js";
+import { validateDebugSessionProviderRegistration } from "./debug-session-provider-registration.js";
+import { registerModuleDurableHandler } from "./durable-handler-registration.js";
+import { registerGovernedResources } from "./governed-resources.js";
+import { registerResourceFileAccessPolicies } from "./resource-file-policies.js";
+import { validateRouteDeclaration } from "./route-declaration.js";
+import { validateSearchProviderRegistration } from "./search-provider-registration.js";
+
+type HandlerInstaller = (registry: DurableHandlerRegistry) => void;
+
+export interface HostCollections {
+  uploadPolicies: ModuleUploadPolicy[];
+  uploadPurposes: Set<string>;
+  modulePurposes: Map<string, Set<string>>;
+  moduleDependencies: ReadonlyMap<string, readonly string[]>;
+  resourceFileAccessPolicies: ModuleResourceFileAccessPolicy[];
+  moduleResourceFileAccessPolicies: Map<
+    string,
+    ModuleResourceFileAccessPolicy[]
+  >;
+  resourceFileAccessPolicyKeys: Set<string>;
+  handlerKeys: Set<string>;
+  handlerInstallers: HandlerInstaller[];
+  durableHandlers: RegisteredModuleDurableHandler[];
+  routes: RegisteredModuleRoute[];
+  routeKeys: Set<string>;
+  taskHandlers: RegisteredModuleTaskHandler[];
+  taskKeys: Set<string>;
+  toolHandlers: RegisteredModuleToolHandler[];
+  sandboxToolHandlers: RegisteredModuleSandboxToolHandler[];
+  toolKeys: Set<string>;
+  aiOperationHandlers: RegisteredModuleAiOperationHandler[];
+  aiOperationKeys: Set<string>;
+  governedResources: RegisteredModuleGovernedResource[];
+  governedResourceKeys: Set<string>;
+  rolePresets: RegisteredModuleRolePreset[];
+  rolePresetKeys: Set<string>;
+  searchProviders: RegisteredModuleSearchProvider[];
+  searchProviderKeys: Set<string>;
+  debugSessionProviders: RegisteredModuleDebugSessionProvider[];
+  debugSessionProviderKeys: Set<string>;
+}
+
+export function createScopedHost(
+  manifest: ModuleManifest,
+  state: HostCollections,
+): ModuleHost {
+  const moduleName = manifest.name;
+  return {
+    moduleName,
+    registerUploadPolicy(policy) {
+      requireModuleNamespace("上传用途", policy.purpose, moduleName);
+      if (state.uploadPurposes.has(policy.purpose)) {
+        throw new Error(`上传用途重复注册：${policy.purpose}`);
+      }
+      state.uploadPurposes.add(policy.purpose);
+      state.uploadPolicies.push(policy);
+      const purposes =
+        state.modulePurposes.get(moduleName) ?? new Set<string>();
+      purposes.add(policy.purpose);
+      state.modulePurposes.set(moduleName, purposes);
+    },
+    registerResourceFileAccessPolicies(policies) {
+      registerResourceFileAccessPolicies(manifest, state, policies);
+    },
+    registerDurableHandler(definition) {
+      requireModuleNamespace("任务 handler", definition.key, moduleName);
+      registerModuleDurableHandler(manifest, state, definition);
+    },
+    registerGovernedResources(registrations) {
+      registerGovernedResources(manifest, state, registrations);
+    },
+    registerRoutes(routes) {
+      for (const definition of routes) {
+        requireModuleNamespace(
+          "路由权限",
+          definition.permissionKey,
+          moduleName,
+        );
+        validateRouteDeclaration(manifest, definition);
+        const key = `${definition.method} ${definition.path}`;
+        if (state.routeKeys.has(key)) {
+          throw new Error(`模块路由重复注册：${key}`);
+        }
+        state.routeKeys.add(key);
+        state.routes.push({ moduleName, definition });
+      }
+    },
+    registerTaskHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("定时任务", registration.taskKey, moduleName);
+        if (!manifest.tasks.some(({ key }) => key === registration.taskKey)) {
+          throw new Error(
+            `定时任务 Handler 未在 Manifest 声明：${registration.taskKey}`,
+          );
+        }
+        if (state.taskKeys.has(registration.taskKey)) {
+          throw new Error(`定时任务 Handler 重复注册：${registration.taskKey}`);
+        }
+        state.taskKeys.add(registration.taskKey);
+        state.taskHandlers.push({ moduleName, registration });
+      }
+    },
+    registerToolHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace("Agent Tool", registration.toolKey, moduleName);
+        if (!manifest.tools.some(({ key }) => key === registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 未在 Manifest 声明：${registration.toolKey}`,
+          );
+        }
+        if (state.toolKeys.has(registration.toolKey)) {
+          throw new Error(
+            `Agent Tool Handler 重复注册：${registration.toolKey}`,
+          );
+        }
+        state.toolKeys.add(registration.toolKey);
+        state.toolHandlers.push({ moduleName, registration });
+      }
+    },
+    registerAiOperationHandlers(registrations) {
+      for (const registration of registrations) {
+        requireModuleNamespace(
+          "AI Operation",
+          registration.operationKey,
+          moduleName,
+        );
+        const operation = manifest.aiOperations?.find(
+          ({ key }) => key === registration.operationKey,
+        );
+        if (!operation) {
+          throw new Error(
+            `AI Operation Handler 未在 Manifest 声明：${registration.operationKey}`,
+          );
+        }
+        if (
+          (operation.kind === "agent" && !registration.prepare) ||
+          (operation.kind === "document" && !registration.prepareDocument) ||
+          (operation.kind === "speech" && !registration.prepareSpeech) ||
+          (operation.kind === "embedding" && !registration.prepareEmbedding)
+        ) {
+          throw new Error(
+            `AI Operation Handler 与 kind 不匹配：${registration.operationKey}`,
+          );
+        }
+        if (state.aiOperationKeys.has(registration.operationKey)) {
+          throw new Error(
+            `AI Operation Handler 重复注册：${registration.operationKey}`,
+          );
+        }
+        state.aiOperationKeys.add(registration.operationKey);
+        state.aiOperationHandlers.push({ moduleName, registration });
+      }
+    },
+    registerRolePresets(presets) {
+      for (const preset of presets) {
+        requireModuleNamespace("角色预设", preset.key, moduleName);
+        if (state.rolePresetKeys.has(preset.key)) {
+          throw new Error(`角色预设重复注册：${preset.key}`);
+        }
+        for (const permissionKey of preset.permissionKeys) {
+          requireModuleNamespace("角色预设权限", permissionKey, moduleName);
+          if (!manifest.permissions.some(({ key }) => key === permissionKey)) {
+            throw new Error(
+              `角色预设引用了模块 ${moduleName} 未声明权限：${permissionKey}`,
+            );
+          }
+        }
+        state.rolePresetKeys.add(preset.key);
+        state.rolePresets.push({ moduleName, preset });
+      }
+    },
+    registerSearchProviders(providers) {
+      for (const provider of providers) {
+        requireModuleNamespace("搜索 Provider", provider.key, moduleName);
+        validateSearchProviderRegistration(manifest, provider);
+        if (state.searchProviderKeys.has(provider.key)) {
+          throw new Error(`搜索 Provider 重复注册：${provider.key}`);
+        }
+        state.searchProviderKeys.add(provider.key);
+        state.searchProviders.push({ moduleName, provider });
+      }
+    },
+    registerDebugSessionProviders(providers) {
+      for (const provider of providers) {
+        validateDebugSessionProviderRegistration(manifest, provider);
+        if (state.debugSessionProviderKeys.has(provider.key)) {
+          throw new Error(`调试会话 Provider 重复注册：${provider.key}`);
+        }
+        state.debugSessionProviderKeys.add(provider.key);
+        state.debugSessionProviders.push({ moduleName, provider });
+      }
+    },
+  };
+}

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

@@ -9,6 +9,7 @@ export {
   type RegisteredModuleTaskHandler,
   type RegisteredModuleToolHandler,
   type RegisteredModuleAiOperationHandler,
+  type RegisteredModuleDebugSessionProvider,
 } from "./module-host/initialize.js";
 export {
   buildModuleRequestContext,

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

@@ -7,7 +7,7 @@ import { createAdkDebugRuntime } from "./runtime-adk-debug.js";
 const token = "debug-token-012345678901234567890123";
 
 describe("ADK Web 专用调试身份", () => {
-  test("只在 canonical Run 路径委托真实用户并收窄权限", async () => {
+  test("只在 canonical Run 与只读 debug-session 路径委托真实用户", async () => {
     const runtime = createRuntime();
     expect(
       runtime.claimsRequest(request("/api/foundation", "GET", token)),
@@ -28,6 +28,30 @@ describe("ADK Web 专用调试身份", () => {
     expect(
       await runtime.resolveRequest(request("/api/foundation", "GET", token)),
     ).toBeUndefined();
+    expect(
+      await runtime.resolveRequest(
+        request("/api/agent/debug/sessions/v1", "GET", token),
+      ),
+    ).toMatchObject({ id: "service_adk_debug" });
+    expect(
+      await runtime.resolveRequest(
+        request(
+          "/api/agent/debug/sessions/v1/wdbg1_" + "a".repeat(43),
+          "GET",
+          token,
+        ),
+      ),
+    ).toMatchObject({ id: "service_adk_debug" });
+    expect(
+      await runtime.resolveRequest(
+        request("/api/agent/debug/sessions/v1", "POST", token),
+      ),
+    ).toBeUndefined();
+    expect(
+      await runtime.resolveRequest(
+        request("/api/agent/debug/sessions/v1/one/events", "GET", token),
+      ),
+    ).toBeUndefined();
     expect(
       await runtime.resolveRequest(
         request("/api/agent/runs/run_1/result", "GET"),

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

@@ -45,7 +45,7 @@ export function createAdkDebugRuntime(
   return {
     claimsRequest,
     async resolveRequest(request: Request): Promise<RequestActor | undefined> {
-      if (!claimsRequest(request) || !isCanonicalRunRequest(request)) {
+      if (!claimsRequest(request) || !isAdkDebugRequest(request)) {
         return undefined;
       }
       return resolveDelegatedActor(actorResolver, dataActorId, permissionKeys);
@@ -123,8 +123,14 @@ function resolvePermissionClosure(
   return [...new Set([operation.permissionKey, ...toolPermissions])];
 }
 
-function isCanonicalRunRequest(request: Request): boolean {
+function isAdkDebugRequest(request: Request): boolean {
   const path = new URL(request.url).pathname.replace(/\/+$/, "");
+  if (
+    request.method === "GET" &&
+    /^\/api\/agent\/debug\/sessions\/v1(?:\/[^/]+)?$/.test(path)
+  ) {
+    return true;
+  }
   if (request.method === "POST" && path === "/api/agent/runs") return true;
   const match = path.match(
     /^\/api\/agent\/runs\/[^/]+\/(events|result|cancel|attach)$/,

package/template/apps/server/src/system/operations.test.ts

@@ -84,6 +84,37 @@ describe("system operation routes", () => {
           path: "/imports",
           usedBytes: 500,
         }),
+        cpuMonitorProbe: async () => ({
+          status: "available",
+          logicalCores: 16,
+          hostUsagePercent: 42.5,
+          processUsagePercent: 3.25,
+          loadAverage1m: 2.1,
+        }),
+        gpuMonitorProbe: async () => ({
+          status: "available",
+          provider: "NVIDIA",
+          message: "GPU 指标可用。",
+          devices: [
+            {
+              index: 0,
+              uuid: "GPU-abc",
+              name: "NVIDIA RTX 5000",
+              usagePercent: 75,
+              memoryUsedBytes: 8_192,
+              memoryTotalBytes: 32_768,
+              memoryUsagePercent: 25,
+              temperatureCelsius: 62,
+              processes: [
+                {
+                  pid: 4321,
+                  name: "python ai-service.py",
+                  usedMemoryBytes: 7_168,
+                },
+              ],
+            },
+          ],
+        }),
       },
     );
     const guardContext = await runtime.createGuardContext(
@@ -104,6 +135,15 @@ describe("system operation routes", () => {
           totalBytes: number;
           usagePercent: number;
         };
+        cpu: {
+          logicalCores: number;
+          hostUsagePercent: number;
+          processUsagePercent: number;
+        };
+      };
+      gpuMonitor: {
+        status: string;
+        devices: Array<{ name: string; processes: Array<{ pid: number }> }>;
       };
       databaseMonitor: { engine: string; version: string };
       diskMonitor: {
@@ -118,6 +158,20 @@ describe("system operation routes", () => {
     expect(snapshot.serviceMonitor.status).toBe("running");
     expect(snapshot.serviceMonitor.startedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
     expect(snapshot.serviceMonitor.memory.usagePercent).toBeGreaterThan(0);
+    expect(snapshot.serviceMonitor.cpu).toMatchObject({
+      logicalCores: 16,
+      hostUsagePercent: 42.5,
+      processUsagePercent: 3.25,
+    });
+    expect(snapshot.gpuMonitor).toMatchObject({
+      status: "available",
+      devices: [
+        {
+          name: "NVIDIA RTX 5000",
+          processes: [{ pid: 4321 }],
+        },
+      ],
+    });
     expect(snapshot.databaseMonitor).toMatchObject({
       engine: "PostgreSQL",
       version: "16.3",

package/template/apps/server/src/system/operations.ts

@@ -18,6 +18,12 @@ import {
   type DirectoryUsageProbe,
   type HostDiskUsageProbe,
 } from "./operation-monitoring.js";
+import {
+  createCpuMonitorProbe,
+  createGpuMonitorProbe,
+  type CpuMonitorProbe,
+  type GpuMonitorProbe,
+} from "./system-resource-monitoring.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -31,6 +37,8 @@ export interface OperationRouteOptions {
   hostDiskUsageProbe?: HostDiskUsageProbe;
   systemUsageProbe?: DirectoryUsageProbe;
   importDataUsageProbe?: DirectoryUsageProbe;
+  cpuMonitorProbe?: CpuMonitorProbe;
+  gpuMonitorProbe?: GpuMonitorProbe;
   onlineUserProvider?: () => Promise<ActiveAuthSession[]>;
 }
 
@@ -69,6 +77,8 @@ export function registerSystemOperationRoutes(
           process.env.WINDY_IMPORT_DATA_PATH,
       ),
     );
+  const cpuMonitorProbe = options.cpuMonitorProbe ?? createCpuMonitorProbe();
+  const gpuMonitorProbe = options.gpuMonitorProbe ?? createGpuMonitorProbe();
   const onlineUserProvider = options.onlineUserProvider ?? (async () => []);
   app.get("/system/operations", async (rawContext) => {
     const { guardContext } = rawContext as OperationRouteContext;
@@ -87,6 +97,8 @@ export function registerSystemOperationRoutes(
           hostDiskUsageProbe,
           systemUsageProbe,
           importDataUsageProbe,
+          cpuMonitorProbe,
+          gpuMonitorProbe,
           onlineUserProvider,
         )
       : forbidden(decision.reason);
@@ -108,6 +120,8 @@ async function createOperationSnapshot(
   hostDiskUsageProbe: HostDiskUsageProbe,
   systemUsageProbe: DirectoryUsageProbe,
   importDataUsageProbe: DirectoryUsageProbe,
+  cpuMonitorProbe: CpuMonitorProbe,
+  gpuMonitorProbe: GpuMonitorProbe,
   onlineUserProvider: () => Promise<ActiveAuthSession[]>,
 ) {
   const [
@@ -116,6 +130,8 @@ async function createOperationSnapshot(
     hostDiskUsage,
     systemUsage,
     importDataUsage,
+    cpuMonitor,
+    gpuMonitor,
     activeSessions,
   ] = await Promise.all([
     redisHealthProbe(),
@@ -123,6 +139,8 @@ async function createOperationSnapshot(
     hostDiskUsageProbe(),
     systemUsageProbe(),
     importDataUsageProbe(),
+    cpuMonitorProbe(),
+    gpuMonitorProbe(),
     onlineUserProvider(),
   ]);
   return {
@@ -138,7 +156,11 @@ async function createOperationSnapshot(
       lastSeenAt: (session.lastSeenAt || session.issuedAt).toISOString(),
       expiresAt: session.expiresAt.toISOString(),
     })),
-    serviceMonitor: serviceMonitorSnapshot(),
+    serviceMonitor: {
+      ...serviceMonitorSnapshot(),
+      cpu: cpuMonitor,
+    },
+    gpuMonitor,
     databaseMonitor,
     diskMonitor: diskMonitorSnapshot(
       hostDiskUsage,

package/template/apps/server/src/system/seed.test.ts

@@ -33,6 +33,7 @@ describe("系统内置角色同步", () => {
     // @windy-module system.settings end
     expect(role?.permissionKeys).not.toContain("system.user.reveal");
     expect(role?.permissionKeys).not.toContain("system.user.export");
+    expect(role?.permissionKeys).not.toContain("system.ai-runtime.read");
     expect(role?.permissionKeys).toContain("custom.permission");
     // @windy-module system.settings begin
     expect(role?.menuKeys).toContain("system.settings");
@@ -54,6 +55,9 @@ describe("系统内置角色同步", () => {
     expect(
       (await repositories.roles.get("role_developer"))?.permissionKeys,
     ).not.toEqual(expect.arrayContaining(["system.user.reveal"]));
+    expect(
+      (await repositories.roles.get("role_developer"))?.permissionKeys,
+    ).not.toContain("system.ai-runtime.read");
 
     await repositories.roles.update(
       "role_developer",

package/template/apps/server/src/system/system-resource-monitoring.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import {
+  calculateCpuMonitor,
+  createGpuMonitorProbe,
+  type CpuSample,
+} from "./system-resource-monitoring.js";
+
+describe("系统 CPU 与 GPU 监控", () => {
+  test("CPU 占用按宿主机时间和逻辑核心归一化进程时间计算", () => {
+    const previous: CpuSample = {
+      hostIdleMilliseconds: 2_000,
+      hostTotalMilliseconds: 10_000,
+      processMicroseconds: 1_000_000,
+      observedAtMicroseconds: 5_000_000,
+      logicalCores: 4,
+      loadAverage1m: 1,
+    };
+    const snapshot = calculateCpuMonitor(previous, {
+      hostIdleMilliseconds: 2_400,
+      hostTotalMilliseconds: 11_000,
+      processMicroseconds: 1_800_000,
+      observedAtMicroseconds: 6_000_000,
+      logicalCores: 4,
+      loadAverage1m: 1.5,
+    });
+
+    expect(snapshot).toMatchObject({
+      hostUsagePercent: 60,
+      processUsagePercent: 20,
+      logicalCores: 4,
+      loadAverage1m: 1.5,
+    });
+  });
+
+  test("NVIDIA 指标关联设备利用率与 AI 计算进程显存", async () => {
+    const probe = createGpuMonitorProbe(async (args) =>
+      args[0]?.startsWith("--query-gpu=")
+        ? {
+            exitCode: 0,
+            stdout: '0, GPU-abc, "NVIDIA RTX 5000", 75, 8192, 32768, 62\n',
+          }
+        : {
+            exitCode: 0,
+            stdout: 'GPU-abc, 4321, "python ai-service.py", 7168\n',
+          },
+    );
+
+    await expect(probe()).resolves.toMatchObject({
+      status: "available",
+      devices: [
+        {
+          index: 0,
+          name: "NVIDIA RTX 5000",
+          usagePercent: 75,
+          memoryUsagePercent: 25,
+          temperatureCelsius: 62,
+          processes: [
+            {
+              pid: 4321,
+              name: "python ai-service.py",
+              usedMemoryBytes: 7_168 * 1_024 ** 2,
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("没有 nvidia-smi 时返回可解释的不可探测状态", async () => {
+    const probe = createGpuMonitorProbe(async () => ({
+      exitCode: null,
+      stdout: "",
+      missing: true,
+    }));
+
+    await expect(probe()).resolves.toMatchObject({
+      status: "not-detected",
+      provider: "NVIDIA",
+      devices: [],
+    });
+  });
+});