create-windy 0.9.1 → 0.10.0

package/template/apps/server/src/system/feature-environment-assessment.ts

@@ -0,0 +1,179 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { EnvironmentSnapshot } from "../../../../packages/shared/src/environment-assessment.js";
+import type {
+  EnvironmentAssessmentSnapshot,
+  FeatureEnvironmentAssessment,
+  FeatureEnvironmentPolicy,
+} from "../../../../packages/shared/src/environment-policy.js";
+import type { EnvironmentPolicyRead } from "./environment-policy-reader.js";
+
+export interface FeatureAssessmentInput {
+  environment: EnvironmentSnapshot;
+  definitions: readonly FeatureFlagDefinition[];
+  resolveEnabled: (definition: FeatureFlagDefinition) => Promise<boolean>;
+  environmentValues?: Record<string, string | undefined>;
+}
+
+/** Advisory only: never changes features, licenses, running tasks, or build contents. */
+export async function assessFeatureEnvironment(
+  source: EnvironmentPolicyRead,
+  input: FeatureAssessmentInput,
+): Promise<EnvironmentAssessmentSnapshot> {
+  if (source.status !== "available") return { ...source, features: [] };
+  const definitions = new Map(
+    input.definitions.map((item) => [String(item.key), item]),
+  );
+  const features = await Promise.all(
+    source.policy.features.map(async (policy) => {
+      const definition = definitions.get(policy.key);
+      if (!definition)
+        return result(
+          policy,
+          "not-packaged",
+          "当前装配未注册此功能；请核对功能 Key 与交付模块。",
+          [],
+        );
+      let enabled: boolean;
+      try {
+        enabled = await input.resolveEnabled(definition);
+      } catch {
+        return result(
+          policy,
+          "unknown",
+          "功能开关状态读取失败；未修改配置。",
+          [],
+        );
+      }
+      return assessRequirements(policy, input, enabled);
+    }),
+  );
+  return {
+    status: "available",
+    message:
+      "评估只生成建议；请管理员核对证据后在功能管理中确认关闭。条件满足不代表模型或业务已验收。",
+    features,
+  };
+}
+function result(
+  policy: FeatureEnvironmentPolicy,
+  status: FeatureEnvironmentAssessment["status"],
+  message: string,
+  evidence: string[],
+): FeatureEnvironmentAssessment {
+  return {
+    key: policy.key,
+    title: policy.title,
+    status,
+    message,
+    evidence,
+    ...(policy.recommendedEnabled === undefined
+      ? {}
+      : { recommendedEnabled: policy.recommendedEnabled }),
+  };
+}
+function assessRequirements(
+  policy: FeatureEnvironmentPolicy,
+  input: FeatureAssessmentInput,
+  enabled: boolean,
+) {
+  const process = input.environment.process;
+  const evidence = [
+    `当前功能开关：${enabled ? "开启" : "关闭"}`,
+    `应用进程：${process.platform}/${process.architecture}；此信息不代表宿主机硬件`,
+    `声明执行方式：${policy.execution}`,
+  ];
+  if (
+    policy.supportedPlatforms?.length &&
+    !policy.supportedPlatforms.includes(process.platform)
+  )
+    return result(
+      policy,
+      "software",
+      "当前应用运行平台不在声明支持范围；更换硬件不一定能解决。",
+      evidence,
+    );
+  if (
+    policy.supportedArchitectures?.length &&
+    !policy.supportedArchitectures.includes(process.architecture)
+  )
+    return result(
+      policy,
+      "software",
+      "当前应用架构不在声明的软件支持范围；需匹配的软件构建。",
+      evidence,
+    );
+  const missing = (policy.requiredEnvironmentKeys ?? []).filter(
+    (key) => !(input.environmentValues ?? {})[key]?.trim(),
+  );
+  if (missing.length)
+    return result(policy, "configuration", "所需配置未就绪；不能归因于硬件。", [
+      ...evidence,
+      `缺少配置项：${missing.join("、")}`,
+    ]);
+  const needsHost =
+    policy.execution !== "remote" &&
+    (policy.execution === "local-gpu" || policy.minMemoryGiB !== undefined);
+  if (needsHost) {
+    const host = input.environment.host;
+    if (host.status !== "available" || !host.report)
+      return result(
+        policy,
+        "unknown",
+        "缺少有效宿主机证据；容器中未检测到设备不等于宿主机没有设备。",
+        evidence,
+      );
+    evidence.push(`宿主机采集时间：${host.report.collectedAt}`);
+    const facts = host.report.facts;
+    if (policy.minMemoryGiB !== undefined) {
+      if (facts.memoryTotalBytes === null)
+        return result(
+          policy,
+          "unknown",
+          "宿主机内存数据未知，无法判断最低内存条件。",
+          evidence,
+        );
+      evidence.push(
+        `宿主机总内存：${(facts.memoryTotalBytes / 1024 ** 3).toFixed(1)} GiB；要求至少 ${policy.minMemoryGiB} GiB`,
+      );
+      if (facts.memoryTotalBytes < policy.minMemoryGiB * 1024 ** 3)
+        return result(
+          policy,
+          "hardware",
+          "宿主机总内存低于声明的最低要求。",
+          evidence,
+        );
+    }
+    if (policy.execution === "local-gpu") {
+      if (facts.gpuCount === undefined)
+        return result(
+          policy,
+          "unknown",
+          "未取得有效 NVIDIA GPU 查询；需核对设备、驱动、权限与采集工具。",
+          evidence,
+        );
+      evidence.push(`NVIDIA GPU 数量：${facts.gpuCount}`);
+      if (facts.gpuCount === 0)
+        return result(
+          policy,
+          "hardware",
+          "有效宿主机查询未返回所需 GPU；本地 GPU 执行条件不满足。",
+          evidence,
+        );
+    }
+  }
+  if (!enabled)
+    return result(
+      policy,
+      "disabled",
+      "功能当前已关闭；环境评估不会自动开启。",
+      evidence,
+    );
+  return result(
+    policy,
+    "available",
+    policy.execution === "none"
+      ? "声明条件已满足；仍以实际业务验收为准。"
+      : "声明条件已满足；模型 readiness、驱动兼容、容器配额及性能尚需单独验收。",
+    evidence,
+  );
+}

package/template/apps/server/src/system/host-diagnostics.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  HOST_PROBE_KEYS,
+  type HostDiagnosticsReport,
+} from "@southwind-ai/shared";
+import {
+  createEnvironmentProbe,
+  parseHostDiagnostics,
+  readHostDiagnostics,
+} from "./host-diagnostics.js";
+
+const now = Date.parse("2026-11-06T12:00:00Z");
+function fixture(): HostDiagnosticsReport {
+  return {
+    schemaVersion: 1,
+    scope: "host",
+    collector: "windy-host-diagnostics-v1",
+    collectedAt: new Date(now).toISOString(),
+    facts: {
+      os: "linux",
+      kernel: "6.1",
+      architecture: "aarch64",
+      cpuLogicalCount: 8,
+      memoryTotalBytes: 16 * 1024 ** 3,
+    },
+    probes: Object.fromEntries(
+      HOST_PROBE_KEYS.map((key) => [
+        key,
+        {
+          status: "missing",
+          exitCode: null,
+          output: "",
+          truncated: false,
+        },
+      ]),
+    ) as HostDiagnosticsReport["probes"],
+  };
+}
+const directories: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    directories
+      .splice(0)
+      .map((dir) => rm(dir, { recursive: true, force: true })),
+  );
+});
+
+test("valid host report preserves unknown GPU and strips undeclared data", () => {
+  const input = { ...fixture(), secret: "not-returned" };
+  const result = parseHostDiagnostics(input, now);
+  expect(result.status).toBe("available");
+  expect(result.report?.facts.gpuCount).toBeUndefined();
+  expect(JSON.stringify(result)).not.toContain("not-returned");
+});
+
+test("version, scope, future date, over-budget output and missing probes fail closed", () => {
+  for (const patch of [
+    { schemaVersion: 2 },
+    { scope: "process" },
+    { collectedAt: "invalid" },
+    { collectedAt: new Date(now + 600_000).toISOString() },
+    { probes: {} },
+  ]) {
+    expect(parseHostDiagnostics({ ...fixture(), ...patch }, now).status).toBe(
+      "invalid",
+    );
+  }
+  const report = fixture();
+  report.probes.cpu.output = "x".repeat(16385);
+  expect(parseHostDiagnostics(report, now).status).toBe("invalid");
+  expect(
+    parseHostDiagnostics(fixture(), now + 25 * 60 * 60 * 1000).status,
+  ).toBe("stale");
+});
+
+test("bounded file read refuses symlink and oversized file and handles absence", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "windy-host-report-"));
+  directories.push(directory);
+  const path = join(directory, "report.json");
+  await writeFile(path, JSON.stringify(fixture()));
+  expect((await readHostDiagnostics(path, now)).status).toBe("available");
+  const link = join(directory, "link.json");
+  await symlink(path, link);
+  expect((await readHostDiagnostics(link, now)).status).toBe("unreadable");
+  await writeFile(path, "x".repeat(256 * 1024 + 1));
+  expect((await readHostDiagnostics(path, now)).status).toBe("invalid");
+  expect(
+    (await readHostDiagnostics(join(directory, "missing"), now)).status,
+  ).toBe("unreadable");
+});
+
+test("without a mount only process scope is reported", async () => {
+  const snapshot = await createEnvironmentProbe({ WINDY_CONTAINERIZED: "1" })();
+  expect(snapshot.process.scope).toBe("process");
+  expect(snapshot.process.containerized).toBe(true);
+  expect(snapshot.host.status).toBe("not-configured");
+  expect(snapshot.host.report).toBeUndefined();
+});
+
+test("deployment metadata is whitelisted and cannot carry arbitrary manifest contents", () => {
+  const result = parseHostDiagnostics(
+    {
+      ...fixture(),
+      deployment: {
+        status: "available",
+        releaseId: "20261106",
+        gitSha: "abcdef123",
+        platform: "linux/arm64",
+        secret: "never-return",
+      },
+    },
+    now,
+  );
+  expect(result.report?.deployment).toEqual({
+    status: "available",
+    releaseId: "20261106",
+    gitSha: "abcdef123",
+    platform: "linux/arm64",
+  });
+  expect(
+    parseHostDiagnostics(
+      { ...fixture(), deployment: { status: "available", gitSha: "invalid" } },
+      now,
+    ).status,
+  ).toBe("invalid");
+});
+
+test("GPU count is not trusted when its probe is missing, failed or truncated", () => {
+  for (const status of [
+    "missing",
+    "failed",
+    "permission-denied",
+    "timeout",
+    "unsupported",
+  ] as const) {
+    const report = fixture();
+    report.facts.gpuCount = 0;
+    report.probes.gpu.status = status;
+    expect(
+      parseHostDiagnostics(report, now).report?.facts.gpuCount,
+    ).toBeUndefined();
+  }
+  const report = fixture();
+  report.facts.gpuCount = 0;
+  report.probes.gpu.status = "ok";
+  report.probes.gpu.truncated = true;
+  expect(
+    parseHostDiagnostics(report, now).report?.facts.gpuCount,
+  ).toBeUndefined();
+  report.probes.gpu.truncated = false;
+  expect(parseHostDiagnostics(report, now).report?.facts.gpuCount).toBe(0);
+});

package/template/apps/server/src/system/host-diagnostics.ts

@@ -0,0 +1,225 @@
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+import { cpus, totalmem } from "node:os";
+import {
+  HOST_PROBE_KEYS,
+  type EnvironmentSnapshot,
+  type HostDiagnosticsReport,
+  type HostDiagnosticProbe,
+} from "@southwind-ai/shared";
+
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const statuses = new Set([
+  "ok",
+  "missing",
+  "permission-denied",
+  "timeout",
+  "failed",
+  "unsupported",
+]);
+type HostState = EnvironmentSnapshot["host"];
+export type EnvironmentProbe = () => Promise<EnvironmentSnapshot>;
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+function text(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length <= max;
+}
+function count(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** Constructs a bounded whitelist projection; unknown fields are never returned to clients. */
+export function parseHostDiagnostics(
+  value: unknown,
+  now = Date.now(),
+): HostState {
+  const data = record(value);
+  const facts = record(data?.facts);
+  const probes = record(data?.probes);
+  if (
+    !data ||
+    data.schemaVersion !== 1 ||
+    data.scope !== "host" ||
+    data.collector !== "windy-host-diagnostics-v1" ||
+    !text(data.collectedAt, 64) ||
+    !facts ||
+    !probes ||
+    !text(facts.os, 128) ||
+    !(facts.distribution === undefined || text(facts.distribution, 256)) ||
+    !text(facts.kernel, 256) ||
+    !text(facts.architecture, 64) ||
+    !count(facts.cpuLogicalCount) ||
+    !(facts.memoryTotalBytes === null || count(facts.memoryTotalBytes)) ||
+    !(facts.gpuCount === undefined || count(facts.gpuCount))
+  ) {
+    return invalid();
+  }
+  const collectedAt = Date.parse(data.collectedAt);
+  if (!Number.isFinite(collectedAt) || collectedAt > now + 5 * 60 * 1000)
+    return invalid();
+  if (now - collectedAt > MAX_AGE_MS)
+    return {
+      status: "stale",
+      message: "宿主机诊断文件超过 24 小时，请在宿主机重新采集。",
+    };
+  const selected = {} as Record<
+    (typeof HOST_PROBE_KEYS)[number],
+    HostDiagnosticProbe
+  >;
+  for (const key of HOST_PROBE_KEYS) {
+    const probe = record(probes[key]);
+    if (
+      !probe ||
+      typeof probe.status !== "string" ||
+      !statuses.has(probe.status) ||
+      !text(probe.output, 16384) ||
+      typeof probe.truncated !== "boolean" ||
+      !(
+        probe.exitCode === null ||
+        (typeof probe.exitCode === "number" &&
+          Number.isSafeInteger(probe.exitCode))
+      )
+    ) {
+      return invalid();
+    }
+    selected[key] = {
+      status: probe.status as HostDiagnosticProbe["status"],
+      output: probe.output,
+      exitCode: probe.exitCode as number | null,
+      truncated: probe.truncated,
+    };
+  }
+  const deployment = parseDeployment(data.deployment);
+  if (deployment === null) return invalid();
+  const report: HostDiagnosticsReport = {
+    schemaVersion: 1,
+    scope: "host",
+    collector: "windy-host-diagnostics-v1",
+    collectedAt: data.collectedAt,
+    facts: {
+      os: facts.os,
+      ...(facts.distribution ? { distribution: facts.distribution } : {}),
+      kernel: facts.kernel,
+      architecture: facts.architecture,
+      cpuLogicalCount: facts.cpuLogicalCount,
+      memoryTotalBytes: facts.memoryTotalBytes,
+      ...(facts.gpuCount !== undefined &&
+      selected.gpu.status === "ok" &&
+      !selected.gpu.truncated
+        ? { gpuCount: facts.gpuCount }
+        : {}),
+    },
+    probes: selected,
+    ...(deployment ? { deployment } : {}),
+  };
+  return {
+    status: "available",
+    message: "已读取宿主机采集文件；这是采集时快照，不是实时监控。",
+    report,
+  };
+}
+
+function parseDeployment(
+  value: unknown,
+): HostDiagnosticsReport["deployment"] | null {
+  if (value === undefined) return undefined;
+  const item = record(value);
+  if (
+    !item ||
+    !["available", "invalid", "unreadable"].includes(String(item.status))
+  )
+    return null;
+  if (item.status !== "available")
+    return { status: item.status as "invalid" | "unreadable" };
+  const patterns = {
+    releaseId: /^[A-Za-z0-9._-]{1,128}$/,
+    gitSha: /^[a-fA-F0-9]{7,64}$/,
+    platform: /^[A-Za-z0-9._/-]{1,64}$/,
+  };
+  const result: NonNullable<HostDiagnosticsReport["deployment"]> = {
+    status: "available",
+  };
+  let count = 0;
+  for (const key of ["releaseId", "gitSha", "platform"] as const) {
+    const field = item[key];
+    if (field === undefined) continue;
+    if (typeof field !== "string" || !patterns[key].test(field)) return null;
+    result[key] = field;
+    count++;
+  }
+  return count ? result : null;
+}
+
+function invalid(): HostState {
+  return {
+    status: "invalid",
+    message: "宿主机诊断文件格式、大小或采集时间无效。",
+  };
+}
+
+export async function readHostDiagnostics(
+  path: string | undefined,
+  now = Date.now(),
+): Promise<HostState> {
+  if (!path)
+    return {
+      status: "not-configured",
+      message: "未挂载宿主机诊断文件；以下运行进程信息不能代表宿主机。",
+    };
+  let file: Awaited<ReturnType<typeof open>> | undefined;
+  try {
+    file = await open(
+      path,
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    );
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return invalid();
+    const buffer = Buffer.alloc(MAX_FILE_BYTES + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const read = await file.read(buffer, bytes, buffer.length - bytes, null);
+      if (!read.bytesRead) break;
+      bytes += read.bytesRead;
+    }
+    if (bytes > MAX_FILE_BYTES) return invalid();
+    try {
+      return parseHostDiagnostics(
+        JSON.parse(buffer.subarray(0, bytes).toString("utf8")),
+        now,
+      );
+    } catch {
+      return invalid();
+    }
+  } catch {
+    return {
+      status: "unreadable",
+      message: "无法读取宿主机诊断文件，请检查只读挂载与文件权限。",
+    };
+  } finally {
+    await file?.close();
+  }
+}
+
+export function createEnvironmentProbe(
+  env: Record<string, string | undefined> = process.env,
+): EnvironmentProbe {
+  return async () => ({
+    generatedAt: new Date().toISOString(),
+    process: {
+      scope: "process",
+      platform: process.platform,
+      architecture: process.arch,
+      nodeVersion: process.version,
+      ...(process.versions.bun ? { bunVersion: process.versions.bun } : {}),
+      containerized: env.WINDY_CONTAINERIZED === "1",
+      logicalCpuCount: cpus().length,
+      memoryTotalBytes: totalmem(),
+    },
+    host: await readHostDiagnostics(env.WINDY_HOST_DIAGNOSTICS_FILE),
+  });
+}

package/template/apps/server/src/system/menu-registry.test.ts

@@ -39,6 +39,32 @@ describe("ManifestMenuRegistry", () => {
     // @windy-module system.settings end
   });
 
+  // @windy-module system.agent begin
+  test("同步时将旧运维目录内的 AI 入口移入新分组", async () => {
+    const repositories = createSystemRepositories(createFoundationSnapshot());
+    const registry = repositories.menuRegistry;
+    await registry.synchronize(actor);
+    await registry.updatePlacement(
+      "system.agent-workbench",
+      { parentKey: "system.operations", visible: false },
+      actor,
+    );
+    await registry.updatePlacement(
+      "system.agent-debug",
+      { parentKey: "system.identity" },
+      actor,
+    );
+    await registry.synchronize(actor);
+    expect(await registry.get("system.agent-workbench")).toMatchObject({
+      parentKey: "system.ai",
+      visible: false,
+    });
+    expect(await registry.get("system.agent-debug")).toMatchObject({
+      parentKey: "system.identity",
+    });
+  });
+  // @windy-module system.agent end
+
   test("支持调整父目录和同级顺序并拒绝循环父级", async () => {
     const repositories = createSystemRepositories(createFoundationSnapshot());
     await repositories.menuRegistry.synchronize(actor);

package/template/apps/server/src/system/menu-registry.ts

@@ -44,13 +44,15 @@ export class ManifestMenuRegistry {
         await this.repository.create(definition, actor);
         continue;
       }
-      const parentKey = this.validParentKey(
-        existing.key,
-        existing.parentKey,
-        storedByKey,
-      )
-        ? existing.parentKey
-        : definition.parentKey;
+      // Move existing AI entries that still use their former default group.
+      const moveToAiGroup =
+        definition.parentKey === "system.ai" &&
+        existing.parentKey === "system.operations";
+      const parentKey =
+        !moveToAiGroup &&
+        this.validParentKey(existing.key, existing.parentKey, storedByKey)
+          ? existing.parentKey
+          : definition.parentKey;
       await this.repository.update(
         existing.id,
         {

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

@@ -198,6 +198,11 @@ describe("system operation routes", () => {
       app,
       runtime,
       createFoundationSnapshot().features,
+      {
+        environmentProbe: async () => {
+          throw new Error("unauthorized host read");
+        },
+      },
     );
     const guardContext = await runtime.createGuardContext(
       new Request("http://localhost/api/system/operations"),