create-windy 0.8.3 → 0.9.1

package/template/apps/server/scripts/check-dsh-platform-example.ts

@@ -0,0 +1,251 @@
+/** Synthetic acceptance: actual platform query Tool + official DSH Loop; no customer data or live model. */
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import {
+  createFoundationSnapshot,
+  loadSystemModules,
+} from "../src/foundation.ts";
+import { createServerRuntime } from "../src/runtime.ts";
+import { createSystemRepositories } from "../src/system/seed.ts";
+import { createSystemToolHandlers } from "../src/agent/routes.ts";
+import { GovernedToolRegistry } from "../src/agent/tool-registry.ts";
+import { RemoteAgentRuntime } from "../src/agent/remote-runtime.ts";
+import { toolDefinitions } from "../src/agent/run-definition-support.ts";
+import { platformBuiltinAgentSkills } from "../src/agent-skills/builtins.ts";
+
+const root = resolve(import.meta.dir, "../../..");
+const modules = loadSystemModules();
+const runtime = createServerRuntime(
+  { WINDY_DEV_ADMIN_TOKEN: "synthetic-example" },
+  { featureCatalog: modules.flatMap((module) => module.features) },
+);
+const context = await runtime.createGuardContext(
+  new Request("http://fixture/api/agent/runs", {
+    headers: { authorization: "Bearer synthetic-example" },
+  }),
+);
+const repositories = createSystemRepositories(
+  createFoundationSnapshot(undefined, modules),
+);
+const registry = new GovernedToolRegistry(
+  modules,
+  createSystemToolHandlers(repositories, runtime),
+  runtime,
+);
+const token = crypto.randomUUID() + crypto.randomUUID();
+let modelCalls = 0,
+  toolCalls = 0,
+  userCount = -1;
+const host = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 0,
+  async fetch(request) {
+    const path = new URL(request.url).pathname;
+    if (path === "/api/internal/agent/tools/execute") {
+      assert.equal(request.headers.get("authorization"), `Bearer ${token}`);
+      const body = (await request.json()) as {
+        executionGrant: string;
+        toolKey: string;
+        arguments: Record<string, unknown>;
+      };
+      assert.equal(body.executionGrant, "synthetic-grant");
+      assert.equal(body.toolKey, "system.users.list");
+      const value = await registry.execute(
+        body.toolKey,
+        body.arguments,
+        context,
+      );
+      userCount = (value as { total: number }).total;
+      toolCalls++;
+      return Response.json({ value });
+    }
+    if (path !== "/v1/chat/completions")
+      return new Response(null, { status: 404 });
+    const body = (await request.json()) as {
+      messages: { role: string; content: unknown }[];
+      tools: { function: { name: string } }[];
+    };
+    modelCalls++;
+    assert(
+      JSON.stringify(body.messages).includes("平台工具查询") ||
+        JSON.stringify(body.messages).includes("当前会话实际可见的工具目录"),
+    );
+    const done = body.messages.at(-1)?.role === "tool";
+    const delta = done
+      ? {
+          content: JSON.stringify({
+            answer: `当前授权平台用户共${userCount}名`,
+          }),
+        }
+      : {
+          tool_calls: [
+            {
+              index: 0,
+              id: "synthetic-call",
+              type: "function",
+              function: {
+                name: body.tools[0]!.function.name,
+                arguments: '{"page":1,"pageSize":10}',
+              },
+            },
+          ],
+        };
+    return new Response(
+      `data: ${JSON.stringify({ choices: [{ delta, finish_reason: done ? "stop" : "tool_calls" }] })}\n\ndata: ${JSON.stringify({ choices: [], usage: { prompt_tokens: 100, completion_tokens: 10 } })}\n\ndata: [DONE]\n\n`,
+      { headers: { "content-type": "text/event-stream" } },
+    );
+  },
+});
+const outputRoot =
+  process.env.WINDY_DSH_EXAMPLE_OUTPUT ||
+  resolve(root, ".artifacts/dsh-platform-example");
+await mkdir(outputRoot, { recursive: true });
+const out = resolve(root, "apps/agent-server/.tmp/platform-example");
+await mkdir(out, { recursive: true });
+const entry = resolve(out, "entry.ts");
+await writeFile(
+  entry,
+  `import {startAgentServer} from ${JSON.stringify(resolve(root, "apps/agent-server/main.ts"))}; const a=await startAgentServer(0); console.log(JSON.stringify({port:a.server.address().port})); process.on("SIGTERM",()=>void a.close().then(()=>process.exit(0)));`,
+);
+const built = await Bun.build({
+  entrypoints: [entry],
+  target: "node",
+  outdir: out,
+  external: ["@deepseek-ai/*", "ajv", "zod", "sharp", "ws"],
+});
+assert(built.success, built.logs.map(String).join("\n"));
+const child = Bun.spawn(["node", resolve(out, "entry.js")], {
+  cwd: resolve(root, "apps/agent-server"),
+  env: {
+    ...process.env,
+    AGENT_SERVER_INTERNAL_TOKEN: token,
+    AGENT_RUNTIME_DATABASE_PATH: ":memory:",
+    QWEN_API_URL: `${host.url.origin}/v1`,
+    QWEN_MODEL: "synthetic-model",
+    AI_TOOL_HOST_URL: host.url.origin,
+    AI_PROVIDER_MAX_CONCURRENT_RUNS: "1",
+    AI_PROVIDER_MAX_QUEUE_DEPTH: "0",
+    AGENT_DSH_HOME: resolve(out, "unused-native-home"),
+  },
+  stdout: "pipe",
+  stderr: "inherit",
+});
+try {
+  const reader = child.stdout.getReader();
+  let ready = "";
+  while (!ready.includes("\n")) {
+    const chunk = await reader.read();
+    assert(!chunk.done, "agent startup failed");
+    ready += new TextDecoder().decode(chunk.value);
+  }
+  const port = JSON.parse(ready.split("\n")[0]!).port as number;
+  const remote = new RemoteAgentRuntime({
+    baseUrl: `http://127.0.0.1:${port}`,
+    internalToken: token,
+    toolHostUrl: host.url.origin,
+    compatibilityMode: "require-v1",
+  });
+  const fields = [
+    "instructions",
+    "user-prompt",
+    "tool-definitions",
+    "output-schema",
+    "provider-output",
+    "tool-results",
+  ] as const;
+  const created = await remote.start(
+    {
+      kind: "agent",
+      operationKey: "system.agent.example",
+      input: {},
+      instructions: platformBuiltinAgentSkills[0]!.markdown,
+      userPrompt: "按当前权限查询平台用户数，并形成可核验汇总",
+      inputModalities: ["text"],
+      requiredCapabilities: ["text-generation"],
+      artifacts: [],
+      outputSchemaKey: "system.agent.example.v1",
+      outputSchema: {
+        type: "object",
+        properties: { answer: { type: "string" } },
+        required: ["answer"],
+        additionalProperties: false,
+      },
+      allowedTools: toolDefinitions(modules, ["system.users.list"]),
+      limits: {
+        maxDurationSeconds: 30,
+        maxInputBytes: 65536,
+        maxOutputBytes: 65536,
+      },
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      providerDataPolicy: {
+        inputFields: [],
+        envelopeFields: fields.map((field) => ({
+          field,
+          classification: "internal",
+          dlpAction: "reject",
+        })),
+      },
+      toolNetworkPolicy: { mode: "forbidden" },
+      executionGrant: "synthetic-grant",
+      release: {
+        releaseId: "synthetic-release",
+        operationVersion: "1",
+        workflowVersion: "1",
+        promptVersion: "1",
+        routeVersion: "1",
+        outputSchemaVersion: "1",
+        toolSchemaVersion: "1",
+        manifestDigest: "1",
+      },
+      traceId: "synthetic-trace",
+      reporting: { actorId: context.actor.id, actorType: "user" },
+    },
+    "synthetic-platform-example",
+  );
+  const events = await remote.events(
+    created.runId,
+    0,
+    AbortSignal.timeout(45000),
+  );
+  const stream = await events.text();
+  assert.match(stream, /event: run.completed/);
+  assert.match(stream, /event: tool.completed/);
+  const response = await remote.result(created.runId);
+  const result = (await response.json()) as { output: { answer: string } };
+  assert.equal(result.output.answer, `当前授权平台用户共${userCount}名`);
+  assert.equal(toolCalls, 1);
+  assert.equal(modelCalls, 2);
+  assert(userCount > 0);
+  const evidence = {
+    synthetic: true,
+    skill: "windy-tool-query",
+    tool: "system.users.list",
+    modelCalls,
+    toolCalls,
+    userCount,
+    answer: result.output.answer,
+    checks: [
+      "actual-platform-tool-registry",
+      "manifest-schema-forwarding",
+      "official-dsh-loop",
+      "canonical-sse",
+      "typed-output",
+      "provider-synthetic",
+    ],
+  };
+  await writeFile(
+    resolve(outputRoot, "platform-example.json"),
+    JSON.stringify(evidence, null, 2),
+  );
+  console.log(JSON.stringify(evidence));
+  reader.releaseLock();
+} finally {
+  child.kill("SIGTERM");
+  await child.exited;
+  host.stop(true);
+  await rm(out, { recursive: true, force: true });
+}

package/template/apps/server/src/agent/dsh-runtime-wire.test.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "bun:test";
+import { loadSystemModules } from "../foundation.js";
+import { toolDefinitions } from "./run-definition-support.js";
+import { parseRemoteStatus } from "./remote-runtime-response.js";
+
+test("Operation将Manifest工具输入Schema传到DSH，缺失Schema时拒绝装配", () => {
+  const modules = loadSystemModules();
+  const [tool] = toolDefinitions(modules, ["system.users.list"]);
+  expect(tool?.inputSchema).toMatchObject({ type: "object" });
+  const missing = modules.map((module) => ({ ...module, jsonSchemas: [] }));
+  expect(() => toolDefinitions(missing, ["system.users.list"])).toThrow(
+    "输入 Schema",
+  );
+});
+
+test("Node运行中状态的null终态不会被误解析为已完成，终态仍必须匹配事件", () => {
+  expect(
+    parseRemoteStatus({
+      runId: "run_synthetic",
+      status: "running",
+      lastSequence: 1,
+      terminalEvent: null,
+    }),
+  ).toEqual({ runId: "run_synthetic", status: "running", lastSequence: 1 });
+  expect(() =>
+    parseRemoteStatus({
+      runId: "run_synthetic",
+      status: "completed",
+      lastSequence: 1,
+      terminalEvent: null,
+    }),
+  ).toThrow();
+});

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

@@ -0,0 +1,41 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { bootstrapAgentSkills } from "../agent-skills/bootstrap.js";
+import { platformBuiltinAgentSkills } from "../agent-skills/builtins.js";
+import type { AgentSkillService } from "../agent-skills/service.js";
+import type { GovernedToolRegistry } from "./tool-registry.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type Runtime = ReturnType<typeof createServerRuntime>;
+interface Governance {
+  readonly skills: AgentSkillService;
+  tools?: GovernedToolRegistry;
+}
+// Runtime-scoped ownership lets asynchronous platform startup precede Tool Host binding.
+const runtimes = new WeakMap<Runtime, Governance>();
+export async function prepareAgentGovernance(input: {
+  runtime: Runtime;
+  modules: readonly ModuleManifest[];
+  db?: NodePgDatabase;
+}) {
+  const previous = runtimes.get(input.runtime);
+  if (previous) return previous;
+  const governance: Governance = {
+    skills: bootstrapAgentSkills({
+      ...input,
+      tools: () => governance.tools,
+    }),
+  };
+  await governance.skills.registerBuiltins(platformBuiltinAgentSkills, {
+    tenantId: "single-tenant",
+  });
+  runtimes.set(input.runtime, governance);
+  return governance;
+}
+export function bindAgentGovernanceTools(
+  runtime: Runtime,
+  tools: GovernedToolRegistry,
+) {
+  const governance = runtimes.get(runtime);
+  if (governance) governance.tools = tools;
+}

package/template/apps/server/src/agent/remote-runtime-response.ts

@@ -36,7 +36,7 @@ export function parseRemoteStatus(value: unknown): AgentRuntimeStatusResponse {
     throw new Error("Agent Runtime 状态字段无效");
   }
   const terminalEvent =
-    value.terminalEvent === undefined
+    value.terminalEvent === undefined || value.terminalEvent === null
       ? undefined
       : parseTerminalEvent(value.terminalEvent, runId);
   const terminalStatus = ["completed", "failed", "cancelled"].includes(status);

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

@@ -24,6 +24,7 @@ export interface AgentRuntimeOperation {
     key: string;
     label: string;
     description: string;
+    inputSchema?: ModuleAiJsonValue;
     approval: "none" | "required";
     idempotency: "none" | "supported" | "required";
     approvalTimeoutSeconds?: number;

package/template/apps/server/src/agent/run-definition-support.ts

@@ -10,10 +10,19 @@ export function toolDefinitions(
   const tools = new Map(
     modules.flatMap(({ tools }) => tools.map((tool) => [tool.key, tool])),
   );
+  const schemas = new Map(
+    modules.flatMap(({ jsonSchemas }) =>
+      (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+    ),
+  );
   return allowedKeys.map((key) => {
     const tool = tools.get(key);
     if (!tool) throw new Error(`AI Operation 引用了未知 Tool：${key}`);
+    const inputSchema = schemas.get(tool.inputSchemaKey);
+    if (!inputSchema)
+      throw new Error(`AI Operation Tool 缺少输入 Schema：${key}`);
     return {
+      inputSchema,
       key: tool.key,
       label: tool.label,
       description: tool.description,

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/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);
+  }
+}

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

@@ -0,0 +1,19 @@
+import type { BuiltinAgentSkill } from "./service.js";
+export const platformBuiltinAgentSkills: readonly BuiltinAgentSkill[] = [
+  {
+    source: "windy-platform/builtin/windy-tool-query@1",
+    markdown: `---
+name: windy-tool-query
+description: 在当前身份授权范围内发现工具、只读查询并解释来源。
+metadata:
+  displayName: 平台工具查询
+---
+
+先读取当前会话实际可见的工具目录，使用与问题相关的简短关键词发现工具。
+仅调用当前身份已授权的只读查询工具，按真实参数 Schema 提交有界条件与分页。
+不得猜测工具名、身份、权限或内部地址；没有工具或权限时明确说明缺口。
+结果区分原始来源、计算结果与待核实推断，不将总结自动当作正式业务事实。
+用户要求修改时，解释需要的正式业务入口和审批；本技能不授予写入权限。
+`,
+  },
+];