@actiondock/core 2.5.1 → 2.7.0

package/dist/errors.js

@@ -61,6 +61,8 @@ export const EXECUTION_ABORTED = "EXECUTION_ABORTED";
 export const TIMEOUT = "TIMEOUT";
 /** 远程服务器网络连接失败 */
 export const NETWORK_ERROR = "NETWORK_ERROR";
+/** 远程事件流全部候选路由均不可用 */
+export const REMOTE_STREAM_UNAVAILABLE = "REMOTE_STREAM_UNAVAILABLE";
 /** 远程目标未启用管理接口能力 */
 export const CAPABILITY_UNAVAILABLE = "CAPABILITY_UNAVAILABLE";
 /** 远程状态键不存在 */
@@ -151,6 +153,26 @@ export const QUEUE_FULL = "QUEUE_FULL";
 export const QUOTA_EXCEEDED = "QUOTA_EXCEEDED";
 /** 输入通道已关闭拒绝继续写入 */
 export const INPUT_CLOSED = "INPUT_CLOSED";
+/** 扁平入参赋值表达式格式非法 */
+export const INVALID_FLAT_ARGUMENT = "INVALID_FLAT_ARGUMENT";
+/** 完整 JSON 文档解析失败 */
+export const INVALID_JSON = "INVALID_JSON";
+/** JSON 字面量解析失败或包含非有限数值 */
+export const INVALID_JSON_LITERAL = "INVALID_JSON_LITERAL";
+/** 扁平入参路径冲突 */
+export const INPUT_PATH_CONFLICT = "INPUT_PATH_CONFLICT";
+/** 扁平入参超出安全阈值上限 */
+export const FLAT_INPUT_LIMIT_EXCEEDED = "FLAT_INPUT_LIMIT_EXCEEDED";
+/** 输入数据超出上限（字节大小、嵌套深度等） */
+export const INPUT_LIMIT_EXCEEDED = "INPUT_LIMIT_EXCEEDED";
+/** 输入违反 ActionDock 安全策略（如包含全局禁止属性） */
+export const INPUT_POLICY_VIOLATION = "INPUT_POLICY_VIOLATION";
+/** 输入源互斥冲突 */
+export const INPUT_CONFLICT = "INPUT_CONFLICT";
+/** 输入文件不存在 */
+export const INPUT_FILE_NOT_FOUND = "INPUT_FILE_NOT_FOUND";
+/** 输入文件或流读取失败 */
+export const INPUT_FILE_READ_FAILED = "INPUT_FILE_READ_FAILED";
 /**
  * 进程领域结构化异常类。
  */

package/dist/execution/service.js

@@ -3,7 +3,8 @@ import { ActionResolver } from "../catalog/action-resolver.js";
 import { computeDigest } from "../project/digest.js";
 import { InMemoryEventSink } from "../runtime/events.js";
 import { ActionRunner } from "../runtime/runner.js";
-import { ACTION_CANCELLED, ACTION_NOT_FOUND, ACTION_TIMEOUT, EXECUTION_FAILED, IDEMPOTENCY_CONFLICT, RUN_REPOSITORY_UNAVAILABLE, UNHANDLED_EXECUTION_ERROR, describeActionLoadFailure, } from "../errors.js";
+import { ACTION_NOT_FOUND, EXECUTION_FAILED, IDEMPOTENCY_CONFLICT, RUN_REPOSITORY_UNAVAILABLE, UNHANDLED_EXECUTION_ERROR, describeActionLoadFailure, } from "../errors.js";
+import { resultStatusToRunStatus } from "../storage/types.js";
 /**
  * 统一执行协调服务实现。
  */
@@ -49,6 +50,8 @@ export class DefaultExecutionService {
                     options.platform.storage.createStorage(this.packageId, {
                         projectRoot: options.projectRoot,
                         customHome: options.customHome,
+                        // 执行服务属于数据目录持有者主路径，打开时收割遗留孤儿运行
+                        recoverOrphans: true,
                     });
         }
         else {
@@ -60,7 +63,8 @@ export class DefaultExecutionService {
             this.storage = options.storage;
         }
         const globalStorage = options.platform
-            ? (options.globalStorage ?? options.platform.storage.createGlobalStorage({ customHome: options.customHome }))
+            ? (options.globalStorage ??
+                options.platform.storage.createGlobalStorage({ customHome: options.customHome, recoverOrphans: true }))
             : options.globalStorage;
         this.ownsStorage = !options.storage;
         this.ownsGlobalStorage = !options.globalStorage && !!options.platform;
@@ -533,13 +537,7 @@ export class DefaultExecutionService {
     watchHandleCompletion(handle, activeItem, bridge) {
         handle.result
             .then((result) => {
-            const finalStatus = result.ok
-                ? "success"
-                : result.error?.code === ACTION_TIMEOUT
-                    ? "timed_out"
-                    : result.error?.code === ACTION_CANCELLED
-                        ? "cancelled"
-                        : "failed";
+            const finalStatus = resultStatusToRunStatus(result.ok, result.ok ? undefined : result.error?.code);
             activeItem.status = finalStatus;
             bridge.emitEvent({ type: "status", status: finalStatus });
             bridge.emitEvent({ type: "finish", result });
@@ -633,6 +631,13 @@ export class DefaultExecutionService {
             }
         }
         this.activeRuns.clear();
+        // 级联释放跨包子包 Runner 及其独立创建的存储连接（幂等，异常不阻断后续释放）
+        try {
+            await this._runner.dispose();
+        }
+        catch {
+            // 子包释放异常已在 dispose 内部隔离，此处仅需保障主流程继续
+        }
         if (this.ownsStorage && this.storage && typeof this.storage.close === "function") {
             await this.storage.close();
         }

package/dist/export/templates.js

@@ -124,7 +124,7 @@ ad link "<skill_root>"
 
 ### 动作参数契约按需调阅
 
-在调用未知参数的 Action 前，可在终端执行命令按需查阅该 Action 的输入输出模式与详细说明：
+在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
 
 \`\`\`bash
 ad describe ${pkgId}/${firstAction}
@@ -134,29 +134,28 @@ ad describe ${pkgId}/${firstAction}
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
 
-推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
 \`\`\`bash
-# 写入参数到临时文件并通过 --input-file 传递
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-ad run ${pkgId}/${firstAction} --input-file /tmp/input.json
+# 调阅参数契约与建议赋值样例
+ad describe ${pkgId}/${firstAction}
 \`\`\`
 
-亦可通过内联参数进行简易命令调用：
+调用语法格式：
+ad run ${pkgId}/${firstAction} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ad describe ${pkgId}/${firstAction} 查阅的参数契约提供）
+
+将参数写入 JSON 文件并通过 --input-file 传递：
 
 \`\`\`bash
-ad run ${pkgId}/${firstAction} --input '{"param": "value"}'
+ad run ${pkgId}/${firstAction} --json --input-file input.json
 \`\`\`
 
-> **免注册本地执行**：
+> 免注册本地执行：
 > 若工作目录已位于本技能根目录，亦可直接免 link 执行：
 > \`\`\`bash
 > cd <skill_root>
-> ad run <action-id> --input-file /tmp/input.json
+> ad run ${firstAction} --json
 > \`\`\`
 
 ### 结构化响应解析
@@ -258,24 +257,31 @@ description: ${desc}
 ${desc}
 
 
+### 动作参数契约按需调阅
+
+在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：
+
+\`\`\`bash
+${binaryRelPath} describe ${firstAction}
+\`\`\`
+
 ### 执行 Action
 
-推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
 \`\`\`bash
-# 写入参数到临时文件并通过 --input-file 传递
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-${binaryRelPath} run <action-id> --input-file /tmp/input.json
+# 调阅参数契约与建议赋值样例
+${binaryRelPath} describe ${firstAction}
 \`\`\`
 
-亦可通过内联参数进行简易命令调用：
+调用语法格式：
+${binaryRelPath} run ${firstAction} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ${binaryRelPath} describe ${firstAction} 查阅的参数契约提供）
+
+将参数写入 JSON 文件并通过 --input-file 传递：
 
 \`\`\`bash
-${binaryRelPath} run ${firstAction} --input '{"param": "value"}'
+${binaryRelPath} run ${firstAction} --json --input-file input.json
 \`\`\`
 
 ### 结构化响应解析
@@ -466,16 +472,22 @@ ${playbookEntries.join("\n")}
 ---`
         : "";
     const sInvoke = `## 标准调用命令
+ 
+推荐在执行前调用 describe 命令调阅确切参数契约：
 
-推荐使用参数文件传递内容，杜绝终端引号转义问题：
+\`\`\`bash
+# 调阅参数契约与建议赋值样例
+ad describe ${sampleActionId}
+\`\`\`
 
+调用语法格式：
+ad run ${sampleActionId} --json -- ASSIGNMENT...
+（其中 ASSIGNMENT 根据 ad describe ${sampleActionId} 查阅的参数契约提供）
+ 
+将参数写入 JSON 文件并通过 --input-file 传递：
+ 
 \`\`\`bash
-cat << 'EOF' > /tmp/input.json
-{
-  "param": "value"
-}
-EOF
-ad run ${sampleActionId} --input-file /tmp/input.json
+ad run ${sampleActionId} --json --input-file input.json
 \`\`\`
 
 ### 结构化响应解析

package/dist/host/host.d.ts

@@ -8,6 +8,7 @@ import type { ActionDockHost, ActionDockHostOptions } from "./types.js";
  */
 export declare class DefaultActionDockHost implements ActionDockHost {
     readonly hostSessionId: string;
+    readonly options: ActionDockHostOptions;
     private apps;
     private readonly internallyCreatedApps;
     private activeSubRunsPerRoot;
@@ -19,11 +20,43 @@ export declare class DefaultActionDockHost implements ActionDockHost {
     private isClosed;
     private dataDirLock?;
     private failedLinkedPackages;
+    private failedAutoLoad?;
+    /** 透传给内部创建 App 的存储收割开关（Host 默认持有者身份，显式可关） */
+    private recoverOrphans;
     constructor(options?: ActionDockHostOptions);
+    /**
+     * 阶段函数：注册显式传入的 packages 列表（现成 App 实例或 AppOptions 配置）。
+     */
+    private registerExplicitPackages;
+    /**
+     * 阶段函数：自动加载当前工程并注册依赖闭包内的全部包。
+     *
+     * 失败语义区分场景：
+     * - 显式传入 projectRoot 时，任何解析失败（损坏 actiondock.json、文件系统错误等）
+     *   必须向上抛出，由调用方感知，严禁吞没；
+     * - 自动探测场景（未传 projectRoot，由 findProjectRoot 发现）失败时记录实例诊断
+     *   failedAutoLoad 并在创建时输出单行告警，保持宿主其余能力可用但绝不无声。
+     */
+    private loadCurrentProject;
+    /**
+     * 阶段函数：扫描全局注册表中已软链接的外部包并注册至 Host。
+     * 加载失败的链接包记录至 failedLinkedPackages 诊断并在调阅时透传精准失败原因。
+     */
+    private registerLinkedPackages;
     private resolvePackageContext;
     private bindApp;
+    /** 路由可见性上下文（公开包集合与依赖解析器） */
+    private visibility;
     getApp(packageId: string): ActionDockApp | undefined;
     listApps(): ActionDockApp[];
+    /**
+     * 获取自动加载工程的失败诊断信息。
+     * 仅自动探测场景会记录此诊断；显式传入 projectRoot 的加载失败会直接抛出，不产生此诊断。
+     */
+    getAutoLoadFailure(): {
+        projectRoot: string;
+        error: string;
+    } | undefined;
     private registerAppInternal;
     registerApp(app: ActionDockApp): void;
     info(): Promise<PackageInfo[]>;