@actiondock/core 2.6.0 → 2.8.0

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

@@ -1,18 +1,26 @@
 /**
  * 远端客户端传输层。
  *
- * 职责单一聚焦：鉴权头拼装、明文传输安全校验、insecure dispatcher 注入
- * 与 v2 -> v1 协议回退，作为全部远端端点函数的传输样板单一事实源。
+ * 职责单一聚焦：鉴权头拼装、明文传输安全校验与 insecure dispatcher 注入，
+ * 作为全部远端端点函数的传输样板单一事实源。
  */
 /**
- * 校验在携带认证 Token 时传输层协议是否安全。
- * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
- * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免。
+ * 传输层安全豁免控制选项。
  */
-export declare function assertSecureTransport(serverUrl: string, token?: string, allowInsecureHttpOrOptions?: boolean | {
+export interface SecureTransportOptions {
+    /** 是否允许向非回环地址发送明文 HTTP 请求 */
     allowInsecureHttp?: boolean;
+    /** 是否跳过 TLS 证书合法性校验 */
     insecure?: boolean;
-}, insecureArg?: boolean): void;
+}
+/**
+ * 校验在携带认证 Token 时传输层协议与目标地址是否安全。
+ * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
+ * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免明文限制。
+ * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT，
+ * 杜绝携凭据请求发往不可控的畸形地址。
+ */
+export declare function assertSecureTransport(serverUrl: string, token?: string, options?: SecureTransportOptions): void;
 /**
  * 构造携带鉴权信息的标准请求头。
  */
@@ -43,19 +51,13 @@ export interface RemoteFetchInit {
  * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
  *
  * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
- * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验、
- * insecure dispatcher 注入与 v2 -> v1 协议回退均在此统一处理。
+ * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验与
+ * insecure dispatcher 注入均在此统一处理。
  */
 export declare function createRemoteFetch(serverUrl: string, token?: string, options?: RemoteClientRequestOptions): (path: string, init?: RemoteFetchInit) => Promise<Response>;
 /**
- * 携带协议回退的远端请求单一入口：先打 /api/v2/ 路由，404 时改打 /api/v1/ 路由。
- *
- * v1 回退请求若网络失败则沿用 v2 响应，保留原始状态与错误体供上层透传。
+ * 远端请求单一入口：执行目标协议路由请求。
  */
-export declare function fetchWithProtocolFallback(base: string, path: string, init: RequestInit & {
+export declare function fetchRemoteRoute(base: string, path: string, init: RequestInit & {
     dispatcher?: any;
 }): Promise<Response>;
-/**
- * 列出指定路由的全部协议版本候选 URL（按优先级排序，含原始路由自身）。
- */
-export declare function listProtocolRouteCandidates(base: string, path: string): string[];

package/dist/profile/client-transport.js

@@ -1,31 +1,20 @@
 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";
 /**
- * 远端客户端传输层。
- *
- * 职责单一聚焦：鉴权头拼装、明文传输安全校验、insecure dispatcher 注入
- * 与 v2 -> v1 协议回退，作为全部远端端点函数的传输样板单一事实源。
- */
-/**
- * 校验在携带认证 Token 时传输层协议是否安全。
+ * 校验在携带认证 Token 时传输层协议与目标地址是否安全。
  * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
- * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免。
+ * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免明文限制。
+ * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT，
+ * 杜绝携凭据请求发往不可控的畸形地址。
  */
-export function assertSecureTransport(serverUrl, token, allowInsecureHttpOrOptions, insecureArg) {
+export function assertSecureTransport(serverUrl, token, options) {
     if (!token || !token.trim()) {
         return;
     }
-    let allowInsecureHttp = false;
-    let insecure = false;
-    if (typeof allowInsecureHttpOrOptions === "object" && allowInsecureHttpOrOptions !== null) {
-        allowInsecureHttp = Boolean(allowInsecureHttpOrOptions.allowInsecureHttp);
-        insecure = Boolean(allowInsecureHttpOrOptions.insecure);
-    }
-    else {
-        allowInsecureHttp = Boolean(allowInsecureHttpOrOptions);
-        insecure = Boolean(insecureArg);
-    }
+    const allowInsecureHttp = Boolean(options?.allowInsecureHttp);
+    const insecure = Boolean(options?.insecure);
     const allow = allowInsecureHttp ||
         insecure ||
         (typeof process !== "undefined" &&
@@ -33,25 +22,44 @@ export function assertSecureTransport(serverUrl, token, allowInsecureHttpOrOptio
                 process.env?.ACTIONDOCK_ALLOW_INSECURE_HTTP === "1" ||
                 process.env?.ACTIONDOCK_INSECURE === "true" ||
                 process.env?.ACTIONDOCK_INSECURE === "1"));
-    if (allow) {
-        return;
-    }
     const base = normalizeServerUrl(serverUrl);
-    if (base.startsWith("http://")) {
+    // 目标地址可解析性前置校验（fail-closed）：携带 token 时若目标 URL 无法解析，
+    // 严禁继续放行——后续请求会携凭据发往不可控的畸形目标。错误信息仅携带
+    // 脱敏地址与解析原因。allow 豁免仅作用于明文传输策略，不豁免地址合法性。
+    if (base.startsWith("http://") || base.startsWith("https://")) {
+        let parsed;
         try {
-            const parsed = new URL(base);
-            if (!isLoopbackHost(parsed.hostname)) {
-                const err = new Error(`Insecure HTTP connection with authentication token to non-loopback host '${parsed.hostname}' is prohibited. Use HTTPS or pass --allow-insecure-http to override.`);
-                err.code = "INSECURE_TRANSPORT";
-                throw err;
-            }
+            parsed = new URL(base);
         }
-        catch (e) {
-            if (e.code === "INSECURE_TRANSPORT") {
-                throw e;
-            }
+        catch (err) {
+            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;
+    }
 }
 /**
  * 构造携带鉴权信息的标准请求头。
@@ -69,8 +77,8 @@ export function buildHeaders(token) {
  * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
  *
  * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
- * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验、
- * insecure dispatcher 注入与 v2 -> v1 协议回退均在此统一处理。
+ * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验与
+ * insecure dispatcher 注入均在此统一处理。
  */
 export function createRemoteFetch(serverUrl, token, options) {
     assertSecureTransport(serverUrl, token, {
@@ -101,55 +109,15 @@ export function createRemoteFetch(serverUrl, token, options) {
         }
         else if (options?.insecure) {
             fetchInit.dispatcher = getInsecureDispatcher();
+            fetchInit.tls = { rejectUnauthorized: false };
         }
-        return fetchWithProtocolFallback(base, path, fetchInit);
+        return fetchRemoteRoute(base, path, fetchInit);
     };
 }
-/** v2 优先、v1 兼容回退的协议版本优先级列表。 */
-const PROTOCOL_PREFERENCE = ["v2", "v1"];
 /**
- * 判定响应是否应当触发下一优先级协议重试。
- * 仅 404（路由不存在）回退；其余状态（如 401、403、500）原样透传。
+ * 远端请求单一入口：执行目标协议路由请求。
  */
-function shouldFallbackToNextProtocol(res) {
-    return res.status === 404;
-}
-/**
- * 携带协议回退的远端请求单一入口：先打 /api/v2/ 路由，404 时改打 /api/v1/ 路由。
- *
- * v1 回退请求若网络失败则沿用 v2 响应，保留原始状态与错误体供上层透传。
- */
-export async function fetchWithProtocolFallback(base, path, init) {
+export async function fetchRemoteRoute(base, path, init) {
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-    const isVersioned = /^\/api\/v\d+\//.test(normalizedPath);
-    let res = await fetch(`${base}${normalizedPath}`, init);
-    if (!isVersioned || !shouldFallbackToNextProtocol(res)) {
-        return res;
-    }
-    const candidates = listProtocolRouteCandidates(base, normalizedPath);
-    // 首个候选即当前已返回 404 的路由，从次优先级继续尝试
-    for (let i = 1; i < candidates.length; i++) {
-        try {
-            const fallbackRes = await fetch(candidates[i], init);
-            if (!shouldFallbackToNextProtocol(fallbackRes)) {
-                return fallbackRes;
-            }
-        }
-        catch {
-            // 回退请求网络异常时保持既有 v2 响应，由上层统一处理
-        }
-    }
-    return res;
-}
-/**
- * 列出指定路由的全部协议版本候选 URL（按优先级排序，含原始路由自身）。
- */
-export function listProtocolRouteCandidates(base, path) {
-    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-    const versionMatch = normalizedPath.match(/^\/api\/(v\d+)\/(.*)$/);
-    if (!versionMatch) {
-        return [`${base}${normalizedPath}`];
-    }
-    const rest = versionMatch[2];
-    return PROTOCOL_PREFERENCE.map((version) => `${base}/api/${version}/${rest}`);
+    return fetch(`${base}${normalizedPath}`, init);
 }

package/dist/profile/client.d.ts

@@ -15,8 +15,8 @@
  * - client-state：状态存储管理
  * - client-config：配置管理
  */
-export { assertSecureTransport, createRemoteFetch, fetchWithProtocolFallback, listProtocolRouteCandidates, } from "./client-transport.js";
-export type { RemoteClientRequestOptions, RemoteFetchInit, } from "./client-transport.js";
+export { assertSecureTransport, createRemoteFetch, fetchRemoteRoute, } from "./client-transport.js";
+export type { RemoteClientRequestOptions, RemoteFetchInit, SecureTransportOptions, } from "./client-transport.js";
 export { checkRemoteHealth } from "./client-health.js";
 export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./client-actions.js";
 export type { RemoteExecuteOptions, RemoteExecutionResult } from "./client-actions.js";

package/dist/profile/client.js

@@ -16,7 +16,7 @@
  * - client-config：配置管理
  */
 // 传输层与通用类型
-export { assertSecureTransport, createRemoteFetch, fetchWithProtocolFallback, listProtocolRouteCandidates, } from "./client-transport.js";
+export { assertSecureTransport, createRemoteFetch, fetchRemoteRoute, } from "./client-transport.js";
 // 健康检查
 export { checkRemoteHealth } from "./client-health.js";
 // 执行与 Action 查询

package/dist/profile/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export * from "./manager.js";
 export * from "./client.js";
+export { toSnakeUpperCase, resolveEnvValue } from "../runtime/env.js";

package/dist/profile/index.js

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export * from "./manager.js";
 export * from "./client.js";
+export { toSnakeUpperCase, resolveEnvValue } from "../runtime/env.js";

package/dist/profile/manager.d.ts

@@ -13,6 +13,11 @@ export declare function normalizeServerUrl(url: string): string;
 export declare function getProfilesFilePath(customHome?: string): string;
 /**
  * 加载并读取 profiles.json 配置文件。
+ *
+ * 损坏语义与注册表（registry.ts）对齐：JSON 损坏或结构非法时将原文件原子留档为
+ * `profiles.json.corrupt` 并抛出带恢复指引的异常，绝不静默返回默认配置——否则
+ * 后续任意一次 saveProfiles 会用默认配置覆写原文件，导致用户全部远端环境配置
+ * 永久丢失。文件不存在时仍走默认初始化。
  */
 export declare function loadProfiles(customHome?: string): ProfilesConfig;
 /**

package/dist/profile/manager.js

@@ -1,8 +1,9 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { toSnakeUpperCase } from "../runtime/env.js";
 import { isLoopbackHost } from "../utils/net.js";
 import { getActionDockHome } from "../utils/index.js";
+import { ActionDockError, INVALID_ARGUMENT } from "../errors.js";
 const PROFILE_NAME_REGEX = /^[a-zA-Z0-9_\-\.]+$/;
 /**
  * 默认初始 Profiles 配置（预设 local 本地环境）。
@@ -56,22 +57,56 @@ export function getProfilesFilePath(customHome) {
 }
 /**
  * 加载并读取 profiles.json 配置文件。
+ *
+ * 损坏语义与注册表（registry.ts）对齐：JSON 损坏或结构非法时将原文件原子留档为
+ * `profiles.json.corrupt` 并抛出带恢复指引的异常，绝不静默返回默认配置——否则
+ * 后续任意一次 saveProfiles 会用默认配置覆写原文件，导致用户全部远端环境配置
+ * 永久丢失。文件不存在时仍走默认初始化。
  */
 export function loadProfiles(customHome) {
     const filePath = getProfilesFilePath(customHome);
     if (!existsSync(filePath)) {
         return structuredClone(DEFAULT_PROFILES_CONFIG);
     }
+    let raw;
     try {
-        const raw = readFileSync(filePath, "utf-8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== "object" || !parsed.profiles) {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
             return structuredClone(DEFAULT_PROFILES_CONFIG);
         }
-        return parsed;
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        archiveCorruptProfiles(filePath);
+        throw new ActionDockError(INVALID_ARGUMENT, `Profiles file '${filePath}' is corrupted (invalid JSON: ${err.message}). ` +
+            `The original data has been preserved as '${filePath}.corrupt'. ` +
+            `Restore it manually or remove it to start with the default profiles.`);
+    }
+    if (!parsed || typeof parsed !== "object" || !parsed.profiles) {
+        archiveCorruptProfiles(filePath);
+        throw new ActionDockError(INVALID_ARGUMENT, `Profiles file '${filePath}' is corrupted (missing or invalid 'profiles' field). ` +
+            `The original data has been preserved as '${filePath}.corrupt'. ` +
+            `Restore it manually or remove it to start with the default profiles.`);
+    }
+    return parsed;
+}
+/**
+ * 将损坏的 profiles 文件原子留档为 `${filePath}.corrupt`，
+ * 后续 saveProfiles 的直接写入不会覆盖留档（文件名不同）。
+ */
+function archiveCorruptProfiles(filePath) {
+    try {
+        renameSync(filePath, `${filePath}.corrupt`);
     }
     catch {
-        return structuredClone(DEFAULT_PROFILES_CONFIG);
+        // 留档失败（如文件被其他进程先行移动）时仅放弃留档：错误仍会向上抛出，
+        // 不会出现静默清空
     }
 }
 /**

package/dist/project/closure.js

@@ -1,5 +1,5 @@
 import { resolve } from "node:path";
-import { ActionResolver } from "../catalog/action-resolver.js";
+import { parseActionRef } from "../catalog/resolve-action.js";
 import { resolvePackageRoot } from "../registry/registry.js";
 import { loadManifest } from "./manifest.js";
 /**
@@ -52,7 +52,7 @@ export async function ensureDependencyClosure(roots, opts = {}) {
                     continue;
                 let parsed;
                 try {
-                    parsed = ActionResolver.parseRef(rawRef);
+                    parsed = parseActionRef(rawRef);
                 }
                 catch {
                     warnings.push(`uses 声明 '${rawRef}' 未在注册表中解析到包`);

package/dist/project/index.d.ts

@@ -4,7 +4,14 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
-export * from "./resolver.js";
 export { SNAPSHOT_TRACKED_FILES, type TransactionFileRecord, type TransactionMetadata, type ProjectTransaction, isPidAlive, 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 { parseJson } from "../input/input-resolver.js";
+export { InputError, FlatInputError, } from "../input/flat-errors.js";
+export { filterWithFallbackInfo, compileIntentRegex, matchIntent, type Extractor, } from "../filter/intent.js";

package/dist/project/index.js

@@ -4,7 +4,16 @@ export * from "./init.js";
 export * from "./loader.js";
 export * from "./lockfile.js";
 export * from "./manifest.js";
-export * from "./resolver.js";
 export { SNAPSHOT_TRACKED_FILES, isPidAlive, 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 { parseJson } from "../input/input-resolver.js";
+export { InputError, FlatInputError, } from "../input/flat-errors.js";
+// 意图过滤与查询
+export { filterWithFallbackInfo, compileIntentRegex, matchIntent, } from "../filter/intent.js";

package/dist/project/init.js

@@ -86,10 +86,10 @@ export function initProject(targetDir, options = {}) {
             node: ">=24.12.0",
         },
         dependencies: {
-            "@actiondock/sdk": "^2.6.0",
+            "@actiondock/sdk": "^2.8.0",
         },
         devDependencies: {
-            "@actiondock/testing": "^2.6.0",
+            "@actiondock/testing": "^2.8.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 "../runtime/module-loader.js";
+import { type ModuleLoader } from "../node/module-loader.js";
 import type { ActionDockManifest, PlaybookDefinition, PlaybookManifestEntry, ProjectConfig } from "./types.js";
 /**
  * 从指定目录开始向上逐级递归查找包含 `actiondock.json` 的项目根目录。

package/dist/project/loader.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { DefaultModuleLoader } from "../runtime/module-loader.js";
+import { NodeModuleLoader, unwrapDefaultExport } from "../node/module-loader.js";
 import { ACTION_LOAD_FAILED, isMissingModuleError } from "../errors.js";
 import { loadManifest, ACTION_ID_REGEX, PLAYBOOK_ID_REGEX } from "./manifest.js";
 /**
@@ -36,7 +36,7 @@ export function findProjectRoot(cwd) {
     }
     return null;
 }
-import { PACKAGE_ID_REGEX, assertPathWithinRoot, assertWithinProjectRoot, } from "../utils/index.js";
+import { PACKAGE_ID_REGEX, assertPathWithinRoot, assertWithinProjectRoot, traverseDirectory, } from "../utils/index.js";
 /**
  * 加载并校验指定目录下的 `actiondock.json` 配置文件。
  *
@@ -126,32 +126,29 @@ export function getInstallCommand(projectRoot) {
     return ["npm", "install"];
 }
 /**
- * 递归扫描指定目录下的特定后缀文件（自动排除测试文件 *.test.ts, *.spec.ts 和 *.d.ts）。
+ * 测试与类型声明文件后缀常量（与 builder 的 isIgnoredPath 保持同一语义口径）。
+ */
+const TEST_FILE_SUFFIXES = [
+    ".test.ts",
+    ".test.js",
+    ".test.tsx",
+    ".test.jsx",
+    ".spec.ts",
+    ".spec.js",
+    ".spec.tsx",
+    ".spec.jsx",
+    ".d.ts",
+];
+/**
+ * 递归扫描指定目录下的特定后缀文件（自动排除测试文件与类型声明文件）。
+ * 目录遍历统一复用 core utils 的 traverseDirectory 单一事实源，
+ * 自带软链接越界与循环防护。
  */
 function scanFiles(dir, extension) {
-    if (!existsSync(dir))
-        return [];
-    const results = [];
-    function walk(current) {
-        const entries = readdirSync(current);
-        for (const entry of entries) {
-            const fullPath = join(current, entry);
-            const stat = statSync(fullPath);
-            if (stat.isDirectory()) {
-                walk(fullPath);
-            }
-            else if (stat.isFile() && fullPath.endsWith(extension)) {
-                // 排除测试与类型声明文件
-                if (!fullPath.endsWith(".test.ts") &&
-                    !fullPath.endsWith(".spec.ts") &&
-                    !fullPath.endsWith(".d.ts")) {
-                    results.push(fullPath);
-                }
-            }
-        }
-    }
-    walk(dir);
-    return results;
+    return traverseDirectory(dir)
+        .filter((entry) => entry.relPath.endsWith(extension) &&
+        !TEST_FILE_SUFFIXES.some((suffix) => entry.relPath.endsWith(suffix)))
+        .map((entry) => entry.fullPath);
 }
 /**
  * 发现并检索项目 actions 目录下的所有 Action 源码文件（.ts）。
@@ -175,7 +172,7 @@ export function discoverActionFiles(projectRoot, actionsDir = "actions") {
  */
 export async function loadActions(projectRoot, _actionsDir = "actions", options = {}) {
     const actions = new Map();
-    const loader = options.loader || new DefaultModuleLoader();
+    const loader = options.loader || new NodeModuleLoader();
     let manifest = null;
     try {
         manifest = loadManifest(projectRoot);
@@ -222,7 +219,7 @@ export async function loadActions(projectRoot, _actionsDir = "actions", options
                 };
                 throw error;
             }
-            const exported = imported?.default ?? imported?.action ?? imported;
+            const exported = unwrapDefaultExport(imported);
             let runFn;
             if (typeof exported === "function") {
                 runFn = exported;

package/dist/project/transactions.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { acquireDirectoryLock, checkReclaimGuard, cleanStaleQuarantines, isProcessAlive, parseQuarantineTimestamp as parseQuarantineTimestampCore, readLockWithGracePeriod, safeReleaseLock as coreSafeReleaseLock, safeRemoveStaleReclaimGuard, safeRollbackLock, } from "../storage/lock-core.js";
+import { ActionDockError, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED } from "../errors.js";
 import { LOCKFILE_NAME } from "./lockfile.js";
 import { MANIFEST_FILE_NAME } from "./manifest.js";
 export const SNAPSHOT_TRACKED_FILES = [
@@ -138,9 +139,7 @@ export function acquireProjectLock(projectRoot, options = {}) {
         lockToken,
         acquireTimeoutMs: options.acquireTimeoutMs,
         createLockError(message) {
-            const busyErr = new Error(message);
-            busyErr.code = "PROJECT_BUSY";
-            return busyErr;
+            return new ActionDockError(PROJECT_BUSY, message);
         },
         messages: {
             timeoutWaitingReclaimGuard: (holderPid) => `PROJECT_BUSY: Timeout waiting for active reclaim guard (PID ${holderPid ?? "unknown"}) on project '${projectRoot}' after ${timeoutMs}ms`,
@@ -154,9 +153,7 @@ export function acquireProjectLock(projectRoot, options = {}) {
         assertStaleHolderReclaimable(info) {
             const holderPid = info.pid;
             if (isProcessAlive(holderPid)) {
-                const busyErr = new Error(`PROJECT_BUSY: Project modification lock is held by PID ${holderPid}. Another command is running in ${projectRoot}.`);
-                busyErr.code = "PROJECT_BUSY";
-                throw busyErr;
+                throw new ActionDockError(PROJECT_BUSY, `PROJECT_BUSY: Project modification lock is held by PID ${holderPid}. Another command is running in ${projectRoot}.`);
             }
         },
         onAcquired: () => true,
@@ -223,9 +220,7 @@ export function runFrozenInstall(projectRoot) {
     });
     if (proc.status !== 0) {
         const errorMsg = proc.stderr?.toString() || proc.stdout?.toString() || "Unknown error";
-        const err = new Error(`PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
-        err.code = "PROJECT_RECOVERY_REQUIRED";
-        throw err;
+        throw new ActionDockError(PROJECT_RECOVERY_REQUIRED, `PROJECT_RECOVERY_REQUIRED: Frozen install failed during recovery in ${projectRoot}: ${errorMsg}`);
     }
 }
 /**
@@ -366,7 +361,7 @@ export async function recoverPendingTransactions(projectRoot, options) {
         releaseLock = acquireProjectLock(projectRoot);
     }
     catch (err) {
-        if (err?.code === "PROJECT_BUSY" || err?.message?.includes("PROJECT_BUSY")) {
+        if (err?.code === "PROJECT_BUSY") {
             // 仅当项目锁被其他活跃进程占用时，安全退出并返回空数组
             return [];
         }

package/dist/registry/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./lock.js";
+export type { RegistryLockOptions } from "./lock.js";
 export * from "./registry.js";
-export * from "./resolve.js";
 export * from "./scan.js";
+export * from "./store.js";
 export * from "./types.js";
+export { getActionDockHome, getPackageSlug, } from "../utils/index.js";

package/dist/registry/index.js

@@ -1,5 +1,6 @@
 export * from "./lock.js";
 export * from "./registry.js";
-export * from "./resolve.js";
 export * from "./scan.js";
+export * from "./store.js";
 export * from "./types.js";
+export { getActionDockHome, getPackageSlug, } from "../utils/index.js";

package/dist/registry/lock.d.ts

@@ -1,5 +1,6 @@
 /**
- * 锁目录创建后超过该时长仍未释放，视为持有进程异常退出的残留锁。
+ * 锁目录最近一次心跳（创建或续期）后超过该时长且持有进程已死亡，
+ * 才视为持有进程异常退出的残留锁。
  */
 export declare const REGISTRY_LOCK_STALE_MS = 10000;
 /**
@@ -11,17 +12,37 @@ export declare const REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS = 15000;
  * 两次获取尝试之间的退避间隔，休眠让出事件循环，避免忙等阻塞。
  */
 export declare const REGISTRY_LOCK_RETRY_DELAY_MS = 25;
+/**
+ * 持锁期间的心跳续期间隔。持有者定期 touch 锁目录刷新 mtime，
+ * 使长耗时持锁操作（如 linkPackage 的深度扫描）不会仅因耗时超过
+ * stale 阈值而被等待方误判为残留锁抢占。
+ */
+export declare const REGISTRY_LOCK_HEARTBEAT_MS = 3000;
+/**
+ * 锁配置选项。
+ */
+export interface RegistryLockOptions {
+    staleMs?: number;
+    acquireTimeoutMs?: number;
+    retryDelayMs?: number;
+    heartbeatMs?: number;
+}
 /**
  * 异步注册表锁（防止多进程并发读写导致 registry.json 损坏）。
  *
- * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录。
- * 冲突处理：EEXIST 时 stat 检查锁目录年龄，超过 stale 阈值则先原子 rename 到
- * 隔离名再删除——rename 仅有一个进程能成功，失败方回到等待重试，消除
- * 「stat 检查后删除再重建」的竞态窗口；未过期的锁通过 sleep 让出事件循环后重试。
+ * 获取方式：fs/promises mkdir 的原子性保证同一时刻仅一个进程能创建锁目录，
+ * 创建成功后立即写入含 pid 与随机 token 的 metadata.json。
+ * 冲突处理：EEXIST 时按保守语义判定残留（见 isStaleLock）：mtime 超龄且
+ * pid 已死才抢占——抢占仍通过原子 rename 到隔离名实现，rename 仅有一个
+ * 进程能成功，失败方回到等待重试，消除「检查后删除再重建」的竞态窗口；
+ * 未过期的锁通过 sleep 让出事件循环后重试。
+ * 心跳续期：持锁期间以固定间隔 touch 锁目录刷新 mtime，使 linkPackage 等
+ * 长耗时持锁操作不会仅因耗时被误判残留；fn 完成后停止心跳并删除锁目录。
  *
  * @param filePath 注册表文件路径，锁目录为其同级 `${filePath}.lock`
  * @param fn 持锁期间执行的操作（同步或异步）
+ * @param options 可选锁超时与重试配置
  * @returns fn 的返回值
- * @throws 超过 REGISTRY_LOCK_ACQUIRE_TIMEOUT_MS 仍未获取时抛出描述性错误
+ * @throws 超过 acquireTimeoutMs 仍未获取时抛出描述性错误
  */
-export declare function withRegistryLock<T>(filePath: string, fn: () => T | Promise<T>): Promise<T>;
+export declare function withRegistryLock<T>(filePath: string, fn: () => T | Promise<T>, options?: RegistryLockOptions): Promise<T>;