@actiondock/core 2.0.1 → 2.0.3

package/README.md

@@ -1,50 +1,82 @@
 # @actiondock/core
 
-The core engine and domain kernel of ActionDock 2.0.
+ActionDock 2.0 核心领域模型与调度引擎。
 
-[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.2-black?logo=bun)](https://bun.sh/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-`@actiondock/core` provides the project loader, runtime execution engine (`ActionRunner`), native SQLite persistence, standalone binary compiler, remote HTTP server/client, and Agent Skill exporter.
+`@actiondock/core` 承载 ActionDock 的领域对象、状态机、持久化接口抽象与执行服务，是与具体宿主环境解耦的通用内核。
 
-> **Role & Usage Context**:
-> - **Authoring Actions**: Use [`@actiondock/sdk`](../sdk) for defining actions, testing with in-memory harness, and zero-dependency action packages.
-> - **CLI Toolchain**: Use [`@actiondock/cli`](../cli) (`ad`) for command-line workflows.
-> - **Engine & Embedding**: Use `@actiondock/core` when you need programmatic access to the ActionRunner engine, project loader, or custom server integrations.
->
-> **Runtime requirement**: [Bun](https://bun.sh/) >= 1.2.0 is required (`@actiondock/core` leverages native `bun:sqlite` and Bun runtime APIs).
+---
+
+## 核心领域模型
+
+- `ProjectConfig`：定义在 `actiondock.json` 中的项目规范，包含包标识、名称、版本号、目录配置以及配置项元数据。
+- `PlaybookDefinition`：智能体操作规程定义，由 Markdown 文本与其头部 YAML 元数据构成，静态记录任务步骤与调用的 Action 依赖列表。
+- `ActionDockManifest`：`actiondock.manifest.json` 声明式元数据清单模型，记录每个 Action 的入口路径、功能描述、输入输出模式、静态依赖与协议注解，作为无副作用模块发现与构建规划的唯一事实源。
+- `ConfigItemDefinition`：单项配置规范，涵盖默认值、类型约束、敏感脱敏标记及绑定的外部环境变量。
 
 ---
 
-## Installation
+## 关键抽象接口
+
+### SqliteDriver 驱动接口
+
+解耦底层数据库实现，提供一致的同步参数化执行与事务契约：
+
+- `exec(sql: string): void`：执行无返回值的 SQL 语句。
+- `prepare(sql: string): SqliteStatement`：编译 SQL 模板，生成支持 `run`、`get`、`all` 方法的预编译语句对象。
+- `transaction<T>(fn: () => T): T`：同步事务执行器，在出现异常时自动回滚，并在驱动层严格拦截异步 Promise 以避免事务泄漏。
+- `close(): void`：释放数据库连接与文件句柄。
+
+### ProcessExecutor 进程执行器接口
 
-```bash
-bun add @actiondock/core
-```
+抽象跨平台的子进程操作，统一下列能力：
+
+- `exec(command, args, options): Promise<ProcessResult>`：执行外部命令并捕获标准输出与标准错误流，支持标准输入流透传、执行超时控制、取消信号响应以及缓冲区防爆保护。
+- `spawnDetached(options): Promise<DetachedProcessResult>`：独立拉起后台长周期守护进程，通过轮询就绪探针确认服务启动状态。
 
 ---
 
-## Key Modules
+## 执行核心与状态机
+
+### ActionRunner 执行状态机
+
+`ActionRunner` 是单个 Action 执行的核心引擎，负责完整的生命周期状态流转与契约保障：
+
+- **调用链环路检测**：基于调用栈跟踪，当检测到依赖循环（例如 A 动作调用 B 动作，B 动作反向调用 A 动作）时立即拦截并返回错误信封。
+- **模式严格校验**：在 Action 执行前使用 Ajv 校验输入数据是否满足 `inputSchema` 契约，校验失败时直接阻断并生成结构化诊断信息。
+- **运行记录持久化**：初始化运行时在 SQLite 中写入 `running` 状态记录，并在结束时流转至对应终态。
+- **生命周期状态转换**：
+  - 启动阶段：状态置为 `running`，绑定超时定时器与取消信号。
+  - 正常完成：捕获返回值，更新状态为 `success` 并持久化输出快照。
+  - 业务抛错：捕获异常，更新状态为 `failed` 并提取结构化错误码与调用栈。
+  - 超时中止：超时定时器触发，发送取消信号并更新状态为 `timed_out`。
+  - 主动取消：外部请求取消，更新状态为 `cancelled`。
+- **上下文环境合成**：动态构建 `ActionContext`，集成配置优先级解析器、状态存储器与标准错误流日志记录器。
 
-- **Project Loader** (`loadProjectConfig`, `loadActions`, `loadPlaybooks`, `initProject`): Discovers and parses Action Packages.
-- **Runtime Execution** (`ActionRunner`, `createActionContext`, `createStandaloneRuntime`): Manages the full action execution lifecycle, schema validation, cycle detection, timeouts, and JSON envelopes.
-- **Storage** (`SqliteRuntimeStorage`, `createStorage`, `createGlobalStorage`): Native SQLite KV store with namespaces, TTL, and WAL mode.
-- **Standalone Builder** (`buildProject`): Uses Bun's native bundler to compile actions into a single standalone binary.
-- **Skill Exporter** (`exportSkill`): Generates self-contained Agent Skills with Playbook SOPs.
-- **Profile & Remote Runner** (`ProfileManager`, `ActionServer`, `executeRemoteAction`): Multi-cloud remote execution with token authentication.
+### DefaultExecutionService 统一执行服务
+
+负责系统层面的并发控制、任务追踪与生命周期协同：
+
+- **并发度控制**：维护活跃任务表，支持配置系统最大并发上限，超限时合理排队或拒接。
+- **全链路追踪**：为每次执行分配全局唯一的根运行标识与父子调用关联。
+- **协同取消传播**：支持根据运行标识获取执行句柄，向下游所有派生子任务广播取消信号。
+- **事件汇聚分发**：将执行过程中的状态变更事件统一推送到可插拔的事件接收器中。
 
 ---
 
-## 📖 Documentation
+## 运行时可插拔设计
+
+`@actiondock/core` 保持平台中立，不绑定任何特定运行环境：
 
-- [Runtime Architecture](../../docs/architecture/runtime.md)
-- [Storage & Persistence Guide](../../docs/developer/storage.md)
-- [Standalone Binary Build](../../docs/developer/build-and-export.md)
-- [HTTP Server & Remote Dispatch](../../docs/consumer/http-service.md)
+- 在日常使用与 Node.js 运行时中，通过 `@actiondock/runtime-node` 注入基于 `node:sqlite` 与 `execa` 的驱动。
+- 在独立二进制编译产物中，通过 `@actiondock/runtime-bun` 注入基于 `bun:sqlite` 与 `Bun.spawn` 的驱动。
+- 在自动化测试中，通过 `@actiondock/testing` 注入纯内存存储驱动与模拟进程执行器。
 
 ---
 
-## License
+## 开源协议
 
-[Apache-2.0](../../LICENSE) © team4u
+本项目采用 Apache-2.0 开源协议。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/core",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "ActionDock Core Engine - Project loader, runtime execution, SQLite storage, standalone builder, and skill exporter",
   "type": "module",
   "main": "./src/index.ts",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "engines": {
-    "bun": ">=1.2.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/build/builder.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
@@ -142,15 +143,18 @@ export async function buildProject(options: BuildOptions): Promise<BuildResult>
     buildArgs.push(`--target=${formattedTarget}`);
   }
 
-  const proc = Bun.spawnSync(buildArgs, {
+  const proc = spawnSync(buildArgs[0], buildArgs.slice(1), {
     cwd: root,
-    stdout: "pipe",
-    stderr: "pipe",
+    stdio: "pipe",
   });
 
-  if (proc.exitCode !== 0) {
-    const errText = proc.stderr.toString() || proc.stdout.toString();
-    throw new Error(`Bun compile failed (exit code ${proc.exitCode}):\n${errText}`);
+  if (proc.error) {
+    throw new Error(`Bun compile failed to spawn: ${proc.error.message}`);
+  }
+
+  if (proc.status !== 0) {
+    const errText = proc.stderr?.toString() || proc.stdout?.toString() || "Unknown error";
+    throw new Error(`Bun compile failed (exit code ${proc.status}):\n${errText}`);
   }
 
   // Compile artifact resolution (on Windows bun compile automatically appends .exe)
@@ -177,6 +181,15 @@ export async function buildProject(options: BuildOptions): Promise<BuildResult>
     }
   }
 
+  const detectedBunVersion = (typeof (globalThis as any).Bun !== "undefined" && (globalThis as any).Bun.version) || (() => {
+    try {
+      const vProc = spawnSync("bun", ["--version"], { stdio: "pipe" });
+      return vProc.stdout ? vProc.stdout.toString().trim() : "unknown";
+    } catch {
+      return "unknown";
+    }
+  })();
+
   // Generate artifact.json metadata
   const metadata = {
     packageId: config.id,
@@ -185,7 +198,7 @@ export async function buildProject(options: BuildOptions): Promise<BuildResult>
     description: config.description,
     target: options.target || "host",
     actions: actionImports.map((a) => a.id),
-    bunVersion: Bun.version,
+    bunVersion: detectedBunVersion,
     lockHash,
     buildHash,
     createdAt: new Date().toISOString(),

package/src/catalog/action-index.ts

@@ -0,0 +1,92 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadManifest } from "../project/manifest";
+import type { CatalogSnapshot, IndexedAction } from "./types";
+
+export class ActionIndex {
+  private actions = new Map<string, IndexedAction[]>(); // actionId -> IndexedAction[]
+
+  constructor(snapshot: CatalogSnapshot) {
+    this.indexSnapshot(snapshot);
+  }
+
+  private indexSnapshot(snapshot: CatalogSnapshot): void {
+    for (const [packageId, pkg] of snapshot.packages) {
+      const manifest = loadManifest(pkg.projectRoot);
+      if (manifest && manifest.actions) {
+        for (const [actionId, item] of Object.entries(manifest.actions)) {
+          const indexed: IndexedAction = {
+            packageId,
+            actionId,
+            contract: {
+              id: actionId,
+              description: item.description,
+              inputSchema: item.inputSchema,
+              outputSchema: item.outputSchema,
+              uses: item.uses,
+              tags: item.tags,
+              annotations: item.annotations as any,
+            },
+            entry: item.entry,
+            projectRoot: pkg.projectRoot,
+          };
+          this.add(indexed);
+        }
+      } else {
+        // 向后兼容回退：若未提供清单，扫描 actions 目录生成基础索引
+        const actionsDir = join(pkg.projectRoot, pkg.config.actionsDir || "actions");
+        if (existsSync(actionsDir)) {
+          try {
+            const files = readdirSync(actionsDir);
+            for (const file of files) {
+              if (file.endsWith(".ts") || file.endsWith(".js")) {
+                const actionId = file.replace(/\.(ts|js)$/, "");
+                const indexed: IndexedAction = {
+                  packageId,
+                  actionId,
+                  contract: {
+                    id: actionId,
+                  },
+                  entry: join(pkg.config.actionsDir || "actions", file),
+                  projectRoot: pkg.projectRoot,
+                };
+                this.add(indexed);
+              }
+            }
+          } catch {
+            // 忽略读取目录异常
+          }
+        }
+      }
+    }
+  }
+
+  private add(action: IndexedAction): void {
+    let list = this.actions.get(action.actionId);
+    if (!list) {
+      list = [];
+      this.actions.set(action.actionId, list);
+    }
+    list.push(action);
+  }
+
+  public list(packageId?: string): IndexedAction[] {
+    const all: IndexedAction[] = [];
+    for (const [_, list] of this.actions) {
+      for (const action of list) {
+        if (!packageId || action.packageId === packageId) {
+          all.push(action);
+        }
+      }
+    }
+    return all;
+  }
+
+  public find(actionId: string, packageId?: string): IndexedAction[] {
+    const matches = this.actions.get(actionId) || [];
+    if (packageId) {
+      return matches.filter((a) => a.packageId === packageId);
+    }
+    return matches;
+  }
+}

package/src/catalog/action-resolver.ts

@@ -0,0 +1,120 @@
+import type { ActionRef, ResolvedActionRef } from "@actiondock/sdk";
+import { ActionIndex } from "./action-index";
+import type { CatalogSnapshot, IndexedAction } from "./types";
+
+export interface ResolveOptions {
+  currentPackageId?: string;
+}
+
+export class ActionResolver {
+  private snapshot: CatalogSnapshot;
+  private index: ActionIndex;
+
+  constructor(snapshot: CatalogSnapshot, index?: ActionIndex) {
+    this.snapshot = snapshot;
+    this.index = index || new ActionIndex(snapshot);
+  }
+
+  /**
+   * 解析字符串或 ActionRef 为规范化的 ActionRef。
+   * 支持 greet、my-tools/greet、@team/github/issues.list。
+   */
+  public static parseRef(refStringOrObj: string | ActionRef): ActionRef {
+    if (typeof refStringOrObj === "object") {
+      return refStringOrObj;
+    }
+
+    const str = refStringOrObj.trim();
+    if (str.includes("/")) {
+      const lastSlashIndex = str.lastIndexOf("/");
+      const packageId = str.slice(0, lastSlashIndex);
+      const actionId = str.slice(lastSlashIndex + 1);
+
+      if (actionId.includes(":") || actionId.includes("/") || actionId.includes("..")) {
+        throw new Error(`Invalid action identifier: '${actionId}'`);
+      }
+      return { packageId, actionId };
+    }
+
+    // 处理旧语法 package:action 的兼容提醒
+    if (str.includes(":")) {
+      const parts = str.split(":");
+      throw new Error(
+        `Legacy syntax '${str}' is deprecated. Please use '${parts.join("/")}' instead.`
+      );
+    }
+
+    return { actionId: str };
+  }
+
+  public resolve(
+    refStringOrObj: string | ActionRef,
+    options: ResolveOptions = {}
+  ): { resolved: ResolvedActionRef; action: IndexedAction } {
+    const ref = ActionResolver.parseRef(refStringOrObj);
+
+    // 1. 若指定了 packageId，直接精确匹配
+    if (ref.packageId) {
+      const matches = this.index.find(ref.actionId, ref.packageId);
+      if (matches.length === 0) {
+        throw new Error(
+          `ACTION_NOT_FOUND: Action '${ref.actionId}' not found in package '${ref.packageId}'`
+        );
+      }
+      const matched = matches[0];
+      const pkg = this.snapshot.packages.get(matched.packageId);
+      return {
+        resolved: {
+          packageId: matched.packageId,
+          packageInstanceId: pkg?.packageInstanceId || matched.packageId,
+          actionId: matched.actionId,
+          generationId: this.snapshot.generationId,
+        },
+        action: matched,
+      };
+    }
+
+    // 2. 未指定 packageId：优先查找当前调用者包
+    if (options.currentPackageId) {
+      const inCurrent = this.index.find(ref.actionId, options.currentPackageId);
+      if (inCurrent.length > 0) {
+        const matched = inCurrent[0];
+        const pkg = this.snapshot.packages.get(matched.packageId);
+        return {
+          resolved: {
+            packageId: matched.packageId,
+            packageInstanceId: pkg?.packageInstanceId || matched.packageId,
+            actionId: matched.actionId,
+            generationId: this.snapshot.generationId,
+          },
+          action: matched,
+        };
+      }
+    }
+
+    // 3. 全局唯一匹配检查
+    const allMatches = this.index.find(ref.actionId);
+    if (allMatches.length === 0) {
+      throw new Error(`ACTION_NOT_FOUND: Action '${ref.actionId}' not found in any linked package`);
+    }
+
+    if (allMatches.length > 1) {
+      const candidates = allMatches.map((m) => `${m.packageId}/${m.actionId}`).join(", ");
+      throw new Error(
+        `AMBIGUOUS_ACTION_REF: Action '${ref.actionId}' is provided by multiple packages: ${candidates}. Please specify the package name.`
+      );
+    }
+
+    const matched = allMatches[0];
+    const pkg = this.snapshot.packages.get(matched.packageId);
+    return {
+      resolved: {
+        packageId: matched.packageId,
+        packageInstanceId: pkg?.packageInstanceId || matched.packageId,
+        actionId: matched.actionId,
+        generationId: this.snapshot.generationId,
+      },
+      action: matched,
+    };
+  }
+}

package/src/catalog/index.ts

@@ -0,0 +1,5 @@
+export * from "./action-index";
+export * from "./action-resolver";
+export * from "./location-registry";
+export * from "./package-catalog";
+export * from "./types";

package/src/catalog/location-registry.ts

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { getActionDockHome } from "../utils";
+import type { LocationLink, LocationRegistryData } from "./types";
+
+export class LocationRegistry {
+  private filePath: string;
+
+  constructor(customHome?: string) {
+    const baseDir = getActionDockHome(customHome);
+    this.filePath = join(baseDir, ".actiondock", "registry.json");
+  }
+
+  public getFilePath(): string {
+    return this.filePath;
+  }
+
+  public load(): LocationRegistryData {
+    if (!existsSync(this.filePath)) {
+      return { schemaVersion: 1, links: [] };
+    }
+    try {
+      const raw = readFileSync(this.filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") {
+        return { schemaVersion: 1, links: [] };
+      }
+
+      // 处理 2.0 旧格式向 1 迁移
+      if (parsed.schemaVersion === 1 && Array.isArray(parsed.links)) {
+        return parsed as LocationRegistryData;
+      }
+
+      const links: LocationLink[] = [];
+      if (parsed.workspaces && typeof parsed.workspaces === "object") {
+        for (const [wsPath, ws] of Object.entries(parsed.workspaces as Record<string, any>)) {
+          links.push({
+            type: "workspace",
+            path: resolve(wsPath),
+            linkedAt: ws.linkedAt || new Date().toISOString(),
+            depth: 3,
+          });
+        }
+      }
+
+      if (parsed.packages && typeof parsed.packages === "object") {
+        for (const [_, pkg] of Object.entries(parsed.packages as Record<string, any>)) {
+          if (!pkg.workspaceRoot && pkg.path) {
+            links.push({
+              type: "package",
+              path: resolve(pkg.path),
+              linkedAt: pkg.linkedAt || new Date().toISOString(),
+            });
+          }
+        }
+      }
+
+      return { schemaVersion: 1, links };
+    } catch {
+      return { schemaVersion: 1, links: [] };
+    }
+  }
+
+  public save(data: LocationRegistryData): void {
+    const dir = dirname(this.filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const tempPath = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tempPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    renameSync(tempPath, this.filePath);
+  }
+
+  public addLink(path: string, options: { type?: "package" | "workspace"; depth?: number } = {}): LocationLink {
+    const absPath = resolve(path);
+    const registry = this.load();
+    const type = options.type || "package";
+    const depth = options.depth ?? (type === "workspace" ? 3 : undefined);
+
+    const existingIndex = registry.links.findIndex((l) => l.path === absPath);
+    const link: LocationLink = {
+      type,
+      path: absPath,
+      linkedAt: new Date().toISOString(),
+      depth,
+    };
+
+    if (existingIndex >= 0) {
+      registry.links[existingIndex] = link;
+    } else {
+      registry.links.push(link);
+    }
+
+    this.save(registry);
+    return link;
+  }
+
+  public removeLink(targetPathOrId: string): LocationLink | null {
+    const registry = this.load();
+    const absPath = resolve(targetPathOrId);
+
+    const idx = registry.links.findIndex(
+      (l) => l.path === absPath || l.path.endsWith(`/${targetPathOrId}`)
+    );
+
+    if (idx >= 0) {
+      const [removed] = registry.links.splice(idx, 1);
+      this.save(registry);
+      return removed;
+    }
+    return null;
+  }
+
+  public prune(): LocationLink[] {
+    const registry = this.load();
+    const valid: LocationLink[] = [];
+    const removed: LocationLink[] = [];
+
+    for (const link of registry.links) {
+      if (existsSync(link.path)) {
+        valid.push(link);
+      } else {
+        removed.push(link);
+      }
+    }
+
+    if (removed.length > 0) {
+      registry.links = valid;
+      this.save(registry);
+    }
+
+    return removed;
+  }
+}

package/src/catalog/package-catalog.ts

@@ -0,0 +1,87 @@
+import { existsSync, realpathSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { findProjectRoot, loadProjectConfig } from "../project/loader";
+import { discoverProjects } from "../registry/registry";
+import { LocationRegistry } from "./location-registry";
+import type { CatalogPackageEntry, CatalogSnapshot } from "./types";
+
+export class PackageCatalog {
+  private registry: LocationRegistry;
+
+  constructor(registry?: LocationRegistry) {
+    this.registry = registry || new LocationRegistry();
+  }
+
+  public buildSnapshot(cwd: string = process.cwd()): CatalogSnapshot {
+    const packages = new Map<string, CatalogPackageEntry>();
+    const seenRealPaths = new Map<string, string>(); // realPath -> packageId
+    const seenPackageIds = new Map<string, string>(); // packageId -> realPath
+
+    const registerPackage = (root: string, isChild: boolean = false) => {
+      const abs = resolve(root);
+      if (!existsSync(abs)) return;
+      const real = realpathSync(abs);
+
+      if (seenRealPaths.has(real)) {
+        return; // 符号链接归一化去重
+      }
+
+      try {
+        const config = loadProjectConfig(abs);
+        if (seenPackageIds.has(config.id)) {
+          const existingPath = seenPackageIds.get(config.id);
+          if (existingPath !== real) {
+            throw new Error(
+              `PACKAGE_ID_CONFLICT: Package ID '${config.id}' is declared by multiple directories: '${existingPath}' and '${real}'`
+            );
+          }
+        }
+
+        const entry: CatalogPackageEntry = {
+          id: config.id,
+          packageInstanceId: `${config.id}:${real}`,
+          projectRoot: abs,
+          config,
+          isWorkspaceChild: isChild,
+        };
+
+        packages.set(config.id, entry);
+        seenRealPaths.set(real, config.id);
+        seenPackageIds.set(config.id, real);
+      } catch (e: any) {
+        if (e.message?.startsWith("PACKAGE_ID_CONFLICT")) {
+          throw e;
+        }
+        // 忽略无效项目
+      }
+    };
+
+    // 优先包含当前工作目录所在项目
+    const currentRoot = findProjectRoot(cwd);
+    if (currentRoot) {
+      registerPackage(currentRoot);
+    }
+
+    // 扫描注册表中的位置
+    const regData = this.registry.load();
+    for (const link of regData.links) {
+      if (!existsSync(link.path)) continue;
+
+      if (link.type === "package") {
+        registerPackage(link.path);
+      } else if (link.type === "workspace") {
+        const subprojects = discoverProjects(link.path, link.depth ?? 3);
+        for (const sub of subprojects) {
+          registerPackage(sub, true);
+        }
+      }
+    }
+
+    return {
+      generationId: randomUUID(),
+      createdAt: new Date().toISOString(),
+      packages,
+    };
+  }
+}