以下为本文档的中文说明agent-tracing智能体追踪是LobeHub开发的一款零配置本地开发工具用于记录和检查AI智能体的执行快照。它通过CLI命令行界面提供对智能体每一步执行的细粒度洞察。在开发模式下AgentRuntimeService.executeStep()方法会自动将每一步执行记录为部分快照partial snapshots存储在.agent-tracing目录中当操作完成时这些部分快照会被合并为一个完整的ExecutionSnapshot JSON文件。该技能的数据流设计精巧执行步骤循环构建StepPresentationData写入部分快照到磁盘完成时最终化为时间戳加追踪ID命名的JSON文件。它会同时捕获上下文引擎数据包括agentDocuments、systemRole等重型负载这些数据通过旁路通道传递不进入Redis状态管道从而避免性能瓶颈。CLI提供了丰富的查看命令inspect查看追踪概览list列出所有快照并支持按步骤查看消息(-m)、工具调用(-t)、原始事件(-e)、运行时上下文(-c)等。开发者还可以使用–payload(-p)查看上下文引擎输入概览使用–memory(-M)查看注入的用户记忆。该技能特别适合调试复杂的多步骤AI智能体系统帮助开发者理解LLM的输入输出、工具调用流程和上下文引擎的工作方式。它提供了从原始数据到格式化输出的完整调试链路是智能体应用开发中不可或缺的诊断工具。Agent Tracing CLI Guidelobechat/agent-tracingis a zero-config local dev tool that records agent execution snapshots to disk and provides a CLI to inspect them.How It WorksInNODE_ENVdevelopment,AgentRuntimeService.executeStep()automatically records each step to.agent-tracing/as partial snapshots. When the operation completes, the partial is finalized into a completeExecutionSnapshotJSON file.Data flow: executeStep loop - buildStepPresentationData- write partial snapshot to disk - on completion, finalize to.agent-tracing/{timestamp}_{traceId}.jsonContext engine capture: InRuntimeExecutors.ts, thecall_llmexecutor callsctx.tracingContextEngine(input, output)afterserverMessagesEngine()processes messages.AgentRuntimeService.executeStepbuffers the call per step and forwards it toOperationTraceRecorder.appendStepas the typedcontextEnginefield. CE flows through this side channel rather than theeventsarray so its heavy payload (agentDocuments, systemRole, …) never enters the Redis state pipeline (LOBE-9110).Package Locationpackages/agent-tracing/ src/ types.ts # ExecutionSnapshot, StepSnapshot, SnapshotSummary store/ types.ts # ISnapshotStore interface file-store.ts # FileSnapshotStore (.agent-tracing/*.json) recorder/ index.ts # appendStepToPartial(), finalizeSnapshot() viewer/ index.ts # Terminal rendering: renderSnapshot, renderStepDetail, renderMessageDetail, renderSummaryTable, renderPayload, renderPayloadTools, renderMemory cli/ index.ts # CLI entry point (#!/usr/bin/env bun) inspect.ts # Inspect command (default) partial.ts # Partial snapshot commands (list, inspect, clean) index.ts # Barrel exportsData StorageCompleted snapshots:.agent-tracing/{ISO-timestamp}_{traceId-short}.jsonLatest symlink:.agent-tracing/latest.jsonIn-progress partials:.agent-tracing/_partial/{operationId}.jsonFileSnapshotStoreresolves fromprocess.cwd()—run CLI from the repo rootCLI CommandsAll commands run from therepo root:# View latest trace (tree overview, inspect is the default command)agent-tracing agent-tracing inspect agent-tracing inspecttraceIdagent-tracing inspect latest# List recent snapshotsagent-tracing list agent-tracing list-l20# Inspect specific step (-s is short for --step)agent-tracing inspecttraceId-s0# View messages (-m is short for --messages)agent-tracing inspecttraceId-s0-m# View full content of a specific message (by index shown in -m output)agent-tracing inspecttraceId-s0--msg2agent-tracing inspecttraceId-s0--msg-input1# View tool call/result details (-t is short for --tools)agent-tracing inspecttraceId-s1-t# View raw events (-e is short for --events)agent-tracing inspecttraceId-s0-e# View runtime context (-c is short for --context)agent-tracing inspecttraceId-s0-c# View context engine input overview (-p is short for --payload)agent-tracing inspecttraceId-pagent-tracing inspecttraceId-s0-p# View available tools in payload (-T is short for --payload-tools)agent-tracing inspecttraceId-Tagent-tracing inspecttraceId-s0-T# View user memory (-M is short for --memory)agent-tracing inspecttraceId-Magent-tracing inspecttraceId-s0-M# Raw JSON output (-j is short for --json)agent-tracing inspecttraceId-jagent-tracing inspecttraceId-s0-j# List in-progress partial snapshotsagent-tracing partial list# Inspect a partial (use inspect directly — all flags work with partial IDs)agent-tracing inspectpartialOperationIdagent-tracing inspectpartialOperationId-Tagent-tracing inspectpartialOperationId-p# Clean up stale partial snapshotsagent-tracing partial cleanInspect Flag Reference| Flag | Short | Description| Default Step || ----------------- | ----- | ------------------------------------------------------------------------------------------------- | ------------ ||--step n|-s| Target a specific step | — ||--messages|-m| Messages context (CE input → params → LLM payload) | — ||--tools|-t| Tool calls results (what agent invoked) | — ||--events|-e| Raw events (llm_start, llm_result, etc.) | — ||--context|-c| Runtime context payload (raw) | — ||--system-role|-r| Full system role content | 0 ||--env| | Environment context | 0 ||--payload|-p| Context engine input overview (model, knowledge, tools summary, memory summary, platform context) | 0 ||--payload-tools|-T| Available tools detail (plugin manifests LLM function definitions) | 0 ||--memory|-M| Full user memory (persona, identity, contexts, preferences, experiences) | 0 ||--diff n|-d| Diff against step N (use with-ror--env) | — ||--msg n| | Full content of message N from Final LLM Payload | — ||--msg-input n| | Full content of message N from Context Engine Input | — ||--json|-j| Output as JSON (combinable with any flag above) | — |Flags marked “Default Step: 0” auto-select step 0 if--stepis not provided. All flags supportlatestor omitted traceId.Typical Debug Workflow# 1. Trigger an agent operation in the dev UI# 2. See the overviewagent-tracing inspect# 3. List all traces, get traceIdagent-tracing list# 4. Quick overview of what was fed into context engineagent-tracing inspect-p# 5. Inspect a specific steps messages to see what was sent to the LLMagent-tracing inspect TRACE_ID-s0-m# 6. Drill into a truncated message for full contentagent-tracing inspect TRACE_ID-s0--msg2# 7. Check available tools vs actual tool callsagent-tracing inspect-T# available toolsagent-tracing inspect-s1-t# actual tool calls results# 8. Inspect user memory injected into the conversationagent-tracing inspect-M# 9. Diff system role between steps (multi-step agents)agent-tracing inspect TRACE_ID-r-d2Key TypesinterfaceExecutionSnapshot{traceId:string;operationId:string;model?:string;provider?:string;startedAt:number;completedAt?:number;completionReason?:|done|error|interrupted|max_steps|cost_limit|waiting_for_human;totalSteps:number;totalTokens:number;totalCost:number;error?:{type:string;message:string};steps:StepSnapshot[];}interfaceStepSnapshot{stepIndex:number;stepType:call_llm|call_tool;executionTimeMs:number;content?:string;// LLM outputreasoning?:string;// Reasoning/thinkinginputTokens?:number;outputTokens?:number;toolsCalling?:Array{apiName:string;identifier:string;arguments?:string};toolsResult?:Array{apiName:string;identifier:string;isSuccess?:boolean;output?:string;};messages?:any[];// DB messagesbefore step context?:{phase:string;payload?:unknown;stepContext?:unknown};events?:Array{type:string;[key:string]:unknown};contextEngine?:{input?:unknown;// contextEngineInput minus messages toolsConfig (reconstructible from baseline)output?:unknown;// processed messages array (final LLM payload)};}–messages Output StructureWhen using--messages, the output shows three sections (if context engine data is available):Context Engine Input— DB messages passed to the engine, with[0],[1], … indices. Use--msg-input Nto view full content.Context Engine Params— systemRole, model, provider, knowledge, tools, userMemory, etc.Final LLM Payload— Processed messages after context engine (system date injection, user memory, history truncation, etc.), with[0],[1], … indices. Use--msg Nto view full content.Integration PointsRecording:apps/server/src/services/agentRuntime/AgentRuntimeService.ts— in theexecuteStep()method, after buildingstepPresentationData, writes partial snapshot in dev modeContext engine capture:apps/server/src/modules/AgentRuntime/RuntimeExecutors.ts— incall_llmexecutor, afterserverMessagesEngine()returns, callsctx.tracingContextEngine(input, output).AgentRuntimeService.executeStepbuffers it per step and passes it totraceRecorder.appendStepas the typedcontextEnginefield (kept off theeventsarray to stay out of Redis state).Store:FileSnapshotStorereads/writes to.agent-tracing/relative toprocess.cwd()3d:[“,,,L40”,null,{“content”:“$41”,“frontMatter”:{“name”:“agent-tracing”,“description”:“Agent tracing CLI for execution snapshots. Use for agent-tracing, traces, snapshots, LLM call inspection, context engine data, agent step analysis, or execution debugging.”,“user-invocable”:false}}]3e:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L42,L42,L42,L43”,“L44,L44,L44,L45”,“L46,L46,L46,L47”]}]]}]]}]48:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]
