create-windy 0.3.18 → 0.4.0

package/package.json

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

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

@@ -10,51 +10,75 @@ description: "Windy 业务模块、Manifest、Repository、Service、Agent Tool
 
 ## 工作流
 
-1. 选择一个稳定的能力基础 Key 和模块命名空间。先定义业务边界、Actor、数据归属与
+1. 先运行 `windy module list` 读取项目实际装配；安装、启用、停用、升级或移除模块时，
+   先执行对应命令的 `--dry-run`，再处理兼容范围、依赖、配置、权限与 Migration 提示。
+   不直接修改 `node_modules`、`.windy` 升级元数据，也不为新增入口改写客户 Admin
+   layout。当前 CLI 对无法安全自动改变的 source/template 模块会 fail closed；按报告
+   修改 project-owned Composition，不能伪造安装成功。
+2. 选择一个稳定的能力基础 Key 和模块命名空间。先定义业务边界、Actor、数据归属与
    失败语义，再改代码。
-2. 在业务 package 的 Module Manifest 一次性注册 Feature、Permission、API、
+3. 在业务 package 的 Module Manifest 一次性注册 Feature、Permission、API、
    菜单/入口、审计动作，以及需要的 Task、Provider、JSON Schema 和 Tool。
-3. 数据层使用 Drizzle Schema、前向 Migration 和 Repository；Service 持有业务规则，
+   Feature 直接使用能力基础 Key，Permission 在同一 Key 后追加动作；Route、Task、
+   Tool、Provider 与 Durable Handler 只能绑定这里已注册且基础 Key 一致的能力。
+4. 数据层使用 Drizzle Schema、前向 Migration 和 Repository；Service 持有业务规则，
    其它模块只能通过 Service、公开 Port 或模块注册机制协作。
-4. Server 通过 `InstallableServerModule` 和 `ModuleHost` 注册 Guarded Route、Task、
+5. 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、
+6. 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. 业务资源包含敏感字段时，在 Manifest 一次声明 Data Policy、standard read、
+7. 业务资源包含敏感字段时，在 Manifest 一次声明 Data Policy、standard read、
    sensitive-disclosure reveal、governed-export Permission 与 masked/reveal API 绑定，
    再用 `registerGovernedResources()` 分别注册对象授权 Resolver 和去除治理字段的投影。
    需要导出时再登记四个 Manifest API 绑定、受控查询校验和 cursor 分页 Source；审批、
    Durable Job、水印、TTL、下载与取消由宿主负责。业务不自行签发明文 Grant、校验密码，
    也不接触 Workflow、BlobStore 或平台 Repository。
-7. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
+8. 若项目包含 `system.agent`，`operation=query` 的 Tool 会由同一 Registry 自动进入
    MCP；不要编辑 MCP Adapter 或复制 Tool 定义。写操作在幂等、审批和结果追踪闭环前
    不通过 MCP 暴露。
    对无需 Actor、Repository、Secret、文件系统或外网的纯计算 Tool，可改用
    `setupSandbox()` 注册；此入口必须同步且无副作用，Handler 只能使用输入、
    `idempotencyKey` 与 `AbortSignal`。需要业务数据或外部服务的 Tool 必须保留在普通
    `setup()`，不能为了使用 Sandbox 绕过依赖边界。
-8. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
+9. 补 Manifest/Composition、Repository/Service、Guard 拒绝和 Handler 契约测试。
+   涉及 Durable Handler 时覆盖 Feature/Permission/Audit 绑定，并证明首次执行、重试和
+   恢复都会按当前 License、Feature 与 RBAC 状态重新授权。
    涉及 Tool 时还要覆盖 Schema 拒绝、数据范围与未授权发现/调用；涉及可选模块时覆盖
    Starter 的文件、依赖和数据库裁剪。涉及资源文件时还要覆盖跨上传者成功、资源绑定/
    purpose/Feature/Permission/Scope 任一拒绝、最小元数据与成功/拒绝审计。
    涉及 Sandbox Tool 时还要覆盖无网络、无平台 Secret、无宿主数据挂载、Worker
    重启恢复，以及策略拒绝与业务失败审计分类。
-9. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
-   小切片提交。
+10. 更新长期文档，运行受影响测试、`bun run typecheck` 和 `bun run lint`，按一个完整
+    小切片提交。
+
+## 项目所有权与自动装配
+
+- `apps/web/src`、`apps/server/src/app`、业务模块源码和
+  `windy.modules.json` 都是 project-owned；客户可以修改或替换。日常模块命令只更新
+  package/锁文件与装配声明，不覆盖 Admin、Router、layout 或 Server Composition。
+- Admin Host 从启用模块的 `./admin` 与 Manifest 贡献投影页面、入口和可见性。客户可
+  隐藏、排序或替换展示；模块不得直接写侧边栏源码。
+- Server Host 只接受 canonical `./manifest`、声明兼容范围的 Adapter 和显式
+  attachment。动态 package 不获得数据库或平台 Repository；需要项目 Repository 的
+  模块在 project-owned Composition 中装配。
+- 每次安装、构建和 Server 监听前都必须执行同一套 Manifest/实现双向校验。未知、
+  重复、缺失声明以及 setup 后替换或变异 canonical Manifest 都应 fail closed。
 
 ## 代码事实源
 
 - Manifest 与 Tool 类型：`packages/modules/src/manifest.ts`
 - Tool 组合校验：`packages/modules/src/tool-composition.ts`
 - 模块 Host 契约：`packages/server-sdk/src/module-host.ts`
+- Durable Handler 契约：`packages/server-sdk/src/durable-handler.ts`
+- 项目模块生命周期：`packages/create-windy/src/module-lifecycle-resolver.ts`
 - Tool Handler 契约：`packages/server-sdk/src/tool-registration.ts`
 - Sandbox Tool 契约：`packages/server-sdk/src/sandbox-tool.ts`
 - 可移除业务示例：`packages/example-work-order/`、`apps/server/src/work-order/`

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "f1470acc1588deb087d3144a76b0729affed0988",
-  "generatorVersion": "0.3.18",
+  "templateCommit": "50d32b9470dbf55110aba320338f5e54ed896c77",
+  "generatorVersion": "0.4.0",
   "modules": [
     {
       "name": "system",

package/template/AGENTS.md

@@ -40,20 +40,30 @@
   共享脚手架或根工具链同样受支持，但通常会增加后续三方合并成本。
 - 修改前可查看 ownership 评估升级风险；优先扩展 `project-owned` 路径，对
   `windy-managed` 路径建议保持改动小而清晰。
+- `windy.modules.json` 是 project-owned 模块装配选择：可调整启用、顺序、Admin
+  可见性与模块配置；package 只写无版本入口，实际版本以 `package.json` 和
+  `bun.lock` 为准。日常模块命令不得为了装配入口改写客户 Router、layout 或 Host。
+- 整个 `apps/web/src` 与整个 `apps/server/src/app` 都是 project-owned。普通
+  `windy update` 不覆盖或三方合并客户的 Admin、Router、layout、页面、Host 或
+  Server 组合。
+- 当前没有 H3 模块，也不支持任意 npm package 名称安装。日常只使用
+  `module list/enable/disable`；内置模块的 add/update/remove 实际集合变化会在写入前
+  fail closed。`system.settings`、`system.storage` 与
+  `system.data-governance` 不能只靠 registry 安全停用。
 - 直接修改 Windy 基线代码时，使用独立小提交记录原因和影响；升级前先运行
   `bun run windy update --dry-run`，根据三方合并计划处理冲突。
-- 完整定制登录页时，在 project-owned 的
-  `apps/web/src/app/auth/login-page.ts` 注册业务组件可获得最低升级成本。若直接修改
-  `apps/web/src/pages/auth/LoginPage.vue` 或 Router，升级器会尝试三方合并。业务页面复用
+- 完整定制登录页时，可在 `apps/web/src/app/auth/login-page.ts` 注册业务组件，也可
+  直接修改 `apps/web/src/pages/auth/LoginPage.vue` 或 Router；这些文件均由项目拥有。
+  业务页面复用
   `useLoginFlow`、`DevelopmentAuthWarning` 和平台品牌设置，保留安全
   `returnTo`、真实认证与开发认证提示。
-- 定制 404、500、维护中或网络异常页时，优先修改 project-owned 的
+- 定制 404、500、维护中或网络异常页时，可以修改
   `apps/web/src/app/error-pages.ts`，并把业务 SFC 放在 `apps/web/src/app/`；
-  直接修改 Router、HTTP 核心或平台默认错误页时会增加三方合并成本。
+  也可以直接修改项目拥有的 Router 或平台默认错误页。
 - 新增业务管理页面时，在业务 Module Manifest 注册 Feature、Permission、菜单和
-  Admin Route，再把 Vue 页面绑定到 project-owned 的
-  `apps/web/src/app/business-routes.ts` 是推荐接入方式。直接修改 Router 或 AppSidebar
-  时同样按 Base/Ours/Theirs 合并。导航来自服务端 Manifest 快照，接入见
+  Admin Route，并由 package 的 `./admin` 提供默认页面；项目需要替换页面时在
+  `apps/web/src/app/web-composition.ts` 按 route key 覆盖 loader。业务工作台路由可在
+  项目拥有的 Router 中直接实现。导航来自服务端 Manifest 快照，接入见
   `docs/development/business-web-routes.md`。
 - 业务 Agent Operation 开启 Provider 出网时，必须在 Manifest 同时声明最小
   `providerDataPolicy.inputFields` JSON Pointer allowlist 与

package/template/README.md

@@ -62,9 +62,10 @@ Skill 完成该能力”。Skill 只指导开发流程；Feature、Permission、
 运行时事实仍以 Module Manifest 与平台 Registry 为准。
 
 当前组合未包含 `system.agent`，MCP Server、Agent Tool Host 和相关文档已被
-物理裁剪。创建时可增加 `--module system.agent` 或使用 `--all-modules`；已部署
-项目使用 `bun run windy module add system.agent`，不要手工复制 MCP Adapter 或
-另建授权链。仓库 Skill 仍可用于普通业务模块开发。
+物理裁剪。创建时可增加 `--module system.agent` 或使用 `--all-modules`。当前没有
+self-contained H3 模块，已部署项目当前不能通过模块命令补装 `system.agent`；
+`module add` 会在写入前 fail closed。不要手工复制 MCP Adapter 或另建授权链。仓库
+Skill 仍可用于普通业务模块开发。
 
 
 
@@ -101,8 +102,8 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | 法律许可 | `UNLICENSED` |
 
 平台当前注册的全部模块如下。H0 表示 profile 锁定核心；H2 表示创建时可以物理包含或
-排除；H3 还具备部署期安装、更新、数据保留卸载和重装证据。通用生命周期命令会保守
-处理所有目录模块，但只有通过完整 H3 回归的模块才标记为 H3。
+排除；H3 还具备部署期安装、更新、数据保留卸载和重装证据。当前没有 H3 模块，也不
+支持任意 npm package 名称安装。
 
 | Module Key | 当前项目 | 热插拔可靠度 | 说明 |
 | ---------- | -------- | ------------ | ---- |
@@ -121,17 +122,24 @@ create-windy 在本机 `.env` 中随机生成的 `WINDY_BOOTSTRAP_ADMIN_PASSWORD
 | `system.bulk-data` | 未包含 | H2 | 批量导入导出与结果留存。 |
 | `system.search` | 未包含 | H2 | 权限感知搜索与 Provider 聚合。 |
 | `system.data-governance` | 未包含 | H2 | 敏感字段、明文访问和治理导出。 |
-| `work-order` | 未包含 | H3 | 可替换的业务模块接入示例。 |
-
-项目自有业务模块以 `apps/server/src/installed-business-modules.ts` 装配的 Module Manifest
-为准；对应 Vue 页面在 project-owned 的
-`apps/web/src/app/business-routes.ts` 注册，侧栏继续从服务端 Manifest 快照生成。
-不要为增加业务页面修改 shared-scaffold Router 或 AppSidebar。shared-scaffold README
-不复制项目业务 Key，避免平台升级固化产品命名。
-
-精确生成来源和选择记录在 `.windy/generation.json`。当前版本已提供可回滚的
-`windy update` 与 `windy module list/add/update/remove`。Feature Flag 关闭仍不
-等于模块卸载。
+| `work-order` | 未包含 | H2 | 可替换的业务模块接入示例。 |
+
+项目装配选择记录在 project-owned 的 `windy.modules.json`，可提交 Git 并结构化编辑；
+它只保存无版本 package 入口、启用状态、顺序、Admin 可见性与模块配置。依赖版本事实
+仍只来自 `package.json` 与 `bun.lock`。Server 默认从
+`apps/server/src/app/server-composition.ts` 装配 Adapter；Web 通过 package 的
+browser-safe `./admin` 与 project-owned 的
+`apps/web/src/app/web-composition.ts` 装配页面，不复制第二份 Feature、Permission
+或路由清单。整个 `apps/web/src` 与整个 `apps/server/src/app` 都是
+project-owned，客户可以修改 Router、layout、页面、Host 和 Server 组合；普通
+`windy update` 不会覆盖或三方合并这些文件。
+
+精确生成来源保留在 `.windy/generation.json`。当前版本已提供可回滚的
+`windy update` 与 `windy module list/enable/disable`。当前内置模块仍依赖
+source/template 或 project-owned Composition；当前内置模块的 add/update/remove
+实际集合变化会在写入前 fail closed。Feature Flag 关闭、module disable 与物理卸载是
+三个不同动作；`system.settings`、`system.storage` 和
+`system.data-governance` 只能在创建期物理排除，部署后不能只改 registry 安全停用。
 
 ## 常用命令
 
@@ -148,8 +156,7 @@ bun run windy doctor
 bun run windy update --check
 bun run windy update --dry-run
 bun run windy module list
-bun run windy module add work-order --dry-run
-bun run windy module remove work-order --dry-run
+# 当前组合没有可安全 runtime disable 的已安装可选模块
 bun run lint
 bun run format
 ```
@@ -158,7 +165,9 @@ bun run format
 
 更新前无需提交、暂存或清理业务改动。`--dry-run` 只生成计划，不写项目；无关 WIP
 保持原样，命中同一路径时按冻结快照与三方合并 fail closed。正式更新先备份，再做
-package 字段级合并、共享脚手架三方合并与完整验证。任何冲突都会在写入前中止，
+package 字段级合并、共享脚手架三方合并与完整验证。整个 `apps/web/src` 和
+`apps/server/src/app` 保持项目版本。任何冲突都会在写入前中止，模块启停在交互
+终端确认；CI、Agent 或其它非 TTY 环境必须显式传入 `--yes`。
 无并发变化的验证失败会自动回滚；中断恢复使用
 `bun run windy doctor --repair`。该命令在提交点前保留并发编辑并回滚其余路径，
 在 committed 提交点后只完成事务状态与备份清理，不回滚项目文件。
@@ -181,9 +190,10 @@ create-windy 默认建立 `main` 分支并创建 `chore: initialize project` 首
 没有配置 Git 用户身份，文件会保留在暂存区；配置身份后手动提交即可。
 
 当前已交付的 Windy 更新器会根据 Project Lock 和文件所有权，从 Project Lock 指向的
-精确 npm artifact 重建 Base 并执行三方合并；它不连接私有源仓库，也不会静默覆盖项目代码。模块
-生命周期命令复用同一计划、事务、验证与恢复边界；卸载默认保留数据库数据，并要求
-显式确认数据处置计划。
+精确 npm artifact 重建 Base 并执行三方合并；它不连接私有源仓库。
+更新器不会静默覆盖项目代码。`module enable/disable` 只以 CAS 事务更新
+`windy.modules.json`；当前内置模块的 add/update/remove 实际集合变化在生成更新
+计划前即被拒绝。
 
 ## License
 

package/template/apps/agent-server/src/southwind_agent_server/adk_debug.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import json
 import os
 import uuid
@@ -15,6 +16,8 @@ from .config import normalize_base_url
 MAX_QUESTION_LENGTH = 4_000
 MAX_VISIBLE_EVENTS = 64
 MAX_EVENT_FRAME_BYTES = 64 * 1024
+DEFAULT_RESULT_POLL_TIMEOUT_SECONDS = 60.0
+DEFAULT_RESULT_POLL_INTERVAL_SECONDS = 0.5
 
 
 @dataclass(frozen=True)
@@ -99,11 +102,19 @@ class CanonicalRunDebugClient:
         bearer_token: str,
         *,
         transport: httpx.AsyncBaseTransport | None = None,
+        result_poll_timeout_seconds: float = DEFAULT_RESULT_POLL_TIMEOUT_SECONDS,
+        result_poll_interval_seconds: float = DEFAULT_RESULT_POLL_INTERVAL_SECONDS,
     ) -> None:
         self._operation_key = operation_key
         self._base_url = normalize_base_url(base_url)
         self._bearer_token = bearer_token.strip()
         self._transport = transport
+        if not 0 <= result_poll_timeout_seconds <= 120:
+            raise ValueError("result_poll_timeout_seconds 必须在 0 到 120 秒之间")
+        if not 0 < result_poll_interval_seconds <= 1:
+            raise ValueError("result_poll_interval_seconds 必须大于 0 且不超过 1 秒")
+        self._result_poll_timeout_seconds = result_poll_timeout_seconds
+        self._result_poll_interval_seconds = result_poll_interval_seconds
         if not self._bearer_token:
             raise RuntimeError("ADK_DEBUG_PLATFORM_TOKEN 未配置，拒绝启动真实调试 Run")
 
@@ -142,13 +153,35 @@ class CanonicalRunDebugClient:
             )
             run_id = read_run_id(started)
             events = await collect_compact_events(self._events(client, run_id))
-            result = await client.get(
-                f"api/agent/runs/{run_id}/result",
-                params={"operationKey": self._operation_key},
-            )
+            try:
+                async with asyncio.timeout(self._result_poll_timeout_seconds):
+                    while True:
+                        result = await client.get(
+                            f"api/agent/runs/{run_id}/result",
+                            params={"operationKey": self._operation_key},
+                        )
+                        if result.is_success:
+                            break
+                        try:
+                            error = result.json()
+                        except json.JSONDecodeError:
+                            error = None
+                        if (
+                            result.status_code != 409
+                            or not isinstance(error, dict)
+                            or error.get("code") != "RUN_CONFLICT"
+                            or error.get("retryable") is not True
+                        ):
+                            raise RuntimeError("平台 Agent Run 永久失败或结果读取失败")
+                        await asyncio.sleep(self._result_poll_interval_seconds)
+            except TimeoutError as error:
+                raise RuntimeError("平台 Agent Run 结果等待超时") from error
+        answer = read_text_output(result, run_id)
+        if not any(event.get("type") == "run.completed" for event in events):
+            events = [*events[: MAX_VISIBLE_EVENTS - 1], {"type": "run.completed"}]
         return {
             "runId": run_id,
-            "answer": read_text_output(result, run_id),
+            "answer": answer,
             "events": events,
         }
 

package/template/apps/agent-server/tests/test_adk_debug_result_polling.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+
+from southwind_agent_server.adk_debug import CanonicalRunDebugClient
+
+OPERATION_KEY = "customer.copilot.global"
+
+
+async def test_client_waits_for_result_after_stream_closes() -> None:
+    result_attempts = 0
+    started_runs = 0
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal result_attempts, started_runs
+        if request.url.path == "/api/agent/runs":
+            started_runs += 1
+            return httpx.Response(200, json={"runId": "run_race"})
+        if request.url.path.endswith("/events"):
+            return httpx.Response(
+                200,
+                content=(
+                    b'event: run.started\ndata: {"sequence":1,"type":"run.started"}\n\n'
+                ),
+            )
+        if request.url.path.endswith("/result"):
+            result_attempts += 1
+            if result_attempts < 3:
+                return httpx.Response(
+                    409,
+                    json={"code": "RUN_CONFLICT", "retryable": True},
+                )
+            return httpx.Response(
+                200,
+                json={
+                    "runId": "run_race",
+                    "status": "completed",
+                    "output": {"text": "稍后可读"},
+                },
+            )
+        raise AssertionError(request.url)
+
+    client = CanonicalRunDebugClient(
+        OPERATION_KEY,
+        "https://platform.test",
+        "developer-token",
+        transport=httpx.MockTransport(handler),
+        result_poll_interval_seconds=0.001,
+    )
+
+    result = await client.run("验证竞态")
+
+    assert result["answer"] == "稍后可读"
+    events = result["events"]
+    assert isinstance(events, list) and {"type": "run.completed"} in events
+    assert started_runs == 1
+    assert result_attempts == 3
+
+
+@pytest.mark.parametrize(
+    ("payload", "timeout_seconds", "delay_seconds", "message"),
+    [
+        (
+            {
+                "code": "RUN_CANCELLED",
+                "message": "secret-upstream-body",
+                "retryable": False,
+            },
+            5,
+            0,
+            "永久失败",
+        ),
+        (
+            {
+                "code": "RUN_CONFLICT",
+                "message": "Agent Run 尚未完成",
+                "retryable": True,
+            },
+            0.01,
+            0,
+            "等待超时",
+        ),
+        (
+            {
+                "code": "RUN_CONFLICT",
+                "message": "slow-secret-upstream-body",
+                "retryable": True,
+            },
+            0.01,
+            0.05,
+            "等待超时",
+        ),
+    ],
+)
+async def test_client_bounds_result_polling_and_hides_error_content(
+    payload: dict[str, object],
+    timeout_seconds: float,
+    delay_seconds: float,
+    message: str,
+) -> None:
+    requests: list[httpx.Request] = []
+
+    async def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path == "/api/agent/runs":
+            return httpx.Response(200, json={"runId": "run_terminal"})
+        if request.url.path.endswith("/events"):
+            return httpx.Response(
+                200,
+                content=(
+                    b"event: run.completed\ndata: "
+                    b'{"sequence":1,"type":"run.completed"}\n\n'
+                ),
+            )
+        if request.url.path.endswith("/result"):
+            await asyncio.sleep(delay_seconds)
+            return httpx.Response(409, json=payload)
+        raise AssertionError(request.url)
+
+    client = CanonicalRunDebugClient(
+        OPERATION_KEY,
+        "https://platform.test",
+        "developer-token",
+        transport=httpx.MockTransport(handler),
+        result_poll_timeout_seconds=timeout_seconds,
+        result_poll_interval_seconds=0.001,
+    )
+
+    with pytest.raises(RuntimeError, match=message) as failure:
+        await client.run("验证结果失败")
+
+    error_message = str(failure.value)
+    assert "secret-upstream-body" not in error_message
+    assert "slow-secret-upstream-body" not in error_message
+    assert sum(request.url.path == "/api/agent/runs" for request in requests) == 1
+    assert sum(request.url.path.endswith("/result") for request in requests) >= 1

package/template/apps/server/Dockerfile

@@ -4,6 +4,7 @@ FROM oven/bun:1.3.14-alpine AS deps
 WORKDIR /app
 
 COPY package.json bun.lock ./
+COPY windy.modules.json windy.modules.json
 # windy-copy:deps begin
 COPY apps/license/package.json apps/license/package.json
 COPY apps/server/package.json apps/server/package.json

package/template/apps/server/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "build": "bun run scripts/validate-module-composition.ts",
     "dev": "bun --watch run src/index.ts",
     "start": "bun run src/index.ts",
     "typecheck": "tsc --noEmit --project tsconfig.json"

package/template/apps/server/scripts/validate-module-composition-once.ts

@@ -0,0 +1,4 @@
+process.argv.push("--validate-module-composition");
+delete process.env.DATABASE_URL;
+
+await import("../src/index.js");

package/template/apps/server/scripts/validate-module-composition.ts

@@ -0,0 +1,28 @@
+import { spawnSync } from "node:child_process";
+
+const variants = [
+  { name: "default", env: { PLATFORM_ENABLE_AI: "false" } },
+  {
+    name: "ai-enabled",
+    env: {
+      PLATFORM_ENABLE_AI: "true",
+      AGENT_SERVER_INTERNAL_TOKEN: "0123456789abcdef0123456789abcdef",
+      AI_ARTIFACT_ENCRYPTION_SECRET: "abcdef0123456789abcdef0123456789",
+    },
+  },
+] as const;
+
+for (const variant of variants) {
+  const result = spawnSync(
+    process.execPath,
+    ["run", "scripts/validate-module-composition-once.ts"],
+    {
+      cwd: process.cwd(),
+      env: { ...process.env, ...variant.env, DATABASE_URL: "" },
+      stdio: "inherit",
+    },
+  );
+  if (result.status !== 0) {
+    throw new Error(`${variant.name} Module Composition 验证失败`);
+  }
+}

package/template/apps/server/src/agent/data-scope-routes.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { buildScopeContext } from "../data-access/context.js";
 import { createFoundationSnapshot, loadSystemModules } from "../foundation.js";
 import { createServerRuntime } from "../runtime.js";
+import { createStaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 import { FakeRouteApp } from "../system/route-test-app.js";
 import { createSystemRepositories } from "../system/seed.js";
 import {
@@ -13,7 +14,11 @@ import { GovernedToolRegistry } from "./tool-registry.js";
 
 describe("Agent Tool data scope", () => {
   test("启动时拒绝 Manifest 与 Handler 不一致", () => {
-    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const snapshot = createFoundationSnapshot();
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      { featureCatalog: snapshot.features },
+    );
     const handlers = createSystemToolHandlers(
       createSystemRepositories(createFoundationSnapshot()),
       runtime,
@@ -41,8 +46,12 @@ describe("Agent Tool data scope", () => {
   test("用户 Tool 忽略客户端 ownership 参数并使用 Server self scope", async () => {
     const snapshot = createFoundationSnapshot();
     const repositories = createSystemRepositories(snapshot);
-    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      { featureCatalog: snapshot.features },
+    );
     const app = new FakeRouteApp();
+    const modules = loadSystemModules();
     const guardContext = await runtime.createGuardContext(
       authenticatedRequest(),
     );
@@ -64,10 +73,11 @@ describe("Agent Tool data scope", () => {
     registerAgentRoutes(
       app,
       new GovernedToolRegistry(
-        loadSystemModules(),
+        modules,
         createSystemToolHandlers(repositories, runtime),
         runtime,
       ),
+      createStaticRouteAuthorizer(runtime, modules),
     );
     guardContext.actor = {
       ...guardContext.actor,
@@ -94,15 +104,20 @@ describe("Agent Tool data scope", () => {
 
   test("请求级 Tool 缺少 Server ScopeContext 时 fail closed", async () => {
     const snapshot = createFoundationSnapshot();
-    const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
+    const runtime = createServerRuntime(
+      { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+      { featureCatalog: snapshot.features },
+    );
     const app = new FakeRouteApp();
+    const modules = loadSystemModules();
     registerAgentRoutes(
       app,
       new GovernedToolRegistry(
-        loadSystemModules(),
+        modules,
         createSystemToolHandlers(createSystemRepositories(snapshot), runtime),
         runtime,
       ),
+      createStaticRouteAuthorizer(runtime, modules),
     );
     const guardContext = await runtime.createGuardContext(
       authenticatedRequest(),

package/template/apps/server/src/agent/routes.test.ts

@@ -5,6 +5,7 @@ import {
 } from "@southwind-ai/shared";
 import { createFoundationSnapshot, loadSystemModules } from "../foundation.js";
 import { createServerRuntime } from "../runtime.js";
+import { createStaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 import type { RouteApp } from "../system/routes.js";
 import { createSystemRepositories } from "../system/seed.js";
 import { createSystemToolHandlers, registerAgentRoutes } from "./routes.js";
@@ -37,12 +38,18 @@ class FakeRouteApp implements RouteApp {
 }
 
 function routeFixture(features?: FeatureFlagDefinition[]) {
-  const runtime = createServerRuntime({ WINDY_DEV_ADMIN_TOKEN: "token_1" });
   const app = new FakeRouteApp();
-  const modules = loadSystemModules();
-  if (features) {
-    modules[0] = { ...modules[0]!, features };
-  }
+  const overrides = new Map(features?.map((feature) => [feature.key, feature]));
+  const modules = loadSystemModules().map((module) => ({
+    ...module,
+    features: module.features.map(
+      (feature) => overrides?.get(feature.key) ?? feature,
+    ),
+  }));
+  const runtime = createServerRuntime(
+    { WINDY_DEV_ADMIN_TOKEN: "token_1" },
+    { featureCatalog: modules.flatMap((module) => module.features) },
+  );
   registerAgentRoutes(
     app,
     new GovernedToolRegistry(
@@ -53,6 +60,7 @@ function routeFixture(features?: FeatureFlagDefinition[]) {
       ),
       runtime,
     ),
+    createStaticRouteAuthorizer(runtime, modules),
   );
   return { app, runtime };
 }
@@ -189,16 +197,21 @@ describe("agent routes", () => {
     await repositories.features.syncManifest(snapshot.features);
     const runtime = createServerRuntime(
       { WINDY_DEV_ADMIN_TOKEN: "token_1" },
-      { featureResolver: repositories.features },
+      {
+        featureCatalog: snapshot.features,
+        featureResolver: repositories.features,
+      },
     );
     const app = new FakeRouteApp();
+    const modules = loadSystemModules();
     registerAgentRoutes(
       app,
       new GovernedToolRegistry(
-        loadSystemModules(),
+        modules,
         createSystemToolHandlers(repositories, runtime),
         runtime,
       ),
+      createStaticRouteAuthorizer(runtime, modules),
     );
     const request = () =>
       new Request(