pi-annotate

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

安装

pi install npm:@jackice/pi-annotate

或从本地路径安装：

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 分钟空闲超时自动关闭服务器
• 单次只能有一个批注会话