@actiondock/core 2.9.1 → 2.11.0

package/dist/project/digest.js

@@ -1,241 +1,103 @@
 import { createHash } from "node:crypto";
 /**
  * 解析 JSON 文本并在检测到重复键时抛出错误。
- * 遵循 RFC 8785 清单校验规范：解析阶段必须率先拦截并拒绝重复键。
+ * 遵循 RFC 8785 清单校验规范:解析阶段必须率先拦截并拒绝重复键。
+ *
+ * 实现策略:JSON.parse 主解析 + 轻量键名扫描器做重复键检测。
+ * 扫描器以状态机遍历原始文本,仅在对象键位置(冒号前的字符串字面量)记录键名,
+ * 同一对象层级内出现重复键名即抛错;字符串内部与转义字符不参与键名提取。
  */
 export function parseJsonWithoutDuplicates(jsonText) {
-    let pos = 0;
+    detectDuplicateKeys(jsonText);
+    return JSON.parse(jsonText);
+}
+/**
+ * 扫描 JSON 文本,检测同一对象层级内的重复键名。
+ *
+ * 状态机只关心「是否处于字符串内」与「对象层级」:
+ * - 遇到未转义引号时切换 inString 状态;
+ * - 字符串闭合后若紧邻(跳过空白)冒号,则该字符串是键:提取键名登记到当前层级;
+ * - 对象层级入栈出栈维护各自已见键集合。
+ */
+function detectDuplicateKeys(jsonText) {
     const len = jsonText.length;
-    function skipWhitespace() {
-        while (pos < len) {
-            const ch = jsonText.charCodeAt(pos);
-            if (ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d) {
-                pos++;
-            }
-            else {
-                break;
+    let pos = 0;
+    let inString = false;
+    let depth = -1;
+    // 每层对象的已见键集合;keyStartStack 记录每个未闭合字符串字面量的起点
+    const seenPerDepth = [];
+    const keyStartStack = [];
+    while (pos < len) {
+        const ch = jsonText[pos];
+        if (inString) {
+            if (ch === "\\") {
+                pos += 2;
+                continue;
             }
-        }
-    }
-    function parseString() {
-        if (jsonText[pos] !== '"') {
-            throw new SyntaxError(`Expected string at position ${pos}`);
-        }
-        const start = pos;
-        pos++; // 跳过开头的引号
-        let result = "";
-        while (pos < len) {
-            const ch = jsonText[pos];
             if (ch === '"') {
-                pos++; // 跳过结束的引号
-                return result;
-            }
-            if (ch === "\\") {
-                pos++;
-                if (pos >= len) {
-                    throw new SyntaxError(`Unterminated escape sequence in string at ${pos}`);
-                }
-                const esc = jsonText[pos];
-                if (esc === '"' || esc === "\\" || esc === "/") {
-                    result += esc;
-                    pos++;
-                }
-                else if (esc === "b") {
-                    result += "\b";
-                    pos++;
-                }
-                else if (esc === "f") {
-                    result += "\f";
-                    pos++;
+                inString = false;
+                const start = keyStartStack.pop();
+                // 判断该字符串是否为对象键:向后跳过空白,若紧邻冒号则为键
+                let look = pos + 1;
+                while (look < len && /\s/.test(jsonText[look]))
+                    look++;
+                if (start !== undefined && look < len && jsonText[look] === ":") {
+                    registerKey(jsonText, start, pos, seenPerDepth, depth);
                 }
-                else if (esc === "n") {
-                    result += "\n";
-                    pos++;
-                }
-                else if (esc === "r") {
-                    result += "\r";
-                    pos++;
-                }
-                else if (esc === "t") {
-                    result += "\t";
-                    pos++;
-                }
-                else if (esc === "u") {
-                    pos++;
-                    const hex = jsonText.slice(pos, pos + 4);
-                    if (hex.length < 4 || !/^[0-9a-fA-F]{4}$/.test(hex)) {
-                        throw new SyntaxError(`Invalid unicode escape sequence \\u${hex} at ${pos}`);
-                    }
-                    result += String.fromCharCode(parseInt(hex, 16));
-                    pos += 4;
-                }
-                else {
-                    throw new SyntaxError(`Invalid escape character '\\${esc}' at ${pos}`);
-                }
-            }
-            else {
-                result += ch;
-                pos++;
-            }
-        }
-        throw new SyntaxError(`Unterminated string starting at ${start}`);
-    }
-    function parseNumber() {
-        const start = pos;
-        if (jsonText[pos] === "-") {
-            pos++;
-        }
-        if (pos >= len) {
-            throw new SyntaxError(`Expected digits at position ${pos}`);
-        }
-        if (jsonText[pos] === "0") {
-            pos++;
-        }
-        else if (jsonText[pos] >= "1" && jsonText[pos] <= "9") {
-            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
-                pos++;
             }
-        }
-        else {
-            throw new SyntaxError(`Invalid number at position ${pos}`);
-        }
-        if (pos < len && jsonText[pos] === ".") {
             pos++;
-            if (pos >= len || jsonText[pos] < "0" || jsonText[pos] > "9") {
-                throw new SyntaxError(`Expected digit after decimal point at position ${pos}`);
-            }
-            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
-                pos++;
-            }
+            continue;
         }
-        if (pos < len && (jsonText[pos] === "e" || jsonText[pos] === "E")) {
+        if (ch === '"') {
+            inString = true;
+            keyStartStack.push(pos + 1);
             pos++;
-            if (pos < len && (jsonText[pos] === "+" || jsonText[pos] === "-")) {
-                pos++;
-            }
-            if (pos >= len || jsonText[pos] < "0" || jsonText[pos] > "9") {
-                throw new SyntaxError(`Expected digit after exponent at position ${pos}`);
-            }
-            while (pos < len && jsonText[pos] >= "0" && jsonText[pos] <= "9") {
-                pos++;
-            }
-        }
-        const numStr = jsonText.slice(start, pos);
-        const num = Number(numStr);
-        if (!Number.isFinite(num)) {
-            throw new SyntaxError(`Number out of range: ${numStr}`);
-        }
-        return num;
-    }
-    function parseObject() {
-        const obj = {};
-        const keys = new Set();
-        pos++; // 跳过 '{'
-        skipWhitespace();
-        if (pos < len && jsonText[pos] === "}") {
+            continue;
+        }
+        if (ch === "{") {
+            depth++;
+            if (seenPerDepth.length <= depth)
+                seenPerDepth.push(new Set());
+            else
+                seenPerDepth[depth] = new Set();
             pos++;
-            return obj;
+            continue;
         }
-        while (pos < len) {
-            skipWhitespace();
-            if (jsonText[pos] !== '"') {
-                throw new SyntaxError(`Expected string key in object at position ${pos}`);
-            }
-            const key = parseString();
-            if (keys.has(key)) {
-                throw new Error(`Duplicate key '${key}' detected in JSON`);
-            }
-            keys.add(key);
-            skipWhitespace();
-            if (pos >= len || jsonText[pos] !== ":") {
-                throw new SyntaxError(`Expected ':' after key '${key}' at position ${pos}`);
-            }
-            pos++; // 跳过 ':'
-            skipWhitespace();
-            const val = parseValue();
-            obj[key] = val;
-            skipWhitespace();
-            if (pos >= len) {
-                throw new SyntaxError("Unexpected end of JSON in object");
-            }
-            if (jsonText[pos] === ",") {
-                pos++;
-                skipWhitespace();
-            }
-            else if (jsonText[pos] === "}") {
-                pos++;
-                return obj;
-            }
-            else {
-                throw new SyntaxError(`Expected ',' or '}' in object at position ${pos}`);
-            }
-        }
-        throw new SyntaxError("Unterminated object in JSON");
-    }
-    function parseArray() {
-        const arr = [];
-        pos++; // 跳过 '['
-        skipWhitespace();
-        if (pos < len && jsonText[pos] === "]") {
+        if (ch === "}") {
+            depth--;
             pos++;
-            return arr;
+            continue;
         }
-        while (pos < len) {
-            skipWhitespace();
-            const val = parseValue();
-            arr.push(val);
-            skipWhitespace();
-            if (pos >= len) {
-                throw new SyntaxError("Unexpected end of JSON in array");
-            }
-            if (jsonText[pos] === ",") {
-                pos++;
-                skipWhitespace();
-            }
-            else if (jsonText[pos] === "]") {
-                pos++;
-                return arr;
-            }
-            else {
-                throw new SyntaxError(`Expected ',' or ']' in array at position ${pos}`);
-            }
-        }
-        throw new SyntaxError("Unterminated array in JSON");
+        pos++;
     }
-    function parseValue() {
-        skipWhitespace();
-        if (pos >= len) {
-            throw new SyntaxError("Unexpected end of JSON input");
-        }
-        const ch = jsonText[pos];
-        if (ch === "{")
-            return parseObject();
-        if (ch === "[")
-            return parseArray();
-        if (ch === '"')
-            return parseString();
-        if (ch === "-" || (ch >= "0" && ch <= "9"))
-            return parseNumber();
-        if (jsonText.startsWith("true", pos)) {
-            pos += 4;
-            return true;
-        }
-        if (jsonText.startsWith("false", pos)) {
-            pos += 5;
-            return false;
-        }
-        if (jsonText.startsWith("null", pos)) {
-            pos += 4;
-            return null;
-        }
-        throw new SyntaxError(`Unexpected token '${ch}' at position ${pos}`);
+}
+/**
+ * 登记一个对象键:回溯提取键名,在当前层级做重复检测。
+ */
+function registerKey(jsonText, start, quoteEndPos, seenPerDepth, depth) {
+    if (depth < 0)
+        return;
+    // quoteEndPos 是闭合引号的位置,键内容为 [start, quoteEndPos)
+    if (quoteEndPos <= start)
+        return;
+    const raw = jsonText.slice(start, quoteEndPos);
+    const key = unescapeJsonKey(raw);
+    const seen = seenPerDepth[depth];
+    if (seen.has(key)) {
+        throw new SyntaxError(`Duplicate key '${key}' in object at depth ${depth}`);
+    }
+    seen.add(key);
+}
+/**
+ * 反转义 JSON 键名字符串字面量内容。
+ */
+function unescapeJsonKey(raw) {
+    try {
+        return JSON.parse(`"${raw}"`);
     }
-    const result = parseValue();
-    skipWhitespace();
-    if (pos < len) {
-        throw new SyntaxError(`Unexpected trailing characters at position ${pos}`);
+    catch {
+        return raw;
     }
-    return result;
 }
 /**
  * 依据 RFC 8785 规范化 JSON 数据。
@@ -256,7 +118,7 @@ export function canonicalizeJson(value) {
     }
     if (type === "number") {
         if (!Number.isFinite(value)) {
-            throw new TypeError("RFC 8785 JSON 规范化拒绝非有限数值 (NaN 或 Infinity)");
+            throw new TypeError("RFC 8785 JSON canonicalization rejects non-finite numbers (NaN or Infinity)");
         }
         if (Object.is(value, -0) || value === 0) {
             return "0";

package/dist/project/index.d.ts

@@ -1,17 +1,16 @@
-export * from "./closure.js";
 export * from "./digest.js";
 export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
-export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isPidAlive, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
+export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 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 { validateActionInputValue } from "../json/value-validator.js";
+export { resolveActionInput, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, type ResolveActionInputOptions, type ReadStdinBoundedOptions, } from "../input/index.js";
+export { validateActionInputValue } from "../value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";
-export { filterWithFallbackInfo, compileIntentRegex, matchIntent, type Extractor, } from "../filter/intent.js";
+export { filterWithFallbackInfo, compileIntentRegex, matchIntent, type Extractor, } from "../utils/intent.js";

package/dist/project/index.js

@@ -1,19 +1,18 @@
-export * from "./closure.js";
 export * from "./digest.js";
 export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
-export { SNAPSHOT_TRACKED_FILES, isPidAlive, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
+export { SNAPSHOT_TRACKED_FILES, isProjectLockHeld, acquireProjectLock, runFrozenInstall, hasPendingTransactions, beginTransaction, recoverPendingTransactions, } from "./transactions.js";
 export * from "./types.js";
 export * from "./types-generator.js";
 export { assertPathWithinRoot, isPathOutsideBoundary, getPackageSlug, parseDuration, traverseDirectory, } from "../utils/index.js";
 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 { validateActionInputValue } from "../json/value-validator.js";
+export { resolveActionInput, buildActionDescribePayload, ACTION_DESCRIBE_SYNTAX_REFERENCE, mapInputValidationFailure, stripBom, readStdinBounded, } from "../input/index.js";
+export { validateActionInputValue } from "../value-validator.js";
 export { parseJson } from "../input/input-resolver.js";
 export { InputError, FlatInputError, } from "../input/flat-errors.js";
 // 意图过滤与查询
-export { filterWithFallbackInfo, compileIntentRegex, matchIntent, } from "../filter/intent.js";
+export { filterWithFallbackInfo, compileIntentRegex, matchIntent, } from "../utils/intent.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.11.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.9.1",
+            "@actiondock/testing": "^2.11.0",
             "@types/node": "^22.13.0",
             "tsx": "^4.19.0",
             "typescript": "^5.7.0",

package/dist/project/loader.d.ts

@@ -1,5 +1,5 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import { type ModuleLoader } from "../node/module-loader.js";
+import { type ModuleLoader } from "../platform/module-loader.js";
 import type { ActionDockManifest, PlaybookDefinition, PlaybookManifestEntry, ProjectConfig } from "./types.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
@@ -22,9 +22,9 @@ export declare const ALLOWED_INSTALLERS: Set<string>;
  * 优先级：
  * - 环境变量 ACTIONDOCK_INSTALLER 显式指定（严格白名单校验：npm, bun）；
  * - 依据项目根目录下现存的锁文件进行精确匹配（bun.lock/bun.lockb -> bun, package-lock.json/npm-shrinkwrap.json -> npm）；
- * - 候选回退优先级探测（npm > bun）。
+ * - 候选回退优先级异步探测（npm > bun）。
  */
-export declare function getInstallCommand(projectRoot?: string): string[];
+export declare function getInstallCommand(projectRoot?: string): Promise<string[]>;
 /**
  * 发现并检索项目 actions 目录下的所有 Action 源码文件（.ts）。
  *

package/dist/project/loader.js

@@ -1,8 +1,8 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { NodeModuleLoader, unwrapDefaultExport } from "../node/module-loader.js";
-import { ACTION_LOAD_FAILED, isMissingModuleError } from "../errors.js";
+import { NodeModuleLoader, unwrapDefaultExport } from "../platform/module-loader.js";
+import { ActionDockError, ACTION_LOAD_FAILED, describeActionLoadFailure, INVALID_ACTION_ID, INVALID_JSON, INVALID_PACKAGE_ID, INVALID_PLAYBOOK_ID, MANIFEST_LOAD_FAILED, PLAYBOOK_NOT_FOUND, PROJECT_CONFIG_NOT_FOUND, } from "../errors.js";
 import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。
@@ -47,14 +47,14 @@ import { PACKAGE_ID_REGEX, assertPathWithinRoot, assertWithinProjectRoot, traver
 export function loadProjectConfig(projectRoot) {
     const configPath = join(projectRoot, "actiondock.json");
     if (!existsSync(configPath)) {
-        throw new Error(`actiondock.json not found in ${projectRoot}`);
+        throw new ActionDockError(PROJECT_CONFIG_NOT_FOUND, `actiondock.json not found in ${projectRoot}`);
     }
     const content = readFileSync(configPath, "utf-8");
     try {
         const parsed = JSON.parse(content);
         const isScoped = /^@[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(parsed.id);
         if (!parsed.id || typeof parsed.id !== "string" || (!PACKAGE_ID_REGEX.test(parsed.id) && !isScoped)) {
-            throw new Error(`actiondock.json invalid or missing 'id': '${parsed?.id}' (must match ${PACKAGE_ID_REGEX})`);
+            throw new ActionDockError(INVALID_PACKAGE_ID, `actiondock.json invalid or missing 'id': '${parsed?.id}' (must match ${PACKAGE_ID_REGEX})`);
         }
         if (!parsed.name || typeof parsed.name !== "string") {
             parsed.name = parsed.id;
@@ -71,18 +71,55 @@ export function loadProjectConfig(projectRoot) {
         return parsed;
     }
     catch (err) {
-        throw new Error(`Failed to parse actiondock.json: ${err.message}`);
+        if (err instanceof ActionDockError) {
+            throw err;
+        }
+        throw new ActionDockError(INVALID_JSON, `Failed to parse actiondock.json: ${err.message}`);
     }
 }
 export const ALLOWED_INSTALLERS = new Set(["npm", "bun"]);
+/**
+ * 异步探测包管理器可用性（通过执行 --version 并检查退出码）。
+ *
+ * 异步化取舍说明：
+ * - 替换同步阻塞子进程调用，避免阻塞 Node.js 事件循环；
+ * - Windows 兼容性保留：npm 在 Windows 上是 .cmd 批处理脚本，在 shell 开启下执行以避免直接调用报错；
+ * - 探测命令限制于白名单内部候选，杜绝外部输入注入风险。
+ */
+function probePackageManager(command) {
+    return new Promise((resolve) => {
+        try {
+            const proc = spawn(command, ["--version"], {
+                stdio: "pipe",
+                shell: process.platform === "win32",
+            });
+            let settled = false;
+            proc.on("error", () => {
+                if (!settled) {
+                    settled = true;
+                    resolve(false);
+                }
+            });
+            proc.on("close", (code) => {
+                if (!settled) {
+                    settled = true;
+                    resolve(code === 0);
+                }
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
 /**
  * 探测宿主系统中可用的包管理工具。
  * 优先级：
  * - 环境变量 ACTIONDOCK_INSTALLER 显式指定（严格白名单校验：npm, bun）；
  * - 依据项目根目录下现存的锁文件进行精确匹配（bun.lock/bun.lockb -> bun, package-lock.json/npm-shrinkwrap.json -> npm）；
- * - 候选回退优先级探测（npm > bun）。
+ * - 候选回退优先级异步探测（npm > bun）。
  */
-export function getInstallCommand(projectRoot) {
+export async function getInstallCommand(projectRoot) {
     const preferred = process.env.ACTIONDOCK_INSTALLER?.trim();
     if (preferred) {
         if (ALLOWED_INSTALLERS.has(preferred)) {
@@ -108,19 +145,9 @@ export function getInstallCommand(projectRoot) {
         ["bun", "install"],
     ];
     for (const [pm, action] of candidates) {
-        try {
-            const check = spawnSync(pm, ["--version"], {
-                stdio: "pipe",
-                // Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 必然 ENOENT，
-                // 会导致探测误判 npm 缺失而错误回退选择 bun
-                shell: process.platform === "win32",
-            });
-            if (check.status === 0) {
-                return [pm, action];
-            }
-        }
-        catch {
-            // 继续探测下一个候选包管理器
+        const available = await probePackageManager(pm);
+        if (available) {
+            return [pm, action];
         }
     }
     return ["npm", "install"];
@@ -178,46 +205,39 @@ export async function loadActions(projectRoot, _actionsDir = "actions", options
         manifest = loadManifest(projectRoot);
     }
     catch (err) {
-        throw new Error(`Failed to load manifest in ${projectRoot}: ${err.message}`);
+        throw new ActionDockError(MANIFEST_LOAD_FAILED, `Failed to load manifest in ${projectRoot}: ${err.message}`);
     }
     // 以 actiondock.json 为唯一事实源读取 Action 的元数据契约与入口
     if (manifest?.actions && Object.keys(manifest.actions).length > 0) {
         for (const [actionId, item] of Object.entries(manifest.actions)) {
             if (!ACTION_ID_REGEX.test(actionId)) {
-                throw new Error(`Invalid action ID '${actionId}' in actiondock.json. Action IDs must match ${ACTION_ID_REGEX}`);
+                throw new ActionDockError(INVALID_ACTION_ID, `Invalid action ID '${actionId}' in actiondock.json. Action IDs must match ${ACTION_ID_REGEX}`);
             }
             const entryPath = resolve(projectRoot, item.entry);
             assertPathWithinRoot(projectRoot, entryPath, `action entry '${item.entry}'`);
             if (!existsSync(entryPath)) {
-                const error = new Error(`Action '${actionId}' entry file not found: ${item.entry}`);
-                error.code = ACTION_LOAD_FAILED;
-                error.details = {
+                throw new ActionDockError(ACTION_LOAD_FAILED, `Action '${actionId}' entry file not found: ${item.entry}`, {
                     actionId,
                     entry: item.entry,
                     entryPath,
-                    hint: `请检查 actiondock.json 中 action '${actionId}' 的 entry 配置 '${item.entry}' 是否正确。`,
-                };
-                throw error;
+                    hint: `Check whether the entry configuration '${item.entry}' for action '${actionId}' in actiondock.json is correct.`,
+                });
             }
             let imported;
             try {
                 imported = await loader.load(entryPath);
             }
             catch (err) {
-                // 复用 errors.ts 的模块缺失判定单一事实源，保留加载器视角的中文修复提示
-                const msg = String(err.message || "");
-                const error = new Error(`Failed to load action '${actionId}' from '${item.entry}': ${msg}`);
-                error.code = ACTION_LOAD_FAILED;
-                error.details = {
+                const failure = describeActionLoadFailure(err, {
                     actionId,
+                    packageId: manifest?.id || basename(projectRoot),
+                    projectRoot,
+                });
+                throw new ActionDockError(failure.code, failure.message, {
+                    ...failure.details,
                     entry: item.entry,
                     entryPath,
-                    rootCause: msg,
-                    hint: isMissingModuleError(msg)
-                        ? `项目依赖缺失，请在 '${projectRoot}' 目录下运行 npm install 安装依赖。`
-                        : undefined,
-                };
-                throw error;
+                }, undefined, failure.details.hint);
             }
             const exported = unwrapDefaultExport(imported);
             let runFn;
@@ -228,15 +248,12 @@ export async function loadActions(projectRoot, _actionsDir = "actions", options
                 runFn = exported.run.bind(exported);
             }
             if (!runFn) {
-                const error = new Error(`Action '${actionId}' in '${item.entry}' does not export a runnable handler`);
-                error.code = ACTION_LOAD_FAILED;
-                error.details = {
+                throw new ActionDockError(ACTION_LOAD_FAILED, `Action '${actionId}' in '${item.entry}' does not export a runnable handler`, {
                     actionId,
                     entry: item.entry,
                     entryPath,
-                    hint: `确保 '${item.entry}' 使用 export default defineAction(...) 导出了可执行处理函数。`,
-                };
-                throw error;
+                    hint: `Ensure that '${item.entry}' exports a runnable handler using export default defineAction(...).`,
+                });
             }
             const def = {
                 run: runFn,
@@ -267,7 +284,7 @@ export function parsePlaybookContent(content, filePath, metadata) {
     const defaultId = filename.replace(/\.md$/, "");
     const playbookId = metadata?.id || defaultId;
     if (!PLAYBOOK_ID_REGEX.test(playbookId)) {
-        throw new Error(`Invalid playbook ID '${playbookId}' found in ${filePath}. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
+        throw new ActionDockError(INVALID_PLAYBOOK_ID, `Invalid playbook ID '${playbookId}' found in ${filePath}. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
     }
     // 规程正文为纯 Markdown，剔除可能残存的旧式 Frontmatter 包裹块
     const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
@@ -299,7 +316,12 @@ export function loadPlaybooks(projectRoot, _playbooksDir = "playbooks", customMa
         try {
             manifest = loadManifest(projectRoot);
         }
-        catch {
+        catch (err) {
+            // 容错与可观测性取舍说明：
+            // - 工程无清单时 loadManifest 返回 null，按空规程集处理属正常场景；
+            // - 清单文件存在但内容损坏或解析失败时，记录可观测警告后安全降级，避免静默吞没异常。
+            const reason = err instanceof Error ? err.message : String(err ?? "Unknown error");
+            process.stderr.write(`[actiondock] Warning: Failed to load manifest in ${projectRoot}: ${reason}\n`);
             return playbooks;
         }
     }
@@ -307,12 +329,12 @@ export function loadPlaybooks(projectRoot, _playbooksDir = "playbooks", customMa
     if (manifest?.playbooks && Object.keys(manifest.playbooks).length > 0) {
         for (const [playbookId, pbEntry] of Object.entries(manifest.playbooks)) {
             if (!PLAYBOOK_ID_REGEX.test(playbookId)) {
-                throw new Error(`Invalid playbook ID '${playbookId}' in actiondock.json. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
+                throw new ActionDockError(INVALID_PLAYBOOK_ID, `Invalid playbook ID '${playbookId}' in actiondock.json. Playbook IDs must match ${PLAYBOOK_ID_REGEX}`);
             }
             const fullPath = resolve(projectRoot, pbEntry.entry);
             assertPathWithinRoot(projectRoot, fullPath, `playbook entry '${pbEntry.entry}'`);
             if (!existsSync(fullPath)) {
-                throw new Error(`Playbook file '${pbEntry.entry}' for '${playbookId}' not found in ${projectRoot}`);
+                throw new ActionDockError(PLAYBOOK_NOT_FOUND, `Playbook file '${pbEntry.entry}' for '${playbookId}' not found in ${projectRoot}`);
             }
             const content = readFileSync(fullPath, "utf-8");
             const def = parsePlaybookContent(content, fullPath, {