# Trace for Pi｜多呈现工作观察器（归档方案）

> 状态：已归档。该方案解决“Pi 的真实运行状态应该显示在哪里”，但没有解决“Agent 连续行动时，总体意图和行动路径是什么”。它仍可作为后续意图系统的遥测与呈现基础设施。

## 一句话定义

一个本地、只读、事件驱动的 Pi 工作观察器：从 Pi extension 获取真实生命周期事件，形成统一状态，并通过 Pi 窗口、Herdr pane、文件和 macOS Pet 四种界面呈现。

## 设计边界

### 解决的问题

- Pi 当前是在等待模型、输出消息、调用工具、压缩、重试、阻塞还是完成；
- 当前工具、目标文件、耗时、context 使用量；
- 存在结构化计划时显示明确的 `completed / total`；
- 用户可在不同注意力场景中选择不同呈现界面。

### 不解决的问题

- 不解释连续数十次模型调用和工具调用背后的总体意图；
- 不重建 Agent 的长期行动路径；
- 不展示隐藏 reasoning；
- 不根据耗时伪造完成百分比；
- 不把日志滚动速度当作生产力或进度；
- 不自动批准权限、执行命令或发送提示词。

## 分层呈现

| 层级 | 位置 | 用途 |
|---|---|---|
| Glance | Pi 底栏 | 一眼确认当前状态 |
| Focus | Pi widget / overlay | 当前计划、阻塞和 context |
| Inspect | Herdr pane | 实时事件、工具和多 session |
| Ambient | macOS Pet | 离开终端后的完成或阻塞提醒 |
| Audit | 文件 | 调试、回放、脚本消费 |

默认策略：

```text
正常工作       → Pi 底栏
有明确计划     → Pi 底栏 + 小型 widget
用户想深入看   → 手动打开 Herdr pane
离开终端       → macOS Pet 提醒
任何时候       → 文件保留真实记录
```

不自动弹 pane，不自动打开窗口，不抢焦点。

## 总体架构

```text
                    ┌────────────────────────┐
                    │       Pi Session       │
                    └───────────┬────────────┘
                                │ lifecycle events
                    ┌───────────▼────────────┐
                    │   Trace Pi Extension   │
                    │                        │
                    │ normalize / redact     │
                    │ state reducer          │
                    │ event journal          │
                    └───┬────────┬────────┬──┘
                        │        │        │
              ┌─────────▼─┐  ┌───▼─────┐  ┌──────────▼─────────┐
              │ Pi UI     │  │ Files   │  │ Local Unix Socket │
              │ footer    │  │ NDJSON  │  │ live subscribers  │
              │ widget    │  │ snapshot│  └──────────┬─────────┘
              │ overlay   │  │ log     │             │
              └───────────┘  └─────────┘       ┌─────┴──────┐
                                               │            │
                                         Herdr pane     macOS Pet
```

第一版不引入独立 daemon。Pi extension 直接维护状态、写入事件文件并向本地 Unix socket 发布实时事件。未来需要统一观察 Pi、Codex、Claude 等多个运行时后，再提取独立 collector。

## 状态模型

```text
idle
starting
awaiting_model
streaming
running_tool
waiting_user
compacting
retrying
settled
blocked
error
disconnected
```

### Pi 事件映射

| Pi 事件 | Trace 状态 |
|---|---|
| `agent_start` | `starting` |
| `turn_start` | `awaiting_model` |
| 首次 `message_update` | `streaming` |
| `tool_execution_start` | `running_tool` |
| `tool_execution_update` | 更新工具进度 |
| `tool_execution_end` | 工具成功或失败 |
| `session_before_compact` | `compacting` |
| 自动失败后重新开始 | `retrying`（Derived） |
| `agent_settled` | `settled` |
| 显式等待用户输入 | `waiting_user` |
| 不可恢复错误 | `error` |

### 证据等级

| 等级 | 含义 |
|---|---|
| Observed | Pi、工具或外部系统直接确认 |
| Reported | Agent 自行报告但尚未验证 |
| Derived | 根据多个事件推导 |
| Unknown | 当前遥测无法判断 |

## 进度规则

绝不根据运行时间计算百分比。只有上游提供结构化计划或明确进度时，才显示 `2/5`。

允许的进度来源：

- Pi plan-mode extension；
- workflow phase；
- subagent orchestration；
- 工具明确提供的进度；
- 用户确认过的任务清单。

没有结构化计划时，只显示：

```text
running tests · 1m 42s
last event 6s ago
```

并行工具不强行选择唯一“当前工具”，而显示活跃工具数量和主要摘要。

## Pi 内显示

### 底栏

```text
Trace · ready · ctx 38%
● awaiting model · 08s · ctx 39%
● test · auth integration · 01:42 · ctx 42%
▲ blocked · waiting for confirmation
◌ compacting context
✓ settled · 3 tools · 02:18
```

### 计划 widget

只在存在明确计划时出现：

```text
Trace · Plan 2/5

✓ Inspect authentication flow
✓ Add failing regression test
● Fix session refresh
○ Run integration tests
○ Review diff
```

### Overlay 与命令

```text
/trace                 查看当前详情
/trace compact         只显示底栏
/trace detailed        开启计划 widget
/trace pane            在 Herdr 中打开观察 pane
/trace off             关闭 Pi 内显示，保留日志
```

Overlay 显示 session、状态、工具、耗时、模型、thinking level、context、计划、最近事件和遥测覆盖率。

## Herdr pane

Herdr 自带集成继续负责 `idle / working / blocked / done` 粗状态。详细观察 pane 不替换受 Herdr 管理的集成文件。

用户执行 `/trace pane` 后：

1. 检查 `HERDR_ENV=1`；
2. 获取当前 pane 几何；
3. 宽 pane 向右拆，窄 pane 向下拆；
4. 使用 `--no-focus`；
5. 新 pane 命名为 `trace`；
6. 运行 `trace watch --session <session-id>`。

Herdr 不可用时，降级为提示 `trace watch` 或 `tail -f`，不影响 Pi。

## 文件输出

```text
~/.local/state/trace/
├── active.json
└── sessions/
    └── <session-id>/
        ├── metadata.json
        ├── events.ndjson
        ├── snapshot.json
        └── activity.log
```

- `events.ndjson`：append-only 机器事件；
- `snapshot.json`：原子替换的当前状态；
- `activity.log`：适合 `tail -f` 的人类可读事实句；
- `metadata.json`：session、cwd、模型和可选 Herdr pane 引用。

默认不记录 prompt 正文、reasoning、完整命令、完整工具输出、环境变量、文件内容、API key 和 URL query 参数。

## macOS Pet

推荐使用 SwiftUI + AppKit 实现菜单栏与透明浮层。

### 动画语义

| 状态 | Pet 表现 |
|---|---|
| idle | 休息 |
| awaiting_model | 侧耳等待 |
| streaming | 阅读或思考姿态 |
| read | 翻书 |
| edit/write | 敲键盘 |
| bash/build | 操作工具台 |
| test | 观察仪表 |
| compacting | 整理背包或收纳纸张 |
| waiting_user | 举起问号牌 |
| blocked | 举起警示牌 |
| error | 摔倒后停住 |
| settled | 一次短庆祝，然后休息 |
| disconnected | 变灰并显示断线 |

第一版交互仅限查看详情、聚焦 pane、拖动、静音、固定、打开日志、多 session 切换及 blocked/done 通知。不得批准工具、中止 Pi、修改文件、发送 prompt 或自动重试。

## 共享协议

其他 Pi extension 可通过共享事件总线发布：

```text
trace:plan
trace:phase
trace:blocked
trace:progress
trace:evidence
```

如果没有扩展主动提供，Trace 不从普通自然语言中猜任务清单。

## 实施阶段

### Phase 1：Pi 内显示 + 文件

交付 extension、状态 reducer、footer、plan widget、overlay 和三种事件文件。

### Phase 2：Herdr pane

交付 `trace watch` TUI、`/trace pane`、自动布局与降级行为。

### Phase 3：macOS Pet

交付菜单栏应用、单 Pet 浮层、状态动画、多 session、通知、聚焦 pane、打开日志和 reduced motion。

### Phase 4：可选控制通道

只有用户明确需要时，再单独设计 abort、steer、approve 和 follow-up，并使用独立 capability 权限。

## 最脆弱的假设

该方案假设 Pi 生命周期和工具事件足以解释用户最关心的状态。如果长时间工具没有 progress update，只能显示“仍在运行、最后事件距今多久、内部进度未知”，不能猜测完成比例。

## 归档结论

该方案适合作为遥测层、事件日志和多界面 presenter，但其核心仍是“把 Pi coding-agent 插件拿到的信息组装显示”。它不能回答连续调用背后的总体目标、行动路径、分支原因和下一步，因此不应作为最终的人类注意力界面。