@actiondock/core 2.7.0 → 2.9.0

package/dist/host/routing.d.ts

@@ -1,43 +1,15 @@
 import type { ActionRef, RuntimeError } from "@actiondock/sdk";
-import type { ActionDockApp, ActionSpec, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
-import type { ActionPackageResolver } from "../project/resolver.js";
-/**
- * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
- *
- * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
- * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
- */
-export declare function isActionNotFoundLikeError(err: any): boolean;
+import type { PackageInfo, PackageRuntime, ActionSpec, PlaybookSpec, PlaybookSummary } from "../package/types.js";
+import { type ActionCatalog, type PackageGraph } from "../catalog/index.js";
 /**
  * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ * 委派纯领域解析 parseActionRef 单一事实源。
  */
 export declare function parseRefLoose(ref: ActionRef | string): ActionRef;
 /**
- * 根调用可见性判定：非公开包且存在依赖解析器时，交由解析器委托规则裁决。
+ * 根调用可见性判定：非公开包且存在依赖图时，交由图委托规则裁决。
  */
-export declare function isRootCallVisible(packageId: string, actionId: string, hostPublicPackageIds: ReadonlySet<string>, resolver?: ActionPackageResolver): boolean;
-/**
- * 跨包短标识符歧义消解结果：唯一匹配、歧义多匹配与零匹配三态。
- */
-export type ShortRefResolution = {
-    kind: "unique";
-    app: ActionDockApp;
-} | {
-    kind: "ambiguous";
-    candidates: string[];
-} | {
-    kind: "not_found";
-};
-/**
- * 在全部已注册包中按短标识符解析唯一提供方。
- *
- * 可见性过滤遵循根调用规则（公开包直接可见；传递依赖包仅可见 Playbook 委托项）；
- * 仅 not-found 语义错误被跳过，其余异常向调用方透传。
- */
-export declare function resolveShortRef(apps: readonly ActionDockApp[], actionId: string, visibility: {
-    hostPublicPackageIds: ReadonlySet<string>;
-    resolver?: ActionPackageResolver;
-}): Promise<ShortRefResolution>;
+export declare function isRootCallVisible(packageId: string, actionId: string, hostPublicPackageIds: ReadonlySet<string>, graph?: PackageGraph): boolean;
 /**
  * 按包标识构造未找到错误信息：优先透传链接包加载失败的精准诊断。
  */
@@ -48,40 +20,35 @@ export declare function packageNotFoundMessage(packageId: string, failedLinkedPa
 /**
  * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
  */
-export declare function listVisiblePlaybooks(apps: readonly ActionDockApp[], visibility: {
+export declare function listVisiblePlaybooks(runtimes: readonly PackageRuntime[], visibility: {
     hostPublicPackageIds: ReadonlySet<string>;
-    resolver?: ActionPackageResolver;
+    graph?: PackageGraph;
 }): Promise<PlaybookSummary[]>;
 /**
- * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
- * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ * 静态查询指定 Playbook 规范：基于 resolvePlaybook 统一纯领域解析。
  */
-export declare function describeVisiblePlaybook(apps: readonly ActionDockApp[], id: string, visibility: {
+export declare function describeVisiblePlaybook(runtimes: readonly PackageRuntime[], id: string, visibility: {
     hostPublicPackageIds: ReadonlySet<string>;
-    resolver?: ActionPackageResolver;
+    graph?: PackageGraph;
 }): Promise<PlaybookSpec>;
 /**
  * 聚合全部已注册包的元数据信息。
  */
-export declare function collectPackageInfos(apps: readonly ActionDockApp[]): Promise<PackageInfo[]>;
+export declare function collectPackageInfos(runtimes: readonly PackageRuntime[]): Promise<PackageInfo[]>;
 /**
  * 构造失配类错误响应载荷（ACTION_NOT_FOUND / AMBIGUOUS_ACTION_REF 等）。
  */
 export declare function buildRuntimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeError;
 /**
- * 构造短标识符歧义错误消息（供静态查询与启动执行链路复用统一文案）。
- */
-export declare function ambiguousActionMessage(actionId: string, candidates: readonly string[]): string;
-/**
- * 静态查询指定 Action 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ * 静态查询指定 Action 规范：基于 resolveAction 统一纯领域解析。
  */
-export declare function describeActionAcrossApps(ref: ActionRef | string, apps: readonly ActionDockApp[], visibility: {
+export declare function describeActionAcrossRuntimes(ref: ActionRef | string, runtimes: readonly PackageRuntime[], visibility: {
     hostPublicPackageIds: ReadonlySet<string>;
-    resolver?: ActionPackageResolver;
+    graph?: PackageGraph;
 }, failedLinkedPackages: ReadonlyMap<string, {
     path: string;
     error: string;
-}>): Promise<ActionSpec>;
+}>, catalog?: ActionCatalog, graph?: PackageGraph): Promise<ActionSpec>;
 /** existsSync 的可注入探测依赖（纯函数模块保持可测试性） */
 export type ExistsProbe = (path: string) => boolean;
 /**

package/dist/host/routing.js

@@ -1,76 +1,28 @@
 import { existsSync } from "node:fs";
-import { ActionResolver } from "../catalog/action-resolver.js";
-/**
- * 判定异常是否为 not-found 语义（包内确实不存在该 Action）。
- *
- * 遍历匹配短标识符时仅跳过此类错误；存储损坏、模块加载失败等内部错误必须向调用方透传，
- * 严禁被吞没后伪装成 ACTION_NOT_FOUND。
- */
-export function isActionNotFoundLikeError(err) {
-    if (!err) {
-        return false;
-    }
-    if (err.code === "ACTION_NOT_FOUND" || err.code === "NOT_FOUND") {
-        return true;
-    }
-    const message = typeof err.message === "string" ? err.message : String(err);
-    return (message.startsWith("ACTION_NOT_FOUND:") ||
-        /Action '[^']*' not found in package/.test(message));
-}
+import { DefaultActionCatalog, DefaultPackageGraph, parseActionRef, resolveAction, resolvePlaybook, } from "../catalog/index.js";
+import { InvocationPolicy } from "../invocation/policy.js";
+import { ActionDockError, PACKAGE_NOT_FOUND } from "../errors.js";
 /**
  * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ * 委派纯领域解析 parseActionRef 单一事实源。
  */
 export function parseRefLoose(ref) {
     try {
-        return ActionResolver.parseRef(ref);
+        return parseActionRef(ref);
     }
     catch {
-        return typeof ref === "object" ? ref : { actionId: ref };
-    }
-}
-/**
- * 根调用可见性判定：非公开包且存在依赖解析器时，交由解析器委托规则裁决。
- */
-export function isRootCallVisible(packageId, actionId, hostPublicPackageIds, resolver) {
-    const isPublic = hostPublicPackageIds.has(packageId);
-    if (isPublic) {
-        return true;
+        return typeof ref === "object" && ref !== null ? ref : { actionId: String(ref) };
     }
-    if (resolver && !resolver.canRootCall(packageId, actionId)) {
-        return false;
-    }
-    return true;
 }
 /**
- * 在全部已注册包中按短标识符解析唯一提供方。
- *
- * 可见性过滤遵循根调用规则（公开包直接可见；传递依赖包仅可见 Playbook 委托项）；
- * 仅 not-found 语义错误被跳过，其余异常向调用方透传。
+ * 根调用可见性判定：非公开包且存在依赖图时，交由图委托规则裁决。
  */
-export async function resolveShortRef(apps, actionId, visibility) {
-    const matches = [];
-    for (const app of apps) {
-        try {
-            if (!isRootCallVisible(app.packageId, actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
-                continue;
-            }
-            await app.describeAction(actionId);
-            matches.push(app);
-        }
-        catch (err) {
-            // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
-            if (!isActionNotFoundLikeError(err)) {
-                throw err;
-            }
-        }
-    }
-    if (matches.length === 1) {
-        return { kind: "unique", app: matches[0] };
-    }
-    if (matches.length > 1) {
-        return { kind: "ambiguous", candidates: matches.map((m) => m.packageId) };
-    }
-    return { kind: "not_found" };
+export function isRootCallVisible(packageId, actionId, hostPublicPackageIds, graph) {
+    const policy = new InvocationPolicy();
+    return (policy.checkRootVisibility(packageId, actionId, {
+        hostPublicPackageIds,
+        graph,
+    }) === undefined);
 }
 /**
  * 按包标识构造未找到错误信息：优先透传链接包加载失败的精准诊断。
@@ -85,74 +37,75 @@ export function packageNotFoundMessage(packageId, failedLinkedPackages) {
 /**
  * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
  */
-export async function listVisiblePlaybooks(apps, visibility) {
+export async function listVisiblePlaybooks(runtimes, visibility) {
     const results = [];
-    for (const app of apps) {
-        const isPublic = visibility.hostPublicPackageIds.has(app.packageId);
-        if (!isPublic && visibility.resolver) {
-            const graph = visibility.resolver.resolveSync();
-            if (!graph.directDependencyIds.has(app.packageId)) {
+    for (const runtime of runtimes) {
+        const isPublic = visibility.hostPublicPackageIds.has(runtime.packageId);
+        if (!isPublic && visibility.graph) {
+            const rootNode = visibility.graph.root ? visibility.graph.getNode(visibility.graph.root.id) : undefined;
+            if (!rootNode?.directDependencies.has(runtime.packageId)) {
                 continue;
             }
         }
-        const appPlaybooks = await app.listPlaybooks();
-        for (const item of appPlaybooks) {
-            const qualifiedId = apps.length > 1 && !item.id.includes("/")
-                ? `${app.packageId}/${item.id}`
+        const runtimePlaybooks = await runtime.listPlaybooks();
+        for (const item of runtimePlaybooks) {
+            const qualifiedId = runtimes.length > 1 && !item.id.includes("/")
+                ? `${runtime.packageId}/${item.id}`
                 : item.id;
             results.push({
                 ...item,
                 id: qualifiedId,
-                packageId: app.packageId,
+                packageId: runtime.packageId,
             });
         }
     }
     return results;
 }
 /**
- * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
- * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ * 基于 Runtime 列表构造无依赖关系的兜底包图。
+ *
+ * 无任何可见包图可用时的降级事实源：每个包独立成节点，无直接与传递依赖边。
  */
-export async function describeVisiblePlaybook(apps, id, visibility) {
-    if (id.includes("/")) {
-        const lastSlashIndex = id.lastIndexOf("/");
-        const packageId = id.slice(0, lastSlashIndex);
-        const playbookId = id.slice(lastSlashIndex + 1);
-        const isPublic = visibility.hostPublicPackageIds.has(packageId);
-        if (!isPublic && visibility.resolver) {
-            const graph = visibility.resolver.resolveSync();
-            if (!graph.directDependencyIds.has(packageId)) {
-                throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Playbook '${id}' belongs to undeclared transitive package '${packageId}'`);
-            }
-        }
-        const app = apps.find((a) => a.packageId === packageId);
-        if (!app) {
-            throw new Error(`Package '${packageId}' not found in host`);
+function buildFallbackGraph(runtimes) {
+    return new DefaultPackageGraph(new Map(runtimes.map((a) => [
+        a.packageId,
+        {
+            identity: a.identity,
+            packageId: a.packageId,
+            root: a.packageRoot || "",
+            manifest: a.projectConfig,
+            manifestDigest: "",
+            version: a.projectConfig?.version || "0.1.0",
+            npmPackage: a.packageId,
+            directDependencies: new Set(),
+            transitiveDependencies: new Set(),
+        },
+    ])));
+}
+/**
+ * 静态查询指定 Playbook 规范：基于 resolvePlaybook 统一纯领域解析。
+ */
+export async function describeVisiblePlaybook(runtimes, id, visibility) {
+    const graph = visibility.graph || buildFallbackGraph(runtimes);
+    const resolved = resolvePlaybook(id, { graph });
+    const isPublic = visibility.hostPublicPackageIds.has(resolved.packageId);
+    if (!isPublic && visibility.graph) {
+        const rootNode = visibility.graph.root ? visibility.graph.getNode(visibility.graph.root.id) : undefined;
+        if (!rootNode?.directDependencies.has(resolved.packageId)) {
+            throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Playbook '${id}' belongs to undeclared transitive package '${resolved.packageId}'`);
         }
-        return app.describePlaybook(playbookId);
     }
-    for (const app of apps) {
-        try {
-            const isPublic = visibility.hostPublicPackageIds.has(app.packageId);
-            if (!isPublic && visibility.resolver) {
-                const graph = visibility.resolver.resolveSync();
-                if (!graph.directDependencyIds.has(app.packageId)) {
-                    continue;
-                }
-            }
-            return await app.describePlaybook(id);
-        }
-        catch {
-            // 忽略未匹配的包
-        }
+    const runtime = runtimes.find((a) => a.packageId === resolved.packageId);
+    if (!runtime) {
+        throw new Error(`Package '${resolved.packageId}' not found in host`);
     }
-    throw new Error(`Playbook '${id}' not found in any registered package`);
+    return runtime.describePlaybook(resolved.playbookId);
 }
 /**
  * 聚合全部已注册包的元数据信息。
  */
-export async function collectPackageInfos(apps) {
-    return Promise.all(apps.map((app) => app.info()));
+export async function collectPackageInfos(runtimes) {
+    return Promise.all(runtimes.map((runtime) => runtime.info()));
 }
 /**
  * 构造失配类错误响应载荷（ACTION_NOT_FOUND / AMBIGUOUS_ACTION_REF 等）。
@@ -165,60 +118,44 @@ export function buildRuntimeError(code, message, details) {
     return error;
 }
 /**
- * 构造短标识符歧义错误消息（供静态查询与启动执行链路复用统一文案）。
- */
-export function ambiguousActionMessage(actionId, candidates) {
-    const joined = candidates.map((c) => `${c}/${actionId}`).join(", ");
-    return `Action '${actionId}' is ambiguous and provided by multiple packages: ${joined}. Please specify '<package-id>/${actionId}'.`;
-}
-/**
- * 静态查询指定 Action 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ * 静态查询指定 Action 规范：基于 resolveAction 统一纯领域解析。
  */
-export async function describeActionAcrossApps(ref, apps, visibility, failedLinkedPackages) {
+export async function describeActionAcrossRuntimes(ref, runtimes, visibility, failedLinkedPackages, catalog, graph) {
     const parsed = parseRefLoose(ref);
-    if (parsed.packageId) {
-        if (!isRootCallVisible(parsed.packageId, parsed.actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
-            throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Action '${parsed.packageId}/${parsed.actionId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`);
-        }
-        const app = apps.find((a) => a.packageId === parsed.packageId);
-        if (!app) {
-            throw new Error(packageNotFoundMessage(parsed.packageId, failedLinkedPackages));
-        }
-        const spec = await app.describeAction(parsed.actionId);
-        return {
-            ...spec,
-            packageId: app.packageId,
-        };
+    if (parsed.packageId && failedLinkedPackages.has(parsed.packageId)) {
+        throw new Error(packageNotFoundMessage(parsed.packageId, failedLinkedPackages));
     }
-    const matches = [];
-    for (const app of apps) {
-        try {
-            if (!isRootCallVisible(app.packageId, parsed.actionId, visibility.hostPublicPackageIds, visibility.resolver)) {
-                continue;
-            }
-            const spec = await app.describeAction(parsed.actionId);
-            matches.push({ app, spec: { ...spec, packageId: app.packageId } });
-        }
-        catch (err) {
-            // 仅将 not-found 语义视为「包内无此 Action」；其余异常必须透传，避免内部错误伪装成 ACTION_NOT_FOUND
-            if (!isActionNotFoundLikeError(err)) {
-                throw err;
+    const effectiveGraph = graph || visibility.graph || buildFallbackGraph(runtimes);
+    const effectiveCatalog = catalog ||
+        new DefaultActionCatalog(effectiveGraph, (pkgId) => runtimes.find((a) => a.packageId === pkgId)?.actionsMap);
+    let resolved;
+    try {
+        resolved = resolveAction(ref, {
+            graph: effectiveGraph,
+            catalog: effectiveCatalog,
+        });
+    }
+    catch (err) {
+        if (err.code === PACKAGE_NOT_FOUND) {
+            const parsed = parseRefLoose(ref);
+            if (parsed.packageId) {
+                throw new ActionDockError(PACKAGE_NOT_FOUND, packageNotFoundMessage(parsed.packageId, failedLinkedPackages));
             }
         }
+        throw err;
     }
-    if (matches.length === 1) {
-        return {
-            ...matches[0].spec,
-            packageId: matches[0].app.packageId,
-        };
+    if (!isRootCallVisible(resolved.package.id, resolved.ref.actionId, visibility.hostPublicPackageIds, effectiveGraph)) {
+        throw new Error(`UNDECLARED_ACTION_DEPENDENCY: Action '${resolved.package.id}/${resolved.ref.actionId}' is not declared as a direct dependency in actiondock.json and is not delegated by a visible playbook`);
     }
-    if (matches.length > 1) {
-        const err = new Error(`INVALID_ACTION_REF: ${ambiguousActionMessage(parsed.actionId, matches.map((m) => m.app.packageId))} (AMBIGUOUS_ACTION_REF)`);
-        err.code = "INVALID_ACTION_REF";
-        err.details = { alias: "AMBIGUOUS_ACTION_REF", candidates: matches.map((m) => m.app.packageId) };
-        throw err;
+    const runtime = runtimes.find((a) => a.packageId === resolved.package.id);
+    if (!runtime) {
+        throw new Error(packageNotFoundMessage(resolved.package.id, failedLinkedPackages));
     }
-    throw new Error(`ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in any registered package`);
+    const spec = await runtime.describeAction(resolved.ref.actionId);
+    return {
+        ...spec,
+        packageId: runtime.packageId,
+    };
 }
 /**
  * 解析宿主自动加载工程根目录：显式指定优先，其次当前进程工作目录探测。

package/dist/host/types.d.ts

@@ -1,15 +1,18 @@
 import type { ActionRef, ExecutionEvent, ExecutionResult, JsonValue, Logger, ProcessAPI, RunRecord } from "@actiondock/sdk";
-import type { ActionDockApp, ActionDockAppOptions, ActionSpec, ActionSummary, ListActionsOptions, PackageInfo, PlaybookSpec, PlaybookSummary } from "../app/types.js";
-import type { CancelResult, ExecuteOptions, ExecutionTicket } from "../execution/types.js";
+import type { PackageInfo, PackageRuntime, PackageRuntimeOptions, ActionSpec, ActionSummary, ListActionsOptions, PlaybookSpec, PlaybookSummary } from "../package/types.js";
+import type { CancelResult, ExecutionTicket } from "../execution/types.js";
+import type { RunOptions } from "../invocation/types.js";
 import type { Clock } from "../runtime/clock.js";
 import type { EventSink } from "../runtime/events.js";
 import type { RuntimePlatform } from "../platform/types.js";
+import type { ConfigValueView, ListRunsOptions, StateScopeOptions } from "../service/types.js";
+import type { StateEntry } from "../storage/types.js";
 /**
  * ActionDock 宿主容器初始化配置选项。
  */
 export interface ActionDockHostOptions {
-    /** 显式预注册的包列表（现成 ActionDockApp 实例或 ActionDockAppOptions 配置）。外部传入的 App 属于借用（borrowed），生命周期完全由调用方负责管理，Host 关闭或初始化失败时仅解绑引用并清理自身内部实例，严禁关闭外部借用的 App 实例。 */
-    packages?: Array<ActionDockApp | ActionDockAppOptions>;
+    /** 显式预注册的包列表（PackageRuntime 实例、PackageRuntimeOptions 配置或包目录物理路径）。Host 统一管理其生命周期，关闭时统一释放。 */
+    packages?: Array<PackageRuntime | PackageRuntimeOptions | string>;
     /** 当前工程根目录绝对物理路径 */
     projectRoot?: string;
     /** 是否自动加载当前工程（默认为 true） */
@@ -17,15 +20,13 @@ export interface ActionDockHostOptions {
     /** 是否扫描已软链接的外部包（通过 listLinkedPackages，默认为 false） */
     scanLinkedPackages?: boolean;
     /**
-     * 是否以数据目录持有者身份打开包存储：true 时内部创建的 App 存储在打开阶段
+     * 是否以数据目录持有者身份打开包存储：true 时内部创建的 Runtime 存储在打开阶段
      * 收割遗留非终态运行记录。默认 true（Host 本身即持有者）；
      * CLI 查询命令创建旁观 Host 时显式置 false，避免误收割并发 serve 进程的在途运行。
      */
     recoverOrphans?: boolean;
     /** 显式注入的运行时平台适配 */
     platform?: RuntimePlatform;
-    /** 全局最大并发活跃运行数 */
-    maxActiveRuns?: number;
     /** 全局调用嵌套深度限制（默认 16） */
     maxCallDepth?: number;
     /** 全局子任务数限制（默认 64） */
@@ -59,15 +60,27 @@ export interface ActionDockHost {
     /** 静态查询并返回指定 Action 的规范结构与模式定义 */
     describeAction(ref: ActionRef | string): Promise<ActionSpec>;
     /** 静态列出所有已注册包中可用的 Playbook 规程摘要 */
-    listPlaybooks(): Promise<PlaybookSummary[]>;
+    listPlaybooks(options?: {
+        intent?: string;
+        package?: string;
+    }): Promise<PlaybookSummary[]>;
     /** 静态查询并返回指定 Playbook 的规范内容与操作指南 */
     describePlaybook(id: string): Promise<PlaybookSpec>;
     /** 同步执行指定 Action 并等待终态结果 */
-    runAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionResult>;
+    runAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionResult>;
     /** 异步启动指定 Action 并立即返回任务执行票据 */
-    startAction(ref: ActionRef | string, input: JsonValue, options?: ExecuteOptions): Promise<ExecutionTicket>;
+    startAction(ref: ActionRef | string, input: JsonValue, options?: RunOptions): Promise<ExecutionTicket>;
     /** 查询指定运行标识的记录详情 */
     getRun(runId: string): Promise<RunRecord | undefined>;
+    /** 列出运行记录 */
+    listRuns(query?: ListRunsOptions): Promise<RunRecord[]>;
+    /** 清理运行记录 */
+    clearRuns(options?: {
+        packageId?: string;
+        actionId?: string;
+        status?: string;
+        olderThanMs?: number;
+    }): Promise<number>;
     /** 取消指定在运行的任务 */
     cancelRun(runId: string, reason?: string): Promise<CancelResult>;
     /** 订阅指定运行的事件流 */
@@ -76,13 +89,33 @@ export interface ActionDockHost {
         signal?: AbortSignal;
         maxQueueSize?: number;
     }): AsyncIterable<ExecutionEvent>;
-    /** 根据包唯一标识获取指定 App 实例 */
-    getApp(packageId: string): ActionDockApp | undefined;
-    /** 获取所有当前已注册的 App 实例列表 */
-    listApps(): ActionDockApp[];
-    /** 注册新的 App 实例至当前宿主容器 */
-    registerApp(app: ActionDockApp): void;
-    /** 优雅关闭宿主容器。仅对内部创建的 App 实例执行 close 并安全释放底层资源；外部传入借用的 App 实例生命周期完全由调用方负责管理，Host 关闭时仅解绑引用并清理自身内部实例。 */
+    /** 获取配置项视图 */
+    getConfig(packageId: string, key: string): Promise<ConfigValueView>;
+    /** 设置配置项 */
+    setConfig(packageId: string, key: string, value: JsonValue): Promise<void>;
+    /** 删除配置项 */
+    deleteConfig(packageId: string, key: string): Promise<boolean>;
+    /** 列出指定包（或 global）的全部配置项视图 */
+    listConfig(packageId: string): Promise<ConfigValueView[]>;
+    /** 获取状态项 */
+    getState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<T | undefined>;
+    /** 设置状态项 */
+    setState<T extends JsonValue = JsonValue>(packageId: string, actionId: string, key: string, value: T, options?: StateScopeOptions): Promise<void>;
+    /** 删除状态项 */
+    deleteState(packageId: string, actionId: string, key: string, options?: StateScopeOptions): Promise<boolean>;
+    /** 列出状态项键名 */
+    listStateKeys(packageId: string, actionId: string, options?: StateScopeOptions): Promise<string[]>;
+    /** 清理状态项 */
+    clearState(packageId: string, actionId: string, options?: StateScopeOptions): Promise<number>;
+    /** 列出状态项明细 */
+    listStateEntries(packageId: string, options?: any): Promise<StateEntry[]>;
+    /** 根据包唯一标识获取指定 Runtime 实例 */
+    getRuntime(packageId: string): PackageRuntime | undefined;
+    /** 获取所有当前已注册的 Runtime 实例列表 */
+    listRuntimes(): PackageRuntime[];
+    /** 注册新的 Runtime 实例至当前宿主容器 */
+    registerRuntime(runtime: PackageRuntime): void;
+    /** 优雅关闭宿主容器。统一完整关闭所管理的所有 Runtime 实例并安全释放底层资源。 */
     close(options?: {
         graceMs?: number;
     }): Promise<void>;

package/dist/index.d.ts

@@ -1,24 +1,21 @@
-export * from "./catalog/index.js";
-export * from "./doctor/index.js";
-export * from "./errors.js";
-export * from "./execution/index.js";
-export * from "./export/index.js";
-export * from "./filter/index.js";
-export * from "./platform/index.js";
-export * from "./profile/index.js";
-export * from "./project/index.js";
-export * from "./registry/index.js";
-export * from "./runtime/index.js";
-export * from "./schema/index.js";
-export * from "./server/index.js";
-export * from "./storage/index.js";
-export * from "./utils/index.js";
-export * from "./version.js";
-export * from "./app/index.js";
-export * from "./host/index.js";
-export * from "./target/index.js";
-export * from "./ipc/index.js";
-export * from "./process/index.js";
-export * from "./input/index.js";
-export * from "./json/index.js";
-export type { ModuleLoader } from "./runtime/index.js";
+/**
+ * ActionDock 核心引擎公共 API 统一收口与出口定义。
+ *
+ * 遵循架构设计规范铁律：收窄为 Minimal 核心门面，非必要内部工程辅助函数、
+ * 平台大对象驱动与解析器工具移至特定子路径导出（./server, ./project, ./registry,
+ * ./profile, ./graph, ./package），严格杜绝在根导出泄露内部执行与平台上下文机制。
+ */
+export { ACTIONDOCK_VERSION } from "./version.js";
+export { createActionDock, connectActionDock, } from "./service/factory.js";
+export type { ActionDockService, ActionDockService as ActionDock, DiscoveryPort, ExecutionPort, RunsPort, EventsPort, RunEventSubscriptionOptions, ConfigPort, StatePort, CreateActionDockOptions, ConnectActionDockOptions, RemoteServiceOptions, ConfigValueView, ListRunsOptions, StateScopeOptions, } from "./service/types.js";
+export type { ActionRef, ResolvedActionRef, ExecutionResult, RunRecord, ExecutionEvent, } from "@actiondock/sdk";
+export type { RunOptions, ExecutionTicket, CancelResult, } from "./execution/types.js";
+export type { ActionSpec, ActionSummary, PlaybookSpec, PlaybookSummary, PackageInfo, ListActionsOptions, } from "./package/types.js";
+export { createNodePlatform, type NodePlatformOptions, } from "./platform/node.js";
+export { startActionDockServer, } from "./server/server.js";
+export type { ServerOptions, ServerOptions as ActionDockServerOptions, ActionDockServerInstance, } from "./server/types.js";
+export { initProject } from "./project/init.js";
+export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+export type { ProjectConfig, } from "./project/types.js";
+export type { PackageGraph, } from "./catalog/graph.js";
+export { ActionDockError, ProcessError, type ErrorCode, type ActionDockErrorCode, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/index.js

@@ -1,23 +1,19 @@
-export * from "./catalog/index.js";
-export * from "./doctor/index.js";
-export * from "./errors.js";
-export * from "./execution/index.js";
-export * from "./export/index.js";
-export * from "./filter/index.js";
-export * from "./platform/index.js";
-export * from "./profile/index.js";
-export * from "./project/index.js";
-export * from "./registry/index.js";
-export * from "./runtime/index.js";
-export * from "./schema/index.js";
-export * from "./server/index.js";
-export * from "./storage/index.js";
-export * from "./utils/index.js";
-export * from "./version.js";
-export * from "./app/index.js";
-export * from "./host/index.js";
-export * from "./target/index.js";
-export * from "./ipc/index.js";
-export * from "./process/index.js";
-export * from "./input/index.js";
-export * from "./json/index.js";
+/**
+ * ActionDock 核心引擎公共 API 统一收口与出口定义。
+ *
+ * 遵循架构设计规范铁律：收窄为 Minimal 核心门面，非必要内部工程辅助函数、
+ * 平台大对象驱动与解析器工具移至特定子路径导出（./server, ./project, ./registry,
+ * ./profile, ./graph, ./package），严格杜绝在根导出泄露内部执行与平台上下文机制。
+ */
+// 1. 核心版本号单一事实源
+export { ACTIONDOCK_VERSION } from "./version.js";
+// 2. 统一服务门面与聚合契约接口
+export { createActionDock, connectActionDock, } from "./service/factory.js";
+// 5. 原生平台装配与服务启动
+export { createNodePlatform, } from "./platform/node.js";
+export { startActionDockServer, } from "./server/server.js";
+// 6. 核心工程辅助
+export { initProject } from "./project/init.js";
+export { loadProjectConfig, findProjectRoot, } from "./project/loader.js";
+// 8. 统一错误模型与核心标准错误码常量
+export { ActionDockError, ProcessError, PACKAGE_NOT_FOUND, ACTION_PACKAGE_VERSION_CONFLICT, ACTION_NOT_FOUND, ACTION_LOAD_FAILED, ACTION_FAILED, ACTION_TIMEOUT, ACTION_CANCELLED, INPUT_VALIDATION_FAILED, OUTPUT_VALIDATION_FAILED, INPUT_NOT_JSON, OUTPUT_NOT_JSON, ACTION_SUBRUN_LIMIT, ACTION_CALL_CYCLE, UNDECLARED_ACTION_DEPENDENCY, INVALID_ACTION_REF, IDEMPOTENCY_CONFLICT, EXECUTION_FAILED, UNHANDLED_EXECUTION_ERROR, RUN_REPOSITORY_UNAVAILABLE, RUN_PERSISTENCE_FAILED, STANDALONE_ASYNC_UNSUPPORTED, INVOCATION_UNSUPPORTED, HOST_PROCESS_EXITED, EXECUTION_ABORTED, TIMEOUT, NETWORK_ERROR, REMOTE_STREAM_UNAVAILABLE, CAPABILITY_UNAVAILABLE, STATE_KEY_NOT_FOUND, STORAGE_BUSY, PROJECT_BUSY, PROJECT_RECOVERY_REQUIRED, STORAGE_WORKER_EXITED, EVENT_BACKPRESSURE_LIMIT, EVENT_CURSOR_EXPIRED, PROCESS_OUTPUT_LIMIT, PROCESS_SPAWN_ERROR, PROCESS_CANCELLED, PROCESS_TIMEOUT, UNAUTHORIZED, NOT_FOUND, SERVER_ERROR, BAD_REQUEST, PACKAGE_FORBIDDEN, ACTION_FORBIDDEN, PLAYBOOK_NOT_FOUND, REQUEST_TOO_LARGE, ACTION_START_FAILED, ACTION_EXECUTION_ERROR, ACTIONS_LIST_ERROR, PLAYBOOKS_LIST_ERROR, RUNS_LIST_ERROR, RUNS_CLEAR_ERROR, INFO_ERROR, PACKAGES_INFO_ERROR, DOCTOR_ERROR, RUN_INTERRUPTED, CONFIG_ENV_ERROR, CONFIG_LIST_ERROR, CONFIG_SET_ERROR, CONFIG_DELETE_ERROR, STATE_LIST_ERROR, STATE_CLEAR_ERROR, STATE_KEY_ERROR, DATA_DIR_IN_USE, DATA_DIR_RECOVERY_REQUIRED, UNSUPPORTED_STORAGE_SCHEMA, STORED_ERROR_DECODE_FAILED, PROCESS_FAILED, GENERATED_TYPES_OUTDATED, PROTOCOL_UNSUPPORTED, SERVICE_RESULT_UNKNOWN, MCP_TOOL_NAME_COLLISION, ACCESS_DENIED, UNSUPPORTED_CAPABILITY, CONTROL_BUSY, CONTROL_EXPIRED, CONTROL_REVOKED, PROCESS_QUARANTINED, PROCESS_LOST, REQUEST_CONFLICT, INPUT_OUTCOME_UNKNOWN, OUTPUT_GAP, OUTPUT_UNAVAILABLE, INVALID_CURSOR, QUEUE_FULL, QUOTA_EXCEEDED, INPUT_CLOSED, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, INVALID_ARGUMENT, PACKAGE_NOT_ALLOWED, INVALID_PACKAGE_ID, PATH_TRAVERSAL, AMBIGUOUS_STATE_KEY, RUN_NOT_FOUND, RUN_ALREADY_FINISHED, IPC_ERROR, } from "./errors.js";

package/dist/input/advice.d.ts

@@ -52,7 +52,11 @@ export interface CliInputAdviceV1 {
  * @returns 遵循技术设计文档规范的结构化输入建议
  */
 export declare function buildCliInputAdviceV1(schema: unknown): CliInputAdviceV1;
-export declare const FLAT_SAFE_KEY_REGEX: RegExp;
+/**
+ * 扁平编码通用指引文案。
+ * 属性名安全判定统一引用 flat-predicates 的单一事实源（含禁止属性排除），
+ * 禁止在本文件另建独立正则分叉。
+ */
 export declare const FLAT_ENCODING_GUIDELINES: readonly string[];
 /**
  * 单个字段的输入建议明细。