---
title: 运行时过程事件
created: 2026-05-07
updated: 2026-05-07
type: concept
tags: [runtime, agent, tool, skill, websocket]
sources: [packages/backend/src/modules/netaclaw/runtime/process_events.ts, packages/backend/src/modules/netaclaw/runtime/attempt.ts, packages/backend/src/modules/netaclaw/service/skill_executor.ts, packages/backend/src/modules/netaclaw/tools/builtin/execute_skill.ts, packages/frontend/src/modules/agent/components/tool-process-timeline.vue, packages/frontend/src/modules/agent/utils/tool-process-display.ts]
---

# 运行时过程事件

运行时过程事件是 2026-05-07 新增的长耗时工具/Skill 进度表达机制。它把“工具正在做什么”从最终 `tool_result` 中拆出来，统一为可流式展示、可采样存档的 `RuntimeProcessEvent`，服务 [[skill-runtime]]、[[tool-system]]、[[vehicle-damage-skill]] 和前端对话页。

## 事件模型

`runtime/process_events.ts` 定义：

- `operationId`：一次工具、Skill、子 Agent 或 runtime 操作的稳定 ID。
- `parentOperationId`：父子操作关系。
- `targetType`：`tool`、`skill`、`subagent`、`task`、`runtime`。
- `source`：事件来源，当前包括 `skill`、`tool`、`subagent`、`runtime`。
- `stage`：阶段名，例如抽帧、检测、复核。
- `status`：`queued`、`started`、`running`、`completed`、`failed`、`cancelled`、`skipped`。
- `level`：`debug`、`info`、`warning`、`error`。
- `current/total/percent`：进度信息。
- `payload`：经过脱敏和截断的结构化补充信息。

`sanitizeProcessPayload()` 会过滤 key 中包含 api key、token、password、secret、authorization、credential 的字段，避免过程事件泄漏密钥。

## 缓冲与落盘

`ProcessEventBuffer` 对重复进度做节流，默认 400ms 聚合一次。终态事件会先 flush 同 operation 的待发送事件，再立即发出终态。

`appendRuntimeProcessLog()` 会把事件追加到：

```text
<dataDir>/netaclaw-process-events/<sessionId>/<operationId>.jsonl
```

同时返回 `runtime_process_log` 引用，便于 session metadata 保存抽样结果和完整日志位置。

## 工具与 Skill 接入

当前重点接入点：

- `execute_skill.ts`：把 compute-entry skill 的 process events 桥接为工具执行过程。
- `SkillExecutorService`：执行子进程时处理 stdout JSON 协议和过程事件。
- `runtime/attempt.ts`：在工具调用生命周期内携带 operationId、process log ref 和采样事件。
- `vehicle-damage-inspection`：在抽帧、检测、grounding、review 等长耗时阶段发出进度。

这使 compute-entry Skill 不再只能“运行结束后返回一个大 JSON”，而可以边运行边给用户可解释进度。

## 前端展示

前端新增：

- `components/tool-process-timeline.vue`：过程时间线组件。
- `utils/tool-process-display.ts`：事件文案、阶段和状态展示工具。
- `StreamingStatusCard.vue`、`message-item.vue`、`chat.ts`：消费流式/历史 metadata 中的 process events。

对话页可以从实时 WebSocket 事件展示进度，也可以从 session tree 节点 metadata 恢复历史过程回放。

## 相关页面

- [[tool-system]]
- [[skill-runtime]]
- [[vehicle-damage-skill]]
- [[websocket-gateway]]
- [[frontend-architecture]]