@actiondock/core 2.9.0 → 2.10.0

package/README.md

@@ -56,7 +56,7 @@ Service -> Resolution -> PackageRuntime -> ExecutionService -> ActionRunner -> A
 
 - 发现端口 `DiscoveryPort`：负责包与动作的元数据发现、清单检索、全文过滤与规程查询。
 - 执行端口 `ExecutionPort`：负责动作的同步阻塞执行（`run`）与异步启动执行（`start`）。
-- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询与协同取消（`cancel`）。
+- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询、协同取消（`cancel`）以及历史记录清理与保留策略淘汰（`clearRuns`、`cleanExpiredRuns`）。
 - 事件端口 `EventsPort`：负责任务执行实时事件流订阅。
 - 配置端口 `ConfigPort`：负责运行时分层配置读取、持久化配置管理与环境变量满足度体检。
 - 状态端口 `StatePort`：负责包级与动作级持久化键值存取、前缀列举与过期清理。

package/dist/catalog/graph.js

@@ -57,10 +57,13 @@ export class UndeclaredActionDependencyError extends ActionDockError {
     targetRef;
     caller;
     constructor(targetRef, caller, reason) {
+        const hint = caller
+            ? `Hint: Add '${targetRef}' to the 'uses' array of action '${caller}' in actiondock.json, then run 'ad validate'.`
+            : undefined;
         const msg = caller
-            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' 未在 'uses' 中声明对 '${targetRef}' 的跨包依赖`
+            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' 未在 'uses' 中声明对 '${targetRef}' 的跨包依赖${hint ? `\n${hint}` : ""}`
             : `UNDECLARED_ACTION_DEPENDENCY: 根调用 Action '${targetRef}' 被拒绝: 目标包既非 actiondock.json 直接依赖，亦未被可见 Playbook 委托${reason ? ` (${reason})` : ""}`;
-        super(UNDECLARED_ACTION_DEPENDENCY, msg);
+        super(UNDECLARED_ACTION_DEPENDENCY, msg, hint ? { hint } : undefined, undefined, hint);
         this.name = "UndeclaredActionDependencyError";
         this.targetRef = targetRef;
         this.caller = caller;

package/dist/doctor/checks/project.js

@@ -115,7 +115,7 @@ async function checkProjectActions(scope) {
                 name: "Actions",
                 status: "warn",
                 message: `No actions found in '${config.actionsDir || "actions"}'`,
-                fix: "Run 'ad action new <id>' to create your first action",
+                fix: "Run 'ad action create <id>' to create your first action",
             });
         }
         else {
@@ -155,7 +155,7 @@ function checkProjectManifest(scope) {
                     name: "Action Manifest",
                     status: "warn",
                     message: `${MANIFEST_FILE_NAME} not found (${actionFiles.length} action source file(s) exist)`,
-                    fix: "Run 'ad validate' to generate or check manifest",
+                    fix: "Run 'ad init' to initialize project manifest, or manually create 'actiondock.json'",
                 });
             }
         }
@@ -174,7 +174,7 @@ function checkProjectManifest(scope) {
                     name: "Action Manifest",
                     status: "warn",
                     message: `${missingFiles.length} action(s) in manifest point to missing files: ${missingFiles.join(", ")}`,
-                    fix: "Run 'ad validate' to check or update actiondock.json",
+                    fix: "Update actiondock.json or use 'ad action create <id>'",
                 });
             }
             else if (untracked.length > 0) {
@@ -184,7 +184,7 @@ function checkProjectManifest(scope) {
                     name: "Action Manifest",
                     status: "warn",
                     message: `${untracked.length} action file(s) not declared in manifest: ${untracked.join(", ")}`,
-                    fix: "Run 'ad validate' to check or update actiondock.json",
+                    fix: "Update actiondock.json or use 'ad action create <id>'",
                 });
             }
             else {

package/dist/doctor/checks/registry.js

@@ -88,7 +88,7 @@ export const checkLinkedPackageDependencies = {
                     name: "Linked Package Dependencies",
                     status: "warn",
                     message: `${missingNodeModules.length} linked package(s) declare dependencies but miss node_modules: ${missingNodeModules.join(", ")}`,
-                    fix: "Run 'npm install' in the affected package directories, or execute 'ad run' to auto-install",
+                    fix: "Run 'npm install --omit=dev' in the affected package directories",
                 });
             }
             else {

package/dist/errors.d.ts

@@ -262,8 +262,39 @@ export declare class ActionDockError<T = any> extends Error {
     readonly code: ErrorCode;
     readonly details?: T;
     readonly status?: number;
-    constructor(code: ErrorCode, message: string, details?: T, status?: number);
+    readonly hint?: string;
+    constructor(code: ErrorCode, message: string, details?: T, status?: number, hint?: string);
 }
+/**
+ * 结构化机器错误信封。
+ */
+export interface ErrorEnvelope {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    hint?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * 统一构造机器错误信封。
+ */
+export declare function createErrorEnvelope(code: string, message: string, details?: unknown, meta?: Record<string, unknown>, hint?: string): ErrorEnvelope;
+/**
+ * 根据 Action 执行失败错误解析自愈指引提示文案。
+ *
+ * 作为 CLI 与独立分发器（StandaloneDispatcher）执行失败时提示解析的单一事实源。
+ *
+ * @param targetRef 目标 Action 引用标识（如 "greet" 或 "pkg/greet"）
+ * @param error 执行失败错误对象
+ */
+export declare function resolveExecutionHint(targetRef: string, error?: {
+    code?: string;
+    details?: unknown;
+    hint?: string;
+}): string | undefined;
 /**
  * 集中定义的标准结构化错误码联合类型。
  */

package/dist/errors.js

@@ -178,7 +178,7 @@ export function describeActionLoadFailure(err, context) {
     const rootCause = err instanceof Error ? err.message : String(err ?? "");
     const isMissingModule = isMissingModuleError(rootCause);
     const hint = isMissingModule
-        ? `依赖未安装，在 '${context.projectRoot}' 执行 npm install 或先执行 'ad run ${context.packageId}/${context.actionId}'`
+        ? `项目依赖缺失，请在 '${context.projectRoot}' 目录下运行 'npm install --omit=dev' 安装依赖后再试。`
         : undefined;
     return {
         code: ACTION_LOAD_FAILED,
@@ -263,15 +263,75 @@ export class ActionDockError extends Error {
     code;
     details;
     status;
-    constructor(code, message, details, status) {
+    hint;
+    constructor(code, message, details, status, hint) {
         super(message);
         this.name = "ActionDockError";
         this.code = code;
         this.details = details;
         this.status = status;
+        this.hint =
+            hint ??
+                (details && typeof details === "object" && typeof details.hint === "string"
+                    ? details.hint
+                    : undefined);
         Object.setPrototypeOf(this, ActionDockError.prototype);
     }
 }
+/**
+ * 统一构造机器错误信封。
+ */
+export function createErrorEnvelope(code, message, details, meta, hint) {
+    const effectiveHint = hint ??
+        (details && typeof details === "object" && typeof details.hint === "string"
+            ? details.hint
+            : undefined);
+    const result = {
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+    };
+    if (effectiveHint !== undefined) {
+        result.hint = effectiveHint;
+    }
+    if (meta && Object.keys(meta).length > 0) {
+        result.meta = meta;
+    }
+    return result;
+}
+/**
+ * 根据 Action 执行失败错误解析自愈指引提示文案。
+ *
+ * 作为 CLI 与独立分发器（StandaloneDispatcher）执行失败时提示解析的单一事实源。
+ *
+ * @param targetRef 目标 Action 引用标识（如 "greet" 或 "pkg/greet"）
+ * @param error 执行失败错误对象
+ */
+export function resolveExecutionHint(targetRef, error) {
+    if (!error)
+        return undefined;
+    if (error.code === INPUT_VALIDATION_FAILED) {
+        return `Tip: Run 'ad describe ${targetRef}' to inspect schema and syntax examples.`;
+    }
+    if (error.code === ACTION_NOT_FOUND) {
+        return "Tip: Run 'ad list' to discover available actions, or 'ad info' to inspect packages.";
+    }
+    if (error.code === ACTION_TIMEOUT) {
+        return "Tip: Increase timeout via '--timeout <duration>', or run in background via '--async' and track with 'ad runs show <runId>'.";
+    }
+    if (error.hint && typeof error.hint === "string") {
+        return error.hint;
+    }
+    if (error.details &&
+        typeof error.details === "object" &&
+        typeof error.details.hint === "string") {
+        return error.details.hint;
+    }
+    return undefined;
+}
 /**
  * 进程领域结构化异常类。
  */

package/dist/host/host.d.ts

@@ -91,7 +91,9 @@ export declare class DefaultActionDockHost implements ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     events(runId: string, options?: {
         after?: number | string;

package/dist/host/host.js

@@ -368,7 +368,9 @@ export class DefaultActionDockHost {
                     declaredUses,
                 }, { packageId: targetPackageId, actionId: targetActionId }, this.graph);
                 if (authErr) {
-                    throw new ActionDockError(authErr.code, authErr.message, authErr.details);
+                    const hint = authErr.details?.hint;
+                    const msg = hint ? `${authErr.message}\n${hint}` : authErr.message;
+                    throw new ActionDockError(authErr.code, msg, authErr.details, undefined, hint);
                 }
             }
             // 调用嵌套深度限制校验
@@ -684,6 +686,16 @@ export class DefaultActionDockHost {
         }
         return total;
     }
+    async cleanExpiredRuns(policy) {
+        let total = 0;
+        for (const runtime of this.listRuntimes()) {
+            if (typeof runtime.cleanExpiredRuns === "function") {
+                const res = await runtime.cleanExpiredRuns(policy);
+                total += res;
+            }
+        }
+        return total;
+    }
     async cancelRun(runId, reason) {
         for (const runtime of this.listRuntimes()) {
             const res = await runtime.cancelRun(runId, reason);

package/dist/host/types.d.ts

@@ -80,7 +80,10 @@ export interface ActionDockHost {
         actionId?: string;
         status?: string;
         olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理所有运行时中的过期及超额终态运行记录 */
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 取消指定在运行的任务 */
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     /** 订阅指定运行的事件流 */

package/dist/index.d.ts

@@ -8,6 +8,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 export { createActionDock, connectActionDock, } from "./service/factory.js";
 export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, StateScopeOptions, } from "./service/types.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, type RunsRetentionPolicy, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 export type { ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, ExecutionEvent, } from "@actiondock/sdk";
 export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
 export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";
@@ -18,4 +20,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, 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";
+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, describeActionLoadFailure, type ActionLoadFailureContext, createErrorEnvelope, type ErrorEnvelope, resolveExecutionHint, } from "./errors.js";

package/dist/index.js

@@ -9,6 +9,8 @@
 export { ACTIONDOCK_VERSION } from "./version.js";
 // 2. 统一服务门面与聚合契约接口
 export { createActionDock, connectActionDock, } from "./service/factory.js";
+export { DEFAULT_RUNS_RETENTION_MS, DEFAULT_MAX_RUNS_PER_PACKAGE, DEFAULT_MIN_RETAIN_RUNS, } from "./storage/types.js";
+export { parseDuration } from "./utils/index.js";
 // 5. 原生平台装配与服务启动
 export { createNodePlatform, } from "./platform/node.js";
 export { startActionDockServer, } from "./server/server.js";
@@ -16,4 +18,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, 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";
+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, describeActionLoadFailure, createErrorEnvelope, resolveExecutionHint, } from "./errors.js";

package/dist/input/describe.d.ts

@@ -47,6 +47,8 @@ export interface ActionDescribePayload {
     entry?: string;
     /** 统一输入模式建议 */
     inputAdvice: ActionDescribeAdvice;
+    /** 扁平输入通用语法速查行列表 */
+    syntaxReference?: string[];
 }
 /**
  * 构造 Action 描述载荷的可选选项。
@@ -82,6 +84,10 @@ export declare function buildActionDescribePayload(spec: {
     entry?: string;
     [key: string]: any;
 }, options?: BuildActionDescribePayloadOptions): ActionDescribePayload;
+/**
+ * 扁平输入通用语法速查行列表。
+ */
+export declare const ACTION_DESCRIBE_SYNTAX_REFERENCE: readonly string[];
 /**
  * 格式化渲染 Action 详情人类可读文本。
  * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。

package/dist/input/describe.js

@@ -109,8 +109,26 @@ export function buildActionDescribePayload(spec, options) {
         ...(spec.entry !== undefined ? { entry: spec.entry } : {}),
         inputAdvice: computeActionDescribeAdvice(spec.inputSchema),
     };
+    const hasAssignments = Boolean(payload.inputAdvice.assignments &&
+        Object.keys(payload.inputAdvice.assignments).length > 0);
+    if (payload.inputAdvice.recommendedMode === "flat" || hasAssignments) {
+        payload.syntaxReference = [...ACTION_DESCRIBE_SYNTAX_REFERENCE];
+    }
     return payload;
 }
+/**
+ * 扁平输入通用语法速查行列表。
+ */
+export const ACTION_DESCRIBE_SYNTAX_REFERENCE = [
+    "  # String assignment (= keeps raw string, no type coercion)",
+    '  key="value"',
+    "  # Typed / JSON assignment (:= parses numbers, booleans, arrays, objects)",
+    "  count:=10  enabled:=true",
+    "  # Array structure (direct JSON array or sequential index)",
+    '  tags:=\'["a", "b"]\' (or tags.0="a" tags.1="b")',
+    "  # Complex or multiline inputs (pass via JSON file)",
+    "  --input-file input.json",
+];
 /**
  * 格式化渲染 Action 详情人类可读文本。
  * 普通 CLI 与 Standalone 统一复用该函数，避免长期排版漂移。
@@ -158,13 +176,20 @@ export function formatActionDetail(input) {
     if (payload.inputAdvice.reason) {
         lines.push(`Reason: ${payload.inputAdvice.reason}`);
     }
-    if (payload.inputAdvice.assignments && Object.keys(payload.inputAdvice.assignments).length > 0) {
+    const hasAssignments = Boolean(payload.inputAdvice.assignments &&
+        Object.keys(payload.inputAdvice.assignments).length > 0);
+    if (hasAssignments) {
         lines.push("");
         lines.push("Assignments:");
         for (const [key, op] of Object.entries(payload.inputAdvice.assignments)) {
             lines.push(`  ${key}${op}`);
         }
     }
+    if (payload.inputAdvice.recommendedMode === "flat" || hasAssignments) {
+        lines.push("");
+        lines.push("Syntax Reference:");
+        lines.push(...(payload.syntaxReference || ACTION_DESCRIBE_SYNTAX_REFERENCE));
+    }
     if (payload.inputAdvice.issues && payload.inputAdvice.issues.length > 0) {
         lines.push("");
         lines.push("Issues:");

package/dist/input/input-resolver.js

@@ -173,7 +173,7 @@ export async function resolveActionInput(options) {
     if (hasFileJson)
         modeCount++;
     if (modeCount > 1) {
-        const err = inputConflict("Input options conflict: flatArgs, input, and inputFile are mutually exclusive", {
+        const err = inputConflict("Input options conflict: flat arguments (-- key=val), inline JSON (-i/--input), and file (-f/--input-file) are mutually exclusive. Specify only one input mode.", {
             reason: "MULTIPLE_INPUT_MODES",
             hasFlatArgs: effectiveFlat,
             hasInput: hasInlineJson,

package/dist/invocation/policy.js

@@ -93,6 +93,7 @@ export class InvocationPolicy {
             ? graph.canCascadeCall(caller.packageId, caller.actionId, target.packageId, target.actionId)
             : usesList.some((u) => isUsesDeclared(u, target.packageId, target.actionId));
         if (!isAllowed) {
+            const hint = `Hint: Add '${targetRef}' to the 'uses' array of action '${caller.actionId}' in actiondock.json, then run 'ad validate'.`;
             return {
                 code: UNDECLARED_ACTION_DEPENDENCY,
                 message: `Undeclared cross-package dependency: Action '${caller.packageId}/${caller.actionId}' does not declare dependency on '${targetRef}' in 'uses'`,
@@ -100,6 +101,7 @@ export class InvocationPolicy {
                     caller: `${caller.packageId}/${caller.actionId}`,
                     target: targetRef,
                     declaredUses: usesList,
+                    hint,
                 },
             };
         }

package/dist/ipc/host.js

@@ -20,6 +20,7 @@ const IPC_METHOD_HANDLERS = {
     getRun: async (service, a) => service.runs.get(a[0]),
     cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
     clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
+    cleanExpiredRuns: async (service, a) => service.runs.cleanExpired ? await service.runs.cleanExpired(a[0]) : 0,
     getConfig: async (service, a) => service.management?.config.get(a[0], a[1]),
     setConfig: async (service, a) => service.management?.config.set(a[0], a[1], a[2]),
     deleteConfig: async (service, a) => service.management?.config.delete(a[0], a[1]),

package/dist/ipc/service.js

@@ -184,6 +184,9 @@ export class IpcActionDockService {
             async clear(opts) {
                 return forward("clearRuns", [opts]);
             },
+            async cleanExpired(policy) {
+                return forward("cleanExpiredRuns", [policy]);
+            },
         };
         if (options.enableManagement !== false) {
             this.management = {

package/dist/package/runtime.d.ts

@@ -97,7 +97,10 @@ export declare class DefaultPackageRuntime implements HostManagedPackageRuntime
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    cleanExpiredRuns(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     listStateEntries(options?: any): Promise<import("../storage/types.js").StateEntry[]>;
     close(options?: {
         graceMs?: number;

package/dist/package/runtime.js

@@ -581,8 +581,16 @@ export class DefaultPackageRuntime {
         return this.storage.clearRuns({
             actionId: options?.actionId,
             status: options?.status,
+            olderThanMs: options?.olderThanMs,
+            keep: options?.keep,
         });
     }
+    async cleanExpiredRuns(policy) {
+        if (typeof this.storage.cleanExpiredRuns === "function") {
+            return this.storage.cleanExpiredRuns(policy);
+        }
+        return 0;
+    }
     async listStateEntries(options) {
         if (typeof this.storage.listStateEntries === "function") {
             return this.storage.listStateEntries(options);

package/dist/package/types.d.ts

@@ -268,7 +268,11 @@ export interface PackageRuntime {
     clearRuns(options?: {
         actionId?: string;
         status?: string;
+        olderThanMs?: number;
+        keep?: number;
     }): Promise<number>;
+    /** 按保留策略清理过期及超额的终态运行记录（基于时间与数量策略） */
+    cleanExpiredRuns?(policy?: import("../storage/types.js").RunsRetentionPolicy): Promise<number>;
     /** 订阅指定运行的事件流 */
     events(runId: string, options?: {
         after?: number | string;

package/dist/platform/node.js

@@ -64,6 +64,7 @@ export function createNodePlatform(options = {}) {
                 clock,
                 driver: createDriver(dbPath),
                 recoverOrphans: opts?.recoverOrphans === true,
+                retentionPolicy: opts?.retentionPolicy,
             });
         },
         createGlobalStorage(opts) {

package/dist/platform/types.d.ts

@@ -1,7 +1,7 @@
 import type { ProcessAPI } from "@actiondock/sdk";
 import type { Clock } from "../runtime/clock.js";
 import type { ModuleLoader } from "../runtime/module-loader.js";
-import type { RuntimeStorage } from "../storage/types.js";
+import type { RunsRetentionPolicy, RuntimeStorage } from "../storage/types.js";
 /**
  * 文件元数据信息契约。
  */
@@ -58,6 +58,8 @@ export interface StorageFactoryOptions {
      * 默认 false（旁观查询打开，不触碰在途记录），供 CLI 查询命令与执行宿主并发共存。
      */
     recoverOrphans?: boolean;
+    /** 运行记录保留策略配置 */
+    retentionPolicy?: RunsRetentionPolicy;
 }
 /**
  * 跨运行时全局存储工厂配置选项。

package/dist/profile/client-runs.d.ts

@@ -30,13 +30,22 @@ export declare function fetchRemoteRuns(serverUrl: string, token?: string, optio
     items: RunRecord[];
 }>;
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export declare function clearRemoteRuns(serverUrl: string, token?: string, options?: {
     packageId?: string;
     actionId?: string;
     status?: string;
+    olderThanMs?: number;
+    keep?: number;
 } & RemoteClientRequestOptions): Promise<{
     ok: boolean;
     clearedCount: number;
 }>;
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export declare function cleanExpiredRemoteRuns(serverUrl: string, token?: string, options?: import("../storage/types.js").RunsRetentionPolicy & RemoteClientRequestOptions): Promise<{
+    ok: boolean;
+    cleanedCount: number;
+}>;

package/dist/profile/client-runs.js

@@ -44,7 +44,7 @@ export async function fetchRemoteRuns(serverUrl, token, options) {
     });
 }
 /**
- * 清空远端运行记录（可按包、Action、状态过滤清除范围）。
+ * 清空远端运行记录（可按包、Action、状态、保留时长、保留数量过滤清除范围）。
  */
 export async function clearRemoteRuns(serverUrl, token, options) {
     return fetchRemoteJson(serverUrl, "/api/v2/runs/clear", token, {
@@ -56,3 +56,16 @@ export async function clearRemoteRuns(serverUrl, token, options) {
         dispatcher: options?.dispatcher,
     });
 }
+/**
+ * 按保留策略清理远端过期及超额运行记录。
+ */
+export async function cleanExpiredRemoteRuns(serverUrl, token, options) {
+    return fetchRemoteJson(serverUrl, "/api/v2/runs/clean-expired", token, {
+        method: "POST",
+        body: options || {},
+        errorPrefix: "Failed to clean expired remote runs",
+        allowInsecureHttp: options?.allowInsecureHttp,
+        insecure: options?.insecure,
+        dispatcher: options?.dispatcher,
+    });
+}

package/dist/profile/client.d.ts

@@ -21,6 +21,6 @@ export { checkRemoteHealth } from "./client-health.js";
 export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./client-actions.js";
 export type { RemoteExecuteOptions, RemoteExecutionResult } from "./client-actions.js";
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./client-config.js";

package/dist/profile/client.js

@@ -24,7 +24,7 @@ export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRe
 // Playbook 规程查询
 export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./client-playbooks.js";
 // 运行记录管理
-export { cancelRemoteRun, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
+export { cancelRemoteRun, clearRemoteRuns, cleanExpiredRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./client-runs.js";
 // 状态存储管理
 export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./client-state.js";
 // 配置管理

package/dist/project/index.d.ts

@@ -10,7 +10,7 @@ export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, type TraverseDirectoryEntry, type TraverseDirectoryOptions, } from "../utils/index.js";
 export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
-export { resolveActionInput, buildActionInputAdvice, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
+export { resolveActionInput, buildActionInputAdvice, formatActionDetail, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
 export { validateActionInputValue } from "../json/value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";

package/dist/project/index.js

@@ -11,7 +11,7 @@ export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDurat
 export { isSecretConfigKey, maskSecretValue, sanitizeConfigDefinitions, } from "../storage/mask.js";
 export { runDoctorChecks, } from "../doctor/doctor.js";
 // 动作入参解析、校验与格式化（含 BOM 剥离与标准输入有界读取的单一事实源转引）
-export { resolveActionInput, buildActionInputAdvice, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
+export { resolveActionInput, buildActionInputAdvice, formatActionDetail, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
 export { validateActionInputValue } from "../json/value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";

package/dist/project/init.js

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

package/dist/project/loader.js

@@ -214,7 +214,7 @@ export async function loadActions(projectRoot, _actionsDir = "actions", options
                     entryPath,
                     rootCause: msg,
                     hint: isMissingModuleError(msg)
-                        ? `项目依赖缺失，请在 '${projectRoot}' 目录下运行 npm install 安装依赖。`
+                        ? `项目依赖缺失，请在 '${projectRoot}' 目录下运行 'npm install --omit=dev' 安装依赖后再试。`
                         : undefined,
                 };
                 throw error;