# pi-annotate

一个可视化的批注扩展，为 pi-agent 提供交互式批注界面，可用于审阅上下文消息和 Markdown 文档。在 macOS 上使用 [Glimpse](https://github.com/hazat/glimpse) 原生 WKWebView 窗口渲染，其他平台回退到浏览器标签页。

<p align="center">
  <img src="docs/demo/annotation-ui.png" alt="pi-annotate 注释界面截图" width="100%">
  <br>
  <em>注释界面：选中文本后弹出浮动工具栏，批注显示在右侧面板</em>
</p>

## 安装

```bash
pi install npm:@jackice/pi-annotate
```

或从本地路径安装：

```bash
pi install /path/to/pi-annotate
```

重启 pi 或运行 `/reload` 加载扩展。

**依赖要求：**
- pi-agent v0.35.0 或更高版本（需要扩展 API）
- macOS 原生窗口：`npm install -g glimpseui@">=0.8.1"`（可选，未安装时回退到浏览器）— Glimpse 0.8.1+ 提供原生剪贴板支持（`⌘C`/`⌘V`）

## 功能特性

- **消息批注**：为最后一条 assistant 消息添加可视化批注 — 选择文本、添加评论、发送反馈给 agent
- **文档批注**：在任何 markdown 文件（spec、plan、设计文档）上打开可视化批注界面
- **自动检测**：自动检测 `docs/superpowers/specs/` 或 `docs/superpowers/plans/` 下的新文档并打开批注界面
- **批注类型**：评论（comment）、建议修改（suggestion）、问题（issue）和表扬（praise）— 各有不同颜色标识
- **快捷标签**：一键预设标签用于常见反馈（需澄清说明、缺少关键细节、需要验证假设等）
- **浮动工具栏**：选中文本后弹出紧凑工具栏，包含评论、删除、快捷标签和赞许操作
- **内联评论弹窗**：点击工具栏上的评论按钮，在选中文本上方/下方添加详细文字反馈
- **反馈投递**：批注以结构化消息发送回 agent
- **直接批准**：无批注时可直接批准文档
- **主题切换**：`⌘+Shift+L` 切换深色/浅色主题（非 macOS 使用 `Ctrl+Shift+L`）
- **自动关闭**：提交反馈或批准后窗口自动关闭

## 工作原理

```
┌─────────┐     ┌──────────────────────────────────────┐     ┌─────────┐
│  Agent  │     │     Glimpse / Browser Annotation UI   │     │  Agent  │
│ 写文档   ├────►│                                      ├────►│ 接收反馈  │
│         │     │  选中文本 → 添加批注 → 发送反馈        │     │         │
└─────────┘     │         ↑                             │     └─────────┘
                │         └── 自动检测路径 ──────────────┤
                └──────────────────────────────────────┘
```

**生命周期：**
1. Agent 写了一份 spec/plan 文档，或你运行 `/annotate <file>` 或 `/annotate-last`
2. 本地服务器启动 → Glimpse 窗口打开（macOS）或浏览器标签页（其他平台）
3. 在文档中选中文本 → 浮动工具栏出现，包含批注操作
4. 通过评论（文本输入）、快捷标签（预设标签）、删除（建议移除）或赞许（表示认可）添加批注
5. 会话通过以下方式结束：
   - **发送反馈** → 批注以跟进消息发送回 agent
   - **批准** → 文档通过，不发送反馈（仅在无批注时可用）
   - **关闭窗口** → 会话结束，不发送反馈
6. 发送反馈或批准后窗口自动关闭

## 使用方法

扩展提供两个斜杠命令和一个自动检测钩子：

### `/annotate-last`

批注当前会话中最后一条 assistant 消息：

```
/annotate-last
```

在消息中选中文本，添加批注或快捷标签，然后向 agent 发送反馈。

### `/annotate <file>`

批注指定的 markdown 文件：

```
/annotate docs/superpowers/specs/my-design.md
/annotate PLAN.md
```

支持：
- 相对路径（相对于当前工作目录）
- 绝对路径
- `@` 前缀表示法（如 `@docs/superpowers/specs/...`）

### 自动检测

当 agent 创建或修改 `docs/superpowers/specs/` 或 `docs/superpowers/plans/` 下的文件时，扩展自动检测 assistant 回复中的文件路径并打开批注界面。

## 批注界面

### 浮动工具栏

选中任何文本后弹出浮动工具栏，包含四个操作：

| 按钮 | 操作 | 说明 |
|--------|--------|-------------|
| 💬 评论 | 打开文本输入框 | 输入对选中文本的详细反馈 |
| 🗑️ 删除 | 创建问题批注 | 建议移除选中的段落 |
| ⚡ 快捷标签 | 打开预设标签选择器 | 一键快速反馈 |
| 👍 赞许 | 创建表扬批注 | 标记选中文本为优秀 |

### 快捷标签

用于 spec、plan 和消息的预设标签：

| 键 | 标签 | 说明 |
|-----|-------|-------------|
| 1 | ❓ 需澄清说明 | 需要进一步解释 |
| 2 | 📋 缺少关键细节 | 缺少关键细节或具体内容 |
| 3 | 🔍 需要验证假设 | 潜在的假设需要验证 |
| 4 | 🔬 缺少具体示例 | 需要具体示例帮助理解 |
| 5 | ⚖️ 需权衡利弊 | 该方案的利弊需要讨论 |
| 6 | 🏗️ 过度设计 | 方案比实际需求更复杂 |
| 7 | 🚫 超出范围 | 超出已定义的范围 |
| 8 | ⚠️ 遗漏边界情况 | 潜在的边界情况未处理 |
| 9 | 📐 结构清晰 | 结构组织清晰 |
| 0 | 👍 方案不错 | 方案合理可行 |

### 批注面板

所有批注显示在右侧栏中。每条批注包含：
- 类型徽章（评论/建议修改/问题/表扬），带颜色编码
- 批注文字
- 原文预览
- 时间戳
- 编辑（✏️）和删除（🗑️）按钮

## 快捷键

| 按键 | 操作 |
|-----|--------|
| `⌘+Shift+L` | 切换深色/浅色主题（非 macOS 使用 `Ctrl`） |
| `1`-`9`, `0` | 按编号选择快捷标签（选择器打开时） |

## 文件结构

```
pi-annotate/
├── index.ts              # 扩展入口、命令、Glimpse 集成
├── server.ts              # 批注 HTTP 服务器（API 路由）
├── form/
│   └── annotate.html      # 批注界面（纯 HTML/CSS/JS，无构建步骤）
├── package.json
└── README.md
```

## 反馈格式

发送反馈时，agent 收到如下结构化消息：

```
## 批注反馈

以下是对 docs/superpowers/specs/my-design.md 的批注意见：

- **suggestion**: 建议补充具体的 API 设计
  > 原文: "使用 RESTful API 进行通信"

- **issue**: 缺少错误处理策略
  > 原文: "系统将在发生错误时返回错误信息"

请修复以上问题。
```

结尾根据内容自适应：
- 如果有 **issues**（问题）："请修复以上问题。"
- 如果有 **suggestions**（建议）："请根据以上建议进行修订。"
- 其他情况："请参考以上批注意见。"

## 限制

- 反馈提交最大 5MB 请求体
- 2 分钟空闲超时自动关闭服务器
- 单次只能有一个批注会话