create-windy 0.3.19 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.3.19",
+  "version": "0.4.1",
   "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": "45fdbe8e2a55dff118933af58a60976e9bfe318c",
-  "generatorVersion": "0.3.19",
+  "templateCommit": "67920c05352fe2d560c018f6b26e5e81e78291b0",
+  "generatorVersion": "0.4.1",
   "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/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(

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

@@ -14,6 +14,7 @@ import {
   type ModuleToolHandlers,
   type PlatformToolExecutionContext,
 } from "./tool-registry.js";
+import type { StaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -85,9 +86,16 @@ export function createSystemToolHandlers(
 export function registerAgentRoutes(
   app: RouteApp,
   registry: GovernedToolRegistry,
+  authorizer: StaticRouteAuthorizer,
 ) {
   app.get("/agent/tools", async (rawContext) => {
     const { guardContext } = rawContext as RouteContext;
+    const denied = await authorizer.authorize(
+      guardContext,
+      "GET",
+      "/api/agent/tools",
+    );
+    if (denied) return denied;
     return Promise.all(
       registry.definitions().map(async (tool) => ({
         key: tool.key,
@@ -103,6 +111,12 @@ export function registerAgentRoutes(
 
   app.post("/agent/tools/:key/execute", async (rawContext) => {
     const context = rawContext as RouteContext;
+    const denied = await authorizer.authorize(
+      context.guardContext,
+      "POST",
+      "/api/agent/tools/:key/execute",
+    );
+    if (denied) return denied;
     try {
       return await registry.execute(
         context.params.key ?? "",

package/template/apps/server/src/agent/runtime-bootstrap.ts

@@ -46,6 +46,11 @@ import { AgentBackgroundOperationExecutor } from "./background-operation.js";
 import type { DeferredAgentBackgroundOperationPortFactory } from "./background-operation-port.js";
 import { UnixSandboxToolClient } from "./sandbox-client.js";
 import { createModuleAiOperationPort } from "../module-host/ai-operation-port.js";
+import {
+  createManifestAuthorizedRouteApp,
+  createStaticRouteAuthorizer,
+} from "../module-host/static-route-authorization.js";
+import { registerUnavailableAiRoutes } from "./unavailable-routes.js";
 
 export function registerAgentPlatformRuntime(input: {
   app: RouteApp;
@@ -79,18 +84,29 @@ export function registerAgentPlatformRuntime(input: {
     toolHandlers,
     input.runtime,
   );
-  registerAgentRoutes(input.app, toolRegistry);
+  const routeAuthorizer = createStaticRouteAuthorizer(
+    input.runtime,
+    input.modules,
+  );
+  registerAgentRoutes(input.app, toolRegistry, routeAuthorizer);
   registerMcpRoutes(
     input.app,
     new PlatformMcpAdapter(toolRegistry, input.runtime, features),
   );
   if (!input.platformConfig.enableAI) {
+    registerUnavailableAiRoutes(
+      createManifestAuthorizedRouteApp(input.app, routeAuthorizer),
+    );
     return {
       toolHandlers,
       aiArtifacts: undefined,
       aiOperations: undefined,
     };
   }
+  const aiRouteApp = createManifestAuthorizedRouteApp(
+    input.app,
+    routeAuthorizer,
+  );
   const internalToken = requiredEnvironment("AGENT_SERVER_INTERNAL_TOKEN");
   const aiArtifacts = new AiArtifactRuntime(
     new AiArtifactCodec(requiredEnvironment("AI_ARTIFACT_ENCRYPTION_SECRET")),
@@ -100,7 +116,7 @@ export function registerAgentPlatformRuntime(input: {
     input.storage,
     resolveAgentActor,
   );
-  registerAiArtifactRoutes(input.app, aiArtifacts, internalToken);
+  registerAiArtifactRoutes(aiRouteApp, aiArtifacts, internalToken);
   const remote = new RemoteAgentRuntime({
     baseUrl: process.env.AGENT_SERVER_URL || "http://agent-server:8080",
     internalToken,
@@ -127,7 +143,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
     grants,
   );
-  registerDocumentRunRoutes(input.app, documentFacade, documentRemote);
+  registerDocumentRunRoutes(aiRouteApp, documentFacade, documentRemote);
   const speechRemote = process.env.SPEECH_SERVER_URL?.trim()
     ? new RemoteSpeechRuntime({
         baseUrl: process.env.SPEECH_SERVER_URL,
@@ -142,7 +158,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
     grants,
   );
-  registerSpeechRunRoutes(input.app, speechFacade, speechRemote);
+  registerSpeechRunRoutes(aiRouteApp, speechFacade, speechRemote);
   const embeddingRemote = process.env.EMBEDDING_SERVER_URL?.trim()
     ? new RemoteEmbeddingRuntime({
         baseUrl: process.env.EMBEDDING_SERVER_URL,
@@ -156,7 +172,7 @@ export function registerAgentPlatformRuntime(input: {
     embeddingRemote,
     aiArtifacts,
   );
-  registerEmbeddingRoutes(input.app, embeddingFacade);
+  registerEmbeddingRoutes(aiRouteApp, embeddingFacade);
   const agentFacade = new AgentRunFacade(
     input.modules,
     input.hosts,
@@ -166,7 +182,7 @@ export function registerAgentPlatformRuntime(input: {
     aiArtifacts,
   );
   registerAgentRunRoutes(
-    input.app,
+    aiRouteApp,
     agentFacade,
     remote,
     new RestrictedAgentToolHost(

package/template/apps/server/src/agent/sandbox-worker.ts

@@ -1,6 +1,6 @@
-import { installedBusinessModules } from "../installed-business-modules.js";
 import { SandboxToolRegistry } from "./sandbox-registry.js";
 import { runSandboxWorkerUntilSignal } from "./sandbox-worker-server.js";
+import { runtimeBusinessModules } from "../module-host/runtime-composition.js";
 
 const socketPath =
   process.env.TOOL_SANDBOX_SOCKET?.trim() ||
@@ -8,5 +8,5 @@ const socketPath =
 
 await runSandboxWorkerUntilSignal(
   socketPath,
-  new SandboxToolRegistry(installedBusinessModules),
+  new SandboxToolRegistry(runtimeBusinessModules),
 );

package/template/apps/server/src/agent/unavailable-routes.ts

@@ -0,0 +1,33 @@
+import type { RouteApp } from "../system/route-types.js";
+
+const unavailableRoutes = [
+  ["GET", "/internal/ai/artifacts"],
+  ["POST", "/document/runs"],
+  ["GET", "/document/runs/:runId/events"],
+  ["GET", "/document/runs/:runId/result"],
+  ["POST", "/document/runs/:runId/cancel"],
+  ["POST", "/speech/runs"],
+  ["GET", "/speech/runs/:runId/events"],
+  ["GET", "/speech/runs/:runId/result"],
+  ["GET", "/speech/runs/:runId/artifact"],
+  ["POST", "/speech/runs/:runId/cancel"],
+  ["POST", "/embeddings"],
+  ["POST", "/agent/runs"],
+  ["GET", "/agent/runs/:runId/events"],
+  ["GET", "/agent/runs/:runId/result"],
+  ["POST", "/agent/runs/:runId/cancel"],
+  ["POST", "/agent/runs/:runId/attach"],
+  ["POST", "/internal/agent/tools/execute"],
+] as const;
+
+export function registerUnavailableAiRoutes(app: RouteApp): void {
+  const unavailable = () =>
+    Response.json(
+      { code: "RUNTIME_UNAVAILABLE", message: "AI Runtime 未启用" },
+      { status: 503 },
+    );
+  for (const [method, path] of unavailableRoutes) {
+    if (method === "GET") app.get(path, unavailable);
+    else app.post(path, unavailable);
+  }
+}