create-windy 0.2.20 → 0.2.22

package/template/docs/platform/agent-runtime.md

@@ -0,0 +1,128 @@
+# Agent Runtime 接入与运行
+
+更新时间：2026-07-25。
+
+Windy 的 Agent Runtime 是可选平台能力。业务模块声明稳定的 AI Operation 和允许调用的
+Tool；Southwind AI Server 负责身份、Feature、Permission、License、Scope、Execution
+Grant 与审计；独立 Agent Server 只负责模型循环、canonical event 和受限 Tool Host
+回调。业务模块不选择 Provider、模型、Endpoint 或凭据。
+
+## 当前可用边界
+
+- OpenAI-compatible `/chat/completions` Provider，支持流式文本和 function calling。
+- `QWEN_API_KEY` 使用服务端 `SecretRef`，只在 Provider Adapter 发请求前解析。
+- 公网 Endpoint 必须为 HTTPS；`localhost`、容器服务名、RFC 1918 地址和
+  `.internal`/`.local` 主机可使用 HTTP。URL 禁止内嵌凭据、query、fragment 和云
+  metadata 地址。
+- Provider 有连接/请求超时、响应大小上限、安全错误映射和 `/models` readiness 检查。
+- Run 支持幂等创建、canonical SSE、cursor/`Last-Event-ID` 重放、取消和唯一终态。
+- SQLite Store 为单副本有界持久化：默认最多 10,000 个 Run、每个 Run 2,000 个事件、
+  16 MiB 输出、终态保留 7 天。它不保存原始输入，只保存请求指纹；进程重启会把未完成
+  Run 收敛为一个可重试失败终态。
+
+SQLite 模式不能作为多副本共享 Store。需要水平扩容时，必须先提供实现同一 `RunStore`
+契约的外部持久化 Adapter。
+
+## Module 接入
+
+Manifest 的 `aiOperations` 是声明事实。每个 Operation 必须声明自己的 Feature、
+Permission、可选 Entitlement、输入/输出 schema 和 `allowedToolKeys`。模型只会收到该
+集合内的 Tool 定义。
+
+模块在 `setup(host)` 中注册模型无关的输入准备器：
+
+```ts
+host.registerAiOperationHandlers([
+  {
+    operationKey: "example.summary.generate",
+    prepare(input, context) {
+      return {
+        instructions: "只根据用户提供的数据生成简洁摘要。",
+        userPrompt: JSON.stringify({
+          input,
+          actorId: context.actor.id,
+        }),
+      };
+    },
+  },
+]);
+```
+
+不要把 Permission、Feature、License、Scope、Execution Grant、Provider 或 API Key
+放进返回值。`prepare` 只负责把已经过宿主 Guard 的类型化输入转成指令和用户消息。
+
+Tool handler 仍通过 `registerToolHandlers` 注册。模型提出 Tool Call 后，Agent Server
+携带短时 opaque grant 回调 Southwind AI Server；受限 Tool Host 会验证：
+
+1. grant 是否绑定当前 Run、Operation、Actor 且未过期；
+2. Tool 是否属于 Operation 的 `allowedToolKeys`；
+3. Operation 与 Tool 当前的 Feature、Permission 和 License；
+4. 宿主创建的 Actor 与请求 Scope。
+
+Tool 请求不能携带权限列表、License、Scope 或“已授权”标志。客户端或模型提供的这些
+字段会被拒绝，未知 Tool 也不会形成注册表探测通道。
+
+## 本地 Compose profile
+
+选择 `system.agent` 的 create-windy 项目会生成 `agent` profile 和随机内部 Token。
+在 `.env` 中填写：
+
+```dotenv
+PLATFORM_ENABLE_AI=true
+AGENT_SERVER_INTERNAL_TOKEN=<至少 12 字符的随机值>
+QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
+QWEN_API_KEY=<服务端密钥>
+QWEN_MODEL=qwen-plus
+
+# 可选安全上限
+# AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
+# AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
+# AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
+```
+
+然后启动：
+
+```bash
+bun run dev:agent
+```
+
+`QWEN_*` 只注入 `agent-server` 容器；Web service 没有这些环境变量。不要增加 `VITE_`
+前缀，也不要把 `.env`、日志、错误响应或截图中的真实 Key 提交到仓库。
+
+健康检查：
+
+```text
+GET http://agent-server:8080/health/live
+GET http://agent-server:8080/health/ready
+```
+
+`ready` 会访问 Provider 的 `/models`。失败只返回稳定错误，不回显 Provider body、
+Authorization、Secret、Endpoint query 或底层异常文本。
+
+## 客户端协议
+
+浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Southwind AI Server：
+
+```text
+POST /api/agent/runs
+GET  /api/agent/runs/:runId/events
+GET  /api/agent/runs/:runId/result
+POST /api/agent/runs/:runId/cancel
+```
+
+SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，以及唯一一个
+`run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
+cursor 恢复；不要重新创建 Run 或重复执行 Tool。
+
+## 从 create-windy 0.2.21 升级
+
+先检查计划，再应用连续 recipe：
+
+```bash
+bunx --bun create-windy@0.2.22 update --check
+bunx --bun create-windy@0.2.22 update
+bun install
+```
+
+升级器会更新受管模板文件；本地修改产生冲突时会 fail closed 并保留事务备份，不会静默
+覆盖。升级后按上面的环境变量启用 `agent` profile。

package/template/docs/platform/agent-tools.md

@@ -10,6 +10,11 @@ Server 端已提供 Agent Tool 的最小闭环：
 - 执行前使用 Permission Guard 校验 `permissionKey`。
 - 权限拒绝记录 `security.denied` 审计事件。
 - 执行成功记录 `agent.tool.execute` 审计事件。
+- ModuleHost 通过 `registerAiOperationHandlers` 注册模型无关 Operation plan。
+- Guarded Run facade 只把 Operation `allowedToolKeys` 中的定义交给模型。
+- Agent Server 的 Tool Call 必须通过短时 Execution Grant 回到受限 Tool Host。
+- Tool Host 使用宿主绑定的 Actor 与 Scope 重新执行 Operation/Tool Guard；客户端和模型
+  不能传权限、License、Scope 或授权结论。
 
 OpenAPI 文档由 `@elysiajs/swagger` 提供，随 Server 启动自动暴露。
 
@@ -34,4 +39,6 @@ Authorization: Bearer dev-admin-token
 - 工具执行复用系统资源 Repository；未配置 `DATABASE_URL` 时使用内存仓储，配置后使用 Drizzle 仓储。
 - 工具参数当前只支持基础分页参数。
 - 审计事件写入内存 sink；配置 `DATABASE_URL` 后会通过有界重试写入 PostgreSQL `audit_logs`，持续失败会增加计数并输出告警，审计查询优先读取该表。详细降级语义见 [平台审计可靠写入](./audit-reliability.md)。
-- 后续应继续完善 Agent Tool 的结构化输入 schema 和执行结果追踪。
+- Agent Runtime、环境变量、SSE 与 Compose profile 见
+  [Agent Runtime 接入与运行](./agent-runtime.md)。
+- 后续应继续完善 Agent Tool 的结构化输入 schema、写操作幂等和执行结果追踪。

package/template/package.json

@@ -15,6 +15,7 @@
     "dev:host": "bun run scripts/dev.ts",
     "dev:web": "bun run --cwd apps/web dev",
     "dev:server": "bun run --cwd apps/server dev",
+    "dev:agent": "docker compose --profile agent up --build",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",
     "dev:signing": "bun run --cwd apps/signing-service dev",

package/template/packages/config/index.test.ts

@@ -4,9 +4,11 @@ import {
   ConfigLoadError,
   defineModuleConfig,
   EnvironmentSecretResolver,
+  loadOpenAiCompatibleDeploymentConfig,
   loadModuleConfigSync,
   loadPlatformConfig,
   ModuleConfigRegistry,
+  normalizeOpenAiCompatibleBaseUrl,
   SecretRef,
   strictBoolean,
 } from "./index.js";
@@ -169,3 +171,44 @@ test("registry 拒绝重复模块和未知模块", () => {
   expect(() => registry.register(definition)).toThrow("配置模块重复注册");
   expect(() => registry.get("example.unknown")).toThrow("未知配置模块");
 });
+
+test("OpenAI-compatible 部署只在服务端解析 Secret 与运行上限", () => {
+  const config = loadOpenAiCompatibleDeploymentConfig({
+    QWEN_API_URL:
+      "https://workspace.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/",
+    QWEN_API_KEY: "server-only",
+    QWEN_MODEL: "qwen-plus",
+    AI_PROVIDER_CONNECT_TIMEOUT_MS: "2500",
+    AI_PROVIDER_REQUEST_TIMEOUT_MS: "45000",
+    AI_PROVIDER_MAX_RESPONSE_BYTES: "1048576",
+  });
+
+  expect(config).toEqual({
+    baseUrl:
+      "https://workspace.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
+    model: "qwen-plus",
+    apiKey: "server-only",
+    connectTimeoutMs: 2500,
+    requestTimeoutMs: 45000,
+    maxResponseBytes: 1048576,
+  });
+});
+
+test("OpenAI-compatible Endpoint 拒绝公网 HTTP 与 metadata", () => {
+  expect(() =>
+    normalizeOpenAiCompatibleBaseUrl("http://api.example.com/v1"),
+  ).toThrow("公网 OpenAI-compatible Endpoint 必须使用 HTTPS");
+  expect(() =>
+    normalizeOpenAiCompatibleBaseUrl("http://169.254.169.254/v1"),
+  ).toThrow("禁止访问云 metadata");
+  expect(() =>
+    normalizeOpenAiCompatibleBaseUrl("https://user:pass@example.com/v1?q=1"),
+  ).toThrow("不允许凭据、查询串或片段");
+
+  expect(
+    normalizeOpenAiCompatibleBaseUrl("http://qwen.internal:9000/v1/"),
+  ).toBe("http://qwen.internal:9000/v1");
+  expect(normalizeOpenAiCompatibleBaseUrl("http://10.20.30.40:8000/v1")).toBe(
+    "http://10.20.30.40:8000/v1",
+  );
+});

package/template/packages/config/index.ts

@@ -1,4 +1,5 @@
 export * from "./src/definition.js";
 export * from "./src/environment-loader.js";
+export * from "./src/ai-openai-compatible.js";
 export * from "./src/platform.js";
 export * from "./src/secrets.js";

package/template/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/config",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "index.ts",
+    "src/ai-openai-compatible.ts",
     "src/**/*.ts",
     "!src/**/*.test.ts"
   ],

package/template/packages/config/src/ai-openai-compatible.ts

@@ -0,0 +1,131 @@
+import { isIP } from "node:net";
+import { z } from "zod";
+import { defineModuleConfig } from "./definition.js";
+import {
+  loadModuleConfigSync,
+  strictInteger,
+  type ConfigEnvironment,
+} from "./environment-loader.js";
+import { EnvironmentSecretResolver } from "./secrets.js";
+
+export interface OpenAiCompatibleDeploymentConfig {
+  baseUrl: string;
+  model: string;
+  apiKey?: string;
+  connectTimeoutMs: number;
+  requestTimeoutMs: number;
+  maxResponseBytes: number;
+}
+
+const deploymentSchema: z.ZodType<OpenAiCompatibleDeploymentConfig> =
+  z.strictObject({
+    baseUrl: z.string().transform(normalizeOpenAiCompatibleBaseUrl),
+    model: z.string().trim().min(1).max(200),
+    apiKey: z.string().trim().min(1).optional(),
+    connectTimeoutMs: z.number().int().min(100).max(30_000),
+    requestTimeoutMs: z.number().int().min(1_000).max(300_000),
+    maxResponseBytes: z
+      .number()
+      .int()
+      .min(1_024)
+      .max(16 * 1_024 * 1_024),
+  });
+
+export const openAiCompatibleDeploymentConfigDefinition =
+  defineModuleConfig<OpenAiCompatibleDeploymentConfig>({
+    key: "ai.openai-compatible",
+    label: "OpenAI-compatible 模型部署",
+    ownedEnvironmentPrefixes: ["QWEN_", "AI_PROVIDER_"],
+    schema: deploymentSchema,
+    environment: [
+      { key: "QWEN_API_URL", path: "baseUrl" },
+      { key: "QWEN_MODEL", path: "model" },
+      {
+        key: "QWEN_API_KEY",
+        path: "apiKey",
+        secret: { provider: "env" },
+      },
+      integer("AI_PROVIDER_CONNECT_TIMEOUT_MS", "connectTimeoutMs", 5_000),
+      integer("AI_PROVIDER_REQUEST_TIMEOUT_MS", "requestTimeoutMs", 60_000),
+      integer(
+        "AI_PROVIDER_MAX_RESPONSE_BYTES",
+        "maxResponseBytes",
+        2 * 1_024 * 1_024,
+      ),
+    ],
+  });
+
+export function loadOpenAiCompatibleDeploymentConfig(
+  environment: ConfigEnvironment = process.env,
+): OpenAiCompatibleDeploymentConfig {
+  return loadModuleConfigSync(
+    openAiCompatibleDeploymentConfigDefinition,
+    environment,
+    new EnvironmentSecretResolver(environment),
+  );
+}
+
+export function normalizeOpenAiCompatibleBaseUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new Error("OpenAI-compatible Endpoint 无效");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("OpenAI-compatible Endpoint 只允许 HTTP 或 HTTPS");
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("OpenAI-compatible Endpoint 不允许凭据、查询串或片段");
+  }
+  const hostname = url.hostname.toLowerCase();
+  if (isCloudMetadataHost(hostname)) {
+    throw new Error("OpenAI-compatible Endpoint 禁止访问云 metadata");
+  }
+  if (url.protocol === "http:" && !isPrivateHost(hostname)) {
+    throw new Error("公网 OpenAI-compatible Endpoint 必须使用 HTTPS");
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  return url.toString().replace(/\/$/, "");
+}
+
+function integer(key: string, path: string, defaultValue: number) {
+  return { key, path, defaultValue, decode: strictInteger };
+}
+
+function isPrivateHost(hostname: string): boolean {
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname.endsWith(".internal") ||
+    hostname.endsWith(".local") ||
+    (!hostname.includes(".") && isIP(hostname) === 0)
+  ) {
+    return true;
+  }
+  if (isIP(hostname) === 4) {
+    const [first = 0, second = 0] = hostname.split(".").map(Number);
+    return (
+      first === 10 ||
+      first === 127 ||
+      (first === 172 && second >= 16 && second <= 31) ||
+      (first === 192 && second === 168)
+    );
+  }
+  if (isIP(hostname) === 6) {
+    return (
+      hostname === "::1" ||
+      hostname.startsWith("fc") ||
+      hostname.startsWith("fd")
+    );
+  }
+  return false;
+}
+
+function isCloudMetadataHost(hostname: string): boolean {
+  return (
+    hostname === "169.254.169.254" ||
+    hostname === "metadata.google.internal" ||
+    hostname === "metadata.azure.internal"
+  );
+}

package/template/packages/server-sdk/index.ts

@@ -40,8 +40,19 @@ export type {
   ModuleTaskHandlerRegistration,
   ModuleTaskResult,
 } from "./src/task-registration.js";
+export type {
+  ModuleAgentToolHostPort,
+  ModuleAgentToolInvocation,
+  ModuleAgentToolResult,
+} from "./src/tool-host-port.js";
 export type {
   ModuleToolContext,
   ModuleToolHandlerRegistration,
   ModuleToolResult,
 } from "./src/tool-registration.js";
+export type {
+  ModuleAiJsonValue,
+  ModuleAiOperationContext,
+  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationPlan,
+} from "./src/ai-operation-registration.js";

package/template/packages/server-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -9,6 +9,7 @@
   "files": [
     "index.ts",
     "src/actor.ts",
+    "src/ai-operation-registration.ts",
     "src/audit-port.ts",
     "src/jobs-port.ts",
     "src/module-host.ts",
@@ -19,7 +20,8 @@
     "src/search-provider-port.ts",
     "src/storage-port.ts",
     "src/task-registration.ts",
-    "src/tool-registration.ts"
+    "src/tool-registration.ts",
+    "src/tool-host-port.ts"
   ],
   "scripts": {
     "test": "bun test",

package/template/packages/server-sdk/src/ai-operation-registration.ts

@@ -0,0 +1,31 @@
+import type { ModuleActor } from "./actor.js";
+
+export type ModuleAiJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | ModuleAiJsonValue[]
+  | { [key: string]: ModuleAiJsonValue };
+
+export interface ModuleAiOperationContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+}
+
+/**
+ * 业务模块只负责把类型化输入收敛为模型无关的指令和用户消息。
+ * Provider、Deployment、Secret、Execution Grant 与 Tool 授权均由宿主持有。
+ */
+export interface ModuleAiOperationPlan {
+  readonly instructions: string;
+  readonly userPrompt: string;
+}
+
+export interface ModuleAiOperationHandlerRegistration {
+  readonly operationKey: string;
+  prepare(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+}

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

@@ -1,4 +1,5 @@
 import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
+import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
 import type { ModuleRolePreset } from "./role-preset.js";
 import type { ModuleRouteDefinition } from "./route-definition.js";
 import type { ModuleSearchProvider } from "./search-provider-port.js";
@@ -35,6 +36,10 @@ export interface ModuleHost {
   registerToolHandlers(
     registrations: readonly ModuleToolHandlerRegistration[],
   ): void;
+  /** 注册 Manifest `aiOperations` 已声明的模型无关 Operation 执行计划。 */
+  registerAiOperationHandlers(
+    registrations: readonly ModuleAiOperationHandlerRegistration[],
+  ): void;
   /** 注册角色预设；permissionKeys 须属于本模块 Manifest 权限声明。 */
   registerRolePresets(presets: readonly ModuleRolePreset[]): void;
   /** 注册 Manifest `providers` 已声明的搜索 Provider。 */

package/template/packages/server-sdk/src/tool-host-port.ts

@@ -0,0 +1,22 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleAgentToolInvocation {
+  readonly runId: string;
+  readonly toolCallId: string;
+  readonly toolKey: string;
+  readonly arguments: Readonly<Record<string, ModuleAiJsonValue>>;
+}
+
+export interface ModuleAgentToolResult {
+  readonly value: ModuleAiJsonValue;
+}
+
+/**
+ * 宿主创建并绑定 Operation、Actor 与 Scope 的受限 Tool Host Port。
+ * 调用方不能传 Permission、Feature、License 或数据范围作为授权事实。
+ */
+export interface ModuleAgentToolHostPort {
+  execute(
+    invocation: ModuleAgentToolInvocation,
+  ): Promise<ModuleAgentToolResult>;
+}