@actiondock/core 2.0.12 → 2.2.0

package/dist/registry/resolve.js

@@ -0,0 +1,195 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findProjectRoot, loadActions, loadPlaybooks, loadProjectConfig } from "../project/loader.js";
+import { loadManifest } from "../project/manifest.js";
+import { getPackageSlug } from "../utils/index.js";
+/**
+ * 实体解析唯一流程（生成器表达）：
+ * 当前项目探测 → scoped 标识符拆分 → 注册表精确匹配 → 遍历链接包 →
+ * 单命中返回、多命中报错、零命中报错。
+ *
+ * 仅将可能异步的操作（探针、链接列表获取）以 thunk 形式 yield，
+ * 由 runFlowSync / runFlowAsync 双驱动器分别以同步调用或 await 方式执行。
+ */
+export function* resolveEntityFlow(opts) {
+    const { identifier, entityNoun } = opts;
+    // 当前项目（或其父级项目）优先探测
+    const currentRoot = findProjectRoot(opts.cwd);
+    if (currentRoot) {
+        try {
+            const config = loadProjectConfig(currentRoot);
+            const hit = yield () => opts.probe(currentRoot, config, identifier);
+            if (hit !== undefined) {
+                return opts.buildResult(currentRoot, config.id, identifier, hit);
+            }
+        }
+        catch {
+            // 当前项目配置损坏或探测失败：忽略并继续注册表查找
+        }
+    }
+    // scoped 标识符拆分：<package-id>/<entity-id> 或 <package-id>:<entity-id>
+    let targetPackage;
+    let pureEntityId = identifier;
+    if (identifier.includes("/")) {
+        const slashIdx = identifier.lastIndexOf("/");
+        targetPackage = identifier.slice(0, slashIdx);
+        pureEntityId = identifier.slice(slashIdx + 1);
+    }
+    else if (identifier.includes(":")) {
+        const colonIdx = identifier.lastIndexOf(":");
+        targetPackage = identifier.slice(0, colonIdx);
+        pureEntityId = identifier.slice(colonIdx + 1);
+    }
+    const linkedList = yield () => opts.listLinkedPackages();
+    if (targetPackage) {
+        let targetRoot;
+        let targetPkgId = targetPackage;
+        if (currentRoot) {
+            try {
+                const config = loadProjectConfig(currentRoot);
+                if (config.id === targetPackage || getPackageSlug(config.id) === targetPackage) {
+                    targetRoot = currentRoot;
+                    targetPkgId = config.id;
+                }
+            }
+            catch {
+                // 当前项目配置损坏：忽略，回退注册表匹配
+            }
+        }
+        let pkg;
+        if (!targetRoot) {
+            pkg = linkedList.find((p) => p.id === targetPackage || getPackageSlug(p.id) === targetPackage);
+            if (pkg && existsSync(pkg.path)) {
+                targetRoot = pkg.path;
+                targetPkgId = pkg.id;
+            }
+        }
+        if (!targetRoot || !existsSync(targetRoot)) {
+            throw new Error(`Linked package '${targetPackage}' not found or path no longer exists (${pkg?.path || "unregistered"}). Run 'ad link' in the package directory.`);
+        }
+        const config = loadProjectConfig(targetRoot);
+        const hit = yield () => opts.probe(targetRoot, config, pureEntityId);
+        if (hit === undefined) {
+            throw new Error(`${entityNoun} '${pureEntityId}' not found in package '${targetPkgId}' (${targetRoot})`);
+        }
+        return opts.buildResult(targetRoot, targetPkgId, pureEntityId, hit);
+    }
+    // 遍历全部链接包搜索
+    const matches = [];
+    for (const pkg of linkedList) {
+        if (!existsSync(pkg.path))
+            continue;
+        try {
+            const config = loadProjectConfig(pkg.path);
+            const hit = yield () => opts.probe(pkg.path, config, identifier);
+            if (hit !== undefined) {
+                matches.push({ entry: pkg, entityId: identifier, value: hit });
+            }
+        }
+        catch {
+            // 忽略损坏的链接包：单个包配置或探测异常不应中断其余包的匹配
+        }
+    }
+    if (matches.length === 1) {
+        const m = matches[0];
+        return opts.buildResult(m.entry.path, m.entry.id, m.entityId, m.value);
+    }
+    if (matches.length > 1) {
+        const pkgList = matches.map((m) => `'${m.entry.id}'`).join(", ");
+        throw new Error(`${entityNoun} '${identifier}' is provided by multiple linked packages: ${pkgList}. Please specify using '<package-id>/${identifier}'.`);
+    }
+    if (currentRoot) {
+        throw new Error(`${entityNoun} '${identifier}' not found in current project or any linked packages`);
+    }
+    else {
+        throw new Error(`${entityNoun} '${identifier}' not found. You are not in an ActionDock project, and no linked package provides '${identifier}'. Use 'ad link' to register your package.`);
+    }
+}
+/**
+ * 同步驱动器：逐个调用 thunk 并把结果回灌生成器，
+ * thunk 抛出的异常经 it.throw 回灌生成器内部的 try/catch 处理。
+ * 同步流程中误注入异步 thunk 时立即抛错，避免 Promise 被当作命中值静默错判。
+ */
+export function runFlowSync(flow) {
+    let step = flow.next();
+    while (!step.done) {
+        const value = step.value();
+        if (value !== undefined && typeof value.then === "function") {
+            throw new Error("Synchronous resolution received an asynchronous effect; check the injected probe and linked-list loader");
+        }
+        let next;
+        try {
+            next = flow.next(value);
+        }
+        catch (err) {
+            next = flow.throw(err);
+        }
+        step = next;
+    }
+    return step.value;
+}
+/**
+ * 异步驱动器：await 每个 thunk 后回灌结果，拒绝原因经 it.throw 回灌。
+ */
+export async function runFlowAsync(flow) {
+    let step = flow.next();
+    while (!step.done) {
+        let next;
+        try {
+            next = flow.next(await step.value());
+        }
+        catch (err) {
+            next = flow.throw(err);
+        }
+        step = next;
+    }
+    return step.value;
+}
+/**
+ * Action 探针（同步）：manifest 声明优先，其次探测源码文件是否落盘。
+ */
+export function probeActionSync(projectRoot, config, actionId) {
+    const manifest = loadManifest(projectRoot);
+    if (manifest?.actions && actionId in manifest.actions) {
+        return true;
+    }
+    const dir = join(projectRoot, config.actionsDir || "actions");
+    if (!existsSync(dir)) {
+        return undefined;
+    }
+    if (actionId.includes("..") || actionId.startsWith("/") || actionId.startsWith("\\")) {
+        return undefined;
+    }
+    if (existsSync(join(dir, `${actionId}.ts`)) || existsSync(join(dir, `${actionId}.js`))) {
+        return true;
+    }
+    const relFile = actionId.replace(/\./g, "/");
+    if (existsSync(join(dir, `${relFile}.ts`)) || existsSync(join(dir, `${relFile}.js`))) {
+        return true;
+    }
+    return undefined;
+}
+/**
+ * Action 探针（异步）：manifest 声明优先，其次加载源码模块；
+ * 模块加载失败时回退同步探测，保证与同步路径判定一致。
+ */
+export async function probeActionAsync(projectRoot, config, actionId) {
+    const manifest = loadManifest(projectRoot);
+    if (manifest?.actions && actionId in manifest.actions) {
+        return true;
+    }
+    try {
+        const actions = await loadActions(projectRoot, config.actionsDir, { autoInstall: false });
+        return actions.has(actionId) ? true : undefined;
+    }
+    catch {
+        return probeActionSync(projectRoot, config, actionId);
+    }
+}
+/**
+ * Playbook 探针：以 actiondock.json 的 playbooks 声明为唯一事实源，命中返回规程定义。
+ */
+export function probePlaybook(projectRoot, config, playbookId) {
+    const playbooks = loadPlaybooks(projectRoot, config.playbooksDir);
+    return playbooks.get(playbookId);
+}

package/dist/registry/scan.d.ts

@@ -0,0 +1,38 @@
+import { loadProjectConfig } from "../project/loader.js";
+import type { LinkedPackageEntry } from "./types.js";
+/**
+ * 目录扫描时跳过的非项目目录（依赖缓存、构建产物与编辑器配置等）。
+ */
+export declare const IGNORED_SCAN_DIRS: Set<string>;
+/**
+ * 递归扫描包含 actiondock.json 的子项目根目录（同步版本）。
+ */
+export declare function discoverProjects(dir: string, maxDepth?: number): string[];
+/**
+ * 递归扫描包含 actiondock.json 的子项目根目录（异步版本，逻辑与同步版一致）。
+ */
+export declare function discoverProjectsAsync(dir: string, maxDepth?: number): Promise<string[]>;
+/**
+ * 扫描并加载全部子项目配置（同步版本）。
+ * 损坏项目（配置缺失或非法）跳过不中断：注册表操作面对的是外部任意目录，
+ * 单个损坏项目不应阻塞其余项目的正常链接与解析。
+ */
+export declare function discoverProjectConfigs(dir: string, maxDepth?: number): Array<{
+    root: string;
+    config: ReturnType<typeof loadProjectConfig>;
+}>;
+/**
+ * 扫描并加载全部子项目配置（异步版本，跳过策略与同步版一致）。
+ */
+export declare function discoverProjectConfigsAsync(dir: string, maxDepth?: number): Promise<Array<{
+    root: string;
+    config: ReturnType<typeof loadProjectConfig>;
+}>>;
+/**
+ * 由项目配置构造注册表链接条目（纯函数，无副作用）。
+ */
+export declare function buildLinkedPackageEntry(config: ReturnType<typeof loadProjectConfig>, path: string, linkedAt: string, workspaceRoot?: string): LinkedPackageEntry;
+/**
+ * 异步探测路径是否存在。
+ */
+export declare function pathExistsAsync(path: string): Promise<boolean>;

package/dist/registry/scan.js

@@ -0,0 +1,135 @@
+import { readdirSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { loadProjectConfig } from "../project/loader.js";
+/**
+ * 目录扫描时跳过的非项目目录（依赖缓存、构建产物与编辑器配置等）。
+ */
+export const IGNORED_SCAN_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".gemini",
+    ".actiondock",
+    ".claude",
+    ".idea",
+    ".vscode",
+]);
+/**
+ * 递归扫描包含 actiondock.json 的子项目根目录（同步版本）。
+ */
+export function discoverProjects(dir, maxDepth = 3) {
+    const results = [];
+    const resolvedDir = resolve(dir);
+    function walk(currentDir, currentDepth) {
+        if (currentDepth > maxDepth)
+            return;
+        try {
+            const entries = readdirSync(currentDir, { withFileTypes: true });
+            const hasActiondock = entries.some((e) => e.isFile() && e.name === "actiondock.json");
+            if (hasActiondock && currentDir !== resolvedDir) {
+                results.push(currentDir);
+                return; // 不再向项目内部子目录递归
+            }
+            for (const entry of entries) {
+                if (entry.isDirectory() && !IGNORED_SCAN_DIRS.has(entry.name)) {
+                    walk(join(currentDir, entry.name), currentDepth + 1);
+                }
+            }
+        }
+        catch {
+            // 忽略无法读取的目录：扫描是尽力而为的探测，单目录不可读不应中断整体发现
+        }
+    }
+    walk(resolvedDir, 1);
+    return results;
+}
+/**
+ * 递归扫描包含 actiondock.json 的子项目根目录（异步版本，逻辑与同步版一致）。
+ */
+export async function discoverProjectsAsync(dir, maxDepth = 3) {
+    const results = [];
+    const resolvedDir = resolve(dir);
+    async function walk(currentDir, currentDepth) {
+        if (currentDepth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            // 忽略无法读取的目录：扫描是尽力而为的探测，单目录不可读不应中断整体发现
+            return;
+        }
+        const hasActiondock = entries.some((e) => e.isFile() && e.name === "actiondock.json");
+        if (hasActiondock && currentDir !== resolvedDir) {
+            results.push(currentDir);
+            return; // 不再向项目内部子目录递归
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() && !IGNORED_SCAN_DIRS.has(entry.name)) {
+                await walk(join(currentDir, entry.name), currentDepth + 1);
+            }
+        }
+    }
+    await walk(resolvedDir, 1);
+    return results;
+}
+/**
+ * 扫描并加载全部子项目配置（同步版本）。
+ * 损坏项目（配置缺失或非法）跳过不中断：注册表操作面对的是外部任意目录，
+ * 单个损坏项目不应阻塞其余项目的正常链接与解析。
+ */
+export function discoverProjectConfigs(dir, maxDepth = 3) {
+    const results = [];
+    for (const root of discoverProjects(dir, maxDepth)) {
+        try {
+            results.push({ root, config: loadProjectConfig(root) });
+        }
+        catch {
+            // 跳过损坏项目：其 actiondock.json 缺失必要字段或非法，无法构成有效链接条目
+        }
+    }
+    return results;
+}
+/**
+ * 扫描并加载全部子项目配置（异步版本，跳过策略与同步版一致）。
+ */
+export async function discoverProjectConfigsAsync(dir, maxDepth = 3) {
+    const results = [];
+    for (const root of await discoverProjectsAsync(dir, maxDepth)) {
+        try {
+            results.push({ root, config: loadProjectConfig(root) });
+        }
+        catch {
+            // 跳过损坏项目：其 actiondock.json 缺失必要字段或非法，无法构成有效链接条目
+        }
+    }
+    return results;
+}
+/**
+ * 由项目配置构造注册表链接条目（纯函数，无副作用）。
+ */
+export function buildLinkedPackageEntry(config, path, linkedAt, workspaceRoot) {
+    return {
+        id: config.id,
+        name: config.name || config.id,
+        version: config.version || "0.0.0",
+        path,
+        linkedAt,
+        ...(workspaceRoot ? { workspaceRoot } : {}),
+    };
+}
+/**
+ * 异步探测路径是否存在。
+ */
+export async function pathExistsAsync(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/registry/types.d.ts

@@ -113,5 +113,5 @@ export interface ResolvedPlaybookProject {
     /** 匹配到的 Playbook ID */
     playbookId: string;
     /** Playbook 实体数据 */
-    playbook: import("../project/types").PlaybookDefinition;
+    playbook: import("../project/types.js").PlaybookDefinition;
 }

package/dist/registry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/action-collection.d.ts

@@ -0,0 +1,27 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import type { ActionSpec } from "../app/types.js";
+/**
+ * 归一化 Action 集合的产物结构。
+ */
+export interface NormalizedActionCollection {
+    /** Action 标识到定义的映射表 */
+    actionsMap: Map<string, ActionDefinition>;
+    /** Action 标识到元数据规范的映射表 */
+    actionSpecs: Record<string, ActionSpec>;
+}
+/**
+ * 将任意形态的 Action 集合输入归一化为统一结构。
+ *
+ * 支持三种输入形态：
+ * - Map 映射表：键即 Action 标识。
+ * - 对象数组：每项以 id 字段定位，action 字段或自身作为定义。
+ * - 普通对象：键值对即标识与定义。
+ *
+ * 作为 app 层与独立运行分发器的归一化逻辑单一事实源（Runner 构造仅接受 Map 形态，无需归一化）。
+ */
+export declare function normalizeActionCollection(rawActions?: Map<string, ActionDefinition> | Array<({
+    id: string;
+    action?: ActionDefinition;
+} & Partial<ActionSpec>) | (ActionDefinition & {
+    id: string;
+})> | Record<string, ActionDefinition>): NormalizedActionCollection;

package/dist/runtime/action-collection.js

@@ -0,0 +1,57 @@
+/**
+ * 将任意形态的 Action 集合输入归一化为统一结构。
+ *
+ * 支持三种输入形态：
+ * - Map 映射表：键即 Action 标识。
+ * - 对象数组：每项以 id 字段定位，action 字段或自身作为定义。
+ * - 普通对象：键值对即标识与定义。
+ *
+ * 作为 app 层与独立运行分发器的归一化逻辑单一事实源（Runner 构造仅接受 Map 形态，无需归一化）。
+ */
+export function normalizeActionCollection(rawActions) {
+    const actionsMap = new Map();
+    const actionSpecs = {};
+    if (!rawActions) {
+        return { actionsMap, actionSpecs };
+    }
+    if (rawActions instanceof Map) {
+        for (const [k, v] of rawActions) {
+            actionsMap.set(k, v);
+            actionSpecs[k] = {
+                id: k,
+                description: v.description,
+                inputSchema: v.inputSchema,
+                outputSchema: v.outputSchema,
+            };
+        }
+        return { actionsMap, actionSpecs };
+    }
+    if (Array.isArray(rawActions)) {
+        for (const item of rawActions) {
+            const id = item.id;
+            const act = item.action ?? item;
+            if (id) {
+                actionsMap.set(id, act);
+                actionSpecs[id] = {
+                    id,
+                    description: item.description ?? act.description,
+                    inputSchema: item.inputSchema ?? act.inputSchema,
+                    outputSchema: item.outputSchema ?? act.outputSchema,
+                };
+            }
+        }
+        return { actionsMap, actionSpecs };
+    }
+    if (typeof rawActions === "object") {
+        for (const [k, v] of Object.entries(rawActions)) {
+            actionsMap.set(k, v);
+            actionSpecs[k] = {
+                id: k,
+                description: v.description,
+                inputSchema: v.inputSchema,
+                outputSchema: v.outputSchema,
+            };
+        }
+    }
+    return { actionsMap, actionSpecs };
+}

package/dist/runtime/clock.d.ts

@@ -17,5 +17,3 @@ export declare class SystemClock implements Clock {
     monotonic(): number;
     sleep(ms: number): Promise<void>;
 }
-export declare function getSystemClock(): Clock;
-export declare function setSystemClock(clock: Clock): void;

package/dist/runtime/clock.js

@@ -0,0 +1,17 @@
+/**
+ * 生产环境系统时钟实现。
+ */
+export class SystemClock {
+    now() {
+        return new Date();
+    }
+    monotonic() {
+        if (typeof performance !== "undefined" && typeof performance.now === "function") {
+            return performance.now();
+        }
+        return Date.now();
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/runtime/context.d.ts

@@ -1,11 +1,11 @@
-import type { ActionContext, ActionDefinition, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
-import type { ProjectConfig } from "../project/types";
-import type { RuntimeStorage } from "../storage/types";
+import type { ActionContext, ActionRef, Config, Logger, ProcessAPI, ProgressReporter, StateStore } from "@actiondock/sdk";
+import type { ProjectConfig } from "../project/types.js";
+import type { RuntimeStorage } from "../storage/types.js";
 /**
  * 生产级配置解析器实现。
  * 严格践行 5 层配置解析优先级链：
  * 1. CLI 临时参数覆写 (Overrides)
- * 2. 本地项目持久化存储 (Local SQLite: .actiondock/runtime.db)
+ * 2. 包级持久化存储 (Package SQLite: ~/.actiondock/data/<package-id>/runtime.db)
  * 3. 全局共享持久化存储 (Global SQLite: ~/.actiondock/global.db)
  * 4. 操作系统环境变量 (process.env: 显式绑定 / 包名前缀 / SNAKE_CASE / 类型转换)
  * 5. 项目默认配置 (actiondock.json 中的 default 字段)
@@ -20,6 +20,16 @@ export declare class RuntimeConfig implements Config {
     get<T = unknown>(key: string): T | undefined;
     get<T = unknown>(key: string, defaultValue: T): T;
     has(key: string): boolean;
+    /**
+     * 结构化解析指定配置项的来源与取值视图。
+     *
+     * 作为五层优先级链的唯一事实源读取视图，供 app 层 getConfig 安全视图直接委托，
+     * 避免重复实现解析链导致行为漂移。
+     */
+    describe<T = unknown>(key: string): {
+        source: "overrides" | "package" | "global" | "env" | "default";
+        value: T | undefined;
+    };
 }
 /**
  * 生产级状态存储实现，将状态持久化到 SQLite 中，完整支持命名空间分段隔离与 TTL。
@@ -52,6 +62,7 @@ export declare class StderrLogger implements Logger {
  * 创建 ActionContext 上下文所需的选项集合。
  */
 export interface ContextOptions {
+    actionId?: string;
     storage: RuntimeStorage;
     globalStorage?: RuntimeStorage;
     overrides?: Record<string, unknown>;
@@ -64,7 +75,7 @@ export interface ContextOptions {
     process?: ProcessAPI;
     progress?: ProgressReporter;
     logger?: Logger;
-    onActionInvoke?: (action: ActionDefinition | ActionRef | string, input: unknown, parentRunId?: string) => Promise<unknown>;
+    onActionInvoke?: (action: ActionRef | string, input: unknown, parentRunId?: string) => Promise<unknown>;
 }
 /**
  * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。