3.2 KiB
3.2 KiB
| title | created | updated | type | tags | sources | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 运行时过程事件 | 2026-05-07 | 2026-05-07 | concept |
|
|
运行时过程事件
运行时过程事件是 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() 会把事件追加到：
<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 恢复历史过程回放。