create-windy 0.4.1 → 0.5.0

package/template/apps/server/src/agent/run-facade-adk-debug.test.ts

@@ -7,6 +7,7 @@ import {
 import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
 import { debugActorAuditMetadata } from "./run-debug-authorization.js";
 import { bindModuleUserProjection } from "../guards.js";
+import { buildScopeContext } from "../data-access/context.js";
 
 describe("ADK 调试 Operation 边界", () => {
   test("专用身份不能切换到未选定的 Agent Operation", async () => {
@@ -53,4 +54,42 @@ describe("ADK 调试 Operation 边界", () => {
       ),
     ).toEqual({ debugDataActorId: "user_dev_admin" });
   });
+
+  test("报表按 Module Actor 投影归属真实调试用户", async () => {
+    const fixture = await createRunFacadeFixture();
+    const actor = bindModuleUserProjection(
+      {
+        ...fixture.context.actor,
+        id: "service_adk_debug",
+        type: "service",
+        scopeContext: buildScopeContext("user_dev_admin", "dept_platform", [
+          {
+            id: "role-debug",
+            code: "debug",
+            dataScope: "self",
+            departmentIds: [],
+          },
+        ]),
+      },
+      "user_dev_admin",
+    );
+    const context = { ...fixture.context, actor };
+    Object.assign(fixture.runtime, {
+      agentDebugOperationForActor: (actorId: string) =>
+        actorId === "service_adk_debug" ? "business.answer" : undefined,
+    });
+
+    await fixture.facade.start(
+      "business.answer",
+      { question: "调试归属" },
+      "request-debug-report",
+      context,
+    );
+
+    expect(fixture.remote.started[0]?.reporting).toEqual({
+      actorId: "user_dev_admin",
+      actorType: "user",
+      departmentId: "dept_platform",
+    });
+  });
 });

package/template/apps/server/src/agent/run-facade.test.ts

@@ -39,6 +39,10 @@ describe("Guarded Agent Run facade", () => {
         promptVersion: "prompt-3",
         routeVersion: "route-4",
       },
+      reporting: {
+        actorId: "actor-1",
+        actorType: "user",
+      },
     });
     expect(fixture.remote.started[0]?.release.releaseId).toMatch(
       /^release_[a-f0-9]{40}$/,
@@ -109,4 +113,78 @@ describe("Guarded Agent Run facade", () => {
       message: "Agent Run 不存在或不可访问",
     });
   });
+
+  test("服务端可验证 canonical 输入，且同幂等键的不同输入 fail closed", async () => {
+    const fixture = await createRunFacadeFixture();
+    await fixture.facade.start(
+      "business.answer",
+      { question: "原始问题", ignored: "不出网" },
+      "request-attested",
+      fixture.context,
+    );
+
+    await expect(
+      fixture.facade.verifyRunInput(
+        "business.answer",
+        "run_1",
+        { question: "原始问题" },
+        fixture.context,
+      ),
+    ).resolves.toBeUndefined();
+    await expect(
+      fixture.facade.verifyRunInput(
+        "business.answer",
+        "run_1",
+        { question: "伪造问题" },
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "RUN_CONFLICT", status: 404 });
+    await expect(
+      fixture.facade.start(
+        "business.answer",
+        { question: "伪造问题" },
+        "request-attested",
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+    expect(fixture.remote.started).toHaveLength(1);
+  });
+
+  test("敏感原文使用 DLP 前承诺且不会与脱敏占位符碰撞", async () => {
+    const fixture = await createRunFacadeFixture();
+    await fixture.facade.start(
+      "business.answer",
+      { question: "联系 13800138000" },
+      "request-sensitive",
+      fixture.context,
+    );
+
+    expect(fixture.remote.started[0]?.input).toEqual({
+      question: "联系 [REDACTED]",
+    });
+    await expect(
+      fixture.facade.verifyRunInput(
+        "business.answer",
+        "run_1",
+        { question: "联系 13800138000" },
+        fixture.context,
+      ),
+    ).resolves.toBeUndefined();
+    await expect(
+      fixture.facade.verifyRunInput(
+        "business.answer",
+        "run_1",
+        { question: "联系 [REDACTED]" },
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ code: "RUN_CONFLICT", status: 404 });
+    await expect(
+      fixture.facade.start(
+        "business.answer",
+        { question: "联系 [REDACTED]" },
+        "request-sensitive",
+        fixture.context,
+      ),
+    ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+  });
 });

package/template/apps/server/src/agent/run-facade.ts

@@ -27,6 +27,7 @@ import type {
 import { AgentRuntimeError } from "./run-contracts.js";
 import {
   governProviderInput,
+  projectProviderInput,
   ProviderInputGovernanceError,
 } from "./provider-input-governance.js";
 import { rotateVisionArtifacts, validateOutputSchema } from "./vision-input.js";
@@ -38,6 +39,7 @@ import {
 } from "./run-definition-support.js";
 import { AgentRunFacadeError, inaccessibleRun } from "./run-errors.js";
 import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
+import { verifyCommittedRunInput } from "./run-input-verification.js";
 import {
   assertSelectedDebugOperation,
   debugActorAuditMetadata,
@@ -52,7 +54,6 @@ type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
 export class AgentRunFacade {
   readonly #operations: Map<string, RegisteredOperation>;
-
   constructor(
     modules: readonly ModuleManifest[],
     hosts: InitializedModuleHosts,
@@ -63,7 +64,6 @@ export class AgentRunFacade {
   ) {
     this.#operations = buildRegisteredOperations(modules, hosts);
   }
-
   async start(
     operationKey: string,
     input: ModuleAiJsonValue,
@@ -116,7 +116,11 @@ export class AgentRunFacade {
       );
     }
     let governedInput = input;
+    let committedInput = input;
     try {
+      committedInput = providerPolicy
+        ? projectProviderInput(input, providerPolicy)
+        : input;
       governedInput = providerPolicy
         ? governProviderInput(input, providerPolicy)
         : input;
@@ -130,8 +134,9 @@ export class AgentRunFacade {
       }
       throw error;
     }
+    const moduleActor = toModuleActor(context.actor);
     const plan = await operation.registration.prepare(governedInput, {
-      actor: toModuleActor(context.actor),
+      actor: moduleActor,
       requestId: context.requestId,
     });
     if (!plan.instructions.trim() || !plan.userPrompt.trim()) {
@@ -161,6 +166,7 @@ export class AgentRunFacade {
         operationKey,
         releaseId: release.releaseId,
         idempotencyKey,
+        input: committedInput,
         authorizationSnapshot: {
           permissionKey: operation.definition.permissionKey,
           featureKey: operation.definition.featureKey,
@@ -194,6 +200,13 @@ export class AgentRunFacade {
           executionGrant: authorization.token,
           release,
           traceId,
+          reporting: {
+            actorId: moduleActor.id,
+            actorType: moduleActor.type,
+            ...(context.actor.scopeContext?.departmentId
+              ? { departmentId: context.actor.scopeContext.departmentId }
+              : {}),
+          },
         },
         scopedRuntimeIdempotencyKey(
           context.actor.id,
@@ -282,6 +295,23 @@ export class AgentRunFacade {
     return operation;
   }
 
+  async verifyRunInput(
+    operationKey: string,
+    runId: string,
+    input: ModuleAiJsonValue,
+    context: RequestGuardContext,
+  ): Promise<void> {
+    const operation = await this.authorizeRun(operationKey, runId, context);
+    await verifyCommittedRunInput({
+      operationKey,
+      runId,
+      value: input,
+      policy: operation.definition.providerDataPolicy,
+      context,
+      authorizations: this.authorizations,
+    });
+  }
+
   async attach(
     operationKey: string,
     runId: string,

package/template/apps/server/src/agent/run-input-commitment.ts

@@ -0,0 +1,50 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export function commitAgentRunInput(
+  secret: string,
+  tokenHash: string,
+  input: ModuleAiJsonValue,
+): string {
+  const digest = createHash("sha256")
+    .update(canonicalizeJson(input))
+    .digest("hex");
+  return createHmac("sha256", secret)
+    .update(`input\u0000${tokenHash}\u0000${digest}`)
+    .digest("hex");
+}
+
+export function sameInputCommitment(left: string, right: string): boolean {
+  const leftBytes = Buffer.from(left, "hex");
+  const rightBytes = Buffer.from(right, "hex");
+  return (
+    leftBytes.byteLength === 32 &&
+    rightBytes.byteLength === 32 &&
+    timingSafeEqual(leftBytes, rightBytes)
+  );
+}
+
+export function canonicalizeJson(value: ModuleAiJsonValue): string {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("Agent Run 输入包含非有限数值");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalizeJson).join(",")}]`;
+  }
+  return `{${Object.keys(value)
+    .sort()
+    .map(
+      (key) =>
+        `${JSON.stringify(key)}:${canonicalizeJson(value[key] as ModuleAiJsonValue)}`,
+    )
+    .join(",")}}`;
+}

package/template/apps/server/src/agent/run-input-verification.ts

@@ -0,0 +1,41 @@
+import type { AiProviderDataPolicy } from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  projectProviderInput,
+  ProviderInputGovernanceError,
+} from "./provider-input-governance.js";
+import {
+  AgentRunAuthorizationError,
+  type AgentRunAuthorizationStore,
+} from "./run-authorization.js";
+import { inaccessibleRun } from "./run-errors.js";
+
+export async function verifyCommittedRunInput(input: {
+  readonly operationKey: string;
+  readonly runId: string;
+  readonly value: ModuleAiJsonValue;
+  readonly policy?: AiProviderDataPolicy;
+  readonly context: RequestGuardContext;
+  readonly authorizations: AgentRunAuthorizationStore;
+}): Promise<void> {
+  try {
+    const committed = input.policy
+      ? projectProviderInput(input.value, input.policy)
+      : input.value;
+    await input.authorizations.verifyRunInput(
+      input.operationKey,
+      input.runId,
+      committed,
+      input.context,
+    );
+  } catch (error) {
+    if (
+      error instanceof AgentRunAuthorizationError ||
+      error instanceof ProviderInputGovernanceError
+    ) {
+      throw inaccessibleRun();
+    }
+    throw error;
+  }
+}

package/template/apps/server/src/agent/runtime-bootstrap-report.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { createFoundationSnapshot, loadSystemModules } from "../foundation.js";
+import { createRequestGuardContext } from "../guards.js";
+import { buildScopeContext } from "../data-access/context.js";
+import { createServerRuntime } from "../runtime.js";
+import { createSystemRepositories } from "../system/seed.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { registerAiRuntimeReporting } from "./runtime-bootstrap.js";
+import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("AI Runtime 报表生产组合", () => {
+  test("注册受权限保护的路由并复用 Agent Server 地址与内部 Token", async () => {
+    const snapshot = createFoundationSnapshot();
+    const modules = loadSystemModules();
+    const features = modules.flatMap(({ features }) => features);
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "admin-token" },
+      { featureCatalog: features },
+    );
+    const app = new FakeRouteApp();
+    const remote = mock(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        const url = new URL(
+          input instanceof Request ? input.url : input.toString(),
+        );
+        expect(url.origin).toBe("http://agent-report.test");
+        expect(url.pathname).toBe("/api/internal/ai-runtime-report/summary");
+        expect(url.searchParams.get("scopeMode")).toBe("all");
+        expect(new Headers(init?.headers).get("authorization")).toBe(
+          "Bearer internal-token-for-tests",
+        );
+        return Response.json(emptySummary());
+      },
+    );
+    globalThis.fetch = remote as unknown as typeof globalThis.fetch;
+    registerAiRuntimeReporting({
+      app,
+      features,
+      runtime,
+      systemRepositories: createSystemRepositories(snapshot),
+      agentServerUrl: "http://agent-report.test",
+      internalToken: "internal-token-for-tests",
+    });
+    const guardContext = await createRequestGuardContext(
+      new Request("http://server.test/api/system/ai-runtime/summary"),
+      {
+        resolveActor: () => ({
+          id: "report-admin",
+          type: "user",
+          name: "报表管理员",
+          roleCodes: ["report-admin"],
+          permissionKeys: ["system.ai-runtime.read"],
+          scopeContext: buildScopeContext("report-admin", "dept_platform", [
+            {
+              id: "role-report-admin",
+              code: "report-admin",
+              dataScope: "all",
+              departmentIds: [],
+            },
+          ]),
+        }),
+      },
+    );
+
+    const result = await app.invoke("GET", "/system/ai-runtime/summary", {
+      guardContext,
+      params: {},
+      query: { range: "day" },
+    });
+
+    expect(result).toEqual(emptySummary());
+    expect(remote).toHaveBeenCalledTimes(1);
+    expect(runtime.auditSink.list().at(-1)?.action).toBe(
+      "agent.runtime.report.read",
+    );
+  });
+
+  test("AI disabled 时四条报表接口明确返回 503", async () => {
+    const app = new FakeRouteApp();
+    registerUnavailableAiRoutes(app);
+
+    for (const path of [
+      "/system/ai-runtime/summary",
+      "/system/ai-runtime/runs",
+      "/system/ai-runtime/runs/:runId",
+      "/system/ai-runtime/actors",
+    ]) {
+      const response = (await app.invoke("GET", path, {})) as Response;
+      expect(response.status).toBe(503);
+      await expect(response.json()).resolves.toEqual({
+        code: "RUNTIME_UNAVAILABLE",
+        message: "AI Runtime 未启用",
+      });
+    }
+  });
+});
+
+function emptySummary() {
+  return {
+    generatedAt: "2026-07-31T00:00:00Z",
+    reportingAvailableFrom: null,
+    retentionDays: 90,
+    runs: {
+      total: 0,
+      completed: 0,
+      failed: 0,
+      cancelled: 0,
+      inProgress: 0,
+      successRate: null,
+    },
+    cache: {
+      hit: 0,
+      miss: 0,
+      unknown: 0,
+      hitRate: null,
+      tokenRate: null,
+      coverageRate: 0,
+    },
+    tokens: {
+      input: 0,
+      output: 0,
+      cachedInput: 0,
+      reasoning: 0,
+      total: 0,
+      coverageRate: 0,
+    },
+    byModel: [],
+    activity: [],
+  };
+}

package/template/apps/server/src/agent/runtime-bootstrap.ts

@@ -1,5 +1,11 @@
 import type { PlatformConfig } from "@southwind-ai/config";
 import type { ModuleManifest } from "@southwind-ai/modules";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import { SystemAiRuntimeActorDirectory } from "../ai-runtime-report/actor-directory.js";
+import { RemoteAiRuntimeReportPort } from "../ai-runtime-report/remote-port.js";
+import { registerAiRuntimeReportRoutes } from "../ai-runtime-report/routes.js";
+import { AiRuntimeReportService } from "../ai-runtime-report/service.js";
+import { departmentDescendantResolver } from "../data-access/department-tree.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import type { createServerRuntime } from "../runtime.js";
 import type { RouteApp } from "../system/routes.js";
@@ -51,6 +57,9 @@ import {
   createStaticRouteAuthorizer,
 } from "../module-host/static-route-authorization.js";
 import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
+import { DebugSessionFacadeV1 } from "./debug-session-facade.js";
+import { DebugSessionIdCodecV1 } from "./debug-session-id.js";
+import { registerDebugSessionRoutesV1 } from "./debug-session-routes.js";
 
 export function registerAgentPlatformRuntime(input: {
   app: RouteApp;
@@ -107,6 +116,21 @@ export function registerAgentPlatformRuntime(input: {
     input.app,
     routeAuthorizer,
   );
+  const debugToken =
+    process.env.NODE_ENV === "development" &&
+    process.env.WINDY_ADK_DEBUG_OPERATION_KEY?.trim()
+      ? process.env.WINDY_ADK_DEBUG_TOKEN?.trim()
+      : undefined;
+  if (debugToken) {
+    registerDebugSessionRoutesV1(
+      input.app,
+      new DebugSessionFacadeV1(
+        input.hosts,
+        input.runtime,
+        new DebugSessionIdCodecV1(debugToken),
+      ),
+    );
+  }
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
   const aiArtifacts = new AiArtifactRuntime(
     new AiArtifactCodec(requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET")),
@@ -117,11 +141,21 @@ export function registerAgentPlatformRuntime(input: {
     resolveAgentActor,
   );
   registerAiArtifactRoutes(aiRouteApp, aiArtifacts, internalToken);
+  const agentServerUrl =
+    process.env.AGENT_SERVER_URL || "http://agent-server:8080";
   const remote = new RemoteAgentRuntime({
-    baseUrl: process.env.AGENT_SERVER_URL || "http://agent-server:8080",
+    baseUrl: agentServerUrl,
     internalToken,
     toolHostUrl: process.env.AGENT_TOOL_HOST_URL || "http://server:9747",
   });
+  registerAiRuntimeReporting({
+    app: aiRouteApp,
+    features,
+    runtime: input.runtime,
+    systemRepositories: input.systemRepositories,
+    agentServerUrl,
+    internalToken,
+  });
   const grants = new ExecutionGrantStore();
   const runAuthorizations = new AgentRunAuthorizationStore(
     input.db
@@ -221,6 +255,37 @@ export function registerAgentPlatformRuntime(input: {
   return { toolHandlers, aiArtifacts, aiOperations };
 }
 
+export function registerAiRuntimeReporting(input: {
+  app: RouteApp;
+  features: FeatureFlagDefinition[];
+  runtime: ReturnType<typeof createServerRuntime>;
+  systemRepositories: SystemRepositories;
+  agentServerUrl: string;
+  internalToken: string;
+}): void {
+  registerAiRuntimeReportRoutes(
+    input.app,
+    new AiRuntimeReportService(
+      new RemoteAiRuntimeReportPort({
+        baseUrl: input.agentServerUrl,
+        internalToken: input.internalToken,
+      }),
+      new SystemAiRuntimeActorDirectory(
+        input.systemRepositories,
+        input.internalToken,
+      ),
+      {
+        descendants: departmentDescendantResolver(
+          input.systemRepositories.departments,
+        ),
+      },
+      input.runtime,
+    ),
+    input.runtime,
+    input.features,
+  );
+}
+
 function requiredEnvironment(key: string): string {
   const value = process.env[key]?.trim();
   if (!value) throw new Error(`启用 AI Runtime 时缺少 ${key}`);

package/template/apps/server/src/agent/tool-host.test.ts

@@ -180,6 +180,7 @@ async function createFixture(
       undefined,
     ).releaseId,
     idempotencyKey: "tool-host-test",
+    input: { question: "tool host" },
     authorizationSnapshot: {
       permissionKey: currentOperation.permissionKey,
       featureKey: currentOperation.featureKey,

package/template/apps/server/src/agent/unavailable-routes.ts

@@ -18,6 +18,10 @@ const unavailableRoutes = [
   ["POST", "/agent/runs/:runId/cancel"],
   ["POST", "/agent/runs/:runId/attach"],
   ["POST", "/internal/agent/tools/execute"],
+  ["GET", "/system/ai-runtime/summary"],
+  ["GET", "/system/ai-runtime/runs"],
+  ["GET", "/system/ai-runtime/runs/:runId"],
+  ["GET", "/system/ai-runtime/actors"],
 ] as const;
 
 export function registerUnavailableAiRoutes(app: RouteApp): void {

package/template/apps/server/src/ai-runtime-report/actor-directory.ts

@@ -0,0 +1,94 @@
+import type {
+  AiRuntimeActorPage,
+  AiRuntimeActorSummary,
+} from "@southwind-ai/shared";
+import {
+  DataAccessDeniedError,
+  DataScopedResourceService,
+} from "../data-access/scoped-resource.js";
+import { departmentDescendantResolver } from "../data-access/department-tree.js";
+import type { RequestActor } from "../guards.js";
+import type { ManagedUser } from "../system/entities.js";
+import type { SystemRepositories } from "../system/seed.js";
+import { AiRuntimeActorHandleCodec } from "./actor-handle.js";
+import type { AiRuntimeActorDirectory } from "./contracts.js";
+
+export class SystemAiRuntimeActorDirectory implements AiRuntimeActorDirectory {
+  readonly #access: DataScopedResourceService<ManagedUser>;
+  readonly #handles: AiRuntimeActorHandleCodec;
+
+  constructor(
+    repositories: Pick<SystemRepositories, "users" | "departments">,
+    handleSecret: string,
+  ) {
+    this.#access = new DataScopedResourceService(
+      repositories.users,
+      departmentDescendantResolver(repositories.departments),
+    );
+    this.#handles = new AiRuntimeActorHandleCodec(handleSecret);
+  }
+
+  async list(
+    query: { q?: string; page: number; pageSize: number },
+    actor: RequestActor,
+  ): Promise<AiRuntimeActorPage> {
+    const result = await this.#access.list(
+      {
+        ...query,
+        status: "active",
+        sort: [{ field: "displayName", order: "asc" }],
+      },
+      ["displayName", "username"],
+      actor,
+    );
+    return {
+      ...result,
+      items: result.items.map((user) => this.#actorSummary(user)),
+    };
+  }
+
+  async resolve(
+    actorIds: readonly string[],
+    actor: RequestActor,
+  ): Promise<Map<string, AiRuntimeActorSummary>> {
+    const result = new Map<string, AiRuntimeActorSummary>();
+    await Promise.all(
+      [...new Set(actorIds)].map(async (id) => {
+        try {
+          const user = await this.#access.get(id, actor);
+          if (user) result.set(id, this.#actorSummary(user));
+        } catch (error) {
+          if (!(error instanceof DataAccessDeniedError)) throw error;
+        }
+      }),
+    );
+    return result;
+  }
+
+  async resolveHandle(
+    handle: string,
+    actor: RequestActor,
+  ): Promise<string | undefined> {
+    const actorId = this.#handles.verify(handle);
+    if (!actorId) return undefined;
+    try {
+      const user = await this.#access.get(actorId, actor);
+      return user?.status === "active" ? user.id : undefined;
+    } catch (error) {
+      if (error instanceof DataAccessDeniedError) return undefined;
+      throw error;
+    }
+  }
+
+  #actorSummary(user: {
+    id: string;
+    username?: string;
+    displayName?: string;
+  }): AiRuntimeActorSummary {
+    return {
+      handle: this.#handles.issue(user.id),
+      displayName: user.displayName?.trim() || user.username || "未命名用户",
+      ...(user.username ? { username: user.username } : {}),
+    };
+  }
+}