omp packages

@jackice/pi-annotate0.3.2

Visual annotation extension for pi coding agent - annotate context messages and markdown documents

jackice Published 7 days ago MIT ~609 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

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、设计文档）上打开可视化批注界面
  • 自动检测：agent 通过 write/edit 创建或修改匹配 include（默认 docs/superpowers/**/*.md）的文档后，在 run 结束时打开批注界面
  • 批注类型：评论（comment）、建议修改（suggestion）、问题（issue）和表扬（praise）— 各有不同颜色标识
  • 快捷标签：一键预设标签用于常见反馈（需澄清说明、缺少关键细节、需要验证假设等）
  • 浮动工具栏：选中文本后弹出紧凑工具栏，包含评论、删除、快捷标签和赞许操作
  • 内联评论弹窗：点击工具栏上的评论按钮，在选中文本上方/下方添加详细文字反馈
  • 反馈投递：批注以结构化消息发送回 agent
  • 直接批准：无批注时可直接批准文档
  • 主题切换：⌘+Shift+L 切换深色/浅色主题（非 macOS 使用 Ctrl+Shift+L）
  • 自动关闭：提交反馈或批准后窗口自动关闭

工作原理

┌─────────┐     ┌──────────────────────────────────────┐     ┌─────────┐
│  Agent  │     │     Glimpse / Browser Annotation UI   │     │  Agent  │
│ 写文档   ├────►│                                      ├────►│ 接收反馈  │
│         │     │  选中文本 → 添加批注 → 发送反馈        │     │         │
└─────────┘     │         ↑                             │     └─────────┘
                │         └── write/edit 触发 ─────────┤
                └──────────────────────────────────────┘

生命周期：

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

Workflow 文档审阅

批准、反馈和退出请求必须携带当前会话 token 并来自同源页面。文档加载失败时禁止提交决议。关闭 workflow 审阅会结束该请求；批准成功后由 workflow 唤醒主代理一次。测试使用 npm test（Node.js）。

当 workflow-mode 在同一 Pi session 中加载时，它可以用此界面审阅绑定版本的 spec、plan、提纲或成稿。workflow 会先记录并校验决议，再让界面报告成功。批准 workflow plan 只授权实施该 plan 及其绑定的 spec 版本。普通 /annotate、/annotate-last 和自动批注仍独立工作，不会授予 workflow 实施批准。

使用方法

扩展提供两个斜杠命令和一个基于 write/edit 的自动批注钩子：

/annotate-last

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

/annotate-last

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

/annotate <file>

批注指定的 markdown 文件：

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

支持：

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

自动检测

扩展监听 write 与 edit 工具调用。当 agent 写入或修改匹配 include 的 markdown 文件后，会在 agent run 完全结束时（agent_settled）打开批注界面；仅读取文档或在回复中提及路径不会触发。自动打开不阻塞会话，反馈以 follow-up 消息回传给 agent。

  • 同一文件在内容未变化时只打开一次；关闭窗口后本会话不再自动打开该文件。
  • 默认只打开新建文件；设置 autoOpen 为 "write" 可包含修改，设为 "off" 关闭自动打开。

配置

pi-annotate 使用自己的配置文件（pi 的 settings.json schema 没有扩展自定义段）：

  1. 全局：~/.pi/agent/annotate.json
  2. 项目：<项目>/.pi/annotate.json（覆盖全局）
  3. 环境变量：PI_ANNOTATE_AUTO=off|create|write
{
  "autoOpen": "create",
  "include": ["docs/superpowers/**/*.md"],
  "onWindowClose": "mute"
}
字段 取值 默认值 说明
autoOpen "off" | "create" | "write" "create" 关闭自动打开、仅新建文件、新建与修改文件
include string[] ["docs/superpowers/**/*.md"] 相对项目根目录的 glob，支持 ** 与 *
onWindowClose "mute" | "ignore" "mute" 关窗后本会话静音该文件

批注界面

浮动工具栏

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

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

快捷标签

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

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

批注面板

所有批注显示在右侧栏中。每条批注包含：

  • 类型徽章（评论/建议修改/问题/表扬），带颜色编码
  • 批注文字
  • 原文预览
  • 时间戳
  • 编辑（✏️）和删除（🗑️）按钮

快捷键

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

文件结构

pi-annotate/
├── index.ts              # 扩展入口、命令、Glimpse 集成
├── auto-annotate.ts      # 自动打开触发、配置、去重
├── 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 分钟空闲超时自动关闭服务器
  • 单次只能有一个批注会话