create-windy 0.2.34 → 0.3.1

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/mcp-business-capabilities.md

@@ -0,0 +1,107 @@
+# MCP 业务能力暴露
+
+## 决策
+
+Windy 以 Module Manifest、Server SDK Handler 和 `GovernedToolRegistry` 组成业务能力深
+模块。MCP、原生 Agent Tool Route 和 Agent Runtime Tool Host 都是该 Interface 的
+Adapter，不拥有业务能力、权限或审计定义。
+
+```text
+业务 Module
+  ├── Manifest：Schema / Tool / Feature / Permission / Audit
+  └── Handler：类型化 JSON 实现
+           │
+           ▼
+  GovernedToolRegistry
+  ├── Schema 与大小限制
+  ├── License / Feature / RBAC / Data Scope
+  ├── Timeout / Audit
+  └── 结构化结果
+           │
+       ┌───┴───────────┐
+       ▼               ▼
+ Agent Tool Route   MCP Adapter
+```
+
+删除 Registry 后，输入输出校验、Guard、Scope、超时和审计复杂度会重新散落到多个调用面；
+因此该模块承担了真实的平台复杂度，而不是协议转发层。
+
+## 为什么不直接包装 OpenAPI
+
+HTTP Route 面向确定性客户端，参数经常包含分页、传输和页面交互细节。MCP Tool 面向模型
+选择和结构化调用，需要更小、语义明确、风险可治理的 Interface。自动包装所有 OpenAPI
+会导致：
+
+- 模型看到大量浅层 CRUD；
+- 页面传输参数成为模型契约；
+- 写操作缺少幂等和审批语义；
+- Route、Tool、权限和审计产生多套漂移定义。
+
+因此业务模块显式选择哪些能力成为 Tool；OpenAPI 和 MCP 可以调用同一业务 Service，
+但不会相互自动推导。
+
+## MCP Transport
+
+远程接入已采用官方 MCP TypeScript SDK `1.29.0` 和无状态 Streamable HTTP，Endpoint
+为 `/api/mcp`。v2 在当前实施时仍为预发布，不进入生产依赖。无状态模式适合当前只读
+请求，也避免把授权快照保存为长期 Session 状态。
+
+MCP Endpoint 必须位于现有 Server 身份解析之后：
+
+- Bearer/Cookie 只用于解析当前 Server Actor，入口另需通过 `system.agent` Feature 与
+  `system.agent.read` Permission；
+- `tools/list` 只返回当前 Actor 获准的只读 Tool；
+- `tools/call` 每次重新经过 Registry，不复用列表阶段的授权结论；
+- 客户端参数不能提供 Permission、Feature、License、Actor 或 Scope；
+- MCP 协议错误与业务 Guard 错误使用稳定、脱敏的错误信息。
+
+## Tool、Resource 与 Skill
+
+当前只提供 Tool：
+
+- Tool 对应可执行的类型化业务查询；
+- Resource 等出现明确的只读文档或静态能力目录消费场景后再增加；
+- Prompt 不作为业务规则来源。
+
+Skill 解决开发流程，不属于运行时授权 Interface。仓库内开发 Skill 指导 Agent：
+
+1. 创建业务模块和 Manifest；
+2. 注册 Feature、Permission、Audit 与 JSON Schema；
+3. 实现 Repository、Service 和 Tool Handler；
+4. 增加 Composition、Guard、Data Scope 与 Schema 测试；
+5. 使用脚手架和真实生成回归验证。
+
+Skill 内容可以从稳定契约和模板派生，但不能独立声明 Tool Key 或授权事实。
+`.agents/skills/windy-business-module/SKILL.md` 随 Starter 一起分发，并指向 Manifest、
+Module Host 和 Tool Handler 的代码事实源。生成组合未包含 `system.agent` 时，Skill
+要求明确物理边界，不在业务层另建 MCP 或授权实现。
+
+## 写操作门槛
+
+MCP Adapter 只暴露 `operation=query`。开放 `command/background` 前必须完成：
+
+- 强制幂等键及结果重放语义；
+- 风险分级和人工审批；
+- Durable Job/结果状态引用；
+- Actor、请求、审批和业务副作用的完整关联；
+- 超时后真实副作用是否仍继续的明确语义；
+- 重试、取消和补偿回归。
+
+在这些条件满足前，Manifest 可以预先描述写能力，但 MCP Adapter 必须过滤它们。
+
+## 运维与验证
+
+- Server 启动前校验声明、Schema 和 Handler 一一对应。
+- MCP 不可用不能影响普通业务 Route 和非 AI 能力启动。
+- 审计只记录 Tool Key、Actor、Request ID、输入输出字节数和结果，不保存原始内容。
+- 回归至少覆盖未授权不可发现、直接调用重新授权、Schema 拒绝、数据范围不可扩大和
+  Handler 输出漂移。
+- MCP API Path、Server 身份、Route 与 Manifest Binding 使用
+  `packages/shared/src/mcp.ts` 的共享 Contract；生成 README 通过跨层测试校对该路径。
+- Tool 目录从当前 Module Manifest 组合，不在 README 或 Skill 固化。新模板通过发布时
+  `template:sync` 更新；既有客户项目只通过显式 `windy update` 合并，不远程静默改写。
+
+官方协议与 SDK 资料：
+
+- [MCP TypeScript SDK v1](https://ts.sdk.modelcontextprotocol.io/)
+- [MCP Server 与 Streamable HTTP](https://ts.sdk.modelcontextprotocol.io/server)

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.1 update --check --cwd .
+bunx --bun create-windy@0.3.1 update --dry-run --cwd .
+bunx --bun create-windy@0.3.1 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.1
 
-先检查计划，再应用连续 recipe：
+目标 CLI 会一次解析 `0.2.34 → 0.3.0 → 0.3.1` 连续 recipe，不需要逐个安装中间
+CLI。确认 npm registry 已能解析精确的 `0.3.1` 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.1 update --check
+bunx --bun create-windy@0.3.1 update
 bun install
 ```
 
 升级器会更新受管模板文件；本地修改产生冲突时会 fail closed 并保留事务备份，不会静默
-覆盖。升级后按上面的环境变量启用 `agent` profile。
+覆盖。升级后按上面的环境变量启用 `agent` profile；`agent-debug` 仍只用于无业务 Tool
+的本机调试。自动化部署应固定精确版本，不能用未核验的 `latest` 替代。

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

@@ -94,6 +94,10 @@ Transport 返回协议允许的状态。
 http://localhost:9747/api/mcp
 ```
 
+普通 Server 已提供该 Endpoint，不需要启动 `dev:agent`。非浏览器 MCP 客户端先通过
+`POST /api/auth/api/login` 获取 Bearer Token，再调用 `tools/list` 获取当前账号实时可见
+的 Tool 与 JSON Schema；客户端和文档都不应固化 Tool 清单。
+
 MCP 使用无状态模式，不保存授权快照或长期 Session。Feature、角色或数据范围变化会在下一次
 调用立即生效。