@actiondock/core 2.5.1 → 2.7.0

package/dist/host/routing.d.ts

@@ -0,0 +1,92 @@
+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;
+/**
+ * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ */
+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 packageNotFoundMessage(packageId: string, failedLinkedPackages: ReadonlyMap<string, {
+    path: string;
+    error: string;
+}>): string;
+/**
+ * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
+ */
+export declare function listVisiblePlaybooks(apps: readonly ActionDockApp[], visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}): Promise<PlaybookSummary[]>;
+/**
+ * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
+ * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ */
+export declare function describeVisiblePlaybook(apps: readonly ActionDockApp[], id: string, visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}): Promise<PlaybookSpec>;
+/**
+ * 聚合全部已注册包的元数据信息。
+ */
+export declare function collectPackageInfos(apps: readonly ActionDockApp[]): 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 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ */
+export declare function describeActionAcrossApps(ref: ActionRef | string, apps: readonly ActionDockApp[], visibility: {
+    hostPublicPackageIds: ReadonlySet<string>;
+    resolver?: ActionPackageResolver;
+}, failedLinkedPackages: ReadonlyMap<string, {
+    path: string;
+    error: string;
+}>): Promise<ActionSpec>;
+/** existsSync 的可注入探测依赖（纯函数模块保持可测试性） */
+export type ExistsProbe = (path: string) => boolean;
+/**
+ * 解析宿主自动加载工程根目录：显式指定优先，其次当前进程工作目录探测。
+ */
+export declare function resolveProjectRoot(options: {
+    projectRoot?: string;
+}, detect: () => string | null, exists?: ExistsProbe): string | null;

package/dist/host/routing.js

@@ -0,0 +1,238 @@
+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));
+}
+/**
+ * 宽松解析引用：优先结构化解析，失败时按对象或裸短标识符回退。
+ */
+export function parseRefLoose(ref) {
+    try {
+        return ActionResolver.parseRef(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;
+    }
+    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 packageNotFoundMessage(packageId, failedLinkedPackages) {
+    const failed = failedLinkedPackages.get(packageId);
+    if (failed) {
+        return `Package '${packageId}' not found in host (failed to load from '${failed.path}': ${failed.error})`;
+    }
+    return `Package '${packageId}' not found in host`;
+}
+/**
+ * 静态查询并聚合可见包的 Playbook 规程摘要（带包前缀限定）。
+ */
+export async function listVisiblePlaybooks(apps, 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)) {
+                continue;
+            }
+        }
+        const appPlaybooks = await app.listPlaybooks();
+        for (const item of appPlaybooks) {
+            const qualifiedId = apps.length > 1 && !item.id.includes("/")
+                ? `${app.packageId}/${item.id}`
+                : item.id;
+            results.push({
+                ...item,
+                id: qualifiedId,
+                packageId: app.packageId,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * 静态查询指定 Playbook 规范：支持「包/规程」限定引用与裸短标识符两级解析。
+ * 未声明依赖的传递包、不存在的规程与空匹配分别抛出对应语义错误。
+ */
+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`);
+        }
+        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 {
+            // 忽略未匹配的包
+        }
+    }
+    throw new Error(`Playbook '${id}' not found in any registered package`);
+}
+/**
+ * 聚合全部已注册包的元数据信息。
+ */
+export async function collectPackageInfos(apps) {
+    return Promise.all(apps.map((app) => app.info()));
+}
+/**
+ * 构造失配类错误响应载荷（ACTION_NOT_FOUND / AMBIGUOUS_ACTION_REF 等）。
+ */
+export function buildRuntimeError(code, message, details) {
+    const error = { code, message };
+    if (details !== undefined) {
+        error.details = 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 规范：包限定引用直查，裸短标识符跨包消歧后返回。
+ */
+export async function describeActionAcrossApps(ref, apps, visibility, failedLinkedPackages) {
+    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,
+        };
+    }
+    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;
+            }
+        }
+    }
+    if (matches.length === 1) {
+        return {
+            ...matches[0].spec,
+            packageId: matches[0].app.packageId,
+        };
+    }
+    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;
+    }
+    throw new Error(`ACTION_NOT_FOUND: Action '${parsed.actionId}' not found in any registered package`);
+}
+/**
+ * 解析宿主自动加载工程根目录：显式指定优先，其次当前进程工作目录探测。
+ */
+export function resolveProjectRoot(options, detect, exists = existsSync) {
+    let root = options.projectRoot;
+    if (!root) {
+        const detected = detect();
+        if (detected) {
+            root = detected;
+        }
+    }
+    if (!root || !exists(root)) {
+        return null;
+    }
+    return root;
+}

package/dist/host/types.d.ts

@@ -16,6 +16,12 @@ export interface ActionDockHostOptions {
     autoLoadCurrentProject?: boolean;
     /** 是否扫描已软链接的外部包（通过 listLinkedPackages，默认为 false） */
     scanLinkedPackages?: boolean;
+    /**
+     * 是否以数据目录持有者身份打开包存储：true 时内部创建的 App 存储在打开阶段
+     * 收割遗留非终态运行记录。默认 true（Host 本身即持有者）；
+     * CLI 查询命令创建旁观 Host 时显式置 false，避免误收割并发 serve 进程的在途运行。
+     */
+    recoverOrphans?: boolean;
     /** 显式注入的运行时平台适配 */
     platform?: RuntimePlatform;
     /** 全局最大并发活跃运行数 */
@@ -44,6 +50,8 @@ export interface ActionDockHostOptions {
  * 作为多包环境下的全局协调中枢，负责多包生命周期、完全限定引用路由、依赖校验与配额管理。
  */
 export interface ActionDockHost {
+    /** 宿主容器初始化配置项（只读） */
+    readonly options?: ActionDockHostOptions;
     /** 获取所有已注册包的元数据信息列表 */
     info(): Promise<PackageInfo[]>;
     /** 静态列出所有已注册包中可用的 Action 摘要 */

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export * from "./profile/index.js";
 export * from "./project/index.js";
 export * from "./registry/index.js";
 export * from "./runtime/index.js";
-export * from "./schema/validator.js";
+export * from "./schema/index.js";
 export * from "./server/index.js";
 export * from "./storage/index.js";
 export * from "./utils/index.js";
@@ -19,4 +19,6 @@ 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";

package/dist/index.js

@@ -9,7 +9,7 @@ export * from "./profile/index.js";
 export * from "./project/index.js";
 export * from "./registry/index.js";
 export * from "./runtime/index.js";
-export * from "./schema/validator.js";
+export * from "./schema/index.js";
 export * from "./server/index.js";
 export * from "./storage/index.js";
 export * from "./utils/index.js";
@@ -19,3 +19,5 @@ 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";

package/dist/input/advice.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 单个字段的输入建议明细（v1 机器契约）。
+ */
+export interface CliInputFieldAdviceV1 {
+    /** 字段路径（属性名） */
+    path: string;
+    /** 是否允许作为输入传入 */
+    inputAllowed: boolean;
+    /** 是否可通过扁平语法安全赋值 */
+    flatSafe: boolean;
+    /** 是否为必填字段 */
+    required?: boolean;
+    /** 字段模式类型 */
+    type?: string;
+    /** 赋值操作符（"=" 或 ":="） */
+    operator?: "=" | ":=";
+    /** 编码类型标识 */
+    encoding?: "string" | "json-number" | "json-boolean" | "json-null" | "json-array" | "json-object" | "json" | string;
+    /** 赋值模板样例 */
+    assignmentTemplate?: string;
+    /** 无法通过扁平赋值或被禁止的原因代码 */
+    reason?: "FORBIDDEN_PROPERTY" | "UNSAFE_FLAT_PROPERTY" | "PROPERTY_SCHEMA_FALSE" | string;
+    /** 推荐的降级输入通道 */
+    fallback?: "stdin-json" | null;
+    /** 字段描述信息 */
+    description?: string;
+    /** 人类提示信息 */
+    hint?: string;
+}
+/**
+ * Action 输入模式编码顾问分析报告（v1 机器契约）。
+ */
+export interface CliInputAdviceV1 {
+    version: 1;
+    analysisMode: "declared-properties-only";
+    analysisStatus: "ok" | "unsupported" | "malformed";
+    analysisCode?: "MALFORMED_SCHEMA" | "COMPLEX_SCHEMA" | "UNSUPPORTED_SCHEMA_SHAPE";
+    analysisMessage?: string;
+    schemaState: "absent" | "reject-all" | "any" | "object" | "json-only" | "complex";
+    inputFeasibility: "known-impossible" | "possible-or-unknown";
+    flatAvailable: boolean;
+    requiredSatisfiable: boolean | null;
+    flatCandidate: boolean;
+    schemaRecommendedMode: "none" | "flat" | "full-json";
+    feasibilityCode?: "SCHEMA_REJECTS_ALL" | "REQUIRED_FIELD_FORBIDDEN" | "REQUIRED_FIELD_REJECTS_ALL" | "REQUIRED_FIELD_DISALLOWED_BY_ADDITIONAL_PROPERTIES";
+    fields: CliInputFieldAdviceV1[];
+}
+/**
+ * 依据 inputSchema 构造 v1 版本的 Action 输入编码顾问报告（机器契约）。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 遵循技术设计文档规范的结构化输入建议
+ */
+export declare function buildCliInputAdviceV1(schema: unknown): CliInputAdviceV1;
+export declare const FLAT_SAFE_KEY_REGEX: RegExp;
+export declare const FLAT_ENCODING_GUIDELINES: readonly string[];
+/**
+ * 单个字段的输入建议明细。
+ */
+export interface ActionInputFieldAdvice {
+    /** 字段路径（属性名） */
+    path: string;
+    /** 字段类型字符串 */
+    type: string;
+    /** 是否为必填字段 */
+    required: boolean;
+    /** 字段名是否满足扁平编码安全规范 */
+    flatSafe: boolean;
+    /** 编码模板（如 "name=TEXT"、"age:=NUMBER"、"meta:=JSON"），非直接可执行 token */
+    assignmentTemplate?: string;
+    /** 人类说明文字，如 "大型结构建议使用 --input-file" */
+    hint?: string;
+    /** 字段描述信息 */
+    description?: string;
+}
+/**
+ * Action 输入模式整体编码顾问分析报告。
+ */
+export interface ActionInputAdvice {
+    /** 根模式是否支持扁平入参赋值（仅当根模式为对象且所有 required 字段均具备 flatSafe 赋值方案时为 true） */
+    flatSupported: boolean;
+    /** 是否存在至少一个可扁平化的字段 */
+    hasFlatFields: boolean;
+    /** 字段明细清单 */
+    fields: ActionInputFieldAdvice[];
+    /** 所有必填字段的编码模板数组 */
+    requiredTemplates: string[];
+    /** 可选字段的编码模板数组 */
+    optionalTemplates: string[];
+    /** 结构化提示与降级说明清单 */
+    notes: string[];
+}
+/**
+ * 依据 inputSchema 构造统一的 Action 输入编码建议。
+ *
+ * @param schema Action 的 inputSchema 定义
+ * @returns 结构化编码建议报告
+ */
+export declare function buildActionInputAdvice(schema: unknown): ActionInputAdvice;
+export { formatActionDetail } from "./describe.js";