@actiondock/core 2.9.1 → 2.11.0

package/dist/{profile/client-transport.js → client/transport.js}

@@ -1,13 +1,59 @@
-import { isLoopbackHost } from "../utils/net.js";
-import { normalizeServerUrl } from "./manager.js";
-import { getInsecureDispatcher } from "../server/dispatcher.js";
-import { ActionDockError, INSECURE_TRANSPORT, INVALID_ARGUMENT } from "../errors.js";
+import { isLoopbackHost } from "../utils/index.js";
+import { getInsecureDispatcher } from "./dispatcher.js";
+import { ActionDockError, INSECURE_TRANSPORT, INVALID_ARGUMENT, NOT_FOUND, REMOTE_REQUEST_FAILED, UNAUTHORIZED } from "../errors.js";
+/**
+ * 格式化并规范化 Server URL 地址（若未指定协议，本地回环地址默认使用 http://，非本地回环地址默认使用 https://，并移除末尾斜杠）。
+ */
+export function normalizeServerUrl(url) {
+    let cleaned = url.trim().replace(/\/+$/, "");
+    if (!cleaned || cleaned === "local") {
+        return cleaned;
+    }
+    if (!/^https?:\/\//i.test(cleaned)) {
+        let hostname = cleaned;
+        const slashIdx = hostname.indexOf("/");
+        if (slashIdx !== -1) {
+            hostname = hostname.slice(0, slashIdx);
+        }
+        if (hostname.startsWith("[")) {
+            const endBracket = hostname.indexOf("]");
+            if (endBracket !== -1) {
+                hostname = hostname.slice(1, endBracket);
+            }
+        }
+        else {
+            const colonIdx = hostname.indexOf(":");
+            if (colonIdx !== -1) {
+                hostname = hostname.slice(0, colonIdx);
+            }
+        }
+        const isLoopback = isLoopbackHost(hostname);
+        cleaned = `${isLoopback ? "http" : "https"}://${cleaned}`;
+    }
+    return cleaned;
+}
+/**
+ * 脱敏 URL：移除 userinfo 凭据与查询串后再返回；仅保留协议、主机与路径。
+ */
+function redactUrl(url) {
+    let candidate = url;
+    try {
+        const u = new URL(candidate);
+        u.username = "";
+        u.password = "";
+        u.search = "";
+        return u.toString();
+    }
+    catch {
+        candidate = candidate.replace(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\/@]+@/, "$1");
+        return candidate.length > 128 ? `${candidate.slice(0, 128)}...` : candidate;
+    }
+}
 /**
  * 校验在携带认证 Token 时传输层协议与目标地址是否安全。
  * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
  * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免明文限制。
- * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT，
- * 杜绝携凭据请求发往不可控的畸形地址。
+ * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT。
  */
 export function assertSecureTransport(serverUrl, token, options) {
     if (!token || !token.trim()) {
@@ -23,9 +69,6 @@ export function assertSecureTransport(serverUrl, token, options) {
                 process.env?.ACTIONDOCK_INSECURE === "true" ||
                 process.env?.ACTIONDOCK_INSECURE === "1"));
     const base = normalizeServerUrl(serverUrl);
-    // 目标地址可解析性前置校验（fail-closed）：携带 token 时若目标 URL 无法解析，
-    // 严禁继续放行——后续请求会携凭据发往不可控的畸形目标。错误信息仅携带
-    // 脱敏地址与解析原因。allow 豁免仅作用于明文传输策略，不豁免地址合法性。
     if (base.startsWith("http://") || base.startsWith("https://")) {
         let parsed;
         try {
@@ -35,31 +78,10 @@ export function assertSecureTransport(serverUrl, token, options) {
             const reason = err instanceof Error ? err.message : String(err);
             throw new ActionDockError(INVALID_ARGUMENT, `Invalid server URL '${redactUrl(base)}' with authentication token: URL parse failed (${reason}). Fix the profile server URL before sending credentials.`);
         }
-        // 明文传输策略：仅非回环明文 http 需要豁免，https 不受限制
         if (!allow && base.startsWith("http://") && !isLoopbackHost(parsed.hostname)) {
             throw new ActionDockError(INSECURE_TRANSPORT, `Insecure HTTP connection with authentication token to non-loopback host '${parsed.hostname}' is prohibited. Use HTTPS or pass --allow-insecure-http to override.`);
         }
     }
-    // 非 http/https 协议形态（如 local）：交给后续请求层处理，此处无从校验
-}
-/**
- * 脱敏 URL：移除 userinfo 凭据与查询串后再返回；仅保留协议、主机与路径。
- */
-function redactUrl(url) {
-    let candidate = url;
-    try {
-        const u = new URL(candidate);
-        u.username = "";
-        u.password = "";
-        u.search = "";
-        return u.toString();
-    }
-    catch {
-        // 解析失败的畸形地址：以正则剥离 userinfo 形态后截断长度，
-        // 避免原始串携带敏感片段外泄到错误信息与日志
-        candidate = candidate.replace(/^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\/@]+@/, "$1");
-        return candidate.length > 128 ? `${candidate.slice(0, 128)}...` : candidate;
-    }
 }
 /**
  * 构造携带鉴权信息的标准请求头。
@@ -75,10 +97,6 @@ export function buildHeaders(token) {
 }
 /**
  * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
- *
- * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
- * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验与
- * insecure dispatcher 注入均在此统一处理。
  */
 export function createRemoteFetch(serverUrl, token, options) {
     assertSecureTransport(serverUrl, token, {
@@ -115,9 +133,81 @@ export function createRemoteFetch(serverUrl, token, options) {
     };
 }
 /**
- * 远端请求单一入口：执行目标协议路由请求。
+ * 远端请求底层入口：执行目标协议路由请求。
  */
 export async function fetchRemoteRoute(base, path, init) {
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
     return fetch(`${base}${normalizedPath}`, init);
 }
+/**
+ * 执行远端请求并将响应解析为 JSON，统一处理错误信封透传。
+ */
+export async function fetchRemoteJson(serverUrl, path, token, options = {}) {
+    const remoteFetch = createRemoteFetch(serverUrl, token, {
+        allowInsecureHttp: options.allowInsecureHttp,
+        insecure: options.insecure,
+        dispatcher: options.dispatcher,
+    });
+    const res = await remoteFetch(path, {
+        method: options.method,
+        body: options.body,
+        signal: options.signal,
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || (options.method === "POST" && data && data.ok === false)) {
+        const errorPrefix = options.errorPrefix || "Remote request failed";
+        const msg = data?.error?.message || `${errorPrefix} (${res.status}): ${res.statusText}`;
+        const code = data?.error?.code ||
+            (res.status === 404 ? NOT_FOUND : res.status === 401 ? UNAUTHORIZED : REMOTE_REQUEST_FAILED);
+        const details = data?.error?.details ?? data?.error;
+        const err = new ActionDockError(code, msg, details, res.status);
+        err.errorData = data?.error;
+        throw err;
+    }
+    return data;
+}
+/**
+ * 由可选参数字典构造查询串（无参数时返回空串）。
+ * 过滤 undefined 与空串。
+ */
+export function buildQueryString(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === "") {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined && item !== "") {
+                    search.append(key, String(item));
+                }
+            }
+            continue;
+        }
+        search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+/**
+ * 构造保留空串语义的查询串：仅跳过 undefined，保留空串。
+ */
+export function buildQueryStringPreservingEmpty(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item !== undefined) {
+                    search.append(key, String(item));
+                }
+            }
+            continue;
+        }
+        search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}

package/dist/doctor/checks/index.d.ts

@@ -1,4 +1,4 @@
-export { checkBunRuntime, checkCliExecutable, checkNodeRuntime } from "./runtime.js";
+export { checkCliExecutable, checkNodeRuntime } from "./runtime.js";
 export { checkGlobalStorage } from "./storage.js";
 export { checkGlobalRegistry, checkLinkedPackageDependencies, checkUsesClosure, } from "./registry.js";
 export { locateProject } from "./project-locate.js";

package/dist/doctor/checks/index.js

@@ -1,4 +1,4 @@
-export { checkBunRuntime, checkCliExecutable, checkNodeRuntime } from "./runtime.js";
+export { checkCliExecutable, checkNodeRuntime } from "./runtime.js";
 export { checkGlobalStorage } from "./storage.js";
 export { checkGlobalRegistry, checkLinkedPackageDependencies, checkUsesClosure, } from "./registry.js";
 export { locateProject } from "./project-locate.js";

package/dist/doctor/checks/project.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { discoverActionFiles, loadActions, loadPlaybooks, loadProjectConfig } from "../../project/loader.js";
 import { loadManifest, MANIFEST_FILE_NAME } from "../../project/manifest.js";
@@ -45,22 +45,21 @@ function checkProjectSdk(scope) {
     }
 }
 /**
- * 检查工程运行时数据库可写性。
- *
- * 探测写入独立临时数据库文件，避免对生产运行库产生写副作用：
- * 体检是诊断行为，不得在真实库上执行写加删事务引入额外写竞争。
+ * 检查工程运行时数据库可写性（纯只读检查，无写副作用）。
  */
-async function checkProjectStorage(scope) {
+function checkProjectStorage(scope) {
     const { ctx, config } = scope;
     const dbPath = resolveDatabasePath(config.id, { customHome: ctx.customHome });
     const probeDir = dirname(dbPath);
-    // 探测库：与生产库同目录但独立命名，结束后整体删除，不留探测残留
-    const probeId = `doctor.probe.${Date.now()}`;
-    const probePkgDir = dirname(resolveDatabasePath(probeId, { customHome: ctx.customHome }));
-    const probeStorage = createStorage(probeId, { customHome: ctx.customHome });
     try {
-        await probeStorage.setConfig("probe", "ok");
-        probeStorage.close();
+        let checkDir = probeDir;
+        while (!existsSync(checkDir)) {
+            const parent = dirname(checkDir);
+            if (parent === checkDir)
+                break;
+            checkDir = parent;
+        }
+        accessSync(checkDir, constants.W_OK);
         ctx.checks.push({
             id: "project.storage",
             category: "project",
@@ -70,10 +69,6 @@ async function checkProjectStorage(scope) {
         });
     }
     catch (err) {
-        try {
-            probeStorage.close();
-        }
-        catch { }
         ctx.checks.push({
             id: "project.storage",
             category: "project",
@@ -83,15 +78,6 @@ async function checkProjectStorage(scope) {
             fix: `Check write permissions for '${probeDir}'`,
         });
     }
-    finally {
-        // 清理探测库目录（含 WAL/SHM 侧车文件）
-        try {
-            if (existsSync(probePkgDir)) {
-                rmSync(probePkgDir, { recursive: true, force: true });
-            }
-        }
-        catch { }
-    }
 }
 /**
  * 检查工程 Actions 可加载性与数量。
@@ -115,7 +101,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 +141,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 +160,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,30 +170,17 @@ 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 {
-                const manifestStat = statSync(manifestPath);
-                const newerFiles = actionFiles.filter((f) => statSync(f).mtimeMs > manifestStat.mtimeMs + 2000);
-                if (newerFiles.length > 0) {
-                    ctx.checks.push({
-                        id: "project.manifest",
-                        category: "project",
-                        name: "Action Manifest",
-                        status: "ok",
-                        message: `Manifest valid (Note: ${newerFiles.length} action file(s) modified after manifest; run 'ad validate' if definitions changed)`,
-                    });
-                }
-                else {
-                    ctx.checks.push({
-                        id: "project.manifest",
-                        category: "project",
-                        name: "Action Manifest",
-                        status: "ok",
-                        message: "Manifest synchronized with action files",
-                    });
-                }
+                ctx.checks.push({
+                    id: "project.manifest",
+                    category: "project",
+                    name: "Action Manifest",
+                    status: "ok",
+                    message: "Manifest synchronized with action files",
+                });
             }
         }
     }
@@ -222,14 +195,12 @@ function checkProjectManifest(scope) {
     }
 }
 /**
- * 检查 files 声明边界与源码目录未声明引用。
+ * 检查 files 声明边界。
  */
 function checkProjectFiles(scope) {
     const { ctx, projectRoot, config } = scope;
     try {
         const declaredFiles = config.files || [];
-        const hasSrc = existsSync(join(projectRoot, "src"));
-        const hasLib = existsSync(join(projectRoot, "lib"));
         if (declaredFiles.length > 0) {
             const missingDeclared = declaredFiles.filter((f) => !existsSync(join(projectRoot, f)));
             if (missingDeclared.length > 0) {
@@ -252,45 +223,6 @@ function checkProjectFiles(scope) {
                 });
             }
         }
-        else if (hasSrc || hasLib) {
-            const actionFiles = discoverActionFiles(projectRoot, config.actionsDir || "actions");
-            let hasReferenceToSrcOrLib = false;
-            const unreadableFiles = [];
-            for (const actFile of actionFiles) {
-                try {
-                    const src = readFileSync(actFile, "utf-8");
-                    if (/['"](?:\.\.\/(?:src|lib)|\.\/(?:src|lib))[^'"]*['"]/.test(src)) {
-                        hasReferenceToSrcOrLib = true;
-                        break;
-                    }
-                }
-                catch (err) {
-                    // 单文件读取失败：计入告警名单，边界检测结论不再基于无声缺失的数据
-                    unreadableFiles.push(`${actFile} (${err?.message || String(err)})`);
-                }
-            }
-            if (hasReferenceToSrcOrLib) {
-                ctx.checks.push({
-                    id: "project.files",
-                    category: "project",
-                    name: "Declared Files",
-                    status: "error",
-                    message: `Actions import modules from ${hasSrc ? "'src/'" : ""}${hasSrc && hasLib ? " and " : ""}${hasLib ? "'lib/'" : ""}, but 'files' is not declared in ${MANIFEST_FILE_NAME}`,
-                    fix: `Add "files": [${hasSrc ? '"src"' : ""}${hasSrc && hasLib ? ', "lib"' : hasLib && !hasSrc ? '"lib"' : ""}] to ${MANIFEST_FILE_NAME}`,
-                });
-            }
-            else {
-                ctx.checks.push({
-                    id: "project.files",
-                    category: "project",
-                    name: "Declared Files",
-                    status: unreadableFiles.length > 0 ? "warn" : "ok",
-                    message: unreadableFiles.length > 0
-                        ? `Project source directories clean, but ${unreadableFiles.length} action file(s) unreadable during boundary scan: ${unreadableFiles.join(", ")}`
-                        : `Project source directories clean (no undeclared references to ${hasSrc ? "src/" : "lib/"})`,
-                });
-            }
-        }
     }
     catch (err) {
         // 文件边界检测整体失败：转为 error 检查项呈现在报告中，而非无声跳过
@@ -299,7 +231,7 @@ function checkProjectFiles(scope) {
             category: "project",
             name: "Declared Files",
             status: "error",
-            message: `Failed to inspect declared files and source boundaries: ${err?.message || String(err)}`,
+            message: `Failed to inspect declared files: ${err?.message || String(err)}`,
         });
     }
 }

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/doctor/checks/runtime.d.ts

@@ -3,10 +3,6 @@ import type { DoctorCheck } from "../context.js";
  * 检查 Node.js 运行时版本是否满足最低要求（>= 24.12.0）。
  */
 export declare const checkNodeRuntime: DoctorCheck;
-/**
- * 检查 Bun 运行时可用性（可选环境，用于跨运行时兼容性测试）。
- */
-export declare const checkBunRuntime: DoctorCheck;
 /**
  * 检查 CLI 可执行文件（ad）是否在 PATH 中。
  */

package/dist/doctor/checks/runtime.js

@@ -65,34 +65,6 @@ export const checkNodeRuntime = {
         }
     },
 };
-/**
- * 检查 Bun 运行时可用性（可选环境，用于跨运行时兼容性测试）。
- */
-export const checkBunRuntime = {
-    id: "runtime.bun",
-    run: (ctx) => {
-        const bunVersion = (typeof globalThis.Bun !== "undefined" && globalThis.Bun.version) ||
-            process.versions.bun;
-        if (bunVersion) {
-            ctx.checks.push({
-                id: "runtime.bun",
-                category: "runtime",
-                name: "Bun Runtime",
-                status: "ok",
-                message: `v${bunVersion} (available for cross-environment testing)`,
-            });
-        }
-        else {
-            ctx.checks.push({
-                id: "runtime.bun",
-                category: "runtime",
-                name: "Bun Runtime",
-                status: "ok",
-                message: "Bun runtime not detected (optional, used for cross-environment compatibility testing)",
-            });
-        }
-    },
-};
 /**
  * 检查 CLI 可执行文件（ad）是否在 PATH 中。
  */

package/dist/doctor/doctor.js

@@ -1,12 +1,11 @@
 import { createDoctorCheckContext } from "./context.js";
-import { checkBunRuntime, checkCliExecutable, checkGlobalRegistry, checkGlobalStorage, checkLinkedPackageDependencies, checkNodeRuntime, checkProject, checkUsesClosure, locateProject, } from "./checks/index.js";
+import { checkCliExecutable, checkGlobalRegistry, checkGlobalStorage, checkLinkedPackageDependencies, checkNodeRuntime, checkProject, checkUsesClosure, locateProject, } from "./checks/index.js";
 /**
  * 检查注册表：按诊断执行顺序排列的检查阶段。
  * 运行时 → 存储 → 注册表 → 工程定位 → 工程级详情，与报告展示顺序一一对应。
  */
 const doctorCheckRegistry = [
     checkNodeRuntime,
-    checkBunRuntime,
     checkCliExecutable,
     checkGlobalStorage,
     checkGlobalRegistry,

package/dist/errors.d.ts

@@ -75,8 +75,6 @@ export declare const STORAGE_BUSY = "STORAGE_BUSY";
 export declare const PROJECT_BUSY = "PROJECT_BUSY";
 /** 工程存在未恢复的崩溃事务，需要执行恢复流程 */
 export declare const PROJECT_RECOVERY_REQUIRED = "PROJECT_RECOVERY_REQUIRED";
-/** SQLite 工作线程已退出 */
-export declare const STORAGE_WORKER_EXITED = "STORAGE_WORKER_EXITED";
 /** 事件订阅队列积压超过背压上限 */
 export declare const EVENT_BACKPRESSURE_LIMIT = "EVENT_BACKPRESSURE_LIMIT";
 export declare const EVENT_CURSOR_EXPIRED = "EVENT_CURSOR_EXPIRED";
@@ -254,6 +252,58 @@ export declare const AMBIGUOUS_STATE_KEY = "AMBIGUOUS_STATE_KEY";
 export declare const RUN_NOT_FOUND = "RUN_NOT_FOUND";
 /** 目标运行已进入终态不可操作 */
 export declare const RUN_ALREADY_FINISHED = "RUN_ALREADY_FINISHED";
+/** 目标环境配置 Profile 未找到 */
+export declare const PROFILE_NOT_FOUND = "PROFILE_NOT_FOUND";
+/** 锁文件读取失败 */
+export declare const LOCKFILE_READ_FAILED = "LOCKFILE_READ_FAILED";
+/** 锁文件内容损坏或存在重复键 */
+export declare const LOCKFILE_CORRUPTED = "LOCKFILE_CORRUPTED";
+/** 锁文件结构或格式非法 */
+export declare const LOCKFILE_INVALID = "LOCKFILE_INVALID";
+/** 不受支持的锁文件版本 */
+export declare const UNSUPPORTED_LOCKFILE_VERSION = "UNSUPPORTED_LOCKFILE_VERSION";
+/** 项目清单读取失败 */
+export declare const MANIFEST_READ_FAILED = "MANIFEST_READ_FAILED";
+/** 项目清单 JSON 解析失败或内容损坏 */
+export declare const MANIFEST_CORRUPTED = "MANIFEST_CORRUPTED";
+/** 项目清单结构或格式非法 */
+export declare const MANIFEST_INVALID = "MANIFEST_INVALID";
+/** 不受支持的项目清单 Schema 版本 */
+export declare const UNSUPPORTED_MANIFEST_SCHEMA = "UNSUPPORTED_MANIFEST_SCHEMA";
+/** 项目清单文件 actiondock.json 未找到 */
+export declare const MANIFEST_NOT_FOUND = "MANIFEST_NOT_FOUND";
+/** 清单确定性摘要与锁文件记录不一致 */
+export declare const MANIFEST_DIGEST_MISMATCH = "MANIFEST_DIGEST_MISMATCH";
+/** 全局注册表文件损坏或格式非法 */
+export declare const REGISTRY_CORRUPTED = "REGISTRY_CORRUPTED";
+/** 底层 SQLite 存储不支持异步事务 */
+export declare const ASYNC_TRANSACTION_UNSUPPORTED = "ASYNC_TRANSACTION_UNSUPPORTED";
+/** 底层存储或数据库连接已关闭 */
+export declare const STORAGE_CLOSED = "STORAGE_CLOSED";
+/** 多个不同物理路径声明了相同的包标识冲突 */
+export declare const PACKAGE_ID_CONFLICT = "PACKAGE_ID_CONFLICT";
+/** 路径参数非法（含空字节或非字符串） */
+export declare const INVALID_PATH = "INVALID_PATH";
+/** 存储数据目录初始化失败 */
+export declare const STORAGE_INIT_FAILED = "STORAGE_INIT_FAILED";
+/** 对象处于非法状态或缺少必要内部资源 */
+export declare const INVALID_STATE = "INVALID_STATE";
+/** 目标进程未找到或不存在 */
+export declare const PROCESS_NOT_FOUND = "PROCESS_NOT_FOUND";
+/** 模块标识符解析失败 */
+export declare const MODULE_RESOLVE_FAILED = "MODULE_RESOLVE_FAILED";
+/** 执行并发达到上限 */
+export declare const EXECUTION_CONCURRENCY_LIMIT = "EXECUTION_CONCURRENCY_LIMIT";
+/** 项目配置文件 actiondock.json 未找到 */
+export declare const PROJECT_CONFIG_NOT_FOUND = "PROJECT_CONFIG_NOT_FOUND";
+/** 项目清单加载失败 */
+export declare const MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED";
+/** 动作标识符不符合命名规范 */
+export declare const INVALID_ACTION_ID = "INVALID_ACTION_ID";
+/** 规程标识符不符合命名规范 */
+export declare const INVALID_PLAYBOOK_ID = "INVALID_PLAYBOOK_ID";
+/** 项目根目录未找到或不是合法的 ActionDock 包 */
+export declare const PROJECT_ROOT_NOT_FOUND = "PROJECT_ROOT_NOT_FOUND";
 /**
  * ActionDock 统一基础结构化异常类。
  * 全仓各领域异常与跨层透传异常的统一事实源基类。
@@ -262,12 +312,43 @@ 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;
 /**
  * 集中定义的标准结构化错误码联合类型。
  */
-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 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 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 | typeof PROFILE_NOT_FOUND | typeof LOCKFILE_READ_FAILED | typeof LOCKFILE_CORRUPTED | typeof LOCKFILE_INVALID | typeof UNSUPPORTED_LOCKFILE_VERSION | typeof MANIFEST_READ_FAILED | typeof MANIFEST_CORRUPTED | typeof MANIFEST_INVALID | typeof UNSUPPORTED_MANIFEST_SCHEMA | typeof MANIFEST_NOT_FOUND | typeof MANIFEST_DIGEST_MISMATCH | typeof REGISTRY_CORRUPTED | typeof ASYNC_TRANSACTION_UNSUPPORTED | typeof STORAGE_CLOSED | typeof PACKAGE_ID_CONFLICT | typeof INVALID_PATH | typeof STORAGE_INIT_FAILED | typeof INVALID_STATE | typeof PROCESS_NOT_FOUND | typeof MODULE_RESOLVE_FAILED | typeof EXECUTION_CONCURRENCY_LIMIT | typeof PROJECT_CONFIG_NOT_FOUND | typeof MANIFEST_LOAD_FAILED | typeof INVALID_ACTION_ID | typeof INVALID_PLAYBOOK_ID | typeof PROJECT_ROOT_NOT_FOUND;
 /** 全仓统一错误码类型别名 */
 export type ActionDockErrorCode = ErrorCode;
 /**