create-windy 0.6.8 → 0.6.10

package/template/docs/architecture/ai-runtime.md

@@ -367,6 +367,11 @@ Endpoint 配置属于高风险管理动作，必须具备独立 Permission 和
 
 ## LLM、VLM 与 Agent SSE 协议
 
+通用规划、Tool/节点汇总与最终回答不由业务仓库各自复制协议。选择 `system.agent` 的
+项目使用[Agent Supervisor 与最终回答契约](../platform/agent-supervisor-output-contract.md)
+组合业务 Operation；只有通过 V1 typed `finalAnswer` 校验的 completed Run 结果才能成为
+用户答案。
+
 ### 适用范围
 
 以下文本或结构化输出统一使用 SSE：

package/template/docs/development/business-web-routes.md

@@ -4,7 +4,8 @@
 
 整个 `apps/web/src` 都是 project-owned 应用源码。布局、页面、组件库封装、Router、
 导航呈现与 Host 实现均可由项目修改、替换或删除；普通 `windy update` 和模块命令不能
-为了接入入口而重写这些文件。
+为了接入入口而整文件重写这些文件。一次性兼容迁移可以使用版本 recipe 修改已登记的
+窄锚点，具体例外见[项目 UI 组件展厅](./ui-component-gallery.md)。
 
 ## package 默认贡献
 
@@ -63,6 +64,7 @@ Foundation 访问快照改善导航和直达体验。`admin.visible=false` 只
 - 客户保留、修改与删除均由项目决定；
 - 删除以 tombstone 跨版本保留；
 - 模块 package 更新只改变依赖与自身导出，不改客户 layout、Router 或页面；
+- 已登记版本 recipe 只追加明确的兼容锚点，缺失或不唯一时 fail closed；
 - Host 不再实现协议时，CLI/构建只诊断并 fail closed，不能覆盖客户实现。
 
 未来若提供整套 Admin 预设更新，它必须是独立、显式选择的三方合并能力；当前没有

package/template/docs/development/ui-component-gallery.md

@@ -0,0 +1,44 @@
+# 项目 UI 组件展厅
+
+更新时间：2026-08-21。
+
+## 能力边界
+
+`/ui/component` 展示当前项目在
+`apps/web/src/components/ui/*/index.ts` 中封装的全部组件族。页面不维护第二份目录清单：
+Vite 在构建当前项目时扫描每个 `index.ts`，因此下游新增 `radio-group`、`textarea` 等
+组件后，会自动出现在“项目扩展”分组并列出真实具名导出。
+
+Windy 自带组件提供可操作的主题内示例。项目扩展组件默认只展示发现结果与导出名，因为
+任意组件所需的 props、slot 和业务上下文无法安全推断；项目可继续在自己的页面中增加
+针对性预览，组件入口本身仍由项目拥有。
+
+该页面属于 `system` Module，统一使用以下 Manifest 事实：
+
+- Feature：`system.ui-components`；
+- Permission：`system.ui-components.read`；
+- Admin Route：`system.ui-components`，路径 `/ui/component`；
+- 菜单入口与直达路由均经过现有 Feature/RBAC Guard。
+
+## 下游升级
+
+`create-windy@0.6.9` 的 `starter-0.6.8-to-0.6.9` recipe 会创建新的展厅页面文件，并在
+下游项目现有 Router 中只追加两处登记内容：
+
+1. `platformAdminPageComponents` 中的懒加载页面 binding；
+2. `PlatformAdminPageKey` 与 `system.ui-components` Route binding。
+
+这不是对整个 Admin 预设的重新同步。其余 `apps/web/src` 文件仍为 project-owned，
+客户的 layout、业务 Route、页面和组件不会被模板覆盖。recipe 只接受唯一的稳定锚点；
+若项目已经完全替换 Host，或锚点缺失/不唯一，dry-run 会报告冲突并在写入前停止。完成
+升级后建议检查：
+
+```bash
+bun run windy update --dry-run
+bun run windy update
+bun run windy doctor
+bun run --cwd apps/web typecheck
+```
+
+验收时应确认 `/ui/component` 可访问，并且组件数量与当前项目
+`apps/web/src/components/ui` 下含 `index.ts` 的目录数量一致。

package/template/docs/license/license-pairing-activation.md

@@ -0,0 +1,67 @@
+# License 手机扫码配对激活
+
+## 产品目标
+
+扫码配对激活把人工操作压缩为“客户服务器展示二维码、手机签发、客户服务器输入 8 位码”。客户服务器不访问互联网，用户不下载、复制或输入完整 License；手机 Web 在后台把同一份 `SignedLicenseV1` 回传到客户内网。
+
+8 位 Crockford Base32 配对码不是 License、兑换码或签名。它只确认手机显示的签发结果与客户服务器当前一次性会话一致。License 版本和有效期只能在完整 V1 通过 ED25519、公钥、产品、设备码、时间和防降级校验后读取。
+
+## 交互与数据流
+
+1. 已认证且具备 `system.license.manage` 的用户创建 5 分钟激活会话。
+2. Web 把浏览器当前 Origin 交给客户 Server；Server 要求它与请求 `Origin` 精确一致，再生成不可预测的 `sessionId`、投递 `token`、`nonce` 和同源回调，返回 canonical `LicensePairingRequestV1` 供 Web 渲染二维码。
+3. 厂商操作员登录 `apps/license` 并扫码。二维码只提供设备码、产品、会话和回调信息，不能提供客户、项目、合同、License 版本或到期时间。
+4. 操作员按签发中心权威资料完成核对，既有签发服务生成 `SignedLicenseV1`。
+5. 手机 Web 使用无凭据、无 Referrer、禁止重定向的跨 Origin 请求，把 canonical License 和一次性 Token 自动 POST 到客户内网回调。
+6. 客户 Server 先验签并确认产品、设备码和有效期，只把合法候选保存在当前进程的短期会话中。
+7. 手机和客户 Server 分别按同一 SDK 协议计算 8 位码。用户输入后，Server 最多允许五次尝试；匹配后仍通过现有串行化 `LicenseInstaller` 完成防降级、原子替换和审计。
+
+普通设备码扫码仍保留签发后下载文件的既有行为。配对回传失败时，License 已经签发，手机页会保留该结果并直接重试自动回传，不会再次调用签发 API；最近签发记录仍可下载文件兜底。
+
+## 协议边界
+
+`LicensePairingRequestV1` 使用严格字段集合：
+
+```json
+{
+  "type": "windy-license-pairing",
+  "version": 1,
+  "sessionId": "一次性会话标识",
+  "token": "一次性高熵投递 Token",
+  "nonce": "一次性高熵挑战值",
+  "productCode": "windy-platform",
+  "machineCode": "客户服务器设备码",
+  "callbackUrl": "客户内网 HTTPS 投递地址",
+  "expiresAt": "会话失效时间"
+}
+```
+
+SDK 拒绝未知字段、非法时间、用户信息、查询串、Fragment、userinfo、错误路径和公网回调地址。生产只允许 HTTPS；HTTP 仅允许 loopback 开发地址。当前内网主机接受 RFC 1918、IPv4/IPv6 link-local、IPv6 ULA、localhost 以及 `.local`、`.internal`、`.lan` 后缀。
+
+配对码绑定 `sessionId`、`nonce`、产品、设备码和 canonical V1 摘要，取 SHA-256 前 40 bit 后编码为 8 位 Crockford Base32。配对码不包含投递 Token，不进入 License 文件，不替代 ED25519。
+
+## Server API 与 Guard
+
+| 方法      | 路径                                                       | 访问边界                            |
+| --------- | ---------------------------------------------------------- | ----------------------------------- |
+| `POST`    | `/api/license/runtime/pairing/sessions`                    | 已认证、License 管理权限            |
+| `GET`     | `/api/license/runtime/pairing/sessions/:sessionId`         | 已认证、License 管理权限            |
+| `OPTIONS` | `/api/license/runtime/pairing/sessions/:sessionId/deliver` | 严格 Origin 的 CORS/PNA 预检        |
+| `POST`    | `/api/license/runtime/pairing/sessions/:sessionId/deliver` | 一次性 Token、严格 Origin、匿名投递 |
+| `POST`    | `/api/license/runtime/pairing/sessions/:sessionId/confirm` | 已认证、License 管理权限和安装审计  |
+
+License 缺失、损坏或过期时，上述恢复入口仍在限制模式窄 allowlist 中；其它业务 API 不会因此开放。所有配对响应使用 `Cache-Control: no-store`，回调只回显稳定状态，不返回 License 或 Token。
+
+## 部署与浏览器条件
+
+客户 Server 使用 `WINDY_LICENSE_PAIRING_ORIGINS` 配置允许执行手机回传的签发中心 Origin，多个 Origin 以逗号分隔。生产缺少配置时扫码配对 fail closed；开发默认只允许 `http://localhost:9843`。不得配置 `*`，也不启用 credentialed CORS。
+
+手机必须同时能够通过移动网络访问厂商 HTTPS 签发中心，并通过客户 Wi-Fi 或 VPN 访问二维码中的客户内网 HTTPS 地址。客户内网证书必须被目标手机信任。浏览器可能对公网页面访问私网地址执行 Private Network Access 预检，客户 Server 只对精确允许的 Origin 返回对应 CORS/PNA 响应。
+
+如果现场禁止手机访问客户内网，系统无法在单个 8 位码中安全传输完整签名 License，应改用 `.license.json`、响应二维码或 W1；不得降级为 SDK 内置共享密钥或截断签名。
+
+## 运行边界
+
+配对会话有固定数量、固定 TTL、一次投递和五次确认限制；失效或锁定时立即丢弃待安装 License。普通日志和审计不保存二维码、Token、完整 License 或配对码，只保留会话/License 标识、摘要和稳定结果。
+
+当前客户 License 运行时仍是单进程单写者设计，配对会话也只存在于当前 Server 进程。多进程或多副本部署必须先提供共享短期会话存储、原子消费和与 License 单写者一致的锁语义，不能依赖负载均衡粘性会话冒充正确性。

package/template/docs/operations/incremental-delivery.md

@@ -107,11 +107,11 @@ package `bin`，避免 fresh `bun install` 改写受管源码的 POSIX mode。
 
 ```bash
 sudo install -d -m 0755 /opt/windy/runtime /opt/windy/bin
-sudo cp -R ./packages/delivery /opt/windy/runtime/delivery-0.6.7.tmp
-sudo chmod 0555 /opt/windy/runtime/delivery-0.6.7.tmp/bin/windy-delivery
-sudo mv /opt/windy/runtime/delivery-0.6.7.tmp \
-  /opt/windy/runtime/delivery-0.6.7
-sudo ln -s /opt/windy/runtime/delivery-0.6.7/bin/windy-delivery \
+sudo cp -R ./packages/delivery /opt/windy/runtime/delivery-0.6.9.tmp
+sudo chmod 0555 /opt/windy/runtime/delivery-0.6.9.tmp/bin/windy-delivery
+sudo mv /opt/windy/runtime/delivery-0.6.9.tmp \
+  /opt/windy/runtime/delivery-0.6.9
+sudo ln -s /opt/windy/runtime/delivery-0.6.9/bin/windy-delivery \
   /opt/windy/bin/windy-delivery.next
 sudo mv -Tf /opt/windy/bin/windy-delivery.next \
   /opt/windy/bin/windy-delivery
@@ -175,10 +175,11 @@ resource fork 或 Finder metadata。路径组件以 `._` 开头时直接拒绝
 
 ## 构建与旧项目升级
 
-`create-windy@0.6.7` 候选把 `packages/delivery`、本说明和 `delivery:remote` 脚本加入
-受管 Starter。`0.6.6 -> 0.6.7` 通过连续 recipe 事务升级；现有 project-owned 发布脚本
-不会被覆盖。正式构建先准备一个完整 release 目录，其中 `images.tar` 必须是 OCI image
-layout（含 `oci-layout`、`index.json` 和 `blobs/sha256/*`），再运行：
+`packages/delivery`、本说明和 `delivery:remote` 脚本自 `create-windy@0.6.7` 起进入受管
+Starter；当前公开版为 `0.6.9`，最低支持基线 `0.6.6` 可通过连续 recipe 事务升级，现有
+project-owned 发布脚本不会被覆盖。正式构建先准备一个完整 release 目录，其中
+`images.tar` 必须是 OCI image layout（含 `oci-layout`、`index.json` 和
+`blobs/sha256/*`），再运行：
 
 ```bash
 bun run delivery:remote -- pack \

package/template/docs/platform/agent-supervisor-output-contract.md

@@ -0,0 +1,80 @@
+# Agent Supervisor 与最终回答契约
+
+更新时间：2026-08-21。
+
+## 边界
+
+`system.agent` 拥有通用 Supervisor 的规划、Tool/节点汇总约束、typed final-answer
+协议和平台发布坐标。业务模块继续拥有 Operation Key、输入、Feature、Permission、
+Audit、数据范围、业务指令、允许的 Tool、附加输出字段、会话持久化和页面投影；不得复制
+一份会随项目漂移的通用 Supervisor Prompt。
+
+业务 Agent Operation 通过 `@southwind-ai/server-sdk` 的
+`defineSystemAgentSupervisorHandler()` 接入。该 seam 会：
+
+1. 在业务指令前加入平台 Supervisor 指令；
+2. 把平台 Workflow/Prompt/Route 版本与业务版本组合成不可变 Run 坐标；
+3. 要求运行时输出 Schema 包含 canonical `finalAnswer` V1；
+4. 标记 Handler，使 Server 在启动 Run 前核对运行时 Schema 与 Manifest Schema 完全一致。
+
+## V1 envelope
+
+面向用户的答案只有一个事实入口：
+
+```json
+{
+  "finalAnswer": {
+    "schemaVersion": 1,
+    "text": "面向用户的完整最终回答"
+  }
+}
+```
+
+Operation 可以在顶层增加业务字段，例如引用、表单建议或受治理成果引用；这些字段必须与
+`finalAnswer` 一起进入该 Operation 自己的 Manifest output schema。Schema 使用
+`composeSystemAgentFinalAnswerSchemaV1()` 组合，不能覆盖 `finalAnswer`、放宽其额外字段
+或省略顶层 required。
+
+Agent Runtime 仍以 Provider strict JSON Schema 和终态 `jsonschema` 校验为最终边界。
+Server 只把与 Manifest 字节语义一致的 Supervisor Schema 交给 Runtime。Run release
+同时固定 Operation、Workflow、Prompt、Route、Manifest digest、Tool Schema digest 和
+独立 output-schema digest；因此旧 release ID 不会静默代表新 Prompt 或新 envelope。
+
+## 消费规则
+
+Web、Server 持久化和其它消费端统一使用 `projectAgentFinalAnswer()`：
+
+- `finalAnswer.schemaVersion === 1` 且 `text` 为非空字符串时才形成用户答案；
+- typed answer 与旧字段同时存在时，typed answer 始终优先；
+- typed answer 存在但无效时 fail closed，不能退回旧字段；
+- 默认不读取顶层 `text`，更不递归搜索任意节点、Tool 结果、`total` 或其它统计字段；
+- 迁移期只有显式 `allowLegacyTopLevelText: true` 才允许一次顶层 `text` fallback，字符串内
+  JSON 不再二次解包。
+
+流式 `output.delta` 是生成进度，不是可持久化的最终回答。只有 completed Run 的结构化
+result 通过上述投影后，才能写入聊天历史或业务成果。
+
+## 下游迁移
+
+从旧 `{ text }` 输出迁移时：
+
+1. 将 Manifest output schema 改为 `composeSystemAgentFinalAnswerSchemaV1()`，业务附加字段
+   保持顶层类型化声明；
+2. 把 Handler 改为 `defineSystemAgentSupervisorHandler()`，业务只保留自身指令和版本；
+3. 将模型示例和测试输出改为 `{ finalAnswer: { schemaVersion: 1, text } }`；
+4. Web、Server 持久化和后台消费改用 `projectAgentFinalAnswer()`；
+5. 只在读取发布前历史结果时临时开启顶层 fallback，并记录命中情况；
+6. 运行 focused Server/Domain 测试、typecheck、build，再用真实 Provider 走一次 canonical
+   Run/SSE/result 回答验收。
+
+下列条件全部满足后删除 project-owned 临时兼容实现：
+
+- 项目已升级到包含本契约的 Windy 版本；
+- 所有可创建新 Run 的 Operation 都声明并产生 typed `finalAnswer`；
+- 在线消费、断线恢复和服务端历史持久化都只走统一投影器；
+- 发布前历史数据已迁移，或其只读路径被单独、明确地保留，不与新 Run 共用 fallback；
+- focused 测试、typecheck、build 与真实 canonical Runtime 回答验收均通过。
+
+删除对象包括业务仓库复制的通用 Supervisor Prompt、递归 `text`/JSON 解包器、任意节点
+答案猜测和新 Run 路径上的 legacy fallback。业务专属 Prompt、权限、数据范围、会话与产品
+投影不属于临时兼容层。

package/template/packages/ai-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/ai-client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/ai-client/src/agent/contracts/final-answer.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AgentContractParseError,
+  projectAgentFinalAnswer,
+} from "@southwind-ai/ai-client/contracts";
+
+describe("Agent typed final answer", () => {
+  test("多节点结果始终优先使用 typed finalAnswer", () => {
+    expect(
+      projectAgentFinalAnswer({
+        finalAnswer: { schemaVersion: 1, text: "可信最终回答" },
+        text: "旧顶层回答",
+        nodes: [
+          { text: "规划文本" },
+          { output: { text: "Tool 文本", total: 999 } },
+        ],
+        total: 2,
+      }),
+    ).toEqual({
+      finalAnswer: { schemaVersion: 1, text: "可信最终回答" },
+      source: "typed-v1",
+    });
+  });
+
+  test("缺少 typed answer 时不猜测任意 text 或 total", () => {
+    for (const value of [
+      { nodes: [{ text: "中间节点" }] },
+      { result: { text: "嵌套结果" } },
+      { total: 42 },
+      { text: '{"text":"重复序列化"}' },
+    ]) {
+      expect(() => projectAgentFinalAnswer(value)).toThrow(
+        AgentContractParseError,
+      );
+    }
+  });
+
+  test("迁移开关只接受一次顶层 text fallback", () => {
+    expect(
+      projectAgentFinalAnswer(
+        { text: "旧版回答", nodes: [{ text: "无关" }] },
+        { allowLegacyTopLevelText: true },
+      ),
+    ).toEqual({
+      finalAnswer: { schemaVersion: 1, text: "旧版回答" },
+      source: "legacy-top-level-text",
+    });
+    expect(() =>
+      projectAgentFinalAnswer(
+        { result: { text: "不允许嵌套 fallback" } },
+        { allowLegacyTopLevelText: true },
+      ),
+    ).toThrow("output.text");
+  });
+
+  test("typed answer 存在但无效时禁止降级旧字段", () => {
+    expect(() =>
+      projectAgentFinalAnswer(
+        {
+          finalAnswer: { schemaVersion: 2, text: "未知协议" },
+          text: "旧版回答",
+        },
+        { allowLegacyTopLevelText: true },
+      ),
+    ).toThrow("只支持版本 1");
+  });
+});

package/template/packages/ai-client/src/agent/contracts/final-answer.ts

@@ -0,0 +1,53 @@
+import { AgentContractParseError, recordAt, stringAt } from "./validation.js";
+
+export const AGENT_FINAL_ANSWER_SCHEMA_VERSION = 1 as const;
+
+export interface AgentFinalAnswerV1 {
+  readonly schemaVersion: 1;
+  readonly text: string;
+}
+
+export interface AgentFinalAnswerProjection {
+  readonly finalAnswer: AgentFinalAnswerV1;
+  readonly source: "typed-v1" | "legacy-top-level-text";
+}
+
+/**
+ * 只读取 canonical typed answer。迁移期可显式允许旧输出的顶层 `text`；不会递归
+ * 搜索节点、Tool 结果、统计字段或再次解析字符串中的 JSON。
+ */
+export function projectAgentFinalAnswer(
+  value: unknown,
+  options: { readonly allowLegacyTopLevelText?: boolean } = {},
+): AgentFinalAnswerProjection {
+  const output = recordAt(value, "output");
+  if (output.finalAnswer !== undefined) {
+    const answer = recordAt(output.finalAnswer, "output.finalAnswer");
+    if (answer.schemaVersion !== AGENT_FINAL_ANSWER_SCHEMA_VERSION) {
+      throw new AgentContractParseError(
+        "output.finalAnswer.schemaVersion",
+        "只支持版本 1",
+      );
+    }
+    return {
+      finalAnswer: {
+        schemaVersion: AGENT_FINAL_ANSWER_SCHEMA_VERSION,
+        text: stringAt(answer, "text", "output.finalAnswer"),
+      },
+      source: "typed-v1",
+    };
+  }
+  if (options.allowLegacyTopLevelText) {
+    return {
+      finalAnswer: {
+        schemaVersion: AGENT_FINAL_ANSWER_SCHEMA_VERSION,
+        text: stringAt(output, "text", "output"),
+      },
+      source: "legacy-top-level-text",
+    };
+  }
+  throw new AgentContractParseError(
+    "output.finalAnswer",
+    "缺少 typed final answer",
+  );
+}

package/template/packages/ai-client/src/agent/contracts/index.ts

@@ -1,5 +1,6 @@
 export * from "./errors.js";
 export * from "./events.js";
+export * from "./final-answer.js";
 export * from "./operation.js";
 export * from "./runs.js";
 export * from "./sse.js";

package/template/packages/modules/index.ts

@@ -14,3 +14,4 @@ export * from "./src/project-module-assembly.js";
 export * from "./src/module-host-range.js";
 export * from "./src/admin-ui-manifest.js";
 export * from "./src/system-admin-ui-catalog.js";
+export * from "./src/system-agent-supervisor.js";

package/template/packages/modules/package.json

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

package/template/packages/modules/src/system-admin-routes.ts

@@ -70,6 +70,14 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "system.feature.read",
     "system.feature",
   ),
+  route(
+    "system.ui-components",
+    "/ui/component",
+    "组件总览",
+    "sidebar",
+    "system.ui-components.read",
+    "system.ui-components",
+  ),
   // @windy-module system.notification begin
   route(
     "system.notification",

package/template/packages/modules/src/system-admin-ui-catalog.ts

@@ -1,8 +1,9 @@
 import type { AdminUiManifest } from "./admin-ui-manifest.js";
 import { systemAdminRoutes } from "./system-admin-routes.js";
+import { systemModuleDefinitions } from "./system-module-catalog.js";
 
 const definitions = [
-  ["system", ["system.feature"]],
+  ["system", ["system.feature", "system.ui-components"]],
   [
     "system.identity",
     [
@@ -58,11 +59,14 @@ const definitions = [
 const routeByKey = new Map(
   systemAdminRoutes.map((route) => [route.key, route] as const),
 );
+const versionByName = new Map(
+  systemModuleDefinitions.map(({ name, version }) => [name, version] as const),
+);
 
 export function systemAdminUiManifests(): AdminUiManifest[] {
   return definitions.map(([name, routeKeys]) => ({
     name,
-    version: "0.1.0",
+    version: versionByName.get(name) ?? "0.1.0",
     adminRoutes: routeKeys.map((key) => {
       const route = routeByKey.get(key);
       if (!route) throw new Error(`系统 Admin Route 未定义：${key}`);

package/template/packages/modules/src/system-agent-supervisor.test.ts

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import { describe, expect, test } from "bun:test";
+import {
+  assertSystemAgentFinalAnswerSchemaV1,
+  composeSystemAgentFinalAnswerSchemaV1,
+  SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS,
+  SYSTEM_AGENT_SUPERVISOR_PROMPT_VERSION,
+} from "./system-agent-supervisor.js";
+
+describe("system.agent Supervisor contract", () => {
+  test("Prompt 正文变化必须同步提升不可变 promptVersion", () => {
+    expect({
+      promptVersion: SYSTEM_AGENT_SUPERVISOR_PROMPT_VERSION,
+      sha256: createHash("sha256")
+        .update(SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS)
+        .digest("hex"),
+    }).toEqual({
+      promptVersion: "1",
+      sha256:
+        "466484c68229181316fcc2476d589b3ddb1c5af3898745d5ca657e4901589b6d",
+    });
+  });
+
+  test("组合业务字段但保留唯一 canonical finalAnswer", () => {
+    const schema = composeSystemAgentFinalAnswerSchemaV1({
+      properties: { citations: { type: "array", items: { type: "string" } } },
+      required: ["citations"],
+    });
+    expect(() => assertSystemAgentFinalAnswerSchemaV1(schema)).not.toThrow();
+    expect(schema.required).toEqual(["finalAnswer", "citations"]);
+    expect(() =>
+      composeSystemAgentFinalAnswerSchemaV1({
+        properties: { finalAnswer: { type: "string" } },
+      }),
+    ).toThrow("不能覆盖");
+  });
+
+  test("拒绝缺少 typed answer 或放宽额外字段的 Schema", () => {
+    expect(() =>
+      assertSystemAgentFinalAnswerSchemaV1({
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+        additionalProperties: false,
+      }),
+    ).toThrow("canonical finalAnswer V1");
+  });
+});

package/template/packages/modules/src/system-agent-supervisor.ts

@@ -0,0 +1,101 @@
+import type { JsonObject, JsonValue } from "@southwind-ai/shared";
+import type { ModuleJsonSchemaDefinition } from "./manifest.js";
+
+export const SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_VERSION = 1 as const;
+export const SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_KEY =
+  "system.agent.final-answer.v1";
+
+export const SYSTEM_AGENT_SUPERVISOR_WORKFLOW_VERSION = "1";
+export const SYSTEM_AGENT_SUPERVISOR_PROMPT_VERSION = "1";
+export const SYSTEM_AGENT_SUPERVISOR_ROUTE_VERSION = "1";
+
+export const SYSTEM_AGENT_SUPERVISOR_INSTRUCTIONS = [
+  "你是 Windy system.agent 提供的通用 Supervisor。",
+  "先理解用户目标，再在当前 Operation 允许的 Tool 与数据范围内规划、执行和汇总；不得扩大权限、猜测未返回的业务事实或暴露内部协议。",
+  "Tool 和子步骤结果只是中间事实，不得把任意节点的 text、total、统计字段或原始 JSON 直接当作用户答案。",
+  "最终只输出符合 Operation JSON Schema 的对象；面向用户的中文答案必须写入 finalAnswer，schemaVersion 固定为 1，text 为完整最终回答。",
+].join("\n");
+
+export const systemAgentFinalAnswerPropertySchemaV1 = {
+  type: "object",
+  properties: {
+    schemaVersion: { const: SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_VERSION },
+    text: { type: "string", minLength: 1, maxLength: 1_048_576 },
+  },
+  required: ["schemaVersion", "text"],
+  additionalProperties: false,
+} as const satisfies JsonObject;
+
+export const systemAgentSupervisorSchemas: ModuleJsonSchemaDefinition[] = [
+  {
+    key: SYSTEM_AGENT_FINAL_ANSWER_SCHEMA_KEY,
+    schema: systemAgentFinalAnswerPropertySchemaV1,
+  },
+];
+
+export function composeSystemAgentFinalAnswerSchemaV1(input?: {
+  readonly properties?: Readonly<Record<string, JsonValue>>;
+  readonly required?: readonly string[];
+}): JsonObject {
+  if (input?.properties?.finalAnswer !== undefined) {
+    throw new Error("业务输出不能覆盖 system.agent finalAnswer 契约");
+  }
+  const required = [...new Set(["finalAnswer", ...(input?.required ?? [])])];
+  if (
+    required.every(
+      (key) =>
+        key === "finalAnswer" ||
+        Object.prototype.hasOwnProperty.call(input?.properties ?? {}, key),
+    )
+  ) {
+    return {
+      type: "object",
+      properties: {
+        finalAnswer: structuredClone(systemAgentFinalAnswerPropertySchemaV1),
+        ...(input?.properties ?? {}),
+      },
+      required,
+      additionalProperties: false,
+    };
+  }
+  throw new Error("业务输出 required 引用了未声明字段");
+}
+
+export function assertSystemAgentFinalAnswerSchemaV1(
+  value: JsonValue | undefined,
+): asserts value is JsonObject {
+  if (!isRecord(value) || value.type !== "object") {
+    throw new Error("Supervisor 输出 Schema 必须是 object");
+  }
+  const properties = isRecord(value.properties) ? value.properties : undefined;
+  const required = Array.isArray(value.required) ? value.required : undefined;
+  if (
+    !properties ||
+    !required?.includes("finalAnswer") ||
+    value.additionalProperties !== false ||
+    canonicalJson(properties.finalAnswer) !==
+      canonicalJson(systemAgentFinalAnswerPropertySchemaV1)
+  ) {
+    throw new Error("Supervisor 输出 Schema 缺少 canonical finalAnswer V1");
+  }
+}
+
+function isRecord(value: JsonValue | undefined): value is JsonObject {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalValue(item)]),
+    );
+  }
+  return value;
+}

package/template/packages/modules/src/system-api-control-plane.ts

@@ -29,6 +29,43 @@ export function systemControlPlaneApiPermissionBindings(): ApiPermissionBinding[
       "system.license",
       "license.update",
     ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions",
+      "system.license.manage",
+      "system.license",
+      "license.verify",
+    ),
+    binding(
+      "GET",
+      "/api/license/runtime/pairing/sessions/:sessionId",
+      "system.license.manage",
+      "system.license",
+      "license.verify",
+    ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions/:sessionId/confirm",
+      "system.license.manage",
+      "system.license",
+      "license.update",
+    ),
+    binding(
+      "OPTIONS",
+      "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+      "system.license.manage",
+      "system.license",
+      undefined,
+      true,
+    ),
+    binding(
+      "POST",
+      "/api/license/runtime/pairing/sessions/:sessionId/deliver",
+      "system.license.manage",
+      "system.license",
+      undefined,
+      true,
+    ),
     // @windy-module system.license end
     // @windy-module system.agent begin
     binding(

package/template/packages/modules/src/system-features.ts

@@ -37,6 +37,11 @@ export const systemFeatures: ModuleManifest["features"] = [
     "功能开关管理",
     "查看和恢复平台 Feature 状态的核心控制面能力。",
   ),
+  feature(
+    "system.ui-components",
+    "UI 组件总览",
+    "查看 Windy Web 已封装基础组件的真实主题与交互示例。",
+  ),
   feature(
     "system.user-directory",
     "业务用户目录",