@actiondock/core 2.9.1 → 2.10.0

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.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);
                 }
             }
             // 调用嵌套深度限制校验

package/dist/index.d.ts

@@ -20,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

@@ -18,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/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.1",
+            "@actiondock/sdk": "^2.10.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.9.1",
+            "@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;

package/dist/runtime/standalone.js

@@ -1,7 +1,7 @@
 import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../filter/index.js";
 import { createActionDock } from "../service/factory.js";
-import { STANDALONE_ASYNC_UNSUPPORTED } from "../errors.js";
+import { STANDALONE_ASYNC_UNSUPPORTED, resolveExecutionHint, } from "../errors.js";
 import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
 import { validateActionInputValue } from "../json/value-validator.js";
 import { normalizeActionCollection } from "./action-collection.js";
@@ -62,6 +62,10 @@ export class StandaloneDispatcher {
     emitError(isJson, code, message, exitCode, options) {
         if (isJson) {
             const details = options?.details;
+            const hint = options?.hint ??
+                (details && typeof details === "object" && typeof details.hint === "string"
+                    ? details.hint
+                    : undefined);
             this.writeOut(JSON.stringify({
                 ok: false,
                 error: {
@@ -69,6 +73,7 @@ export class StandaloneDispatcher {
                     message,
                     ...(details !== undefined ? { details } : {}),
                 },
+                ...(hint !== undefined ? { hint } : {}),
             }, null, 2));
         }
         else {
@@ -249,8 +254,11 @@ export class StandaloneDispatcher {
             description: a.description || "",
         }));
         const filterRes = filterWithFallbackInfo(list, effectiveIntent, [(a) => a.id, (a) => a.description], !noFallback);
+        const hints = [
+            "Tip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.",
+        ];
         if (isJson) {
-            this.writeOut(JSON.stringify(filterRes.items, null, 2));
+            this.writeOut(JSON.stringify({ items: filterRes.items, hints }, null, 2));
         }
         else {
             let text = `Actions in ${this.options.packageId} (v${this.options.version}):\n\n`;
@@ -272,7 +280,11 @@ export class StandaloneDispatcher {
             action = await service.discovery.describeAction(id);
         }
         catch {
-            return this.emitError(isJson, "INVALID_ARGUMENT", `Action '${id}' not found`, ExitCode.INVALID_ARGUMENT);
+            const hint = "Tip: Run 'ad list' to discover available actions.";
+            return this.emitError(isJson, "INVALID_ARGUMENT", `Action '${id}' not found`, ExitCode.INVALID_ARGUMENT, {
+                textMessage: `Error: Action '${id}' not found\n${hint}`,
+                hint,
+            });
         }
         const payload = buildActionDescribePayload(action, {
             packageId: this.options.packageId,
@@ -294,8 +306,12 @@ export class StandaloneDispatcher {
         let inputStr;
         let inputFile;
         let timeoutMs;
+        const recognizedFlags = new Set(["--json", "--async"]);
         for (let i = 0; i < subArgs.length; i++) {
             const arg = subArgs[i];
+            if (arg === id || recognizedFlags.has(arg)) {
+                continue;
+            }
             if (arg === "--timeout" && i + 1 < subArgs.length) {
                 try {
                     timeoutMs = parseDuration(subArgs[++i]);
@@ -318,12 +334,31 @@ export class StandaloneDispatcher {
             else if (arg.startsWith("--input=")) {
                 inputStr = arg.slice(8);
             }
+            else if (arg === "-i" && i + 1 < subArgs.length) {
+                inputStr = subArgs[++i];
+            }
+            else if (arg.startsWith("-i=")) {
+                inputStr = arg.slice(3);
+            }
             else if (arg === "--input-file" && i + 1 < subArgs.length) {
                 inputFile = subArgs[++i];
             }
             else if (arg.startsWith("--input-file=")) {
                 inputFile = arg.slice(13);
             }
+            else if (arg === "-f" && i + 1 < subArgs.length) {
+                inputFile = subArgs[++i];
+            }
+            else if (arg.startsWith("-f=")) {
+                inputFile = arg.slice(3);
+            }
+            else if (arg.startsWith("-")) {
+                const hint = "Hint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>.";
+                return this.emitError(isJson, "INVALID_ARGUMENT", `error: unknown option '${arg}'`, ExitCode.INVALID_ARGUMENT, {
+                    textMessage: `error: unknown option '${arg}'\n${hint}`,
+                    hint,
+                });
+            }
         }
         let input;
         try {
@@ -348,7 +383,14 @@ export class StandaloneDispatcher {
             timeoutMs,
         });
         if (isJson) {
-            this.writeOut(JSON.stringify(result, null, 2));
+            if (!result.ok) {
+                const hint = resolveExecutionHint(id, result.error);
+                const machineOutput = hint !== undefined ? { ...result, hint } : result;
+                this.writeOut(JSON.stringify(machineOutput, null, 2));
+            }
+            else {
+                this.writeOut(JSON.stringify(result, null, 2));
+            }
         }
         else {
             if (result.ok) {
@@ -428,6 +470,10 @@ export class StandaloneDispatcher {
                         ? result.error.details
                         : JSON.stringify(result.error.details, null, 2));
                 }
+                const hint = resolveExecutionHint(id, result.error);
+                if (hint) {
+                    this.writeErr(hint);
+                }
             }
         }
         return result.ok ? ExitCode.SUCCESS : ExitCode.FAILURE;

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export declare const ACTIONDOCK_VERSION = "2.9.1";
+export declare const ACTIONDOCK_VERSION = "2.10.0";

package/dist/version.js

@@ -1,4 +1,4 @@
 /**
  * ActionDock 核心版本号单一事实源。
  */
-export const ACTIONDOCK_VERSION = "2.9.1";
+export const ACTIONDOCK_VERSION = "2.10.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -66,7 +66,7 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/sdk": "^2.9.1",
+    "@actiondock/sdk": "^2.10.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "undici": "^7.29.1"