@actiondock/core 2.8.0 → 2.9.0

package/README.md

@@ -87,6 +87,26 @@ ActionDock 2.x 全面贯彻单一事实源设计，彻底杜绝各模块私自
 
 ---
 
+## 微服务启动与访问控制
+
+通过 `startActionDockServer` 启动 Node.js 原生 HTTP/HTTPS 微服务，提供标准 RESTful API 与统一内嵌 `/mcp` 端点：
+
+- 服务配置参数（`ServerOptions`）：
+  - `port`：监听端口（默认 5177）。
+  - `host`：监听地址（默认 127.0.0.1，监听非回环地址时强制要求配置 token）。
+  - `token`：服务访问鉴权令牌。
+  - `packageAllowlist`：允许访问执行的包标识白名单列表（为空允许全部）。
+  - `actionAllowlist`：允许访问执行的动作标识白名单列表（为空允许全部，支持短名 actionId 与全限定名 packageId/actionId）。
+  - `tls`：HTTPS 证书与私钥配置。
+  - `corsOrigins`：允许的跨域来源白名单。
+- 权限交集与安全拦截：
+  - 同时配置 `packageAllowlist` 与 `actionAllowlist` 时取两者交集。
+  - 未在白名单中的动作详情调阅与执行请求均被严格拦截，返回 HTTP 403 状态码与 `ACTION_FORBIDDEN` 结构化错误。
+  - 历史运行记录查询、单次详情与取消操作同步实施白名单校验。
+  - 统一内嵌的 MCP 协议端点工具注册与任务扩展同样受白名单联动过滤。
+
+---
+
 ## 数据目录锁与故障自愈
 
 通过 `DataDirLock` 在数据目录下维护 `.actiondock.data.lock` 排他文件锁，记录宿主进程与受管子进程状态：

package/dist/errors.d.ts

@@ -98,6 +98,8 @@ export declare const SERVER_ERROR = "SERVER_ERROR";
 export declare const BAD_REQUEST = "BAD_REQUEST";
 /** 目标包未列入允许白名单（403 禁止访问） */
 export declare const PACKAGE_FORBIDDEN = "PACKAGE_FORBIDDEN";
+/** 目标动作未列入允许白名单（403 禁止访问） */
+export declare const ACTION_FORBIDDEN = "ACTION_FORBIDDEN";
 /** 目标规程未找到 */
 export declare const PLAYBOOK_NOT_FOUND = "PLAYBOOK_NOT_FOUND";
 /** 请求体体积超出安全限制 */
@@ -265,7 +267,9 @@ export declare class ActionDockError<T = any> extends Error {
 /**
  * 集中定义的标准结构化错误码联合类型。
  */
-export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof STORAGE_WORKER_EXITED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR;
+export type ErrorCode = typeof PACKAGE_NOT_FOUND | typeof ACTION_PACKAGE_VERSION_CONFLICT | typeof ACTION_NOT_FOUND | typeof ACTION_LOAD_FAILED | typeof ACTION_FAILED | typeof ACTION_TIMEOUT | typeof ACTION_CANCELLED | typeof INPUT_VALIDATION_FAILED | typeof OUTPUT_VALIDATION_FAILED | typeof INPUT_NOT_JSON | typeof OUTPUT_NOT_JSON | typeof ACTION_SUBRUN_LIMIT | typeof ACTION_CALL_CYCLE | typeof UNDECLARED_ACTION_DEPENDENCY | typeof INVALID_ACTION_REF | typeof IDEMPOTENCY_CONFLICT | typeof EXECUTION_FAILED | typeof UNHANDLED_EXECUTION_ERROR | typeof RUN_REPOSITORY_UNAVAILABLE | typeof RUN_PERSISTENCE_FAILED | typeof STANDALONE_ASYNC_UNSUPPORTED | typeof INVOCATION_UNSUPPORTED | typeof HOST_PROCESS_EXITED | typeof EXECUTION_ABORTED | typeof TIMEOUT | typeof SERVICE_CLOSED | typeof NETWORK_ERROR | typeof INSECURE_TRANSPORT | typeof REMOTE_REQUEST_FAILED | typeof REMOTE_STREAM_UNAVAILABLE | typeof CAPABILITY_UNAVAILABLE | typeof STATE_KEY_NOT_FOUND | typeof STORAGE_BUSY | typeof PROJECT_BUSY | typeof PROJECT_RECOVERY_REQUIRED | typeof STORAGE_WORKER_EXITED | typeof EVENT_BACKPRESSURE_LIMIT | typeof EVENT_CURSOR_EXPIRED | typeof PROCESS_OUTPUT_LIMIT | typeof PROCESS_SPAWN_ERROR | typeof PROCESS_CANCELLED | typeof PROCESS_TIMEOUT | typeof UNAUTHORIZED | typeof NOT_FOUND | typeof SERVER_ERROR | typeof BAD_REQUEST | typeof PACKAGE_FORBIDDEN | typeof ACTION_FORBIDDEN | typeof PLAYBOOK_NOT_FOUND | typeof REQUEST_TOO_LARGE | typeof ACTION_START_FAILED | typeof ACTION_EXECUTION_ERROR | typeof ACTIONS_LIST_ERROR | typeof PLAYBOOKS_LIST_ERROR | typeof RUNS_LIST_ERROR | typeof RUNS_CLEAR_ERROR | typeof INFO_ERROR | typeof PACKAGES_INFO_ERROR | typeof DOCTOR_ERROR | typeof RUN_INTERRUPTED | typeof CONFIG_ENV_ERROR | typeof CONFIG_LIST_ERROR | typeof CONFIG_SET_ERROR | typeof CONFIG_DELETE_ERROR | typeof STATE_LIST_ERROR | typeof STATE_CLEAR_ERROR | typeof STATE_KEY_ERROR | typeof DATA_DIR_IN_USE | typeof DATA_DIR_RECOVERY_REQUIRED | typeof UNSUPPORTED_STORAGE_SCHEMA | typeof STORED_ERROR_DECODE_FAILED | typeof PROCESS_FAILED | typeof GENERATED_TYPES_OUTDATED | typeof PROTOCOL_UNSUPPORTED | typeof SERVICE_RESULT_UNKNOWN | typeof MCP_TOOL_NAME_COLLISION | typeof ACCESS_DENIED | typeof UNSUPPORTED_CAPABILITY | typeof CONTROL_BUSY | typeof CONTROL_EXPIRED | typeof CONTROL_REVOKED | typeof PROCESS_QUARANTINED | typeof PROCESS_LOST | typeof REQUEST_CONFLICT | typeof INPUT_OUTCOME_UNKNOWN | typeof OUTPUT_GAP | typeof OUTPUT_UNAVAILABLE | typeof INVALID_CURSOR | typeof QUEUE_FULL | typeof QUOTA_EXCEEDED | typeof INPUT_CLOSED | typeof INVALID_FLAT_ARGUMENT | typeof INVALID_JSON | typeof INVALID_JSON_LITERAL | typeof INPUT_PATH_CONFLICT | typeof FLAT_INPUT_LIMIT_EXCEEDED | typeof INPUT_LIMIT_EXCEEDED | typeof INPUT_POLICY_VIOLATION | typeof INPUT_CONFLICT | typeof INPUT_FILE_NOT_FOUND | typeof INPUT_FILE_READ_FAILED | typeof INVALID_ARGUMENT | typeof PACKAGE_NOT_ALLOWED | typeof INVALID_PACKAGE_ID | typeof PATH_TRAVERSAL | typeof AMBIGUOUS_STATE_KEY | typeof RUN_NOT_FOUND | typeof RUN_ALREADY_FINISHED | typeof IPC_ERROR | typeof SERVICE_ERROR;
+/** 全仓统一错误码类型别名 */
+export type ActionDockErrorCode = ErrorCode;
 /**
  * 进程领域结构化异常类。
  */

package/dist/errors.js

@@ -98,6 +98,8 @@ export const SERVER_ERROR = "SERVER_ERROR";
 export const BAD_REQUEST = "BAD_REQUEST";
 /** 目标包未列入允许白名单（403 禁止访问） */
 export const PACKAGE_FORBIDDEN = "PACKAGE_FORBIDDEN";
+/** 目标动作未列入允许白名单（403 禁止访问） */
+export const ACTION_FORBIDDEN = "ACTION_FORBIDDEN";
 /** 目标规程未找到 */
 export const PLAYBOOK_NOT_FOUND = "PLAYBOOK_NOT_FOUND";
 /** 请求体体积超出安全限制 */

package/dist/index.d.ts

@@ -18,4 +18,4 @@ export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
 export type { ProjectConfig, } from "./project/types.js";
 export type { PackageGraph, } from "./catalog/graph.js";
-export { ActionDockError, ProcessError, type ErrorCode, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";
+export { ActionDockError, ProcessError, type ErrorCode, type ActionDockErrorCode, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/index.js

@@ -16,4 +16,4 @@ export { startActionDockServer, } from "./server/server.js";
 export { initProject } from "./project/init.js";
 export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
 // 8. 统一错误模型与核心标准错误码常量
-export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.8.0",
+            "@actiondock/sdk": "^2.9.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.8.0",
+            "@actiondock/testing": "^2.9.0",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/project/types.d.ts

@@ -83,6 +83,11 @@ export interface ActionDockManifest {
     actionsDir?: string;
     /** Playbook 规程文档存放目录（向后兼容过渡配置） */
     playbooksDir?: string;
+    /** 服务端高级配置（如虚拟投影视图 views 等） */
+    server?: {
+        views?: Record<string, import("../server/types.js").ServerViewOptions> | import("../server/types.js").ServerViewOptions[];
+        [key: string]: unknown;
+    };
 }
 /**
  * ActionDock 项目根配置文件契约（等同于 ActionDockManifest，actiondock.json 为单一事实源）。

package/dist/server/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./security.js";
+export * from "./policy.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";

package/dist/server/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./security.js";
+export * from "./policy.js";
 export * from "./body.js";
 export * from "./routes/index.js";
 export * from "./server.js";

package/dist/server/policy.d.ts

@@ -0,0 +1,138 @@
+import { ActionDockError } from "../errors.js";
+import type { McpEndpointHandler } from "./mcp-endpoint.js";
+import type { EffectiveServerPolicy, ServerOptions, ServerViewOptions } from "./types.js";
+export { extractBearerToken } from "./security.js";
+/**
+ * 动作未列入白名单拒绝访问异常。
+ */
+export declare class ActionForbiddenError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(actionRef: string);
+}
+/**
+ * 包未列入白名单拒绝访问异常。
+ */
+export declare class PackageNotAllowedError extends ActionDockError {
+    status: number;
+    statusCode: number;
+    constructor(packageId: string);
+}
+/**
+ * 归一化后的单个服务视图结构。
+ */
+export interface NormalizedServerView {
+    /** 视图唯一标识名称 */
+    name: string;
+    /** 该视图生效的统一安全策略 */
+    policy: EffectiveServerPolicy;
+    /** 该视图是否启用 MCP 端点 */
+    enableMcp: boolean;
+    /** 原始配置选项 */
+    rawOptions: ServerViewOptions;
+    /** 为该视图独立装配的 MCP 端点处理器 */
+    mcpEndpointHandler?: McpEndpointHandler;
+}
+/**
+ * 根据客户端携带的 Token 智能匹配已注册的视图。
+ * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
+ *
+ * @param token 客户端提供的 Bearer Token
+ * @param views 可遍历的视图集合
+ * @returns 匹配成功的视图对象，未命中返回 undefined
+ */
+export declare function matchViewByToken(token: string, views: Iterable<NormalizedServerView>): NormalizedServerView | undefined;
+/**
+ * 归一化解析服务端配置的所有视图集合。
+ * 保证默认视图与显式自定义视图具有统一的数据结构。
+ *
+ * @param options 服务端配置选项
+ * @returns 默认视图与全部视图 Map 映射
+ */
+export declare function normalizeServerViews(options: ServerOptions): {
+    defaultView: NormalizedServerView;
+    views: Map<string, NormalizedServerView>;
+};
+/**
+ * 校验目标动作是否在 actionAllowlist 允许白名单中。
+ * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
+ * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
+ * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param allowlist 允许动作白名单列表
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowed(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, allowlist?: string[]): boolean;
+/**
+ * 根据生效策略统一判定目标动作是否允许访问。
+ * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string | null | undefined, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定目标包标识是否允许访问。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export declare function isPackageAllowedByPolicy(packageId?: string | null, policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略统一判定配置与状态管理路由是否开启。
+ *
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许管理操作
+ */
+export declare function isManagementAllowedByPolicy(policy?: EffectiveServerPolicy): boolean;
+/**
+ * 根据生效策略对动作列表进行统一过滤。
+ *
+ * @param actions 待过滤的动作列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的动作列表
+ */
+export declare function filterActionsByPolicy<T extends {
+    id: string;
+    packageId?: string;
+    actionId?: string;
+}>(actions: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 根据生效策略对包列表进行统一过滤。
+ *
+ * @param packages 待过滤的包列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的包列表
+ */
+export declare function filterPackagesByPolicy<T extends {
+    id: string;
+}>(packages: T[], policy?: EffectiveServerPolicy): T[];
+/**
+ * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param action 目标动作对象或引用
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertActionAllowedByPolicy(action: {
+    actionId?: string;
+    id?: string;
+    packageId?: string;
+} | string, policy?: EffectiveServerPolicy): void;
+/**
+ * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ */
+export declare function assertPackageAllowedByPolicy(packageId: string, policy?: EffectiveServerPolicy): void;

package/dist/server/policy.js

@@ -0,0 +1,368 @@
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { ActionDockError, ACTION_FORBIDDEN, PACKAGE_NOT_ALLOWED } from "../errors.js";
+import { safeEqual } from "./security.js";
+export { extractBearerToken } from "./security.js";
+/**
+ * 动作未列入白名单拒绝访问异常。
+ */
+export class ActionForbiddenError extends ActionDockError {
+    status = 403;
+    statusCode = 403;
+    constructor(actionRef) {
+        super(ACTION_FORBIDDEN, `Action '${actionRef}' is not in the allowed action list`);
+        this.name = "ActionForbiddenError";
+        Object.setPrototypeOf(this, ActionForbiddenError.prototype);
+    }
+}
+/**
+ * 包未列入白名单拒绝访问异常。
+ */
+export class PackageNotAllowedError extends ActionDockError {
+    status = 403;
+    statusCode = 403;
+    constructor(packageId) {
+        super(PACKAGE_NOT_ALLOWED, `Package '${packageId}' is not in the allowed package list`);
+        this.name = "PackageNotAllowedError";
+        Object.setPrototypeOf(this, PackageNotAllowedError.prototype);
+    }
+}
+/**
+ * 根据客户端携带的 Token 智能匹配已注册的视图。
+ * 使用 safeEqual 进行恒定时间比较以防范时序攻击。
+ *
+ * @param token 客户端提供的 Bearer Token
+ * @param views 可遍历的视图集合
+ * @returns 匹配成功的视图对象，未命中返回 undefined
+ */
+export function matchViewByToken(token, views) {
+    const trimmed = token.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    let matched = undefined;
+    for (const view of views) {
+        const candidateToken = view.policy.token?.trim();
+        if (candidateToken) {
+            const isMatch = safeEqual(trimmed, candidateToken);
+            if (isMatch && !matched) {
+                matched = view;
+            }
+        }
+    }
+    return matched;
+}
+/**
+ * 归一化解析服务端配置的所有视图集合。
+ * 保证默认视图与显式自定义视图具有统一的数据结构。
+ *
+ * @param options 服务端配置选项
+ * @returns 默认视图与全部视图 Map 映射
+ */
+export function normalizeServerViews(options) {
+    const views = new Map();
+    // 1. 初始化基于全局配置的默认视图
+    const defaultRawOptions = {
+        name: "default",
+        token: options.token,
+        packageAllowlist: options.packageAllowlist,
+        actionAllowlist: options.actionAllowlist,
+        enableManagement: options.enableManagement,
+        enableMcp: options.enableMcp !== false,
+        mcpHandler: options.mcpHandler,
+    };
+    const customViews = new Map();
+    // 2. 解析 options.views 自定义视图
+    if (options.views) {
+        if (Array.isArray(options.views)) {
+            for (let i = 0; i < options.views.length; i++) {
+                const item = options.views[i];
+                if (!item || typeof item !== "object")
+                    continue;
+                const name = item.name?.trim() || `view_${i}`;
+                if (!name || name === "." || name === "..") {
+                    continue;
+                }
+                if (name === "default") {
+                    Object.assign(defaultRawOptions, item);
+                }
+                else {
+                    customViews.set(name, {
+                        name,
+                        policy: {
+                            viewName: name,
+                            token: item.token,
+                            packageAllowlist: item.packageAllowlist,
+                            actionAllowlist: item.actionAllowlist,
+                            enableManagement: item.enableManagement,
+                        },
+                        enableMcp: item.enableMcp !== false,
+                        rawOptions: item,
+                    });
+                }
+            }
+        }
+        else if (typeof options.views === "object") {
+            for (const [key, item] of Object.entries(options.views)) {
+                if (!item || typeof item !== "object")
+                    continue;
+                const name = item.name?.trim() || key.trim();
+                if (!name || name === "." || name === "..") {
+                    continue;
+                }
+                if (name === "default") {
+                    Object.assign(defaultRawOptions, item);
+                }
+                else {
+                    customViews.set(name, {
+                        name,
+                        policy: {
+                            viewName: name,
+                            token: item.token,
+                            packageAllowlist: item.packageAllowlist,
+                            actionAllowlist: item.actionAllowlist,
+                            enableManagement: item.enableManagement,
+                        },
+                        enableMcp: item.enableMcp !== false,
+                        rawOptions: item,
+                    });
+                }
+            }
+        }
+    }
+    const defaultView = {
+        name: "default",
+        policy: {
+            viewName: "default",
+            token: defaultRawOptions.token,
+            packageAllowlist: defaultRawOptions.packageAllowlist,
+            actionAllowlist: defaultRawOptions.actionAllowlist,
+            enableManagement: defaultRawOptions.enableManagement,
+        },
+        enableMcp: defaultRawOptions.enableMcp !== false,
+        rawOptions: defaultRawOptions,
+    };
+    // 默认视图置于首位，随后装载自定义视图
+    views.set("default", defaultView);
+    for (const [k, v] of customViews) {
+        views.set(k, v);
+    }
+    return { defaultView, views };
+}
+/**
+ * 校验目标动作是否在 actionAllowlist 允许白名单中。
+ * 支持短名 actionId 与全限定名 packageId/actionId 匹配：
+ * - 白名单项若含 '/'（如 pkg/act），则必须 packageId 与 actionId 同时精确匹配。
+ * - 白名单项若不含 '/'（如 act），则只需 actionId 匹配（不限包）。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param allowlist 允许动作白名单列表
+ * @returns 是否允许访问
+ */
+export function isActionAllowed(action, allowlist) {
+    if (!allowlist || !Array.isArray(allowlist) || allowlist.length === 0) {
+        return true;
+    }
+    if (!action) {
+        return false;
+    }
+    let target;
+    try {
+        if (typeof action === "string") {
+            target = parseActionRef(action);
+        }
+        else {
+            const rawId = action.actionId || action.id;
+            if (!rawId)
+                return false;
+            if (action.packageId) {
+                if (rawId.includes("/")) {
+                    target = parseActionRef(rawId);
+                }
+                else {
+                    target = parseActionRef({
+                        packageId: action.packageId,
+                        actionId: rawId,
+                    });
+                }
+            }
+            else {
+                target = parseActionRef(rawId);
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    for (const item of allowlist) {
+        if (typeof item !== "string")
+            continue;
+        const trimmed = item.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const rule = parseActionRef(trimmed);
+            if (rule.packageId) {
+                if (rule.packageId === target.packageId && rule.actionId === target.actionId) {
+                    return true;
+                }
+            }
+            else {
+                if (rule.actionId === target.actionId) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
+/**
+ * 根据生效策略统一判定目标动作是否允许访问。
+ * 同时综合校验策略中的 packageAllowlist 与 actionAllowlist 约束。
+ *
+ * @param action 目标动作对象或引用字符串
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export function isActionAllowedByPolicy(action, policy) {
+    if (!policy) {
+        return true;
+    }
+    if (!action) {
+        return false;
+    }
+    let pkgId;
+    let actId;
+    try {
+        if (typeof action === "string") {
+            const parsed = parseActionRef(action);
+            pkgId = parsed.packageId;
+            actId = parsed.actionId;
+        }
+        else {
+            pkgId = action.packageId;
+            const rawId = action.actionId || action.id;
+            if (!rawId)
+                return false;
+            if (rawId.includes("/")) {
+                const parsed = parseActionRef(rawId);
+                pkgId = parsed.packageId || pkgId;
+                actId = parsed.actionId;
+            }
+            else {
+                actId = rawId;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    // 1. 若配置了 packageAllowlist，校验所属包白名单
+    if (policy.packageAllowlist && policy.packageAllowlist.length > 0) {
+        if (pkgId) {
+            if (!policy.packageAllowlist.includes(pkgId)) {
+                return false;
+            }
+        }
+        else {
+            // 未指明所属包时，仅当其动作标识明确列入 actionAllowlist 时才允许放行
+            if (!policy.actionAllowlist ||
+                policy.actionAllowlist.length === 0 ||
+                !isActionAllowed({ actionId: actId }, policy.actionAllowlist)) {
+                return false;
+            }
+        }
+    }
+    // 2. 若配置了 actionAllowlist，校验动作白名单
+    if (policy.actionAllowlist && policy.actionAllowlist.length > 0) {
+        if (!isActionAllowed({ packageId: pkgId, actionId: actId }, policy.actionAllowlist)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 根据生效策略统一判定目标包标识是否允许访问。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许访问
+ */
+export function isPackageAllowedByPolicy(packageId, policy) {
+    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+        return true;
+    }
+    if (!packageId) {
+        return false;
+    }
+    return policy.packageAllowlist.includes(packageId);
+}
+/**
+ * 根据生效策略统一判定配置与状态管理路由是否开启。
+ *
+ * @param policy 当前生效的服务端策略
+ * @returns 是否允许管理操作
+ */
+export function isManagementAllowedByPolicy(policy) {
+    return policy?.enableManagement === true;
+}
+/**
+ * 根据生效策略对动作列表进行统一过滤。
+ *
+ * @param actions 待过滤的动作列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的动作列表
+ */
+export function filterActionsByPolicy(actions, policy) {
+    if (!policy) {
+        return actions;
+    }
+    const hasPkg = policy.packageAllowlist && policy.packageAllowlist.length > 0;
+    const hasAct = policy.actionAllowlist && policy.actionAllowlist.length > 0;
+    if (!hasPkg && !hasAct) {
+        return actions;
+    }
+    return actions.filter((a) => isActionAllowedByPolicy({ packageId: a.packageId, actionId: a.actionId || a.id }, policy));
+}
+/**
+ * 根据生效策略对包列表进行统一过滤。
+ *
+ * @param packages 待过滤的包列表
+ * @param policy 当前生效的服务端策略
+ * @returns 过滤后允许访问的包列表
+ */
+export function filterPackagesByPolicy(packages, policy) {
+    if (!policy?.packageAllowlist || policy.packageAllowlist.length === 0) {
+        return packages;
+    }
+    return packages.filter((p) => p.id && policy.packageAllowlist.includes(p.id));
+}
+/**
+ * 校验目标动作是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param action 目标动作对象或引用
+ * @param policy 当前生效的服务端策略
+ */
+export function assertActionAllowedByPolicy(action, policy) {
+    if (!isActionAllowedByPolicy(action, policy)) {
+        const actRef = typeof action === "string"
+            ? action
+            : action.packageId
+                ? `${action.packageId}/${action.actionId || action.id}`
+                : action.actionId || action.id || "unknown";
+        throw new ActionForbiddenError(actRef);
+    }
+}
+/**
+ * 校验目标包是否属于允许白名单，不符合则抛出 403 异常。
+ *
+ * @param packageId 目标包 ID
+ * @param policy 当前生效的服务端策略
+ */
+export function assertPackageAllowedByPolicy(packageId, policy) {
+    if (!isPackageAllowedByPolicy(packageId, policy)) {
+        throw new PackageNotAllowedError(packageId);
+    }
+}