@actiondock/sdk 2.0.0

package/README.md

@@ -0,0 +1,121 @@
+# @actiondock/sdk
+
+The lightweight, zero-dependency SDK for defining, orchestrating, and testing AI Agent Actions and Skills in ActionDock 2.0.
+
+[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.2-black?logo=bun)](https://bun.sh/)
+[![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)
+
+> **Runtime requirement**: [Bun](https://bun.sh/) >= 1.2.0 is required.
+
+---
+
+## Installation
+
+```bash
+bun add @actiondock/sdk
+```
+
+---
+
+## Quick Example
+
+### 1. Define an Action (`actions/greet.ts`)
+
+```ts
+import { defineAction } from "@actiondock/sdk";
+
+export default defineAction({
+  id: "sample.greet",
+  description: "Greet a user and track greeting count in persistent state",
+
+  inputSchema: {
+    type: "object",
+    properties: {
+      name: { type: "string", minLength: 1 },
+    },
+    required: ["name"],
+  },
+
+  async run(input: { name: string }, ctx) {
+    const greeting = ctx.config.get("GREETING_PREFIX", "Hello");
+    const count = ((await ctx.state.get<number>(`greet:${input.name}`)) || 0) + 1;
+    await ctx.state.set(`greet:${input.name}`, count);
+    ctx.log.info(`Greeted ${input.name} ${count} time(s)`);
+
+    return {
+      message: `${greeting}, ${input.name}!`,
+      count,
+    };
+  },
+});
+```
+
+### 2. Test in Milliseconds (`tests/greet.test.ts`)
+
+```ts
+import { describe, expect, it } from "bun:test";
+import { createTestRuntime } from "@actiondock/sdk";
+import greetAction from "../actions/greet";
+
+describe("sample.greet Action", () => {
+  it("greets user and updates state counter", async () => {
+    const runtime = createTestRuntime({
+      config: { GREETING_PREFIX: "Welcome" },
+      state: { "greet:Alice": 2 },
+    });
+
+    const result = await runtime.run(greetAction, { name: "Alice" });
+    expect(result.message).toBe("Welcome, Alice!");
+    expect(result.count).toBe(3);
+    expect(await runtime.state.get("greet:Alice")).toBe(3);
+  });
+});
+```
+
+---
+
+## Core Capabilities
+
+- **`ActionContext`**:
+  - `ctx.config`: 5-tier configuration resolution (`CLI > SQLite > Global > ENV > default > fallback`).
+  - `ctx.state`: Cross-action persistent state store with namespacing (`scope()`) and automatic TTL expiration.
+  - `ctx.actions`: Action-to-action invocation (`invoke()`) with recursion & cycle detection.
+  - `ctx.log`: Clean stderr-directed structured logging (keeping stdout clean for JSON envelopes).
+  - `ctx.signal`: Cooperative `AbortSignal` for graceful timeout and cancellation.
+- **`execCli`**: Deadlock-safe, cross-platform synchronous CLI executor with Windows `.cmd` resolution, stdin streaming, timeout, and signal support.
+- **`spawnDetached`**: Safe asynchronous launcher for daemon-spawning CLI tools (e.g., `agent-browser open`), preventing pipe EOF hangs via fire-and-forget stdio decoupling and polling probe.
+- **`createTestRuntime`**: Fast, zero-dependency in-memory test harness for unit tests.
+
+---
+
+## API Summary
+
+| Export | Type | Description |
+|---|---|---|
+| `defineAction(def)` | Function | Defines and defensively validates an Action |
+| `createTestRuntime(opts)` | Function | Creates an in-memory test runner (`config`, `state`, `logger`, `run()`) |
+| `execCli(cmd, args, opts)` | Function | Synchronous, deadlock-safe CLI execution utility |
+| `spawnDetached(opts)` | Function | Safe asynchronous launcher & readiness prober for daemon-spawning CLI tools |
+| `MemoryConfig` | Class | In-memory `Config` provider for unit tests |
+| `MemoryStateStore` | Class | In-memory `StateStore` with TTL and namespace support |
+| `MemoryLogger` | Class | In-memory `Logger` collecting log entries for test assertions |
+| `ActionContext` | Interface | Runtime context provided to `action.run(input, ctx)` |
+| `ActionDefinition` | Interface | Schema and execution contract for an Action |
+| `ExecutionResult` | Type | Standard JSON envelope (`ok: true, data` or `ok: false, error`) |
+
+---
+
+## 📖 Documentation
+
+For detailed guides, design principles, and exhaustive API references, see the [ActionDock Documentation Center](https://github.com/team4u/actiondock#readme):
+
+- [Action SDK API Reference](https://github.com/team4u/actiondock/blob/main/docs/reference/action-api.md)
+- [ActionContext Concept](https://github.com/team4u/actiondock/blob/main/docs/concepts/action-context.md)
+- [Testing & Verification Guide](https://github.com/team4u/actiondock/blob/main/docs/guides/testing.md)
+
+---
+
+## License
+
+[Apache-2.0](LICENSE) © team4u

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@actiondock/sdk",
+  "version": "2.0.0",
+  "description": "ActionDock SDK for defining and testing standalone AI Agent Actions",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": ["actiondock", "agent", "actions", "skill", "ai", "mcp"],
+  "author": "team4u",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/team4u/actiondock.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/team4u/actiondock#readme",
+  "bugs": {
+    "url": "https://github.com/team4u/actiondock/issues"
+  }
+}

package/src/action.ts

@@ -0,0 +1,38 @@
+import type { ActionDefinition } from "./types";
+
+/**
+ * 辅助函数：声明并定义一个强类型的 Action 动作。
+ * 
+ * 职责：
+ * 1. 提供 TypeScript 泛型推导支持（入参类型 `I` 与出参类型 `O`）。
+ * 2. 在声明期进行防御性基础结构校验，确保包含非空的字符串 `id` 和可执行的 `run` 函数。
+ * 
+ * @param definition 包含 id, description, inputSchema, outputSchema, run 的 Action 定义对象
+ * @returns 经过校验的 ActionDefinition 原对象
+ * @throws {Error} 若 definition 不是对象、缺失 id 或缺失 run 函数
+ * 
+ * @example
+ * ```ts
+ * export default defineAction({
+ *   id: "sample.greet",
+ *   description: "向指定用户打招呼",
+ *   async run(input: { name: string }, ctx) {
+ *     return { message: `Hello, ${input.name}!` };
+ *   }
+ * });
+ * ```
+ */
+export function defineAction<I = unknown, O = unknown>(
+  definition: ActionDefinition<I, O>
+): ActionDefinition<I, O> {
+  if (!definition || typeof definition !== "object") {
+    throw new Error("Action definition must be an object");
+  }
+  if (!definition.id || typeof definition.id !== "string") {
+    throw new Error("Action definition must have a string 'id'");
+  }
+  if (typeof definition.run !== "function") {
+    throw new Error(`Action '${definition.id}' must have a 'run' function`);
+  }
+  return definition;
+}

package/src/cli.ts

@@ -0,0 +1,317 @@
+/**
+ * CLI 执行选项配置。
+ */
+export interface ExecCliOptions {
+  /**
+   * 子进程工作目录，默认为当前工作目录 (process.cwd())。
+   */
+  cwd?: string;
+
+  /**
+   * 自定义环境变量字典（合并到 process.env 之上）。
+   */
+  env?: Record<string, string>;
+
+  /**
+   * 协作式取消信号（如 ActionContext 中的 ctx.signal）。
+   * 若信号在执行前或执行期间触发，将安全中断或拒绝执行。
+   */
+  signal?: AbortSignal;
+
+  /**
+   * 单条命令超时时间（单位：毫秒）。
+   * 超时后将向子进程发送终止信号强制结束，并标记 timedOut 为 true。
+   */
+  timeout?: number;
+
+  /**
+   * 写入子进程标准输入（stdin）的文本或原始二进制数据。
+   */
+  input?: string | Uint8Array;
+
+  /**
+   * 输出文本的解码字符集（默认为 "utf-8"，支持 "gbk" 等跨平台字符集）。
+   */
+  encoding?: string;
+
+  /**
+   * 当命令执行失败（非零退出码或超时）时是否直接抛出 Error（默认为 false）。
+   * 设为 true 时，可省去手动 if (!res.ok) 校验。
+   */
+  throwOnError?: boolean;
+}
+
+/**
+ * CLI 执行结果结构体。
+ */
+export interface ExecCliResult {
+  /** 命令是否成功退出（即 exitCode === 0 且未发生超时或中断） */
+  ok: boolean;
+  /** 进程退出码（若未找到命令、超时或信号中断等异常时为 -1） */
+  exitCode: number;
+  /** 解码并去除首尾空白后的标准输出文本 */
+  stdout: string;
+  /** 解码并去除首尾空白后的标准错误文本 */
+  stderr: string;
+  /** 原始标准输出字节流（用于图片、音频、压缩包等二进制数据处理） */
+  raw: Uint8Array;
+  /** 是否因超时强制终止 */
+  timedOut?: boolean;
+  /** 命令执行总耗时（毫秒） */
+  durationMs: number;
+}
+
+/**
+ * 跨平台、防管道死锁的同步 CLI 命令调度器。
+ * 
+ * 核心特性与设计原则：
+ * 1. **Windows .cmd 兼容**：自动通过 `Bun.which()` 解析 Windows 平台下的 `.cmd` / `.bat` / `.exe` 物理绝对路径；
+ * 2. **防管道死锁**：采用 `Bun.spawnSync` 同步排空（Drain）管道并关闭句柄，彻底避免无头浏览器/Node 子进程因句柄残留导致异步流挂起；
+ * 3. **超时与取消安全**：支持毫秒级 `timeout` 超时强杀与 `signal` (AbortSignal) 取消信号；
+ * 4. **标准输入与二进制支持**：支持 `input` 管道灌入与 `raw` 原始二进制字节流输出；
+ * 5. **耗时度量与编码支持**：自动统计 `durationMs`，支持自定义 `encoding`（如 Windows GBK/CP936 解码）；
+ * 6. **灵活判定与快速抛错**：默认返回 `ok: false` 供业务层分支判定，亦可通过 `throwOnError: true` 自动抛错。
+ * 
+ * @param command 可执行命令名称或路径（如 "git", "agent-browser", "docker", "jq"）
+ * @param args 传递给命令的参数列表（默认为 []）
+ * @param options 运行选项（工作目录、环境变量、取消信号、超时、stdin、字符编码、抛错开关）
+ * @returns ExecCliResult 执行结果结构体
+ */
+export function execCli(
+  command: string,
+  args: string[] = [],
+  options: ExecCliOptions = {}
+): ExecCliResult {
+  const startTime = performance.now();
+
+  // 1. 检查取消信号
+  if (options.signal?.aborted) {
+    const errRes: ExecCliResult = {
+      ok: false,
+      exitCode: -1,
+      stdout: "",
+      stderr: "Command aborted before execution by signal",
+      raw: new Uint8Array(0),
+      durationMs: 0,
+    };
+    if (options.throwOnError) {
+      throw new Error(errRes.stderr);
+    }
+    return errRes;
+  }
+
+  // 2. 跨平台绝对路径解析（解决 Windows 下 npm 全局 .cmd shim 识别问题）
+  const hasPathSep = command.includes("/") || command.includes("\\");
+  const binPath = hasPathSep ? command : (Bun.which(command) || command);
+
+  if (!hasPathSep && !Bun.which(command)) {
+    const errRes: ExecCliResult = {
+      ok: false,
+      exitCode: -1,
+      stdout: "",
+      stderr: `Command '${command}' not found in PATH.`,
+      raw: new Uint8Array(0),
+      durationMs: Math.round(performance.now() - startTime),
+    };
+    if (options.throwOnError) {
+      throw new Error(errRes.stderr);
+    }
+    return errRes;
+  }
+
+  // 3. 处理标准输入数据
+  let stdinOption: Uint8Array | "ignore" | undefined = "ignore";
+  if (options.input !== undefined) {
+    if (typeof options.input === "string") {
+      stdinOption = new TextEncoder().encode(options.input);
+    } else if (options.input instanceof Uint8Array) {
+      stdinOption = options.input;
+    }
+  }
+
+  try {
+    const proc = Bun.spawnSync([binPath, ...args], {
+      cwd: options.cwd || process.cwd(),
+      env: options.env ? { ...process.env, ...options.env } : process.env,
+      stdin: stdinOption,
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: options.timeout,
+    });
+
+    const durationMs = Math.round(performance.now() - startTime);
+    const timedOut = Boolean((proc as any).exitedDueToTimeout);
+
+    // 4. 自定义字符集解码
+    const decoder = new TextDecoder(options.encoding || "utf-8");
+    const rawStdout = proc.stdout ? new Uint8Array(proc.stdout) : new Uint8Array(0);
+    const rawStderr = proc.stderr ? new Uint8Array(proc.stderr) : new Uint8Array(0);
+
+    const stdout = rawStdout.length > 0 ? decoder.decode(rawStdout).trim() : "";
+    let stderr = rawStderr.length > 0 ? decoder.decode(rawStderr).trim() : "";
+
+    if (timedOut && !stderr) {
+      stderr = `Command '${command}' timed out after ${options.timeout}ms`;
+    }
+
+    const exitCode = timedOut ? -1 : (proc.exitCode ?? (proc.success ? 0 : -1));
+    const ok = !timedOut && exitCode === 0;
+
+    const result: ExecCliResult = {
+      ok,
+      exitCode,
+      stdout,
+      stderr,
+      raw: rawStdout,
+      timedOut: timedOut || undefined,
+      durationMs,
+    };
+
+    if (options.throwOnError && !ok) {
+      throw new Error(stderr || `Command '${command}' failed with exit code ${exitCode}`);
+    }
+
+    return result;
+  } catch (err: any) {
+    const durationMs = Math.round(performance.now() - startTime);
+    const errRes: ExecCliResult = {
+      ok: false,
+      exitCode: -1,
+      stdout: "",
+      stderr: err?.message || String(err),
+      raw: new Uint8Array(0),
+      durationMs,
+    };
+    if (options.throwOnError) {
+      throw err;
+    }
+    return errRes;
+  }
+}
+
+/**
+ * 启动后台守护进程类 CLI 命令的选项配置。
+ */
+export interface SpawnDetachedOptions {
+  /**
+   * 可执行命令名称或路径（如 "agent-browser", "docker", "daemon"）。
+   */
+  command: string;
+
+  /**
+   * 传递给命令的参数列表（默认为 []）。
+   */
+  args?: string[];
+
+  /**
+   * 就绪探测回调函数（返回 true 表示守护进程已就绪或命令副作用已生效）。
+   */
+  probe: () => Promise<boolean> | boolean;
+
+  /**
+   * 轮询探测间隔时间（单位：毫秒，默认为 400ms）。
+   */
+  intervalMs?: number;
+
+  /**
+   * 总超时时间（单位：毫秒，默认为 30000ms）。
+   */
+  timeoutMs?: number;
+
+  /**
+   * 协作式取消信号（如 ActionContext 中的 ctx.signal）。
+   */
+  signal?: AbortSignal;
+
+  /**
+   * 子进程工作目录，默认为当前工作目录 (process.cwd())。
+   */
+  cwd?: string;
+
+  /**
+   * 自定义环境变量字典（合并到 process.env 之上）。
+   */
+  env?: Record<string, string>;
+}
+
+/**
+ * 安全执行“会拉起后台守护进程”的 CLI 命令（如 agent-browser open）。
+ *
+ * 核心三步工作流：
+ * 1. 异步 fire：stdio 全 ignore —— 确保后台 daemon 进程继承不到任何管道句柄，从根源杜绝管道 EOF 挂起；
+ * 2. 等 CLI 进程自身退出：错开冷启动窗口，避免探测命令并发拉起第二个 daemon 导致冲突；
+ * 3. 轮询探测就绪：执行轻量 probe 回调确认守护进程就绪或副作用生效。
+ *
+ * @param options 启动与探测配置项
+ * @returns Promise<boolean> 若在超时前 probe 返回 true 则返回 true；若超时仍未就绪则返回 false
+ */
+export async function spawnDetached(options: SpawnDetachedOptions): Promise<boolean> {
+  const { command, args = [], probe, signal, cwd, env } = options;
+  const intervalMs = options.intervalMs ?? 400;
+  const timeoutMs = options.timeoutMs ?? 30_000;
+
+  // 1. 检查取消信号
+  if (signal?.aborted) {
+    throw new Error("Command aborted before execution by signal");
+  }
+
+  // 2. 跨平台绝对路径解析（解决 Windows 下 npm 全局 .cmd shim 识别问题）
+  const hasPathSep = command.includes("/") || command.includes("\\");
+  const binPath = hasPathSep ? command : (Bun.which(command) || command);
+
+  if (!hasPathSep && !Bun.which(command)) {
+    throw new Error(`Command '${command}' not found in PATH.`);
+  }
+
+  // 3. fire-and-forget：ignore 所有 stdio，unref 防止阻塞事件循环
+  const child = Bun.spawn([binPath, ...args], {
+    cwd: cwd || process.cwd(),
+    env: env ? { ...process.env, ...env } : process.env,
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+    signal,
+  });
+  child.unref();
+
+  // 4. 等待 CLI 前端进程自身退出（错开冷启动窗口，避免 probe 并发拉起两个 daemon）
+  try {
+    await child.exited;
+  } catch (err) {
+    if (signal?.aborted) {
+      throw new Error("aborted");
+    }
+    throw err;
+  }
+
+  if (signal?.aborted) {
+    throw new Error("aborted");
+  }
+
+  // 5. 轮询探测就绪
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      throw new Error("aborted");
+    }
+
+    try {
+      const ready = await probe();
+      if (ready) {
+        return true;
+      }
+    } catch (probeErr) {
+      if (signal?.aborted) {
+        throw new Error("aborted");
+      }
+      // probe 异常通常为守护进程未完全就绪时的暂时性错误，继续等待轮询
+    }
+
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    const sleepTime = Math.min(intervalMs, remaining);
+    await new Promise((resolve) => setTimeout(resolve, sleepTime));
+  }
+
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export { defineAction } from "./action";
+export {
+  execCli,
+  spawnDetached,
+  type ExecCliOptions,
+  type ExecCliResult,
+  type SpawnDetachedOptions,
+} from "./cli";
+export {
+  createTestRuntime,
+  MemoryConfig,
+  MemoryStateStore,
+  MemoryLogger,
+  type TestRuntime,
+  type TestRuntimeOptions,
+} from "./test-runtime";
+export type {
+  ActionContext,
+  ActionDefinition,
+  ActionInvoker,
+  Config,
+  ExecutionResult,
+  JsonSchema,
+  Logger,
+  RuntimeError,
+  RunRecord,
+  RunStatus,
+  StateStore,
+} from "./types";
+
+

package/src/test-runtime.ts

@@ -0,0 +1,273 @@
+import type {
+  ActionContext,
+  ActionDefinition,
+  ActionInvoker,
+  Config,
+  Logger,
+  StateStore,
+} from "./types";
+
+/**
+ * 创建内存测试运行时所需的初始化选项。
+ */
+export interface TestRuntimeOptions {
+  /** 初始注入的配置键值对映射 */
+  config?: Record<string, unknown>;
+  /** 初始注入的状态键值对映射 */
+  state?: Record<string, unknown>;
+  /** 自定义日志记录器（可选，默认创建 MemoryLogger） */
+  logger?: Logger;
+  /** 自定义取消信号（可选，默认使用未中断的 AbortSignal） */
+  signal?: AbortSignal;
+}
+
+/**
+ * 基于内存 Map 的只读/可写配置实现，专供单元测试使用。
+ */
+export class MemoryConfig implements Config {
+  private store: Map<string, unknown>;
+
+  constructor(initial: Record<string, unknown> = {}) {
+    this.store = new Map(Object.entries(initial));
+  }
+
+  get<T = unknown>(key: string): T | undefined;
+  get<T = unknown>(key: string, defaultValue: T): T;
+  get<T = unknown>(key: string, defaultValue?: T): T | undefined {
+    if (this.store.has(key)) {
+      return this.store.get(key) as T;
+    }
+    return defaultValue;
+  }
+
+  has(key: string): boolean {
+    return this.store.has(key);
+  }
+
+  /**
+   * 在测试期间动态更新或插入配置值。
+   * @param key 配置键名
+   * @param value 配置值
+   */
+  set(key: string, value: unknown): void {
+    this.store.set(key, value);
+  }
+}
+
+/**
+ * 内存状态条目结构体，包含数据值与可选的过期时间戳。
+ */
+export interface MemoryStateEntry {
+  value: unknown;
+  expiresAt?: number;
+}
+
+/**
+ * 基于内存 Map 的状态存储实现，支持命名空间隔离与 TTL 自动失效，专供单元测试使用。
+ */
+export class MemoryStateStore implements StateStore {
+  private store: Map<string, any>;
+  private namespace: string;
+
+  constructor(
+    store?: Map<string, any>,
+    namespace = ""
+  ) {
+    this.store = store || new Map();
+    this.namespace = namespace;
+  }
+
+  private qualify(key: string): string {
+    return this.namespace ? `${this.namespace}:${key}` : key;
+  }
+
+  private extractEntry(raw: unknown): MemoryStateEntry {
+    if (
+      raw !== null &&
+      typeof raw === "object" &&
+      ("__actiondock_entry__" in (raw as Record<string, unknown>) ||
+        "expiresAt" in (raw as Record<string, unknown>))
+    ) {
+      return raw as MemoryStateEntry;
+    }
+    return { value: raw };
+  }
+
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    const qKey = this.qualify(key);
+    const raw = this.store.get(qKey);
+    if (raw === undefined) return undefined;
+    const entry = this.extractEntry(raw);
+    if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+      this.store.delete(qKey);
+      return undefined;
+    }
+    return (entry.value !== undefined ? structuredClone(entry.value) : undefined) as T;
+  }
+
+  async set<T = unknown>(
+    key: string,
+    value: T,
+    ttl?: number
+  ): Promise<void> {
+    const qKey = this.qualify(key);
+    const expiresAt =
+      typeof ttl === "number" && ttl > 0 ? Date.now() + ttl * 1000 : undefined;
+
+    const entry: MemoryStateEntry = {
+      value: structuredClone(value),
+      expiresAt,
+    };
+    (entry as any).__actiondock_entry__ = true;
+    this.store.set(qKey, entry);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const qKey = this.qualify(key);
+    return this.store.delete(qKey);
+  }
+
+  async clear(prefix = ""): Promise<number> {
+    const keysToDelete = await this.keys(prefix);
+    let count = 0;
+    for (const k of keysToDelete) {
+      if (this.store.delete(this.qualify(k))) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  async keys(prefix = ""): Promise<string[]> {
+    const fullPrefix = this.qualify(prefix);
+    const now = Date.now();
+    const result: string[] = [];
+    for (const [k, raw] of this.store.entries()) {
+      if (k.startsWith(fullPrefix)) {
+        const entry = this.extractEntry(raw);
+        if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
+          this.store.delete(k);
+          continue;
+        }
+        if (this.namespace) {
+          result.push(k.slice(this.namespace.length + 1));
+        } else {
+          result.push(k);
+        }
+      }
+    }
+    return result;
+  }
+
+  scope(namespace: string): StateStore {
+    const nextNs = this.namespace
+      ? `${this.namespace}:${namespace}`
+      : namespace;
+    return new MemoryStateStore(this.store, nextNs);
+  }
+}
+
+/**
+ * 内存日志记录器实现，将所有日志记录在数组中以便在测试断言中检索。
+ */
+export class MemoryLogger implements Logger {
+  public logs: Array<{ level: string; message: string; data?: unknown }> = [];
+
+  debug(message: string, data?: unknown): void {
+    this.logs.push({ level: "debug", message, data });
+  }
+
+  info(message: string, data?: unknown): void {
+    this.logs.push({ level: "info", message, data });
+  }
+
+  warn(message: string, data?: unknown): void {
+    this.logs.push({ level: "warn", message, data });
+  }
+
+  error(message: string, data?: unknown): void {
+    this.logs.push({ level: "error", message, data });
+  }
+}
+
+/**
+ * 测试运行时接口，提供对内存配置、状态和日志的直接访问及便捷的 Action 执行方法。
+ */
+export interface TestRuntime {
+  /** 内存配置实例 */
+  config: MemoryConfig;
+  /** 内存状态存储实例 */
+  state: MemoryStateStore;
+  /** 内存日志记录器 */
+  logger: MemoryLogger;
+  /**
+   * 执行指定的 Action 并返回最终输出结果
+   * @param action 目标 Action
+   * @param input 输入参数
+   */
+  run<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O>;
+}
+
+/**
+ * 创建用于单元测试的轻量级内存测试运行时（TestRuntime）。
+ * 
+ * 特点：
+ * 1. 零外部依赖：无需依赖 SQLite 或本地文件系统，即开即用。
+ * 2. 真实语义：完整支持状态持久化、TTL 过期、命名空间隔离、Action 相互调用与环路死锁检测。
+ * 
+ * @param options 初始化选项（可选初始 config, state, logger, signal）
+ * @returns TestRuntime 实例
+ * 
+ * @example
+ * ```ts
+ * const runtime = createTestRuntime({
+ *   config: { API_KEY: "test_key" }
+ * });
+ * const result = await runtime.run(myAction, { foo: "bar" });
+ * expect(result.success).toBe(true);
+ * expect(await runtime.state.get("some_key")).toBe(1);
+ * ```
+ */
+export function createTestRuntime(options: TestRuntimeOptions = {}): TestRuntime {
+  const config = new MemoryConfig(options.config || {});
+  const memoryMap = new Map<string, unknown>(
+    Object.entries(options.state || {})
+  );
+  const state = new MemoryStateStore(memoryMap);
+  const logger = (options.logger as MemoryLogger) || new MemoryLogger();
+  const signal = options.signal ?? new AbortController().signal;
+
+  const callStack: string[] = [];
+
+  const invoker: ActionInvoker = {
+    async invoke<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O> {
+      if (callStack.includes(action.id)) {
+        throw new Error(
+          `Cycle detected in action invocation: ${callStack.join(" -> ")} -> ${action.id}`
+        );
+      }
+      callStack.push(action.id);
+      try {
+        const ctx: ActionContext = {
+          config,
+          state,
+          actions: invoker,
+          log: logger,
+          signal,
+        };
+        return await action.run(input, ctx);
+      } finally {
+        callStack.pop();
+      }
+    },
+  };
+
+  return {
+    config,
+    state,
+    logger,
+    async run<I, O>(action: ActionDefinition<I, O>, input: I): Promise<O> {
+      return invoker.invoke(action, input);
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,204 @@
+/**
+ * 标准 JSON Schema 结构定义。
+ * 支持对象模式（Object Schema）或布尔模式（Boolean Schema）。
+ */
+export type JsonSchema = Record<string, unknown> | boolean;
+
+/**
+ * ActionDock 标准运行时错误对象。
+ */
+export interface RuntimeError {
+  /** 机器可读的唯一错误码，例如 ACTION_NOT_FOUND, INPUT_VALIDATION_FAILED, ACTION_TIMEOUT 等 */
+  code: string;
+  /** 人类可读的错误描述信息 */
+  message: string;
+  /** 结构化的附加错误详情（如 JSON Schema 校验失败的具体字段列表） */
+  details?: unknown;
+  /** 导致此错误的底层原始异常或原因 */
+  cause?: unknown;
+}
+
+/**
+ * 标准执行结果信封（JSON Envelope）。
+ * ActionDock 在 CLI、独立二进制、HTTP Runner 和 MCP 等所有场景中均输出该格式。
+ */
+export type ExecutionResult<T = unknown> =
+  | {
+      /** 执行是否成功 */
+      ok: true;
+      /** 本次执行的全局唯一运行 ID（UUIDv4） */
+      runId: string;
+      /** Action 执行返回的业务数据 */
+      data: T;
+    }
+  | {
+      /** 执行是否失败 */
+      ok: false;
+      /** 本次执行的全局唯一运行 ID（UUIDv4） */
+      runId: string;
+      /** 运行时错误详情 */
+      error: RuntimeError;
+    };
+
+/**
+ * 配置提供器接口（只读查询）。
+ * 遵循 5 层优先级链：CLI 参数 > 本地 SQLite > 全局 SQLite > 环境变量 > 项目默认值 > 回退默认值。
+ */
+export interface Config {
+  /**
+   * 获取指定键的配置值，未设置时返回 undefined
+   * @param key 配置键名
+   */
+  get<T = unknown>(key: string): T | undefined;
+  /**
+   * 获取指定键的配置值，未设置时返回提供的默认值
+   * @param key 配置键名
+   * @param defaultValue 默认回退值
+   */
+  get<T = unknown>(key: string, defaultValue: T): T;
+  /**
+   * 检查指定键是否存在配置值（无论来源于哪一层优先级）
+   * @param key 配置键名
+   */
+  has(key: string): boolean;
+}
+
+/**
+ * 共享状态持久化存储接口。
+ * 提供跨 Action 调用的数据共享与持久化存储能力，支持命名空间与基于秒的 TTL 自动过期机制。
+ */
+export interface StateStore {
+  /**
+   * 读取指定键的状态值。若键已过期则返回 undefined
+   * @param key 状态键名
+   */
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  /**
+   * 设置状态键值对，可选指定过期存活时间（TTL）
+   * @param key 状态键名
+   * @param value 要存储的数据值（会自动进行深拷贝/序列化）
+   * @param ttl 存活时间（单位：秒）。不传或 <= 0 表示永久有效
+   */
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+  /**
+   * 删除指定键的状态数据。
+   * @param key 状态键名
+   * @returns 是否实际删除了数据（true: 存在并删除，false: 不存在）
+   */
+  delete(key: string): Promise<boolean>;
+  /**
+   * 清空当前命名空间（或指定前缀）下的所有状态数据
+   * @param prefix 可选的键名前缀过滤条件
+   * @returns 实际清除的条目数量
+   */
+  clear(prefix?: string): Promise<number>;
+  /**
+   * 列出当前命名空间下所有匹配前缀的状态键名（已自动过滤已过期的键）
+   * @param prefix 键名前缀过滤条件
+   */
+  keys(prefix?: string): Promise<string[]>;
+  /**
+   * 创建一个具有独立命名空间隔离的子 StateStore 实例
+   * @param namespace 命名空间标识
+   */
+  scope(namespace: string): StateStore;
+}
+
+/**
+ * 结构化日志记录器接口。
+ * 所有日志输出均定向到 stderr，确保不污染 stdout 中的 JSON 信封。
+ */
+export interface Logger {
+  /** 记录调试级别日志 */
+  debug(message: string, data?: unknown): void;
+  /** 记录信息级别日志 */
+  info(message: string, data?: unknown): void;
+  /** 记录警告级别日志 */
+  warn(message: string, data?: unknown): void;
+  /** 记录错误级别日志 */
+  error(message: string, data?: unknown): void;
+}
+
+/**
+ * Action 间相互调用的执行器接口。
+ * 支持在 Action 内部安全调用同 Package 或其他 Action，内置调用栈防死循环环路检测。
+ */
+export interface ActionInvoker {
+  /**
+   * 调用指定的 Action 并传入参数，返回其执行结果
+   * @param action 目标 Action 定义对象
+   * @param input 传递给目标 Action 的输入参数
+   */
+  invoke<I, O>(
+    action: ActionDefinition<I, O>,
+    input: I
+  ): Promise<O>;
+}
+
+/**
+ * 传递给 Action `run` 处理函数的运行时上下文对象。
+ */
+export interface ActionContext {
+  /** 配置读取接口，自动按多层优先级解析配置 */
+  config: Config;
+  /** 状态持久化存储接口，提供跨 Action 调用的数据存取与 TTL */
+  state: StateStore;
+  /** Action 相互调用接口，支持模块化组合与复用 */
+  actions: ActionInvoker;
+  /** 结构化日志接口，输出定向至 stderr */
+  log: Logger;
+  /** 取消信号，用于感知客户端中断、超时或 SIGINT */
+  signal: AbortSignal;
+}
+
+/**
+ * Action 动作定义契约。
+ * 通过 `defineAction({...})` 声明。
+ */
+export interface ActionDefinition<I = unknown, O = unknown> {
+  /** Action 唯一标识符（例如: "github.get-pr" 或 "sample.greet"） */
+  id: string;
+  /** Action 功能描述，用于 CLI 帮助文档、Agent 发现以及 MCP Tool 描述 */
+  description?: string;
+  /** 输入参数的 JSON Schema 校验规范 */
+  inputSchema?: JsonSchema;
+  /** 输出结果的 JSON Schema 校验规范 */
+  outputSchema?: JsonSchema;
+  /**
+   * Action 的核心业务执行函数
+   * @param input 符合 inputSchema 契约的输入数据
+   * @param ctx 运行时上下文对象（包含 config, state, actions, log, signal）
+   */
+  run(input: I, ctx: ActionContext): Promise<O> | O;
+}
+
+/**
+ * 运行记录状态枚举。
+ */
+export type RunStatus = "running" | "success" | "failed" | "cancelled";
+
+/**
+ * Action 执行运行历史记录。
+ */
+export interface RunRecord {
+  /** 全局唯一运行 ID (UUIDv4) */
+  id: string;
+  /** 所属 Action Package 的唯一 ID */
+  packageId: string;
+  /** 所执行的 Action ID */
+  actionId: string;
+  /** 父级调用的运行 ID（若由其他 Action 嵌套调用触发） */
+  parentRunId?: string;
+  /** 运行生命周期状态 */
+  status: RunStatus;
+  /** 输入参数快照 */
+  input: unknown;
+  /** 执行成功时的输出结果 */
+  output?: unknown;
+  /** 执行失败时的错误信息 */
+  error?: RuntimeError;
+  /** 开始执行时间（ISO 8601 格式） */
+  startedAt: string;
+  /** 结束执行时间（ISO 8601 格式，进行中时为 undefined） */
+  finishedAt?: string;
+}