create-windy 0.9.1 → 0.10.1

package/template/docs/architecture/durable-jobs.md

@@ -153,12 +153,16 @@ Lease 或 timeout sweep 会终结旧 attempt 并写 Failure；只有 `currentAtt
 
 这是一条渐进迁移边界：新业务应直接注册 durable handler，不再新增另一套 `running` 状态机；Scheduler/Bulk Adapter 只服务现有接口兼容。
 
+<!-- @windy-module system.workflow begin -->
+
 ## 审批超时接入
 
 最小审批注册稳定 handler `system.workflow.timeout` 和独立 queue。创建审批时以 WorkItem ID 作为提交幂等键，把 Job 的 `availableAt` 固定为审批 `dueAt`；payload 只保存 WorkItem ID。handler 到期后重新读取当前 WorkItem 与版本，只有 `pending` 或 `claimed` 才执行服务账号专用的 `timeout` 命令，已终结任务重复执行为空操作。
 
 启动与每次派发前会分页扫描尚未终结的审批并幂等补交 Job，用于覆盖“审批事实已提交、进程在 durable submit 前退出”的短窗口。调度器只负责唤醒派发，真实任务、可用时间、重试和执行结果都在 Durable Job 表中；新实例重建 Repository、Registry 和 Worker 后可以继续领取，不依赖旧进程 timer 或闭包。完整审批边界见[最小审批工作流](./minimal-approval-workflow.md)。
 
+<!-- @windy-module system.workflow end -->
+
 ## 运维与验证
 
 事实模型、执行恢复与兼容关联分别使用 `0023_fresh_thunderbolt_ross.sql`、
@@ -182,3 +186,16 @@ PostgreSQL Repository 集成测试通过 `JOBS_TEST_DATABASE_URL` 启用，覆
 - token 原文只允许短暂存在于 worker 进程，持久化层保存 SHA-256；数据库泄露不能直接伪造心跳或完成请求。
 - 自动重试有界，但人工恢复可产生新的 attempt；每次人工恢复都需要理由和幂等请求号，由运维/RBAC/审计入口在接入层约束。
 - 当前使用 PostgreSQL 作为 durable runtime 的并发真相。其它数据库必须实现同等 claim/lease 语义后才能声明兼容。
+
+## 租约快照索引
+
+快照按 `job_id` 读取全部历史租约，并按 `acquired_at` 排序。迁移
+`0065_durable_job_lease_snapshot_lookup` 增加 `(job_id, acquired_at)` 索引。
+阶段活跃租约唯一约束、到期索引、历史状态和 fencing 契约继续由现有逻辑维护。
+生成项目未选择 `system.scheduler` 时，模板裁剪会随租约表移除该索引 DDL。
+
+在隔离的 PostgreSQL 18.3 实例中，使用平台租约表 DDL 和 20 万条合成租约，
+执行 `EXPLAIN (ANALYZE, BUFFERS)` 检查按单个任务读取完整快照。应用迁移前为并行全表扫描，
+应用后命中新增索引并对 20 行结果排序，结果保留 active、expired 和 released 状态。
+`pg_index` 确认索引 valid、ready。实际部署按正式迁移执行，大表安排维护窗口，
+并在目标数据库用代表性任务 ID 复核执行计划、等待事件和历史状态。

package/template/docs/architecture/embedded-dsh-integration.md

@@ -8,7 +8,7 @@
 
 ## 实现与职责
 
-Agent Server 是 Node 24.7+ 与 TypeScript workspace，固定官方 DSH `0.2.1-rc.2` 和 Cordis `4.0.5`。Bun 管理依赖及构建；DSH 原生插件安装器需要的 pnpm 随同镜像交付。通过公开 AgentLoop、Skill Provider、MCP、生命周期及 UI slot 接入，没有自维护的 DSH 内核。
+Agent Server 是 Node 24.9+ 与 TypeScript workspace，使用官方 DSH `~0.2.2-rc.1` 和 Cordis `^4.1.0`，实际版本由 Bun 锁文件确定。Bun 管理依赖及构建；DSH 原生插件安装器需要的 pnpm 随同镜像交付。通过公开 AgentLoop、Skill Provider、MCP、生命周期及 UI slot 接入，没有自维护的 DSH 内核。
 
 | 所有者         | 职责                                                                                                      |
 | -------------- | --------------------------------------------------------------------------------------------------------- |

package/template/docs/development/dsh-plugins.md

@@ -1,6 +1,6 @@
 # DSH 插件与项目接入
 
-运行基线固定为官方DSH `0.2.1-rc.2`、Cordis `4.0.5`和Node 24.7+。不要把本次回迁同时当作上游升级。官方依赖通过Bun与锁文件安装；不修改node_modules或复制上游内核。
+运行基线为官方 DSH `~0.2.2-rc.1`、Cordis `^4.1.0` 和 Node 24.9+。所有直接依赖的 DSH 包使用同一版本范围，升级时一起更新。官方依赖通过Bun与锁文件安装；不修改node_modules或复制上游内核。
 
 ## 项目扩展
 

package/template/docs/development/performance-engineering.md

@@ -0,0 +1,24 @@
+# 性能开发与验收
+
+## 启动与模块装配
+
+- 浏览器通过 `@southwind-ai/modules/admin-ui` 读取路由目录，模块名称和版本来自无运行时导入的 `system-module-definitions.ts`。服务端完整 Manifest 从同一文件装配权限、审计、API 和 Agent。新增浏览器入口时检查 tree-shaking 前的解析图，开发模式会请求静态依赖。
+- Router 使用原生路由 loader，受保护的管理页面在认证、Feature、Permission 和 License 守卫允许后解析。公共入口的主题从 `main.ts` 引入 `style.css`，应用布局和管理壳按实际布局加载。品牌主题若由项目扩展提供，由公开页面或公共入口显式导入。为登录和公开错误页验收浅色与深色。
+- 生成时未选择的模块应同时裁剪源码、路由绑定、依赖和相应数据库对象。禁用的外部模块包从 Vite 虚拟 Admin 注册表排除。内置模块在通用产物中仍可能有异步 chunk。运行时关闭 Feature 或拒绝权限应阻止导航加载和隐藏入口，浏览器已取得的字节仍可访问。
+- 使用生产构建 manifest 检查 HTML 预加载、递归静态 imports 和所有输出 chunk。物理裁剪需要同时检查动态入口和产物文件。开发模式另查浏览器请求或预摇树解析图。Secret、内部执行策略和敏感算法留在服务端，客户端只拿当前用户授权的最小投影。服务端逐请求校验 Feature、RBAC、License 和 Scope。
+- 可选 Copilot、图表和 PageAgent 按功能启用、有效权限和实际使用时机加载。异步导入完成后复核会话、权限、取消信号与页面范围再创建控制器。撤权或离开作用域时卸载和停止运行。授权或网络快照失败沿用现有恢复路径。
+
+## 数据与交互
+
+- 默认读取当前展示投影，编辑时才补全。保存保留未展示的配置与版本约束。提交等价数据时保留未变化对象的引用，避免重建图表。
+- 有合法快照时先展示并后台刷新，已展示内容保持可操作。缓存绑定身份与权限，退出、身份变更及 401/403 时失效。网络与缓存读取可并行，迟到缓存或旧会话请求不得覆盖新结果。敏感会话快照复用项目加密和有效期机制，普通网络失败沿用页面既有恢复契约。
+- 图谱的结构、照片与选择分别更新。用绘图库公开的局部更新接口保持视口，菜单打开时才计算菜单模型，读取已绘制 ID。几何缓存限定在一次布局或转换，验证 Unicode、换行、字体变化与导出结果。
+- 骨架、指标和时间戳预留空间，未知值显示“—”。同时验收对比度、键盘焦点、标签和点击区域。过期的 Vite 构建资源在 `/assets/` 返回 404，应用深链接继续进入 SPA。
+- 测试断言失败时追溯字段所有者、当前 API 和引入字段的历史。使用独立预期字段、实体 ID 和关系断言覆盖完整投影，避免为通过测试而删字段。
+
+## 可复现的验收
+
+1. 在独立目录构建并冻结候选产物，记录提交和构建标识、真实路由、数据规模、权限、设备、视口、节流、扩展、冷缓存和热缓存条件。
+2. 覆盖匿名登录和公开错误页、已登录首页、实际管理页面以及安装了可选模块的代表性交互。检查 LCP 对应业务内容，记录代表性操作的 Event Timing 和 INP。桌面目标为 LCP < 2 秒、INP < 300 ms、Lighthouse Performance、Accessibility、Best Practices、SEO 各 ≥ 96。分别保存 Lighthouse 的 TBT 与交互测量。
+3. 保留失败历史并标明错路由、运行时错误和不完整样本，按最近有效样本报告。区分本地短会话指标与生产分位数。Windy 的验收使用自身产物和数据。
+4. Windy 源仓库的执行层级见 `docs/agents/testing-gates.md`。生成项目使用自身的验收门禁。浏览器测量按项目授权执行。

package/template/docs/operations/admin-settings-yaml.md

@@ -0,0 +1,29 @@
+# Admin 配置 YAML 迁移
+
+在源实例打开 **Admin → 全局设置 → 配置迁移**，保存配置后点击 **导出 YAML**。
+在客户实例打开同一页面，选择 **导入 YAML**，上传文件并查看校验结果及当前值和导入值。
+确认差异后点击 **确认导入**，页面会刷新水印表单与当前会话的水印设置。
+如果目标配置在预览之后发生变化，请重新选择文件获取预览。
+
+版本 1 支持以下水印字段。
+
+```yaml
+version: 1
+watermark:
+  enabled: true
+  density: medium
+  contentFields:
+    - username
+    - displayName
+  opacityPercent: 8
+  fontSize: 14
+```
+
+`contentFields` 存放显示字段的枚举值。例如 `phone` 表示按目标实例当前登录者显示手机号，
+`custom` 表示使用目标实例已有的自定义文字。文件只包含上述白名单字段。
+密钥、客户记录、账号实际字段值、品牌资源和自定义水印文字均由各实例管理。
+
+导出需要水印查看权限。预览和导入需要水印管理权限，均受水印功能开关控制。
+服务器拒绝未知字段、未知版本、多文档、重复键、别名、锚点、显式标签及超过 8 KiB 的文件，
+并复用水印表单的字段和值域校验。确认时重新校验文件与预览坐标，写入时检查目标基线；
+成功导入在 `config.update` 审计中标记 `source: yaml`，记录变更字段名。

package/template/docs/operations/dsh-agent-migration.md

@@ -15,7 +15,7 @@
 
 ## 配置与资源
 
-- Node要求24.7+；Linux内核必须满足Landlock完整约束及seccomp。协调器使用root切换UID，容器drop ALL后仅补SETUID、SETGID、CHOWN、DAC_OVERRIDE、KILL，启用no-new-privileges。
+- Node要求24.9+；Linux内核必须满足Landlock完整约束及seccomp。协调器使用root切换UID，容器drop ALL后仅补SETUID、SETGID、CHOWN、DAC_OVERRIDE、KILL，启用no-new-privileges。
 - `AGENT_SERVER_INTERNAL_TOKEN`是内部服务认证；Provider继续使用`QWEN_API_URL/QWEN_API_KEY/QWEN_MODEL`。HTTPS Provider域名须在`AI_PROVIDER_HTTPS_HOST_ALLOWLIST`，内部结果加密使用`AGENT_INTERNAL_OUTPUT_ENCRYPTION_SECRET`。不向用户进程下发这些真实凭据。
 - 全局模型容量由`AI_PROVIDER_MAX_CONCURRENT_RUNS`控制。Compose保留1槽、0队列默认值；因此原生模型任务显示容量预留不可用。现场确认模型和内存后才能提高上限；原生请求始终保留至少1槽给既有调用链。
 - 原生任务上限`AGENT_DSH_MAX_ACTIVE_RUNS=2`，用户Worker默认2，工作区软配额512MiB，容器4GiB/2CPU/512PID。软配额不代替磁盘硬配额，WASM峰值RSS也不等于V8 heap限制。
@@ -83,7 +83,7 @@ bun run --cwd apps/agent-server test:confinement
 | 生产 Web 镜像     | Node构建和Bun生产启动通过；只读容器中用合成同容器API上游验证就绪、静态首页、原生HTTP/WS转发及伪造内部身份头剥离，不涉及浏览器。                                                                                                                                                |
 | 技能与诊断持久化  | 专用 PostgreSQL 18 容器执行0064三表迁移及真实 Repository：4项、37个断言通过，包括并发 CAS、幂等、重建连接池后的待审计恢复、停用/回滚及30天精确过期边界/有界清理。未连接业务数据库。                                                                                            |
 | 技能界面与权限    | 导入包边界、共享范围、依赖、读取与变更审计、版本冲突、停用/回滚及未保存输入保护由服务/API/组件检查覆盖；没有浏览器 E2E。                                                                                                                                                       |
-| Workflow/错误诊断 | 动态预设只读注册、当前授权与可用性说明；实际 HTTP 失败生成诊断号，只存路由模板/安全码，拒绝越权查询并审计。查询立即排除过期记录，物理清理在失败记录写入时按分钟节流、有界执行。                                                                                                |
+| Workflow/错误诊断 | 动态预设只读注册、当前授权与可用性说明；实际 HTTP 失败生成诊断号，只存路由模板/安全码，拒绝越权查询并审计。管理面可分页浏览最近 30 天的脱敏失败记录，也可按编号定位。两种查询复用诊断读取权限和审计，立即排除过期记录。物理清理在失败记录写入时按分钟节流、有界执行。          |
 | 非案件示例        | 真实平台 ToolRegistry 的 `system.users.list` 经真实 DSH Loop 调用1次，合成 Provider 调用2次，canonical SSE 与结构化汇总返回授权示例用户数1。没有利剑案件依赖。                                                                                                                 |
 | 文档与下载        | Linux UID20000、无外网、只读输入下读取 `windy-office` 技能，使用镜像文档工具生成新 DOCX/XLSX 并独立回读，保留来源摘要和文本编号001；生产下载插件+真实 LocalFileSystem+HTTP 验证字节/摘要/中文文件名及匿名、跨会话、越界、软链拒绝。Session坐标和连接身份明确使用合成 fixture。 |
 | Office 预览       | 固定 WASM 将36778字节合成 DOCX 转为29653字节完整 PDF，用时2402ms，峰值RSS1527008KiB、缺失字体为空；另行回读PDF有1页且包含中文平台用户汇总。超限前拒绝、预取消、禁用后台转换均通过。                                                                                            |

package/template/docs/operations/environment-capabilities.md

@@ -0,0 +1,185 @@
+# 环境能力评估与构建预设
+
+Windy 将交付内容、运行时功能开关和设备能力分开处理。没有 GPU 时，普通业务功能与 CPU
+可执行的任务仍可保留；模型或 Adapter 是否支持 CPU，需要检查实际实现与验收证据。
+环境评估只给出建议，不替管理员自动关闭功能。评估状态 `available` 只表示声明条件
+满足，不表示模型、Provider 或业务已实测可用。
+
+可直接复制[中文环境预设模板](../../deploy/environment/windy.environment.example.yaml)，
+按实际模块与业务能力修改；模板保留共享 Runtime 的当前依赖边界。
+
+## 首次生成的 YAML / JSON 入口
+
+```sh
+bunx create-windy my-app --environment-profile ./windy.environment.yaml --yes
+```
+
+`--environment-profile` 同时接受 YAML 与 JSON，严格校验结构与模块名；输入及生成后的策略
+均不超过 128 KiB，与 Server 读取上限一致。不与 `--module`、
+`--all-modules`、`--no-optional-modules` 混用。它不改变原有 `--profile private-enterprise`
+的部署档位语义。`build.modules` 走现有模块依赖解析与生成裁剪流程：必需模块及依赖自动
+补齐，未选择模块按分发清单裁剪源码、依赖、路由绑定与数据库对象。
+
+以下示例生成不需要 Agent 或 Document Runtime 的基础项目；它不是“带 CPU OCR”预设：
+
+```yaml
+schemaVersion: 1
+build:
+  modules:
+    - system
+    - system.identity
+    - system.configuration
+    - system.operations
+# 环境建议单独维护，不参与模块裁剪，也不自动开关 Feature。
+features: []
+```
+
+生成器始终发放带中文注释的 `windy.environment.yaml`，其中 `build.modules` 记录实际解析后的
+模块集合。它由项目所有者维护，后续模板升级保留客户文件；原有生成版本与选项仍由
+`.windy/generation.json` 记录。修改已有项目的 YAML 不会删除已经构建的模块或安装中的
+数据库对象；需按该项目正式的生成、升级或交付流程处理。
+
+## 启动运行时
+
+配置 `runtime.agent`、`runtime.document`、`runtime.speech` 和 `runtime.embedding` 可分别
+启停 Server 装配，修改文件后重启 Server 生效。省略的开关保留现有装配行为。
+`PLATFORM_ENABLE_AI_RUNTIME` 仍是总开关，`runtime.*: false` 对应的 Feature 会在 Access
+Snapshot 中关闭，即使数据库 Feature 配置为开启。格式无效的环境文件会阻止 Server 启动。若总开关关闭，YAML 显式启用任一运行时也会阻止启动，避免容器正常启动但业务能力静默不可用。
+
+纯 CPU OCR 的 Server 配置为 `agent: false`、`document: true`，并分别选择 Speech 和
+Embedding。仍须交付包含媒体代码的模块，配置 Document 端点和共享 Artifact 凭据。
+生成时可通过 `build.runtimes` 分别省去独立运行时应用源码、Compose 服务、镜像构建入口与专用卷。
+`build.runtimes.*: false` 与 `runtime.*: true` 冲突时拒绝配置。显式启用且已交付的运行时
+会进入默认 Compose 启动集合，并默认开启共享运行时总开关。生成的 Compose 默认以只读方式挂载环境文件，即使首次生成
+未显式提供预设。生成后修改 YAML
+会影响 Server 重启后的装配，Compose 服务集合则由生成时的配置决定。生成时写入的 Server
+交付上限会拒绝 YAML 尝试启用已裁剪的运行时。裁掉 Agent 时，生成器也会移除 Agent 专属 Admin
+页面源码、路由和菜单声明。媒体和公共 Server 装配由 `system.media-runtime` 提供。
+
+使用环境预设生成项目时，初始预设写入 Project Lock。后续升级用该快照重建来源和目标模板，
+保留已裁剪的运行时应用，客户可继续维护自己的运行时 YAML。旧版 Agent 项目在解析目标模块
+依赖时会补齐 `system.media-runtime`。迁移会一次性复制原来能调用媒体 API 的角色授权，
+并沿用旧 Agent Feature 的启用、可见性和许可版本限制。已有媒体 Feature 记录优先；
+升级完成后可分别管理三个媒体 Feature 和对应角色授权。
+
+## 运行时评估建议
+
+Server 通过 `WINDY_ENVIRONMENT_PROFILE_FILE` 显式指定策略文件。容器部署需将文件只读
+挂载到容器中，并配置容器内路径；只修改宿主机路径或生成文件，不会自动接通容器。
+宿主诊断报告由 `WINDY_HOST_DIAGNOSTICS_FILE` 指定，同样只读挂载；服务端读取报告，
+不会自行提权执行宿主命令。报告缺失或过期时相关环境结论保持 `unknown`，不能假定宿主
+没有 GPU，亦不能用容器自身的资源信息冒充宿主实况。
+
+`build.modules` 在运行时仅是交付记录，不能用它替代当前 Manifest、安装清单或权限判断。
+
+`features` 的每项针对一个真实 Manifest Feature，使用以下字段：
+
+| 字段                                           | 中文语义                                                                       |
+| ---------------------------------------------- | ------------------------------------------------------------------------------ |
+| `key`、`title`                                 | 正式 Feature Key 与说明名称                                                    |
+| `execution`                                    | `none` 无执行资源要求、`cpu` CPU 执行、`local-gpu` 本地 GPU、`remote` 远程服务 |
+| `recommendedEnabled`                           | 管理员可评估的启停建议，不直接改写已有开关                                     |
+| `supportedPlatforms`、`supportedArchitectures` | 该实现实际支持的操作系统/架构范围；应依据软件适配证据填写                      |
+| `minMemoryGiB`                                 | 已知最低内存要求；不能用它承诺延迟或吞吐                                       |
+| `requiredEnvironmentKeys`                      | 必需配置的变量名，仅检查配置条件，不在报告中公开值                             |
+
+填写 `features` 前核对当前模块是否已交付、Feature 是否真实注册、软件是否适配以及服务是否
+就绪。设备探测结果不能替代模型初始化、端点鉴权、业务输出或质量验证；未知状态应保留
+为待确认。报告与建议供管理员判断，既有 RBAC、License、Scope 和业务 Guard 继续生效。
+
+## 宿主诊断报告
+
+在需要评估的宿主机运行随模板交付的采集脚本，报告只包含有界诊断结果：
+
+```sh
+umask 077
+mkdir -p .local/diagnostics
+python3 scripts/operations/collect-device-info.py > .local/diagnostics/host.json
+# 可选：补充具体服务状态与已安装发布标识
+python3 scripts/operations/collect-device-info.py \
+  --systemd-unit windy.service --manifest /opt/windy/manifest.json \
+  > .local/diagnostics/host.json
+```
+
+报告采用新的结构化 JSON 协议，不直接导入历史 TXT 诊断文本。可选 manifest 只读取
+`releaseId`、`gitSha`、`platform` 白名单字段。采集器不安装软件、不重启服务、不读取应用
+凭据；缺少工具会记录缺失状态。报告可能包含
+主机名、网络地址、磁盘挂载和容器名称，应保存在运维可控目录，不纳入 Git 或公开附件。
+服务端评估和页面展示仍受运维权限控制。
+
+以下为添加到现有 Server 服务的只读挂载示例，路径与文件名由部署方确认：
+
+```yaml
+services:
+  server:
+    environment:
+      WINDY_ENVIRONMENT_PROFILE_FILE: /app/diagnostics/windy.environment.yaml
+      WINDY_HOST_DIAGNOSTICS_FILE: /app/diagnostics/host.json
+    volumes:
+      - ./windy.environment.yaml:/app/diagnostics/windy.environment.yaml:ro
+      - ./.local/diagnostics/host.json:/app/diagnostics/host.json:ro
+```
+
+先生成报告再启动容器，避免 Docker 把缺失文件路径创建为目录。后续刷新报告后重新读取
+运维快照；报告是否新鲜由服务端校验，旧报告不能当作当前设备状态。
+
+## CPU OCR、Agent 与病毒扫描的边界
+
+Agent、Document、Speech 与 Embedding 共用的 Provider 输入治理、执行凭据、内部令牌校验
+和幂等键位于 `apps/server/src/ai-runtime-security/`。Document、Speech 与 Embedding 的远端连接和
+路由装配位于 `apps/server/src/media-runtime/composition.ts`。这两部分当前仍随现有模块交付，
+共享 Artifact、媒体 readiness 与业务端口通过 `media-runtime/shared-composition.ts` 装配，
+当 YAML 关闭 Agent 时，Server 直接装配媒体和共享端口，跳过 Agent Host、工具注册与 MCP。
+
+`system.media-runtime` 可单独选择，为 Document、Speech、Embedding 与公共 Artifact 提供
+Manifest、Server 装配和数据库归属。选择 `system.agent` 时，生成器会自动补齐这个依赖。
+媒体直接 API 使用各自的 Feature。公共文件入口使用
+`system.ai-artifact`，仍要求内部令牌、文件引用和当前对象授权。读取 Agent 截图另需启用
+`system.agent`。
+
+病毒扫描通过独立的 `antivirus.packaged` 和 `antivirus.enabled` 声明，与 AI 运行时和 GPU
+无关。Windy 通用模板默认两项均为 `false`，也允许省略此段以沿用项目原有配置。
+通用生成器只交付平台能力，若请求 `packaged: true` 会明确拒绝。
+
+需要扫描的项目负责打包扫描器、病毒库及更新服务，并在项目拥有的
+`apps/server/src/app/antivirus-composition.ts` 中装配 `ProjectAntivirusBinding`。
+该绑定须接入项目实际的入库流程。Server 启动时，`enabled: true` 传递 `required`，
+扫描器必须完成就绪检查并返回 `ready`，否则拒绝启动。交付声明必须与项目实际装配一致。
+已打包扫描器、但暂时停用时使用 `packaged: true`、`enabled: false`，Server 传递
+`disabled`，项目应停止扫描并保留原有文件解析流程。只改 YAML 无法安装扫描器或病毒库。
+
+若扫描器是独立 Worker，项目的启动器须用同一份环境预设选择 Worker 模式，并在 Worker
+重启后再启动 Server。对于只在启动时读取扫描模式的 Worker，项目绑定应核对 Worker 实际
+行为和就绪状态；修改 Server 自身的环境变量不会切换已经运行的 Worker。
+验收时通过实际入库接口送入干净文件与匹配测试签名的合成文件，核对启用时的拦截结果和
+停用时的跳过记录，并确认停用扫描后仍可正常解析。
+
+管理员确认启停时，记录受影响的业务功能、当前证据和选择；已有用户授权可直接沿用。
+因未知设备、暂时探测失败或未验证性能而自动全局停用 AI，会误伤 CPU 或远程服务能力。
+回滚通过恢复此前经过确认的功能设置完成；构建时移除的能力需要重新交付，运行时开关
+无法补回缺失代码。
+
+## Skill 分发与验证层级
+
+开发约定由根目录 `.agents/skills/windy-business-module/SKILL.md` 维护。create-windy 的
+`template-manifest.ts` 将该目录纳入模板，`template:sync` 从已提交的 Git HEAD 生成发布副本；
+不维护第二份容易漂移的手写 Skill。本次新增的环境适配约定随正式模板分发。
+
+普通本地修改只运行项目允许的静态检查。参数、YAML/JSON 校验、依赖闭包、裁剪结果和
+客户文件保留由合并候选测试覆盖，完整生成、构建与 pack consumer 属于发版门禁。
+模板被发放不代表目标主机或业务质量已通过验收。
+
+### 业务能力开关
+
+业务页面和服务入口使用 Access Snapshot 中对应的 Feature Key。拥有业务权限的调用方仍须通过目标
+Operation 自身的权限和数据范围校验。
+
+| 能力           | Feature Key        | 平台直接 API 权限       |
+| -------------- | ------------------ | ----------------------- |
+| Agent          | `system.agent`     | `system.agent.read`     |
+| Document / OCR | `system.document`  | `system.document.read`  |
+| Speech         | `system.speech`    | `system.speech.read`    |
+| Embedding      | `system.embedding` | `system.embedding.read` |
+
+自定义角色调用媒体直接 API 时需要对应的新权限。当前 Feature 控制业务入口和 API 访问，
+生成裁剪仍需独立模块边界。

package/template/docs/platform/module-configuration.md

@@ -25,6 +25,21 @@
 
 unknown 检查只作用于 Definition 明确拥有的 prefix 或 exact key，避免把操作系统、Bun、测试工具或其它服务环境变量误判为平台配置。
 
+## 共享 AI Runtime 开关
+
+推荐环境变量为 `PLATFORM_ENABLE_AI_RUNTIME`，控制共享 AI Runtime 基础设施，包含 CPU OCR
+所需的 Document Runtime；它不代表已提供 GPU、大模型或 Copilot，也不是构建功能预设。
+内部逻辑字段保持 `enableAI`，不迁移已有配置版本。
+
+旧变量 `PLATFORM_ENABLE_AI` 作为兼容别名继续读取。只配置其中之一即可；进程环境同时包含两者时必须
+解析为相同布尔值，否则启动返回 `CONFIG_INVALID_VALUE`（字段 `enableAI`），不静默选择
+优先级。两者均未配置时仍默认 `false`；空值、非法值和拼错的变量名仍拒绝。Compose
+先读取新名称，未设置时回退旧名称，只向容器传新名称；迁移 `.env` 时删除旧名称以避免歧义。已有只配置旧名的安装不因模板升级被关闭。
+
+环境别名显式登记在 Definition，严格白名单同时识别新旧名；当前别名仅支持非 Secret
+字段，避免改变 SecretResolver 的引用边界。该开关保留共享基础设施，具体业务功能仍由
+模块装配、Manifest Feature、RBAC、License 与 Scope 判定。
+
 ## SecretRef 与 SecretResolver
 
 Secret 配置分成引用和运行时值两层：
@@ -66,12 +81,12 @@ handle/connection/purpose，业务模块看不到物理 locator。
 
 当前 `platform.runtime` 白名单包括：
 
-- `enableAI`：更新 foundation 平台能力投影；
+- `enableAI`：重启后装配或停用 AI 与 Agent Runtime，并同步管理面「AI 与 Agent」分组与页面准入；
 - `cache.healthTimeoutMs`：后续 Redis 探活按最新值创建 probe。
 - `security.sessionTtlSeconds`：即时影响新签发会话，已有会话保持原过期时间；
 - `security.passwordMinLength/passwordMaxLength`：即时影响 Argon2 密码修改、重置校验和密码页服务端策略；
-- `storage.bulkDataMaxByteSize/storage.brandingLogoMaxByteSize`：即时影响后续上传会话；
-- `regional.timeZone`：即时影响公共平台设置投影和 Web 后续日期格式化；
+- `storage.bulkDataMaxByteSize/storage.brandingLogoMaxByteSize`：即时影响后续上传会话。Logo 上限以字节保存，界面同时显示易读的换算值，默认 5 MiB（5,242,880 字节）；
+- `regional.timeZone`：即时影响公共平台设置投影和 Web 后续日期格式化。界面通过下拉选择 IANA 时区，显示其标识和当前 UTC 偏移；
 - `mail.enabled/host/port/secure/fromAddress/connectTimeoutMs`：保存为
   `pending-restart`，下次 Server 启动后进入 typed runtime config。
 

package/template/docs/platform/platform-authentication.md

@@ -36,7 +36,7 @@ POST /api/auth/users/:id/password
 - `POST /auth/sessions/revoke-all` 默认只吊销本人其它会话并保留当前会话，响应返回吊销数量以及当前会话是否保留。只有显式提交 `{ "includeCurrent": true }` 才会吊销包括当前会话在内的全部本人会话并清除 Cookie；客户端不能提交目标用户 ID。
 - `GET /auth/login-events` 返回当前 Session Actor 最近 20 条登录成功/失败事件。查询条件固定为服务端 Actor，客户端即使提交 `actorId` 也不能读取他人的事件；响应只保留结果、时间、IP、User-Agent 和稳定失败原因，不暴露审计 Actor 或目标账号字段。未知账号登录失败继续归属匿名 Actor，不能借该接口探测账号是否存在。
 - 只有具备 `system.user.manage` 权限的用户可以重置密码。接口接收 `password`，服务端生成 Argon2id hash；通用用户 CRUD 不读写或返回 `password_hash`。重置后账号进入 `must-change-password`，`password_changed_at` 保持空值，并立即吊销该用户全部活跃会话。
-- 已认证用户通过 `POST /api/auth/password/change` 提交当前密码和新密码。服务端固定使用 Session Actor 作为目标用户，不接受客户端 `userId`；校验当前密码、拒绝复用当前密码，并在成功后把状态恢复为 `active`、记录 `password_changed_at`。成功改密会吊销包括当前会话在内的全部会话、清除 Cookie，用户必须用新密码重新登录。
+- 用户可从「个人设置 → 登录密码 → 修改密码」发起改密。已认证用户通过 `POST /api/auth/password/change` 提交当前密码和新密码。服务端固定使用 Session Actor 作为目标用户，不接受客户端 `userId`；校验当前密码、拒绝复用当前密码，并在成功后把状态恢复为 `active`、记录 `password_changed_at`。成功改密会吊销包括当前会话在内的全部会话、清除 Cookie，用户必须用新密码重新登录。
 
 登录成功、登录失败、退出、会话吊销、密码更新和越权拒绝都会写入审计。审计只记录用户、Session ID、结果和稳定原因，不记录明文密码、Bearer Token 或 Cookie。
 

package/template/package.json

@@ -67,7 +67,9 @@
     "check:document": "uv run --directory apps/document-server ruff check . && uv run --directory apps/document-server ruff format --check . && uv run --directory apps/document-server mypy",
     "check:speech": "uv run --directory apps/speech-server ruff check . && uv run --directory apps/speech-server ruff format --check . && uv run --directory apps/speech-server mypy",
     "check:embedding": "uv run --directory apps/embedding-server ruff check . && uv run --directory apps/embedding-server ruff format --check . && uv run --directory apps/embedding-server mypy",
-    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/delivery typecheck && bun run --cwd packages/create-windy typecheck && bun run --cwd apps/agent-server typecheck && bun run --cwd apps/windy-gateway typecheck && bun run --cwd packages/model-gateway typecheck",
+    "typecheck:quality": "tsc --noEmit --project scripts/quality/tsconfig.json",
+    "typecheck:affected": "bun run scripts/typecheck-affected.ts",
+    "typecheck": "bun run --cwd apps/web typecheck && bun run --cwd apps/server typecheck && bun run --cwd apps/license typecheck && bun run --cwd apps/signing-service typecheck && bun run --cwd packages/ai-client typecheck && bun run --cwd packages/license-sdk typecheck && bun run --cwd packages/jobs typecheck && bun run --cwd packages/server-sdk typecheck && bun run --cwd packages/storage typecheck && bun run --cwd packages/database typecheck && bun run --cwd packages/crud-generator typecheck && bun run --cwd packages/delivery typecheck && bun run --cwd packages/create-windy typecheck && bun run --cwd apps/agent-server typecheck && bun run --cwd apps/windy-gateway typecheck && bun run --cwd packages/model-gateway typecheck && bun run typecheck:quality",
     "lint": "oxlint .",
     "format": "oxfmt",
     "check:static": "bun run lint && bun run typecheck && bun run check:agent && bun run check:document && bun run check:speech && bun run check:embedding",
@@ -82,15 +84,15 @@
     ]
   },
   "devDependencies": {
-    "@types/bun": "^1.3.14",
-    "@types/pg": "^8.20.0",
-    "drizzle-kit": "^0.31.10",
-    "drizzle-orm": "^0.45.2",
+    "@types/bun": "~1.3.14",
+    "@types/pg": "^8.23.1",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.4",
     "husky": "^9.1.7",
-    "lint-staged": "^17.1.1",
+    "lint-staged": "^17.6.0",
     "oxfmt": "^0.59.0",
-    "oxlint": "^1.74.0",
-    "pg": "^8.22.0",
+    "oxlint": "^1.92.0",
+    "pg": "^8.23.1",
     "typescript": "5.9.3"
   },
   "dependencies": {}

package/template/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/config",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -14,7 +14,7 @@
   ],
   "dependencies": {
     "@southwind-ai/shared": "workspace:^0.3.0",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "exports": {
     ".": "./index.ts"

package/template/packages/config/src/definition.ts

@@ -5,6 +5,8 @@ export type EnvironmentValueDecoder = (value: string) => unknown;
 
 export interface ModuleConfigEnvironmentField {
   key: string;
+  /** Legacy environment names; conflicting values are rejected. */
+  aliases?: readonly string[];
   path: string;
   defaultValue?: unknown;
   decode?: EnvironmentValueDecoder;
@@ -94,16 +96,24 @@ function validateDefinition<T>(definition: ModuleConfigDefinition<T>): void {
   const environmentKeys = new Set<string>();
   const paths = new Set<string>();
   for (const field of definition.environment) {
-    if (!/^[A-Z][A-Z0-9_]*$/.test(field.key)) {
-      throw new Error(`配置模块 ${definition.key} 包含无效环境变量名`);
+    if (field.secret && field.aliases?.length) {
+      throw new Error(`配置模块 ${definition.key} 的 Secret 不支持环境别名`);
+    }
+    for (const key of [field.key, ...(field.aliases ?? [])]) {
+      if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+        throw new Error(`配置模块 ${definition.key} 包含无效环境变量名`);
+      }
+      if (environmentKeys.has(key)) {
+        throw new Error(`配置模块 ${definition.key} 包含重复字段`);
+      }
+      environmentKeys.add(key);
     }
     if (!/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)*$/.test(field.path)) {
       throw new Error(`配置模块 ${definition.key} 包含无效字段路径`);
     }
-    if (environmentKeys.has(field.key) || paths.has(field.path)) {
+    if (paths.has(field.path)) {
       throw new Error(`配置模块 ${definition.key} 包含重复字段`);
     }
-    environmentKeys.add(field.key);
     paths.add(field.path);
   }
 }

package/template/packages/config/src/environment-loader.ts

@@ -78,7 +78,7 @@ async function readField(
   environment: ConfigEnvironment,
   resolver: SecretResolver,
 ): Promise<unknown> {
-  const raw = environment[field.key];
+  const raw = readEnvironmentValue(moduleKey, field, environment);
   if (!field.secret) return decodeField(moduleKey, field, raw);
   const ref = createSecretRef(field, raw);
   if (!ref) return missingSecret(moduleKey, field);
@@ -101,7 +101,7 @@ function readFieldSync(
   environment: ConfigEnvironment,
   resolver: SecretResolver,
 ): unknown {
-  const raw = environment[field.key];
+  const raw = readEnvironmentValue(moduleKey, field, environment);
   if (!field.secret) return decodeField(moduleKey, field, raw);
   const ref = createSecretRef(field, raw);
   if (!ref) return missingSecret(moduleKey, field);
@@ -126,6 +126,25 @@ function readFieldSync(
   }
 }
 
+function readEnvironmentValue(
+  moduleKey: string,
+  field: ModuleConfigEnvironmentField,
+  environment: ConfigEnvironment,
+): string | undefined {
+  if (!field.aliases?.length) return environment[field.key];
+  const values = [field.key, ...field.aliases]
+    .map((key) => environment[key])
+    .filter((value): value is string => value !== undefined);
+  const first = values[0];
+  if (first === undefined || values.length < 2) return first;
+  const decode = (raw: string) => decodeField(moduleKey, field, raw);
+  const selected = decode(first);
+  if (values.slice(1).some((raw) => !Object.is(decode(raw), selected))) {
+    throw new ConfigLoadError("CONFIG_INVALID_VALUE", moduleKey, field.path);
+  }
+  return first;
+}
+
 function createSecretRef(
   field: ModuleConfigEnvironmentField,
   raw: string | undefined,
@@ -181,7 +200,12 @@ function assertKnownEnvironment<T>(
   definition: ModuleConfigDefinition<T>,
   environment: ConfigEnvironment,
 ): void {
-  const known = new Set(definition.environment.map((field) => field.key));
+  const known = new Set(
+    definition.environment.flatMap((field) => [
+      field.key,
+      ...(field.aliases ?? []),
+    ]),
+  );
   const exact = new Set(definition.ownedEnvironmentKeys || []);
   const prefixes = definition.ownedEnvironmentPrefixes || [];
   const unknown = Object.keys(environment).filter(

package/template/packages/config/src/platform-ai-runtime.test.ts

@@ -0,0 +1,94 @@
+import { expect, test } from "bun:test";
+import { z } from "zod";
+import { defineModuleConfig } from "./definition.js";
+import { ConfigLoadError, loadModuleConfig } from "./environment-loader.js";
+import { loadPlatformConfig, platformConfigDefinition } from "./platform.js";
+import { EnvironmentSecretResolver } from "./secrets.js";
+
+test("共享 AI Runtime 使用明确新名，兼容旧名与缺省关闭", () => {
+  expect(loadPlatformConfig({}).enableAI).toBe(false);
+  for (const key of ["PLATFORM_ENABLE_AI_RUNTIME", "PLATFORM_ENABLE_AI"]) {
+    expect(loadPlatformConfig({ [key]: "true" }).enableAI).toBe(true);
+    expect(loadPlatformConfig({ [key]: "false" }).enableAI).toBe(false);
+  }
+  expect(
+    loadPlatformConfig({
+      PLATFORM_ENABLE_AI_RUNTIME: "true",
+      PLATFORM_ENABLE_AI: "1",
+    }).enableAI,
+  ).toBe(true);
+});
+
+test("新旧变量冲突、空值或非法值均 fail closed 且不回显输入", () => {
+  for (const legacy of ["false", "", "DO-NOT-LEAK"]) {
+    try {
+      loadPlatformConfig({
+        PLATFORM_ENABLE_AI_RUNTIME: "true",
+        PLATFORM_ENABLE_AI: legacy,
+      });
+      throw new Error("Expected configuration rejection");
+    } catch (error) {
+      expect(error).toBeInstanceOf(ConfigLoadError);
+      expect(error).toMatchObject({
+        code: "CONFIG_INVALID_VALUE",
+        fieldPath: "enableAI",
+      });
+      expect(String(error)).not.toContain("DO-NOT-LEAK");
+    }
+  }
+  expect(() => loadPlatformConfig({ PLATFORM_ENABLE_AI_RUNTIME: "" })).toThrow(
+    ConfigLoadError,
+  );
+  expect(() =>
+    loadPlatformConfig({ PLATFORM_ENABLE_AI_RUNTIM: "true" }),
+  ).toThrow(expect.objectContaining({ code: "CONFIG_UNKNOWN_ENV" }));
+});
+
+test("异步 Definition Loader 也读取旧名而不绕过冲突校验", async () => {
+  const environment = { PLATFORM_ENABLE_AI: "true" };
+  expect(
+    (
+      await loadModuleConfig(
+        platformConfigDefinition,
+        environment,
+        new EnvironmentSecretResolver(environment),
+      )
+    ).enableAI,
+  ).toBe(true);
+  await expect(
+    loadModuleConfig(
+      platformConfigDefinition,
+      {
+        PLATFORM_ENABLE_AI: "false",
+        PLATFORM_ENABLE_AI_RUNTIME: "true",
+      },
+      new EnvironmentSecretResolver({}),
+    ),
+  ).rejects.toMatchObject({ code: "CONFIG_INVALID_VALUE" });
+});
+
+test("别名不能与其他字段重复，也不能用于 Secret 引用", () => {
+  const definition = {
+    key: "test.alias",
+    label: "Alias",
+    schema: z.object({ first: z.string(), second: z.string() }),
+    environment: [
+      { key: "FIRST", aliases: ["SECOND"], path: "first" },
+      { key: "SECOND", path: "second" },
+    ],
+  };
+  expect(() => defineModuleConfig(definition)).toThrow("重复字段");
+  expect(() =>
+    defineModuleConfig({
+      ...definition,
+      environment: [
+        {
+          key: "TOKEN",
+          aliases: ["OLD_TOKEN"],
+          path: "first",
+          secret: { provider: "env" },
+        },
+      ],
+    }),
+  ).toThrow("Secret 不支持环境别名");
+});

package/template/packages/config/src/platform.ts

@@ -206,9 +206,12 @@ export const platformConfigDefinition = defineModuleConfig<PlatformConfig>({
     // @windy-module system.agent end
   ],
   environment: [
-    value("PLATFORM_NAME", "name", "Windy Platform"),
+    value("PLATFORM_NAME", "name", "Windy"),
     value("PLATFORM_LOGO_URL", "logoUrl"),
-    value("PLATFORM_ENABLE_AI", "enableAI", false, strictBoolean),
+    {
+      ...value("PLATFORM_ENABLE_AI_RUNTIME", "enableAI", false, strictBoolean),
+      aliases: ["PLATFORM_ENABLE_AI"],
+    },
     value("DATABASE_DIALECT", "database.dialect", "postgresql"),
     secret("DATABASE_URL", "database.url"),
     secret("REDIS_URL", "cache.redisUrl"),

package/template/packages/database/drizzle/0065_durable_job_lease_snapshot_lookup.sql

@@ -0,0 +1 @@
+CREATE INDEX "idx_durable_job_leases_job_acquired" ON "durable_job_leases" USING btree ("job_id","acquired_at");