create-windy 0.2.33 → 0.3.0

package/dist/cli.js

@@ -248,6 +248,7 @@ var optionalModuleManifests = [
       "apps/server/src/agent",
       "apps/server/src/mcp",
       "apps/server/src/module-host/tool-handlers.ts",
+      "apps/server/src/module-host/tool-handlers.test.ts",
       "packages/modules/src/system-agent-tools.ts"
     ],
     documentation: [
@@ -298,21 +299,48 @@ var optionalModuleManifests = [
     ]
   },
   {
-    ...module("system.notification", "站内通知", "通知发布、阅读和归档。", [
-      "system",
-      "system.identity"
-    ]),
+    ...module("system.notification", "站内通知", "通知定向与定时发布、用户偏好、外部渠道投递、修改历史、阅读、收藏和归档。", ["system", "system.identity", "system.scheduler"]),
+    registryDependencies: [
+      {
+        sourceName: "nodemailer",
+        name: "nodemailer",
+        version: "^9.0.3"
+      },
+      {
+        sourceName: "@types/nodemailer",
+        name: "@types/nodemailer",
+        version: "^8.0.1"
+      }
+    ],
     fileRoots: [
       "apps/server/src/notification",
       "apps/web/src/layout/NotificationMenu.vue",
+      "apps/web/src/layout/NotificationMenuItem.vue",
       "apps/web/src/layout/NotificationMenu.webtest.ts",
+      "apps/web/src/layout/NotificationPreferencesDialog.vue",
+      "apps/web/src/layout/NotificationPreferencesDialog.webtest.ts",
+      "apps/web/src/services/notification-api.ts",
       "apps/web/src/pages/system/SystemNotificationsPage.vue",
       "apps/web/src/pages/system/SystemNotificationsPage.webtest.ts",
-      "apps/web/src/pages/system/components/NotificationPublishForm.vue"
+      "apps/web/src/pages/system/components/NotificationPublishForm.vue",
+      "apps/web/src/pages/system/components/NotificationPublishDialog.vue",
+      "apps/web/src/pages/system/components/NotificationManagementCard.vue",
+      "apps/web/src/pages/system/components/NotificationHistoryDialog.vue",
+      "apps/web/src/pages/system/composables/useNotificationPermissions.ts",
+      "apps/web/src/services/notification-api.webtest.ts",
+      "scripts/notification-postgres-regression.ts",
+      "packages/database/src/schema-notification-delivery.test.ts"
     ],
     documentation: ["docs/platform/notifications.md"],
     schemaFiles: ["packages/database/src/schema/notifications.ts"],
-    databaseTables: ["platform_notifications", "notification_reads"]
+    databaseTables: [
+      "platform_notifications",
+      "notification_reads",
+      "notification_favorites",
+      "notification_revisions",
+      "notification_preferences",
+      "notification_delivery_outbox"
+    ]
   },
   {
     ...module("system.workflow", "审批工作流", "审批、转交、超时和补偿。", [
@@ -354,8 +382,11 @@ var optionalModuleManifests = [
     fileRoots: [
       "apps/server/src/search",
       "apps/server/src/module-host/search-providers.ts",
+      "apps/web/src/composables/useGlobalSearch.ts",
       "apps/web/src/layout/NavigationSearchDialog.vue",
-      "apps/web/src/layout/NavigationSearchDialog.webtest.ts"
+      "apps/web/src/layout/NavigationSearchDialog.webtest.ts",
+      "apps/web/src/layout/GlobalSearchResults.vue",
+      "apps/web/src/services/search-api.ts"
     ],
     documentation: ["docs/architecture/search-provider-protocol.md"]
   },
@@ -476,7 +507,7 @@ var platformModules = [
       {
         sourceName: "@southwind-ai/license",
         name: "@southwind-ai/license",
-        version: "^0.1.1"
+        version: "^0.1.3"
       }
     ],
     fileRoots: [
@@ -533,8 +564,12 @@ var platformModules = [
       "apps/server/src/persistence.integration.test.ts",
       "apps/server/src/system/audit-routes.ts",
       "apps/server/src/system/audit-routes.test.ts",
+      "apps/web/src/pages/system/audit-log-presenter.ts",
+      "apps/web/src/pages/system/audit-time-range.ts",
       "apps/web/src/pages/system/components/AuditActionCell.vue",
       "apps/web/src/pages/system/components/AuditActionCell.webtest.ts",
+      "apps/web/src/pages/system/components/AuditLogDetailDialog.vue",
+      "apps/web/src/pages/system/components/AuditLogDetailDialog.webtest.ts",
       "apps/web/src/pages/system/components/AuditLogFilters.vue",
       "apps/web/src/pages/system/components/AuditLogFilters.webtest.ts"
     ],
@@ -1529,6 +1564,7 @@ var starterComposeBase = `services:
       AGENT_SERVER_URL: http://agent-server:8080
       AGENT_TOOL_HOST_URL: http://server:9747
       AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
+__OPENSEARCH_SERVER_ENV__
     ports:
       - "9747:9747"
     volumes:
@@ -1539,6 +1575,7 @@ var starterComposeBase = `services:
       migrate:
         condition: service_completed_successfully
 
+__OPENSEARCH_SERVICE__
   web:
     build:
       context: .
@@ -1572,7 +1609,30 @@ var starterComposeBase = `services:
 volumes:
   postgres-data:
   server-audit-data:
-__AGENT_VOLUME__
+__OPTIONAL_VOLUMES__
+`;
+var openSearchComposeService = `  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
+
 `;
 var agentComposeService = `  agent-server:
     profiles: ["agent"]
@@ -1582,6 +1642,8 @@ var agentComposeService = `  agent-server:
     environment:
       AGENT_SERVER_INTERNAL_TOKEN: \${AGENT_SERVER_INTERNAL_TOKEN:-}
       AGENT_RUN_STORE_PATH: /app/data/agent/runs.sqlite3
+      AI_PROVIDER_AUDIT_STORE_PATH: /app/data/agent/provider-audit.sqlite3
+      AI_PROVIDER_AUDIT_RETENTION_DAYS: \${AI_PROVIDER_AUDIT_RETENTION_DAYS:-90}
       QWEN_API_URL: \${QWEN_API_URL:-}
       QWEN_API_KEY: \${QWEN_API_KEY:-}
       QWEN_MODEL: \${QWEN_MODEL:-}
@@ -1595,36 +1657,91 @@ var agentComposeService = `  agent-server:
       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
+
 `;
-function starterComposeFor(includeAgent) {
+function starterComposeFor(includeAgent, includeSearch = true) {
   return starterComposeBase.replace(`  web:
 `, `${includeAgent ? agentComposeService : ""}  web:
-`).replace("__AGENT_VOLUME__", includeAgent ? "  agent-run-data:" : "");
+`).replace("__OPENSEARCH_SERVER_ENV__", includeSearch ? `      OPENSEARCH_URL: \${OPENSEARCH_URL:-}
+      OPENSEARCH_USERNAME: \${OPENSEARCH_USERNAME:-}
+      OPENSEARCH_PASSWORD: \${OPENSEARCH_PASSWORD:-}
+      OPENSEARCH_WORK_ORDER_INDEX: \${OPENSEARCH_WORK_ORDER_INDEX:-windy-work-orders-v1}` : "").replace("__OPENSEARCH_SERVICE__", includeSearch ? openSearchComposeService : "").replace("__OPTIONAL_VOLUMES__", [
+    includeAgent ? "  agent-run-data:" : "",
+    includeSearch ? "  opensearch-data:" : ""
+  ].filter(Boolean).join(`
+`));
 }
 var starterCompose = starterComposeFor(true);
-function environmentExample(includeExample, includeAgent = true) {
+function environmentExample(includeExample, includeAgent = true, includeSearch = true) {
   return `# 复制为 .env 后填写。不要提交真实密码。
 POSTGRES_PASSWORD=
 WINDY_BOOTSTRAP_ADMIN_PASSWORD=
 ${includeAgent ? `
 # Agent profile 仅由服务端 Agent Runtime 读取；不要使用 VITE_ 前缀。
+# ADK Web 调试 profile 不读取以下变量，也不能调用真实业务 Operation 或 Tool。
 PLATFORM_ENABLE_AI=false
 AGENT_SERVER_INTERNAL_TOKEN=
 QWEN_API_URL=
 QWEN_API_KEY=
 QWEN_MODEL=
 AI_PROVIDER_HTTPS_HOST_ALLOWLIST=
+# AI_PROVIDER_AUDIT_RETENTION_DAYS=90
 # AI_PROVIDER_CONNECT_TIMEOUT_MS=5000
 # AI_PROVIDER_REQUEST_TIMEOUT_MS=60000
 # AI_PROVIDER_MAX_RESPONSE_BYTES=2097152
 ` : ""}
 
+${includeSearch ? `# OpenSearch profile 默认不启动；bun run dev:search 会只向 Server 注入容器内地址。
+OPENSEARCH_URL=
+OPENSEARCH_USERNAME=
+OPENSEARCH_PASSWORD=
+# OPENSEARCH_REQUEST_TIMEOUT_MS=3000
+# OPENSEARCH_WORK_ORDER_INDEX=windy-work-orders-v1
+
 # 可选搜索配置；不配置时启用 Manifest 中默认开启的 Provider。${includeExample ? `
 # SEARCH_PROVIDER_KEYS=work-order.ticket.search` : `
 # 当前 core profile 没有业务 SearchProvider；接入业务模块后再配置 Key。`}
 # SEARCH_PROVIDER_TIMEOUT_MS=800
 # SEARCH_HEALTH_TIMEOUT_MS=500
 # SEARCH_MAX_REQUESTS_PER_MINUTE=30
+` : ""}
 `;
 }
 // src/project-files.ts
@@ -1647,6 +1764,7 @@ ${includeAgent ? "- Agent：[Agent Runtime 接入](./platform/agent-runtime.md)
 function starterReadme(projectName, includeExample = true, includeOxc = true, projectLicense = "UNLICENSED", selectedModules = []) {
   const selected = new Set(selectedModules);
   const includeAgent = selected.has("system.agent");
+  const includeSearch = selected.has("system.search");
   const moduleRows = moduleDistributionCatalog.map(({ name, description, selection }) => `| \`${name}\` | ${selected.has(name) ? "已包含" : "未包含"} | ${selection === "required" ? "H0" : "H2"} | ${description} |`).join(`
 `);
   return `# ${projectName}
@@ -1722,6 +1840,32 @@ bun run dev:agent
 MCP 客户端使用 \`http://localhost:9747/api/mcp\`，并通过平台 Bearer Token 或 Session
 Cookie 鉴权。该入口只发现当前账号获准的只读 Tool；每次调用都会重新执行 Feature、
 RBAC 和数据范围校验。
+
+ADK Web 仅用于本机开发调试：
+
+\`\`\`bash
+bun run dev:adk-web
+\`\`\`
+
+访问 \`http://127.0.0.1:8000\`。该独立 \`agent-debug\` profile 只加载无 Provider、
+无业务 Tool 的受控调试 Agent，不接收 Actor 或 Execution Grant，也不能代表真实业务
+Operation；普通 \`dev\`、\`agent\` profile 和生产部署均不会启动或暴露它。
+` : ""}
+${includeSearch ? `
+## OpenSearch 搜索 profile
+
+全局搜索默认使用各业务模块自己的 Repository Provider，不依赖外部搜索服务。需要验证
+可重建索引 Adapter 时运行：
+
+\`\`\`bash
+bun run dev:search
+\`\`\`
+
+该命令显式启动 OpenSearch 并只向 Server 注入容器内地址；普通 \`bun run dev\` 不会
+启动 OpenSearch。OpenSearch 只保存可重建的业务搜索投影，PostgreSQL 仍是事实源，最终
+结果会再次经过目标资源权限与 dataScope 校验。宿主机调试端口仅绑定
+\`127.0.0.1:19200\`，不要直接暴露到客户网络。接入细节见
+[SearchProvider 协议](./docs/architecture/search-provider-protocol.md)。
 ` : ""}
 
 ## 页面与登录
@@ -1777,6 +1921,7 @@ bun run dev
 bun run dev:build
 bun run dev:web
 bun run dev:server
+${includeSearch ? "bun run dev:search" : ""}
 bun run typecheck
 bun run test
 bun run build
@@ -1850,7 +1995,13 @@ function createStarterPackage(source, projectName, includeOxc = true, projectLic
       dev: "docker compose up",
       "docker:sync": "create-windy sync-docker",
       "dev:build": "bun run docker:sync && docker compose up --build",
-      ...selectedModules.includes("system.agent") ? { "dev:agent": "docker compose --profile agent up --build" } : {},
+      ...selectedModules.includes("system.search") ? {
+        "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build"
+      } : {},
+      ...selectedModules.includes("system.agent") ? {
+        "dev:agent": "docker compose --profile agent up --build",
+        "dev:adk-web": "docker compose --profile agent-debug up --build adk-web-debug"
+      } : {},
       ...generatorVersion ? { windy: "create-windy" } : {},
       "dev:web": "bun run --cwd apps/web dev",
       "dev:server": "bun run --cwd apps/server dev",
@@ -1895,7 +2046,8 @@ var templateRootFiles = [
   "docker-compose.yml",
   "drizzle.config.ts",
   "module-schema.lineages.json",
-  "package.json"
+  "package.json",
+  "scripts/notification-postgres-regression.ts"
 ];
 var templateDirectories = [
   ".agents/skills/windy-business-module",
@@ -1927,6 +2079,7 @@ var templateDocumentationFiles = [
   "docs/architecture/object-storage.md",
   "docs/architecture/search-provider-protocol.md",
   "docs/development/crud-generator.md",
+  "docs/development/custom-error-pages.md",
   "docs/development/custom-login-page.md",
   "docs/license/license-offline-activation-code.md",
   "docs/operations/observability.md",
@@ -1934,6 +2087,7 @@ var templateDocumentationFiles = [
   "docs/platform/agent-runtime.md",
   "docs/platform/audit-reliability.md",
   "docs/platform/bulk-data-jobs.md",
+  "docs/platform/business-user-directory.md",
   "docs/platform/data-access-control.md",
   "docs/platform/module-configuration.md",
   "docs/platform/navigation-registry.md",
@@ -2146,8 +2300,8 @@ async function generateProject(input) {
   const packageJson = JSON.parse(await readFile10(packagePath, "utf8"));
   await writeFile9(packagePath, `${JSON.stringify(createStarterPackage(packageJson, input.projectName, includeOxc, projectLicense, selectedModules, templateMetadata.generatorVersion), null, 2)}
 `);
-  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterComposeFor(selectedModules.includes("system.agent")));
-  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample, selectedModules.includes("system.agent")));
+  await writeFile9(join10(input.targetDirectory, "docker-compose.yml"), starterComposeFor(selectedModules.includes("system.agent"), selectedModules.includes("system.search")));
+  await writeFile9(join10(input.targetDirectory, ".env.example"), environmentExample(includeExample, selectedModules.includes("system.agent"), selectedModules.includes("system.search")));
   await writeFile9(join10(input.targetDirectory, "README.md"), starterReadme(input.projectName, includeExample, includeOxc, projectLicense, selectedModules));
   await writeFile9(join10(input.targetDirectory, "docs/README.md"), starterDocsReadme(selectedModules.includes("system.license"), selectedModules.includes("system.agent")));
   await reflectCodeQualityChoice(input.targetDirectory, includeOxc);
@@ -4364,7 +4518,9 @@ var recipes = [
   { id: "starter-0.2.29-to-0.2.30", from: "0.2.29", to: "0.2.30" },
   { id: "starter-0.2.30-to-0.2.31", from: "0.2.30", to: "0.2.31" },
   { id: "starter-0.2.31-to-0.2.32", from: "0.2.31", to: "0.2.32" },
-  { id: "starter-0.2.32-to-0.2.33", from: "0.2.32", to: "0.2.33" }
+  { id: "starter-0.2.32-to-0.2.33", from: "0.2.32", to: "0.2.33" },
+  { id: "starter-0.2.33-to-0.2.34", from: "0.2.33", to: "0.2.34" },
+  { id: "starter-0.2.34-to-0.3.0", from: "0.2.34", to: "0.3.0" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (sourceVersion === targetVersion)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.2.33",
+  "version": "0.3.0",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.agents/skills/windy-business-module/SKILL.md

@@ -18,14 +18,23 @@ description: "Windy 业务模块、Manifest、Repository、Service、Agent Tool
    其它模块只能通过 Service、公开 Port 或模块注册机制协作。
 4. Server 通过 `InstallableServerModule` 和 `ModuleHost` 注册 Guarded Route、Task、
    Provider 或 Tool Handler。Handler 调用 Service，不直接访问其它模块 Repository。
+   需要选择启用用户时使用 `ModuleRequestContext.userDirectory`；不要导入用户 Admin
+   Repository。业务 RolePreset 不能注册平台 Permission，部署管理员须显式向业务角色
+   授予 `system.user-directory.read` 并配置数据范围。
 5. Tool 输入输出只使用 Manifest 已注册的顶层 object JSON Schema。Actor、Permission、
    Feature、License 和 Data Scope 只来自 `ModuleToolContext` 与平台 Runtime。
+   Tool 或 Route 需要读取同业务范围内其他用户上传的文件时，在 Host 注册精确
+   `purpose + resourceType` 的 `registerResourceFileAccessPolicies()`；Resolver 必须用
+   project-owned Repository 回查资源与 fileId 绑定及对象级授权，只返回布尔判定，
+   再通过 `context.storage.openResourceFile()` 取得最小元数据与流。禁止注入
+   UploadRepository、BlobStore 或申请平台 manage Repository。
 6. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
    MCP；不要编辑 MCP Adapter 或复制 Tool 定义。写操作在幂等、审批和结果追踪闭环前
    不通过 MCP 暴露。
 7. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
    涉及 Tool 时还要覆盖 Schema 拒绝、数据范围与未授权发现/调用；涉及可选模块时覆盖
-   Starter 的文件、依赖和数据库裁剪。
+   Starter 的文件、依赖和数据库裁剪。涉及资源文件时还要覆盖跨上传者成功、资源绑定/
+   purpose/Feature/Permission/Scope 任一拒绝、最小元数据与成功/拒绝审计。
 8. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
    小切片提交。
 

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "395761d19b6dac6f4135547bedf996e3a53249a7",
-  "generatorVersion": "0.2.33",
+  "templateCommit": "c6c39b2cac4c74ed6352c50e89a4bcddab0eafc7",
+  "generatorVersion": "0.3.0",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -44,6 +44,13 @@
   `apps/web/src/pages/auth/LoginPage.vue` 或 Router。业务页面复用
   `useLoginFlow`、`DevelopmentAuthWarning` 和平台品牌设置，保留安全
   `returnTo`、真实认证与开发认证提示。
+- 定制 404、500、维护中或网络异常页时，只修改 project-owned 的
+  `apps/web/src/app/error-pages.ts`，并把业务 SFC 放在 `apps/web/src/app/`；
+  保留四个类型化注册项，不要为换视觉修改 Router、HTTP 核心或平台默认错误页。
+- 业务 Agent Operation 开启 Provider 出网时，必须在 Manifest 同时声明最小
+  `providerDataPolicy.inputFields` JSON Pointer allowlist 与
+  `envelopeFields`；raw input 会在进入 `prepare` 前裁剪并执行 DLP。接入与升级
+  诊断见 `docs/platform/agent-runtime.md`。
 
 ## 常用入口
 
@@ -51,6 +58,8 @@
   或 MCP 暴露时使用的仓库内开发流程。
 - `docs/development/custom-login-page.md`：完整替换登录页的 ownership、认证复用和
   升级迁移说明。
+- `docs/development/custom-error-pages.md`：统一错误语义、Request ID 与业务页面
+  替换方式。
 - `bun run dev`：复用 Docker 镜像启动 PostgreSQL、自动 migration、Server 与支持热更新的 Web。
 - `bun run dev:build`：依赖、Dockerfile 或 lockfile 变化后重建并启动开发环境。
 - `bun run dev:web`：启动 Web 开发服务。

package/template/README.md

@@ -53,6 +53,7 @@ bun run dev:server
 `DATABASE_URL` 时使用内存模式。
 
 
+
 ## 页面与登录
 
 全新数据库的初始平台账号为 `admin`。初始密码不是所有项目共用的固定值，而是
@@ -100,7 +101,7 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | `system.storage` | 未包含 | H2 | 上传、下载和对象生命周期。 |
 | `system.agent` | 未包含 | H2 | 受控 Agent 工具宿主。 |
 | `system.scheduler` | 未包含 | H2 | 任务、重试、历史和恢复。 |
-| `system.notification` | 未包含 | H2 | 通知发布、阅读和归档。 |
+| `system.notification` | 未包含 | H2 | 通知定向与定时发布、用户偏好、外部渠道投递、修改历史、阅读、收藏和归档。 |
 | `system.workflow` | 未包含 | H2 | 审批、转交、超时和补偿。 |
 | `system.bulk-data` | 未包含 | H2 | 批量导入导出与结果留存。 |
 | `system.search` | 未包含 | H2 | 权限感知搜索与 Provider 聚合。 |
@@ -121,6 +122,7 @@ bun run dev
 bun run dev:build
 bun run dev:web
 bun run dev:server
+
 bun run typecheck
 bun run test
 bun run build

package/template/apps/agent-server/Dockerfile

@@ -8,6 +8,7 @@ RUN pip install --no-cache-dir uv==0.9.27 \
 COPY apps/agent-server/pyproject.toml apps/agent-server/uv.lock ./
 RUN uv sync --frozen --no-dev --no-install-project
 COPY apps/agent-server/src ./src
+COPY apps/agent-server/adk_web_agents ./adk_web_agents
 RUN uv sync --frozen --no-dev
 
 ENV PATH="/app/apps/agent-server/.venv/bin:${PATH}"

package/template/apps/agent-server/README.md

@@ -1,8 +1,9 @@
 # Southwind AI Agent Server
 
 Python 3.12 Agent Runtime。HTTP 层只公开 Southwind AI canonical Agent
-contracts。当前可用 Adapter 连接 OpenAI-compatible `/chat/completions`；Google ADK
-仍只是未配置 Provider 时安全拒绝的内部 Adapter。
+contracts。真实业务 Run 在内部通过 Google ADK 2.5 的 Runner、Session、LlmAgent 和
+Event 执行；ADK 类型不会越过 `AgentEngineAdapter`。模型调用继续复用受治理的
+OpenAI-compatible `/chat/completions` Provider。
 
 ```bash
 uv sync --frozen
@@ -23,7 +24,7 @@ Run 创建使用 `Idempotency-Key`。事件以 SSE 传输，支持 `Last-Event-I
 断线重放，并周期发送 comment heartbeat。Provider 或框架异常只会映射为 canonical
 安全错误，不会把原始异常正文暴露给调用方。
 
-配置以下仅服务端可见的环境变量后，默认运行 OpenAI-compatible Adapter：
+配置以下仅服务端可见的环境变量后，默认运行 ADK Adapter：
 
 ```bash
 export AGENT_SERVER_INTERNAL_TOKEN='<random-token>'
@@ -32,17 +33,39 @@ export QWEN_API_KEY='<server-secret>'
 export QWEN_MODEL='qwen-plus'
 export AI_PROVIDER_HTTPS_HOST_ALLOWLIST='dashscope-intl.aliyuncs.com'
 export AGENT_RUN_STORE_PATH='.data/agent-runs.sqlite3'
+export AI_PROVIDER_AUDIT_STORE_PATH='.data/provider-audit.sqlite3'
+export AI_PROVIDER_AUDIT_RETENTION_DAYS='90'
 uv run uvicorn southwind_agent_server.app:app
 ```
 
 公网 URL 必须使用 HTTPS 且 Host 精确命中 allowlist；本机、容器服务名和内网地址允许
 HTTP。Provider 请求包含连接和总超时、响应大小限制、错误脱敏与 `/models`
 readiness。缺少 URL/Model 时回退
-`AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
-`DeterministicEngineAdapter`。
+未配置的 `AdkEngineAdapter` 并返回 unavailable，不调用模型。测试另使用
+`DeterministicEngineAdapter`。每个 ADK Tool 只声明 Operation 已允许的 Key；其执行
+函数只回调 Southwind AI Tool Host，并携带当前 Run 的 opaque Execution Grant。
 
 未设置 `AGENT_RUN_STORE_PATH` 时使用的 `InMemoryRunStore` **仅用于 deterministic
 测试**。配置路径后使用有界 SQLite Store，可在单副本重启后保留 Run/Event/Result 和
 cursor；多副本部署仍必须替换为共享 Store。Execution Grant 与 Tool 授权由
 Southwind AI Server 签发和复核，Agent Server 不能自行扩大 Operation 的
 `allowedToolKeys`。
+
+每次实际 `/chat/completions` HTTP 调用前，Runtime 会对 Manifest 允许的输入 JSON
+Pointer 与 Provider outbound envelope 字段执行 DLP，并将 deployment、operation、
+run、attempt、分类集合、实际序列化请求字节数和 allow/redact/reject 决策写入独立
+SQLite append-only 表。审计不保存 prompt、请求正文或 Secret；审计写入失败时禁止
+出网。记录到期后只由配置的 TTL 清理，清理计数可通过需内部 Token 的
+`GET /health/provider-governance` 查看。SQLite 实现仅支持单副本；多副本部署必须替换
+为共享、并发安全的审计 Adapter。
+
+开发者可单独启动 ADK Web：
+
+```bash
+bun run dev:adk-web
+```
+
+访问 `http://127.0.0.1:8000`。该 `agent-debug` profile 不读取 Qwen、内部 Token 或
+业务配置，只加载无 Provider、无业务 Tool 的确定性调试 Agent。它用于检查 ADK Web、
+Session 和 Event 交互，不能复现带 Actor/Execution Grant 的真实 Operation，也不能
+作为生产调用入口。

package/template/apps/agent-server/adk_web_agents/__init__.py

@@ -0,0 +1 @@
+"""Developer-only ADK Web agents."""

package/template/apps/agent-server/adk_web_agents/safe_debug/__init__.py

@@ -0,0 +1,3 @@
+from .agent import root_agent
+
+__all__ = ["root_agent"]

package/template/apps/agent-server/adk_web_agents/safe_debug/agent.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from google.adk.agents import LlmAgent
+from google.adk.models.base_llm import BaseLlm
+from google.adk.models.llm_request import LlmRequest
+from google.adk.models.llm_response import LlmResponse
+from google.genai import types
+
+
+class SafeDebugLlm(BaseLlm):
+    async def generate_content_async(
+        self,
+        llm_request: LlmRequest,
+        stream: bool = False,
+    ) -> AsyncGenerator[LlmResponse, None]:
+        del llm_request, stream
+        text = (
+            "这是 Windy 的 ADK 开发调试 Agent。"
+            "它不连接业务 Repository、Tool Host 或模型 Provider，"
+            "不能代表生产业务 Operation。"
+        )
+        yield LlmResponse(
+            content=types.Content(
+                role="model",
+                parts=[types.Part(text=text)],
+            ),
+            partial=False,
+        )
+
+
+root_agent = LlmAgent(
+    name="safe_debug",
+    model=SafeDebugLlm(model="windy-safe-debug"),
+    instruction=(
+        "仅说明开发调试边界；不访问业务数据，不调用 Tool，不连接模型 Provider。"
+    ),
+    tools=[],
+)

package/template/apps/agent-server/pyproject.toml

@@ -21,7 +21,7 @@ dev = [
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
-pythonpath = ["src"]
+pythonpath = [".", "src"]
 testpaths = ["tests"]
 
 [tool.ruff]