@ocdb/core

openclaw-debug-toolkit 的共享类型定义包。纯类型，无运行时代码。

所有其他包（@ocdb/plugin、@ocdb/tool-sdk、ocdt CLI）均从此包导入类型。

安装

npm install @ocdb/core

类型总览

DebugRun

一次 Agent 执行的顶层记录。

interface DebugRun {
  runId: string
  sessionId: string
  agentId: string
  parentRunId?: string           // fork 时指向源 run
  forkFromCheckpointId?: string  // fork 时指向源 checkpoint

  status: 'running' | 'completed' | 'failed' | 'cancelled'
  mode: 'live' | 'replay' | 'fork'

  startedAt: number
  endedAt?: number
  error?: unknown

  checkpoints: Checkpoint[]
  toolLedger: ToolCallRecord[]
  artifactRefs: ArtifactRef[]
  metadata: Record<string, unknown>
}

mode 含义：

| 值 | 含义 | |---|---| | live | 正常的 Agent 执行 | | replay | 使用 --captured 固定 LLM 输出的确定性重放 | | fork | 从某个 checkpoint 派生的调试 run |

Checkpoint

某个执行边界的完整状态快照。每次 run 会在 6 种边界处各打一个 checkpoint：

type CheckpointBoundary =
  | 'before_prompt_build'  // context 组装完成，prompt 构建前
  | 'before_model_call'    // 最终 prompt 已确定，LLM 调用前
  | 'after_model_call'     // 模型返回后
  | 'before_tool_call'     // 工具调用前（每次工具调用一个）
  | 'after_tool_call'      // 工具调用完成后
  | 'agent_end'            // run 结束

interface Checkpoint {
  checkpointId: string
  runId: string
  boundary: CheckpointBoundary
  stepIndex: number          // 第几轮 ReAct loop（-1 表示 agent_end）

  messages: Message[]        // 当时的完整消息列表
  systemPrompt?: string
  model?: ModelConfig        // LLM 配置（provider, model, temperature）
  promptVersion?: string     // prompt 模板版本

  runtimeContext: RuntimeContextSnapshot  // 当时的业务上下文快照
  toolCallId?: string        // tool 边界专用
  toolLedgerSnapshot: ToolCallRecord[]   // 当时的工具调用记录快照
  artifactRefs?: ArtifactRef[]

  finishReason?: string      // after_model_call 专用：模型停止原因
  usage?: {                  // after_model_call 专用：token 用量
    inputTokens: number
    outputTokens: number
  }
  createdAt: number
}

fork 语义：从某个 checkpoint fork 时，取出其 messages + runtimeContext，合并 ForkConfig 的覆盖项，创建新 debug session，后续步骤重新执行。

ToolCallRecord

单次工具调用的完整记录。Tool Cassette 的核心数据结构。

type SideEffectLevel =
  | 'none'                    // 纯函数，无副作用
  | 'read_only'               // 只读查询
  | 'expensive_read'          // 昂贵的只读（大查询、外部 API）
  | 'write'                   // 写入操作
  | 'external_irreversible'   // 外部不可逆（发消息、提单等）

type ReplayPolicy =
  | 'reuse_result'    // replay 时直接复用历史结果，跳过真实调用
  | 're_execute'      // replay 时重新执行
  | 'mock_result'     // replay 时注入 mock 数据
  | 'manual_confirm'  // 需要人工确认（当前版本等同于 re_execute）
  | 'forbid_replay'   // 禁止自动 replay，遇到直接报错

interface ToolCallRecord {
  toolCallId: string
  toolName: string
  args: unknown
  argsHash: string       // args 的 SHA-256 前 16 位，用于 cassette 匹配
  result?: unknown
  error?: unknown
  sideEffectLevel: SideEffectLevel
  replayPolicy: ReplayPolicy
  startedAt: number
  endedAt?: number
}

RuntimeContextSnapshot

可整体或局部替换的业务运行时上下文。fork 时最常修改的部分。

interface RuntimeContextSnapshot {
  user: {
    userId: string
    roleId: string
    permissions: string[]
  }
  conversation: {
    sessionId: string
    summary?: string
  }
  project: {
    projectId: string
    reportId?: string
    [key: string]: unknown   // 业务扩展字段
  }
  task: {
    taskId: string
    workflowId: string
    stepStates: Record<string, unknown>
  }
  tools: {
    availableTools: string[]
    toolMocks?: Record<string, unknown>
  }
  model: {
    provider: string
    model: string
    promptVersion: string
  }
}

ForkConfig

发起 fork 时的配置。由 CLI ocdb replay 命令或 HTTP POST /fork 传入。

interface ForkConfig {
  sourceRunId: string
  sourceCheckpointId: string

  // 模型覆盖（三选一）
  modelOverride?: {
    mode: 'captured'   // 使用历史 LLM 输出（确定性重放）
        | 'real'       // 使用原 run 的模型（不覆盖）
        | 'override'   // 替换为指定模型
    provider?: string  // override 模式下指定 provider
    model?: string     // override 模式下指定 model
  }

  // 局部覆盖 runtimeContext（深度 merge）
  contextPatch?: Partial<RuntimeContextSnapshot>

  // 工具 replay 策略覆盖（支持 '*' 通配符）
  // 例：{ '*': 'reuse_result', 'save_report': 'forbid_replay' }
  // 具名工具优先级高于 '*' 通配符
  toolPolicyMap?: Record<string, ReplayPolicy>

  // mode=mock_result 时注入的 mock 数据
  toolMockResults?: Record<string, unknown>

  // prompt 版本覆盖
  promptVersionOverride?: string
}

ArtifactRef

产物快照引用，用于对比两次 run 的产物差异。

interface ArtifactRef {
  artifactId: string
  type: string
  version: number
  contentHash: string
  storagePath: string
  createdAt: number
  metadata: Record<string, unknown>
}

Message

Agent 消息格式。

interface Message {
  role: 'user' | 'assistant' | 'tool' | 'system'
  content: unknown
  toolCallId?: string   // role=tool 时关联的 tool call ID
  toolName?: string     // role=tool 时的工具名称
}

完整导出列表

// run.ts
export type { DebugRun, RunStatus, RunMode }

// checkpoint.ts
export type { Checkpoint, CheckpointBoundary, ModelConfig, Message }

// tool-call.ts
export type { ToolCallRecord, SideEffectLevel, ReplayPolicy }

// artifact.ts
export type { ArtifactRef }

// context.ts
export type { RuntimeContextSnapshot }

// fork.ts
export type { ForkConfig }