58 lines
3.2 KiB
Markdown
58 lines
3.2 KiB
Markdown
# 事件映射
|
||
|
||
## 三层映射
|
||
|
||
Pi 发出的事件首先经过 `PiEventAdapter` 变成经过裁剪和脱敏的 `HarnessEvent`。Web 的 reducer 再把有序事件投影为 assistant-ui 消息、工具和运行状态。Pi 原始对象不会直接进入浏览器。
|
||
|
||
| Pi / Harness 来源 | HarnessEvent | Web / assistant-ui 状态 |
|
||
| --- | --- | --- |
|
||
| Session 创建 | `session.started` | 建立初始 timeline |
|
||
| HTTP message input | `user.message` | user message，附件仅为 IDs |
|
||
| Harness 开始 run | `run.started` | `isRunning=true`，显示停止按钮 |
|
||
| `message_update.text_delta` | `assistant.delta` | 按稳定 messageId 追加文本 |
|
||
| 最终 assistant `message_end`（非 toolUse / error） | `assistant.completed` | assistant message complete |
|
||
| `tool_execution_start` | `tool.requested` | 创建工具调用 part |
|
||
| `tool_execution_end` 成功 | `tool.completed` | 自定义工具使用 Pi result.details 展示指标和保存结果 |
|
||
| `tool_execution_end` 失败 | `tool.failed` | 工具卡显示安全错误 |
|
||
| Broker 请求 | `approval.required` | 打开服务器审批 Dialog |
|
||
| Broker 决策 / 超时 / 取消 | `approval.resolved` | 关闭 pending 状态 |
|
||
| AttachmentStore 成功 | `attachment.uploaded` | 保存安全附件元数据 |
|
||
| AttachmentStore 拒绝 | `attachment.rejected` | timeline / 错误状态 |
|
||
| ModelStore 配置 | `model.configured` | 更新安全模型摘要 |
|
||
| Harness 正常结束 | `run.completed` | run 和消息标为 complete |
|
||
| Harness 取消 | `run.cancelled` | 消息 incomplete/cancelled |
|
||
| Harness 失败 | `run.failed` | 消息 incomplete/error |
|
||
| Session 删除 | `session.ended` | 连接回到 idle |
|
||
|
||
## Skill 推导事件
|
||
|
||
`skill.requested` 和 `skill.loaded` 不是 Pi SDK 的原生事件。Harness 按下面条件推导：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[Pi read start] --> B[realpath]
|
||
B --> C{是否匹配 SkillIndex}
|
||
C -->|否| D[只保留普通 tool 事件]
|
||
C -->|是| E[skill.requested]
|
||
E --> F{同一 toolCallId read 成功}
|
||
F -->|是| G[skill.loaded]
|
||
F -->|否| H[不发 loaded]
|
||
```
|
||
|
||
真实路径匹配避免仅凭用户提供的字符串伪造 Skill 活动。事件由 Session 队列串行处理，因此异步 `realpath` 不会导致 read end 越过 read start。
|
||
|
||
运行时索引匹配 Session 内的只读 Skill 正文快照，目录面板仍展示来源路径。模型尚未输出文本时，首个工具事件也会建立 assistant 消息，避免工具卡片一直隐藏到最终回复。
|
||
|
||
## 顺序、重放与去重
|
||
|
||
- 每个 Session 的 sequence 从 1 单调递增。
|
||
- SSE 初次连接可用 `afterSequence`，重连可用 `Last-Event-ID`。
|
||
- Server 先重放 cursor 之后的事件，再订阅新事件，并发送 heartbeat。
|
||
- Web 忽略 sequence 小于等于当前值的重复事件。
|
||
- sequence 出现缺口时，Web 不应用该事件，而是重置投影并从 0 重连。
|
||
- timeline 最多保留 500 条客户端状态，界面显示最近 100 条筛选结果。
|
||
|
||
## 数据最小化
|
||
|
||
事件负载经过 `redactAndLimit`。API Key、authorization、token 等敏感字段被脱敏；工具参数和结果有字节上限。图片事件只含 ID、MIME、字节数和尺寸，不含 base64。错误映射只保留明确 code 和有限长度的安全消息。
|