create-windy 0.8.3 → 0.10.0

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/agent-production-store.md

@@ -1,82 +1,9 @@
-# Agent 生产 Store、不可变 Release 与评估追踪
+# Agent 运行存储
 
-## 目标与边界
+2026-10-29。Agent Server 已由Node/DSH接管。canonical运行、SSE事件、Provider审计与原生用户工作区使用Agent专用本地存储；默认数据库为`AGENT_RUNTIME_DATABASE_PATH=/app/data/agent/embedded-dsh.sqlite`。
 
-Agent Runtime 的 PostgreSQL Store 是多副本生产默认实现。它只保存 Run
-执行事实、加密后的调用/事件/结果、Release 快照和评估结果，不保存业务会话、消息、
-标题、案件范围或归档策略。业务事实仍由业务模块持久化。
+当前只支持单副本，不承诺旧Python PostgreSQL Store模式或跨副本容量/HA。旧`AGENT_RUN_STORE_PATH`、`AGENT_DATABASE_URL`、`AI_PROVIDER_AUDIT_STORE_PATH`不能作为新实现已启用的证据。
 
-SQLite Store 只用于单副本本地开发和确定性验证；未配置
-`AGENT_DATABASE_URL` 且配置了 `AGENT_RUN_STORE_PATH` 时才启用。生产部署不得用
-共享文件系统模拟多副本 SQLite。
+产品PostgreSQL继续保存业务长期Session/Memory/Workflow、授权、运行绑定与报表治理事实；DSH存储不替代这些职责。内部结果仍使用Host声明的加密策略，普通历史读取不泄露internal输出。
 
-## 状态与反馈闭环
-
-同一个 `Idempotency-Key` 只能对应同一请求指纹。Run 的 canonical event 使用
-`run_id + sequence` 唯一键，读取接口按 cursor 重放；终态后追加、完成和取消都是
-幂等操作。事件或输出超过上限时，Store 写入唯一的 `run.failed`，避免运行态无限
-增长。
-
-每个工作副本领取 30 秒租约，并每 10 秒续租。租约丢失会中止当前执行，保留加密
-调用快照供其他副本接管；恢复轮询使用行锁和 `skip locked` 防止重复领取。终态数据
-按 TTL 清理，运行中数据不会被 TTL 清理。
-
-## 不可变 Release 与回滚
-
-每次 Run 固定以下坐标：
-
-- Operation 与模块版本；
-- Workflow、Prompt 和模型 Route 版本；
-- Tool/输出 Schema 摘要；
-- Manifest 摘要。
-
-这些坐标生成稳定的 `releaseId`。同一 `releaseId` 只能对应同一快照，冲突时
-fail closed，不能原地修改。业务模块通过
-`ModuleAiOperationHandlerRegistration.release` 显式声明 Workflow、Prompt 和
-Route 版本；未声明时使用模块版本。
-
-回滚不是修改历史 Release，而是重新部署此前的模块/注册版本。旧 Release 仍保留，
-新 Run 会固定到回滚后的旧坐标，历史 Run、评估和审计关联不会被改写。
-
-## 评估、用量、Attempt、审计和 Trace
-
-`POST /api/agent/evaluations` 仅接受内部 Token，可按 Release、评估集 Key 和评估集
-版本幂等记录指标；同一坐标提交不同结果会拒绝。`usage.reported` 作为加密 canonical
-event 保存。Provider attempt 审计以 `runId + attempt` 唯一保存，并可通过 Run 关联
-Release、usage 和平台 Audit。
-
-平台将请求关联值哈希为 128 位 Trace ID。Agent Runtime 用它建立 OTel 父 Trace，
-Span 只包含 Run ID、Operation Key、Release ID 和终态，不写 Prompt、业务输入、
-模型输出、Tool 参数、Actor 或 Secret。配置
-`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 后启用 OTLP/HTTP 导出，认证头由
-`OTEL_EXPORTER_OTLP_HEADERS` 注入。
-
-## 运维配置
-
-生产 Agent profile 必须配置：
-
-```dotenv
-AGENT_DATABASE_URL=postgresql://...
-AGENT_RUN_ENCRYPTION_SECRET=至少32字节随机值
-AGENT_SERVER_INTERNAL_TOKEN=随机内部令牌
-```
-
-可选配置：
-
-```dotenv
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example/v1/traces
-OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20...
-```
-
-加密密钥缺失或不足 32 字节时 Runtime 拒绝启动。数据库迁移必须先于 Agent Server
-启动。Provider attempt 的独立审计 Store 仍按
-`AI_PROVIDER_AUDIT_RETENTION_DAYS` 执行留存；不可把它与业务日志混用。
-
-## 故障与恢复
-
-- PostgreSQL 不可用：启动 fail closed；运行中的副本停止续租，不继续产生副作用。
-- 副本退出：租约过期后由其他副本恢复加密调用，不创建新 Run。
-- OTLP 不可用：BatchSpanProcessor 按 OTel 导出策略处理，不向业务响应暴露 Collector
-  细节；Run Store 与平台 Audit 仍是业务审计事实。
-- Release 快照冲突、评估结果漂移或幂等键漂移：稳定拒绝，要求修正发布输入。
-- 超过容量、事件数或输出大小：写入或返回有界失败，不允许无界降级。
+备份时协调停止Agent写入，保存SQLite主文件及WAL一致边界和原生HOME。采用新数据路径并允许旧Agent专用数据重置；业务数据库和文件必须保留。具体切换与回退见[迁移运维](../operations/dsh-agent-migration.md)。

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

@@ -1,5 +1,7 @@
 # AI Runtime 用量与运行报表
 
+> 2026-10-29：执行层现由[内置DSH](../architecture/embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 `system.ai-runtime` 为 `system.agent` 提供运行事实、模型用量和缓存覆盖的管理面。它读取
 canonical Agent Run 与每次 Provider Attempt 的独立报表投影，不把管理报表变成新的
 执行入口，也不以报表写入结果改写 canonical Run 终态。

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

@@ -1,5 +1,7 @@
 # Agent Runtime 接入
 
+> 2026-10-29：执行层现由[内置DSH](../architecture/embedded-dsh-integration.md)接管。下文涉及Python Direct Engine、旧安装/存储及OTEL配置的内容属于历史实现；当前启动、配置与限制以[迁移运维](../operations/dsh-agent-migration.md)为准。canonical API、业务长期Session和治理契约继续有效。
+
 ## 当前基线
 
 Windy 的服务端 Agent Runtime 由独立 Python Agent Server 承载，生产默认 Engine 是

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

@@ -0,0 +1,25 @@
+# DSH 技能与治理
+
+技能是可审查的工作方法和文件包，不授予工具、身份或数据权限。Windy后台治理DSH `SKILL.md`/ZIP，不依赖旧Agent Code任务或脚本执行器。
+
+## 管理与运行
+
+后台支持目录、详情、全部版本、共享范围、依赖、导入发布、停用和回滚。范围包括本人、部门和租户；读写均由Host构造的当前Scope约束。平台内置“平台工具查询”提供非案件示例；启动初始化不会覆盖已治理的后续版本或停用状态。
+
+- `GET /api/agent/skills`、`/:key`、`/:key/versions`：当前可读目录、正文及历史。
+- `POST /api/agent/skills`：导入SKILL.md或ZIP并发布新版本。
+- `POST /api/agent/skills/:key/disable|rollback`：停用或发布恢复历史内容的新版本。
+- 写请求必须携带`idempotency-key`和`expectedVersion`；回滚另携带目标`version`。正文类型由共享DTO约束。
+- `GET /api/agent/workbench/skills`：仅供当前原生身份读取可执行的已发布包；不授予管理权限。
+
+Feature是`system.agent-skill`，权限是`.read`、`.manage`、`.execute`。工具依赖必须与已注册工具的Feature/Permission一致，并逐次检查当前可用性。
+
+版本、包内容和幂等回执使用Repository+Drizzle持久化。变更先形成待审计回执，关键审计成功后才向运行时公开；重复请求复用回执，摘要漂移或版本竞争返回冲突。启动恢复未完成审计，避免崩溃后把未审计版本暴露给模型。读取审计只保存种类、Key、版本或数量，不保存技能正文。
+
+## 文件包与编辑
+
+SKILL.md必须是有效UTF-8，包含唯一YAML头的name、description和非空正文。ZIP有归档大小、展开大小、文件数和单文件上限；拒绝目录穿越、重复路径、链接、特殊文件、多个技能根和不受控YAML引用。具体上限以共享校验器和界面反馈为准。
+
+导入失败保留当前输入，保存期间阻止重复提交。关闭编辑容器、切换路由与刷新前按真实编辑基线确认，成功后才清理未保存状态。
+
+原生工作台的个人技能继续保存在当前工作区`.dsh/skills`。个人导入不产生组织发布身份。平台发布技能通过DSH公开Provider提供；每次发现/读取重新授权、比较版本摘要，附件按用户只读物化，停用或回滚撤下旧目录。已经发送给模型的历史上下文不能据此追溯消除。

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

@@ -21,6 +21,7 @@
     "speech:pins": "bun run scripts/provision-speech-readiness.ts",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
+    "dev:gateway": "bun run --cwd apps/windy-gateway start",
     "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",
@@ -58,15 +59,17 @@
     "release:candidate": "bun run scripts/release-candidate.ts",
     "release:verify:full": "bun run scripts/release-verify.ts --full",
     "test:packages:pack": "bun run scripts/platform-package-release.ts",
-    "test:agent": "uv run --directory apps/agent-server pytest",
+    "test:agent": "bun run --cwd apps/agent-server test",
     "test:document": "uv run --directory apps/document-server pytest",
     "test:speech": "uv run --directory apps/speech-server pytest",
     "test:embedding": "uv run --directory apps/embedding-server pytest",
-    "check:agent": "uv run --directory apps/agent-server ruff check . && uv run --directory apps/agent-server ruff format --check . && uv run --directory apps/agent-server mypy",
+    "check:agent": "bun run --cwd apps/agent-server typecheck",
     "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",
+    "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",
@@ -81,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 不支持环境别名");
+});