@actiondock/core 2.0.9 → 2.0.11-beta.0

package/src/server/server.ts

@@ -1,27 +1,20 @@
-import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { runDoctorChecks } from "../doctor/doctor";
-import { filterByIntent, filterWithFallbackInfo } from "../filter";
-import {
-  findProjectRoot,
-  loadActions,
-  loadPlaybooks,
-  loadProjectConfig,
-} from "../project/loader";
-import {
-  getRegistryStatus,
-  listLinkedPackages,
-  resolveActionProject,
-  resolvePackageRoot,
-  resolvePlaybookProject,
-} from "../registry/registry";
-import { ActionRunner } from "../runtime/runner";
-import type { RuntimeStorage } from "../storage/types";
 import { createServer as createNodeHttpServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { resolve } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { InvalidJsonError, readJsonBody, RequestTooLargeError } from "./body";
+import { findProjectRoot } from "../project/loader";
+import {
+  handleActionsRoutes,
+  handleConfigRoutes,
+  handleDoctorRoute,
+  handleHealthRoute,
+  handleInfoRoute,
+  handlePlaybooksRoutes,
+  handleRunsRoutes,
+  handleStateRoutes,
+  jsonResponse,
+  type RouteContext,
+} from "./routes";
 import { ServerRuntimeRegistry } from "./runtime-registry";
 import { isLoopbackHost, resolveCorsHeaders, verifyBearerToken } from "./security";
 import type { ActionDockServerInstance, CoreHttpServerFactory, CoreHttpServerInstance, ServerOptions } from "./types";
@@ -121,137 +114,9 @@ export function launchHttpServer(
 }
 
 /**
- * 辅助函数：快速构造带 CORS 头的 JSON HTTP 响应。
- */
-function jsonResponse(
-  data: unknown,
-  status = 200,
-  corsHeaders: Record<string, string> = {}
-): Response {
-  return new Response(JSON.stringify(data, null, 2), {
-    status,
-    headers: {
-      "Content-Type": "application/json",
-      ...corsHeaders,
-    },
-  });
-}
-
-/**
- * 跨内存活跃连接与所有已知持久化存储全局检索指定 runId 的运行记录。
- */
-function findRunAcrossStorages(
-  runId: string,
-  runtimeRegistry: ServerRuntimeRegistry,
-  projectRoot?: string | null,
-  customHome?: string
-) {
-  const inMemory = runtimeRegistry.findRun(runId);
-  if (inMemory) return inMemory;
-
-  if (projectRoot) {
-    try {
-      const config = loadProjectConfig(projectRoot);
-      const storage = runtimeRegistry.getStorage(config.id, projectRoot);
-      const run = storage.getRun(runId);
-      if (run) return { storage, run };
-    } catch {
-      // 忽略读取错误
-    }
-  }
-
-  try {
-    const linked = listLinkedPackages(customHome);
-    for (const pkg of linked) {
-      if (!existsSync(pkg.path)) continue;
-      const storage = runtimeRegistry.getStorage(pkg.id, pkg.path);
-      const run = storage.getRun(runId);
-      if (run) return { storage, run };
-    }
-  } catch {
-    // 忽略读取错误
-  }
-
-  return null;
-}
-
-/**
- * 辅助函数：依据 package 参数或项目上下文解析目标 Storage 实例与根目录。
- */
-function resolveStorageForPackage(
-  packageIdOrPath: string | undefined,
-  runtimeRegistry: ServerRuntimeRegistry,
-  projectRoot?: string | null,
-  customHome?: string
-): { packageId: string; storage: RuntimeStorage; projectRoot?: string } {
-  if (packageIdOrPath) {
-    const root = resolvePackageRoot(packageIdOrPath, customHome);
-    if (root) {
-      const config = loadProjectConfig(root);
-      return {
-        packageId: config.id,
-        storage: runtimeRegistry.getStorage(config.id, root),
-        projectRoot: root,
-      };
-    }
-    return {
-      packageId: packageIdOrPath,
-      storage: runtimeRegistry.getStorage(packageIdOrPath),
-    };
-  }
-
-  if (projectRoot) {
-    const config = loadProjectConfig(projectRoot);
-    return {
-      packageId: config.id,
-      storage: runtimeRegistry.getStorage(config.id, projectRoot),
-      projectRoot,
-    };
-  }
-
-  const linked = listLinkedPackages(customHome);
-  if (linked.length > 0) {
-    const first = linked[0];
-    return {
-      packageId: first.id,
-      storage: runtimeRegistry.getStorage(first.id, first.path),
-      projectRoot: first.path,
-    };
-  }
-
-  return {
-    packageId: "default",
-    storage: runtimeRegistry.getStorage("default"),
-  };
-}
-
-/**
- * 启动 ActionDock 2.0 原生轻量级 HTTP Runner 服务端。
+ * 启动 ActionDock 2.0 原生轻量级 HTTP 服务装配中枢。
  * 
- * 全面暴露 RESTful 调度与运维接口：
- * - GET  /api/v1/health             : 健康检查与就绪状态
- * - GET  /api/v1/info               : 统一自省探索（支持 ?intent= 智能决议、?package= 详情下钻、?tree=true 工作区拓扑）
- * - GET  /api/v1/doctor             : 深度环境与依赖诊断
- * - GET  /api/v1/actions            : 列出可用 Actions（支持 ?intent= 与 ?package=）
- * - GET  /api/v1/actions/:id        : 查看单个 Action 的 Schema 详情
- * - POST /api/v1/actions/:id/run    : 同步或异步执行 Action
- * - GET  /api/v1/playbooks          : 列出可用 Playbook 工作流
- * - GET  /api/v1/playbooks/:id      : 查看 Playbook 步骤流程与 SOP 规程正文
- * - GET  /api/v1/runs               : 多维检索历史运行记录
- * - POST /api/v1/runs/clear         : 批量清理历史运行记录
- * - GET  /api/v1/runs/:runId        : 查询历史或异步任务运行状态
- * - POST /api/v1/runs/:runId/cancel : 中断在途任务
- * - GET  /api/v1/runs/:runId/stream : 基于 SSE 实时长任务日志与进度流推送
- * - GET  /api/v1/state              : 检索状态键名列表
- * - GET  /api/v1/state/:key         : 获取指定状态值
- * - PUT  /api/v1/state/:key         : 写入持久化状态（支持 TTL）
- * - DELETE /api/v1/state/:key      : 删除指定状态
- * - POST /api/v1/state/clear        : 清空状态数据
- * - GET  /api/v1/config             : 获取配置项规格与当前值（敏感凭证脱敏）
- * - PUT  /api/v1/config             : 持久化更新配置
- * - DELETE /api/v1/config/:key      : 删除配置项
- * - GET  /api/v1/config/env         : 检查环境变量满足率
- * - ALL  /mcp                       : 一体化 MCP Streamable HTTP 协议端点（可选）
+ * 仅负责中间件流转、认证拦截、路由分发与服务生命周期管理。
  */
 export function startActionDockServer(
   options: ServerOptions = {}
@@ -275,69 +140,41 @@ export function startActionDockServer(
 
   const server = launchHttpServer(port, host, async (req) => {
     const origin = req.headers.get("origin");
-      const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
+    const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
 
-      if (req.method === "OPTIONS") {
-        return new Response(null, {
-          status: 204,
-          headers: corsHeaders,
-        });
-      }
+    if (req.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: corsHeaders,
+      });
+    }
 
-      const url = new URL(req.url);
-      const pathname = url.pathname;
+    const url = new URL(req.url);
+    const pathname = url.pathname;
 
-      // 0. Health Check (supports /api/v1/health and /health)
-      if (pathname === "/api/v1/health" || pathname === "/health") {
-        if (!verifyBearerToken(req, token)) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: {
-                code: "UNAUTHORIZED",
-                message: "Invalid or missing Bearer token",
-              },
-            },
-            401,
-            corsHeaders
-          );
-        }
-        const healthData: Record<string, unknown> = {
-          status: "ok",
-          version: "2.0.0",
-          timestamp: new Date().toISOString(),
-          uptime: process.uptime(),
-        };
-        if (options.exposeDebugInfo && projectRoot) {
-          healthData.projectRoot = projectRoot;
-        }
-        return jsonResponse(healthData, 200, corsHeaders);
-      }
+    const ctx: RouteContext = {
+      req,
+      url,
+      pathname,
+      corsHeaders,
+      projectRoot,
+      customHome,
+      runtimeRegistry,
+      options,
+    };
 
-      // 1. MCP Unified Gateway: /mcp
-      if (
-        options.enableMcp !== false &&
-        options.mcpHandler &&
-        (pathname === "/mcp" || pathname.startsWith("/mcp/"))
-      ) {
-        if (!verifyBearerToken(req, token)) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: {
-                code: "UNAUTHORIZED",
-                message: "Invalid or missing Bearer token",
-              },
-            },
-            401,
-            corsHeaders
-          );
-        }
-        const mcpRes = await options.mcpHandler(req);
-        if (mcpRes) return mcpRes;
-      }
+    // 1. 健康检查路由（内部处理独立鉴权逻辑）
+    const healthResponse = await handleHealthRoute(ctx);
+    if (healthResponse) {
+      return healthResponse;
+    }
 
-      // 鉴权检查（后续所有 /api/v1/* 均要求鉴权）
+    // 2. MCP 统一网关端点
+    if (
+      options.enableMcp !== false &&
+      options.mcpHandler &&
+      (pathname === "/mcp" || pathname.startsWith("/mcp/"))
+    ) {
       if (!verifyBearerToken(req, token)) {
         return jsonResponse(
           {
@@ -351,1130 +188,52 @@ export function startActionDockServer(
           corsHeaders
         );
       }
+      const mcpRes = await options.mcpHandler(req);
+      if (mcpRes) return mcpRes;
+    }
 
-      // 2. Info 自省: GET /api/v1/info
-      if (pathname === "/api/v1/info" && req.method === "GET") {
-        try {
-          const isTree = url.searchParams.get("tree") === "true";
-          if (isTree) {
-            const status = getRegistryStatus(customHome);
-            return jsonResponse(
-              { ok: true, type: "tree", ...status },
-              200,
-              corsHeaders
-            );
-          }
-
-          const intent = url.searchParams.get("intent") || undefined;
-          const targetPkg = url.searchParams.get("package") || undefined;
-
-          // 收集所有候选包全量元数据
-          const aggregatedPackages: any[] = [];
-
-          if (projectRoot) {
-            try {
-              const config = loadProjectConfig(projectRoot);
-              const actions = await loadActions(projectRoot, config.actionsDir);
-              const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
-              aggregatedPackages.push({
-                id: config.id,
-                name: config.name,
-                version: config.version,
-                description: config.description || "",
-                path: projectRoot,
-                actionsCount: actions.size,
-                playbooksCount: playbooks.size,
-                actions: Array.from(actions.entries()).map(([id, a]) => ({
-                  id,
-                  description: a.description || "",
-                  inputSchema: a.inputSchema || null,
-                  outputSchema: a.outputSchema || null,
-                })),
-                playbooks: Array.from(playbooks.entries()).map(([id, p]) => ({
-                  id,
-                  description: p.description || "",
-                  actions: p.actions || [],
-                })),
-                configDeclared: config.config || {},
-              });
-            } catch {
-              // 忽略解析异常
-            }
-          } else {
-            const linked = listLinkedPackages(customHome);
-            for (const pkg of linked) {
-              if (!existsSync(pkg.path)) continue;
-              try {
-                const config = loadProjectConfig(pkg.path);
-                const actions = await loadActions(pkg.path, config.actionsDir);
-                const playbooks = loadPlaybooks(pkg.path, config.playbooksDir);
-                aggregatedPackages.push({
-                  id: config.id,
-                  name: config.name,
-                  version: config.version,
-                  description: config.description || "",
-                  path: pkg.path,
-                  actionsCount: actions.size,
-                  playbooksCount: playbooks.size,
-                  actions: Array.from(actions.entries()).map(([id, a]) => ({
-                    id,
-                    description: a.description || "",
-                    inputSchema: a.inputSchema || null,
-                    outputSchema: a.outputSchema || null,
-                  })),
-                  playbooks: Array.from(playbooks.entries()).map(([id, p]) => ({
-                    id,
-                    description: p.description || "",
-                    actions: p.actions || [],
-                  })),
-                  configDeclared: config.config || {},
-                });
-              } catch {
-                // 忽略故障包
-              }
-            }
-          }
-
-          // 显式指定 package 详情下钻
-          if (targetPkg) {
-            const matched = aggregatedPackages.find(
-              (p) => p.id === targetPkg || p.path === targetPkg
-            );
-            if (!matched) {
-              return jsonResponse(
-                {
-                  ok: false,
-                  error: {
-                    code: "PACKAGE_NOT_FOUND",
-                    message: `Package '${targetPkg}' not found on remote server`,
-                  },
-                },
-                404,
-                corsHeaders
-              );
-            }
-            return jsonResponse(
-              {
-                ok: true,
-                type: "package_detail",
-                ...matched,
-                ...(options.exposeDebugInfo ? { projectRoot: matched.path } : {}),
-              },
-              200,
-              corsHeaders
-            );
-          }
-
-          // 意图过滤与决议
-          if (intent) {
-            const filterRes = filterWithFallbackInfo(
-              aggregatedPackages,
-              intent,
-              [
-                (p) => p.id,
-                (p) => p.name,
-                (p) => p.description,
-                (p) => p.actions.map((a: any) => a.id),
-                (p) => p.actions.map((a: any) => a.description),
-                (p) => p.playbooks.map((pb: any) => pb.id),
-                (p) => p.playbooks.map((pb: any) => pb.description),
-              ],
-              true
-            );
-
-            // 唯一命中智能展开详情
-            if (filterRes.matchedCount === 1) {
-              const single = filterRes.items[0];
-              return jsonResponse(
-                {
-                  ok: true,
-                  type: "package_detail",
-                  isSingleMatch: true,
-                  ...single,
-                  ...(options.exposeDebugInfo ? { projectRoot: single.path } : {}),
-                },
-                200,
-                corsHeaders
-              );
-            }
-
-            return jsonResponse(
-              {
-                ok: true,
-                type: "package_list",
-                isFallback: filterRes.isFallback,
-                packages: filterRes.items,
-              },
-              200,
-              corsHeaders
-            );
-          }
-
-          // 单包模式直接展开详情
-          if (projectRoot && aggregatedPackages.length === 1) {
-            const p = aggregatedPackages[0];
-            return jsonResponse(
-              {
-                ok: true,
-                type: "package_detail",
-                id: p.id,
-                name: p.name,
-                version: p.version,
-                description: p.description,
-                actionsCount: p.actionsCount,
-                playbooksCount: p.playbooksCount,
-                actions: p.actions.map((a: any) => a.id),
-                actionsDetail: p.actions,
-                playbooks: p.playbooks.map((pb: any) => pb.id),
-                playbooksDetail: p.playbooks,
-                configDeclared: p.configDeclared,
-                linkedPackages: listLinkedPackages(customHome),
-                ...(options.exposeDebugInfo ? { projectRoot } : {}),
-              },
-              200,
-              corsHeaders
-            );
-          }
-
-          // 全局注册表概览
-          return jsonResponse(
-            {
-              ok: true,
-              type: "package_list",
-              version: "2.0.0",
-              packages: aggregatedPackages,
-              linkedPackages: listLinkedPackages(customHome),
-            },
-            200,
-            corsHeaders
-          );
-        } catch (err: any) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: { code: "INFO_ERROR", message: err.message },
-            },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 3. Doctor 深度体检: GET /api/v1/doctor
-      if (pathname === "/api/v1/doctor" && req.method === "GET") {
-        try {
-          const targetPkg = url.searchParams.get("package") || undefined;
-          const report = await runDoctorChecks({
-            cwd: projectRoot || process.cwd(),
-            packageIdOrPath: targetPkg,
-            customHome,
-          });
-          return jsonResponse({ ok: true, report }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "DOCTOR_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 4. Actions List: GET /api/v1/actions
-      if (pathname === "/api/v1/actions" && req.method === "GET") {
-        try {
-          const actionList: Array<{
-            id: string;
-            description: string;
-            packageId?: string;
-          }> = [];
-
-          if (projectRoot) {
-            const config = loadProjectConfig(projectRoot);
-            const actions = await loadActions(projectRoot, config.actionsDir);
-            for (const [id, a] of actions.entries()) {
-              actionList.push({
-                id,
-                description: a.description || "",
-                packageId: config.id,
-              });
-            }
-          }
-
-          const linked = listLinkedPackages(customHome);
-          for (const pkg of linked) {
-            if (projectRoot && pkg.path === projectRoot) continue;
-            if (!existsSync(pkg.path)) continue;
-            try {
-              const config = loadProjectConfig(pkg.path);
-              const actions = await loadActions(pkg.path, config.actionsDir);
-              for (const [id, a] of actions.entries()) {
-                actionList.push({
-                  id,
-                  description: a.description || "",
-                  packageId: pkg.id,
-                });
-              }
-            } catch {
-              // Ignore broken package
-            }
-          }
-
-          const intent = url.searchParams.get("intent");
-          const targetPkg = url.searchParams.get("package");
-
-          let filtered = targetPkg
-            ? actionList.filter((a) => a.packageId === targetPkg)
-            : actionList;
-
-          if (intent) {
-            filtered = filterByIntent(
-              filtered,
-              intent,
-              [(a) => a.id, (a) => a.description, (a) => a.packageId],
-              false
-            );
-          }
-
-          return jsonResponse(filtered, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: { code: "ACTIONS_LIST_ERROR", message: err.message },
-            },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 5. Action Show: GET /api/v1/actions/:id
-      const actionShowMatch = pathname.match(/^\/api\/v1\/actions\/([^/]+)$/);
-      if (actionShowMatch && req.method === "GET") {
-        const actionId = decodeURIComponent(actionShowMatch[1]);
-        try {
-          const resolved = await resolveActionProject(
-            actionId,
-            projectRoot || process.cwd(),
-            customHome
-          );
-          const config = loadProjectConfig(resolved.projectRoot);
-          const actions = await loadActions(resolved.projectRoot, config.actionsDir);
-          const action = actions.get(resolved.actionId);
-          if (!action) {
-            return jsonResponse(
-              {
-                ok: false,
-                error: {
-                  code: "ACTION_NOT_FOUND",
-                  message: `Action '${resolved.actionId}' not found in package '${resolved.packageId}'`,
-                },
-              },
-              404,
-              corsHeaders
-            );
-          }
-
-          return jsonResponse(
-            {
-              id: action.id,
-              packageId: resolved.packageId,
-              description: action.description || "",
-              inputSchema: action.inputSchema || null,
-              outputSchema: action.outputSchema || null,
-            },
-            200,
-            corsHeaders
-          );
-        } catch (err: any) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: { code: "ACTION_NOT_FOUND", message: err.message },
-            },
-            404,
-            corsHeaders
-          );
-        }
-      }
-
-      // 6. Action Run: POST /api/v1/actions/:id/run
-      const actionRunMatch = pathname.match(/^\/api\/v1\/actions\/([^/]+)\/run$/);
-      if (actionRunMatch && req.method === "POST") {
-        const actionId = decodeURIComponent(actionRunMatch[1]);
-        let body: any = {};
-        try {
-          body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
-        } catch (err: any) {
-          if (err instanceof RequestTooLargeError) {
-            return jsonResponse(
-              {
-                ok: false,
-                runId: randomUUID(),
-                error: { code: "REQUEST_TOO_LARGE", message: err.message },
-              },
-              413,
-              corsHeaders
-            );
-          }
-          if (err instanceof InvalidJsonError) {
-            return jsonResponse(
-              {
-                ok: false,
-                runId: randomUUID(),
-                error: { code: "INVALID_JSON", message: err.message },
-              },
-              400,
-              corsHeaders
-            );
-          }
-          return jsonResponse(
-            {
-              ok: false,
-              runId: randomUUID(),
-              error: { code: "INVALID_JSON", message: `Failed to parse request body: ${err.message}` },
-            },
-            400,
-            corsHeaders
-          );
-        }
-
-        try {
-          const resolved = await resolveActionProject(
-            actionId,
-            projectRoot || process.cwd(),
-            customHome
-          );
-          const config = loadProjectConfig(resolved.projectRoot);
-          const actions = await loadActions(resolved.projectRoot, config.actionsDir);
-          const storage = runtimeRegistry.getStorage(config.id, resolved.projectRoot);
-
-          const runner = new ActionRunner({
-            packageId: config.id,
-            storage,
-            projectConfig: config,
-            configOverrides: body?.config || {},
-            actions,
-          });
-
-          const isAsync = body?.execution?.mode === "async" || body?.async === true;
-          const timeoutMs =
-            typeof body?.execution?.timeoutMs === "number" && body.execution.timeoutMs > 0
-              ? body.execution.timeoutMs
-              : undefined;
-
-          if (isAsync) {
-            const handle = runner.start(resolved.actionId, body?.input || {}, {
-              timeoutMs,
-            });
-            runtimeRegistry.executionManager.register(handle);
-
-            // 监听结算以广播 SSE 完成事件
-            handle.result
-              .then((res) => {
-                runtimeRegistry.emit(handle.runId, { type: "finish", data: res });
-              })
-              .catch((err) => {
-                runtimeRegistry.emit(handle.runId, {
-                  type: "finish",
-                  data: {
-                    ok: false,
-                    error: {
-                      code: "ACTION_EXECUTION_ERROR",
-                      message: err?.message || String(err),
-                    },
-                  },
-                });
-              });
-
-            return jsonResponse(
-              {
-                ok: true,
-                runId: handle.runId,
-                status: "running",
-                streamUrl: `/api/v1/runs/${handle.runId}/stream`,
-              },
-              202,
-              corsHeaders
-            );
-          }
-
-          // 同步执行模式
-          const handle = runner.start(resolved.actionId, body?.input || {}, {
-            signal: req.signal,
-            timeoutMs,
-          });
-          runtimeRegistry.executionManager.register(handle);
-          const result = await handle.result;
-
-          return jsonResponse(result, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            {
-              ok: false,
-              runId: randomUUID(),
-              error: {
-                code: "ACTION_EXECUTION_ERROR",
-                message: err.message || String(err),
-              },
-            },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 7. Playbooks List: GET /api/v1/playbooks
-      if (pathname === "/api/v1/playbooks" && req.method === "GET") {
-        try {
-          const pbList: Array<{
-            id: string;
-            description: string;
-            actions: string[];
-            packageId: string;
-            filePath: string;
-          }> = [];
-
-          const targetPkg = url.searchParams.get("package");
-          const intent = url.searchParams.get("intent");
-
-          const roots: Array<{ root: string; packageId: string }> = [];
-          if (projectRoot) {
-            const cfg = loadProjectConfig(projectRoot);
-            roots.push({ root: projectRoot, packageId: cfg.id });
-          }
-          const linked = listLinkedPackages(customHome);
-          for (const pkg of linked) {
-            if (projectRoot && pkg.path === projectRoot) continue;
-            if (!existsSync(pkg.path)) continue;
-            roots.push({ root: pkg.path, packageId: pkg.id });
-          }
-
-          for (const item of roots) {
-            if (targetPkg && item.packageId !== targetPkg && item.root !== targetPkg) continue;
-            try {
-              const cfg = loadProjectConfig(item.root);
-              const pbs = loadPlaybooks(item.root, cfg.playbooksDir);
-              for (const [id, pb] of pbs.entries()) {
-                pbList.push({
-                  id,
-                  description: pb.description || "",
-                  actions: pb.actions || [],
-                  packageId: item.packageId,
-                  filePath: pb.filePath,
-                });
-              }
-            } catch {}
-          }
-
-          const filtered = intent
-            ? filterByIntent(
-                pbList,
-                intent,
-                [(p) => p.id, (p) => p.description, (p) => p.packageId, (p) => p.actions],
-                false
-              )
-            : pbList;
-
-          return jsonResponse(filtered, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "PLAYBOOKS_LIST_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 8. Playbook Show: GET /api/v1/playbooks/:id
-      const pbShowMatch = pathname.match(/^\/api\/v1\/playbooks\/([^/]+)$/);
-      if (pbShowMatch && req.method === "GET") {
-        const pbId = decodeURIComponent(pbShowMatch[1]);
-        try {
-          const resolved = resolvePlaybookProject(
-            pbId,
-            projectRoot || process.cwd(),
-            customHome
-          );
-          const pb = resolved.playbook;
-          return jsonResponse(
-            {
-              ok: true,
-              id: pb.id,
-              packageId: resolved.packageId,
-              description: pb.description || "",
-              actions: pb.actions || [],
-              filePath: pb.filePath,
-              content: pb.content,
-            },
-            200,
-            corsHeaders
-          );
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "PLAYBOOK_NOT_FOUND", message: err.message } },
-            404,
-            corsHeaders
-          );
-        }
-      }
-
-      // 9. Runs List: GET /api/v1/runs
-      if (pathname === "/api/v1/runs" && req.method === "GET") {
-        try {
-          const status = url.searchParams.get("status") || undefined;
-          const actionId = url.searchParams.get("actionId") || undefined;
-          const packageId = url.searchParams.get("packageId") || undefined;
-          const intent = url.searchParams.get("intent") || undefined;
-          const limit = parseInt(url.searchParams.get("limit") || "50", 10);
-
-          const allRuns: any[] = [];
-          const seenRunIds = new Set<string>();
-
-          const candidateStorages: Array<{ packageId: string; storage: RuntimeStorage }> = [];
-          if (projectRoot) {
-            try {
-              const cfg = loadProjectConfig(projectRoot);
-              candidateStorages.push({
-                packageId: cfg.id,
-                storage: runtimeRegistry.getStorage(cfg.id, projectRoot),
-              });
-            } catch {}
-          }
-          const linked = listLinkedPackages(customHome);
-          for (const pkg of linked) {
-            if (projectRoot && pkg.path === projectRoot) continue;
-            if (!existsSync(pkg.path)) continue;
-            candidateStorages.push({
-              packageId: pkg.id,
-              storage: runtimeRegistry.getStorage(pkg.id, pkg.path),
-            });
-          }
-
-          for (const item of candidateStorages) {
-            if (packageId && item.packageId !== packageId) continue;
-            try {
-              const records = item.storage.listRuns({ actionId, limit });
-              for (const r of records) {
-                if (!seenRunIds.has(r.id)) {
-                  seenRunIds.add(r.id);
-                  if (status && r.status !== status) continue;
-                  allRuns.push(r);
-                }
-              }
-            } catch {}
-          }
-
-          allRuns.sort((a, b) => (b.startedAt || "").localeCompare(a.startedAt || ""));
-
-          const filtered = intent
-            ? filterByIntent(
-                allRuns,
-                intent,
-                [(r) => r.id, (r) => r.actionId, (r) => r.status, (r) => r.packageId],
-                false
-              )
-            : allRuns;
-
-          const sliced = filtered.slice(0, limit);
-          return jsonResponse(
-            { ok: true, total: filtered.length, items: sliced },
-            200,
-            corsHeaders
-          );
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "RUNS_LIST_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 10. Runs Clear: POST /api/v1/runs/clear or DELETE /api/v1/runs
-      if (
-        (pathname === "/api/v1/runs/clear" && req.method === "POST") ||
-        (pathname === "/api/v1/runs" && req.method === "DELETE")
-      ) {
-        try {
-          let body: any = {};
-          if (req.method === "POST" || req.headers.get("content-type")?.includes("json")) {
-            body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
-          }
-          const packageId = url.searchParams.get("packageId") || body.packageId || undefined;
-          const actionId = url.searchParams.get("actionId") || body.actionId || undefined;
-          const status = url.searchParams.get("status") || body.status || undefined;
-
-          let clearedCount = 0;
-          const candidateStorages: RuntimeStorage[] = [];
-          if (projectRoot) {
-            try {
-              const cfg = loadProjectConfig(projectRoot);
-              candidateStorages.push(runtimeRegistry.getStorage(cfg.id, projectRoot));
-            } catch {}
-          }
-          const linked = listLinkedPackages(customHome);
-          for (const pkg of linked) {
-            if (projectRoot && pkg.path === projectRoot) continue;
-            if (!existsSync(pkg.path)) continue;
-            if (packageId && pkg.id !== packageId) continue;
-            candidateStorages.push(runtimeRegistry.getStorage(pkg.id, pkg.path));
-          }
-
-          for (const storage of candidateStorages) {
-            clearedCount += storage.clearRuns({ actionId, status });
-          }
-
-          return jsonResponse({ ok: true, clearedCount }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "RUNS_CLEAR_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 11. Run Stream (SSE): GET /api/v1/runs/:runId/stream
-      const runStreamMatch = pathname.match(/^\/api\/v1\/runs\/([^/]+)\/stream$/);
-      if (runStreamMatch && req.method === "GET") {
-        const runId = decodeURIComponent(runStreamMatch[1]);
-        const found = findRunAcrossStorages(runId, runtimeRegistry, projectRoot, customHome);
-        const activeHandle = runtimeRegistry.executionManager.get(runId);
-
-        if (!found && !activeHandle) {
-          return jsonResponse(
-            { ok: false, error: { code: "RUN_NOT_FOUND", message: `Run '${runId}' not found` } },
-            404,
-            corsHeaders
-          );
-        }
-
-        const stream = new ReadableStream({
-          start(controller) {
-            const encoder = new TextEncoder();
-            const sendEvent = (event: string, data: any) => {
-              try {
-                controller.enqueue(
-                  encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
-                );
-              } catch {}
-            };
-
-            if (activeHandle) {
-              sendEvent("status", { runId, status: "running" });
-              const unsubscribe = runtimeRegistry.subscribe(runId, (evt) => {
-                sendEvent(evt.type, evt.data);
-                if (evt.type === "finish") {
-                  try { controller.close(); } catch {}
-                }
-              });
-
-              activeHandle.result.then(
-                (res) => {
-                  sendEvent("finish", res);
-                  try { controller.close(); } catch {}
-                },
-                (err) => {
-                  sendEvent("finish", {
-                    ok: false,
-                    error: { message: err?.message || String(err) },
-                  });
-                  try { controller.close(); } catch {}
-                }
-              );
-
-              req.signal.addEventListener("abort", () => {
-                unsubscribe();
-                try { controller.close(); } catch {}
-              });
-            } else if (found) {
-              sendEvent("finish", found.run);
-              controller.close();
-            }
-          },
-        });
-
-        return new Response(stream, {
-          status: 200,
-          headers: {
-            "Content-Type": "text/event-stream",
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            ...corsHeaders,
-          },
-        });
-      }
-
-      // 12. Run Show: GET /api/v1/runs/:runId
-      const runShowMatch = pathname.match(/^\/api\/v1\/runs\/([^/]+)$/);
-      if (runShowMatch && req.method === "GET") {
-        const runId = decodeURIComponent(runShowMatch[1]);
-        const found = findRunAcrossStorages(runId, runtimeRegistry, projectRoot, customHome);
-
-        if (!found) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: {
-                code: "RUN_NOT_FOUND",
-                message: `Run '${runId}' not found`,
-              },
-            },
-            404,
-            corsHeaders
-          );
-        }
-
-        return jsonResponse(found.run, 200, corsHeaders);
-      }
-
-      // 13. Run Cancel: POST /api/v1/runs/:runId/cancel
-      const runCancelMatch = pathname.match(/^\/api\/v1\/runs\/([^/]+)\/cancel$/);
-      if (runCancelMatch && req.method === "POST") {
-        const runId = decodeURIComponent(runCancelMatch[1]);
-        let body: any = {};
-        try {
-          body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
-        } catch {
-          // Body is optional
-        }
-
-        const reason = body?.reason || "Cancelled by client request";
-
-        const activeHandle = runtimeRegistry.executionManager.get(runId);
-        if (activeHandle) {
-          const cancelled = runtimeRegistry.executionManager.cancel(runId, reason);
-          if (cancelled) {
-            return jsonResponse(
-              {
-                ok: true,
-                runId,
-                status: "cancelled",
-              },
-              200,
-              corsHeaders
-            );
-          }
-        }
-
-        const found = findRunAcrossStorages(runId, runtimeRegistry, projectRoot, customHome);
-        if (!found) {
-          return jsonResponse(
-            {
-              ok: false,
-              error: {
-                code: "RUN_NOT_FOUND",
-                message: `Run '${runId}' not found`,
-              },
-            },
-            404,
-            corsHeaders
-          );
-        }
-
-        const { storage, run } = found;
-        if (run.status === "success" || run.status === "failed" || run.status === "cancelled") {
-          return jsonResponse(
-            {
-              ok: false,
-              error: {
-                code: "RUN_ALREADY_FINISHED",
-                message: `Run '${runId}' has already finished with status '${run.status}'`,
-              },
-            },
-            409,
-            corsHeaders
-          );
-        }
-
-        storage.updateRun(runId, "cancelled", undefined, {
-          code: "ACTION_CANCELLED",
-          message: reason,
-        });
-
-        return jsonResponse(
-          {
-            ok: true,
-            runId,
-            status: "cancelled",
-          },
-          200,
-          corsHeaders
-        );
-      }
-
-      // 14. State List: GET /api/v1/state
-      if (pathname === "/api/v1/state" && req.method === "GET") {
-        try {
-          const pkgParam = url.searchParams.get("package") || undefined;
-          const nsParam = url.searchParams.get("namespace") ?? undefined;
-          const prefix = url.searchParams.get("prefix") || "";
-
-          const { packageId, storage } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          const keys = await storage.listStateKeys(nsParam !== undefined ? nsParam : null, prefix);
-          return jsonResponse({ ok: true, packageId, keys }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "STATE_LIST_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 15. State Clear: POST /api/v1/state/clear
-      if (pathname === "/api/v1/state/clear" && req.method === "POST") {
-        try {
-          const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes }).catch(() => ({}));
-          const pkgParam = url.searchParams.get("package") || body.package || undefined;
-          const { packageId, storage } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          const clearedCount = await storage.clearState({
-            namespace: body.namespace ?? (url.searchParams.get("namespace") || undefined),
-            all: Boolean(body.all ?? url.searchParams.get("all") === "true"),
-            prefix: body.prefix ?? (url.searchParams.get("prefix") || undefined),
-          });
-          return jsonResponse({ ok: true, packageId, clearedCount }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "STATE_CLEAR_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 16. State Key CRUD: GET / PUT / POST / DELETE /api/v1/state/:key
-      const stateKeyMatch = pathname.match(/^\/api\/v1\/state\/([^/]+)$/);
-      if (stateKeyMatch) {
-        const key = decodeURIComponent(stateKeyMatch[1]);
-        const pkgParam = url.searchParams.get("package") || undefined;
-        const nsParam = url.searchParams.get("namespace") || undefined;
-
-        const { packageId, storage } = resolveStorageForPackage(
-          pkgParam,
-          runtimeRegistry,
-          projectRoot,
-          customHome
-        );
-
-        if (req.method === "GET") {
-          const entry = await storage.findState(key, nsParam);
-          if (!entry || entry.value === undefined) {
-            return jsonResponse(
-              { ok: false, error: { code: "STATE_KEY_NOT_FOUND", message: `State key '${key}' not found` } },
-              404,
-              corsHeaders
-            );
-          }
-          return jsonResponse(
-            {
-              ok: true,
-              packageId,
-              key: entry.key,
-              namespace: entry.namespace,
-              value: entry.value,
-              expiresAt: entry.expiresAt,
-            },
-            200,
-            corsHeaders
-          );
-        }
-
-        if (req.method === "PUT" || req.method === "POST") {
-          const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
-          const val = body.value !== undefined ? body.value : body;
-          const ttl = typeof body.ttl === "number" ? body.ttl : undefined;
-          const namespace = body.namespace || nsParam || "";
-
-          let actualKey = key;
-          let ns = namespace;
-          if (!ns && key.includes(":")) {
-            const idx = key.indexOf(":");
-            ns = key.slice(0, idx);
-            actualKey = key.slice(idx + 1);
-          }
-
-          await storage.setState(ns, actualKey, val, ttl);
-          return jsonResponse(
-            { ok: true, packageId, key: actualKey, namespace: ns, message: "updated" },
-            200,
-            corsHeaders
-          );
-        }
-
-        if (req.method === "DELETE") {
-          const deleted = await storage.deleteStateSmart(key, nsParam);
-          if (!deleted) {
-            return jsonResponse(
-              { ok: false, error: { code: "STATE_KEY_NOT_FOUND", message: `State key '${key}' not found` } },
-              404,
-              corsHeaders
-            );
-          }
-          return jsonResponse({ ok: true, packageId, key, deleted: true }, 200, corsHeaders);
-        }
-      }
-
-      // 17. Config Env Check: GET /api/v1/config/env
-      if (pathname === "/api/v1/config/env" && req.method === "GET") {
-        try {
-          const pkgParam = url.searchParams.get("package") || undefined;
-          const { packageId, projectRoot: root } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          if (!root) {
-            return jsonResponse({ ok: true, packageId, envChecks: [] }, 200, corsHeaders);
-          }
-          const cfg = loadProjectConfig(root);
-          const declared = cfg.config || {};
-          const envChecks: any[] = [];
-          for (const [k, def] of Object.entries(declared)) {
-            const envKeys = [
-              k,
-              `ACTIONDOCK_${k}`,
-              `${packageId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${k}`,
-            ];
-            const foundEnv = envKeys.find((ek) => process.env[ek] !== undefined);
-            envChecks.push({
-              key: k,
-              required: def.default === undefined,
-              satisfied: Boolean(foundEnv || def.default !== undefined),
-              matchedEnv: foundEnv || null,
-              hasDefault: def.default !== undefined,
-              secret: Boolean(def.secret),
-            });
-          }
-          return jsonResponse({ ok: true, packageId, envChecks }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "CONFIG_ENV_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 18. Config Query: GET /api/v1/config
-      if (pathname === "/api/v1/config" && req.method === "GET") {
-        try {
-          const pkgParam = url.searchParams.get("package") || undefined;
-          const { packageId, storage, projectRoot: root } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          const stored = storage.listConfig();
-          let declared: Record<string, any> = {};
-          if (root) {
-            try {
-              const cfg = loadProjectConfig(root);
-              declared = cfg.config || {};
-            } catch {}
-          }
-          const maskedValues: Record<string, any> = {};
-          for (const [k, v] of Object.entries(stored)) {
-            if (declared[k]?.secret) {
-              maskedValues[k] = "******";
-            } else {
-              maskedValues[k] = v;
-            }
-          }
-          return jsonResponse(
-            { ok: true, packageId, declared, values: maskedValues },
-            200,
-            corsHeaders
-          );
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "CONFIG_LIST_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 19. Config Update: PUT / POST /api/v1/config
-      if (pathname === "/api/v1/config" && (req.method === "PUT" || req.method === "POST")) {
-        try {
-          const body = await readJsonBody(req, { maxBytes: options.maxBodyBytes });
-          const pkgParam = url.searchParams.get("package") || body.package || undefined;
-          const { packageId, storage } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          const key = body.key;
-          if (!key) {
-            return jsonResponse(
-              { ok: false, error: { code: "INVALID_ARGUMENT", message: "Config 'key' is required" } },
-              400,
-              corsHeaders
-            );
-          }
-          storage.setConfig(key, body.value);
-          return jsonResponse({ ok: true, packageId, key, message: "updated" }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "CONFIG_SET_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 20. Config Delete: DELETE /api/v1/config/:key
-      const configKeyMatch = pathname.match(/^\/api\/v1\/config\/([^/]+)$/);
-      if (configKeyMatch && req.method === "DELETE") {
-        try {
-          const key = decodeURIComponent(configKeyMatch[1]);
-          const pkgParam = url.searchParams.get("package") || undefined;
-          const { packageId, storage } = resolveStorageForPackage(
-            pkgParam,
-            runtimeRegistry,
-            projectRoot,
-            customHome
-          );
-          const deleted = storage.deleteConfig(key);
-          return jsonResponse({ ok: true, packageId, key, deleted }, 200, corsHeaders);
-        } catch (err: any) {
-          return jsonResponse(
-            { ok: false, error: { code: "CONFIG_DELETE_ERROR", message: err.message } },
-            500,
-            corsHeaders
-          );
-        }
-      }
-
-      // 404 Not Found
+    // 3. 全局 API 认证鉴权拦截
+    if (!verifyBearerToken(req, token)) {
       return jsonResponse(
         {
           ok: false,
           error: {
-            code: "NOT_FOUND",
-            message: `Route not found: ${req.method} ${pathname}`,
+            code: "UNAUTHORIZED",
+            message: "Invalid or missing Bearer token",
           },
         },
-        404,
+        401,
         corsHeaders
       );
     }
-  );
+
+    // 4. 业务领域路由分发
+    const routeResponse =
+      (await handleInfoRoute(ctx)) ||
+      (await handleDoctorRoute(ctx)) ||
+      (await handleActionsRoutes(ctx)) ||
+      (await handlePlaybooksRoutes(ctx)) ||
+      (await handleRunsRoutes(ctx)) ||
+      (await handleStateRoutes(ctx)) ||
+      (await handleConfigRoutes(ctx));
+
+    if (routeResponse) {
+      return routeResponse;
+    }
+
+    // 5. 404 路由兜底
+    return jsonResponse(
+      {
+        ok: false,
+        error: {
+          code: "NOT_FOUND",
+          message: `Route not found: ${req.method} ${pathname}`,
+        },
+      },
+      404,
+      corsHeaders
+    );
+  });
 
   const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
   const url = `http://${actualHost}:${server.port}`;