70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
---
|
||
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]]
|