create-windy 0.8.3 → 0.10.0

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

@@ -1,3 +1,4 @@
+import type { AiRuntimeSwitches } from "@southwind-ai/shared";
 import type { PlatformConfig } from "@southwind-ai/config";
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
 import type { ModuleManifest } from "@southwind-ai/modules";
@@ -24,6 +25,7 @@ import type { AgentWorkflowWorkspacePolicyDefinition } from "../agent-workflow/w
 export interface AgentPlatformRuntimeInput {
   app: RouteApp;
   platformConfig: PlatformConfig;
+  aiRuntimeSwitches?: AiRuntimeSwitches;
   modules: readonly ModuleManifest[];
   hosts: InitializedModuleHosts;
   runtime: ReturnType<typeof createServerRuntime>;

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

@@ -1,38 +1,7 @@
 import { resolveCurrentSystemActor } from "../system/actor.js";
 import type { AgentAdminReadinessRef } from "./admin-catalog-bootstrap.js";
 import { registerAgentAdminCatalogRuntime } from "./admin-catalog-bootstrap.js";
-import { AiArtifactCodec } from "../ai-artifact/codec.js";
-import { registerAiArtifactRoutes } from "../ai-artifact/routes.js";
-import { AiArtifactRuntime } from "../ai-artifact/runtime.js";
-import { DocumentRunFacade } from "../document/facade.js";
-import {
-  RemoteDocumentRuntime,
-  unavailableDocumentRuntime,
-} from "../document/remote-runtime.js";
-import { registerDocumentRunRoutes } from "../document/routes.js";
-import { createDocumentOutputRuntime } from "../document/output-artifact-composition.js";
-import { installDocumentOutputRuntimeRoutes } from "../document/output-artifact-route-composition.js";
-import { createModuleAiOperationReadinessPort } from "../ai-runtime-readiness/operation-port.js";
-import { AiRuntimeReadinessTrustStoreV1 } from "../ai-runtime-readiness/trust-store.js";
-import { EmbeddingFacade } from "../embedding/facade.js";
-import { EmbeddingRunAuthorizations } from "../embedding/run-authorization.js";
-import { InMemoryEmbeddingRunBindingRepository } from "../embedding/run-binding-repository.js";
-import { DrizzleEmbeddingRunBindingRepository } from "../embedding/drizzle-run-binding-repository.js";
-import {
-  RemoteEmbeddingRuntime,
-  unavailableEmbeddingRuntime,
-} from "../embedding/remote-runtime.js";
-import {
-  registerEmbeddingRoutes,
-  registerEmbeddingRunArtifactRoutes,
-} from "../embedding/routes.js";
-import { SpeechRunFacade } from "../speech/facade.js";
-import {
-  RemoteSpeechRuntime,
-  unavailableSpeechRuntime,
-} from "../speech/remote-runtime.js";
-import { registerSpeechRunRoutes } from "../speech/routes.js";
-import { ExecutionGrantStore } from "./execution-grants.js";
+import { composeSharedAiRuntime } from "../media-runtime/shared-composition.js";
 import { RemoteAgentRuntime } from "./remote-runtime.js";
 import { AgentRunFacade } from "./run-facade.js";
 import { registerAgentRunRoutes } from "./run-routes.js";
@@ -41,18 +10,16 @@ import { DrizzleAgentRunBindingRepository } from "./drizzle-run-binding-reposito
 import { AgentRunAuthorizationStore } from "./run-authorization.js";
 import { InMemoryAgentRunBindingRepository } from "./run-binding-repository.js";
 import { AgentBackgroundOperationExecutor } from "./background-operation.js";
-import { createModuleAiPorts } from "./module-ai-port-factory.js";
 import { createManifestAuthorizedRouteApp } from "../module-host/static-route-authorization.js";
 import { disableAgentRuntime } from "./runtime-disabled-composition.js";
 import { createClientAgentSessionRuntime } from "./client-session/bootstrap.js";
 import { attachClientAgentWorkflowArtifactRuntime } from "./client-workflow-artifact/runtime-composition.js";
 import { bindClientAgentHostRevocations } from "./client-session/host-revocation-composition.js";
 import { registerAgentSessions } from "./agent-session-bootstrap.js";
-import { createAiRuntimeReadinessSources } from "./runtime-readiness-sources.js";
 import { registerAiRuntimeReporting } from "./runtime-reporting-bootstrap.js";
 import { registerScreenshotIntakeRoutes } from "./screenshot-intake-routes.js";
 import { createScreenshotIntakeRuntimeV2 } from "./screenshot-intake-bootstrap.js";
-import { requiredEnvironment } from "./required-environment.js";
+import { requiredEnvironment } from "../media-runtime/required-environment.js";
 import { composeAgentLongSessionRuntime } from "./session-runtime-composition.js";
 import { registerAgentWorkbenchRuntime } from "./workbench-bootstrap.js";
 import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
@@ -73,31 +40,59 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     input.app,
     routeAuthorizer,
   );
-  if (!input.platformConfig.enableAI) {
+  if (
+    !input.platformConfig.enableAI ||
+    (input.aiRuntimeSwitches?.agent === false &&
+      input.aiRuntimeSwitches.document === false &&
+      input.aiRuntimeSwitches.speech === false &&
+      input.aiRuntimeSwitches.embedding === false)
+  ) {
     return disableAgentRuntime(input, aiRouteApp, tools);
   }
   const sessionSecret = requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET");
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
-  const businessSessions = registerAgentSessions({
-    ...input,
-    secret: internalToken,
-  });
-  const aiArtifacts = new AiArtifactRuntime(
-    new AiArtifactCodec(sessionSecret),
-    input.hosts,
-    input.runtime,
-    features,
-    input.storage,
-    resolveAgentActor,
-  );
-  registerAiArtifactRoutes(aiRouteApp, aiArtifacts, internalToken);
   const agentServerUrl =
     process.env.AGENT_SERVER_URL || "http://agent-server:8080";
-  const remote = new RemoteAgentRuntime({
-    baseUrl: agentServerUrl,
+  const remote =
+    input.aiRuntimeSwitches?.agent === false
+      ? undefined
+      : new RemoteAgentRuntime({
+          baseUrl: agentServerUrl,
+          internalToken,
+          toolHostUrl: process.env.AGENT_TOOL_HOST_URL || "http://server:9747",
+          compatibilityMode: "prefer-v1",
+        });
+  const sharedAi = composeSharedAiRuntime({
+    app: aiRouteApp,
+    switches: input.aiRuntimeSwitches,
+    modules: input.modules,
+    hosts: input.hosts,
+    runtime: input.runtime,
+    storage: input.storage,
+    db: input.db,
+    features,
+    resolveActor: resolveAgentActor,
+    secret: sessionSecret,
     internalToken,
-    toolHostUrl: process.env.AGENT_TOOL_HOST_URL || "http://server:9747",
-    compatibilityMode: "prefer-v1",
+    agent: remote,
+  });
+  const { aiArtifacts } = sharedAi;
+  catalogReadiness.current = sharedAi.catalogReadiness;
+  if (!remote) {
+    const disabledAgent = disableAgentRuntime(input, aiRouteApp, tools, {
+      mediaAvailable: true,
+    });
+    const moduleAi = sharedAi.modulePorts();
+    return {
+      ...disabledAgent,
+      aiArtifacts,
+      aiOperations: moduleAi.operations,
+      aiReadiness: moduleAi.readiness,
+    };
+  }
+  const businessSessions = registerAgentSessions({
+    ...input,
+    secret: internalToken,
   });
   const clientAgentSessionRuntime = createClientAgentSessionRuntime({
     app: input.app,
@@ -142,7 +137,6 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     agentServerUrl,
     internalToken,
   });
-  const grants = new ExecutionGrantStore();
   const runAuthorizations = new AgentRunAuthorizationStore(
     input.db
       ? new DrizzleAgentRunBindingRepository(input.db)
@@ -165,93 +159,6 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
     ],
     memoryObjects: input.sessionMemoryObjects,
   });
-  const documentRemote = process.env.DOCUMENT_SERVER_URL?.trim()
-    ? new RemoteDocumentRuntime({
-        baseUrl: process.env.DOCUMENT_SERVER_URL,
-        internalToken,
-      })
-    : unavailableDocumentRuntime;
-  const speechRemote = process.env.SPEECH_SERVER_URL?.trim()
-    ? new RemoteSpeechRuntime({
-        baseUrl: process.env.SPEECH_SERVER_URL,
-        internalToken,
-      })
-    : unavailableSpeechRuntime;
-  const embeddingRemote = process.env.EMBEDDING_SERVER_URL?.trim()
-    ? new RemoteEmbeddingRuntime({
-        baseUrl: process.env.EMBEDDING_SERVER_URL,
-        internalToken,
-      })
-    : unavailableEmbeddingRuntime;
-  const readinessSources = createAiRuntimeReadinessSources({
-    agent: remote,
-    document: documentRemote,
-    speech: speechRemote,
-    embedding: embeddingRemote,
-  });
-  const readinessTrustStore = new AiRuntimeReadinessTrustStoreV1();
-  const aiReadiness = createModuleAiOperationReadinessPort({
-    modules: input.modules,
-    sources: readinessSources,
-    trustStore: readinessTrustStore,
-    runtime: input.runtime,
-  });
-  catalogReadiness.current = aiReadiness;
-  const outputRuntime = createDocumentOutputRuntime({
-    modules: input.modules,
-    readiness: aiReadiness,
-    runtime: input.runtime,
-    storage: input.storage,
-    resolveActor: resolveAgentActor,
-    db: input.db,
-  });
-  const documentFacadeWithOutput = new DocumentRunFacade(
-    input.modules,
-    input.hosts,
-    input.runtime,
-    documentRemote,
-    aiArtifacts,
-    grants,
-    outputRuntime?.host,
-    aiReadiness,
-  );
-  installDocumentOutputRuntimeRoutes(outputRuntime, aiRouteApp, internalToken);
-  registerDocumentRunRoutes(
-    aiRouteApp,
-    documentFacadeWithOutput,
-    documentRemote,
-  );
-  const speechFacade = new SpeechRunFacade(
-    input.modules,
-    input.hosts,
-    input.runtime,
-    speechRemote,
-    aiArtifacts,
-    grants,
-    aiReadiness,
-    outputRuntime?.speechHost,
-  );
-  registerSpeechRunRoutes(aiRouteApp, speechFacade, speechRemote);
-  const embeddingFacade = new EmbeddingFacade(
-    input.modules,
-    input.hosts,
-    input.runtime,
-    embeddingRemote,
-    aiArtifacts,
-    new EmbeddingRunAuthorizations(
-      input.db
-        ? new DrizzleEmbeddingRunBindingRepository(input.db)
-        : new InMemoryEmbeddingRunBindingRepository(),
-      internalToken,
-    ),
-    aiReadiness,
-  );
-  registerEmbeddingRoutes(aiRouteApp, embeddingFacade);
-  registerEmbeddingRunArtifactRoutes(
-    aiRouteApp,
-    embeddingFacade,
-    internalToken,
-  );
   const agentFacade = new AgentRunFacade(
     input.modules,
     input.hosts,
@@ -314,22 +221,7 @@ export function registerAgentPlatformRuntime(input: AgentPlatformRuntimeInput) {
       remote,
     ),
   );
-  const moduleAi = createModuleAiPorts({
-    modules: input.modules,
-    runtime: input.runtime,
-    sources: readinessSources,
-    trustStore: readinessTrustStore,
-    operations: {
-      agentFacade,
-      agentRemote: remote,
-      documentFacade: documentFacadeWithOutput,
-      documentRemote,
-      speechFacade,
-      speechRemote,
-      embeddingFacade,
-      modules: input.modules,
-    },
-  });
+  const moduleAi = sharedAi.modulePorts({ agentFacade, agentRemote: remote });
   return {
     toolHandlers,
     aiArtifacts,

package/template/apps/server/src/agent/runtime-disabled-composition.ts

@@ -9,10 +9,11 @@ export function disableAgentRuntime(
   input: AgentPlatformRuntimeInput,
   app: RouteApp,
   tools: ReturnType<typeof composeAgentToolRuntime>,
+  options?: { mediaAvailable: boolean },
 ) {
   registerAgentWorkbenchRuntime(input, app);
   registerProductionAgentWorkflowRuntime(input, app, tools.toolRegistry);
-  registerUnavailableAiRoutes(app);
+  registerUnavailableAiRoutes(app, options);
   return {
     toolHandlers: tools.toolHandlers,
     aiArtifacts: undefined,

package/template/apps/server/src/agent/runtime-tool-composition.ts

@@ -1,3 +1,4 @@
+import { bindAgentGovernanceTools } from "./governance-runtime.js";
 import { createModuleToolHandlerMap } from "../module-host.js";
 import { PlatformMcpAdapter } from "../mcp/adapter.js";
 import { registerMcpRoutes } from "../mcp/routes.js";
@@ -25,6 +26,7 @@ export function composeAgentToolRuntime(input: AgentPlatformRuntimeInput) {
     toolHandlers,
     input.runtime,
   );
+  bindAgentGovernanceTools(input.runtime, toolRegistry);
   const routeAuthorizer = createStaticRouteAuthorizer(
     input.runtime,
     input.modules,

package/template/apps/server/src/agent/session-invalidation/authorization-revocation.ts

@@ -0,0 +1,54 @@
+import { agentSourceInvalidations } from "@southwind-ai/database";
+import { and, desc, eq } from "drizzle-orm";
+import type { AgentAuthorizationInvalidationInput } from "../../system/authorization-invalidation-bridge.js";
+import type { ModuleAuthoritativeSourceAccessRegistry } from "../context-memory/authoritative-source-registry.js";
+import type { DrizzleSessionInvalidationOutbox } from "../session-persistence/drizzle-invalidation-outbox.js";
+import { authorizationCoordinateForActor } from "../session-projection-access.js";
+
+export async function invalidateActorAuthorization(
+  input: AgentAuthorizationInvalidationInput,
+  sources: ModuleAuthoritativeSourceAccessRegistry,
+  outbox: DrizzleSessionInvalidationOutbox,
+) {
+  const authorization = authorizationCoordinateForActor(input.previousActor);
+  const sourceKind = "authorization-scope";
+  const [latest] = await input.database
+    .select({ sequence: agentSourceInvalidations.sequence })
+    .from(agentSourceInvalidations)
+    .where(
+      and(
+        eq(agentSourceInvalidations.sourceModuleKey, "system.agent"),
+        eq(agentSourceInvalidations.sourceKind, sourceKind),
+        eq(agentSourceInvalidations.sourceId, authorization.actorId),
+      ),
+    )
+    .orderBy(desc(agentSourceInvalidations.sequence))
+    .limit(1);
+  const occurredAt = Date.parse(input.occurredAt);
+  if (!Number.isSafeInteger(occurredAt) || occurredAt < 1) {
+    throw new Error("Agent 授权失效时间坐标无效");
+  }
+  const sequence = Math.max(occurredAt, (latest?.sequence ?? 0) + 1);
+  const producer = sources.bindInvalidationProducer({
+    moduleKey: "system.agent",
+    authorization,
+    append: {
+      append: (envelope) =>
+        outbox.appendInTransaction(input.database, envelope),
+    },
+  });
+  const result = await producer.authorizationRevoked({
+    source: {
+      sourceKind,
+      sourceId: authorization.actorId,
+      version: authorization.scopeDigest,
+      sequence,
+    },
+    event: {
+      eventId: input.eventId,
+      eventSequence: sequence,
+      occurredAt: input.occurredAt,
+    },
+  });
+  if (result === "stale") throw new Error("Agent 授权失效序列未收敛");
+}

package/template/apps/server/src/agent/session-runtime-composition.ts

@@ -1,6 +1,5 @@
+import { invalidateActorAuthorization } from "./session-invalidation/authorization-revocation.js";
 import type { ModuleManifest } from "@southwind-ai/modules";
-import { agentSourceInvalidations } from "@southwind-ai/database";
-import { and, desc, eq } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { RequestActor } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
@@ -30,7 +29,6 @@ import type { AgentRunAuthorizationStore } from "./run-authorization.js";
 import { AgentRunSessionBindingAuthorizer } from "./run-session-authorization.js";
 import { DrizzleSessionAuthoritativeSourceAccess } from "./session-context-source.js";
 import {
-  authorizationCoordinateForActor,
   ResolvingCurrentSourceAuthorizationPort,
   SessionProjectionSourceAuthorizer,
 } from "./session-projection-access.js";
@@ -215,51 +213,3 @@ export function composeAgentLongSessionRuntime(input: {
     },
   };
 }
-
-async function invalidateActorAuthorization(
-  input: AgentAuthorizationInvalidationInput,
-  sources: ModuleAuthoritativeSourceAccessRegistry,
-  outbox: DrizzleSessionInvalidationOutbox,
-) {
-  const authorization = authorizationCoordinateForActor(input.previousActor);
-  const sourceKind = "authorization-scope";
-  const [latest] = await input.database
-    .select({ sequence: agentSourceInvalidations.sequence })
-    .from(agentSourceInvalidations)
-    .where(
-      and(
-        eq(agentSourceInvalidations.sourceModuleKey, "system.agent"),
-        eq(agentSourceInvalidations.sourceKind, sourceKind),
-        eq(agentSourceInvalidations.sourceId, authorization.actorId),
-      ),
-    )
-    .orderBy(desc(agentSourceInvalidations.sequence))
-    .limit(1);
-  const occurredAt = Date.parse(input.occurredAt);
-  if (!Number.isSafeInteger(occurredAt) || occurredAt < 1) {
-    throw new Error("Agent 授权失效时间坐标无效");
-  }
-  const sequence = Math.max(occurredAt, (latest?.sequence ?? 0) + 1);
-  const producer = sources.bindInvalidationProducer({
-    moduleKey: "system.agent",
-    authorization,
-    append: {
-      append: (envelope) =>
-        outbox.appendInTransaction(input.database, envelope),
-    },
-  });
-  const result = await producer.authorizationRevoked({
-    source: {
-      sourceKind,
-      sourceId: authorization.actorId,
-      version: authorization.scopeDigest,
-      sequence,
-    },
-    event: {
-      eventId: input.eventId,
-      eventSequence: sequence,
-      occurredAt: input.occurredAt,
-    },
-  });
-  if (result === "stale") throw new Error("Agent 授权失效序列未收敛");
-}

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

@@ -63,8 +63,19 @@ const unavailableRoutes = [
   ["GET", "/system/ai-runtime/actors"],
 ] as const;
 
-export function registerUnavailableAiRoutes(app: RouteApp): void {
-  registerUnavailableRoutes(app, unavailableRoutes, "AI Runtime 未启用");
+export function registerUnavailableAiRoutes(
+  app: RouteApp,
+  options?: { mediaAvailable: boolean },
+): void {
+  const routes = options?.mediaAvailable
+    ? unavailableRoutes.filter(
+        ([, path]) =>
+          path.startsWith("/agent/") ||
+          path.startsWith("/internal/agent/") ||
+          path.startsWith("/system/ai-runtime/"),
+      )
+    : unavailableRoutes;
+  registerUnavailableRoutes(app, routes, "AI Runtime 未启用");
   registerUnavailableRoutes(
     app,
     longSessionUnavailableRoutes,

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

@@ -1,3 +1,6 @@
+import { AgentWorkflowPresetRegistry } from "../agent-workflow/preset-registry.js";
+import { registerAgentWorkflowPresetRoutes } from "../agent-workflow/preset-routes.js";
+import { projectAgentWorkflowPresets } from "../app/agent-workflow-presets.js";
 import type { RouteApp } from "../system/routes.js";
 import { composeProductionAgentWorkflowRuntime } from "../agent-workflow/runtime-composition.js";
 import { registerAgentWorkflowRoutes } from "../agent-workflow/routes.js";
@@ -57,5 +60,11 @@ export function registerProductionAgentWorkflowRuntime(
       : {}),
   });
   registerAgentWorkflowRoutes(app, runtime);
+  registerAgentWorkflowPresetRoutes(
+    app,
+    new AgentWorkflowPresetRegistry(input.modules, projectAgentWorkflowPresets),
+    input.runtime,
+    () => !!runtime,
+  );
   return runtime;
 }

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

@@ -0,0 +1,88 @@
+import type {
+  AgentSkillRequirement,
+  AgentSkillVersion,
+} from "@southwind-ai/shared";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { AgentSkillError } from "./contracts.js";
+export function skillActor(context: RequestGuardContext) {
+  const scope = context.actor.scopeContext;
+  if (
+    context.actor.type !== "user" ||
+    !isServerScopeContext(scope) ||
+    scope.actorId !== context.actor.id ||
+    (context.actor.credentialState !== undefined &&
+      context.actor.credentialState !== "active")
+  )
+    throw new AgentSkillError(
+      "SKILL_FORBIDDEN",
+      "当前身份缺少技能治理范围",
+      403,
+    );
+  return {
+    actorId: context.actor.id,
+    tenantId: scope.tenantId,
+    departmentId: scope.departmentId,
+    tenantWide: scope.grants.some(
+      (grant) => grant.scope === "all" || grant.scope === "tenant",
+    ),
+  };
+}
+export function skillReadable(
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  const actor = skillActor(context);
+  return (
+    skill.tenantId === actor.tenantId &&
+    (skill.ownerActorId === actor.actorId ||
+      skill.scope === "tenant" ||
+      (skill.scope === "department" &&
+        !!actor.departmentId &&
+        skill.departmentId === actor.departmentId))
+  );
+}
+export function skillGovernable(
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  const actor = skillActor(context);
+  return (
+    skill.tenantId === actor.tenantId &&
+    (skill.ownerActorId === actor.actorId ||
+      (skill.scope !== "personal" && actor.tenantWide))
+  );
+}
+export interface AgentSkillAccess {
+  authorize(
+    context: RequestGuardContext,
+    action: "read" | "manage" | "execute",
+  ): Promise<boolean>;
+  requirement(
+    context: RequestGuardContext,
+    requirement: AgentSkillRequirement,
+  ): Promise<boolean>;
+}
+export async function requireSkillAccess(
+  access: AgentSkillAccess,
+  context: RequestGuardContext,
+  action: "read" | "manage" | "execute",
+) {
+  skillActor(context);
+  if (!(await access.authorize(context, action)))
+    throw new AgentSkillError(
+      "SKILL_FORBIDDEN",
+      "当前身份不能执行此技能操作",
+      403,
+    );
+}
+
+export async function skillRequirementsAvailable(
+  access: AgentSkillAccess,
+  skill: AgentSkillVersion,
+  context: RequestGuardContext,
+) {
+  for (const requirement of skill.requirements)
+    if (!(await access.requirement(context, requirement))) return false;
+  return true;
+}

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

@@ -0,0 +1,49 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { createServerRuntime } from "../runtime.js";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import { AgentSkillService } from "./service.js";
+import { DrizzleAgentSkillRepository } from "./drizzle-repository.js";
+import { InMemoryAgentSkillRepository } from "./repository.js";
+export { registerAgentSkillRoutes } from "./routes.js";
+export function bootstrapAgentSkills(input: {
+  db?: NodePgDatabase;
+  runtime: ReturnType<typeof createServerRuntime>;
+  modules: readonly ModuleManifest[];
+  tools?: GovernedToolRegistry | (() => GovernedToolRegistry | undefined);
+}) {
+  const feature = input.modules
+    .flatMap((module) => module.features)
+    .find((value) => value.key === "system.agent-skill");
+  return new AgentSkillService(
+    input.db
+      ? new DrizzleAgentSkillRepository(input.db)
+      : new InMemoryAgentSkillRepository(),
+    {
+      async authorize(context, action) {
+        if (!feature) return false;
+        return (
+          await evaluateAccessGuards(input.runtime, context, {
+            feature,
+            permission: { permissionKey: `system.agent-skill.${action}` },
+          })
+        ).decision.allowed;
+      },
+      async requirement(context, requirement) {
+        const tools =
+          typeof input.tools === "function" ? input.tools() : input.tools;
+        const definition = tools?.definition(requirement.toolKey);
+        if (
+          !definition ||
+          definition.featureKey !== requirement.featureKey ||
+          definition.permissionKey !== requirement.permissionKey
+        )
+          return false;
+        return (await tools!.availability(requirement.toolKey, context))
+          .allowed;
+      },
+    },
+    (event) => input.runtime.auditSink.recordCriticalEvent(event),
+  );
+}

package/template/apps/server/src/agent-skills/builtin-registration.ts

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import type {
+  AgentSkillRequirement,
+  AgentSkillVersion,
+  AuditEvent,
+} from "@southwind-ai/shared";
+import type { AgentSkillRepository } from "./contracts.js";
+import { parseSkillBundle, hashSkillValue } from "./bundle.js";
+export interface BuiltinAgentSkill {
+  readonly markdown: string;
+  readonly source: string;
+  readonly requirements?: readonly AgentSkillRequirement[];
+}
+export async function registerBuiltinSkillBundles(
+  skills: readonly BuiltinAgentSkill[],
+  input: {
+    readonly tenantId: string;
+    readonly repository: AgentSkillRepository;
+    readonly audit: (event: AuditEvent) => Promise<void>;
+  },
+) {
+  if (!input.tenantId || input.tenantId.length > 64)
+    throw new Error("Builtin skill tenant is required");
+  const tenantId = input.tenantId;
+  for (const definition of skills) {
+    const bundle = parseSkillBundle({
+      format: "markdown",
+      content: definition.markdown,
+    });
+    const existing = await input.repository.versions(tenantId, bundle.name);
+    if (
+      existing.some((record) => record.auditCommitted) ||
+      (existing.length && existing[0]?.metadata.origin !== "builtin")
+    )
+      continue;
+    const metadata: AgentSkillVersion = {
+      key: bundle.name,
+      version: 1,
+      tenantId,
+      ownerActorId: "windy-platform",
+      scope: "tenant",
+      origin: "builtin",
+      status: "published",
+      name: bundle.displayName,
+      description: bundle.description,
+      digest: bundle.digest,
+      requirements: definition.requirements ?? [],
+      safetyConstraints: [],
+      createdAt: new Date().toISOString(),
+      createdBy: "windy-platform",
+      source: definition.source,
+    };
+    const receipt = await input.repository.mutate(
+      {
+        tenantId,
+        actorId: "windy-platform",
+        idempotencyKey: `builtin:${bundle.name}`,
+        requestDigest: hashSkillValue([bundle.digest, definition]),
+        key: bundle.name,
+        expectedVersion: 0,
+      },
+      async () => ({
+        record: { metadata, bundle, auditCommitted: false },
+        audit: {
+          id: randomUUID(),
+          action: "agent.skill.publish",
+          actor: {
+            id: "windy-platform",
+            type: "service",
+            name: "Windy 技能初始化",
+            roleCodes: [],
+          },
+          outcome: "success",
+          target: { type: "agent-skill", id: bundle.name },
+          occurredAt: metadata.createdAt,
+          metadata: { version: 1, digest: bundle.digest },
+        },
+      }),
+    );
+    await input.audit(receipt.audit);
+    await input.repository.acknowledge(receipt);
+  }
+}