create-windy 0.4.0 → 0.5.0

package/template/packages/server-sdk/src/debug-session-provider.ts

@@ -0,0 +1,63 @@
+import type { ModuleActor } from "./actor.js";
+
+export const MODULE_DEBUG_SESSION_SCHEMA_VERSION = 1 as const;
+
+export interface ModuleDebugSessionContextV1 {
+  readonly actor: ModuleActor;
+  readonly operationKey: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleDebugSessionListInputV1 extends ModuleDebugSessionContextV1 {
+  readonly limit: number;
+  /** Provider 私有的不透明 keyset cursor；Host 只原样回传给同一 Provider。 */
+  readonly cursor?: string;
+}
+
+export interface ModuleDebugSessionGetInputV1 extends ModuleDebugSessionContextV1 {
+  readonly sourceId: string;
+}
+
+export interface ModuleDebugSessionSummaryV1 {
+  /** 仅在 Provider 与 Host 之间使用，不会返回给 ADK Web。 */
+  readonly sourceId: string;
+  readonly title: string;
+  readonly scopeLabel?: string;
+  readonly updatedAt: string;
+  readonly revision: string;
+}
+
+export interface ModuleDebugSessionPageV1 {
+  readonly sessions: readonly ModuleDebugSessionSummaryV1[];
+  readonly truncated: boolean;
+  /** truncated=true 时必须提供，用于 Host 继续读取直到完整。 */
+  readonly next?: string;
+}
+
+export interface ModuleDebugSessionMessageV1 {
+  readonly sequence: number;
+  readonly role: "user" | "assistant";
+  readonly content: string;
+  readonly createdAt: string;
+}
+
+export interface ModuleDebugSessionV1 extends ModuleDebugSessionSummaryV1 {
+  readonly messages: readonly ModuleDebugSessionMessageV1[];
+}
+
+/**
+ * 开发期 ADK Web 会话投影。Provider 只读业务事实，Host 负责重新授权、审计、
+ * 有界校验与不透明 ID；V1 不支持业务会话的追加、重命名或删除。
+ */
+export interface ModuleDebugSessionProviderV1 {
+  readonly schemaVersion: typeof MODULE_DEBUG_SESSION_SCHEMA_VERSION;
+  readonly key: string;
+  readonly operationKeys: readonly string[];
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  list(input: ModuleDebugSessionListInputV1): Promise<ModuleDebugSessionPageV1>;
+  get(
+    input: ModuleDebugSessionGetInputV1,
+  ): Promise<ModuleDebugSessionV1 | undefined>;
+}

package/template/packages/server-sdk/src/module-host.ts

@@ -1,4 +1,5 @@
 import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
+import type { ModuleDebugSessionProviderV1 } from "./debug-session-provider.js";
 import type { ModuleDurableHandlerDefinition } from "./durable-handler.js";
 import type { ModuleGovernedResourceRegistration } from "./data-governance-registration.js";
 import type { ModuleRolePreset } from "./role-preset.js";
@@ -60,6 +61,10 @@ export interface ModuleHost {
   registerRolePresets(presets: readonly ModuleRolePreset[]): void;
   /** 注册 Manifest `providers` 已声明的搜索 Provider。 */
   registerSearchProviders(providers: readonly ModuleSearchProvider[]): void;
+  /** 注册开发期 ADK Web 使用的只读业务会话投影。 */
+  registerDebugSessionProviders(
+    providers: readonly ModuleDebugSessionProviderV1[],
+  ): void;
 }
 
 /**

package/template/packages/shared/index.ts

@@ -1,4 +1,7 @@
 export * from "./src/audit.js";
+// @windy-module system.agent begin
+export * from "./src/ai-runtime-report.js";
+// @windy-module system.agent end
 export * from "./src/database.js";
 export * from "./src/data-governance.js";
 export * from "./src/feature.js";

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/ai-runtime-report.ts

@@ -0,0 +1,134 @@
+import type { ISODateTime, PageResult } from "./primitives.js";
+
+export type AiRuntimeReportRange = "day" | "month" | "retained";
+export type AiRuntimeRunStatus =
+  | "accepted"
+  | "running"
+  | "awaiting-approval"
+  | "completed"
+  | "failed"
+  | "cancelled";
+export type AiRuntimeAttemptOutcome =
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "blocked"
+  | "abandoned";
+export type AiRuntimeCacheStatus = "hit" | "miss" | "unknown";
+export type AiRuntimeUsageSource =
+  | "provider-reported"
+  | "estimated"
+  | "unknown";
+
+export interface AiRuntimeRunCounts {
+  total: number;
+  completed: number;
+  failed: number;
+  cancelled: number;
+  inProgress: number;
+  successRate: number | null;
+}
+
+export interface AiRuntimeCacheSummary {
+  hit: number;
+  miss: number;
+  unknown: number;
+  hitRate: number | null;
+  tokenRate: number | null;
+  coverageRate: number;
+}
+
+export interface AiRuntimeTokenSummary {
+  input: number | null;
+  output: number | null;
+  cachedInput: number | null;
+  reasoning: number | null;
+  total: number | null;
+  coverageRate: number;
+}
+
+export interface AiRuntimeModelUsageSummary {
+  deploymentKey: string;
+  model: string;
+  attempts: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cachedInputTokens: number | null;
+  reasoningTokens: number | null;
+  totalTokens: number | null;
+  unknownUsageCount: number;
+}
+
+export interface AiRuntimeActivityPoint {
+  date: string;
+  runs: number;
+  completed: number;
+  failed: number;
+  totalTokens: number | null;
+}
+
+export interface AiRuntimeReportSummary {
+  generatedAt: ISODateTime;
+  reportingAvailableFrom: ISODateTime | null;
+  retentionDays: number;
+  runs: AiRuntimeRunCounts;
+  cache: AiRuntimeCacheSummary;
+  tokens: AiRuntimeTokenSummary;
+  byModel: AiRuntimeModelUsageSummary[];
+  activity: AiRuntimeActivityPoint[];
+}
+
+export interface AiRuntimeActorSummary {
+  handle: string;
+  displayName: string;
+  username?: string;
+}
+
+export interface AiRuntimeRunUsage {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cachedInputTokens: number | null;
+  reasoningTokens: number | null;
+  totalTokens: number | null;
+}
+
+export interface AiRuntimeRunListItem {
+  runId: string;
+  operationKey: string;
+  actor: AiRuntimeActorSummary | null;
+  status: AiRuntimeRunStatus;
+  startedAt: ISODateTime | null;
+  finishedAt: ISODateTime | null;
+  durationMs: number | null;
+  attemptCount: number;
+  models: string[];
+  cacheStatus: AiRuntimeCacheStatus;
+  usage: AiRuntimeRunUsage;
+}
+
+export interface AiRuntimeAttemptDetail extends AiRuntimeRunUsage {
+  attemptId: string;
+  sequence: number;
+  toolRound: number;
+  deploymentKey: string;
+  model: string;
+  outcome: AiRuntimeAttemptOutcome;
+  cacheStatus: AiRuntimeCacheStatus;
+  usageSource: AiRuntimeUsageSource;
+  firstTokenLatencyMs: number | null;
+  durationMs: number | null;
+  safeErrorCode: string | null;
+  startedAt: ISODateTime;
+  finishedAt: ISODateTime | null;
+}
+
+export interface AiRuntimeRunDetail extends AiRuntimeRunListItem {
+  releaseId: string;
+  traceId: string;
+  safeErrorCode: string | null;
+  attempts: AiRuntimeAttemptDetail[];
+}
+
+export type AiRuntimeRunPage = PageResult<AiRuntimeRunListItem>;
+export type AiRuntimeActorPage = PageResult<AiRuntimeActorSummary>;

package/template/packages/shared/src/platform-settings.ts

@@ -18,12 +18,27 @@ export const WATERMARK_CONTENT_FIELDS = [
 ] as const;
 export type WatermarkContentField = (typeof WATERMARK_CONTENT_FIELDS)[number];
 
+export const WATERMARK_OPACITY_RANGE = {
+  min: 3,
+  max: 30,
+  step: 1,
+} as const;
+
+export const WATERMARK_FONT_SIZE_RANGE = {
+  min: 12,
+  max: 32,
+  step: 1,
+} as const;
+
 export interface PlatformWatermarkPolicy {
   enabled: boolean;
+  /** @deprecated 升级兼容字段，始终与 enabled 保持一致。 */
   businessPagesEnabled: boolean;
   density: WatermarkDensity;
   contentFields: WatermarkContentField[];
   customContent: string;
+  opacityPercent: number;
+  fontSize: number;
 }
 
 export const DEFAULT_PLATFORM_WATERMARK_POLICY: Readonly<PlatformWatermarkPolicy> =
@@ -33,4 +48,6 @@ export const DEFAULT_PLATFORM_WATERMARK_POLICY: Readonly<PlatformWatermarkPolicy
     density: "medium",
     contentFields: ["username", "displayName"],
     customContent: "",
+    opacityPercent: 8,
+    fontSize: 14,
   };

package/template/scripts/lib/postgres-regression.ts

@@ -0,0 +1,201 @@
+import { resolve } from "node:path";
+
+export interface CommandOptions {
+  allowFailure?: boolean;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stdin?: string;
+  stdout?: "inherit" | "pipe";
+  stderr?: "inherit" | "pipe";
+}
+
+export interface CommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export const repositoryRoot = resolve(import.meta.dir, "../..");
+
+export async function runCommand(
+  command: string[],
+  options: CommandOptions = {},
+): Promise<CommandResult> {
+  const child = Bun.spawn(command, {
+    cwd: options.cwd || repositoryRoot,
+    env: options.env ?? process.env,
+    stdin: options.stdin === undefined ? undefined : "pipe",
+    stdout: options.stdout || "pipe",
+    stderr: options.stderr || "pipe",
+  });
+  if (options.stdin !== undefined) {
+    child.stdin.write(options.stdin);
+    child.stdin.end();
+  }
+  const [stdout, stderr, exitCode] = await Promise.all([
+    child.stdout ? new Response(child.stdout).text() : "",
+    child.stderr ? new Response(child.stderr).text() : "",
+    child.exited,
+  ]);
+  if (exitCode !== 0 && !options.allowFailure) {
+    throw new Error(
+      `${command.join(" ")} failed (${exitCode})\n${stdout}${stderr}`,
+    );
+  }
+  return { exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+export class PostgresRegressionHarness {
+  readonly container: string;
+  private port?: string;
+
+  constructor(prefix: string) {
+    this.container = `${prefix}-${crypto.randomUUID().slice(0, 8)}`;
+  }
+
+  async start(): Promise<void> {
+    await runCommand([
+      "docker",
+      "run",
+      "--rm",
+      "--detach",
+      "--name",
+      this.container,
+      "--env",
+      "POSTGRES_DB=windy",
+      "--env",
+      "POSTGRES_USER=windy",
+      "--env",
+      "POSTGRES_PASSWORD=windy",
+      "--publish",
+      "127.0.0.1::5432",
+      "postgres:17-alpine",
+    ]);
+    await this.waitUntilReady();
+    const portResult = await runCommand([
+      "docker",
+      "port",
+      this.container,
+      "5432/tcp",
+    ]);
+    this.port = portResult.stdout.match(/:(\d+)$/)?.[1];
+    if (!this.port) {
+      throw new Error(`无法解析 PostgreSQL 端口：${portResult.stdout}`);
+    }
+  }
+
+  databaseUrl(database = "windy"): string {
+    if (!this.port) throw new Error("PostgreSQL 容器尚未启动");
+    const url = new URL(`postgresql://127.0.0.1:${this.port}/${database}`);
+    url.username = "windy";
+    url.password = "windy";
+    return url.toString();
+  }
+
+  async createDatabase(database: string): Promise<void> {
+    await this.execute(`CREATE DATABASE ${quoteIdentifier(database)}`, "windy");
+  }
+
+  async execute(sql: string, database = "windy"): Promise<void> {
+    await this.psql(sql, database);
+  }
+
+  async query(sql: string, database = "windy"): Promise<string> {
+    return (await this.psql(sql, database)).stdout;
+  }
+
+  async migrate(
+    database = "windy",
+    allowFailure = false,
+  ): Promise<CommandResult> {
+    return runCommand(["bun", "run", "db:migrate"], {
+      allowFailure,
+      env: { ...process.env, DATABASE_URL: this.databaseUrl(database) },
+    });
+  }
+
+  async close(): Promise<void> {
+    await runCommand(["docker", "rm", "--force", this.container], {
+      allowFailure: true,
+    });
+  }
+
+  private async psql(sql: string, database: string): Promise<CommandResult> {
+    return runCommand(
+      [
+        "docker",
+        "exec",
+        "--interactive",
+        this.container,
+        "psql",
+        "--set",
+        "ON_ERROR_STOP=1",
+        "--username",
+        "windy",
+        "--dbname",
+        database,
+        "--tuples-only",
+        "--no-align",
+      ],
+      { stdin: sql },
+    );
+  }
+
+  private async waitUntilReady(): Promise<void> {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+      const [result, logs] = await Promise.all([
+        runCommand(
+          [
+            "docker",
+            "exec",
+            this.container,
+            "pg_isready",
+            "--username",
+            "windy",
+            "--dbname",
+            "windy",
+          ],
+          { allowFailure: true },
+        ),
+        runCommand(["docker", "logs", this.container], {
+          allowFailure: true,
+        }),
+      ]);
+      if (
+        result.exitCode === 0 &&
+        `${logs.stdout}\n${logs.stderr}`.includes(
+          "PostgreSQL init process complete; ready for start up.",
+        )
+      ) {
+        return;
+      }
+      await Bun.sleep(500);
+    }
+    throw new Error("PostgreSQL 未在 30 秒内就绪");
+  }
+}
+
+export function expectEqual(
+  actual: string,
+  expected: string,
+  label: string,
+): void {
+  if (actual !== expected) {
+    throw new Error(`${label}：期望 ${expected}，实际 ${actual}`);
+  }
+}
+
+export function expect(condition: unknown, label: string): asserts condition {
+  if (!condition) throw new Error(label);
+}
+
+export function sqlLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function quoteIdentifier(value: string): string {
+  if (!/^[a-z][a-z0-9_]*$/.test(value)) {
+    throw new Error(`不安全的数据库标识符：${value}`);
+  }
+  return `"${value}"`;
+}