@actiondock/cli 2.8.0 → 2.9.1

package/README.md

@@ -108,6 +108,7 @@ ad pack
 
 - 严格目标定位：通过 `-P, --package <id|path>` 指定目标包。系统严格区分物理路径与注册表包标识符，若目标不存在则不向当前目录或父级目录隐式回退，直接以参数校验错误退出。
 - 多目标检索契约：在执行多目标检索（如 `ad info` 或 `ad list`）时，若无任何匹配项，在机器模式下始终返回确定性空数组结构并以状态码 0 退出，不因空搜索产生异常中断。
+- 服务端细粒度白名单：通过 `ad serve` 启动微服务时，支持通过 `-P, --package <package-id>` 与 `-A, --action <action-ref>` 分别指定包白名单与动作白名单（支持短名与全限定名，可多次指定或逗号分隔）。同时配置时取权限交集。未授权动作的详情调阅与执行均被阻断并返回 403 错误（错误码 `ACTION_FORBIDDEN`），历史运行记录与 MCP 协议工具暴露同步过滤。
 
 ### Action 执行入参契约
 
@@ -173,14 +174,14 @@ $data | ConvertTo-Json -Depth 100 | ad run complex-action --input-file -
 | `ad playbook list` / `show` | 查看智能体操作规程 Playbook |
 | `ad config list` / `get` / `set` | 管理包运行时配置与环境变量绑定 |
 | `ad state list` / `get` / `set` / `delete` / `clear` | 查看与维护 SQLite 持久化状态 |
-| `ad runs list` / `show` | 查询任务执行历史与追踪记录 |
+| `ad runs list` / `show` / `clear` | 查询任务执行历史与追踪记录，或按时间与数量策略清理历史数据 |
 | `ad test` | 执行快速单元测试 |
 | `ad build` | 构建 Node.js 目录交付产物（支持 `--vendor-deps` 与 `--archive`） |
 | `ad pack` | 打包为标准 npm tarball（`.tgz`），支持 `--dry-run` |
 | `ad export skill` | 导出 Agent Skill 技能包（支持 `--mode source` 与 `--mode node`） |
 | `ad link` / `unlink` | 注册或注销工作区全局路由与符号链接 |
 | `ad profile` | 管理远程执行节点凭证与环境配置 |
-| `ad serve` | 启动远程 HTTP/HTTPS 执行调度微服务（原生支持 `--https` 自签名与生产证书） |
+| `ad serve` | 启动远程 HTTP/HTTPS 执行调度微服务（支持 `-P` 包白名单与 `-A` 动作白名单细粒度权限控制，原生支持 `--https` 自签名与生产证书） |
 | `ad mcp` | 以 STDIO 或 HTTP 协议启动 MCP 服务 |
 
 ---

package/bin/ad.js

@@ -1,42 +1,71 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const distEntry = resolve(import.meta.dirname, "../dist/index.js");
+const isBun = typeof process.versions.bun !== "undefined";
+const hasTsx =
+  process.execArgv.some((arg, i) => arg === "--import" && process.execArgv[i + 1]?.includes("tsx")) ||
+  process.execArgv.some((arg) => arg.includes("tsx"));
 
-if (existsSync(distEntry)) {
-  const { runCliProcess } = await import(pathToFileURL(distEntry).href);
-  await runCliProcess(process.argv);
-} else {
-  const isBun = typeof process.versions.bun !== "undefined";
-  const hasTsx =
-    process.execArgv.some((arg, i) => arg === "--import" && process.execArgv[i + 1]?.includes("tsx")) ||
-    process.execArgv.some((arg) => arg.includes("tsx"));
-
-  if (!isBun && !hasTsx) {
-    const require = createRequire(import.meta.url);
-    let tsxSpecifier = null;
+if (!isBun && !hasTsx) {
+  const require = createRequire(import.meta.url);
+  let tsxSpecifier = null;
+  try {
+    tsxSpecifier = pathToFileURL(require.resolve("tsx", { paths: [import.meta.dirname, process.cwd()] })).href;
+  } catch {
     try {
       tsxSpecifier = pathToFileURL(require.resolve("tsx")).href;
     } catch {
       // 未检测到 tsx 模块
     }
+  }
+
+  if (tsxSpecifier) {
+    const child = spawn(
+      process.execPath,
+      ["--import", tsxSpecifier, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+      {
+        stdio: "inherit",
+      }
+    );
+
+    const forwardSignal = (sig) => {
+      if (child.pid && !child.killed) {
+        try {
+          child.kill(sig);
+        } catch {}
+      }
+    };
+
+    process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+    process.on("SIGINT", () => forwardSignal("SIGINT"));
+    process.on("SIGHUP", () => forwardSignal("SIGHUP"));
 
-    if (tsxSpecifier) {
-      const res = spawnSync(
-        process.execPath,
-        ["--import", tsxSpecifier, fileURLToPath(import.meta.url), ...process.argv.slice(2)],
-        {
-          stdio: "inherit",
+    await new Promise((resolvePromise) => {
+      child.on("exit", (code, signal) => {
+        if (signal) {
+          process.removeListener("SIGTERM", forwardSignal);
+          process.removeListener("SIGINT", forwardSignal);
+          process.removeListener("SIGHUP", forwardSignal);
+          process.kill(process.pid, signal);
+        } else {
+          process.exit(code ?? 0);
         }
-      );
-      process.exit(res.status ?? (res.signal ? 1 : 0));
-    }
+        resolvePromise();
+      });
+    });
   }
+}
+
+const distEntry = resolve(import.meta.dirname, "../dist/index.js");
 
+if (existsSync(distEntry)) {
+  const { runCliProcess } = await import(pathToFileURL(distEntry).href);
+  await runCliProcess(process.argv);
+} else {
   const { runCliProcess } = await import("../src/index.ts");
   await runCliProcess(process.argv);
 }

package/dist/commands/run.js

@@ -216,6 +216,36 @@ export async function executeAction(id, options, context, flatArgs, control) {
         throw err;
     }
 }
+const RUN_HELP_AFTER_TEXT = `
+Introspection & Guidance:
+  If uncertain about an action's inputs or schemas:
+    ad describe <id>               Inspect action schema, required fields, and assignment examples
+  If handling multi-step tasks or complex workflows:
+    ad playbook list               List available Standard Operating Procedures (SOPs)
+    ad playbook show <id>          View step-by-step procedure and execution rules
+
+Flat Input Syntax & Examples:
+  Standard invocation syntax:
+    ad run <id> [control-options] [-- <assignments...>]
+
+  Flat parameter assignments:
+    # String assignment (= keeps raw string, no type coercion)
+    ad run <id> -- key="value" path="src/index.ts"
+
+    # Typed / JSON assignment (:= parses numbers, booleans, arrays, objects)
+    ad run <id> -- count:=10 enabled:=true timeoutMs:=5000
+
+    # Sequential array indexing (zero-indexed, consecutive)
+    ad run <id> -- paths.0="src" paths.1="docs"
+    # Or direct JSON array
+    ad run <id> -- paths:='["src", "docs"]'
+
+    # Nested object properties
+    ad run <id> -- user.name="alice" user.age:=30
+
+  Complex or multiline inputs:
+    # Pass via JSON file with --input-file to avoid shell escaping issues
+    ad run <id> --input-file input.json`;
 /**
  * 挂载 run 子命令至指定 Commander 节点。
  *
@@ -236,6 +266,7 @@ export function attachRunCommand(parent, context) {
         .option("--async", "Execute asynchronously in background (requires remote server or profile)")
         .option("--data-dir <path>", "Custom database directory")
         .option("--json", "Output as JSON")
+        .addHelpText("after", RUN_HELP_AFTER_TEXT)
         .action(async (id, params, rawOptions, cmd) => {
         let flatArgs;
         let effectiveRawOptions = rawOptions;

package/dist/commands/runs.js

@@ -1,4 +1,4 @@
-import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { findProjectRoot, loadProjectConfig, parseDuration, } from "@actiondock/core";
 import { filterWithFallbackInfo, } from "@actiondock/core/project";
 import { listLinkedPackages, resolvePackageRoot, } from "@actiondock/core/registry";
 import { ArgumentError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, packageNotFoundError, } from "../errors.js";
@@ -177,7 +177,10 @@ export function registerRunsCommands(program, context) {
         .command("clear")
         .description("Clear execution run records")
         .option("-P, --package <id>", "Target package ID or path")
-        .option("-a, --action <actionId>", "Filter by action ID"))
+        .option("-a, --action <actionId>", "Filter by action ID")
+        .option("--status <status>", "Filter by run status (e.g. success, failed)")
+        .option("--older-than <duration>", "Only clear runs older than specified duration (e.g. 14d, 7d, 24h, 30m)")
+        .option("--keep <count>", "Keep the most recent N runs and clear older ones"))
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
         .action(async (rawOptions, cmd) => {
@@ -193,16 +196,49 @@ export function registerRunsCommands(program, context) {
                 // 清单损坏时保留原始 -P 参数作为包标识
             }
         }
+        let olderThanMs;
+        if (options.olderThan) {
+            try {
+                olderThanMs = parseDuration(options.olderThan);
+            }
+            catch (err) {
+                throw new ArgumentError(`Invalid --older-than argument: ${err.message}`);
+            }
+        }
+        let keep;
+        if (options.keep !== undefined) {
+            const parsed = parseInt(String(options.keep), 10);
+            if (isNaN(parsed) || parsed < 0) {
+                throw new ArgumentError("Invalid --keep argument: must be a non-negative integer");
+            }
+            keep = parsed;
+        }
         await withService(options, context, async (service, resolved) => {
             const count = service.runs.clear
-                ? await service.runs.clear({ packageId, actionId: options.action })
+                ? await service.runs.clear({
+                    packageId,
+                    actionId: options.action,
+                    status: options.status,
+                    olderThanMs,
+                    keep,
+                })
                 : 0;
+            const filters = [];
+            if (options.action)
+                filters.push(`action='${options.action}'`);
+            if (options.status)
+                filters.push(`status='${options.status}'`);
+            if (options.olderThan)
+                filters.push(`older than ${options.olderThan}`);
+            if (keep !== undefined)
+                filters.push(`keeping newest ${keep}`);
+            const filterDesc = filters.length > 0 ? ` (${filters.join(", ")})` : "";
             const payload = { ok: true, clearedCount: count };
             renderResult(payload, {
                 json: options.json,
                 humanFormatter: () => resolved.type === "remote"
-                    ? `Cleared ${count} execution run(s) on remote server.`
-                    : `Cleared ${count} execution run(s) in package '${packageId}'.`,
+                    ? `Cleared ${count} execution run(s) on remote server${filterDesc}.`
+                    : `Cleared ${count} execution run(s) in package '${packageId}'${filterDesc}.`,
                 context,
             });
         }, { localRoot: targetPackageRoot });

package/dist/commands/serve.js

@@ -2,10 +2,11 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createActionDock, createNodePlatform, findProjectRoot, loadProjectConfig, startActionDockServer, } from "@actiondock/core";
 import { resolvePackageRoot } from "@actiondock/core/registry";
+import { parseActionRef } from "@actiondock/core/graph";
 import { formatHostForUrl, } from "@actiondock/core/server";
 import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
 import { writeStderr, writeStdout } from "../renderer.js";
-import { ensureSelfSignedCertificate, getEffectiveOptions, normalizeCorsOrigins, registerStopSignalHandler, printServerBanner, resolveMaxBodyBytes, resolveServerHost, resolveServerPort, resolveServerToken, parseListOption, } from "../utils/index.js";
+import { ensureSelfSignedCertificate, getEffectiveOptions, loadViewsFromFile, mergeServerViews, normalizeCorsOrigins, registerStopSignalHandler, printServerBanner, resolveMaxBodyBytes, resolveServerHost, resolveServerPort, resolveServerToken, parseListOption, } from "../utils/index.js";
 /**
  * 注册 serve HTTP 服务启动命令。
  *
@@ -33,6 +34,9 @@ export function registerServeCommand(program, context) {
         .option("--tls-passphrase <passphrase>", "Passphrase for TLS private key (or set ACTIONDOCK_TLS_PASSPHRASE)")
         .option("-d, --dir <path>", "Project root directory (default: current working directory)")
         .option("-P, --package <package-id>", "Specific package ID(s) to serve (can be specified multiple times or comma-separated)", parseListOption, [])
+        .option("-A, --action <action-ref>", "Specific action ref(s) to serve (can be specified multiple times or comma-separated)", parseListOption, [])
+        .option("--views-file <path>", "Path to JSON file configuring virtual projection views")
+        .option("--views <json>", "JSON string configuring virtual projection views")
         .option("--data-dir <path>", "Custom database storage directory")
         .action(async (rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
@@ -87,10 +91,42 @@ export function registerServeCommand(program, context) {
         const projectRoot = options.dir
             ? resolve(options.dir)
             : findProjectRoot(process.cwd());
+        let projectConfig;
+        let projectName = "Global Registry Mode";
+        if (projectRoot) {
+            try {
+                projectConfig = loadProjectConfig(projectRoot);
+                projectName = `${projectConfig.name} (${projectConfig.id})`;
+            }
+            catch {
+                // 降级处理
+            }
+        }
+        const fileViews = options.viewsFile
+            ? loadViewsFromFile(options.viewsFile)
+            : undefined;
+        let cliViews;
+        if (options.views) {
+            try {
+                const parsed = typeof options.views === "string" ? JSON.parse(options.views) : options.views;
+                cliViews =
+                    parsed && typeof parsed === "object" && "views" in parsed && (typeof parsed.views === "object" || Array.isArray(parsed.views))
+                        ? parsed.views
+                        : parsed;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new ArgumentError(`Failed to parse --views option: ${msg}`);
+            }
+        }
+        const configViews = projectConfig?.server?.views;
+        const viewsConfig = mergeServerViews(mergeServerViews(configViews, fileViews), cliViews);
         const rawPackages = options.package || [];
         const packageAllowlist = rawPackages.length > 0 ? [] : undefined;
         const resolvedPackageIds = [];
         const explicitPackages = [];
+        const rawActions = options.action || [];
+        const actionAllowlist = rawActions.length > 0 ? [...rawActions] : undefined;
         if (rawPackages.length > 0) {
             for (const pkgId of rawPackages) {
                 const root = resolvePackageRoot(pkgId, projectRoot || undefined, context?.customHome);
@@ -123,14 +159,64 @@ export function registerServeCommand(program, context) {
                 }
             }
         }
-        let projectName = "Global Registry Mode";
-        if (projectRoot) {
-            try {
-                const config = loadProjectConfig(projectRoot);
-                projectName = `${config.name} (${config.id})`;
+        if (rawActions.length > 0) {
+            for (const actRef of rawActions) {
+                try {
+                    const parsed = parseActionRef(actRef);
+                    if (parsed.packageId) {
+                        const root = resolvePackageRoot(parsed.packageId, projectRoot || undefined, context?.customHome);
+                        if (root) {
+                            if (!projectRoot || root !== projectRoot) {
+                                if (!explicitPackages.some((p) => p.packageRoot === root)) {
+                                    explicitPackages.push({ packageRoot: root });
+                                }
+                            }
+                        }
+                        else {
+                            writeStderr(`Warning: Package '${parsed.packageId}' specified in action '${actRef}' was not found.`, context);
+                        }
+                    }
+                }
+                catch {
+                    // 忽略非标准或短引用形态
+                }
             }
-            catch {
-                // 降级处理
+        }
+        if (viewsConfig) {
+            const viewItems = Array.isArray(viewsConfig) ? viewsConfig : Object.values(viewsConfig);
+            for (const item of viewItems) {
+                if (!item || typeof item !== "object")
+                    continue;
+                if (Array.isArray(item.packageAllowlist)) {
+                    for (const pkgId of item.packageAllowlist) {
+                        if (typeof pkgId === "string") {
+                            const root = resolvePackageRoot(pkgId, projectRoot || undefined, context?.customHome);
+                            if (root && (!projectRoot || root !== projectRoot)) {
+                                if (!explicitPackages.some((p) => p.packageRoot === root)) {
+                                    explicitPackages.push({ packageRoot: root });
+                                }
+                            }
+                        }
+                    }
+                }
+                if (Array.isArray(item.actionAllowlist)) {
+                    for (const actRef of item.actionAllowlist) {
+                        if (typeof actRef === "string") {
+                            try {
+                                const parsed = parseActionRef(actRef);
+                                if (parsed.packageId) {
+                                    const root = resolvePackageRoot(parsed.packageId, projectRoot || undefined, context?.customHome);
+                                    if (root && (!projectRoot || root !== projectRoot)) {
+                                        if (!explicitPackages.some((p) => p.packageRoot === root)) {
+                                            explicitPackages.push({ packageRoot: root });
+                                        }
+                                    }
+                                }
+                            }
+                            catch { }
+                        }
+                    }
+                }
             }
         }
         const platform = createNodePlatform({
@@ -145,9 +231,9 @@ export function registerServeCommand(program, context) {
             customHome: context?.customHome,
             dataDir: options.dataDir || context?.dataDir,
             platform,
-            scanLinkedPackages: !projectRoot || rawPackages.length > 0,
+            scanLinkedPackages: !projectRoot || rawPackages.length > 0 || rawActions.length > 0 || Boolean(viewsConfig),
         });
-        let mcpHandler;
+        let mcpHandlerFactory;
         const enableMcp = options.mcp !== false;
         if (enableMcp) {
             // MCP 处理器创建失败时直接终止启动，避免横幅宣称不存在的端点
@@ -156,19 +242,22 @@ export function registerServeCommand(program, context) {
                     import("@actiondock/mcp"),
                     import("@modelcontextprotocol/server"),
                 ]);
-                const handler = createMcpHandler(() => {
-                    return createActionDockMcpServer({
-                        service,
-                        packageAllowlist,
-                        packageIds: packageAllowlist,
+                mcpHandlerFactory = (view) => {
+                    const handler = createMcpHandler(() => {
+                        return createActionDockMcpServer({
+                            service,
+                            packageAllowlist: view.packageAllowlist,
+                            packageIds: view.packageAllowlist,
+                            actionAllowlist: view.actionAllowlist,
+                        });
+                    }, {
+                        onerror: (err) => {
+                            writeStderr(`[MCP HTTP Error] ${err?.message || String(err)}`, context);
+                        },
                     });
-                }, {
-                    onerror: (err) => {
-                        writeStderr(`[MCP HTTP Error] ${err?.message || String(err)}`, context);
-                    },
-                });
-                mcpHandler = async (req) => {
-                    return handler.fetch(req);
+                    return async (req) => {
+                        return handler.fetch(req);
+                    };
                 };
             }
             catch (err) {
@@ -188,22 +277,31 @@ export function registerServeCommand(program, context) {
                 exposeDebugInfo,
                 enableMcp,
                 enableManagement,
-                mcpHandler,
+                mcpHandlerFactory,
                 tls,
                 projectRoot: projectRoot || undefined,
                 service,
                 packageAllowlist,
+                actionAllowlist,
+                views: viewsConfig,
             });
             const displayHost = formatHostForUrl(host);
             const actualEndpointHost = formatHostForUrl(host === "0.0.0.0" ? "127.0.0.1" : host);
             const scheme = tls ? "https" : "http";
-            printServerBanner(`ActionDock 2.0 HTTP Runner Server`, scheme, displayHost, server.port, context);
+            printServerBanner(`ActionDock 2.0 HTTP Runner Server`, scheme, displayHost, server.port, context, {
+                views: viewsConfig,
+                endpointHost: actualEndpointHost,
+                enableMcp,
+            });
             if (resolvedPackageIds.length > 0) {
                 writeStdout(`  * Packages:        ${resolvedPackageIds.join(", ")}`, context);
             }
             else {
                 writeStdout(`  * Project:         ${projectName}`, context);
             }
+            if (actionAllowlist && actionAllowlist.length > 0) {
+                writeStdout(`  * Actions:         ${actionAllowlist.join(", ")}`, context);
+            }
             if (projectRoot && exposeDebugInfo) {
                 writeStdout(`  * Root Path:       ${projectRoot}`, context);
             }

package/dist/utils/server-launch.d.ts

@@ -1,3 +1,4 @@
+import type { ServerViewOptions } from "@actiondock/core/server";
 import type { CliContext } from "../types.js";
 /**
  * 服务类命令（ad serve、ad mcp serve、ad mcp、ad run）的共享启动脚手架（单一事实源）。
@@ -51,11 +52,63 @@ export declare function registerStopSignalHandler(server: {
     stop(): Promise<unknown> | unknown;
 }, serverName: string, context?: CliContext): void;
 /**
- * 打印服务就绪横幅（顶部固定段，serve 与 mcp serve 共享排版）。
+ * 虚拟视图简要展示信息。
+ */
+export interface ServerViewSummary {
+    name: string;
+    enableMcp?: boolean;
+}
+/**
+ * 打印服务横幅的可选配置参数。
+ */
+export interface PrintServerBannerOptions {
+    views?: Record<string, ServerViewOptions> | ServerViewOptions[];
+    endpointHost?: string;
+    enableMcp?: boolean;
+}
+/**
+ * 从指定文件路径加载虚拟视图配置字典。
+ *
+ * @param filePath 视图配置文件路径
+ * @returns 解析后的视图字典或数组
+ */
+export declare function loadViewsFromFile(filePath: string): Record<string, ServerViewOptions> | ServerViewOptions[];
+/**
+ * 合并项目配置与独立配置文件中的虚拟视图定义。
+ * 命令行 --views-file 优先级高于项目配置文件 actiondock.json 中的 server.views。
+ *
+ * @param configViews 项目配置中的 views
+ * @param fileViews 独立配置文件中的 views
+ */
+export declare function mergeServerViews(configViews?: Record<string, ServerViewOptions> | ServerViewOptions[], fileViews?: Record<string, ServerViewOptions> | ServerViewOptions[]): Record<string, ServerViewOptions> | ServerViewOptions[] | undefined;
+/**
+ * 从服务视图配置中提取所有命名空间视图列表（排除 default 默认视图）。
+ *
+ * @param views 视图字典或数组
+ * @returns 命名空间视图简要信息列表
+ */
+export declare function extractNamespacedViews(views?: Record<string, ServerViewOptions> | ServerViewOptions[]): ServerViewSummary[];
+/**
+ * 打印服务命名空间虚拟视图列表。
+ *
+ * @param views 视图配置字典或数组
+ * @param scheme 访问协议（http 或 https）
+ * @param endpointHost 面向调用的端点主机地址
+ * @param port 监听端口
+ * @param context CLI 上下文
+ * @param options 额外选项（如全局 enableMcp）
+ */
+export declare function printServerViews(views: Record<string, ServerViewOptions> | ServerViewOptions[] | undefined, scheme: string, endpointHost: string, port: number, context?: CliContext, options?: {
+    enableMcp?: boolean;
+}): void;
+/**
+ * 打印服务就绪横幅（顶部固定段，支持展示命名空间视图）。
  *
  * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
  * @param scheme 端点协议（http 或 https）
  * @param displayHost 面向展示的主机地址
  * @param port 实际监听端口
+ * @param contextOrOptions 命令行上下文或横幅配置选项
+ * @param maybeOptions 横幅配置选项（包含 views 等信息）
  */
-export declare function printServerBanner(title: string, scheme: string, displayHost: string, port: number, context?: CliContext): void;
+export declare function printServerBanner(title: string, scheme: string, displayHost: string, port: number, contextOrOptions?: CliContext | PrintServerBannerOptions, maybeOptions?: PrintServerBannerOptions): void;

package/dist/utils/server-launch.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { parseDuration, } from "@actiondock/core/project";
 import { ArgumentError } from "../errors.js";
 import { writeStderr, writeStdout } from "../renderer.js";
@@ -99,16 +101,175 @@ export function registerStopSignalHandler(server, serverName, context) {
     process.once("SIGTERM", stopSignalHandler);
 }
 /**
- * 打印服务就绪横幅（顶部固定段，serve 与 mcp serve 共享排版）。
+ * 从指定文件路径加载虚拟视图配置字典。
+ *
+ * @param filePath 视图配置文件路径
+ * @returns 解析后的视图字典或数组
+ */
+export function loadViewsFromFile(filePath) {
+    const resolvedPath = resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        throw new ArgumentError(`Views file not found: ${resolvedPath}`);
+    }
+    let parsed;
+    try {
+        const content = readFileSync(resolvedPath, "utf-8");
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ArgumentError(`Failed to read views file: ${msg}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new ArgumentError("Invalid views file: expected a JSON object or array");
+    }
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    const obj = parsed;
+    if (obj.views && typeof obj.views === "object") {
+        return obj.views;
+    }
+    if (obj.server && typeof obj.server === "object" && obj.server.views) {
+        const srv = obj.server;
+        return srv.views;
+    }
+    return parsed;
+}
+/**
+ * 合并项目配置与独立配置文件中的虚拟视图定义。
+ * 命令行 --views-file 优先级高于项目配置文件 actiondock.json 中的 server.views。
+ *
+ * @param configViews 项目配置中的 views
+ * @param fileViews 独立配置文件中的 views
+ */
+export function mergeServerViews(configViews, fileViews) {
+    if (!configViews && !fileViews) {
+        return undefined;
+    }
+    if (!configViews) {
+        return fileViews;
+    }
+    if (!fileViews) {
+        return configViews;
+    }
+    if (!Array.isArray(configViews) && !Array.isArray(fileViews)) {
+        return { ...configViews, ...fileViews };
+    }
+    const merged = {};
+    const addEntry = (item, fallbackKey) => {
+        const key = item.name?.trim() || fallbackKey;
+        merged[key] = { ...item, name: key };
+    };
+    if (Array.isArray(configViews)) {
+        configViews.forEach((item, index) => addEntry(item, item.name || `view_${index}`));
+    }
+    else {
+        Object.entries(configViews).forEach(([k, v]) => addEntry(v, k));
+    }
+    if (Array.isArray(fileViews)) {
+        fileViews.forEach((item, index) => addEntry(item, item.name || `view_${index}`));
+    }
+    else {
+        Object.entries(fileViews).forEach(([k, v]) => addEntry(v, k));
+    }
+    return merged;
+}
+/**
+ * 从服务视图配置中提取所有命名空间视图列表（排除 default 默认视图）。
+ *
+ * @param views 视图字典或数组
+ * @returns 命名空间视图简要信息列表
+ */
+export function extractNamespacedViews(views) {
+    if (!views)
+        return [];
+    const result = [];
+    if (Array.isArray(views)) {
+        for (let i = 0; i < views.length; i++) {
+            const item = views[i];
+            if (!item)
+                continue;
+            const name = item.name?.trim() || `view_${i}`;
+            if (name === "default")
+                continue;
+            result.push({
+                name,
+                enableMcp: item.enableMcp,
+            });
+        }
+    }
+    else if (typeof views === "object") {
+        for (const [key, item] of Object.entries(views)) {
+            if (!item)
+                continue;
+            const name = item.name?.trim() || key.trim();
+            if (name === "default")
+                continue;
+            result.push({
+                name,
+                enableMcp: item.enableMcp,
+            });
+        }
+    }
+    return result;
+}
+/**
+ * 打印服务命名空间虚拟视图列表。
+ *
+ * @param views 视图配置字典或数组
+ * @param scheme 访问协议（http 或 https）
+ * @param endpointHost 面向调用的端点主机地址
+ * @param port 监听端口
+ * @param context CLI 上下文
+ * @param options 额外选项（如全局 enableMcp）
+ */
+export function printServerViews(views, scheme, endpointHost, port, context, options) {
+    const namespaced = extractNamespacedViews(views);
+    if (namespaced.length === 0) {
+        return;
+    }
+    writeStdout(`  * Views:`, context);
+    for (const v of namespaced) {
+        const encodedName = encodeURIComponent(v.name);
+        writeStdout(`    - ${v.name}:`, context);
+        writeStdout(`      - HTTP Root:    ${scheme}://${endpointHost}:${port}/views/${encodedName}`, context);
+        const mcpEnabled = options?.enableMcp !== false && v.enableMcp !== false;
+        const mcpDesc = mcpEnabled
+            ? `${scheme}://${endpointHost}:${port}/views/${encodedName}/mcp`
+            : "Disabled";
+        writeStdout(`      - MCP Endpoint: ${mcpDesc}`, context);
+    }
+}
+/**
+ * 打印服务就绪横幅（顶部固定段，支持展示命名空间视图）。
  *
  * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
  * @param scheme 端点协议（http 或 https）
  * @param displayHost 面向展示的主机地址
  * @param port 实际监听端口
+ * @param contextOrOptions 命令行上下文或横幅配置选项
+ * @param maybeOptions 横幅配置选项（包含 views 等信息）
  */
-export function printServerBanner(title, scheme, displayHost, port, context) {
+export function printServerBanner(title, scheme, displayHost, port, contextOrOptions, maybeOptions) {
+    let context;
+    let options;
+    if (contextOrOptions &&
+        ("views" in contextOrOptions || "endpointHost" in contextOrOptions || "enableMcp" in contextOrOptions)) {
+        options = contextOrOptions;
+    }
+    else {
+        context = contextOrOptions;
+        options = maybeOptions;
+    }
     writeStdout(`\n======================================================`, context);
     writeStdout(`  ${title}`, context);
     writeStdout(`======================================================`, context);
     writeStdout(`  * Listening on:    ${scheme}://${displayHost}:${port}`, context);
+    if (options?.views) {
+        const endpointHost = options.endpointHost || displayHost;
+        printServerViews(options.views, scheme, endpointHost, port, context, {
+            enableMcp: options.enableMcp,
+        });
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,10 +34,10 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.8.0",
-    "@actiondock/core": "^2.8.0",
-    "@actiondock/mcp": "^2.8.0",
-    "@actiondock/sdk": "^2.8.0",
+    "@actiondock/builder": "^2.9.1",
+    "@actiondock/core": "^2.9.1",
+    "@actiondock/mcp": "^2.9.1",
+    "@actiondock/sdk": "^2.9.1",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },