create-windy 0.1.0

package/template/docs/architecture/module-manifest-composition.md

@@ -0,0 +1,47 @@
+# Module Manifest 组合契约
+
+更新时间：2026-07-16。
+
+## 目标与边界
+
+Module Manifest 是模块公开能力的唯一声明 Interface；Server、Web 等宿主只提供具体 Implementation，并在 Composition Root 通过同一个 `validateModuleComposition` Seam 完成 fail-fast 校验。本批不实现业务搜索，只提供通用 Provider 注册位。
+
+Manifest 当前覆盖：
+
+- Feature、Permission、API Route、Admin Route 与菜单 Surface；
+- Migration 与 Schema Export 证据；
+- Scheduled Task、Agent Tool、Provider 与 Audit Action；
+- 模块依赖及版本元数据。
+
+## 不变量
+
+组合校验在运行时业务逻辑前执行，并拒绝：
+
+1. 缺失依赖、依赖循环及同类能力重复 Key；
+2. Menu、Admin Route、API、Task、Tool、Provider 对未知 Permission 或 Feature 的引用；
+3. Tool 对未知 Audit Action 的引用；
+4. Menu 与 Admin Route 路径或 Guard 漂移；
+5. 已声明 Route、Task、Tool、Provider 缺少宿主 Handler，或宿主注册未声明 Handler；
+6. Schema Export 没有对应 Migration ID 证据，或可执行 Migration 归属错误。
+
+同一个稳定能力基础 Key 仍可分别出现在 Feature、Permission 前缀、菜单和页面入口中；“重复”按能力类别判断，避免破坏项目既定 Key 语义。
+
+## 模块与 Adapter
+
+- `@windy/modules` 是深 Module：拥有声明类型、依赖排序、引用规则和组合验证，不依赖 Elysia 或 Vue。
+- `systemModuleFactories` 是 15 个平台模块的运行时目录；`systemFoundationModule()` 仅保留为兼容聚合视图，不再作为 Composition Root 中唯一的巨型平台模块。
+- 多个模块可以向同一菜单目录贡献入口；`composeModuleMenus()` 合并一致的目录壳，并在标题、类型、顺序或 Guard 漂移时 fail fast。
+- Server Adapter 提供 API Route、Task、Tool、Provider Handler Key；启动监听前验证。
+- Web Adapter 提供实际 Admin Route Key；构建测试验证页面、Guard 与 Manifest 一致。
+- 普通业务 Module 可以只声明 API、Task 等 Server 能力；`menus` 与 `adminRoutes` 为空时，Windy Web 不导入业务 package 或 Vue 页面。
+- Drizzle schema 的具体表定义仍在 `@windy/database`，Manifest 只公开模块 Schema Export 和历史 migration 证据，不复制数据库实现。
+
+这种边界允许宿主替换实现，同时保持 Manifest 的能力语义稳定。
+
+## 分批落地
+
+- 第一批：类型、声明级验证和失败回归。
+- 第二批（已完成）：Server 直接读取 Elysia 实际路由表、Scheduler definitions 和 Agent Tool Handler Registry，在 `listen` 与 Worker 启动前执行 fail-fast。无数据库开发模式下不会注册的密码管理与个人资料路由，由其实际注册函数导出 Implementation 描述，避免把条件装配误判成缺少代码实现。
+- 第三批（已完成）：Web 只注册页面组件、name 和 props，path、标题、Permission 与 Feature 由 Manifest Admin Route Adapter 生成；模块加载时校验所有 Admin Route 都有实现。License 恢复页的“已认证即可直访”作为 `directAccess: authenticated` 显式声明，Sidebar 可见性仍使用 Manifest Permission/Feature。
+
+每批都必须更新本文件与产品任务状态后再提交。

package/template/docs/architecture/object-storage.md

@@ -0,0 +1,65 @@
+# 通用文件与对象存储
+
+## 模块与 seam
+
+`@windy/storage` 是平台文件能力的唯一底层模块。业务模块只学习 `BlobStore` 接口：流式写入、流式打开和删除；文件名、MIME、上传会话、Owner、权限与审计不进入这个底层接口，由上层上传模块统一处理。
+
+`ArtifactRef` 使用 `blob_` 加 128 位随机值，不包含目录、租户或内容摘要，不能由业务主键推算。`ContentHash` 当前固定为 SHA-256。调用方可以声明大小和摘要，本地 Adapter 会在写入过程中验证；任何不一致都不会发布 Blob。
+
+## 本地 Adapter
+
+`LocalFileBlobStore` 逐块消费 Web `ReadableStream`，直接写入权限为 `0600` 的临时文件，同时累计字节数和 SHA-256。完成后执行文件同步和同文件系统 rename，再发布小型 JSON 元数据。读取返回文件流，不把 Blob 整体载入内存。
+
+目录结构按引用前缀分片：
+
+```text
+<root>/
+  .tmp/
+  blobs/<prefix>/blob_<random>.blob
+  blobs/<prefix>/blob_<random>.json
+```
+
+部署时 `root` 必须是仅 Server 运行账号可写的持久目录，不得直接暴露给 Web Server。生产下载只经过应用授权路由，不能把上述路径映射成公开静态目录。
+
+`BlobStore` 同时是未来 S3-compatible Adapter 的 seam。业务层不依赖云 SDK、bucket 或 presigned URL；后续 Adapter 必须保持相同的流式、摘要与不可猜引用语义。
+
+## 可续传上传
+
+`UploadService` 是上传生命周期的唯一入口，依据用途策略校验文件名、大小、MIME 与扩展名。图片用途还会在首个分片流经存储前嗅探 PNG、JPEG 或 WebP 魔数；嗅探最多保留签名所需的前 12 字节，不读取整个文件。
+
+客户端创建会话后，使用服务端返回的 `nextPartNumber` 和 `receivedByteSize` 顺序续传。相同编号、偏移、大小和摘要的重试是幂等操作；其它旧偏移或并发更新会返回冲突，客户端必须读取最新会话再继续。每个分片由 `BlobStore` 独立验证大小和 SHA-256。完成时按编号串联分片流，再次校验总大小和可选总 SHA-256，整个路径不拼装内存 Buffer。
+
+PostgreSQL 通过 `file_upload_sessions`、`file_upload_parts` 和 `file_metadata` 持久化会话进度及最终文件。分片提交使用 `received_byte_size + next_part_number` compare-and-set；最终 Blob 与 FileMetadata 只有数据库状态切换成功后才发布为完成状态。
+
+清理任务先删除已过期会话的分片和已过期文件，再将数据库仍引用的 `ArtifactRef` 集合交给 `LocalFileBlobMaintenance`。本地维护器只删除超过 grace period 的临时文件或未引用 Blob，避免与正在提交的上传竞争。生产应由 Scheduler 周期调用清理入口；grace period 默认一小时。
+
+## 授权下载与业务接入
+
+存储能力以 `system.storage` Feature 注册，上传和下载路由统一引用 Module Manifest 的权限：
+
+- `system.storage.create`：创建会话、查询续传位置、提交分片、完成或终止本人上传。
+- `system.storage.read`：下载本人文件。
+- `system.storage.manage`：在具备 read 的前提下跨 Owner 下载；跨 Owner 不改变文件归属。
+
+每次创建、完成、终止和授权下载都会记录稳定审计动作。文件过期在打开 Blob 前检查，即使 Owner 或 manage 用户也不能绕过；数据库元数据与 Blob 大小或摘要不一致时返回内容不可用，不流出部分内容。响应体直接使用 `BlobStore.open()` 返回的流，并带有长度、SHA-256、ETag 和安全文件名。
+
+Logo 使用 `branding-logo` 上传策略。匿名 `/api/platform/files/:id` 只允许读取当前品牌设置实际引用、且 purpose 为 `branding-logo` 的文件，不能把一个不可猜引用自行升级为公开访问。bulk import/export 的结果和失败 artifact 通过同一 `BlobStore` 保存，数据库只持久化 artifact ref、摘要、大小和留存元数据；下载与到期清理复用统一端口。导入 source 暂时保留在幂等任务事务内，避免任务已创建但 source Blob 未绑定的半成品状态。
+
+## 运行配置
+
+- `WINDY_BLOB_DRIVER`：当前生产 Adapter 为 `local`；配置未知驱动时启动失败，不静默回退。
+- `WINDY_STORAGE_ROOT`：本地持久目录，默认 `.data/storage`。Compose 使用独立 named volume 挂载 `/app/data/storage`。
+- S3-compatible 支持保留在 `BlobStore` seam；当前不强制安装云 SDK。未来 Adapter 必须保持流式读写、服务端摘要验证、不可猜引用、明确删除与损坏语义，不能让业务模块学习 bucket/key。
+
+## 故障语义
+
+- 声明大小或 SHA-256 不一致：拒绝并删除临时文件。
+- 元数据丢失：按不存在处理；元数据存在但内容缺失或大小不符：报告损坏，不返回部分文件。
+- 删除为幂等操作；第一次存在时返回 `true`，重复删除返回 `false`。
+- 进程在 Blob 发布与元数据发布之间退出时可能产生孤儿内容；上传生命周期模块基于过期时间、引用集合与 grace period 清理。
+
+## 当前切片
+
+- F1：Blob 端口、SHA-256、随机引用和本地流式 Adapter 已完成。
+- F2：上传会话、分片续传、文件元数据、校验和清理已完成。
+- F3：服务端授权下载、审计、bulk artifact 与 Logo 接入已完成。

package/template/docs/architecture/search-provider-protocol.md

@@ -0,0 +1,59 @@
+# SearchProvider 协议与治理边界
+
+## 目标
+
+平台通过一个稳定的 `SearchService` 聚合业务搜索结果，但不读取业务模块 Repository，也不把用户输入转换成跨模块 SQL。业务模块通过 Manifest 声明 `kind: "search"` 的 Provider，并提供同 Key、同版本的 Handler。Composition Root 启动时要求声明与实现一一对应，未知 Handler、缺失 Handler、重复 Key、协议版本或 Provider 版本漂移都会 fail-fast。
+
+默认部署不引入 OpenSearch、Elasticsearch 或其它外部搜索引擎。小数据量模块可以实现 Repository Provider；将来若替换为可重建索引 Provider，平台协议、调用方与业务详情授权边界不变，业务数据库仍是事实源。
+
+## 深模块边界
+
+`SearchService` 是宿主唯一需要调用的搜索边界。它负责：
+
+- 从 Module Manifest 发现 Provider，按强类型配置启用或停用，并报告版本和健康状态；
+- 先按目标 Feature、License 与 RBAC 裁剪 Provider，再允许请求的 `providerKeys` 进一步缩小集合；客户端不能启用、扩大或探测未授权 Provider；
+- 并发执行 Provider，并在单 Provider 超时、异常或非法响应时隔离失败，返回分组结果、部分失败与耗时观察值；
+- 维护分页游标、按服务端 Actor 限流，并用 Manifest 中的业务路由模板构造深链；Provider 不能注入任意 URL；
+- 只接受脱敏标题和脱敏摘要，拒绝携带 `title`、`description` 或 `raw` 等明文字段的 Provider 响应；
+- 查询审计只记录 SHA-256 摘要、长度和 Provider Key；结果访问审计只记录分组数、命中数和部分失败状态。
+
+Provider 只负责在自身模块边界内执行搜索。它接收平台从已认证 Actor、有效角色、组织和 nominal `ScopeContext` 计算出的 `SearchExecutionContext`。查询请求没有 actor、角色、组织、租户或数据范围字段，因此客户端只能提供查询词、分页限制、游标和用于缩小集合的 Provider Key。业务 Provider 必须把 `ScopeContext` 编译进 Repository predicate，让搜索、count 和分页在同一查询中执行范围约束；先查全量再在内存过滤不符合协议。
+
+## 权限与数据泄漏边界
+
+使用统一搜索入口的权限和读取目标资源的权限是两层独立判定：
+
+1. Server API 路由使用 `system.search.read` 与 `system.search` 检查入口准入。
+2. `SearchService` 对每个 Provider 再检查其 Manifest 声明的目标 `permissionKey` 和 `featureKey`。
+3. Provider 使用服务端 `ScopeContext` 在 Repository 查询阶段缩小实体集合。
+
+因此拥有搜索入口权限不代表可以搜索所有资源；缺少目标权限的 Provider 不出现在发现结果中，也不会暴露空分组、健康状态或错误差异。请求指定未知、已停用或未授权 Provider 时统一返回不可用错误，避免把 Provider 存在性变成权限探针。
+
+搜索结果仅是脱敏发现投影，不授予明文或导出权限。每个命中显式声明：明文详情继续委托目标资源接口授权，受治理导出继续委托统一导出能力。两条后续链路属于 P0-7 的资源访问和导出治理，不在搜索协议内复制实现。
+
+## 稳定 DTO
+
+- `SearchRequest`：`query`、`limit`、版本化聚合 `cursor`、可选 `providerKeys`。
+- `SearchResultPage`：按 Provider 分组的脱敏 `hits`、下一页游标、`partial`、通用失败和观察值。
+- `SearchProvider`：稳定 Key、实现版本、可中止的 `search` 与 `health`。
+- `SearchProviderDefinition`：协议版本、实现版本、标签、默认启用状态、目标 Feature/Permission 和业务深链模板。
+
+游标只保存各 Provider 的不透明分页状态，不包含授权快照，也不能替代每次请求重新执行 Feature、RBAC 与 dataScope 判定。非法或未知版本游标会返回稳定的 `INVALID_CURSOR`。
+
+## Server API 与启动配置
+
+- `GET /api/search/providers` 只返回入口与目标资源均已授权的 Provider 目录、版本和健康状态，不接收查询词。
+- `POST /api/search` 只从 JSON body 读取 `SearchRequest`。平台不提供 `GET /api/search?q=...`，避免查询词进入 URL、代理访问日志和浏览器历史。
+- 两条路由先执行独立的 `system.search` Feature 与 `system.search.read` Permission Guard；通过入口后，Core 再逐个执行目标资源 Guard。`INVALID_REQUEST` / `INVALID_CURSOR`、`SCOPE_DENIED`、`PROVIDER_UNAVAILABLE` 和 `RATE_LIMITED` 分别稳定映射为 400、403、404 和 429。
+- `SEARCH_PROVIDER_KEYS` 是逗号分隔的启动白名单；未配置时按 Manifest 的 `enabledByDefault` 启用，显式空字符串关闭全部 Provider，未知、重复或非法 Key 使启动失败。
+- `SEARCH_PROVIDER_TIMEOUT_MS`、`SEARCH_HEALTH_TIMEOUT_MS` 允许 10-5000 毫秒；`SEARCH_MAX_REQUESTS_PER_MINUTE` 允许 1-300。非整数或越界配置使启动失败，不能被静默截断或钳制。
+
+Composition Root 把 Server 实际注册的搜索 API 与 Provider Handler Key 一并交给 Module Composition 校验。没有业务 Provider 声明的项目允许 Core 以空 Registry 启动；只要 Manifest 与 Handler 不一致，启动就在监听端口前失败。
+
+## 当前验证范围
+
+协议单元测试覆盖声明/实现/版本 fail-fast、启停与健康发现、目标权限裁剪、客户端不能扩大服务端身份和组织范围、分组与游标、Manifest 深链、明文响应拒绝、故障/超时隔离、部分失败、按 Actor 限流，以及审计中不出现原始查询词。Server API 测试另行覆盖入口权限先行、目标权限二次裁剪、Feature 关闭、只接受 POST body、稳定错误状态和直接 API 伪造身份/部门不能扩大 scoped Repository 结果。
+
+示例 Work Order 已注册 `work-order.ticket.search`，Provider 只调用 `WorkOrderService.list`，后者把查询、count、分页与服务端 dataScope 一起交给 scoped Repository；测试会让裸 `Repository.list` 主动抛错，并确认本人范围不会返回其他负责人的匹配工单。另一个实现相同 Key/版本的测试 Provider 可以在不修改 Core 的情况下替换工单 Adapter。
+
+生成器默认产物保留 Work Order Provider；`--no-example` 完整移除业务 Provider、schema 与 migration 引用，但保留搜索 Core、Guarded API 和类型化空 Registry。`bun run test:create-windy` 对两种生成物执行真实安装、typecheck、test、build 和 Server 启动，并显式断言该移除边界；`bun run test:db:data-scope` 在真实 PostgreSQL 中分别验证核心用户资源与可删除工单资源的 Repository 级范围约束。

package/template/docs/development/crud-generator.md

@@ -0,0 +1,57 @@
+# CRUD 代码生成器
+
+OPS-03 提供一个基于 canonical CRUD 元数据的保守生成器。它生成可编译、可测试的独立模块包，不自动修改平台 schema 导出、路由注册或 Drizzle migration，因此不会在一次生成命令中悄悄改变生产数据库。
+
+## 使用方式
+
+```bash
+bun run generate:crud -- \
+  --spec examples/inventory-item.crud.json \
+  --output packages/inventory
+bun install
+bun run --cwd packages/inventory typecheck
+bun run --cwd packages/inventory test
+```
+
+输出目标必须不存在。生成器先按封闭的 canonical 字段集合验证完整元数据，在同级临时目录写完全部文件后再原子重命名；未知字段、目标已存在、字段名/列名重复、路径格式错误或路径逃逸、保留审计字段被占用、非字符串字段声明全文搜索时都会在生成前直接失败。它不会合并或覆盖人工代码。
+
+生成包包含：
+
+- domain 类型和严格 Zod create/update DTO；
+- PostgreSQL canonical Drizzle schema；
+- 模块私有 Repository 端口和 Drizzle 实现；
+- 仅依赖 Repository 接口的 service；
+- read/create/update/delete 逐动作权限路由、列表与详情精确接口绑定、关键写审计和 Guard port；
+- Module Manifest、Feature、可选允许 License 版本集合和 API 权限绑定；生成业务模块默认不声明 Windy 菜单或 Admin Route；
+- service 与路由 Guard/审计单元测试。
+
+所有生成文件均受 350 行上限回归保护。仓库测试会在 `.tmp/crud-generator` 生成 fixture，临时连接当前 workspace 依赖，实际执行 `tsc` 和 `bun test`，结束后清理；fixture 不加入 workspace、不生成 migration。
+
+## 接入平台
+
+生成完成后必须人工完成以下显式接线并接受代码评审：
+
+1. 把生成 schema 从业务模块公开出口接入 `@windy/database` canonical schema，再执行 `bun run db:generate` 并审阅 migration diff。
+2. 在 Server composition root 创建模块自己的 Drizzle Repository，注入 service；业务模块不得读取其它模块 Repository。
+3. 为生成的 `CrudAccessPort` 提供平台 Adapter。Adapter 必须调用现有 `evaluateAccessGuards`，按 `license → license-version → dynamic feature → permission` 顺序执行策略；没有商业版本限制的基础功能省略 `license-version`；不能在生成模块中复制 Guard 逻辑。
+4. 把 `CrudAuditPort` 接到平台可靠审计 writer，并保留生成器为 create/update/delete 指定的 `critical` 策略；随后注册生成的 Module Manifest 和 routes。
+5. 业务页面应在独立业务应用中组合自己的组件；只有明确属于平台管理控制面的能力，才可另行声明 Admin Route 并在 Windy Web 提供实现。生成器不生成 Vue 页面。
+
+生成的 schema 仅使用 Drizzle PostgreSQL canonical 类型。达梦、人大金仓和 RuoYi 旧库运行时受控写入不在本任务范围内。
+
+## 元数据约束
+
+当前 `schemaVersion` 固定为 `1`，支持 `string`、`integer`、`boolean`、`datetime` 和 `json` 字段。字符串必须声明 `maxLength`；`id/status/created*/updated*/deleted*` 是平台保留字段。权限固定拆为：
+
+- `<module>.<resource>.read`
+- `<module>.<resource>.create`
+- `<module>.<resource>.update`
+- `<module>.<resource>.delete`
+
+这使接口权限总览可以从已注册 manifest 精确展示每个 HTTP 动作的权限、Feature 和允许的 License 版本，不需要扫描源码猜测。
+
+## 系统接口权限目录
+
+`GET /api/system/operations` 的 `systemInterfaces` 只消费 Server composition root 已注册的 `ModuleManifest[]`。每条记录包含模块、HTTP method/path、权限 Key、匿名策略、Feature、由业务应用为 Feature 声明的允许 License 版本，以及实际 Guard 顺序。相同 method/path 重复绑定或接口引用未注册 Feature 时 fail closed，避免总览展示与运行策略不一致。
+
+Web 运维总览按该目录展示 `License → License 版本 → Feature → RBAC` 链路。Feature 控制面本身为了允许开发角色恢复被关闭的功能，不绑定业务 Feature，因此会如实展示为 `License → RBAC`。健康检查、Swagger 或仅做会话认证而未声明权限 Key 的入口不会伪装成 manifest 权限绑定。

package/template/docs/license/license-offline-activation-code.md

@@ -0,0 +1,67 @@
+# W1 分组离线激活码
+
+## 产品边界
+
+W1 是同一份 `SignedLicenseV1` 的离线传输编码，用于客户电脑没有网络、摄像头且文件传输不便时手工录入。它不是联网兑换短码，不改变授权字段、签名对象或安装规则，也不会建立第二套 License 状态。
+
+签发中心仍保留 `.license.json` 下载。操作员可以针对任一签发记录查看 W1，按段抄写或复制完整文本。客户 License 页面既可上传文件，也可逐段输入或整段粘贴 W1；两条入口最终都将 canonical `SignedLicenseV1` 交给同一个服务端安装入口。
+
+客户电脑不扫描 License 二维码，不要求摄像头。W1 解码和安装均不访问厂商服务器。
+
+## 确定性编码
+
+编码顺序固定如下：
+
+1. 用现有严格解析器验证 `SignedLicenseV1`，并生成 canonical JSON。
+2. 将 V1 固定字段映射为有固定位置的紧凑 tuple；`formatVersion=1` 和 `algorithm=ED25519` 由 W1 格式固定，不在 tuple 中重复。
+3. 将 64 字节 ED25519 签名从 Base64 还原为原始字节，避免 Base64 的传输膨胀；这不改变签名内容。
+4. 使用 zlib level 9 确定性压缩紧凑 tuple。
+5. 生成信封：`4 字节 tuple 原文长度 + zlib 数据 + 64 字节签名 + 4 字节 canonical JSON CRC32`。
+6. 使用 Crockford Base32 编码信封。
+7. 每段承载最多 25 个 Base32 数据字符，并附加 2 个依赖段序号的校验字符；最终以 `W1-` 为前缀，只在段之间加入连字符。
+
+签发页面把每段内部再按 5 个字符做视觉分组，并单独标出末尾 2 个段校验字符。实际编码不为每个 5 字符小组增加校验位，避免明显放大手工录入长度。
+
+## 输入和错误处理
+
+- 输入不区分大小写，并忽略空格、换行和连字符。
+- `O` 只按 `0` 归一化，`I` 和 `L` 只按 `1` 归一化；不会尝试猜测或修复其他字符。
+- 段校验失败返回具体段号，单字符数据错误或校验字符错误不会进入安装流程。
+- 截断、未知版本、非法字符、zlib 损坏、tuple 长度/类型错误和整体 CRC 错误均稳定拒绝。
+- CRC32 和段校验只用于发现抄写/传输错误，不是安全边界。解码后的完整 License 必须继续通过 ED25519、公钥、产品、设备码、到期时间和防降级校验。
+- 解码成功只生成 canonical License JSON；服务端仍使用同一个串行化 `LicenseInstaller` 完成防降级、原子替换和摘要审计。失败不会覆盖 current。
+- 普通日志、签发审计和客户安装审计不保存完整 W1。签发端查看 W1 只记录 License ID 和导出动作；客户安装审计只保存 canonical License 摘要、稳定结果和非敏感标识。
+
+### 安全长度上限
+
+常见 W1 不足 1 KiB。实现为正常字段增长保留了数十倍余量，同时在分配、解析和解压之前执行以下固定上限：
+
+| 层次                         |   最大长度 | 拒绝时机                 |
+| ---------------------------- | ---------: | ------------------------ |
+| 原始打印/粘贴文本            | 32 Ki 字符 | 大小写转换和去分隔符之前 |
+| 去空白、连字符后的规范化文本 | 28 Ki 字符 | Base32 解码之前          |
+| 信封内 zlib 数据             |     16 KiB | 解压之前                 |
+| 解压后的紧凑 tuple           |     64 KiB | 增量解压过程中           |
+| 安装或签发 JSON 请求体       |     64 KiB | JSON 解析之前            |
+
+解压器以小块增量消费压缩数据，累计输出一旦超过信封声明长度或 64 KiB 上限便立即停止，不会先完整分配异常膨胀的输出。HTTP 入口先校验 `Content-Length`，再对没有长度或声明不可信的请求流逐块计数；声明值与实际字节数不一致时同样拒绝。超限、JSON 损坏等错误只返回稳定中文原因，不回显 W1 或请求正文。
+
+## 长度基准
+
+下表由当前固定 V1 测试向量测得。`完整编码字符`包含 `W1`、段分隔连字符和校验字符；Base32 本身不包含易混的 `I/L/O/U`。V1 现在只携带单一 License 版本标记，不再包含数量可变的能力列表。
+
+| 样本                         | canonical JSON 字节 | 段数 | 完整编码字符 |
+| ---------------------------- | ------------------: | ---: | -----------: |
+| 仓库固定 V1 版本标记向量 |                 673 |   20 |          519 |
+
+因此 W1 仍然只是无 U 盘、无摄像头时的兜底入口，不能承诺 150～300 字符。仅 64 字节 ED25519 签名转为 Base32 就需要约 103 个数据字符，V1 还签入客户、项目、合同、设备、时间、公钥 ID 和 License 版本等完整展示字段。
+
+若未来必须进一步缩短，应设计新的签名格式版本，由产品明确哪些展示字段可以不再进入签名正文，或使用更紧凑的稳定标识与二进制字段编码；不得删除现有 V1 字段后仍冒充 V1，也不得改为联网兑换、只校验 CRC 或削弱 ED25519。
+
+## 接口与运维
+
+- `GET /api/licenses/:id/activation-code`：需要 `license.record.read`，返回 `W1`、分段和字符数，设置 `Cache-Control: no-store`，并复用 License 下载事件和敏感导出审计。
+- `POST /api/license/runtime/install`：既接受原有 `{ license }`，也接受 `{ activationCode }`。W1 解码后只把 canonical License 传给现有安装器。
+- 签发页面和客户页面都不把 W1 写入浏览器日志。复制能力仅在操作员明确点击后调用系统剪贴板。
+
+W1 的压缩算法、tuple 字段顺序、信封结构、Base32 字母表和分段校验都属于版本协议；任何不兼容修改必须使用新的显式前缀，不能改变既有 W1 解码结果。

package/template/docs/operations/observability.md

@@ -0,0 +1,50 @@
+# 运行时可观测性
+
+本页定义 P0 生产运维基线中的探针、结构化日志、指标和关联标识契约。它描述的是应用边界，不代表反向代理、TLS、告警平台或客户基础设施已经验收。
+
+## 存活与就绪探针
+
+存活探针只回答进程是否仍能处理 HTTP，不访问数据库或外部服务；就绪探针用于决定是否接收流量，会检查当前服务启动所需的依赖。探针失败只返回稳定状态，不回显异常、连接串或上游响应正文。
+
+| 服务    | Liveness        | Readiness        | 兼容入口          | 就绪条件                                                               |
+| ------- | --------------- | ---------------- | ----------------- | ---------------------------------------------------------------------- |
+| Server  | `GET /api/live` | `GET /api/ready` | `GET /api/health` | PostgreSQL 已配置且可查询；显式非生产内存模式允许显示 `not-configured` |
+| Web     | `GET /-/live`   | `GET /-/ready`   | 无                | `dist/index.html` 存在且 Server `/api/ready` 返回成功                  |
+| License | `GET /api/live` | `GET /api/ready` | `GET /api/health` | PostgreSQL License schema 可用                                         |
+| Signing | `GET /live`     | `GET /ready`     | `GET /health`     | Vault 可用、已初始化且未 sealed                                        |
+
+`/api/health` 和 `/health` 只为已有调用方保留；新编排必须分别使用 liveness 和 readiness。Dockerfile 的 `HEALTHCHECK` 使用 readiness；根目录开发 Compose 也用 readiness 控制服务依赖，但它仍然不是生产编排。
+
+Server readiness 同时返回审计 writer 状态，便于对 `degraded`、队列积压或丢弃计数告警。审计降级当前不会自动把实例摘流；关键写入仍由业务 Guard fail closed，处置方式见[平台审计可靠写入](../platform/audit-reliability.md)。
+
+## Request 与 Job 关联
+
+Web、Server、License 和 Signing 接受 `x-request-id`。只保留 1 至 128 位的 ASCII 字母、数字、点、下划线和连字符；缺失或非法值会替换为新 UUID，并在响应 `x-request-id` 中返回。Web 同源代理会把同一值转发给 Server，因此浏览器错误响应、Server 完成日志和审计事件可使用同一标识定位。
+
+后台调度使用一次触发链的 `requestId` 和单次执行的 `runId`：审计事件保存两者，聚合指标只记录结果分类，不把任一标识放进 metric label。业务 handler 如调用外部系统，应继续透传当前关联标识，并保持敏感头与正文不落日志。
+
+## 结构化日志
+
+应用启动、运行模式警告和 HTTP 完成事件使用单行 JSON。HTTP 完成事件的稳定字段为：
+
+- `timestamp`、`level`、`event`、`component`；
+- `requestId`、`method`、`statusCode`、`durationMs`；
+- Server 可额外记录粗粒度 `actorType`，不记录用户或资源 ID。
+
+请求完成日志禁止记录完整 URL、query、请求或响应 body、Cookie、Authorization、Secret、连接串和原始异常。需要增加字段时，必须先判断其基数和敏感性，并补充防泄漏测试。生产日志采集器应按 JSON 字段解析，按 `requestId` 关联，不依赖自由文本。
+
+## Server 指标
+
+`GET /api/metrics` 输出 Prometheus text format，并设置 `Cache-Control: no-store`。当前指标包括：
+
+- 进程 uptime 和 RSS；
+- 活跃请求数、按安全 HTTP method 和状态码分类的完成计数、无路由 label 的耗时汇总；
+- 调度 tick 次数，以及 `scheduled`、`retried`、`blocked`、`failed` 结果计数。
+
+指标不使用 URL、route parameter、request ID、run ID、用户 ID 或资源 ID label，避免泄密和无界基数。该入口当前没有独立公网认证层；生产反向代理和网络策略必须只允许内部监控系统访问，不能直接暴露到互联网。
+
+## 当前验证状态
+
+已验证：共享关联标识校验、四个服务的 liveness/readiness 分离、Server 指标格式、Server/License 请求完成日志字段、Web 到 Server 的标识透传，均有 Bun 单元或边界测试；工作区 typecheck 和 Oxlint 已通过。Dockerfile 已声明 readiness `HEALTHCHECK`。
+
+尚未由本页证明：生产 Compose、新环境部署、备份恢复、升级回滚、原生 Linux amd64 runner、告警规则、长稳运行、多实例和大容量。这些项必须由后续生产恢复演练和目标环境记录单独闭环；Docker Desktop 或 QEMU 上的 amd64 运行不能写成原生 Linux amd64 已认证。

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

@@ -0,0 +1,37 @@
+# Agent Tool 注册与执行
+
+## 当前状态
+
+Server 端已提供 Agent Tool 的最小闭环：
+
+- 工具定义来自模块 manifest 的 `tools` 字段。
+- `GET /api/agent/tools` 返回已注册工具和当前请求是否有权限。
+- `POST /api/agent/tools/:key/execute` 执行工具。
+- 执行前使用 Permission Guard 校验 `permissionKey`。
+- 权限拒绝记录 `security.denied` 审计事件。
+- 执行成功记录 `agent.tool.execute` 审计事件。
+
+OpenAPI 文档由 `@elysiajs/swagger` 提供，随 Server 启动自动暴露。
+
+## 当前工具
+
+- `system.users.list`：查询用户。
+- `system.features.list`：查询功能开关。
+- `system.audit.list`：查询审计日志。
+
+## 开发态鉴权
+
+开发态可用：
+
+```text
+Authorization: Bearer dev-admin-token
+```
+
+该 token 来自内存运行时上下文，只用于本地闭环验证，不是生产登录体系。
+
+## 当前边界
+
+- 工具执行复用系统资源 Repository；未配置 `DATABASE_URL` 时使用内存仓储，配置后使用 Drizzle 仓储。
+- 工具参数当前只支持基础分页参数。
+- 审计事件写入内存 sink；配置 `DATABASE_URL` 后会通过有界重试写入 PostgreSQL `audit_logs`，持续失败会增加计数并输出告警，审计查询优先读取该表。详细降级语义见 [平台审计可靠写入](./audit-reliability.md)。
+- 后续应继续完善 Agent Tool 的结构化输入 schema 和执行结果追踪。

package/template/docs/platform/audit-reliability.md

@@ -0,0 +1,95 @@
+# 平台审计可靠写入
+
+## 目标与边界
+
+平台普通审计统一通过可靠写入器进入 PostgreSQL `audit_logs`。本设计只处理平台运行时审计，不改变 License Authority 的 `license_events` 追加式不可变事件模型；后者仍由签发领域事务保证，不进入本地恢复队列。
+
+本次不新增数据库表或 migration：`audit_logs.id` 已是事件唯一标识，恢复重放通过 `ON CONFLICT DO NOTHING` 保持幂等。PostgreSQL 不可用时，关键安全事件写入独立的本地恢复文件，避免恢复队列与主库发生同故障域失效。
+
+## 两类写入策略
+
+| 策略     | 典型事件                                                                                                  | PostgreSQL 持续失败后的行为                                                    |
+| -------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| 普通审计 | 普通 CRUD、导入导出、Agent Tool 执行、权限拒绝                                                            | 业务继续；保留进程内事件；增加失败和丢弃计数；记录降级告警                     |
+| 关键审计 | 登录/退出/密码和会话操作、用户与角色变更、Feature Flag 开关、License 资源变更、License 上传与损坏文件恢复 | 写入本地原子恢复队列后业务可继续；数据库和恢复队列都不可用时抛错并 fail closed |
+
+自动调度因同一个 Feature、License 或权限原因持续被拒绝时，仅在首次进入该拒绝状态时写入一条 `task.execute / denied`；相同任务恢复执行后，后续再次被拒绝会重新记录。人工触发属于独立的用户安全行为，仍逐次记录 `security.denied`。这样保留状态变化信号，同时避免高频任务用重复拒绝事件淹没业务审计。
+
+批量任务派发器每 5 秒轮询一次。定时执行返回 `claimed: false` 代表没有业务任务可领取，Scheduler 完成并立即丢弃这条 idle run，也不写 `task.execute` 审计；人工触发即使没有领取任务仍保留执行历史和 `task.trigger` / `task.execute`，真实领取、失败、重试和 Guard 拒绝同样完整留痕。idle 判定由任务定义显式声明，普通任务不会自动套用。
+
+审计页面使用操作者、动作和时间三个选择控件。操作者候选来自最近 100 条审计记录，动作候选来自 `@windy/shared` 的稳定动作目录，并以中文名称和说明展示；筛选请求继续传递稳定 action key。时间选择按最近 24 小时、7 天或 30 天换算为 ISO `occurredAfter`，内存与 PostgreSQL Reader 使用同一时间边界，非法时间值返回 `400 INVALID_AUDIT_TIME_RANGE`。
+
+常规审计列表在服务端固定排除 `system_scheduler` 执行身份产生的日志，客户端不能构造参数绕过；调度执行结果统一到定时任务的执行历史查看。审计导出提供“包含定时器日志”选项，默认关闭，只影响本次导出，不改变页面列表状态。
+
+动作列直接显示中文动作名，并使用 shadcn-vue / Reka UI Tooltip 零延迟展示稳定 action key、动作说明、操作对象和相关上下文。非空通用资源搜索记录 `data.search`，metadata 包含查询内容、资源和匹配数；审计列表自身不递归记录搜索。自由文本可能包含手机号或邮箱，因此部署方应把审计访问权限、保留期和导出权限视为敏感数据治理边界；默认字段名脱敏不等于自由文本内容脱敏。
+
+每次 PostgreSQL 写入默认最多尝试 3 次。重试间隔按指数增长，并受最大间隔约束，不会无限重试或无限阻塞请求。恢复队列也有最大条数；队列已满等同于队列不可用，关键动作会失败。
+
+License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和失败原因，不保存 License 正文或签名正文。可靠写入器还会在进入内存、PostgreSQL 或恢复文件前递归脱敏，默认覆盖 `password`、`token`、`secret`、`authorization`、`cookie`、`license`、`signature` 和 `privateKey` 等字段名；`AUDIT_REDACT_FIELDS` 只能追加字段，不能取消默认保护。
+
+这里的 fail closed 精确定义为请求不会返回业务成功；它不表示业务 Repository 写入与审计落库/本地文件天然处于同一原子事务。现有变更路径可能先完成业务写入再记录成功审计，因此数据库与恢复队列同时失败时，调用方必须先查询最终业务状态，再按幂等语义决定是否重试。需要强原子性的领域事实仍应像 License Authority 一样在领域事务内写追加事件，而不是依赖平台恢复队列补足事务边界。
+
+## 恢复与幂等
+
+关键事件在 PostgreSQL 持续失败后写入 `WINDY_AUDIT_QUEUE_FILE`：
+
+1. 队列文件使用同目录临时文件写入后原子重命名，文件权限为 `0600`。
+2. Server 启动、以及后续任一审计写入恢复成功时，会顺序重放队列。
+3. PostgreSQL 以事件 ID 幂等插入，连接超时后即使数据库实际已提交，重放也不会生成重复事件。
+4. 只有成功持久化的前缀会从队列移除；首次失败事件及其后续事件继续保留。
+
+恢复文件所在目录必须挂载到持久卷，并只允许 Server 运行账号访问。不要把它放到容器临时层、共享静态目录或备份公开目录。
+
+## 可观测状态
+
+`GET /api/health` 的 `audit` 字段返回非敏感运行状态：
+
+```json
+{
+  "state": "degraded",
+  "attempted": 12,
+  "persisted": 10,
+  "failedAttempts": 5,
+  "retries": 3,
+  "queued": 1,
+  "dropped": 1,
+  "lastFailureAt": "2026-07-10T08:00:00.000Z",
+  "lastSuccessAt": "2026-07-10T07:59:00.000Z",
+  "alert": "关键审计已进入可恢复队列"
+}
+```
+
+- `failedAttempts` 是底层尝试失败次数，包括随后成功的重试。
+- `retries` 是已经执行的重试次数。
+- `queued` 是当前仍待恢复的关键事件数。
+- `dropped` 是 PostgreSQL 持续失败后未进入持久队列的普通事件数。
+- `state=degraded` 或 `queued/dropped > 0` 应触发运维告警。
+
+进入降级状态时 Server 同时写入结构化 error 日志，日志只包含上述状态，不包含事件正文。
+
+## 环境变量
+
+| 变量                        | 默认值                             | 说明                                        |
+| --------------------------- | ---------------------------------- | ------------------------------------------- |
+| `WINDY_AUDIT_MAX_ATTEMPTS`  | `3`                                | 单次事件总尝试次数，包含首次写入，最大 `10` |
+| `WINDY_AUDIT_RETRY_BASE_MS` | `50`                               | 指数退避基础间隔，最大 `60000` 毫秒         |
+| `WINDY_AUDIT_RETRY_MAX_MS`  | `500`                              | 单次重试最大等待时间，最大 `60000` 毫秒     |
+| `WINDY_AUDIT_QUEUE_FILE`    | `./data/audit/recovery-queue.json` | 关键事件恢复文件                            |
+| `WINDY_AUDIT_QUEUE_SIZE`    | `1000`                             | 关键恢复队列最大事件数，上限 `100000`       |
+| `AUDIT_REDACT_FIELDS`       | 空                                 | 在默认敏感字段之外追加的逗号分隔字段名      |
+
+生产环境未配置审计持久化 writer 时，关键动作不会回退为内存 best-effort，而是直接 fail closed。普通审计仍维持业务可用性，但健康状态会显示写入失败。
+
+恢复文件只适用于单实例独占写入。多副本部署必须为每个 Server 实例配置独立持久卷和独立 `WINDY_AUDIT_QUEUE_FILE`，再在监控侧聚合各实例状态；多个进程共享同一个恢复文件没有跨进程锁，会产生覆盖风险。
+
+## 故障处置
+
+1. 检查 `/api/health` 的 `audit` 状态和 Server 的“审计持久化进入降级状态”日志。
+2. 检查 PostgreSQL 连接、连接池容量、`audit_logs` 表和磁盘容量。
+3. 确认恢复文件所在持久卷可写、权限为 Server 账号私有，且队列未达到上限。
+4. 修复 PostgreSQL 后执行一个普通的已审计请求；写入成功会触发队列恢复。也可以重启 Server，在启动阶段恢复。
+5. 只有 `queued=0` 且状态恢复为 `healthy` 后才解除告警。`dropped` 是累计计数，不会自动归零，应结合故障窗口内的进程内事件和业务日志进行人工补查。
+
+## 验证覆盖
+
+自动测试覆盖瞬时故障后成功、退避上限、普通事件持续失败、关键事件入队、数据库恢复重放、数据库与队列同时失败、队列内容深层脱敏、License 损坏文件恢复上传入队，以及 PostgreSQL 事件 ID 幂等重放。真实 PostgreSQL 集成测试使用 `AUDIT_TEST_DATABASE_URL` 显式启用。