create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent-skills/service.ts

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import type {
+  AgentSkillBundle,
+  AgentSkillCommandRequest,
+  AgentSkillVersion,
+  AuditEvent,
+  ImportAgentSkillRequest,
+} from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import {
+  requireSkillAccess,
+  skillRequirementsAvailable,
+  skillActor,
+  skillGovernable,
+  skillReadable,
+  type AgentSkillAccess,
+} from "./access.js";
+import { parseSkillBundle, hashSkillValue, skillKey } from "./bundle.js";
+import {
+  AgentSkillError,
+  type AgentSkillRepository,
+  type StoredAgentSkill,
+} from "./contracts.js";
+
+import {
+  registerBuiltinSkillBundles,
+  type BuiltinAgentSkill,
+} from "./builtin-registration.js";
+export type { BuiltinAgentSkill } from "./builtin-registration.js";
+import { validateImport, version } from "./input.js";
+import { AgentSkillReader } from "./reader.js";
+export class AgentSkillService extends AgentSkillReader {
+  constructor(
+    repository: AgentSkillRepository,
+    access: AgentSkillAccess,
+    private readonly audit: (event: AuditEvent) => Promise<void>,
+  ) {
+    super(repository, access);
+  }
+  async publish(
+    input: ImportAgentSkillRequest,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+  ) {
+    await requireSkillAccess(this.access, context, "manage");
+    validateImport(input);
+    const bundle = parseSkillBundle(input),
+      actor = skillActor(context);
+    if (
+      (input.scope === "tenant" && !actor.tenantWide) ||
+      (input.scope === "department" && !actor.departmentId)
+    )
+      throw new AgentSkillError(
+        "SKILL_SCOPE_FORBIDDEN",
+        "当前身份不能发布到该共享范围",
+        403,
+      );
+    const requirements = input.requirements ?? [];
+    for (const requirement of requirements)
+      if (!(await this.access.requirement(context, requirement)))
+        throw new AgentSkillError(
+          "SKILL_REQUIREMENT_UNAVAILABLE",
+          "技能依赖未注册或当前不可用",
+          409,
+        );
+    return this.mutate(
+      bundle.name,
+      input.expectedVersion,
+      idempotencyKey,
+      { action: "publish", input },
+      context,
+      async (current) => {
+        if (current && !skillGovernable(current.metadata, context))
+          throw unavailable();
+        if (
+          input.scope === "personal" &&
+          current &&
+          current.metadata.ownerActorId !== actor.actorId
+        )
+          throw new AgentSkillError(
+            "SKILL_SCOPE_FORBIDDEN",
+            "不能将其他所有者的技能改为个人范围",
+            403,
+          );
+        return {
+          bundle,
+          metadata: {
+            key: bundle.name,
+            version: input.expectedVersion + 1,
+            tenantId: actor.tenantId,
+            ownerActorId: current?.metadata.ownerActorId ?? actor.actorId,
+            departmentId:
+              input.scope === "department" ? actor.departmentId : undefined,
+            scope: input.scope,
+            origin: current?.metadata.origin ?? "shared",
+            status: "published",
+            name: bundle.displayName,
+            description: bundle.description,
+            digest: bundle.digest,
+            requirements,
+            safetyConstraints: input.safetyConstraints ?? [],
+            createdAt: new Date().toISOString(),
+            createdBy: actor.actorId,
+            source: "admin-import",
+          },
+        };
+      },
+    );
+  }
+  async command(
+    key: string,
+    action: "disable" | "rollback",
+    input: AgentSkillCommandRequest,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+  ) {
+    await requireSkillAccess(this.access, context, "manage");
+    skillKey(key);
+    version(input.expectedVersion);
+    if (
+      action === "rollback" &&
+      (!Number.isSafeInteger(input.version) || input.version! < 1)
+    )
+      throw new AgentSkillError(
+        "SKILL_INPUT_INVALID",
+        "请选择要回滚的历史版本",
+      );
+    return this.mutate(
+      key,
+      input.expectedVersion,
+      idempotencyKey,
+      { action, input },
+      context,
+      async (current, records) => {
+        if (!current || !skillGovernable(current.metadata, context))
+          throw unavailable();
+        const target =
+          action === "rollback"
+            ? records.find(
+                (record) =>
+                  record.auditCommitted &&
+                  record.metadata.version === input.version &&
+                  record.metadata.status === "published",
+              )
+            : current;
+        if (
+          !target ||
+          !skillReadable(target.metadata, context) ||
+          !skillGovernable(target.metadata, context)
+        )
+          throw unavailable();
+        const actor = skillActor(context);
+        if (
+          action === "rollback" &&
+          ((target.metadata.scope === "tenant" && !actor.tenantWide) ||
+            (target.metadata.scope === "department" &&
+              !actor.tenantWide &&
+              target.metadata.departmentId !== actor.departmentId))
+        )
+          throw new AgentSkillError(
+            "SKILL_SCOPE_FORBIDDEN",
+            "当前身份不能恢复该共享范围",
+            403,
+          );
+        if (
+          action === "rollback" &&
+          !(await skillRequirementsAvailable(
+            this.access,
+            target.metadata,
+            context,
+          ))
+        )
+          throw new AgentSkillError(
+            "SKILL_REQUIREMENT_UNAVAILABLE",
+            "目标版本依赖当前不可用",
+            409,
+          );
+        return {
+          bundle: target.bundle,
+          metadata: {
+            ...target.metadata,
+            version: input.expectedVersion + 1,
+            status: action === "disable" ? "disabled" : "published",
+            createdAt: new Date().toISOString(),
+            createdBy: context.actor.id,
+            ...(action === "rollback"
+              ? { restoredFromVersion: target.metadata.version }
+              : {}),
+          },
+        };
+      },
+    );
+  }
+  async registerBuiltins(
+    skills: readonly BuiltinAgentSkill[],
+    input: { readonly tenantId: string },
+  ) {
+    await this.recoverPendingAudits();
+    await registerBuiltinSkillBundles(skills, {
+      ...input,
+      repository: this.repository,
+      audit: this.audit,
+    });
+  }
+  async recordRead(
+    context: RequestGuardContext,
+    detail: {
+      readonly kind: "catalog" | "detail" | "versions";
+      readonly key?: string;
+      readonly version?: number;
+      readonly itemCount?: number;
+    },
+  ) {
+    await requireSkillAccess(this.access, context, "read");
+    await this.audit({
+      id: randomUUID(),
+      action: "agent.skill.read",
+      actor: auditActor(context),
+      outcome: "success",
+      target: { type: "agent-skill", id: detail.key ?? "catalog" },
+      requestId: context.requestId,
+      occurredAt: new Date().toISOString(),
+      metadata: {
+        kind: detail.kind,
+        ...(detail.version === undefined ? {} : { version: detail.version }),
+        ...(detail.itemCount === undefined
+          ? {}
+          : { itemCount: detail.itemCount }),
+      },
+    });
+  }
+  async recoverPendingAudits() {
+    let receipts = await this.repository.pendingAudits();
+    while (receipts.length) {
+      for (const receipt of receipts) {
+        await this.audit(receipt.audit);
+        await this.repository.acknowledge(receipt);
+      }
+      receipts = await this.repository.pendingAudits();
+    }
+  }
+  private async mutate(
+    key: string,
+    expectedVersion: number,
+    idempotencyKey: string,
+    payload: unknown,
+    context: RequestGuardContext,
+    change: (
+      current: StoredAgentSkill | undefined,
+      records: readonly StoredAgentSkill[],
+    ) => Promise<{ metadata: AgentSkillVersion; bundle: AgentSkillBundle }>,
+  ) {
+    version(expectedVersion);
+    if (!/^[A-Za-z0-9_.:-]{8,160}$/.test(idempotencyKey))
+      throw new AgentSkillError(
+        "SKILL_IDEMPOTENCY_REQUIRED",
+        "技能变更需要有效的幂等键",
+      );
+    const actor = skillActor(context),
+      receipt = await this.repository.mutate(
+        {
+          tenantId: actor.tenantId,
+          actorId: actor.actorId,
+          idempotencyKey,
+          requestDigest: hashSkillValue({ key, payload }),
+          key,
+          expectedVersion,
+        },
+        async (current, records) => {
+          const record = await change(current, records);
+          const action = (payload as { action: string }).action;
+          return {
+            record: { ...record, auditCommitted: false },
+            audit: {
+              id: randomUUID(),
+              action: `agent.skill.${action}`,
+              actor: auditActor(context),
+              outcome: "success",
+              target: { type: "agent-skill", id: key },
+              requestId: context.requestId,
+              occurredAt: new Date().toISOString(),
+              metadata: {
+                version: record.metadata.version,
+                digest: record.metadata.digest,
+                scope: record.metadata.scope,
+              },
+            },
+          };
+        },
+      );
+    if (!skillGovernable(receipt.result, context)) throw unavailable();
+    if (!receipt.auditCommitted) {
+      await this.audit(receipt.audit);
+      await this.repository.acknowledge(receipt);
+    }
+    return receipt.result;
+  }
+}
+function unavailable() {
+  return new AgentSkillError("SKILL_UNAVAILABLE", "技能或版本不可用", 404);
+}

package/template/apps/server/src/agent-workflow/preset-registry.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { systemModuleManifest } from "@southwind-ai/modules";
+import type { AgentWorkflowDefinition } from "@southwind-ai/shared";
+import { createServerRuntime } from "../runtime.js";
+import {
+  AgentWorkflowPresetRegistry,
+  type AgentWorkflowPresetRegistration,
+} from "./preset-registry.js";
+
+const module = systemModuleManifest("system.agent");
+const definition: AgentWorkflowDefinition = {
+  schemaVersion: 1,
+  workflowKey: "system.agent.example",
+  version: "1.0.0",
+  label: "示例",
+  entryNodeId: "final",
+  nodes: [
+    {
+      id: "final",
+      type: "final",
+      label: "结束",
+      outputSchemaKey: "system.agent.example.output",
+      failurePolicy: { mode: "fail-run" },
+    },
+  ],
+  edges: [],
+  budget: {
+    maxDurationSeconds: 60,
+    maxModelAttempts: 1,
+    maxToolCalls: 1,
+    maxSubagents: 0,
+    maxParallelism: 1,
+    maxInputTokens: 100,
+    maxOutputTokens: 100,
+    maxCostMicros: 0,
+  },
+};
+const registration: AgentWorkflowPresetRegistration = {
+  key: "system.agent.example",
+  moduleKey: "system.agent",
+  label: "示例工单",
+  description: "查看工单流程",
+  definition,
+  featureKey: "system.agent-workflow",
+  permissionKey: "system.agent-workflow.read",
+  entry: { path: "/work-orders", label: "进入工单" },
+};
+async function fixture() {
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "admin-token" },
+    { featureCatalog: module.features },
+  );
+  const context = await runtime.createGuardContext(
+    new Request("http://localhost/api/agent/workflows/presets", {
+      headers: { authorization: "Bearer admin-token" },
+    }),
+  );
+  context.actor = {
+    ...context.actor,
+    permissionKeys: [
+      ...context.actor.permissionKeys,
+      "system.agent-workflow.read",
+    ],
+  };
+  return { runtime, context };
+}
+
+describe("Workflow 预设只读目录", () => {
+  test("拒绝重复、未知模块、未知能力和外部业务入口", () => {
+    expect(
+      () =>
+        new AgentWorkflowPresetRegistry([module], [registration, registration]),
+    ).toThrow();
+    expect(() => new AgentWorkflowPresetRegistry([], [registration])).toThrow();
+    expect(
+      () =>
+        new AgentWorkflowPresetRegistry(
+          [module],
+          [{ ...registration, permissionKey: "system.agent-workflow.unknown" }],
+        ),
+    ).toThrow();
+    expect(
+      () =>
+        new AgentWorkflowPresetRegistry(
+          [module],
+          [
+            {
+              ...registration,
+              entry: { path: "//attacker.test", label: "入口" },
+            },
+          ],
+        ),
+    ).toThrow();
+  });
+
+  test("每次读取重算授权，匿名和撤权不泄露业务预设", async () => {
+    const { runtime, context } = await fixture();
+    const registry = new AgentWorkflowPresetRegistry([module], [registration]);
+    const items = await registry.list(context, runtime, true);
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      label: "示例工单",
+      availability: "available",
+      entry: { path: "/work-orders" },
+    });
+    context.actor.permissionKeys = [];
+    expect(await registry.list(context, runtime, true)).toHaveLength(0);
+    const anonymous = await runtime.createGuardContext(
+      new Request("http://localhost/api/agent/workflows/presets"),
+    );
+    expect(await registry.list(anonymous, runtime, true)).toHaveLength(0);
+  });
+
+  test("未就绪只投影原因，不启动Workflow或泄露原始错误", async () => {
+    const { runtime, context } = await fixture();
+    const registry = new AgentWorkflowPresetRegistry(
+      [module],
+      [
+        {
+          ...registration,
+          readiness: async () => {
+            throw new Error("provider secret");
+          },
+        },
+      ],
+    );
+    const unavailable = await registry.list(context, runtime, true);
+    expect(unavailable[0]).toMatchObject({
+      availability: "unavailable",
+      safeCode: "WORKFLOW_PRESET_UNAVAILABLE",
+    });
+    expect(JSON.stringify(unavailable)).not.toContain("provider secret");
+    expect((await registry.list(context, runtime, false))[0]).toMatchObject({
+      safeCode: "WORKFLOW_RUNTIME_UNAVAILABLE",
+    });
+  });
+});

package/template/apps/server/src/agent-workflow/preset-registry.ts

@@ -0,0 +1,191 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AgentWorkflowDefinition,
+  AgentWorkflowPresetSummary,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { evaluateRouteGuards } from "../route-guards.js";
+import { validateAgentWorkflowDefinition } from "./definition-validation.js";
+
+export interface AgentWorkflowPresetRegistration {
+  readonly key: string;
+  readonly moduleKey: string;
+  readonly label: string;
+  readonly description: string;
+  readonly definition: AgentWorkflowDefinition;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly entry?: { readonly path: string; readonly label: string };
+  readonly readiness?: (context: RequestGuardContext) => Promise<
+    | { readonly available: true }
+    | {
+        readonly available: false;
+        readonly safeCode: string;
+        readonly reason: string;
+      }
+  >;
+}
+
+type Runtime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "resolveFeature" | "recordDecisions"
+>;
+
+/** 代码注册的只读目录，执行仍走所属业务入口的当前授权与不可变 Release。 */
+export class AgentWorkflowPresetRegistry {
+  private readonly registrations: readonly AgentWorkflowPresetRegistration[];
+
+  constructor(
+    private readonly modules: readonly ModuleManifest[],
+    registrations: readonly AgentWorkflowPresetRegistration[] = [],
+  ) {
+    if (registrations.length > 200)
+      throw new Error("Workflow 预设数量超过上限");
+    const keys = new Set<string>();
+    this.registrations = registrations.map((registration) => {
+      const module = modules.find(
+        ({ name }) => name === registration.moduleKey,
+      );
+      if (
+        !module ||
+        !registration.key.startsWith(`${module.name}.`) ||
+        keys.has(registration.key)
+      ) {
+        throw new Error("Workflow 预设归属无效或 Key 重复");
+      }
+      if (
+        !module.features.some(({ key }) => key === registration.featureKey) ||
+        !module.permissions.some(
+          ({ key }) => key === registration.permissionKey,
+        ) ||
+        !registration.permissionKey.startsWith(`${registration.featureKey}.`)
+      ) {
+        throw new Error("Workflow 预设引用未声明的治理能力");
+      }
+      if (!registration.definition.workflowKey.startsWith(`${module.name}.`))
+        throw new Error("Workflow 预设定义超出模块命名空间");
+      if (
+        registration.entry &&
+        (!safePresetEntry(registration.entry.path) ||
+          !safeText(registration.entry.label, 80))
+      )
+        throw new Error("Workflow 预设业务入口无效");
+      if (
+        !safeText(registration.label, 160) ||
+        !safeText(registration.description, 1000)
+      )
+        throw new Error("Workflow 预设说明无效");
+      keys.add(registration.key);
+      return Object.freeze({
+        ...registration,
+        definition: structuredClone(
+          validateAgentWorkflowDefinition(registration.definition),
+        ),
+        entry: registration.entry
+          ? Object.freeze({ ...registration.entry })
+          : undefined,
+      });
+    });
+  }
+
+  async list(
+    context: RequestGuardContext,
+    runtime: Runtime,
+    runtimeAvailable: boolean,
+  ): Promise<readonly AgentWorkflowPresetSummary[]> {
+    const items: AgentWorkflowPresetSummary[] = [];
+    for (const registration of this.registrations) {
+      const feature = this.modules
+        .find(({ name }) => name === registration.moduleKey)!
+        .features.find(({ key }) => key === registration.featureKey)!;
+      const decision = await evaluateRouteGuards(
+        runtime,
+        context,
+        {
+          feature,
+          permission: {
+            method: "GET",
+            path: "/api/agent/workflows/presets",
+            permissionKey: registration.permissionKey,
+          },
+        },
+        { record: false },
+      );
+      if (!decision.allowed) continue;
+      let readiness: Awaited<
+        ReturnType<NonNullable<AgentWorkflowPresetRegistration["readiness"]>>
+      > = { available: true };
+      if (!runtimeAvailable)
+        readiness = {
+          available: false,
+          safeCode: "WORKFLOW_RUNTIME_UNAVAILABLE",
+          reason: "Workflow 运行时尚未就绪",
+        };
+      else if (registration.readiness) {
+        try {
+          readiness = await registration.readiness(context);
+        } catch {
+          readiness = {
+            available: false,
+            safeCode: "WORKFLOW_PRESET_UNAVAILABLE",
+            reason: "预设所需条件暂不可用",
+          };
+        }
+      }
+      const blocked = !readiness.available;
+      items.push({
+        key: registration.key,
+        moduleKey: registration.moduleKey,
+        label: registration.label,
+        description: registration.description,
+        workflowKey: registration.definition.workflowKey,
+        version: registration.definition.version,
+        budget: structuredClone(registration.definition.budget),
+        nodes: registration.definition.nodes.map(({ id, label, type }) => ({
+          id,
+          label,
+          type,
+        })),
+        availability: blocked ? "unavailable" : "available",
+        ...(!readiness.available
+          ? {
+              safeCode: /^[A-Z][A-Z0-9_]{1,79}$/.test(readiness.safeCode)
+                ? readiness.safeCode
+                : "WORKFLOW_PRESET_UNAVAILABLE",
+              blockedReason: safeText(readiness.reason, 300)
+                ? readiness.reason
+                : "预设所需条件暂不可用",
+            }
+          : {}),
+        ...(registration.entry ? { entry: { ...registration.entry } } : {}),
+      });
+    }
+    return items;
+  }
+}
+
+function safeText(value: string, max: number) {
+  return (
+    Boolean(value.trim()) &&
+    value.length <= max &&
+    ![...value].some(
+      (character) =>
+        character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
+    )
+  );
+}
+
+export function safePresetEntry(path: string): boolean {
+  return (
+    path.startsWith("/") &&
+    !path.startsWith("//") &&
+    path.length <= 1024 &&
+    !path.includes("\\") &&
+    ![...path].some(
+      (character) =>
+        character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127,
+    ) &&
+    !/%(?:2f|5c|0[0-9a-f]|1[0-9a-f]|7f)/i.test(path)
+  );
+}