create-windy 0.6.18 → 0.6.20

package/template/apps/web/src/pages/system/components/user-account/UserRoleSelector.webtest.ts

@@ -22,13 +22,38 @@ describe("UserRoleSelector", () => {
           code: "department-manager",
           name: "部门负责人",
           dataScope: "department-and-children",
+          permissionKeys: ["system.user.read", "system.user.manage"],
         },
       ],
       total: 1,
       page: 1,
       pageSize: 100,
     });
-    const wrapper = mount(UserRoleSelector, { props: { modelValue: [] } });
+    const wrapper = mount(UserRoleSelector, {
+      props: {
+        modelValue: [],
+        permissions: [
+          {
+            key: "system.user.read",
+            label: "查看用户",
+            module: "system",
+            moduleLabel: "系统管理",
+            resource: "user",
+            resourceLabel: "用户账号",
+            action: "read",
+          },
+          {
+            key: "system.user.manage",
+            label: "管理用户",
+            module: "system",
+            moduleLabel: "系统管理",
+            resource: "user",
+            resourceLabel: "用户账号",
+            action: "manage",
+          },
+        ],
+      },
+    });
     await flushPromises();
 
     expect(api.list).toHaveBeenCalledWith(
@@ -37,6 +62,10 @@ describe("UserRoleSelector", () => {
     );
     expect(wrapper.text()).toContain("部门负责人");
     expect(wrapper.text()).toContain("本部门及下级");
+    expect(wrapper.text()).toContain("查看 2 项功能权限");
+    await wrapper.get("summary").trigger("click");
+    expect(wrapper.text()).toContain("用户账号");
+    expect(wrapper.text()).toContain("查看用户、管理用户");
     await wrapper.get('[role="checkbox"]').trigger("click");
     expect(wrapper.emitted("update:modelValue")?.at(-1)).toEqual([
       ["role_manager"],

package/template/docs/architecture/agent-runtime-compatibility.md

@@ -0,0 +1,107 @@
+# Remote Agent Runtime 兼容契约
+
+更新时间：2026-09-02。
+
+状态：WAI-1 V1 兼容协商基础已实现。它不开放新的业务 Run 入口，也不代表外部业务系统已经可以
+直接接入生产 Agent Server。
+
+## 目标
+
+Windy 继续只有一套 Agent Runtime。业务系统保留领域治理，中央 Windy Runtime 负责模型执行和
+运行事实，两者通过显式版本化的 Remote Agent Runtime Interface 演进，不能依赖“HTTP 能通”或
+共享源码版本猜测兼容性。
+
+WAI-1 只冻结兼容 Offer 和 Run 创建时的版本 pin：
+
+- Agent Server 通过受认证的 `GET /api/agent/runtime/compatibility` 返回 V1 Offer；
+- Windy Server 选择共同协议版本，并校验 Engine release、协议能力和完整 Offer 摘要；
+- 创建 Run 时用请求头固定所选协议版本和 Offer digest；
+- Agent Server 在写 Store 或执行 Engine 前重新校验两个 pin；
+- 旧 Server 不发送 pin 时，新 Agent Server 保持兼容；新 Server 在 `prefer-v1` 模式下只对旧
+  Agent Server 的明确 `404` 回退，畸形或不兼容 Offer 不降级。
+
+公开 TypeScript 契约位于 `@southwind-ai/server-sdk`。它是 Server Adapter 的 Interface，不进入
+浏览器 Bundle，也不让业务 Module 直接访问 Agent Server。
+
+## 所有权
+
+| 所有者       | 保留职责                                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 外部业务系统 | Manifest、Operation prepare、Feature/RBAC/License/Data Scope、DLP、Artifact 授权、Execution Grant、Tool allowlist、审批、幂等、审计与 Tool Handler |
+| 中央 Windy   | Run 生命周期、Remote execution、Provider/模型路由、canonical SSE/result/cancel、Usage 与可观测事实                                                 |
+| Agent Server | 受控 Model/Tool loop、Run Store、Engine identity、协议 Offer 与 pin 校验；禁止访问业务数据库或 Repository                                          |
+
+中央 Runtime 只接收业务 Host 已治理的输入、ArtifactRef、版本化 Operation Release、Tool schema
+和 opaque Execution Grant。数据库 URL、Repository Adapter、业务 Secret、Actor 自报权限或“已审批”
+标志都不属于此 Interface。
+
+## V1 Offer
+
+Offer 使用以下稳定结构：
+
+```json
+{
+  "schemaVersion": 1,
+  "runtimeKind": "agent",
+  "engineId": "windy.direct.openai-compatible.v1",
+  "protocolVersions": [1],
+  "protocolFeatures": ["canonical-sse-replay.v1", "run-lifecycle.v1"],
+  "toolCallback": {
+    "contractVersion": 1,
+    "authentication": "windy-internal-bearer-v1"
+  },
+  "releaseDigest": "sha256:<engine-and-protocol-digest>",
+  "capabilitiesDigest": "sha256:<features-and-callback-digest>",
+  "offerDigest": "sha256:<complete-offer-digest>"
+}
+```
+
+`protocolFeatures` 描述 Runtime 传输与治理语义，不复用 Operation 的
+`requiredCapabilities`。后者仍表示模型或执行能力，例如 `text-generation`、`vision`。
+
+三个摘要使用稳定字段顺序、排序后的集合和紧凑 JSON 计算：
+
+- `releaseDigest` 绑定 `runtimeKind + engineId + protocolVersions`；
+- `capabilitiesDigest` 绑定 `protocolFeatures + toolCallback`；
+- `offerDigest` 绑定前述全部字段与两个子摘要。
+
+调用方必须重新计算摘要。只修改数组顺序不会改变语义；重复、超界、非法稳定 Key、未知
+`schemaVersion`、无共同协议、能力缺失、callback auth 不匹配或摘要漂移都失败关闭。
+
+## 协商与滚动升级
+
+Windy 项目组合使用 `prefer-v1`：
+
+1. 每次创建 Run 前读取当前 Offer，不缓存跨进程替换后的事实；
+2. Offer 为合法 V1 时发送：
+   - `X-Windy-Agent-Runtime-Protocol: 1`
+   - `X-Windy-Agent-Runtime-Offer-Digest: sha256:...`
+3. 只有兼容端点明确返回 `404` 才按旧协议创建 Run；网络失败、403、5xx、畸形响应和不兼容
+   V1 均拒绝启动；
+4. Agent Server 接受“两个 pin 都缺失”的旧客户端；只有一个 pin、未知版本或 digest 不一致均在
+   Run admission 前拒绝。
+
+供后续外部业务 Host 使用的 Adapter 必须选择 `require-v1`，不能允许 404 legacy fallback。
+Run body 保持原样，避免给 Pydantic `extra=forbid` 的旧 Agent Server 增加字段而破坏滚动升级。
+
+## 当前认证限制
+
+V1 Offer 如实声明 `windy-internal-bearer-v1`。它只适用于同一受控部署内的 Windy Server 与
+Agent Server，仍使用 `AGENT_SERVER_INTERNAL_TOKEN` 保护兼容查询、Run 接口和 Tool callback。
+
+不得把该 token 复制给 Sharp S-Word 或其它业务系统，也不得把当前 callback URL 暴露为跨系统
+公共入口。外部生产接入前必须新增独立受众、短时或可轮换凭据、重放保护和按业务 Host 撤销的
+callback auth profile；届时外部 Adapter 以 `require-v1` 要求新 profile，旧内部 Adapter 继续并行。
+
+## 非目标
+
+WAI-1 不实现：
+
+- LiteLLM 或多 Provider Gateway；
+- 完整 RAG、向量索引或跨系统检索；
+- Sharp S-Word 的 Manifest、Tool、数据或 UI 接线；
+- 远程业务 Host 注册表、租户路由或共享 Copilot UI；
+- callback 认证升级。
+
+这些能力必须在新切片中复用本 Interface，不得新增第二套 Agent Server、Run/Event DTO 或业务数据库
+访问路径。

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

@@ -1,20 +1,13 @@
 # Windy AI Runtime 架构
 
-更新时间：2026-08-27。
-
-状态：架构已确认，文本 Agent、Document AI、批量 Speech/ASR 与受控 Vision Artifact
-切片已实现。当前包含 Module AI Operation
-注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
-Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
-Provider 时仍安全拒绝。真实业务 Run 由 Windy Direct OpenAI-compatible Engine 执行，
-并直接产生 canonical signal。持久 Session/Workflow、LiteLLM 多 Provider 路由和
-PostgreSQL 多副本 Store 尚未实现。Document AI 已提供独立
-Server、授权 ArtifactRef、结构化页级结果、本地/内网 Adapter 契约，以及搜索型 PDF
-等派生文件的受治理 Output Artifact producer 协议；项目 composition 尚未接线，不能
-视为生产可用。Speech 已提供批量转写、归一化、VAD/时间戳契约、稳定分段和结果
-Artifact，但未提供实时 ASR、TTS 或 Dictation。不能据此宣称完整 AI Runtime 已交付。
-Vision 已提供 `agent.vision` 的多图片受控输入、像素限制、逐次发送审计和 JSON Schema
-终态校验；视频帧输入与实时视觉不在当前切片。
+更新时间：2026-09-02。
+
+状态：文本 Agent、Document、Embedding、批量 Speech/ASR、受控 Vision Artifact、PostgreSQL
+Run Store、持久 Session/Memory 与 Workflow/委派切片均已实现。WAI-1 已为 Windy Server 到
+Agent Server 增加 additive 的 V1 兼容 Offer、release/capability digest 和 Run 创建 pin；详见
+[Remote Agent Runtime 兼容契约](./agent-runtime-compatibility.md)。当前 Provider 仍是单一 Direct
+OpenAI-compatible Adapter；LiteLLM 多 Provider 路由、完整 RAG、外部业务 Host callback 认证与
+Sharp S-Word 接线均未实现。未配置任一可选 Runtime 时继续安全拒绝对应 Operation，不阻止普通业务。
 
 ## 目标
 

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

@@ -18,6 +18,11 @@ POST /api/agent/runs/:runId/cancel
 创建 Run 必须携带幂等键；SSE 支持 cursor 重放和 heartbeat。Engine 切换不改变 Run DTO、
 canonical Event、唯一终态、取消或 Tool 授权语义。
 
+Windy Server 与 Agent Server 之间已经提供 additive 的 V1 兼容 Offer、release/capability digest
+和 Run 创建请求头 pin。当前同部署 Adapter 使用滚动兼容的 `prefer-v1`；任何外部业务 Host Adapter
+必须使用 `require-v1`，且在独立 callback 认证 profile 落地前不得投入生产。完整职责与失败语义见
+[Remote Agent Runtime 兼容契约](../architecture/agent-runtime-compatibility.md)。
+
 ## 能力与治理边界
 
 Direct Engine 已覆盖：

package/template/packages/server-sdk/contracts/agent-runtime-compatibility/v1/offer.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": 1,
+  "runtimeKind": "agent",
+  "engineId": "windy.direct.openai-compatible.v1",
+  "protocolVersions": [1],
+  "protocolFeatures": [
+    "canonical-sse-replay.v1",
+    "execution-grant-forwarding.v1",
+    "operation-release-attestation.v1",
+    "run-cancel.v1",
+    "run-lifecycle.v1",
+    "runtime-reporting.v1",
+    "tool-callback.v1"
+  ],
+  "toolCallback": {
+    "contractVersion": 1,
+    "authentication": "windy-internal-bearer-v1"
+  },
+  "releaseDigest": "sha256:410c49040a4e4de40dd2fed60877b2b08e9bbcb23198f10a7cbb3cf7d1135ce0",
+  "capabilitiesDigest": "sha256:bcdd3822f9077ac6d1cd42f8a53dbdb46d9a5bc908821e92bd6fb28e2ec6ab65",
+  "offerDigest": "sha256:1375cd3a1511f2d5fdde3cac123d9d6bc603f80ad746758508d0a3da67ed8fad"
+}

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

@@ -1,4 +1,23 @@
 export type { ModuleActor } from "./src/actor.js";
+export {
+  AGENT_RUNTIME_COMPATIBILITY_PATH_V1,
+  AGENT_RUNTIME_COMPATIBILITY_SCHEMA_VERSION,
+  AGENT_RUNTIME_INTERNAL_CALLBACK_AUTH_V1,
+  AGENT_RUNTIME_KIND_V1,
+  AGENT_RUNTIME_OFFER_DIGEST_HEADER_V1,
+  AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+  AGENT_RUNTIME_PROTOCOL_HEADER_V1,
+  AGENT_RUNTIME_PROTOCOL_VERSION_V1,
+  AGENT_RUNTIME_TOOL_CALLBACK_CONTRACT_VERSION_V1,
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+  parseAgentRuntimeCompatibilityOfferV1,
+  type AgentRuntimeCompatibilityDigestV1,
+  type AgentRuntimeCompatibilityNegotiationV1,
+  type AgentRuntimeCompatibilityOfferV1,
+  type AgentRuntimeCompatibilityRequirementsV1,
+} from "./src/agent-runtime-compatibility.js";
 export { pageAgentClientRunCapability } from "./src/client-agent-session.js";
 export type {
   ModuleClientAgentHostAuthAdapter,

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

@@ -26,6 +26,7 @@
     "src/ai-runtime-readiness-validation.ts",
     "src/ai-runtime-readiness-validation-values.ts",
     "src/ai-runtime-readiness-values.ts",
+    "src/agent-runtime-compatibility.ts",
     "src/agent-session-memory-port.ts",
     "src/agent-session-provider.ts",
     "src/agent-source-invalidation-port.ts",
@@ -71,6 +72,7 @@
   },
   "exports": {
     ".": "./index.ts",
+    "./contracts/agent-runtime-compatibility/v1/*": "./contracts/agent-runtime-compatibility/v1/*",
     "./contracts/ai-runtime-readiness/v1/*": "./contracts/ai-runtime-readiness/v1/*"
   },
   "publishConfig": {

package/template/packages/server-sdk/src/agent-runtime-compatibility.contract.test.ts

@@ -0,0 +1,143 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, test } from "bun:test";
+import {
+  AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+  type AgentRuntimeCompatibilityOfferV1,
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+  parseAgentRuntimeCompatibilityOfferV1,
+} from "./agent-runtime-compatibility.js";
+
+const fixture = await loadFixture();
+
+describe("Remote Agent Runtime compatibility V1", () => {
+  test("公共 builder 与跨语言 fixture 字节语义一致", () => {
+    expect(
+      createAgentRuntimeCompatibilityOfferV1(
+        "windy.direct.openai-compatible.v1",
+      ),
+    ).toEqual(fixture);
+    expect(parseAgentRuntimeCompatibilityOfferV1(fixture)).toEqual(fixture);
+  });
+
+  test("协商最高共同版本并要求完整协议能力与 callback 认证", () => {
+    const result = negotiateAgentRuntimeCompatibilityV1(
+      fixture,
+      localAgentRuntimeCompatibilityRequirementsV1(),
+    );
+
+    expect(result).toEqual({ ok: true, protocolVersion: 1, offer: fixture });
+  });
+
+  test("未知 schema、缺失能力和 callback 认证漂移均失败关闭", () => {
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(
+        { ...fixture, schemaVersion: 2 },
+        localAgentRuntimeCompatibilityRequirementsV1(),
+      ),
+    ).toEqual({ ok: false, code: "CONTRACT_UNSUPPORTED" });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        requiredProtocolFeatures: [
+          ...AGENT_RUNTIME_PROTOCOL_FEATURES_V1,
+          "future-required.v1",
+        ],
+      }),
+    ).toEqual({
+      ok: false,
+      code: "CAPABILITY_MISSING",
+      subject: "future-required.v1",
+    });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        requiredToolCallbackAuthentication: "signed-callback-v1",
+      }),
+    ).toEqual({
+      ok: false,
+      code: "CALLBACK_AUTH_UNSUPPORTED",
+      subject: "signed-callback-v1",
+    });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        protocolVersions: [2],
+      }),
+    ).toEqual({ ok: false, code: "CONTRACT_UNSUPPORTED" });
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(fixture, {
+        ...localAgentRuntimeCompatibilityRequirementsV1(),
+        expectedReleaseDigest: `sha256:${"0".repeat(64)}`,
+      }),
+    ).toEqual({ ok: false, code: "RELEASE_DIGEST_MISMATCH" });
+  });
+
+  test("任一受摘要保护字段漂移都不能沿用旧 Offer", () => {
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolFeatures: [...fixture.protocolFeatures, "tampered.v1"],
+      }),
+    ).toBeNull();
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        engineId: "windy.other-engine.v1",
+      }),
+    ).toBeNull();
+  });
+
+  test("重复或超界集合与非稳定 identity 被拒绝", () => {
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolVersions: [1, 1],
+      }),
+    ).toBeNull();
+    expect(
+      parseAgentRuntimeCompatibilityOfferV1({
+        ...fixture,
+        protocolFeatures: Array.from(
+          { length: 65 },
+          (_, index) => `feature-${index}.v1`,
+        ),
+      }),
+    ).toBeNull();
+    expect(() =>
+      createAgentRuntimeCompatibilityOfferV1("https://provider.invalid"),
+    ).toThrow("engineId invalid");
+  });
+
+  test("恶意 getter 或循环对象只形成安全的契约拒绝", () => {
+    const throwing = Object.defineProperty({}, "schemaVersion", {
+      get() {
+        throw new Error("secret getter body");
+      },
+    });
+    const cyclic: Record<string, unknown> = { ...fixture };
+    cyclic.toolCallback = cyclic;
+
+    expect(parseAgentRuntimeCompatibilityOfferV1(throwing)).toBeNull();
+    expect(parseAgentRuntimeCompatibilityOfferV1(cyclic)).toBeNull();
+    expect(
+      negotiateAgentRuntimeCompatibilityV1(
+        throwing,
+        localAgentRuntimeCompatibilityRequirementsV1(),
+      ),
+    ).toEqual({ ok: false, code: "CONTRACT_INVALID" });
+  });
+});
+
+async function loadFixture(): Promise<AgentRuntimeCompatibilityOfferV1> {
+  return JSON.parse(
+    await readFile(
+      new URL(
+        "../contracts/agent-runtime-compatibility/v1/offer.json",
+        import.meta.url,
+      ),
+      "utf8",
+    ),
+  ) as AgentRuntimeCompatibilityOfferV1;
+}

package/template/packages/server-sdk/src/agent-runtime-compatibility.public-api.test.ts

@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test";
+import {
+  createAgentRuntimeCompatibilityOfferV1,
+  localAgentRuntimeCompatibilityRequirementsV1,
+  negotiateAgentRuntimeCompatibilityV1,
+} from "../index.js";
+
+test("@southwind-ai/server-sdk 根入口公开 Remote Agent Runtime V1 协商", () => {
+  const offer = createAgentRuntimeCompatibilityOfferV1(
+    "windy.direct.openai-compatible.v1",
+  );
+
+  expect(
+    negotiateAgentRuntimeCompatibilityV1(
+      offer,
+      localAgentRuntimeCompatibilityRequirementsV1(),
+    ),
+  ).toMatchObject({ ok: true, protocolVersion: 1 });
+});