create-windy 0.2.19 → 0.2.21

package/template/docs/architecture/object-storage.md

@@ -58,8 +58,20 @@ Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只
 - 删除为幂等操作；第一次存在时返回 `true`，重复删除返回 `false`。
 - 进程在 Blob 发布与元数据发布之间退出时可能产生孤儿内容；上传生命周期模块基于过期时间、引用集合与 grace period 清理。
 
+## 模块受限 Upload/BlobRead Port
+
+业务模块不直接使用 `UploadService` / `FileService`，而是经 `ModuleRequestContext.storage` 获得 `ModuleStoragePort`（宿主实现见 `apps/server/src/module-host/storage-port.ts`）：
+
+- `createUploadSession` 的 purpose 强制属于本模块经 Host 注册的 Upload Policy；跨模块用途和平台基础用途（如 `bulk-data`、`branding-logo`）一律以 `UPLOAD_FORBIDDEN` 拒绝。Owner 由宿主以当前 Actor 补齐，模块无法代他人创建会话。
+- `openFile` 走 `FileService.open` 的 Owner 约束，并在返回前校验文件用途属于本模块——即使是本人文件，用途越界也拒绝。
+- `openPublicFile` 走 `FileService.openPublic` 的 Purpose 约束，且只允许本模块已注册用途。
+- 模块不直接接触 `BlobStore` 或 Upload Repository；宿主未挂载存储服务时，任何访问都以明确错误失败，不静默绕过。
+
+用途唯一性仍在 Host 注册时全局校验：命名空间重叠的模块（如 `shop` 与 `shop.sub`）注册同一 purpose 会在启动时失败。
+
 ## 当前切片
 
 - F1：Blob 端口、SHA-256、随机引用和本地流式 Adapter 已完成。
 - F2：上传会话、分片续传、文件元数据、校验和清理已完成。
 - F3：服务端授权下载、审计、bulk artifact 与 Logo 接入已完成。
+- F4：模块受限 Upload/BlobRead Port 已完成，业务模块经 Host 注册用途并受命名空间约束。

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.20 升级
+
+先检查计划，再应用连续 recipe：
+
+```bash
+bunx --bun create-windy@0.2.21 update --check
+bunx --bun create-windy@0.2.21 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";
@@ -49,6 +51,63 @@ test("strict loader 对 unknown 与错误类型 fail-fast 且不回显输入值"
   }
 });
 
+test("WINDY_LICENSE_VERSIONS 解析宿主自定义 License 版本目录", () => {
+  const config = loadPlatformConfig({
+    WINDY_LICENSE_VERSIONS: JSON.stringify([
+      { key: "oem-basic", label: "OEM 基础版", order: 10 },
+      {
+        key: "oem-pro",
+        label: "OEM 专业版",
+        description: "含高级治理能力",
+        order: 20,
+      },
+    ]),
+  });
+
+  expect(config.license.versions).toEqual([
+    { key: "oem-basic", label: "OEM 基础版", description: "", order: 10 },
+    {
+      key: "oem-pro",
+      label: "OEM 专业版",
+      description: "含高级治理能力",
+      order: 20,
+    },
+  ]);
+  expect(loadPlatformConfig({}).license.versions).toBeUndefined();
+});
+
+test("WINDY_LICENSE_VERSIONS 非法 JSON 或非法结构时 fail-fast", () => {
+  expect(() =>
+    loadPlatformConfig({ WINDY_LICENSE_VERSIONS: "not-a-json" }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "license.versions",
+    }),
+  );
+  expect(() =>
+    loadPlatformConfig({
+      WINDY_LICENSE_VERSIONS: JSON.stringify([{ key: "missing-order" }]),
+    }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+    }),
+  );
+  expect(() =>
+    loadPlatformConfig({
+      WINDY_LICENSE_VERSIONS: JSON.stringify([
+        { key: "fractional", label: "小数版本", order: 1.5 },
+      ]),
+    }),
+  ).toThrow(
+    expect.objectContaining<Partial<ConfigLoadError>>({
+      code: "CONFIG_INVALID_VALUE",
+      fieldPath: "license.versions",
+    }),
+  );
+});
+
 test("必填 Secret 缺失时 fail-fast 且 registry 不暴露环境引用", () => {
   const definition = defineModuleConfig({
     key: "example.secure",
@@ -112,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.1",
+  "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/config/src/platform.ts

@@ -1,4 +1,11 @@
-import type { DatabaseDialect } from "@southwind-ai/shared";
+import type {
+  DatabaseDialect,
+  LicenseCatalogDefinition,
+} from "@southwind-ai/shared";
+import {
+  parseLicenseCatalog,
+  parseLicenseCatalogJson,
+} from "@southwind-ai/shared";
 import { z } from "zod";
 import { defineModuleConfig, ModuleConfigRegistry } from "./definition.js";
 import {
@@ -33,6 +40,8 @@ export interface PlatformConfig {
     publicKeyId?: string;
     publicKey?: string;
     machineCode?: string;
+    /** 宿主自定义 License 版本目录；未配置时回退 shared 默认三级目录。 */
+    versions?: LicenseCatalogDefinition[];
   };
   audit: { enabled: boolean; redactFields: string[] };
   compatibility: {
@@ -75,6 +84,20 @@ const platformSchema: z.ZodType<PlatformConfig> = z.strictObject({
     publicKeyId: z.string().trim().min(1).optional(),
     publicKey: z.string().trim().min(1).optional(),
     machineCode: z.string().trim().min(1).optional(),
+    versions: z
+      .unknown()
+      .transform((value, context) => {
+        try {
+          return parseLicenseCatalog(value);
+        } catch (error) {
+          context.addIssue({
+            code: "custom",
+            message: error instanceof Error ? error.message : "版本目录无效",
+          });
+          return z.NEVER;
+        }
+      })
+      .optional(),
   }),
   audit: z.strictObject({
     enabled: z.boolean(),
@@ -105,6 +128,7 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
     "LICENSE_PUBLIC_KEY_ID",
     "LICENSE_PUBLIC_KEY",
     "LICENSE_MACHINE_CODE",
+    "WINDY_LICENSE_VERSIONS",
   ],
   environment: [
     value("PLATFORM_NAME", "name", "Windy Platform"),
@@ -133,6 +157,9 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
     value("LICENSE_PUBLIC_KEY_ID", "license.publicKeyId"),
     value("LICENSE_PUBLIC_KEY", "license.publicKey"),
     secret("LICENSE_MACHINE_CODE", "license.machineCode"),
+    value("WINDY_LICENSE_VERSIONS", "license.versions", undefined, (raw) =>
+      parseLicenseCatalogJson(raw, "WINDY_LICENSE_VERSIONS"),
+    ),
     value("AUDIT_ENABLED", "audit.enabled", true, strictBoolean),
     value(
       "AUDIT_REDACT_FIELDS",

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/database/src/runner.ts

@@ -1,16 +1,14 @@
-import type {
-  BundleMigrationDefinition,
-  DatabaseCompatibilityAdapter,
-  DatabaseDialect,
-  MigrationBundle,
-  MigrationManifestSource,
-  MigrationStatement,
-} from "@southwind-ai/shared";
 import {
   normalizeManifestBundles,
   orderBundleMigrations,
   validateAndOrderBundles,
-} from "./bundle-validation.js";
+  type BundleMigrationDefinition,
+  type DatabaseCompatibilityAdapter,
+  type DatabaseDialect,
+  type MigrationBundle,
+  type MigrationManifestSource,
+  type MigrationStatement,
+} from "@southwind-ai/shared";
 import { createDialectAdapter } from "./dialects.js";
 import type { MigrationHistoryEntry, MigrationHistoryStore } from "./store.js";
 

package/template/packages/example-work-order/index.ts

@@ -2,3 +2,4 @@ export * from "./src/contract.js";
 export * from "./src/manifest.js";
 export * from "./src/migration-bundle.js";
 export * from "./src/schema.js";
+export * from "./src/server-module.js";

package/template/packages/example-work-order/package.json

@@ -4,6 +4,8 @@
   "private": true,
   "type": "module",
   "dependencies": {
+    "@southwind-ai/modules": "workspace:*",
+    "@southwind-ai/server-sdk": "workspace:*",
     "@southwind-ai/shared": "workspace:*",
     "zod": "^4.4.3"
   },

package/template/packages/example-work-order/src/server-module.ts

@@ -0,0 +1,61 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  InstallableServerModule,
+  ModuleRouteDefinition,
+  ModuleSearchProvider,
+  ModuleTaskHandler,
+} from "@southwind-ai/server-sdk";
+import { workOrderModule } from "./manifest.js";
+
+export interface WorkOrderServerBindings {
+  readonly routes: readonly ModuleRouteDefinition[];
+  readonly snapshot: ModuleTaskHandler;
+  readonly searchProvider: ModuleSearchProvider;
+}
+
+/**
+ * 工单业务包拥有 Manifest 与 Host 注册过程；宿主只注入具体业务实现。
+ */
+export function createWorkOrderServerModule(
+  bindings: WorkOrderServerBindings,
+): InstallableServerModule<ModuleManifest> {
+  return {
+    manifest: workOrderModule(),
+    setup(host) {
+      host.registerUploadPolicy({
+        purpose: "work-order.ticket.attachment",
+        maxByteSize: 20 * 1024 * 1024,
+        maxPartByteSize: 4 * 1024 * 1024,
+        sessionTtlMs: 2 * 60 * 60_000,
+        allowedTypes: {
+          "application/pdf": ["pdf"],
+          "image/png": ["png"],
+          "image/jpeg": ["jpg", "jpeg"],
+          "text/plain": ["txt"],
+        },
+        signature: "none",
+      });
+      host.registerRoutes(bindings.routes);
+      host.registerTaskHandlers([
+        {
+          taskKey: "work-order.ticket.snapshot",
+          handler: bindings.snapshot,
+        },
+      ]);
+      host.registerSearchProviders([bindings.searchProvider]);
+      host.registerRolePresets([
+        {
+          key: "work-order.ticket-manager",
+          label: "工单管理员",
+          description: "管理本部门及下级部门工单的模块角色预设。",
+          dataScope: "department-and-children",
+          permissionKeys: [
+            "work-order.ticket.create",
+            "work-order.ticket.manage",
+            "work-order.ticket.read",
+          ],
+        },
+      ]);
+    },
+  };
+}

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/jobs/src/types.ts

@@ -179,8 +179,14 @@ export interface SubmitDurableJobResult {
   created: boolean;
 }
 
-export interface DurableJobs {
+/**
+ * 只保留提交能力的窄接口，用于向模块等受限调用方暴露 Durable Jobs。
+ */
+export interface DurableJobSubmitter {
   submit(input: SubmitDurableJob): Promise<SubmitDurableJobResult>;
+}
+
+export interface DurableJobs extends DurableJobSubmitter {
   get(id: string): Promise<DurableJobSnapshot | undefined>;
   list(requestedBy: string, limit?: number): Promise<DurableJob[]>;
 }

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {