feat: initial commit

docs/event-mapping.md

@@ -0,0 +1,25 @@
+# Event mapping
+
+Pi 原生事件到 HarnessEvent 的转换集中在 `packages/harness/src/pi-event-adapter.ts`。未识别事件安全忽略，不会让 Run 崩溃。
+
+| Pi / Harness fact | HarnessEvent | assistant-ui / UI state |
+| --- | --- | --- |
+| message text delta | `assistant.delta` | 按 messageId 合并文本，status running |
+| assistant message end | `assistant.completed` | message status complete，polite live announcement |
+| extension `tool_call` preflight | `tool.requested` | Tool part running / approval pending |
+| tool execution success | `tool.completed` | Tool result success |
+| tool execution error | `tool.failed` | Tool result error |
+| canonical Skill `read` request | `skill.requested` | Catalog 高亮 requested |
+| 同一 read 成功结果 | `skill.loaded` | Catalog 高亮 loaded |
+| ApprovalBroker request | `approval.required` | Tool card + modal pending |
+| broker decision/timeout/cancel | `approval.resolved` | approved/denied/expired/cancelled |
+| registry accepts message | `user.message`, `run.started` | user message + running |
+| prompt resolves | `run.completed` | run idle |
+| abort by user/system | `run.cancelled` | incomplete，显示 reason |
+| prompt/create failure | `run.failed` | incomplete/error |
+
+Skill requested/loaded 是 Harness 推导事件，不是 Pi 原生事件。匹配依据是 `DefaultResourceLoader` 已发现的 canonical `SKILL.md` 索引；仅文件名相同不算命中。
+
+`tool.requested` 在 extension preflight 写入，后续 Pi `tool_execution_start` 按 toolCallId 去重。读取类 Tool 的 completed event 只暴露安全摘要，避免把 Skill 正文或文件内容复制到 Timeline。参数会限长、敏感字段脱敏，绝对路径转换为项目相对路径或 `<protected-path>`。
+
+SSE 事件 id 是 eventId，事件名是 HarnessEvent type。`Last-Event-ID` 比 query `afterSequence` 优先；若 cursor 早于 1000 条保留窗口，先发送 `stream.gap`，客户端重新建立可识别边界，而不是静默丢事件。