create-windy 0.2.34 → 0.3.0

package/template/apps/web/src/services/notification-api.webtest.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import {
+  favoriteNotification,
+  getNotificationAudienceOptions,
+  getNotificationPreference,
+  listNotificationRevisions,
+  listNotifications,
+  unfavoriteNotification,
+  updateNotificationPreference,
+  updateNotification,
+} from "./notification-api";
+
+const mocks = vi.hoisted(() => ({
+  request: vi.fn(async () => ({ items: [], total: 0, page: 1, pageSize: 10 })),
+}));
+
+vi.mock("./http", () => ({ apiRequest: mocks.request }));
+
+describe("普通用户通知 API", () => {
+  beforeEach(() => {
+    mocks.request.mockClear();
+  });
+
+  test("旧分页调用保持原 URL 兼容", async () => {
+    await listNotifications(2, 20);
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/notifications?page=2&pageSize=20",
+    );
+  });
+
+  test("关键词、分类、已读和收藏筛选统一编码到服务端查询", async () => {
+    await listNotifications(3, 15, {
+      q: "维护 窗口",
+      category: "系统/安全",
+      read: "unread",
+      favorite: false,
+    });
+
+    expect(mocks.request).toHaveBeenCalledWith(
+      "/notifications?page=3&pageSize=15&q=%E7%BB%B4%E6%8A%A4+%E7%AA%97%E5%8F%A3&category=%E7%B3%BB%E7%BB%9F%2F%E5%AE%89%E5%85%A8&read=unread&favorite=false",
+    );
+  });
+
+  test("收藏与取消收藏使用显式幂等方法", async () => {
+    await favoriteNotification("notice/1");
+    await unfavoriteNotification("notice/1");
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/notifications/notice%2F1/favorite",
+      { method: "PUT" },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/notifications/notice%2F1/favorite",
+      { method: "DELETE" },
+    );
+  });
+
+  test("管理端修改公告并分页读取版本历史", async () => {
+    const input = {
+      title: "修改公告",
+      summary: "修改摘要",
+      content: "修改正文",
+      category: "系统",
+    };
+    await updateNotification("notice/1", input);
+    await listNotificationRevisions("notice/1", 2, 20);
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/system/notifications/notice%2F1",
+      { method: "PUT", body: JSON.stringify(input) },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/system/notifications/notice%2F1/revisions?page=2&pageSize=20",
+    );
+  });
+
+  test("偏好和管理端受众选项走受 Guard 保护的稳定端点", async () => {
+    await getNotificationPreference();
+    await updateNotificationPreference({
+      enabledChannels: ["email"],
+      disabledCategories: ["营销"],
+    });
+    await getNotificationAudienceOptions();
+
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      1,
+      "/notifications/preferences",
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      2,
+      "/notifications/preferences",
+      {
+        method: "PUT",
+        body: JSON.stringify({
+          enabledChannels: ["email"],
+          disabledCategories: ["营销"],
+        }),
+      },
+    );
+    expect(mocks.request).toHaveBeenNthCalledWith(
+      3,
+      "/system/notifications/audience-options",
+    );
+  });
+});

package/template/apps/web/src/services/search-api.ts

@@ -0,0 +1,39 @@
+import { apiRequest } from "./http";
+
+export interface SearchHit {
+  id: string;
+  resourceType: string;
+  maskedTitle: string;
+  maskedExcerpt?: string;
+  score?: number;
+  providerKey: string;
+  deepLink: {
+    surface: "business";
+    routeTemplate: string;
+    params: Record<string, string>;
+  };
+}
+
+export interface SearchResultGroup {
+  providerKey: string;
+  label: string;
+  hits: readonly SearchHit[];
+}
+
+export interface SearchResultPage {
+  groups: readonly SearchResultGroup[];
+  partial: boolean;
+  failures: Array<{
+    providerKey: string;
+    code: string;
+    message: string;
+  }>;
+}
+
+export function searchPlatform(query: string, signal?: AbortSignal) {
+  return apiRequest<SearchResultPage>("/search", {
+    method: "POST",
+    body: JSON.stringify({ query, limit: 8 }),
+    signal,
+  });
+}

package/template/apps/web/src/services/system-api.ts

@@ -154,3 +154,21 @@ export function quickCreateDepartment(payload: Record<string, unknown>) {
     body: JSON.stringify(payload),
   });
 }
+
+export function transitionDepartment(
+  departmentId: string,
+  payload: {
+    action: "disable" | "delete";
+    targetDepartmentId?: string;
+  },
+) {
+  return apiRequest<{
+    department: SystemRecord;
+    movedChildren: number;
+    movedUsers: number;
+    updatedRoles: number;
+  }>(`/system/departments/${departmentId}/transition`, {
+    method: "POST",
+    body: JSON.stringify(payload),
+  });
+}

package/template/apps/web/vitest.config.ts

@@ -9,6 +9,7 @@ export default mergeConfig(
       include: ["src/**/*.webtest.ts"],
       clearMocks: true,
       restoreMocks: true,
+      testTimeout: 15_000,
     },
   }),
 );

package/template/docker-compose.yml

@@ -46,6 +46,10 @@ services:
       AGENT_SERVER_URL: http://agent-server:8080
       AGENT_TOOL_HOST_URL: http://server:9747
       AGENT_SERVER_INTERNAL_TOKEN: ${AGENT_SERVER_INTERNAL_TOKEN:-}
+      OPENSEARCH_URL: ${OPENSEARCH_URL:-}
+      OPENSEARCH_USERNAME: ${OPENSEARCH_USERNAME:-}
+      OPENSEARCH_PASSWORD: ${OPENSEARCH_PASSWORD:-}
+      OPENSEARCH_WORK_ORDER_INDEX: ${OPENSEARCH_WORK_ORDER_INDEX:-windy-work-orders-v1}
     ports:
       - "9747:9747"
     volumes:
@@ -56,6 +60,29 @@ services:
       migrate:
         condition: service_completed_successfully
 
+  opensearch:
+    profiles: ["search"]
+    image: opensearchproject/opensearch:2.19.3
+    environment:
+      discovery.type: single-node
+      DISABLE_INSTALL_DEMO_CONFIG: "true"
+      DISABLE_SECURITY_PLUGIN: "true"
+      OPENSEARCH_JAVA_OPTS: "-Xms512m -Xmx512m"
+    ports:
+      - "127.0.0.1:19200:9200"
+    volumes:
+      - opensearch-data:/usr/share/opensearch/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "curl -fsS http://127.0.0.1:9200/_cluster/health?wait_for_status=yellow",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+
+
   agent-server:
     profiles: ["agent"]
     build:
@@ -79,6 +106,44 @@ services:
       server:
         condition: service_started
 
+  adk-web-debug:
+    profiles: ["agent-debug"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    command:
+      [
+        "adk",
+        "web",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8000",
+        "--no-reload",
+        "--session_service_uri",
+        "memory://",
+        "--artifact_service_uri",
+        "memory://",
+        "--logo-text",
+        "Windy ADK 开发调试（无业务工具）",
+        "--logo-image-url",
+        "data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E",
+        "/app/apps/agent-server/adk_web_agents",
+      ]
+    ports:
+      - "127.0.0.1:8000:8000"
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/', timeout=3)",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
   web:
     build:
       context: .
@@ -113,3 +178,4 @@ volumes:
   postgres-data:
   server-audit-data:
   agent-run-data:
+  opensearch-data:

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

@@ -1,12 +1,14 @@
 # Southwind AI Runtime 架构
 
-更新时间：2026-07-25。
+更新时间：2026-07-26。
 
 状态：架构已确认，首个可消费的文本 Agent 切片已实现。当前包含 Module AI Operation
 注册、Guarded Run facade、短时 Execution Grant、受限 Tool Host、OpenAI-compatible
 Provider、canonical HTTP/SSE、取消、cursor 重放和单副本有界 SQLite Store。未配置
-Provider 时仍安全拒绝。ADK Workflow、LiteLLM 多 Provider 路由、PostgreSQL 多副本
-Store、Document AI 和 Speech 运行进程尚未实现，不能据此宣称完整 AI Runtime 已交付。
+Provider 时仍安全拒绝。真实业务 Run 已在内部使用 ADK 2.5 Runner、Session、LlmAgent
+和 Event，并把事件转换为既有 canonical signal。ADK Workflow、LiteLLM 多 Provider
+路由、PostgreSQL 多副本 Store、Document AI 和 Speech 运行进程尚未实现，不能据此
+宣称完整 AI Runtime 已交付。
 
 ## 目标
 
@@ -643,6 +645,12 @@ type DictationEvent =
 
 ADK Web 只在 developer profile 启动，绑定 localhost 或受控开发网络。它不是生产 Prompt 管理或生产 Debug 控制面。
 
+当前 Compose 使用独立 `agent-debug` profile，宿主机只发布
+`127.0.0.1:8000`。由于原生 ADK Web 没有 Southwind AI Server 签发的 Actor 与
+Execution Grant，它只加载一个无 Provider、无业务 Tool 的确定性调试 Agent。真实业务
+Operation 只能走 canonical HTTP/SSE → ADK Adapter → 受治理 Provider/Tool Host 链路；
+不得把 ADK Web 的调试会话解释为生产授权或业务执行证据。
+
 Prompt 和 Workflow 使用：
 
 ```text
@@ -728,8 +736,9 @@ LiteLLM 版本必须固定并通过供应链审查，客户现场禁止动态安
 
 当前已完成第 1、2、4 项和第 5 项的受限 Tool Host 基础闭环，并交付可直接连接
 OpenAI-compatible Provider 的文本 Agent Adapter。SQLite Store 提供单副本有界持久化，
-重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。ADK unavailable
-Adapter 保留为未配置 Provider 时的 fail-closed fallback。
+重启后保留终态和 cursor，但不替代后续 PostgreSQL 多副本 Store。配置 Provider 后，
+文本与 Tool Run 由 ADK Runner/Session/Event 执行；未配置 Provider 时同一 Adapter
+fail closed。开发 ADK Web 已作为 localhost-only 的受控调试入口交付，不是业务入口。
 
 1. 定义 Agent、Document、Speech Operation 与 Module Manifest 组合校验；
 2. 建立 Python Agent Server、ADK Adapter 和 deterministic test Adapter；

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

@@ -4,7 +4,7 @@
 
 平台通过一个稳定的 `SearchService` 聚合业务搜索结果，但不读取业务模块 Repository，也不把用户输入转换成跨模块 SQL。业务模块通过 Manifest 声明 `kind: "search"` 的 Provider，并提供同 Key、同版本的 Handler。Composition Root 启动时要求声明与实现一一对应，未知 Handler、缺失 Handler、重复 Key、协议版本或 Provider 版本漂移都会 fail-fast。
 
-默认部署不引入 OpenSearch、Elasticsearch 或其它外部搜索引擎。小数据量模块可以实现 Repository Provider；将来若替换为可重建索引 Provider，平台协议、调用方与业务详情授权边界不变，业务数据库仍是事实源。
+默认部署不引入 OpenSearch、Elasticsearch 或其它外部搜索引擎。小数据量模块可以实现 Repository Provider；需要外部索引时可以显式启动 OpenSearch 开发 profile。两种实现共用同一 Provider 协议、调用方与业务详情授权边界，业务数据库始终是事实源。
 
 ## 深模块边界
 
@@ -48,11 +48,47 @@ Provider 只负责在自身模块边界内执行搜索。它接收平台从已
 - `SEARCH_PROVIDER_KEYS` 是逗号分隔的启动白名单；未配置时按 Manifest 的 `enabledByDefault` 启用，显式空字符串关闭全部 Provider，未知、重复或非法 Key 使启动失败。
 - `SEARCH_PROVIDER_TIMEOUT_MS`、`SEARCH_HEALTH_TIMEOUT_MS` 允许 10-5000 毫秒；`SEARCH_MAX_REQUESTS_PER_MINUTE` 允许 1-300。非整数或越界配置使启动失败，不能被静默截断或钳制。
 
+## Web 全局入口
+
+Header 的 `Ctrl/⌘ K` 全局搜索同时展示两类结果：
+
+- 平台导航在浏览器内只过滤 Admin Bootstrap 已下发且当前账号获准的菜单；
+- 业务数据只通过 `POST /api/search` 获取，并按 Manifest Provider 分组展示脱敏标题、摘要和业务深链。
+
+输入使用 250ms 延迟并在关键词变化或 Dialog 关闭时中止旧请求，避免迟到响应覆盖新结果。单个 Provider 超时或故障时显示“结果可能不完整”，其它 Provider 和菜单仍可使用。Web 不维护 Provider Key、目标权限或 Feature 的副本，也不接收 OpenSearch 地址和凭据。
+
+## 可选 OpenSearch Adapter
+
+根项目和包含 `system.search` 的 Starter 提供显式开发入口：
+
+```bash
+bun run dev:search
+```
+
+该命令设置容器内 `OPENSEARCH_URL=http://opensearch:9200`，并启动 Compose 的 `search` profile。普通 `bun run dev` 不设置地址，也不会启动或连接 OpenSearch。开发 profile 使用固定镜像、持久卷和健康检查；宿主端口只绑定 `127.0.0.1:19200`。`system.search` 被物理裁剪时，生成物同时移除 OpenSearch service、Server 环境变量、volume 和启动脚本。
+
+Server 可读取以下配置：
+
+- `OPENSEARCH_URL`：不含凭据、路径、查询参数的 HTTP(S) 根地址；未配置即使用原 Repository Provider；
+- `OPENSEARCH_USERNAME` / `OPENSEARCH_PASSWORD`：必须成对配置，只进入 Server 到 OpenSearch 的 Authorization Header；
+- `OPENSEARCH_REQUEST_TIMEOUT_MS`：100-30000ms，默认 3000ms；
+- `OPENSEARCH_WORK_ORDER_INDEX`：示例工单的可重建索引名，默认 `windy-work-orders-v1`。
+
+示例工单 Adapter 展示了项目业务层的正确接法：
+
+1. 第一次查询或索引失效后，从 PostgreSQL 事实源读取当前快照并重建索引；
+2. 创建、更新和归档成功后增量更新索引；OpenSearch 写失败只标记投影失效，不回滚已提交的业务事实；
+3. Provider 把服务端 `ScopeContext` 编译为 OpenSearch `term` / `terms` Filter，无授权分支使用 `match_none`；
+4. 命中 ID 返回前再次调用业务 Service 读取目标资源，防止陈旧索引绕过详情权限；
+5. 标题和摘要只从重新授权后的业务实体生成脱敏投影。
+
+这个 Compose profile 用于本地接入与回归，不是生产拓扑。生产环境应启用 OpenSearch TLS、认证、最小网络可达性、容量和快照策略；大规模增量索引应由项目自有 Outbox/Durable Job 驱动，不能把索引成功当成业务事务提交条件，也不能直接把开发 profile 暴露到客户网络。
+
 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 结果。
+协议单元测试覆盖声明/实现/版本 fail-fast、启停与健康发现、目标权限裁剪、客户端不能扩大服务端身份和组织范围、分组与游标、Manifest 深链、明文响应拒绝、故障/超时隔离、部分失败、按 Actor 限流，以及审计中不出现原始查询词。Server API 测试另行覆盖入口权限先行、目标权限二次裁剪、Feature 关闭、只接受 POST body、稳定错误状态和直接 API 伪造身份/部门不能扩大 scoped Repository 结果。OpenSearch 测试覆盖默认关闭、配置拒绝、凭据只进入 Server 请求头、索引重建、范围 Filter 与无授权 `match_none`；Web 测试覆盖菜单检索、业务分组结果和深链跳转。
 
 示例 Work Order 已注册 `work-order.ticket.search`，Provider 只调用 `WorkOrderService.list`，后者把查询、count、分页与服务端 dataScope 一起交给 scoped Repository；测试会让裸 `Repository.list` 主动抛错，并确认本人范围不会返回其他负责人的匹配工单。另一个实现相同 Key/版本的测试 Provider 可以在不修改 Core 的情况下替换工单 Adapter。
 

package/template/docs/development/custom-error-pages.md

@@ -0,0 +1,78 @@
+# 业务项目定制错误页
+
+Windy 为 Web 提供统一的 404、500、维护中和网络异常页面，同时允许业务项目替换任意
+一种页面。业务选择入口是：
+
+```text
+apps/web/src/app/error-pages.ts
+```
+
+该文件在 `.windy/files.json` 中属于 `project-owned`。Windy 升级会给尚无此文件的
+项目创建默认选择器；文件存在后，后续更新只保留业务选择。平台默认页面
+`apps/web/src/pages/errors/PlatformErrorPage.vue` 属于 `windy-managed`，Router 和
+全局错误导航属于 `shared-scaffold`，业务项目不应为换视觉而修改这些文件。
+
+## 默认行为
+
+默认选择器让四种错误都使用平台页面：
+
+```ts
+import PlatformErrorPage from "@/pages/errors/PlatformErrorPage.vue";
+import { defineErrorPageComponents } from "@/pages/errors/error-page-extension";
+
+export const errorPageComponents = defineErrorPageComponents({
+  notFound: PlatformErrorPage,
+  internal: PlatformErrorPage,
+  maintenance: PlatformErrorPage,
+  network: PlatformErrorPage,
+});
+```
+
+错误来源与页面的稳定映射如下：
+
+| 来源                                                | 页面     |
+| --------------------------------------------------- | -------- |
+| Router 没有匹配业务路由                             | 404      |
+| Vue 渲染异常、Router 加载异常、HTTP 5xx（503 除外） | 500      |
+| HTTP 503                                            | 维护中   |
+| `fetch` 无法建立连接或传输中断                      | 网络异常 |
+
+HTTP 5xx 响应中的 `x-request-id` 会进入错误页，用户可将它直接提供给维护人员。调用方若
+要在当前交互内自行处理后台重试，可以给 `apiRequest` / `apiResponse` 传入
+`{ suppressFailureHandler: true }`，避免跳转全局错误页；这不改变原 Promise 的失败
+语义。
+
+## 替换业务页面
+
+把业务 SFC 放在 `apps/web/src/app/` 下，再只修改选择器。例如只替换网络异常页：
+
+```ts
+import NetworkErrorPage from "./NetworkErrorPage.vue";
+import PlatformErrorPage from "@/pages/errors/PlatformErrorPage.vue";
+import { defineErrorPageComponents } from "@/pages/errors/error-page-extension";
+
+export const errorPageComponents = defineErrorPageComponents({
+  notFound: PlatformErrorPage,
+  internal: PlatformErrorPage,
+  maintenance: PlatformErrorPage,
+  network: NetworkErrorPage,
+});
+```
+
+业务组件接收统一的只读 Props：
+
+```ts
+interface ErrorPageProps {
+  kind: "not-found" | "internal" | "maintenance" | "network";
+  from: string;
+  requestId?: string;
+}
+```
+
+`from` 已限制为站内绝对路径，错误页自身和外部 URL 会回退到 `/`。业务组件应使用
+文本插值展示地址和 Request ID，不使用 `v-html`；重试只导航到 `from`，不得把查询
+参数解释为外部链接。错误页是公共恢复入口，不应读取管理权限快照或把敏感信息写入
+页面。
+
+完整自定义也必须保留四个注册项。`defineErrorPageComponents` 会在 TypeScript 阶段
+检查 Key 是否齐全；Router 只依赖这个稳定导出，不感知业务组件实现。

package/template/docs/development/custom-login-page.md

@@ -78,9 +78,9 @@ composable。
 先提交当前业务改动并保持 Git 工作区干净，然后执行：
 
 ```bash
-bunx --bun create-windy@0.2.34 update --check --cwd .
-bunx --bun create-windy@0.2.34 update --dry-run --cwd .
-bunx --bun create-windy@0.2.34 update --cwd .
+bunx --bun create-windy@0.3.0 update --check --cwd .
+bunx --bun create-windy@0.3.0 update --dry-run --cwd .
+bunx --bun create-windy@0.3.0 update --cwd .
 bun install
 ```
 

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

@@ -1,6 +1,6 @@
 # Agent Runtime 接入与运行
 
-更新时间：2026-07-25。
+更新时间：2026-07-26。
 
 Windy 的 Agent Runtime 是可选平台能力。业务模块声明稳定的 AI Operation 和允许调用的
 Tool；Southwind AI Server 负责身份、Feature、Permission、License、Scope、Execution
@@ -9,6 +9,8 @@ Grant 与审计；独立 Agent Server 只负责模型循环、canonical event
 
 ## 当前可用边界
 
+- 真实业务 Run 使用 Google ADK 2.5 `Runner`、`InMemorySessionService`、`LlmAgent`
+  与 `Event`；ADK 类型只存在于 Python Adapter 内，外部 HTTP/SSE 契约不变。
 - OpenAI-compatible `/chat/completions` Provider，支持流式文本和 function calling。
 - `QWEN_API_KEY` 使用服务端 `SecretRef`，只在 Provider Adapter 发请求前解析。
 - 公网 Endpoint 必须为 HTTPS，并精确命中
@@ -173,6 +175,28 @@ Agent profile 还必须挂载 `AI_PROVIDER_AUDIT_STORE_PATH`。create-windy Star
 `/app/data/agent/provider-audit.sqlite3` 并复用单副本持久卷；自行维护 Compose 的项目
 需要显式补齐该变量。未配置时 Provider 启动 fail closed，并给出缺失变量名。
 
+## Developer-only ADK Web
+
+ADK Web 使用独立 profile 启动：
+
+```bash
+bun run dev:adk-web
+```
+
+访问地址为 `http://127.0.0.1:8000`。Compose 服务在容器内监听 `0.0.0.0:8000`，
+但端口只发布到宿主机 `127.0.0.1`。普通 `dev`、`agent` profile 和生产 Compose 均不
+包含该服务。
+
+该界面明确显示“Windy ADK 开发调试（无业务工具）”，并只加载一个确定性 Agent：
+
+- 不读取 `QWEN_*`、Provider URL/Secret 或 `AGENT_SERVER_INTERNAL_TOKEN`；
+- 不注册业务 Tool，不连接 Tool Host 或业务 Repository；
+- 不接收 Actor、Scope 或 Execution Grant；
+- 只用于观察 ADK Web、Session 和 Event，不代表真实业务 Operation。
+
+真实业务调试必须继续从 canonical Run API 发起并提供 Southwind AI Server 签发的
+Execution Grant；不能通过 ADK Web 补造或绕过这条授权链。
+
 ## 客户端协议
 
 浏览器继续使用 `@southwind-ai/ai-client` 访问同源 Southwind AI Server：
@@ -188,15 +212,17 @@ SSE 事件包括 `output.delta`、`tool.requested`、`tool.completed`、usage，
 `run.completed`、`run.failed` 或 `run.cancelled` 终态。断线后使用已确认 sequence 作为
 cursor 恢复；不要重新创建 Run 或重复执行 Tool。
 
-## 从 create-windy 0.2.25 或更早版本升级
+## 从 create-windy 0.2.34 升级到 0.3.0
 
-先检查计划，再应用连续 recipe：
+`0.2.34 → 0.3.0` 使用连续 recipe，不需要逐个安装中间 CLI。确认 npm registry 已能
+解析精确的 `0.3.0` artifact 后，先检查计划，再应用：
 
 ```bash
-bunx --bun create-windy@0.2.26 update --check
-bunx --bun create-windy@0.2.26 update
+bunx --bun create-windy@0.3.0 update --check
+bunx --bun create-windy@0.3.0 update
 bun install
 ```
 
 升级器会更新受管模板文件；本地修改产生冲突时会 fail closed 并保留事务备份，不会静默
-覆盖。升级后按上面的环境变量启用 `agent` profile。
+覆盖。升级后按上面的环境变量启用 `agent` profile；`agent-debug` 仍只用于无业务 Tool
+的本机调试。自动化部署应固定精确版本，不能用未核验的 `latest` 替代。

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

@@ -17,11 +17,53 @@
 
 批量任务派发器每 5 秒轮询一次。定时执行返回 `claimed: false` 代表没有业务任务可领取，Scheduler 完成并立即丢弃这条 idle run，也不写 `task.execute` 审计；人工触发即使没有领取任务仍保留执行历史和 `task.trigger` / `task.execute`，真实领取、失败、重试和 Guard 拒绝同样完整留痕。idle 判定由任务定义显式声明，普通任务不会自动套用。
 
-审计页面使用操作者、动作和时间三个选择控件。操作者候选来自最近 100 条审计记录，动作候选来自 `@southwind-ai/shared` 的稳定动作目录，并以中文名称和说明展示；筛选请求继续传递稳定 action key。时间选择按最近 24 小时、7 天或 30 天换算为 ISO `occurredAfter`，内存与 PostgreSQL Reader 使用同一时间边界，非法时间值返回 `400 INVALID_AUDIT_TIME_RANGE`。
+审计页面支持关键字、操作者、动作以及本地开始/结束分钟筛选。操作者候选来自最近
+100 条审计记录，动作候选来自 Module Composition 形成的稳定动作目录，并以中文名称和
+说明展示；筛选请求继续传递稳定 action key。`datetime-local` 输入按用户浏览器本地时区
+转换为 ISO：开始分钟使用 `00.000` 秒，结束分钟包含至 `59.999` 秒。内存与 PostgreSQL
+Reader 使用同一组含边界时间；时间不是完整 ISO 或开始晚于结束时返回
+`400 INVALID_AUDIT_TIME_RANGE`。
+
+关键字 `q` 会做 NFKC、首尾空白和连续空白规范化，最长 120 个字符。搜索范围包括动作
+Key、操作者 ID/名称、目标类型/ID/标签、IP、message、module、requestId，以及已经过
+审计脱敏并持久化的 metadata 文本。PostgreSQL 查询使用参数绑定并把 `%`、`_` 和反斜线
+当作普通字符，不执行客户端表达式，也不查询登录 Session、业务明文表或未持久化请求体。
+列表和导出共享完全相同的 `q`、操作者、动作与时间筛选；导出的
+`includeScheduler` 默认关闭，只有显式勾选时才包含调度器事件。
 
 常规审计列表在服务端固定排除 `system_scheduler` 执行身份产生的日志，客户端不能构造参数绕过；调度执行结果统一到定时任务的执行历史查看。审计导出提供“包含定时器日志”选项，默认关闭，只影响本次导出，不改变页面列表状态。
 
-动作列直接显示中文动作名，并使用 shadcn-vue / Reka UI Tooltip 零延迟展示稳定 action key、动作说明、操作对象和相关上下文。非空通用资源搜索记录 `data.search`，metadata 包含查询内容、资源和匹配数；审计列表自身不递归记录搜索。自由文本可能包含手机号或邮箱，因此部署方应把审计访问权限、保留期和导出权限视为敏感数据治理边界；默认字段名脱敏不等于自由文本内容脱敏。
+动作列直接显示中文动作名，并优先使用 event.message、target、module 与已记录 metadata
+组成一行操作摘要；CRUD、搜索、功能开关和 Agent Tool 等常见动作提供稳定中文表达，
+未知业务动作保留 action key、对象和实际上下文，不推断未记录事实。“查看详情”使用
+shadcn-vue Dialog，以安全纯文本展示动作说明、结果、操作者、IP、时间、操作对象、
+message、module、requestId、User-Agent 和已脱敏 metadata，不使用 `v-html`。
+非空通用资源搜索记录 `data.search`；审计列表自身不递归记录搜索。自由文本可能包含
+手机号或邮箱，因此部署方应把审计访问权限、保留期和导出权限视为敏感数据治理边界；
+默认字段名脱敏不等于自由文本内容脱敏。
+
+## HTTP 请求来源与可信代理
+
+平台 HTTP 审计的 IP 与 User-Agent 来自当前请求，不写回认证 Resolver 返回的 Session
+Actor。Bun `server.requestIP(request)` 提供的直接对端先经过 IP 规范化；User-Agent
+去除首尾空白并最多保留 1024 个字符。所有由 Guard、平台 Route、业务 Module 与
+Agent Tool 在该请求内产生的审计事件，都通过 `RequestGuardContext` 复制这份来源。
+
+默认 `WINDY_TRUST_PROXY=false`，此时无条件忽略客户端提交的 `X-Forwarded-For`，只记录
+合法的直接对端 IP。只有同时满足以下条件时才采用转发来源：
+
+1. `WINDY_TRUST_PROXY=true`；
+2. 直接对端是 loopback，或在 `WINDY_TRUSTED_PROXY_IPS` 的逗号分隔精确 IP 列表内；
+3. `X-Forwarded-For` 只包含一个合法 IPv4/IPv6 地址。
+
+多段转发链、非法地址或不受信直接对端均退回直接对端 IP。当前策略有意不猜测多级代理
+链；部署多个反向代理时，应由最后一个受信代理清洗并输出单一客户端地址。配置了
+`WINDY_TRUSTED_PROXY_IPS` 却未显式启用信任、布尔值不是 `true/false`、或列表含非法
+IP 时，Server 启动 fail closed。
+
+数据库 schema 早已包含 `audit_logs.ip` 与 `user_agent`，因此本功能无需 migration。
+历史日志、非 HTTP 后台事件，以及升级前未复制请求来源的事件仍可能没有 IP 或
+User-Agent，管理端明确显示“未记录”，不会用当前 Session 或其它字段猜测补齐。
 
 每次 PostgreSQL 写入默认最多尝试 3 次。重试间隔按指数增长，并受最大间隔约束，不会无限重试或无限阻塞请求。恢复队列也有最大条数；队列已满等同于队列不可用，关键动作会失败。
 
@@ -77,6 +119,8 @@ License 上传仍只记录候选摘要、可识别的 License ID、公钥 ID 和
 | `WINDY_AUDIT_QUEUE_FILE`    | `./data/audit/recovery-queue.json` | 关键事件恢复文件                            |
 | `WINDY_AUDIT_QUEUE_SIZE`    | `1000`                             | 关键恢复队列最大事件数，上限 `100000`       |
 | `AUDIT_REDACT_FIELDS`       | 空                                 | 在默认敏感字段之外追加的逗号分隔字段名      |
+| `WINDY_TRUST_PROXY`         | `false`                            | 是否允许从受信直接代理读取单一转发 IP       |
+| `WINDY_TRUSTED_PROXY_IPS`   | 空                                 | 受信直接代理的精确 IP，逗号分隔             |
 
 生产环境未配置审计持久化 writer 时，关键动作不会回退为内存 best-effort，而是直接 fail closed。普通审计仍维持业务可用性，但健康状态会显示写入失败。
 

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

@@ -1,6 +1,6 @@
 # 类型化模块配置与 Secret 边界
 
-更新时间：2026-07-16。
+更新时间：2026-07-26。
 
 ## 目标与边界
 
@@ -54,16 +54,25 @@ Secret 配置分成引用和运行时值两层：
 - `applying`：版本已入库，正在调用模块 Apply Adapter；
 - `effective`：当前生效版本，同模块同时只能有一个；
 - `failed`：schema 已通过但运行时应用失败，稳定错误不包含底层异常正文；
+- `pending-restart`：版本已持久化但包含需重启字段，当前进程不冒充已生效；下次启动校验并应用成功后提升为 `effective`；
 - `superseded`：曾经生效，已被后续版本替代。
 
 版本号由 PostgreSQL transaction 内的 module-key advisory lock 分配，唯一索引继续提供最终并发保护。应用成功后，Repository 在事务内把旧 `effective` 标为 `superseded` 并把新版本标为 `effective`；应用失败只标记新版本为 `failed`，原生效版本不变。Server 启动时先读取每个已注册模块的生效版本并通过同一 schema 与 Apply Adapter 恢复，再建立 foundation 和探活运行时。
 
-当前首批允许动态管理的 `platform.runtime` 字段只有：
+当前 `platform.runtime` 白名单包括：
 
 - `enableAI`：更新 foundation 平台能力投影；
 - `cache.healthTimeoutMs`：后续 Redis 探活按最新值创建 probe。
+- `security.sessionTtlSeconds`：即时影响新签发会话，已有会话保持原过期时间；
+- `security.passwordMinLength/passwordMaxLength`：即时影响 Argon2 密码修改、重置校验和密码页服务端策略；
+- `storage.bulkDataMaxByteSize/storage.brandingLogoMaxByteSize`：即时影响后续上传会话；
+- `regional.timeZone`：即时影响公共平台设置投影和 Web 后续日期格式化；
+- `mail.enabled/host/port/secure/fromAddress/connectTimeoutMs`：保存为
+  `pending-restart`，下次 Server 启动后进入 typed runtime config。
 
-数据库、Redis URL、Session、License 机器码、签名 Token 和 Vault Token 等 Secret 或引用均不进入版本表、diff、普通 API、管理界面或审计 metadata。
+同一版本只要变更了需重启字段，就整体等待重启，避免一部分字段先应用造成原子性错觉。旧版本缺少后来新增的字段时，Apply Adapter 使用当前环境基线补齐，再经过完整 schema 校验；因此升级不要求回写历史行。数据库、Redis URL、SMTP URL、License 机器码、签名 Token 和 Vault Token 等 Secret 或引用均不进入版本表、diff、普通 API、管理界面或审计 metadata。`MAIL_SMTP_URL` 仍只由 env SecretResolver 注入进程内配置。
+
+邮件字段由通知模块的标准 SMTP Adapter 在 Server 组合根消费。`mail.enabled=false` 时不注册邮件渠道；启用后可使用 env-only `MAIL_SMTP_URL`，或使用 `host/port/secure/fromAddress/connectTimeoutMs` 建立传输。保存配置仍是 `pending-restart`，只有重启后新建的 Adapter 才读取新值。配置存在不等于必然送达：实际结果由持久 outbox、用户偏好、收件地址和 SMTP 响应共同决定。短信供应商实现不属于平台配置，业务项目必须通过通知 ChannelAdapter Port 注入，平台不会猜供应商报文。
 
 ## 回滚、权限与审计
 
@@ -71,7 +80,7 @@ Secret 配置分成引用和运行时值两层：
 
 配置读取要求 `system.config.read`，创建版本和回滚要求 `system.config.manage`；菜单、Web Router 和所有四个 API 绑定统一引用 `system.config` Feature 与 System Module Manifest。mutation 在改配置前先写 `critical` intent 审计，审计不可持久化或进入恢复队列时返回 `503 AUDIT_UNAVAILABLE` 且不创建版本。结果审计只记录 module Key、版本、状态、回滚来源和 changed paths，不记录 before/after 值、请求值、Secret 或 `SecretRef`。
 
-管理端 `/system/configurations` 只根据服务端字段描述生成编辑表单，显示环境/版本来源、生效版本、diff、失败状态和历史；回滚必须经过带原因的显式确认。编辑值或原因未保存时，路由离开和刷新分别使用应用 Dialog 与原生 `beforeunload` 保护，保存失败会保留当前输入。
+管理端 `/system/configurations` 只根据服务端字段描述生成编辑表单，显示每个字段即时/重启语义、环境/版本来源、生效版本、diff、失败或等待重启状态和历史；回滚必须经过带原因的显式确认。编辑值或原因未保存时，路由离开和刷新分别使用应用 Dialog 与原生 `beforeunload` 保护，保存失败会保留当前输入。
 
 ## 运维与验证