niceeval 0.5.4 → 0.6.1

package/src/o11y/execution-tree.ts

@@ -0,0 +1,367 @@
+// ExecutionTree:标准事件流骨架 + 可选 OTel span enrichment 合成的统一执行记录
+// (定稿见 docs/observability.md「OTLP traces → 统一瀑布图」、docs/concepts.md「执行树」词条)。
+//
+// 骨架来自 events,永远不因有没有 spans 而变形:message / thinking / skill.loaded /
+// action(action.called + action.result 按 callId 合并成一个节点)/ subagent(同理)/
+// input.requested / compaction / error,每种事件一个节点,顺序 = 事件出现的顺序
+// (合并节点的位置 = 它 called/loaded 那条事件的位置,result/completed 只更新已有节点,
+// 不产生新位置)。没有 spans 时,`span` 字段整体缺失——渲染层据此判断「timing
+// unavailable」,不是 0,也不是从别处反推的估算值。
+//
+// spans 参数假定调用方已经跑过 otlp/select.ts::selectTraceSpans——本函数不做 firehose
+// 过滤,只做「一批语义 span → 骨架节点」的关联,职责单一。关联只走显式 correlation:
+// span.attributes.call_id(现有 mapper 的既有约定,如 claude-code mapper 把
+// tool_use_id 复制过来)或 GenAI 语义约定的 gen_ai.tool.call.id,与 action/subagent/
+// skill.loaded 节点的 callId 精确相等才算数(skill.loaded 的 callId 是可选的——只有原生
+// 协议把 Skill 加载表达成可关联的工具调用时才有,如 Claude Code 的 Skill tool_use;没有
+// 就不参与关联,不影响骨架本身)——从不按 span 名字、文本内容或时间接近度去猜。一个
+// callId 必须唯一对应一条候选 span 才合并;callId 找不到对应骨架节点,或同一个
+// callId 撞了多条候选 span(无法唯一决定该并给哪个节点),这些 span 一律降级成独立
+// 标注的 telemetry-only 节点,绝不強行择一合并。
+//
+// 合并进节点的是【完整 span 对象】(startMs/endMs/parentSpanId/status/attributes 原样
+// 保留供下钻),不重新定义耗时之类的派生字段——耗时是 endMs - startMs,渲染层自己算。
+// action 节点合并时额外吃下 otlp/select.ts::enrichTraceWithIO 想做的事:那个函数把
+// ToolCall.input/output 反向糊到 span.attributes 上的 io.tool/io.input/io.output/io.status
+// 四个键(给独立的 trace.json/瀑布图用),这里在节点内部原地重做一遍同一份 join(同一个
+// IO_MAX 截断预算,ioText 从 otlp/select.ts 直接复用,没有另立口径)——好处不是"action
+// 节点自己没有 input/output"(它本来就有,且是不截断的完整 JsonValue,比 span 视角更权威),
+// 而是让合并出的 span 本身也带一份和旧 enrichTraceWithIO 输出一致的属性,不强迫下游
+// 区分"这份 span 是不是已经被 enrichTraceWithIO 处理过"才能读到入参出参文本。
+// subagent 节点没有 tool-call 形状的 input 字段,不套用这份 io.* 注入。
+//
+// 没有 timingConfidence 字段的设计取舍:otlp/turn-otel.ts 在 traceparent 缺失时会退化成
+// 「按时间窗口把一批 span 划给某一轮 send」的兜底归属(串行守卫下才可靠,见该文件的
+// TurnSpans.attribution),这确实是比「span 精确挂在某个 callId 下」更弱的保证。但这个
+// 弱保证的信息在到达本函数之前就已经丢了——SessionManager 只在运行期 log 一次 warning
+// (`otel.windowAttribution`),从不把 attribution 写回 TraceSpan 本身,所以传进来的
+// spans 天生就分不出「这条是 traceparent 精确挂上的」还是「这条是窗口兜底扫进来的」。
+// 就算这个信息保留了下来,也不该拿它伪造一个「timing 存在但打折扣」的中间态:窗口兜底
+// 归属的是「这批 span 属于哪一轮 send」,本函数关联的是「这条 span 属于哪个 callId 节点」
+// ——两者是正交的轴。一条 span 不管是靠 traceparent 还是窗口兜底进的 trace,它自己的
+// call_id 属性不变,凭 call_id 精确匹配到节点的正确性完全不受轮次归属精度影响(唯一
+// 会被窗口误差污染的是「这条 span 该算哪一轮」这类跨轮聚合,ExecutionTree 不做这个)。
+// 所以诚实的状态只有二元的:call_id 唯一命中 → 有 span(timing 可信);否则 → 没有,
+// 不发明第三档「有 span 但不确定」。
+
+import type { InputRequest, JsonValue, StreamEvent, ToolName, TraceSpan } from "../types.ts";
+import { ioText } from "./otlp/select.ts";
+
+// ───────────────────────── 节点类型 ─────────────────────────
+
+interface ExecutionNodeBase {
+  /** 本函数内确定性生成,同一份 (events, spans) 输入永远产出同一批 id(不是全局稳定 id,
+   * 不跨调用持久化——目前没有下游需要跨次运行比对同一个节点)。 */
+  id: string;
+  /** 唯一关联上的 OTel span(供下钻;渲染层用 endMs - startMs 算耗时)。action 节点的
+   * span.attributes 额外补了 io.tool/io.input/io.output/io.status(见 withIoAttributes);
+   * 其余节点原样保留。缺失 = timing unavailable——要么这次运行没有 OTel 接入,要么有 span
+   * 但没能唯一关联到这个节点上;两种情况都不是「假装有耗时」,统一表现为字段不存在。 */
+  span?: TraceSpan;
+}
+
+export interface ExecutionMessageNode extends ExecutionNodeBase {
+  kind: "message";
+  role: "assistant" | "user";
+  text: string;
+}
+
+export interface ExecutionThinkingNode extends ExecutionNodeBase {
+  kind: "thinking";
+  text: string;
+}
+
+/** Skill 加载节点——一等,直接来自 StreamEvent 的 "skill.loaded",不靠工具名/文本猜。 */
+export interface ExecutionSkillNode extends ExecutionNodeBase {
+  kind: "skill.loaded";
+  skill: string;
+  /**
+   * 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有,和 StreamEvent 同名字段同一含义。
+   * 存在时参与和 action/subagent 节点同一套 callId 关联(见主函数 nodeByCallId):Claude Code
+   * 的 Skill 调用本身就是一次 tool_use,OTel mapper 同样会把它的 tool_use_id 复制成
+   * span.attributes.call_id,唯一命中时这个节点也应该拿到 timing,不因为节点 kind 是
+   * skill.loaded 就被排除在 enrichment 之外。
+   */
+  callId?: string;
+}
+
+/**
+ * action.called + action.result 按 callId 合并成一个节点。`status` 多了 "pending"
+ * (StreamEvent 的 action.result.status 没有这一档)——这是 ExecutionTree 独有的中间态,
+ * 表示这次运行结束时结果始终没有回来(如超时截断的 transcript),诚实地区分「还没完成」
+ * 和「跑完但失败/被拒绝」。
+ */
+export interface ExecutionActionNode extends ExecutionNodeBase {
+  kind: "action";
+  callId: string;
+  /** 原始工具名(未归一化),对齐 StreamEvent.action.called.name。 */
+  name: string;
+  /** 归一化后的规范工具名,省略表示 adapter 没能归一(等同 ToolCall.name 缺省为 "unknown")。 */
+  tool?: ToolName;
+  input: JsonValue;
+  output?: JsonValue;
+  status: "pending" | "completed" | "failed" | "rejected";
+}
+
+/** subagent.called + subagent.completed 按 callId 合并;pending 语义同 ExecutionActionNode。 */
+export interface ExecutionSubagentNode extends ExecutionNodeBase {
+  kind: "subagent";
+  callId: string;
+  name: string;
+  remoteUrl?: string;
+  output?: JsonValue;
+  status: "pending" | "completed" | "failed";
+}
+
+export interface ExecutionInputRequestedNode extends ExecutionNodeBase {
+  kind: "input.requested";
+  request: InputRequest;
+}
+
+export interface ExecutionCompactionNode extends ExecutionNodeBase {
+  kind: "compaction";
+  reason?: string;
+}
+
+export interface ExecutionErrorNode extends ExecutionNodeBase {
+  kind: "error";
+  message: string;
+}
+
+/**
+ * span 存在、有意义,但唯一关联不到任何骨架节点——原样保留成独立节点,清楚标注「只有遥测、
+ * 没有对应事件」,不悄悄猜着并进某个骨架节点。`span` 是必填字段:这类节点的全部内容就是
+ * 这一条 span 本身,没有骨架事件可以叠加。
+ */
+export interface ExecutionTelemetryNode {
+  kind: "telemetry";
+  id: string;
+  span: TraceSpan;
+}
+
+export type ExecutionNode =
+  | ExecutionMessageNode
+  | ExecutionThinkingNode
+  | ExecutionSkillNode
+  | ExecutionActionNode
+  | ExecutionSubagentNode
+  | ExecutionInputRequestedNode
+  | ExecutionCompactionNode
+  | ExecutionErrorNode
+  | ExecutionTelemetryNode;
+
+export interface ExecutionTree {
+  /**
+   * 骨架节点在前,顺序 = 事件出现顺序;telemetry-only 节点(未能唯一关联的 span)
+   * 按 span.startMs 追加在骨架之后——它们不属于骨架,不改变骨架的节点/顺序/内容,
+   * 只是叠加在末尾的额外证据。
+   */
+  nodes: ExecutionNode[];
+  /**
+   * 这次运行是否提供过任何 span——不代表关联成功,只代表「OTel 接入过」。供渲染层区分
+   * 两种不同的诚实提示:整体没有 OTel 接入(该字段为 false,所有节点自然都没有 span),
+   * 和 OTel 接入了但这一个节点恰好关联不上(该字段为 true,该节点的 span 仍缺失)。
+   */
+  timingAvailable: boolean;
+}
+
+// ───────────────────────── 关联 key ─────────────────────────
+
+/** span 的显式 correlation key,按优先级尝试(见模块头注:只认这两个,不猜)。 */
+const CALL_ID_ATTRS = ["call_id", "gen_ai.tool.call.id"] as const;
+
+function spanCallId(span: TraceSpan): string | undefined {
+  const attrs = span.attributes ?? {};
+  for (const key of CALL_ID_ATTRS) {
+    const v = attrs[key];
+    if (typeof v === "string" && v) return v;
+  }
+  return undefined;
+}
+
+/**
+ * 与 `otlp/select.ts` 的 `enrichTraceWithIO` 同口径地给合并上的 span 补
+ * `io.tool` / `io.input` / `io.output` / `io.status`——node 的 input/output 已经是
+ * 事件流自身的完整 JsonValue(不截断,给程序化消费方);这里另外派生一份文本、按
+ * `IO_MAX` 截断,给任何只认 span.attributes 通用形状的下游(比如把 span 原样转存/
+ * 展示的调试视图)一份和旧 enrichTraceWithIO 输出完全一致的键。不修改传入的 span 对象。
+ */
+function withIoAttributes(span: TraceSpan, node: ExecutionActionNode): TraceSpan {
+  const attributes: Record<string, JsonValue> = { ...span.attributes };
+  if (node.name) attributes["io.tool"] = node.name;
+  if (node.input !== undefined && node.input !== null) attributes["io.input"] = ioText(node.input);
+  if (node.output !== undefined && node.output !== null) attributes["io.output"] = ioText(node.output);
+  if (node.status !== "pending") attributes["io.status"] = node.status;
+  return { ...span, attributes };
+}
+
+// ───────────────────────── 主函数 ─────────────────────────
+
+/**
+ * 纯函数:把标准事件流(骨架)与一批已挑选好的 OTel span(可选 enrichment)合成一棵
+ * ExecutionTree。events 决定节点的存在、顺序与内容;spans 只能给已存在的节点补时间,
+ * 从不新增、删除或重排骨架节点。
+ */
+export function buildExecutionTree(events: readonly StreamEvent[], spans: readonly TraceSpan[]): ExecutionTree {
+  const nodes: ExecutionNode[] = [];
+  const actionById = new Map<string, ExecutionActionNode>();
+  const subagentById = new Map<string, ExecutionSubagentNode>();
+  const skillByCallId = new Map<string, ExecutionSkillNode>();
+  let seq = 0;
+  const nextId = (prefix: string): string => `${prefix}-${seq++}`;
+
+  for (const ev of events) {
+    switch (ev.type) {
+      case "message":
+        nodes.push({ id: nextId("message"), kind: "message", role: ev.role, text: ev.text });
+        break;
+
+      case "thinking":
+        nodes.push({ id: nextId("thinking"), kind: "thinking", text: ev.text });
+        break;
+
+      case "skill.loaded": {
+        const node: ExecutionSkillNode = { id: nextId("skill"), kind: "skill.loaded", skill: ev.skill, callId: ev.callId };
+        if (ev.callId) skillByCallId.set(ev.callId, node);
+        nodes.push(node);
+        break;
+      }
+
+      case "action.called": {
+        const node: ExecutionActionNode = {
+          id: `action-${ev.callId}`,
+          kind: "action",
+          callId: ev.callId,
+          name: ev.name,
+          tool: ev.tool,
+          input: ev.input,
+          status: "pending",
+        };
+        actionById.set(ev.callId, node);
+        nodes.push(node);
+        break;
+      }
+
+      case "action.result": {
+        const existing = actionById.get(ev.callId);
+        if (existing) {
+          existing.output = ev.output;
+          existing.status = ev.status;
+        } else {
+          // 只有结果、没配上调用(乱序/截断的 transcript):补一条占位节点,位置 = 结果到达时,
+          // 与 derive.ts::deriveRunFacts 的同名兜底一致,不静默丢弃这条结果。
+          const node: ExecutionActionNode = {
+            id: `action-${ev.callId}`,
+            kind: "action",
+            callId: ev.callId,
+            name: "unknown",
+            input: null,
+            output: ev.output,
+            status: ev.status,
+          };
+          actionById.set(ev.callId, node);
+          nodes.push(node);
+        }
+        break;
+      }
+
+      case "subagent.called": {
+        const node: ExecutionSubagentNode = {
+          id: `subagent-${ev.callId}`,
+          kind: "subagent",
+          callId: ev.callId,
+          name: ev.name,
+          remoteUrl: ev.remoteUrl,
+          status: "pending",
+        };
+        subagentById.set(ev.callId, node);
+        nodes.push(node);
+        break;
+      }
+
+      case "subagent.completed": {
+        const existing = subagentById.get(ev.callId);
+        if (existing) {
+          existing.output = ev.output;
+          existing.status = ev.status;
+        } else {
+          const node: ExecutionSubagentNode = {
+            id: `subagent-${ev.callId}`,
+            kind: "subagent",
+            callId: ev.callId,
+            name: "unknown",
+            output: ev.output,
+            status: ev.status,
+          };
+          subagentById.set(ev.callId, node);
+          nodes.push(node);
+        }
+        break;
+      }
+
+      case "input.requested":
+        nodes.push({ id: nextId("input"), kind: "input.requested", request: ev.request });
+        break;
+
+      case "compaction":
+        nodes.push({ id: nextId("compaction"), kind: "compaction", reason: ev.reason });
+        break;
+
+      case "error":
+        nodes.push({ id: nextId("error"), kind: "error", message: ev.message });
+        break;
+
+      default: {
+        // 穷尽性检查:StreamEvent 加新变体时这里编译报错,提醒同步补一个节点类型。
+        const _exhaustive: never = ev;
+        void _exhaustive;
+      }
+    }
+  }
+
+  // callId → 骨架节点(action、subagent、skill.loaded 共用同一命名空间;call id 在一次 run
+  // 内按现有约定唯一——deriveRunFacts 等既有折叠逻辑同样这么假设)。skill.loaded 的 callId
+  // 是可选的(不是所有原生协议都把 Skill 加载表达成可关联的工具调用),只有存在时才参与。
+  const nodeByCallId = new Map<string, ExecutionActionNode | ExecutionSubagentNode | ExecutionSkillNode>();
+  for (const n of actionById.values()) nodeByCallId.set(n.callId, n);
+  for (const n of subagentById.values()) nodeByCallId.set(n.callId, n);
+  for (const n of skillByCallId.values()) nodeByCallId.set(n.callId!, n);
+
+  // 按 callId 分组候选 span;没有 callId 的直接进「待定为 telemetry-only」。
+  const spansByCallId = new Map<string, TraceSpan[]>();
+  const uncorrelated: TraceSpan[] = [];
+  for (const span of spans) {
+    const callId = spanCallId(span);
+    if (!callId) {
+      uncorrelated.push(span);
+      continue;
+    }
+    const list = spansByCallId.get(callId);
+    if (list) list.push(span);
+    else spansByCallId.set(callId, [span]);
+  }
+
+  const telemetry: ExecutionTelemetryNode[] = [];
+  for (const [callId, candidates] of spansByCallId) {
+    const node = nodeByCallId.get(callId);
+    if (node && candidates.length === 1) {
+      const matched = candidates[0];
+      // action 节点额外补 io.tool/io.input/io.output/io.status——同 otlp/select.ts 的
+      // enrichTraceWithIO 一个口径(同一个 IO_MAX 截断预算),这里在节点内部原地做一遍,
+      // 不依赖调用方传入的 spans 是不是已经被 enrichTraceWithIO 处理过。subagent 与
+      // skill.loaded 节点没有对应的 tool-call 形状入参/出参字段,原样保留 span,不发明 io.* 键。
+      node.span = node.kind === "action" ? withIoAttributes(matched, node) : matched;
+    } else {
+      // 没有对应骨架节点,或同一 callId 撞了多条 span(无法唯一决定该并给谁)——
+      // 都降级为 telemetry-only,不強行择一合并。
+      for (const span of candidates) telemetry.push({ id: `telemetry-${span.spanId}`, kind: "telemetry", span });
+    }
+  }
+  for (const span of uncorrelated) telemetry.push({ id: `telemetry-${span.spanId}`, kind: "telemetry", span });
+  telemetry.sort((a, b) => a.span.startMs - b.span.startMs);
+
+  return {
+    nodes: [...nodes, ...telemetry],
+    timingAvailable: spans.length > 0,
+  };
+}

package/src/o11y/otlp/receiver.ts

@@ -10,7 +10,7 @@ import { parseOtlpTraces } from "./parse.ts";
 import { t } from "../../i18n/index.ts";
 
 export interface TraceReceiver {
-  /** agent 应导出到的完整端点(host 由后端定:docker → host.docker.internal)。 */
+  /** agent 应导出到的完整端点(host 由 provider 定:docker → host.docker.internal)。 */
   endpoint(host: string): string;
   /** 目前为止收到并解析出的全部 span(副本)。 */
   collect(): TraceSpan[];

package/src/o11y/otlp/select.ts

@@ -48,10 +48,14 @@ export function selectTraceSpans(spans: TraceSpan[]): TraceSpan[] {
   return kept.sort((a, b) => a.startMs - b.startMs);
 }
 
-/** I/O 文本上限:文件内容/命令输出可能很大,截一下别把 trace 撑爆。 */
-const IO_MAX = 4000;
+/**
+ * I/O 文本上限:文件内容/命令输出可能很大,截一下别把 trace 撑爆。导出给
+ * `execution-tree.ts` 复用——ExecutionTree 的 action 节点给合并上去的 span 补同一份
+ * io.* attributes,必须和这里同一个截断预算,不能另立一个数字。
+ */
+export const IO_MAX = 4000;
 
-function ioText(v: unknown): string {
+export function ioText(v: unknown): string {
   const s = typeof v === "string" ? v : JSON.stringify(v);
   if (s === undefined) return "";
   return s.length > IO_MAX ? s.slice(0, IO_MAX) + `…(+${s.length - IO_MAX})` : s;

package/src/o11y/parsers/claude-code.test.ts

@@ -0,0 +1,175 @@
+// claude-code transcript 解析器单测。
+//
+// 重点覆盖 Skill 加载识别(定稿见 docs/observability.md「OTLP traces → 统一瀑布图」、
+// docs/concepts.md「标准事件流」词条:skill.loaded 是一等事件,不靠工具名/文本猜):
+// 真实原生格式是 tool_use 块 name:"Skill"、input:{ skill:"<skill 名>", args?:"..." }
+// (核对过 Claude Code CLI 自带的 SkillTool 定义,见 claude-code.ts 的 extractSkillName 头注)。
+// 这里额外覆盖大小写、限定名、和「普通工具调用完全不受影响」的回归锁——skill.loaded 是
+// 严格新增,不能改变任何非 Skill tool_use 的既有行为。
+
+import { describe, expect, it } from "vitest";
+import { parseClaudeCodeTranscript } from "./claude-code.ts";
+
+const line = (obj: object): string => JSON.stringify(obj);
+
+function toolUseLine(block: { id: string; name: string; input: object }) {
+  return line({ type: "assistant", message: { content: [{ type: "tool_use", ...block }] } });
+}
+
+function toolResultLine(toolUseId: string, content: unknown, isError = false) {
+  return line({ type: "user", message: { content: [{ type: "tool_result", tool_use_id: toolUseId, content, is_error: isError }] } });
+}
+
+describe("parseClaudeCodeTranscript — Skill 加载", () => {
+  it("Skill tool_use 产出 skill.loaded(带 callId),不产出 action.called", () => {
+    const raw = [
+      toolUseLine({ id: "toolu_01", name: "Skill", input: { skill: "pdf" } }),
+      toolResultLine("toolu_01", "PDF Processing\n\n## Quick start\n..."),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([{ type: "skill.loaded", skill: "pdf", callId: "toolu_01" }]);
+  });
+
+  it("识别限定名(namespace:skill),原样作为 skill 字段透传", () => {
+    const raw = toolUseLine({ id: "toolu_02", name: "Skill", input: { skill: "ms-office-suite:pdf" } });
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([{ type: "skill.loaded", skill: "ms-office-suite:pdf", callId: "toolu_02" }]);
+  });
+
+  it("工具名大小写不定也能识别(防御性小写比较)", () => {
+    const raw = toolUseLine({ id: "toolu_03", name: "skill", input: { skill: "xlsx" } });
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([{ type: "skill.loaded", skill: "xlsx", callId: "toolu_03" }]);
+  });
+
+  it("Skill 加载的 tool_result 被吃掉,不补发孤儿 action.result", () => {
+    const raw = [
+      toolUseLine({ id: "toolu_01", name: "Skill", input: { skill: "pdf" } }),
+      toolResultLine("toolu_01", "skill body here"),
+      line({ type: "assistant", message: { content: [{ type: "text", text: "done" }] } }),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events.map((e) => e.type)).toEqual(["skill.loaded", "message"]);
+    expect(events.some((e) => e.type === "action.result")).toBe(false);
+  });
+
+  it("input.skill 缺失或非字符串时不当作 Skill 加载,回落成普通 action.called", () => {
+    const raw = [
+      toolUseLine({ id: "toolu_04", name: "Skill", input: {} }),
+      toolUseLine({ id: "toolu_05", name: "Skill", input: { skill: 42 } }),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([
+      { type: "action.called", callId: "toolu_04", name: "Skill", input: {}, tool: "unknown" },
+      { type: "action.called", callId: "toolu_05", name: "Skill", input: { skill: 42 }, tool: "unknown" },
+    ]);
+  });
+
+  it("普通(非 Skill)工具调用完全不受影响:Bash 仍产出 action.called + action.result,顺序不变", () => {
+    const raw = [
+      toolUseLine({ id: "toolu_06", name: "Bash", input: { command: "ls" } }),
+      toolResultLine("toolu_06", "a.ts\nb.ts", false),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([
+      { type: "action.called", callId: "toolu_06", name: "Bash", input: { command: "ls" }, tool: "shell" },
+      { type: "action.result", callId: "toolu_06", output: "a.ts\nb.ts", status: "completed" },
+    ]);
+  });
+
+  it("Skill 加载与普通工具调用混合出现时,各自独立、顺序保持事件出现顺序", () => {
+    const raw = [
+      toolUseLine({ id: "t1", name: "Skill", input: { skill: "pdf" } }),
+      toolResultLine("t1", "skill body"),
+      toolUseLine({ id: "t2", name: "Read", input: { file_path: "/a.txt" } }),
+      toolResultLine("t2", "file contents"),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([
+      { type: "skill.loaded", skill: "pdf", callId: "t1" },
+      { type: "action.called", callId: "t2", name: "Read", input: { file_path: "/a.txt" }, tool: "file_read" },
+      { type: "action.result", callId: "t2", output: "file contents", status: "completed" },
+    ]);
+  });
+
+  it("Read/Write/Edit/WebFetch/WebSearch/Task 等既有别名归一不受 Skill 识别改动影响(回归锁)", () => {
+    const raw = [
+      toolUseLine({ id: "a", name: "Write", input: { file_path: "/x", content: "y" } }),
+      toolUseLine({ id: "b", name: "Task", input: { prompt: "go" } }),
+      toolUseLine({ id: "c", name: "WebSearch", input: { query: "q" } }),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+    const tools = events.filter((e) => e.type === "action.called").map((e) => (e as { tool?: string }).tool);
+
+    expect(tools).toEqual(["file_write", "agent_task", "web_search"]);
+  });
+});
+
+describe("parseClaudeCodeTranscript — 既有行为回归", () => {
+  it("assistant 文本 + thinking + tool_use 混合一行时,三者按既有顺序全部产出", () => {
+    const raw = line({
+      type: "assistant",
+      message: {
+        content: [
+          { type: "text", text: "checking files" },
+          { type: "thinking", thinking: "should look at package.json" },
+          { type: "tool_use", id: "c1", name: "Bash", input: { command: "cat package.json" } },
+        ],
+      },
+    });
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events).toEqual([
+      { type: "message", role: "assistant", text: "checking files" },
+      { type: "thinking", text: "should look at package.json" },
+      { type: "action.called", callId: "c1", name: "Bash", input: { command: "cat package.json" }, tool: "shell" },
+    ]);
+  });
+
+  it("失败的 tool_result(is_error)映射成 status: failed", () => {
+    const raw = [
+      toolUseLine({ id: "c1", name: "Bash", input: { command: "false" } }),
+      toolResultLine("c1", "command failed", true),
+    ].join("\n");
+
+    const { events } = parseClaudeCodeTranscript(raw);
+
+    expect(events[1]).toMatchObject({ type: "action.result", callId: "c1", status: "failed" });
+  });
+
+  it("compact_boundary 产出 compaction 事件并计数", () => {
+    const raw = line({ type: "system", subtype: "compact_boundary" });
+    const { events, compactions } = parseClaudeCodeTranscript(raw);
+    expect(events).toEqual([{ type: "compaction" }]);
+    expect(compactions).toBe(1);
+  });
+
+  it("空/未定义输入返回空事件流,不抛错", () => {
+    expect(parseClaudeCodeTranscript(undefined).events).toEqual([]);
+    expect(parseClaudeCodeTranscript("").events).toEqual([]);
+    expect(parseClaudeCodeTranscript("   \n  \n").events).toEqual([]);
+  });
+
+  it("坏 JSON 行不中断解析,标 parseSuccess: false 但保留其余行的事件", () => {
+    const raw = ["not json {{{", toolUseLine({ id: "c1", name: "Bash", input: {} })].join("\n");
+    const { events, parseSuccess } = parseClaudeCodeTranscript(raw);
+    expect(parseSuccess).toBe(false);
+    expect(events).toEqual([{ type: "action.called", callId: "c1", name: "Bash", input: {}, tool: "shell" }]);
+  });
+});

package/src/o11y/parsers/claude-code.ts

@@ -40,6 +40,24 @@ function normalizeToolName(name: string): ToolName {
   return normalizeShared(name, CLAUDE_TOOL_ALIASES);
 }
 
+// ───────────────────────── Skill 加载识别 ─────────────────────────
+
+/**
+ * Claude Code 原生调用 Skill 时,tool_use 块的 name 恒为 "Skill"(核对过 Claude Code CLI
+ * 自带的 SkillTool 定义:`buildTool({ name: SKILL_TOOL_NAME, ... })`,`SKILL_TOOL_NAME = "Skill"`,
+ * 严格大小写;这里放宽成大小写不敏感比较,只是防御性兜底,不代表原生真的会变大小写),
+ * input 的 schema 是 `z.object({ skill: z.string(), args: z.string().optional() })`——
+ * skill 名在 `input.skill`(不是 `command`),可能是限定名如 "ms-office-suite:pdf"。
+ */
+const SKILL_TOOL_NAME = "skill";
+
+/** name 是 Skill 工具、且 input.skill 是非空字符串时返回 skill 名;否则 undefined(交给调用方走普通 action.called)。 */
+function extractSkillName(name: string, input: JsonValue): string | undefined {
+  if (name.toLowerCase() !== SKILL_TOOL_NAME) return undefined;
+  const skill = get(input, "skill");
+  return typeof skill === "string" && skill ? skill : undefined;
+}
+
 // ───────────────────────── 小工具 ─────────────────────────
 
 function get(obj: unknown, key: string): unknown {
@@ -130,6 +148,10 @@ export function parseClaudeCodeTranscript(raw: string | undefined): ParsedTransc
   let requests = 0;
   let compactions = 0;
   let parseSuccess = true;
+  // 已识别成 skill.loaded 的 tool_use callId:对应的 tool_result 回来时要吃掉、
+  // 不再补发一条 action.result(否则会凭空多出一个没有 action.called 配对的孤儿事件,
+  // ExecutionTree 会把它当成占位工具调用节点,而 Skill 加载已经由 skill.loaded 表达过了)。
+  const skillCallIds = new Set<string>();
 
   if (!raw || !raw.trim()) {
     return { events, usage: { inputTokens: 0, outputTokens: 0 }, compactions: 0, parseSuccess: true };
@@ -175,6 +197,7 @@ export function parseClaudeCodeTranscript(raw: string | undefined): ParsedTransc
         if (toolResults.length > 0) {
           for (const r of toolResults) {
             const callId = String(get(r, "tool_use_id") ?? get(r, "id") ?? "unknown");
+            if (skillCallIds.has(callId)) continue; // Skill 加载的结果已经由 skill.loaded 表达过,不重复计入。
             const isError = get(r, "is_error") === true || !!get(r, "error");
             events.push({
               type: "action.result",
@@ -203,6 +226,14 @@ export function parseClaudeCodeTranscript(raw: string | undefined): ParsedTransc
             const name = String(get(b, "name") ?? "unknown");
             const callId = String(get(b, "id") ?? "unknown");
             const input = (get(b, "input") ?? {}) as JsonValue;
+
+            const skill = extractSkillName(name, input);
+            if (skill !== undefined) {
+              events.push({ type: "skill.loaded", skill, callId });
+              skillCallIds.add(callId);
+              continue;
+            }
+
             events.push({
               type: "action.called",
               callId,
@@ -214,6 +245,7 @@ export function parseClaudeCodeTranscript(raw: string | undefined): ParsedTransc
         }
       } else if (type === "tool_result" || type === "tool_response") {
         const callId = String(get(data, "tool_use_id") ?? get(data, "id") ?? "unknown");
+        if (skillCallIds.has(callId)) continue; // 同上:Skill 加载的结果不重复计入 action.result。
         const isError = get(data, "is_error") === true || !!get(data, "error");
         events.push({
           type: "action.result",

package/src/o11y/types.ts

@@ -54,7 +54,7 @@ export interface InputRequest {
 }
 
 /**
- * 标准事件流的词汇(对标 docs/agents-and-adapters.md)。adapter 唯一的硬活就是把
+ * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把
  * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。
  */
 export type StreamEvent =
@@ -69,6 +69,11 @@ export type StreamEvent =
       output?: JsonValue;
       status: "completed" | "failed" | "rejected";
     }
+  /**
+   * 一次 Skill 加载:一等事件,由 adapter 从原生协议里识别出「这是加载 Skill」并直接产出,
+   * 不靠 renderer 按工具名/文本猜。`callId` 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有。
+   */
+  | { type: "skill.loaded"; skill: string; callId?: string }
   /** 发起一次子 agent 调用(如 Task 工具、远程 sub-agent);`remoteUrl` 仅远程子 agent 有。 */
   | { type: "subagent.called"; callId: string; name: string; remoteUrl?: string }
   /** 一次子 agent 调用的结果,按 `callId` 与对应的 `subagent.called` 对位。 */