@actiondock/core 2.0.2 → 2.0.3

package/src/project/init.ts

@@ -16,13 +16,14 @@ export interface InitOptions {
 /**
  * 在目标目录初始化一个完整的 ActionDock 2.0 Action Package 脚手架。
  * 生成内容包括：
- * 1. actiondock.json（项目元数据与配置声明）
- * 2. package.json（模块依赖与 bun test 脚本）
- * 3. tsconfig.json（现代 ESNext / Bundler 编译配置）
- * 4. .gitignore（排除持久化 db、node_modules、dist）
- * 5. actions/greet.ts（标准示例 Action，演示 config、state、log 使用）
- * 6. playbooks/greet-user.md（标准 SOP Playbook 演示）
- * 7. tests/greet.test.ts（基于 createTestRuntime 的零依赖单元测试）
+ * - actiondock.json（项目元数据与配置声明）
+ * - actiondock.manifest.json（声明式元数据清单事实源）
+ * - package.json（Node.js 标准脚本与依赖声明）
+ * - tsconfig.json（现代 NodeNext 模块规范）
+ * - .gitignore（排除持久化 db、node_modules、dist）
+ * - actions/greet.ts（标准示例 Action，演示 config、state、log 使用）
+ * - playbooks/greet-user.md（标准 SOP Playbook 演示）
+ * - tests/greet.test.ts（基于 node:test 与 @actiondock/testing 的测试用例）
  * 
  * @param targetDir 目标项目目录
  * @param options 初始化选项
@@ -58,20 +59,61 @@ export function initProject(targetDir: string, options: InitOptions = {}): void
     JSON.stringify(actiondockJson, null, 2) + "\n"
   );
 
-  // 2. package.json
+  // 2. actiondock.manifest.json
+  const manifestJson = {
+    schemaVersion: 1,
+    actions: {
+      "sample.greet": {
+        entry: "actions/greet.ts",
+        description: "Greeting action demonstrating basic input, config, and state usage",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the person to greet",
+            },
+          },
+          required: ["name"],
+        },
+        outputSchema: {
+          type: "object",
+          properties: {
+            message: { type: "string" },
+            timesGreeted: { type: "number" },
+          },
+          required: ["message", "timesGreeted"],
+        },
+        uses: [],
+        tags: ["sample"],
+      },
+    },
+    assets: [],
+  };
+  writeFileSync(
+    join(root, "actiondock.manifest.json"),
+    JSON.stringify(manifestJson, null, 2) + "\n"
+  );
+
+  // 3. package.json
   const packageJson = {
     name: id,
     version: "0.1.0",
     description,
     type: "module",
     scripts: {
-      test: "bun test",
+      test: "node --import tsx --test tests/*.test.ts",
+    },
+    engines: {
+      node: ">=22.12.0",
     },
     dependencies: {
-      "@actiondock/sdk": "^2.0.0",
+      "@actiondock/sdk": "^2.0.3",
     },
     devDependencies: {
-      "@types/bun": "latest",
+      "@actiondock/testing": "^2.0.3",
+      "@types/node": "^22.12.0",
+      "tsx": "^4.19.0",
       "typescript": "^5.7.0",
     },
   };
@@ -80,15 +122,15 @@ export function initProject(targetDir: string, options: InitOptions = {}): void
     JSON.stringify(packageJson, null, 2) + "\n"
   );
 
-  // 3. tsconfig.json
+  // 4. tsconfig.json
   const tsconfigJson = {
     compilerOptions: {
-      target: "ESNext",
-      module: "ESNext",
-      moduleResolution: "bundler",
+      target: "ES2022",
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
       strict: true,
       skipLibCheck: true,
-      types: ["bun-types"],
+      types: ["node"],
     },
   };
   writeFileSync(
@@ -96,16 +138,17 @@ export function initProject(targetDir: string, options: InitOptions = {}): void
     JSON.stringify(tsconfigJson, null, 2) + "\n"
   );
 
-  // 4. .gitignore
+  // 5. .gitignore
   const gitignore = `.actiondock/
 node_modules/
 dist/
-bun.lock
-*.db
+build/
+*.log
+.env
 `;
   writeFileSync(join(root, ".gitignore"), gitignore);
 
-  // 5. actions/
+  // 6. actions/
   const actionsDir = join(root, "actions");
   mkdirSync(actionsDir, { recursive: true });
 
@@ -113,12 +156,15 @@ bun.lock
 
 export default defineAction({
   id: "sample.greet",
-  description: "Greet a user with configurable greeting",
+  description: "Greeting action demonstrating basic input, config, and state usage",
 
   inputSchema: {
     type: "object",
     properties: {
-      name: { type: "string", description: "Name of person to greet" },
+      name: {
+        type: "string",
+        description: "Name of the person to greet",
+      },
     },
     required: ["name"],
   },
@@ -127,9 +173,9 @@ export default defineAction({
     type: "object",
     properties: {
       message: { type: "string" },
-      timestamp: { type: "string" },
+      timesGreeted: { type: "number" },
     },
-    required: ["message", "timestamp"],
+    required: ["message", "timesGreeted"],
   },
 
   async run(input: { name: string }, ctx) {
@@ -141,14 +187,14 @@ export default defineAction({
 
     return {
       message: \`\${greeting}, \${input.name}!\`,
-      timestamp: new Date().toISOString(),
+      timesGreeted: count,
     };
   },
 });
 `;
   writeFileSync(join(actionsDir, "greet.ts"), sampleAction);
 
-  // 6. playbooks/
+  // 7. playbooks/
   const playbooksDir = join(root, "playbooks");
   mkdirSync(playbooksDir, { recursive: true });
 
@@ -166,12 +212,13 @@ actions:
 `;
   writeFileSync(join(playbooksDir, "greet-user.md"), samplePlaybook);
 
-  // 7. tests/
+  // 8. tests/
   const testsDir = join(root, "tests");
   mkdirSync(testsDir, { recursive: true });
 
-  const sampleTest = `import { describe, expect, it } from "bun:test";
-import { createTestRuntime } from "@actiondock/sdk";
+  const sampleTest = `import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestRuntime } from "@actiondock/testing";
 import greetAction from "../actions/greet";
 
 describe("greet action", () => {
@@ -181,12 +228,12 @@ describe("greet action", () => {
     });
 
     const res1 = await runtime.run(greetAction, { name: "Alice" });
-    expect(res1.message).toBe("Hi, Alice!");
-    expect(await runtime.state.get("greet_count")).toBe(1);
+    assert.equal(res1.message, "Hi, Alice!");
+    assert.equal(await runtime.state.get("greet_count"), 1);
 
     const res2 = await runtime.run(greetAction, { name: "Bob" });
-    expect(res2.message).toBe("Hi, Bob!");
-    expect(await runtime.state.get("greet_count")).toBe(2);
+    assert.equal(res2.message, "Hi, Bob!");
+    assert.equal(await runtime.state.get("greet_count"), 2);
   });
 });
 `;

package/src/project/loader.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import YAML from "yaml";
@@ -68,29 +69,28 @@ export function loadProjectConfig(projectRoot: string): ProjectConfig {
 }
 
 /**
- * 探测宿主系统中可用的包管理工具（优先级：bun > pnpm > yarn > npm）。
+ * 探测宿主系统中可用的包管理工具（优先级：pnpm > npm > yarn > bun）。
  */
 function getInstallCommand(): string[] {
   const candidates: [string, string][] = [
-    ["bun", "install"],
     ["pnpm", "install"],
-    ["yarn", "install"],
     ["npm", "install"],
+    ["yarn", "install"],
+    ["bun", "install"],
   ];
   for (const [pm, action] of candidates) {
     try {
-      const check = Bun.spawnSync([pm, "--version"], {
-        stdout: "pipe",
-        stderr: "pipe",
+      const check = spawnSync(pm, ["--version"], {
+        stdio: "pipe",
       });
-      if (check.exitCode === 0) {
+      if (check.status === 0) {
         return [pm, action];
       }
     } catch {
       // 继续探测下一个候选包管理器
     }
   }
-  return ["bun", "install"];
+  return ["npm", "install"];
 }
 
 /**
@@ -131,13 +131,12 @@ export function ensureProjectDependencies(projectRoot: string, force = false): b
       `[actiondock] Installing dependencies using ${installCmd[0]} for '${pkg.name || basename(projectRoot)}'...\n`
     );
 
-    const proc = Bun.spawnSync(installCmd, {
+    const proc = spawnSync(installCmd[0], installCmd.slice(1), {
       cwd: projectRoot,
-      stdout: "pipe",
-      stderr: "pipe",
+      stdio: "pipe",
     });
 
-    if (proc.exitCode !== 0) {
+    if (proc.status !== 0) {
       const errText = proc.stderr?.toString() || `Unknown error during ${installCmd[0]} install`;
       process.stderr.write(`[actiondock] Warning: Dependency installation failed: ${errText}\n`);
       return false;

package/src/project/manifest.ts

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ActionDockManifest, ActionManifestEntry } from "./types";
+
+export const MANIFEST_FILE_NAME = "actiondock.manifest.json";
+
+/**
+ * 读取并解析项目的声明式清单文件。
+ * 若文件不存在则返回 null。
+ */
+export function loadManifest(projectRoot: string): ActionDockManifest | null {
+  const filePath = join(projectRoot, MANIFEST_FILE_NAME);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as ActionDockManifest;
+    if (!parsed || typeof parsed !== "object" || parsed.schemaVersion !== 1) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 保存声明式清单文件至项目根目录。
+ */
+export function saveManifest(projectRoot: string, manifest: ActionDockManifest): void {
+  const filePath = join(projectRoot, MANIFEST_FILE_NAME);
+  writeFileSync(filePath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * 校验清单数据结构的合法性。
+ */
+export function validateManifest(manifest: unknown): { valid: boolean; errors?: string[] } {
+  if (!manifest || typeof manifest !== "object") {
+    return { valid: false, errors: ["Manifest must be an object"] };
+  }
+  const m = manifest as ActionDockManifest;
+  const errors: string[] = [];
+
+  if (m.schemaVersion !== 1) {
+    errors.push("Manifest 'schemaVersion' must be 1");
+  }
+  if (!m.actions || typeof m.actions !== "object") {
+    errors.push("Manifest 'actions' must be an object");
+  } else {
+    for (const [actionId, item] of Object.entries(m.actions)) {
+      if (!item || typeof item !== "object") {
+        errors.push(`Action entry '${actionId}' must be an object`);
+        continue;
+      }
+      if (!item.entry || typeof item.entry !== "string") {
+        errors.push(`Action '${actionId}' must specify string 'entry'`);
+      }
+      if (item.uses && !Array.isArray(item.uses)) {
+        errors.push(`Action '${actionId}' property 'uses' must be an array`);
+      }
+      if (item.tags && !Array.isArray(item.tags)) {
+        errors.push(`Action '${actionId}' property 'tags' must be an array`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * 为单个 Action 构建清单项。
+ */
+export function createManifestEntry(options: {
+  entry: string;
+  description?: string;
+  inputSchema?: Record<string, unknown> | boolean;
+  outputSchema?: Record<string, unknown> | boolean;
+  uses?: string[];
+  tags?: string[];
+  annotations?: Record<string, unknown>;
+}): ActionManifestEntry {
+  return {
+    entry: options.entry,
+    description: options.description,
+    inputSchema: options.inputSchema,
+    outputSchema: options.outputSchema,
+    uses: options.uses || [],
+    tags: options.tags || [],
+    annotations: options.annotations,
+  };
+}

package/src/project/types.ts

@@ -60,3 +60,33 @@ export interface PlaybookDefinition extends PlaybookFrontmatter {
   /** Playbook 源文件的绝对物理路径 */
   filePath: string;
 }
+
+/**
+ * 单个 Action 在清单中的声明项。
+ */
+export interface ActionManifestEntry {
+  /** Action 入口文件相对路径（如 "actions/greet.ts"） */
+  entry: string;
+  /** Action 功能描述 */
+  description?: string;
+  /** 输入参数模式规范 */
+  inputSchema?: Record<string, unknown> | boolean;
+  /** 输出结果模式规范 */
+  outputSchema?: Record<string, unknown> | boolean;
+  /** 静态依赖的 Action 列表 */
+  uses?: string[];
+  /** 标签列表 */
+  tags?: string[];
+  /** 协议注解元数据 */
+  annotations?: Record<string, unknown>;
+}
+
+/**
+ * ActionDock 声明式清单（actiondock.manifest.json）规范。
+ * 作为元数据的单一事实源，实现无副作用的模块发现与构建规划。
+ */
+export interface ActionDockManifest {
+  schemaVersion: number;
+  actions: Record<string, ActionManifestEntry>;
+  assets?: string[];
+}

package/src/runtime/clock.ts

@@ -0,0 +1,41 @@
+/**
+ * 统一时间与时钟接口。
+ */
+export interface Clock {
+  /** 获取当前系统墙上时间 */
+  now(): Date;
+  /** 获取单调递增时间戳（单位：毫秒） */
+  monotonic(): number;
+  /** 异步休眠指定毫秒 */
+  sleep(ms: number): Promise<void>;
+}
+
+/**
+ * 生产环境系统时钟实现。
+ */
+export class SystemClock implements Clock {
+  now(): Date {
+    return new Date();
+  }
+
+  monotonic(): number {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+      return performance.now();
+    }
+    return Date.now();
+  }
+
+  sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+let defaultClock: Clock = new SystemClock();
+
+export function getSystemClock(): Clock {
+  return defaultClock;
+}
+
+export function setSystemClock(clock: Clock): void {
+  defaultClock = clock;
+}

package/src/runtime/context.ts

@@ -1,15 +1,19 @@
+import { randomUUID } from "node:crypto";
 import type {
   ActionContext,
   ActionDefinition,
   ActionInvoker,
   Config,
   Logger,
+  ProcessAPI,
+  ProgressReporter,
   StateStore,
 } from "@actiondock/sdk";
 import type { ProjectConfig } from "../project/types";
 import { createGlobalStorage } from "../storage";
 import type { RuntimeStorage } from "../storage/types";
 import { resolveEnvValue } from "./env";
+import { getProcessExecutor } from "./process";
 
 /**
  * 生产级配置解析器实现。
@@ -184,8 +188,12 @@ export interface ContextOptions {
   overrides?: Record<string, unknown>;
   projectConfig?: ProjectConfig;
   parentRunId?: string;
+  runId?: string;
+  rootRunId?: string;
   callStack?: string[];
   signal?: AbortSignal;
+  process?: ProcessAPI;
+  progress?: ProgressReporter;
   onActionInvoke?: (
     action: ActionDefinition,
     input: unknown,
@@ -196,7 +204,7 @@ export interface ContextOptions {
 /**
  * 构建并装配传递给 Action 的完整 ActionContext 运行时上下文。
  * 
- * @param options 上下文构建参数（包含存储连接、配置覆盖、项目元数据、取消信号与互调委托）
+ * @param options 上下文构建参数
  * @returns 组装完毕的 ActionContext 实例
  */
 export function createActionContext(options: ContextOptions): ActionContext {
@@ -208,6 +216,8 @@ export function createActionContext(options: ContextOptions): ActionContext {
   const state = new RuntimeStateStore(options.storage);
   const log = new StderrLogger();
   const signal = options.signal ?? new AbortController().signal;
+  const currentRunId = options.runId || randomUUID();
+  const currentRootRunId = options.rootRunId || options.parentRunId || currentRunId;
 
   const invoker: ActionInvoker = {
     async invoke<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O> {
@@ -215,18 +225,30 @@ export function createActionContext(options: ContextOptions): ActionContext {
         return (await options.onActionInvoke(
           action as any,
           input,
-          options.parentRunId
+          currentRunId
         )) as O;
       }
       throw new Error("ActionInvoker not configured with an invocation delegate");
     },
   };
 
+  const processApi = options.process || getProcessExecutor();
+  const progressApi: ProgressReporter = options.progress || {
+    report() {},
+  };
+
   return {
     config,
     state,
     actions: invoker,
+    process: processApi,
     log,
+    progress: progressApi,
     signal,
+    run: {
+      id: currentRunId,
+      rootId: currentRootRunId,
+      parentId: options.parentRunId,
+    },
   };
 }

package/src/runtime/events.ts

@@ -0,0 +1,142 @@
+import type { ExecutionEvent } from "@actiondock/sdk";
+
+export interface EventSink {
+  emit(event: ExecutionEvent): void;
+  subscribe(
+    runId: string,
+    options?: { after?: number; signal?: AbortSignal }
+  ): AsyncIterable<ExecutionEvent>;
+  clear(runId: string): void;
+}
+
+/**
+ * 进程内有界事件缓冲区实现。
+ * 遵循设计文档：每个运行最多保留 1024 条或 1MB 事件，支持单调序号。
+ */
+export class InMemoryEventSink implements EventSink {
+  private eventsByRun = new Map<string, ExecutionEvent[]>();
+  private listeners = new Map<string, Set<(event: ExecutionEvent) => void>>();
+  private maxEventsPerRun = 1024;
+
+  emit(event: ExecutionEvent): void {
+    let list = this.eventsByRun.get(event.runId);
+    if (!list) {
+      list = [];
+      this.eventsByRun.set(event.runId, list);
+    }
+
+    if (list.length >= this.maxEventsPerRun) {
+      // 淘汰旧日志和进度事件，保留状态和结果
+      const nonEssentialIndex = list.findIndex((e) => e.type === "log" || e.type === "progress");
+      if (nonEssentialIndex >= 0) {
+        list.splice(nonEssentialIndex, 1);
+      } else {
+        list.shift();
+      }
+    }
+    list.push(event);
+
+    const subs = this.listeners.get(event.runId);
+    if (subs) {
+      for (const listener of subs) {
+        try {
+          listener(event);
+        } catch {
+          // 忽略单个监听器内部异常
+        }
+      }
+    }
+  }
+
+  async *subscribe(
+    runId: string,
+    options: { after?: number; signal?: AbortSignal } = {}
+  ): AsyncIterable<ExecutionEvent> {
+    const after = options.after ?? -1;
+    const history = this.eventsByRun.get(runId) || [];
+
+    for (const evt of history) {
+      if (evt.sequence > after) {
+        yield evt;
+      }
+    }
+
+    const lastEvt = history[history.length - 1];
+    if (lastEvt && (lastEvt.type === "finish" || lastEvt.type === "status" && lastEvt.status !== "running")) {
+      return;
+    }
+
+    const queue: ExecutionEvent[] = [];
+    let notify: (() => void) | null = null;
+    let done = false;
+
+    const listener = (evt: ExecutionEvent) => {
+      if (evt.sequence > after) {
+        queue.push(evt);
+        if (notify) {
+          notify();
+          notify = null;
+        }
+        if (evt.type === "finish") {
+          done = true;
+        }
+      }
+    };
+
+    let subs = this.listeners.get(runId);
+    if (!subs) {
+      subs = new Set();
+      this.listeners.set(runId, subs);
+    }
+    subs.add(listener);
+
+    const cleanup = () => {
+      subs?.delete(listener);
+      if (subs && subs.size === 0) {
+        this.listeners.delete(runId);
+      }
+    };
+
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => {
+        done = true;
+        if (notify) {
+          notify();
+          notify = null;
+        }
+      }, { once: true });
+    }
+
+    try {
+      while (!done && !options.signal?.aborted) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else {
+          await new Promise<void>((resolve) => {
+            notify = resolve;
+          });
+        }
+      }
+      while (queue.length > 0) {
+        yield queue.shift()!;
+      }
+    } finally {
+      cleanup();
+    }
+  }
+
+  clear(runId: string): void {
+    this.eventsByRun.delete(runId);
+    this.listeners.delete(runId);
+  }
+}
+
+let defaultEventSink: EventSink = new InMemoryEventSink();
+
+export function getDefaultEventSink(): EventSink {
+  return defaultEventSink;
+}
+
+export function setDefaultEventSink(sink: EventSink): void {
+  defaultEventSink = sink;
+}

package/src/runtime/index.ts

@@ -3,3 +3,7 @@ export * from "./runner";
 export * from "./execution-manager";
 export * from "./standalone";
 export * from "./env";
+export * from "./clock";
+export * from "./process";
+export * from "./events";
+