create-windy 0.6.7 → 0.6.9

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

@@ -1,4 +1,4 @@
-# Southwind AI Runtime 架构
+# Windy AI Runtime 架构
 
 更新时间：2026-07-31。
 
@@ -18,7 +18,7 @@ Vision 已提供 `agent.vision` 的多图片受控输入、像素限制、逐次
 
 ## 目标
 
-Southwind AI 为生成项目提供可选的 AI Runtime。它统一治理模型 Deployment、业务 Operation、Feature Flag、RBAC Permission、License、Audit、Secret、用量和离线部署，但不自行重做通用 Agent Framework、LLM Router、OCR 引擎或语音模型。
+Windy 为生成项目提供可选的 AI Runtime。它统一治理模型 Deployment、业务 Operation、Feature Flag、RBAC Permission、License、Audit、Secret、用量和离线部署，但不自行重做通用 Agent Framework、LLM Router、OCR 引擎或语音模型。
 
 首期目标：
 
@@ -34,14 +34,14 @@ Southwind AI 为生成项目提供可选的 AI Runtime。它统一治理模型 D
 
 ## 核心决策
 
-1. Agent Runtime 是 Southwind AI 的官方可选底座能力，不是每个业务 Module 自行实现的功能。
+1. Agent Runtime 是 Windy 的官方可选底座能力，不是每个业务 Module 自行实现的功能。
 2. Agent Server 独立部署，首期使用 Python ADK；ADK 只属于内部 Implementation。
 3. 首个文本切片由 Agent Server 内置 OpenAI-compatible Adapter；需要多 Provider
    路由、fallback 与集中限流时，再引入独立自托管 LiteLLM Proxy。
 4. OCR 和文档解析由独立 Document AI Server 执行，不放入 Agent Server 或 LiteLLM。
 5. ASR、TTS 和 AI Dictation 由独立 Speech Server 执行；实时 Agent 会话由 Agent Server 编排。
 6. 文本 LLM、VLM 和 Agent 输出使用 SSE；实时音频/视频需要双向传输，使用 WebSocket。
-7. Southwind AI Server 是身份、Feature、Permission、License、数据范围、Tool 授权和 Audit 的事实源。
+7. Windy Server 是身份、Feature、Permission、License、数据范围、Tool 授权和 Audit 的事实源。
 8. 所有业务文件通过 `ArtifactRef` 传递，不在跨服务 DTO 中携带大型 Base64 文件或本地绝对路径。
 
 ## 总体拓扑
@@ -51,7 +51,7 @@ Southwind AI 为生成项目提供可选的 AI Runtime。它统一治理模型 D
         │
         │ AgentOperation / DocumentOperation / SpeechOperation
         ▼
-Southwind AI Server
+Windy Server
         ├── Feature / RBAC / License / Audit / Data Scope
         ├── AI Deployment Registry
         ├── Agent Tool Host
@@ -81,7 +81,7 @@ Southwind AI Server
 
 ## Module 与部署职责
 
-### Southwind AI Server
+### Windy Server
 
 拥有：
 
@@ -109,12 +109,12 @@ Southwind AI Server
 - ADK Runner、Workflow、Session、Checkpoint、Eval；
 - Agent、Workflow 和 Prompt Release；
 - Run 生命周期、取消、恢复和 canonical event；
-- ADK Event 到 Southwind AI Event 的转换；
+- ADK Event 到 Windy Event 的转换；
 - Agent Step、Prompt Version、Tool Call 和模型 attempt 的关联；
 - 开发环境 ADK Web；
 - 实时 Agent 会话编排。
 
-Agent Server 不直接访问业务 Repository。模型产生 Tool Call 只表示执行意图；每次真实 Tool 执行都必须回到 Southwind AI Tool Host，重新检查当前 Feature、License、Permission 和数据范围。
+Agent Server 不直接访问业务 Repository。模型产生 Tool Call 只表示执行意图；每次真实 Tool 执行都必须回到 Windy Tool Host，重新检查当前 Feature、License、Permission 和数据范围。
 
 ### LiteLLM Proxy
 
@@ -187,7 +187,7 @@ credential 删除 scope，缺少 credential 时如实保留 Host TTL cleanup pen
 Document、Speech 与 Embedding Interface 已分别由 `./document`、`./speech`、
 `./embedding` 子路径交付。
 
-npm Module 数量与部署进程数量是两个不同维度。Southwind Server、Agent Server、
+npm Module 数量与部署进程数量是两个不同维度。Windy Server、Agent Server、
 Document AI Server 和 Speech Server 仍独立部署：它们具有不同的协议、资源和故障域；
 业务侧则只学习一个稳定入口。`ai-client` 内部通过 Agent、Document、Speech Adapter
 隔离远端 Implementation，不能把 ADK、LiteLLM、PaddleOCR 或 Provider SDK 类型暴露给业务。
@@ -379,7 +379,7 @@ Endpoint 配置属于高风险管理动作，必须具备独立 Permission 和
 
 SSE 是单向 Server-to-Client 协议。创建、取消、审批、恢复和 Tool continuation 使用独立 HTTP command，不在 SSE 连接中反向发送。
 
-Southwind AI Server 与 Agent Server 之间使用本节定义的 canonical SSE；Agent Server 调用 LiteLLM 的文本 LLM/VLM 时使用 OpenAI-compatible SSE streaming。Provider 专有流协议在 LiteLLM Adapter 内终止，不能越过该 Seam。VLM 的图片或视频作为请求 Artifact 发送，模型的文本与结构化响应仍通过 SSE 返回。
+Windy Server 与 Agent Server 之间使用本节定义的 canonical SSE；Agent Server 调用 LiteLLM 的文本 LLM/VLM 时使用 OpenAI-compatible SSE streaming。Provider 专有流协议在 LiteLLM Adapter 内终止，不能越过该 Seam。VLM 的图片或视频作为请求 Artifact 发送，模型的文本与结构化响应仍通过 SSE 返回。
 
 实时语音和视频需要客户端与服务端同时发送媒体帧，因此使用 WebSocket，不属于本节 SSE 约束。
 
@@ -663,7 +663,7 @@ type DictationEvent =
 - 级联：ASR → ADK Agent/LLM → TTS；
 - 原生双向模型：音频/视频 ⇄ Realtime Model。
 
-客户端先向 Southwind AI Server 创建 Live Session 并通过 Guard，再使用短时、绑定 Session 和 audience 的凭证连接 Agent Server WebSocket。Tool Call 仍回到 Southwind AI Tool Host 二次授权。
+客户端先向 Windy Server 创建 Live Session 并通过 Guard，再使用短时、绑定 Session 和 audience 的凭证连接 Agent Server WebSocket。Tool Call 仍回到 Windy Tool Host 二次授权。
 
 首期不新增独立 Realtime Server。连接规模、电话线路、WebRTC 或媒体转码成为真实需求后，再把媒体数据面拆出。
 
@@ -703,7 +703,7 @@ published version 不可原地修改。每次 Run 固定：
 
 首期优先使用代码或 YAML、Git、Eval 和不可变 Release。只有出现非开发人员在线编辑的真实需求后，再扩展 diff、审批、回滚、fixture、route 对比和发布管理。
 
-生产 Trace 优先输出到客户本地 OTel Collector 与 Jaeger/Tempo。Southwind AI 控制面提供脱敏 Run 摘要和受权限保护的 Trace 入口，不复制 ADK Web。
+生产 Trace 优先输出到客户本地 OTel Collector 与 Jaeger/Tempo。Windy 控制面提供脱敏 Run 摘要和受权限保护的 Trace 入口，不复制 ADK Web。
 
 生产默认不持久化完整 Prompt、响应、音频、图片或 Tool 参数。明文诊断需要专门 Feature、Permission、加密、脱敏、TTL 和访问审计。
 
@@ -720,12 +720,12 @@ published version 不可原地修改。每次 Run 固定：
 | TTS  | 输入字符数、输出音频秒数、GPU 时间                    |
 | Live | Session 时长、输入/输出音频秒数、LLM token、Tool 次数 |
 
-每条事实标记 `provider-reported`、`estimated` 或 `unknown`；缺失不能记为零。成本绑定调用时的价格快照。LiteLLM 保存 Provider/Deployment 原始事实，Agent Server 保存 Run/Step 归属，Document AI 和 Speech Server 保存各自模态事实，Southwind AI 通过共享 invocation ID 汇总展示。
+每条事实标记 `provider-reported`、`estimated` 或 `unknown`；缺失不能记为零。成本绑定调用时的价格快照。LiteLLM 保存 Provider/Deployment 原始事实，Agent Server 保存 Run/Step 归属，Document AI 和 Speech Server 保存各自模态事实，Windy 通过共享 invocation ID 汇总展示。
 
 ## 安全与授权
 
 - 浏览器和普通业务前端不能直接使用 LiteLLM master key；
-- Southwind AI Server 在发起 Run 前执行 License → Feature → Permission Guard；
+- Windy Server 在发起 Run 前执行 License → Feature → Permission Guard；
 - Remote Runtime 只接受短时、限 audience、限 Operation、绑定 actor、run 和 expiry 的 Execution Grant；
 - Grant 不能携带长期有效的 Permission 列表作为授权事实；
 - Tool 执行、人工批准后的继续和后台重试都重新读取当前授权；
@@ -797,7 +797,7 @@ fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交
 - 文本 LLM、VLM 和 Agent 输出统一通过 canonical SSE；
 - SSE 断线后使用 cursor 恢复，不重新执行模型调用；
 - Feature、Permission、License 任一拒绝都会 fail-closed；
-- 模型 Tool Call 不能绕过 Southwind AI Tool Host；
+- 模型 Tool Call 不能绕过 Windy Tool Host；
 - 同一 Run 能关联 Audit、ADK Trace、LiteLLM attempt 和 Usage；
 - 本地/内网模型可配置协议、主机、端口和 Base Path；
 - 完全断网环境仍可运行已配置的本地 LLM、OCR 和 Speech Operation；

package/template/docs/architecture/module-secret-resolution.md

@@ -221,14 +221,14 @@ Resolver 不会被调用。
 泄漏，但不能识别回调返回的其它未知凭据，也不能把故意通过网络或其它副作用发送凭据的
 恶意模块变成安全代码。这些边界必须继续通过代码审查、模块来源治理和网络策略控制。
 
-## 利剑 SMB / SFTP 接入
+## SMB / SFTP 业务模块接入示例
 
-利剑升级到包含该契约的 Windy 版本后，按以下方式接入，不需要修改 Windy 的配置
+业务项目升级到包含该契约的 Windy 版本后，按以下方式接入，不需要修改 Windy 的配置
 Registry 或 Agent Tool Runtime：
 
-1. 在拥有 SMB/SFTP 同步能力的利剑 Module Manifest 分别声明 password/private-key
+1. 在拥有 SMB/SFTP 同步能力的业务 Module Manifest 分别声明 password/private-key
    handle、稳定 connection/purpose，以及同基础 Key Feature、Permission 和审计动作；
-2. 在利剑 project-owned `server-composition.ts` 为每个声明添加
+2. 在项目的 project-owned `server-composition.ts` 为每个声明添加
    SDK 根导出的 `createModuleSecretBinding()`，生产 Resolver 指向客户批准的 Secret
    Store；
 3. Route/Service 在一次连接操作内使用

package/template/docs/architecture/report-staging.md

@@ -148,7 +148,7 @@ Starter 会同时裁剪 helper 源码、编译步骤和依赖。非官方镜像
 需要自行提供同一 helper；缺失或 RAR5 真实读取失败会返回
 `REPORT_STAGING_UNSUPPORTED_ARCHIVE`，不会回退旧 `bsdtar -x` 或其他外部命令。
 
-相较老 DSP/原先 `bsdtar` 直接解压，当前实现保留已由真实 probe 验证的 RAR5 streaming
+相较旧的外部命令直解压方案，当前实现保留已由真实 probe 验证的 RAR5 streaming
 reader，但把落盘所有权和逐 write 配额检查收回 Host，并用可严格解析的 framing 取代
 人类可读 listing。V1 callback 刻意不提供 seek/reopen；需要随机 seek 的 RAR4、ZIP 或
 其他格式会 fail closed，当前不承诺与通用 `archive_read_open_filenames` 格式等价。

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/custom-login-page.md

@@ -30,13 +30,13 @@ export const loginPageComponent = defineLoginPageComponent(PlatformLoginPage);
 ## 完整业务页面
 
 将业务页面放在同一个 project-owned 目录，例如
-`apps/web/src/app/auth/SharpSwordLoginPage.vue`，然后只修改 selector：
+`apps/web/src/app/auth/ProjectLoginPage.vue`，然后只修改 selector：
 
 ```ts
-import SharpSwordLoginPage from "./SharpSwordLoginPage.vue";
+import ProjectLoginPage from "./ProjectLoginPage.vue";
 import { defineLoginPageComponent } from "@/pages/auth/login-page-extension";
 
-export const loginPageComponent = defineLoginPageComponent(SharpSwordLoginPage);
+export const loginPageComponent = defineLoginPageComponent(ProjectLoginPage);
 ```
 
 业务 SFC 使用 Vue 3 Composition API 和 TypeScript。认证提交必须复用

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-offline-activation-code.md

@@ -50,8 +50,8 @@ W1 是同一份 `SignedLicenseV1` 的离线传输编码，用于客户电脑没
 
 下表由当前固定 V1 测试向量测得。`完整编码字符`包含 `W1`、段分隔连字符和校验字符；Base32 本身不包含易混的 `I/L/O/U`。V1 现在只携带单一 License 版本标记，不再包含数量可变的能力列表。
 
-| 样本                         | canonical JSON 字节 | 段数 | 完整编码字符 |
-| ---------------------------- | ------------------: | ---: | -----------: |
+| 样本                     | canonical JSON 字节 | 段数 | 完整编码字符 |
+| ------------------------ | ------------------: | ---: | -----------: |
 | 仓库固定 V1 版本标记向量 |                 673 |   20 |          519 |
 
 因此 W1 仍然只是无 U 盘、无摄像头时的兜底入口，不能承诺 150～300 字符。仅 64 字节 ED25519 签名转为 Base32 就需要约 103 个数据字符，V1 还签入客户、项目、合同、设备、时间、公钥 ID 和 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.8.tmp
+sudo chmod 0555 /opt/windy/runtime/delivery-0.6.8.tmp/bin/windy-delivery
+sudo mv /opt/windy/runtime/delivery-0.6.8.tmp \
+  /opt/windy/runtime/delivery-0.6.8
+sudo ln -s /opt/windy/runtime/delivery-0.6.8/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.8`，最低支持基线 `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-runtime.md

@@ -3,7 +3,7 @@
 更新时间：2026-07-26。
 
 Windy 的 Agent Runtime 是可选平台能力。业务模块声明稳定的 AI Operation 和允许调用的
-Tool；Southwind AI Server 负责身份、Feature、Permission、License、Scope、Execution
+Tool；Windy Server 负责身份、Feature、Permission、License、Scope、Execution
 Grant 与审计；独立 Agent Server 只负责模型循环、canonical event 和受限 Tool Host
 回调。业务模块不选择 Provider、模型、Endpoint 或凭据。
 
@@ -94,7 +94,7 @@ host.registerAiOperationHandlers([
 放进返回值。`prepare` 只负责把已经过宿主 Guard 的类型化输入转成指令和用户消息。
 
 Tool handler 仍通过 `registerToolHandlers` 注册。模型提出 Tool Call 后，Agent Server
-携带短时 opaque grant 回调 Southwind AI Server；受限 Tool Host 会验证：
+携带短时 opaque grant 回调 Windy Server；受限 Tool Host 会验证：
 
 1. grant 是否绑定当前 Run、Operation、Actor 且未过期；
 2. Tool 是否属于 Operation 的 `allowedToolKeys`；
@@ -106,7 +106,7 @@ Tool 请求不能携带权限列表、License、Scope 或“已授权”标志
 
 ## 跨进程 Limits 契约
 
-Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Southwind AI Server
+Manifest 的 Operation limits 同时包含输入、执行时间和输出上限。Windy Server
 在调用远端 Agent Server 前先执行文本输入与 Artifact 声明的 `maxInputBytes` 校验；
 跨进程请求逐字段发送 Agent Server 需要再次执行的时长、输入、输出、图片数量与像素
 上限。禁止通过展开 Manifest 对象透传 limits：TypeScript 的结构类型不会在运行时
@@ -293,7 +293,7 @@ Operation 契约。
 
 ## 客户端协议
 
-浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Southwind AI Server：
+浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Windy Server：
 
 ```text
 POST /api/agent/runs

package/template/docs/platform/document-ai-runtime.md

@@ -4,7 +4,7 @@
 
 Windy 的 Document AI 是可选的独立故障域。业务模块声明稳定的
 `kind=document` Operation，并先把当前 Actor 有权读取的业务资源换成短时
-`ArtifactRef`；Southwind Server 完成 Feature、RBAC、License、数据范围、业务对象绑定
+`ArtifactRef`；Windy Server 完成 Feature、RBAC、License、数据范围、业务对象绑定
 和审计后，才把任务交给 Document Server。未安装或未配置 Document Server 时，对应
 Operation 稳定返回 `CAPABILITY_UNAVAILABLE`，普通业务和文本 Agent 仍可启动。
 
@@ -103,7 +103,7 @@ Repository 证明当前 Actor 可访问真实资源并绑定该文件时才会
 
 ## HTTP 与事件协议
 
-浏览器通过同源 Southwind Server 调用：
+浏览器通过同源 Windy Server 调用：
 
 ```text
 POST /api/document/runs
@@ -131,7 +131,7 @@ fail closed；Adapter 的单源 multipart 字段为 `file`，多源字段为重
 
 ### Output Artifact 握手
 
-Output Sink 启用时，Southwind Host 在调用 Runtime 前冻结：
+Output Sink 启用时，Windy Host 在调用 Runtime 前冻结：
 
 - 预分配的 `runId`；
 - 不含 credential 的 Sink Descriptor，包括 scope、output kind、部署/Release/Offer/

package/template/docs/platform/speech-ai-runtime.md

@@ -16,7 +16,7 @@ Agent 启动。
    Repository 回查 `resourceId`、`fileId` 与当前 Actor 的真实关系。
 2. 模块路由调用 `context.aiArtifacts.issue(...)` 换取加密、短时、opaque
    `ArtifactRef`。
-3. `@southwind-ai/ai-client/speech` 只把 Artifact 与领域选项提交到同源 Southwind
+3. `@southwind-ai/ai-client/speech` 只把 Artifact 与领域选项提交到同源 Windy
    Server。
 4. Server 重新检查 Feature、Permission、License、数据范围、能力摘要和 Artifact
    元数据，并按 Actor + Operation 作用域化幂等键。

package/template/docs/platform/vision-ai-runtime.md

@@ -12,7 +12,7 @@ Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的
 
 - 浏览器和业务模块只提交平台签发的 opaque `ArtifactRef`，不能提交 URL、Base64、
   BlobStore Key、宿主路径、模型名或 Provider Endpoint。
-- Southwind Server 在 Feature、Permission、License、数据范围通过后重新打开资源，
+- Windy Server 在 Feature、Permission、License、数据范围通过后重新打开资源，
   校验 MIME、字节数与 SHA-256，再为 Agent Server 轮换短时引用。
 - Agent Server 只从固定 `AI_ARTIFACT_URL` 内网入口读取图片，拒绝调用方 URL。
 - 只接受 JPEG、PNG、WebP；解码后强制检查图片数量、总字节与单图像素。

package/template/docs/product/built-in-roles.md

@@ -21,6 +21,14 @@ Starter 首次安装提供四个稳定角色。角色 ID 和 code 是升级契
 
 ## 安全边界
 
-当前 `dataScope` 和 `departmentIds` 已持久化，但 Repository 查询级的数据范围 Guard 仍是产品缺口。为避免默认角色越权写入，部门负责人基线暂不授予 `system.user.manage` 或 `system.department.manage`。在部门及下级查询约束和越权测试完成前，不应通过 seed 扩大该角色的写权限；管理员仍可按部署需求显式配置自定义角色。
+`dataScope` 和 `departmentIds` 已持久化，用户、示例工单、Agent Tool、导出与受支持的
+后台路径已经接入 Repository 级查询范围强制。列表、总数、详情、更新和删除把同一 scope
+predicate 下推到查询，缺少 nominal `ScopeContext` 或 ownership 绑定时 fail closed；完整
+边界见[Repository 级 Data Scope 强制](../architecture/data-scope-query-enforcement.md)。新增
+Repository 或异步资源仍必须显式登记 `dataAccess`，不能因已有基础设施而默认视为已覆盖。
+
+部门负责人基线继续不授予 `system.user.manage` 或 `system.department.manage`。这是最小
+权限的产品默认值，不是用前端隐藏替代服务端 Guard；管理员可按部署需求显式配置自定义
+角色，最终仍受 Feature、Permission 和 Repository scope 共同约束。
 
 用户敏感字段策略将 `system.user.read`、`system.user.reveal` 和 `system.user.export` 分为三类能力。普通读取只能取得服务端脱敏结果；明文查看与治理导出即使由超级管理员执行，也必须重新授权并写入关键审计。客户端提交的角色 code、权限数组或展示模式不是授权来源。

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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

@@ -2,7 +2,7 @@ import type { AdminUiManifest } from "./admin-ui-manifest.js";
 import { systemAdminRoutes } from "./system-admin-routes.js";
 
 const definitions = [
-  ["system", ["system.feature"]],
+  ["system", ["system.feature", "system.ui-components"]],
   [
     "system.identity",
     [

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",
     "业务用户目录",

package/template/packages/modules/src/system-module-catalog.ts

@@ -21,12 +21,13 @@ export const systemModuleDefinitions = [
     version: "0.1.0",
     label: "系统核心",
     description: "管理面准入、Feature 治理、数据库基线与审计动作目录。",
-    resources: ["admin", "runtime", "auth", "feature"],
+    resources: ["admin", "runtime", "auth", "feature", "ui-components"],
     featureKeys: [
       "system.admin",
       "system.runtime",
       "system.auth",
       "system.feature",
+      "system.ui-components",
       "system.ruoyi-compat",
     ],
   },

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

@@ -169,6 +169,17 @@ export function systemFoundationModule(): ModuleManifest {
             featureKey: "system.config",
           },
           // @windy-module system.configuration end
+          {
+            key: "system.ui-components",
+            title: "组件总览",
+            type: "menu",
+            order: 70,
+            visible: true,
+            path: "/ui/component",
+            icon: "blocks",
+            permissionKey: "system.ui-components.read",
+            featureKey: "system.ui-components",
+          },
         ],
       },
       {

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

@@ -11,6 +11,7 @@ const systemResourceLabels = {
   menu: "菜单管理",
   dict: "字典管理",
   feature: "功能开关",
+  "ui-components": "UI 组件总览",
   search: "全局搜索",
   settings: "全局设置",
   config: "配置版本",
@@ -96,6 +97,7 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   permission("dict", "manage"),
   permission("feature", "read"),
   permission("feature", "manage"),
+  permission("ui-components", "read"),
   // @windy-module system.search begin
   permission("search", "read"),
   permission("search", "manage"),

package/template/packages/modules/src/system-ui-components.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { systemFoundationModule } from "./system-modules.js";
+
+describe("系统组件展厅能力注册", () => {
+  test("以同一能力 Key 注册 Feature、Permission、菜单和路由", () => {
+    const manifest = systemFoundationModule();
+    const menus = flattenMenus(manifest.menus);
+
+    expect(manifest.features).toContainEqual(
+      expect.objectContaining({ key: "system.ui-components" }),
+    );
+    expect(manifest.permissions).toContainEqual(
+      expect.objectContaining({ key: "system.ui-components.read" }),
+    );
+    expect(
+      menus.find(({ key }) => key === "system.ui-components"),
+    ).toMatchObject({
+      path: "/ui/component",
+      permissionKey: "system.ui-components.read",
+      featureKey: "system.ui-components",
+    });
+    expect(
+      manifest.adminRoutes.find(({ key }) => key === "system.ui-components"),
+    ).toMatchObject({
+      path: "/ui/component",
+      permissionKey: "system.ui-components.read",
+      featureKey: "system.ui-components",
+    });
+  });
+});
+
+function flattenMenus(
+  menus: ReturnType<typeof systemFoundationModule>["menus"],
+): ReturnType<typeof systemFoundationModule>["menus"] {
+  return menus.flatMap((menu) => [menu, ...flattenMenus(menu.children || [])]);
+}