create-windy 0.3.17 → 0.3.19

package/template/apps/server/src/runtime-request-actor.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import type { RequestActor } from "./guards.js";
+import { resolveRequestActor } from "./runtime-request-actor.js";
+
+const debugActor: RequestActor = {
+  id: "service_adk_debug",
+  type: "service",
+  name: "ADK 开发调试",
+  roleCodes: ["adk-debug"],
+  permissionKeys: ["analysis.copilot.execute"],
+};
+
+test("保留凭据命中后不回退普通认证", async () => {
+  let standardCalls = 0;
+  const request = new Request("http://localhost/api/foundation");
+  const actor = await resolveRequestActor(
+    request,
+    () => {
+      standardCalls += 1;
+      return {
+        id: "user_regular",
+        type: "user",
+        name: "普通用户",
+        roleCodes: ["user"],
+        permissionKeys: [],
+      };
+    },
+    {
+      claimsRequest: () => true,
+      resolveRequest: () => undefined,
+    },
+  );
+
+  expect(actor).toBeUndefined();
+  expect(standardCalls).toBe(0);
+});
+
+test("保留凭据在 canonical 路径始终解析为专用主体", async () => {
+  const actor = await resolveRequestActor(
+    new Request("http://localhost/api/agent/runs", { method: "POST" }),
+    () => ({
+      id: "user_regular",
+      type: "user",
+      name: "普通用户",
+      roleCodes: ["user"],
+      permissionKeys: ["analysis.copilot.execute"],
+    }),
+    {
+      claimsRequest: () => true,
+      resolveRequest: () => debugActor,
+    },
+  );
+
+  expect(actor).toBe(debugActor);
+});

package/template/apps/server/src/runtime-request-actor.ts

@@ -0,0 +1,22 @@
+import type { RequestActor } from "./guards.js";
+
+export interface ReservedRequestActorResolver {
+  claimsRequest(request: Request): boolean;
+  resolveRequest(
+    request: Request,
+  ): Promise<RequestActor | undefined> | RequestActor | undefined;
+}
+
+export async function resolveRequestActor(
+  request: Request,
+  resolveStandard: () =>
+    | Promise<RequestActor | undefined>
+    | RequestActor
+    | undefined,
+  reserved?: ReservedRequestActorResolver,
+): Promise<RequestActor | undefined> {
+  if (reserved?.claimsRequest(request)) {
+    return reserved.resolveRequest(request);
+  }
+  return resolveStandard();
+}

package/template/apps/server/src/runtime.test.ts

@@ -22,6 +22,9 @@ describe("server runtime", () => {
 
     expect(context.actor.id).toBe("user_dev_admin");
     expect(context.actor.permissionKeys).toContain("system.menu.read");
+    // @windy-module work-order begin
+    expect(context.actor.permissionKeys).toContain("work-order.ticket.read");
+    // @windy-module work-order end
   });
 
   test("生产环境强制关闭开发管理员 token", async () => {

package/template/apps/server/src/runtime.ts

@@ -31,6 +31,13 @@ import {
   requestSourcePolicyFromEnv,
   resolveRequestSource,
 } from "./http/request-source.js";
+import { resolveRequestActor } from "./runtime-request-actor.js";
+// @windy-module system.agent begin
+import {
+  createAdkDebugRuntime,
+  type AdkDebugActorResolver,
+} from "./runtime-adk-debug.js";
+// @windy-module system.agent end
 
 export type {
   FeatureFlagRuntimeResolver,
@@ -78,6 +85,9 @@ export interface ServerRuntimeOptions {
   featureCatalog?: readonly FeatureFlagDefinition[];
   auditWriter?: AuditEventWriter;
   auditReader?: AuditEventReader;
+  // @windy-module system.agent begin
+  adkDebugActorResolver?: AdkDebugActorResolver;
+  // @windy-module system.agent end
 }
 
 export class InMemorySessionStore {
@@ -186,6 +196,19 @@ export function createServerRuntime(
   options: ServerRuntimeOptions = {},
 ) {
   const developmentAuth = readDevelopmentAuthBypass(env);
+  // @windy-module system.agent begin
+  const adkDebug = createAdkDebugRuntime(
+    env,
+    undefined,
+    options.adkDebugActorResolver,
+  );
+  if (adkDebug.usesToken(developmentAuth.token)) {
+    throw new Error("ADK Web 调试 Token 不能复用开发管理员 Token");
+  }
+  if (adkDebug.usesToken(env.AGENT_SERVER_INTERNAL_TOKEN?.trim())) {
+    throw new Error("ADK Web 调试 Token 不能复用 Agent 内部服务 Token");
+  }
+  // @windy-module system.agent end
   const sessionStore = new InMemorySessionStore(
     developmentAuth.token
       ? [{ token: developmentAuth.token, actor: developmentAdminActor() }]
@@ -216,9 +239,15 @@ export function createServerRuntime(
         metadata.clientIp,
         requestSourcePolicy,
       );
-      const actor =
-        (await options.actorResolver?.resolve(request)) ||
-        sessionStore.resolve(request);
+      const actor = await resolveRequestActor(
+        request,
+        async () =>
+          (await options.actorResolver?.resolve(request)) ||
+          sessionStore.resolve(request),
+        // @windy-module system.agent begin
+        adkDebug,
+        // @windy-module system.agent end
+      );
       const license =
         (await options.licenseResolver?.resolve()) || licenseStore.resolve();
       return createRequestGuardContext(request, {
@@ -227,6 +256,10 @@ export function createServerRuntime(
         resolveLicense: () => license,
       });
     },
+    // @windy-module system.agent begin
+    resolveEphemeralActor: adkDebug.resolveActor,
+    agentDebugOperationForActor: adkDebug.operationForActor,
+    // @windy-module system.agent end
     async createGuardContextForActor(
       request: Request,
       actor: RequestActor,

package/template/apps/server/src/scheduler/definitions.test.ts

@@ -8,12 +8,22 @@ describe("平台任务 Manifest Adapter", () => {
     const definitions = createPlatformTaskDefinitions(
       createFoundationSnapshot().features,
       {
+        // @windy-module system.bulk-data begin
         bulkDataDispatch: () => ({ claimed: false }),
         bulkDataCleanup: () => ({ deleted: 0 }),
+        // @windy-module system.bulk-data end
+        // @windy-module system.storage begin
         storageCleanup: () => ({ deleted: 0 }),
+        // @windy-module system.storage end
+        // @windy-module system.workflow begin
         workflowTimeoutDispatch: () => ({ claimed: false }),
+        // @windy-module system.workflow end
+        // @windy-module system.data-governance begin
         governedExportDispatch: () => ({ claimed: false }),
+        // @windy-module system.data-governance end
+        // @windy-module system.notification begin
         notificationDispatch: () => ({ claimed: false }),
+        // @windy-module system.notification end
       },
     );
 
@@ -22,20 +32,26 @@ describe("平台任务 Manifest Adapter", () => {
         .tasks.map(({ key }) => key)
         .sort(),
     );
+    // @windy-module system.bulk-data begin
     expect(
       definitions
         .find(({ key }) => key === "system.bulk-data.dispatch")
         ?.isIdleResult?.({ claimed: false }),
     ).toBe(true);
+    // @windy-module system.bulk-data end
+    // @windy-module system.data-governance begin
     expect(
       definitions
         .find(({ key }) => key === "system.governed-export.dispatch")
         ?.isIdleResult?.({ claimed: false }),
     ).toBe(true);
+    // @windy-module system.data-governance end
+    // @windy-module system.notification begin
     expect(
       definitions
         .find(({ key }) => key === "system.notification.dispatch")
         ?.isIdleResult?.({ claimed: false }),
     ).toBe(true);
+    // @windy-module system.notification end
   });
 });

package/template/docker-compose.agent-debug.yml

@@ -0,0 +1,56 @@
+services:
+  server:
+    environment:
+      PLATFORM_ENABLE_AI: "true"
+      WINDY_ADK_DEBUG_TOKEN: ${ADK_DEBUG_PLATFORM_TOKEN:?请先由 create-windy doctor 修复本地调试 Token}
+      WINDY_ADK_DEBUG_OPERATION_KEY: ${WINDY_ADK_DEBUG_OPERATION_KEY:?项目尚未选择 ADK Web 调试 Operation}
+      WINDY_ADK_DEBUG_DATA_ACTOR_ID: ${WINDY_ADK_DEBUG_DATA_ACTOR_ID:?项目尚未选择 ADK Web 真实开发数据用户}
+
+  adk-web-debug:
+    profiles: ["agent-debug"]
+    build:
+      context: .
+      dockerfile: apps/agent-server/Dockerfile
+    environment:
+      ADK_DEBUG_PLATFORM_URL: http://server:9747
+      ADK_DEBUG_PLATFORM_TOKEN: ${ADK_DEBUG_PLATFORM_TOKEN:?请先由 create-windy doctor 修复本地调试 Token}
+      ADK_DEBUG_OPERATION_KEY: ${WINDY_ADK_DEBUG_OPERATION_KEY:?项目尚未选择 ADK Web 调试 Operation}
+    command:
+      [
+        "adk",
+        "web",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8000",
+        "--no-reload",
+        "--session_service_uri",
+        "memory://",
+        "--artifact_service_uri",
+        "memory://",
+        "--logo-text",
+        "Windy ADK 真实 Run 调试",
+        "--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
+    depends_on:
+      server:
+        condition: service_started
+      agent-server:
+        condition: service_healthy
+      tool-sandbox:
+        condition: service_started

package/template/docker-compose.yml

@@ -100,7 +100,7 @@ services:
       [
         "sh",
         "-c",
-        "chmod 0700 /run/windy-tool-sandbox && chown 1000:1000 /run/windy-tool-sandbox",
+        "chown 0:0 /run/windy-tool-sandbox && chmod 0700 /run/windy-tool-sandbox && chown 1000:1000 /run/windy-tool-sandbox",
       ]
     network_mode: none
     read_only: true
@@ -230,44 +230,6 @@ 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: .

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

@@ -654,13 +654,22 @@ type DictationEvent =
 
 ## Prompt、Debug 与 Trace
 
-ADK Web 只在 developer profile 启动，绑定 localhost 或受控开发网络。它不是生产 Prompt 管理或生产 Debug 控制面。
+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 的调试会话解释为生产授权或业务执行证据。
+`127.0.0.1:8000`。Windy 的 `canonical_debug` 是确定性 Adapter：它把用户文本交给
+project-owned 配置选择的真实文本 Operation，并通过 canonical HTTP/SSE 读取 Run、
+Tool 和终态摘要。业务 Permission、Scope、Execution Grant、Provider 与 Tool Host
+继续由正式 Server/Agent Server 管理，ADK Web 不获得 Repository、Provider Key 或内部
+Token。项目配置只包含 Operation Key 与当前启用的真实开发数据用户 ID，不能重复或扩大
+Manifest 的权限、Scope 与 Tool 列表。数据用户用于复用其成员关系和当前 Scope。开发 Wrapper
+创建的核心主体仍是 `service_adk_debug`，权限只取该用户已有权限与 Operation/allowed
+Tools 闭包的精确交集，并且只能调用 canonical Run API；审计不会把它记录成普通用户会话。
+
+该 Adapter 证明真实业务执行链，不等于把另一进程内的完整 ADK Agent/Workflow 图装入
+原生 ADK Web。内部节点、Prompt 版本和 replay 若要可视化，必须通过另一个版本化协议
+显式暴露。不得把开发调试会话解释为生产授权或业务执行证据。
 
 Prompt 和 Workflow 使用：
 

package/template/docs/architecture/module-manifest-composition.md

@@ -28,6 +28,20 @@ Manifest 当前覆盖：
 
 同一个稳定能力基础 Key 仍可分别出现在 Feature、Permission 前缀、菜单和页面入口中；“重复”按能力类别判断，避免破坏项目既定 Key 语义。
 
+## 功能注册门禁
+
+所有面向用户、业务或系统开放的能力必须有 Manifest 功能注册；这是一项可执行门禁，
+不是只靠文档约定的建议。每个能力注册一个 Feature 基础 Key，并声明所需动作；Feature
+用于功能目录、开关与 License，动作派生或声明同一基础 Key 下的 RBAC Permission。
+例如 `personnel.profile` 对应 `personnel.profile.read`、`personnel.profile.create`、
+`personnel.profile.update` 与 `personnel.profile.delete`。
+
+菜单、Admin 路由、按钮、Server API、Agent Tool、后台任务、Provider、审计动作和
+License 配置必须引用同一 Manifest 中已注册的 Feature/Permission。未知引用、重复 Key、
+缺少 Feature、缺少动作权限或未声明实现均在三处以同一规则 fail closed：模块安装前、
+项目构建时和服务监听前。这样权限目录与 License/Feature 目录不会依赖第二份手写 Key
+列表，也不会出现只注册页面或 API 的“幽灵功能”。
+
 ## 模块与 Adapter
 
 - `@southwind-ai/modules` 是深 Module：拥有声明类型、依赖排序、引用规则和组合验证，不依赖 Elysia 或 Vue。

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

@@ -74,19 +74,5 @@ const developmentAuth = developmentAuthStatus();
 布局和内容，但不应绕过 Router 的 `guestOnly` Guard、首次改密跳转或平台认证
 composable。
 
-## 从 0.2.32 升级
-
-可直接在现有业务改动上执行：更新不会检查无关工作区改动；若平台变更与同一共享文件
-重叠，计划会报告三方合并冲突：
-
-```bash
-bunx --bun create-windy@latest update --check --cwd .
-bunx --bun create-windy@latest update --dry-run --cwd .
-bunx --bun create-windy@latest update --cwd .
-bun install
-```
-
-计划中应看到 selector 以 `project-owned` 新增，Router 通过三方合并接入 selector。
-若旧业务登录页曾放在 `apps/web/src/pages/auth/LoginPage.vue` 或直接改 Router，应将
-业务 SFC 移到 `apps/web/src/app/auth/`，改 selector 指向它，再恢复受管文件。后续升级
-会保留 selector 和业务 SFC。
+该 selector 与业务 SFC 属于 project-owned seam。后续 Starter 更新必须保留它们，
+Router 只通过稳定 selector 组合，不把业务登录页重新纳入受管文件。

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

@@ -124,6 +124,8 @@ Manifest 的 Operation limits 同时包含输入、执行时间和输出上限
 ```dotenv
 PLATFORM_ENABLE_AI=true
 AGENT_SERVER_INTERNAL_TOKEN=<至少 32 字符的随机值>
+ADK_DEBUG_PLATFORM_TOKEN=<create-windy 自动生成的独立随机值>
+AGENT_RUN_ENCRYPTION_SECRET=<至少 32 字符的独立随机值>
 AI_ARTIFACT_ENCRYPTION_SECRET=<至少 32 字符的随机值>
 QWEN_API_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
 QWEN_API_KEY=<服务端密钥>
@@ -145,9 +147,13 @@ AI_PROVIDER_AUDIT_RETENTION_DAYS=90
 bun run dev:agent
 ```
 
-`create-windy` 会为新的本地项目同时生成内部 Token 与 Artifact 加密 Secret。已有项目
-升级后必须补齐 `AI_ARTIFACT_ENCRYPTION_SECRET`；它只用于平台签发短时 opaque
-ArtifactRef，不得复用 Provider Key。Vision Deployment 需把能力与输入模态显式扩展为
+`create-windy` 会为新的本地项目分别生成内部 Token、ADK 调试 Token、Run Store 加密
+Secret 与 Artifact 加密 Secret，四者不得互相复用。已有项目升级时 updater 只会为
+普通 `.env` 原子补齐缺失或空的受管 Secret，不覆盖任何非空值；符号链接、重复定义或
+缺失的 `.env` 会停止自动修复并由 `windy doctor` 报告，避免覆盖外部 Secret Store 或
+已有部署配置。
+`AI_ARTIFACT_ENCRYPTION_SECRET` 只用于平台签发短时 opaque ArtifactRef，不得复用
+Provider Key。Vision Deployment 需把能力与输入模态显式扩展为
 `text-generation,vision` 和 `text,image`，详见
 [Vision AI Runtime](./vision-ai-runtime.md)。Document profile 的配置与调用链见
 [Document AI Runtime](./document-ai-runtime.md)。
@@ -187,25 +193,62 @@ Agent profile 还必须挂载 `AI_PROVIDER_AUDIT_STORE_PATH`。create-windy Star
 
 ## Developer-only ADK Web
 
-ADK Web 使用独立 profile 启动：
+ADK Web 使用独立 profile 调试真实 canonical Run。项目先在 project-owned 的
+`apps/agent-server/project/adk-web-debug.json` 选择一个文本 Operation：
+
+```json
+{
+  "schemaVersion": 1,
+  "textOperation": {
+    "key": "your-module.copilot.global",
+    "dataActorId": "user_dev_admin"
+  }
+}
+```
+
+该 v1 接缝只承诺 `{ "question": string } -> { "text": string }`。Operation、Permission、
+Feature、Tool、Scope、Provider Policy 和输入输出 Schema 仍由业务 Module Manifest
+声明；`dataActorId` 必须是项目当前存在且启用的开发用户，用于复用真实案件成员关系与
+当前 Scope。Windy 不接受第二份权限、Scope 或 Tool 列表。用户不存在、权限闭包不足、
+Operation 未知或不符合文本契约时明确拒绝，不回退成伪造回答。
+
+一条命令会同时启动 Server、Tool Sandbox、Agent Server 与 ADK Web：
 
 ```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 补造或绕过这条授权链。
+但端口只发布到宿主机 `127.0.0.1`。启动脚本读取 project-owned JSON，将唯一
+Operation Key 与真实开发数据用户注入 Windy-owned `docker-compose.agent-debug.yml`；
+普通 `dev`、`agent` profile 和生产 Compose 均不包含该服务或调试身份。
+
+选择 `canonical_debug` 应用后，每条问题由确定性 dispatcher 交给正式
+`POST /api/agent/runs`，再读取 SSE 与最终结果：
+
+- `create-windy` 自动生成独立随机 `ADK_DEBUG_PLATFORM_TOKEN`，无需复制登录 Token；
+- Server 只在 `NODE_ENV=development` 且加载调试 Compose Wrapper 时创建专用
+  `service_adk_debug` 身份；该 Token 只在 canonical Run 路径生效，不能访问 Foundation、
+  Admin 或其它 Server API；即使与普通会话 Token 误碰撞也被视为保留调试凭据，不会
+  回退普通认证；
+- Server 每次从用户目录解析 `dataActorId`，复用该用户当前 Scope 和业务成员 ID；只在
+  用户本身拥有完整权限闭包时，向 Module 投影该真实用户。核心 Run、Token 和审计主体仍
+  是 `service_adk_debug`，不会冒充普通用户会话；
+- 专用身份的权限精确收窄到所选 Operation Permission 与其 `allowedToolKeys` 的
+  Permission 闭包，并在 Tool Host 重新解析用户和复核 Scope；不能切换到其它 Operation；
+- ADK Web 容器不读取 `QWEN_*`、Provider Secret、`AGENT_SERVER_INTERNAL_TOKEN`，
+  不连接业务 Repository 或 Tool Host；
+- 正式 Server 仍签发 Actor、Scope 和短时 Execution Grant，Agent Server 仍按
+  `allowedToolKeys` 执行并审计；
+- SSE 先于结果持久化结束时，Adapter 最多再等待 60 秒并每 500ms 读取同一个 Run
+  的结果；只重试明确标记为可重试的 `RUN_CONFLICT`，不会重新创建 Run；
+- 事件摘要最多 64 条，单个 SSE frame 最大 64 KiB；流式 `output.delta` 只显示计数，
+  客户端边读边压缩，不先把完整事件流保存在内存。
+
+`safe_debug` 仍保留为不接业务的纯 ADK UI smoke。`canonical_debug` 能验证真实数据、
+模型与 Tool 链，但 ADK Web 显示的是“dispatcher → canonical Run”，不是另一进程内部
+完整的 Prompt/Agent/Workflow 节点图。完整 workflow replay 需要另行定义版本化调试
+协议，不能从当前事件摘要推断。
 
 ## 客户端协议
 

package/template/docs/platform/agent-tool-sandbox.md

@@ -41,9 +41,10 @@ Worker 重启会轮换密钥。Client 在连接中断或密钥轮换竞态时用
 读取宿主路径或依赖导入时初始化的外部连接。
 
 命名 Volume 初始由 root 持有。一次性的 `tool-sandbox-init` 仅挂载该 IPC Volume，
-使用 `CHOWN` capability 将目录交给镜像内固定的 `bun` 用户后退出；它同样无网络、
-无 Secret、只读 RootFS。常驻 Worker 与 Server 随后以相同非 root UID 访问权限为
-`0700` 的目录，HMAC 密钥文件权限为 `0600`。
+使用 `CHOWN` capability 先临时取回目录所有权，收紧为 `0700`，再交给镜像内固定的
+`bun` 用户后退出；这个顺序对首次创建和已由 `bun` 持有的残留 Volume 都是幂等的，
+无需扩大为 `FOWNER` capability。它同样无网络、无 Secret、只读 RootFS。常驻 Worker
+与 Server 随后以相同非 root UID 访问该目录，HMAC 密钥文件权限为 `0600`。
 
 ## 失败与审计
 

package/template/docs/platform/platform-authentication.md

@@ -97,7 +97,15 @@ Server 会幂等创建默认开发管理员和 `developer` 角色；仅当默认
 - `WINDY_DB_USER_TOKEN_PREFIX` 只能修改开发直通前缀。
 - `NODE_ENV=production` 时，上述 Token 与 `user:` 直通无条件关闭，即使环境变量误配置也不会生效。
 
-Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV_AUTH_BYPASS=1` 和非空 `VITE_DEV_ADMIN_TOKEN` 时，前端才会携带显式 Bearer Token，并在登录页和应用壳持续显示警告；生产构建无条件忽略这两个变量。完成一次真实密码登录后，当前页面生命周期内会停用开发 Token，后续请求只使用 Cookie。Docker Compose 不再注入默认 `dev-admin-token`。
+Web 不提供默认开发 Token。只有 Vite 开发模式同时设置 `VITE_DEV_AUTH_BYPASS=1` 和非空 `VITE_DEV_ADMIN_TOKEN` 时，前端才会携带显式 Bearer Token，并在登录页和应用壳持续显示警告；生产构建无条件忽略这两个变量。完成一次真实密码登录后，当前页面生命周期内会停用开发 Token，后续请求只使用 Cookie。
+
+选择 Agent 模块的新项目会在本机 `.env` 自动生成独立随机
+`ADK_DEBUG_PLATFORM_TOKEN`。只有 `bun run dev:adk-web` 加载的开发 Compose Wrapper
+会把它作为 `WINDY_ADK_DEBUG_TOKEN` 注入 Server，并注入 localhost-only ADK Web；它
+不会复用 `WINDY_DEV_ADMIN_TOKEN`，也不会启用固定 `dev-admin-token` 或 `user:` 直通。
+Server 仅在 canonical Agent Run 路径把它解析成 `service_adk_debug`，权限收敛为项目
+选择的 Operation 与 allowed Tools 权限闭包。该 Token 不进入 Web、Agent Server、
+Provider 或生产 Compose；非 development Server 即使误配也会拒绝。
 
 未配置 `DATABASE_URL` 时不会注册真实登录 API；只允许显式的非生产开发直通，不存在内存生产账号或默认生产密码。
 

package/template/package.json

@@ -19,7 +19,7 @@
     "dev:document": "PLATFORM_ENABLE_AI=true DOCUMENT_SERVER_URL=http://document-server:8090 docker compose --profile agent --profile document up --build",
     "dev:speech": "PLATFORM_ENABLE_AI=true SPEECH_SERVER_URL=http://speech-server:8091 docker compose --profile agent --profile speech up --build",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
-    "dev:adk-web": "docker compose --profile agent-debug up --build adk-web-debug",
+    "dev:adk-web": "bun run scripts/dev-adk-web.ts",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
     "dev:license": "bun run --cwd apps/license dev",
     "dev:license:docker": "docker compose --profile license up license",