# visual-annotator

**Repository Path**: binghe021/visual-annotator

## Basic Information

- **Project Name**: visual-annotator
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Visual Annotator（可视化标注工具）

一款浏览器扩展，用于在任意网页上标注元素并复制结构化 Markdown——专为 AI 编程助手打造。

标注元素、截取截图、捕获浏览器控制台日志，然后把一切粘贴到你选择的 AI 助手中。输出针对 AI 消费做了优化：包含选择器、边界框、计算样式以及截图文件路径的结构化 Markdown。

**一键捕获控制台** —— 所有 `console.log`、`console.warn`、`console.error` 以及未处理的异常都会在后台被记录。点击工具栏中的终端图标，即可将它们作为格式化的 Markdown 复制。图标上的红点会提醒你有错误发生。

### 配合使用

**Markdown + 截图** —— 有本地文件系统访问权限的 AI 助手可以直接读取保存的截图文件：

| 助手 | 用法 |
|------|------|
| **[Claude Code CLI](https://code.claude.com/docs/en/quickstart)** | 将 Markdown + 截图路径粘贴到 CLI 提示中 |
| **[Claude Code VS Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)** | 粘贴到 Claude Code 聊天面板 |
| **[Cursor](https://cursor.com)** | 粘贴到聊天或 Cmd+K 行内编辑 |
| **[Windsurf](https://windsurf.com)** | 粘贴到 Cascade 聊天 |
| **[Cline](https://cline.bot)** | 粘贴到 VS Code 的聊天面板 |
| **[Aider](https://github.com/Aider-AI/aider)** | 粘贴到 CLI 提示中 |
| **[GitHub Copilot](https://github.com/features/copilot)** | 粘贴到 VS Code 的 Copilot 聊天 |
| **[Pi](https://github.com/badlogic/pi-mono)** | 粘贴到 CLI 提示中 |
| **[OpenCode](https://github.com/anomalyco/opencode)** | 粘贴到 CLI 提示中 |
| **[Gemini CLI](https://geminicli.com)** | 粘贴到 CLI 提示中 |
| **[Google Antigravity](https://antigravity.google)** | 粘贴到对话中 |

**仅 Markdown** —— 没有文件系统访问权限的网页端 AI 助手可以获取完整的结构化 Markdown（选择器、样式、边界框），但无法加载截图文件：

| 助手 | 用法 |
|------|------|
| **ChatGPT** | 粘贴到对话中 |
| **[Gemini](https://gemini.google.com)** | 粘贴到对话中 |
| 其他任何助手 | 只要能读 Markdown 就能用 |

无后端。无框架依赖。适用于所有网站。

## 演示

https://github.com/user-attachments/assets/c954c6cb-d978-4980-a194-51a8702903c3

## 安装

### Mac

1. 下载或克隆此仓库
2. 打开 Chrome，进入 `chrome://extensions`
3. 开启**开发者模式**（右上角开关）
4. 点击**加载已解压的扩展程序**
5. 在文件对话框中，导航到下载的 `visual-annotator` 文件夹并选中
6. 扩展图标出现在工具栏——点击拼图图标，将 **Visual Annotator** 固定以便快速访问

### Windows

1. 下载或克隆此仓库
2. 打开 Chrome，在地址栏输入 `chrome://extensions`
3. 开启**开发者模式**（右上角开关）
4. 点击**加载已解压的扩展程序**
5. 浏览到下载的 `visual-annotator` 文件夹并选中
6. 扩展图标出现在工具栏——点击拼图图标，将 **Visual Annotator** 固定以便快速访问

### 更新

拉取新代码后更新：

1. 进入 `chrome://extensions`
2. 找到 **Visual Annotator**，点击重新加载图标（圆形箭头）

## 使用方法

1. **切换工具栏** —— 点击扩展图标或按 `Cmd+Shift+.`（Mac）/ `Ctrl+Shift+.`（Windows/Linux）
2. **标注** —— 点击钢笔图标（或按 `A`），然后点击页面上的任意元素
3. **评论** —— 可选地添加描述，选择意图和严重程度
4. **意图** —— 选择修复、变更、提问、通过或**复制**（获取元素的 HTML DOM）
5. **截图** —— 在标注弹窗中直接截取元素的裁剪截图
6. **复制** —— 点击复制图标，将所有标注作为结构化 Markdown 复制到剪贴板
7. **控制台** —— 点击终端图标，将捕获的控制台日志作为 Markdown 复制
8. **保存截图** —— 点击下载图标，批量将所有截图保存到本地
9. **导出分享包** —— 点击归档图标，导出含 Markdown + 截图的 ZIP 压缩包
10. **粘贴** —— 粘贴到任意 AI 助手的提示中

## 扩展弹窗

点击扩展图标打开弹窗，包含以下选项：

| 选项 | 说明 |
|------|------|
| 显示/隐藏工具栏 | 在当前页面切换标注工具栏 |
| 始终开启 | 在每个页面自动显示工具栏 |
| 自动复制 | 每次标注后自动将 Markdown 复制到剪贴板 |
| 自动截图 | 每次标注时自动截取截图 |

## 工具栏按钮

| 按钮 | 快捷键 | 说明 |
|------|--------|------|
| 标注 | `A` | 切换元素选择模式 |
| 复制 | — | 将所有标注作为 Markdown 复制 |
| 控制台 | — | 将浏览器控制台日志作为 Markdown 复制 |
| 保存截图 | — | 批量保存所有截图到本地 |
| 导出分享包 | — | 导出含 Markdown + 截图的 ZIP 压缩包 |
| 清空 | `X` | 移除所有标注 |
| 最小化 | — | 将工具栏折叠为一个小悬浮按钮 |

## 元素选择器

标注模式激活时：

- **悬停**元素可看到高亮和提示框（标签、类名、尺寸）
- **Alt/Option + 滚动**可在父元素间循环切换
- **点击**选择元素并打开评论弹窗
- **点击编号标记**编辑已有标注
- **Escape**退出标注模式

## 复制意图

**复制**意图让你获取页面上任意元素的完整 HTML DOM。当你想让 AI 助手理解精确的标记结构时非常有用——例如复刻组件、重构 HTML 或调试渲染问题。

选择"复制"作为意图时，会出现一个复选框：**包含元素的完整 HTML DOM**（默认勾选）。所选元素的完整 `outerHTML` 将作为代码块包含在 Markdown 输出中。

```markdown
## 1. `div.card` [copy · important]

- **Comment:** Replicate this card component
- **HTML:**
```html
<div class="card">
  <h2>Title</h2>
  <p>Content with <a href="#">links</a></p>
</div>
```

---
```

## Markdown 输出

复制按钮生成的 Markdown 如下：

```markdown
# Visual Feedback — My App
**URL:** https://myapp.com/dashboard
**Viewport:** 1440x900
**Date:** 2025-01-15T10:30:00.000Z

---

## 1. `button.btn-primary` [fix · important]

- **Comment:** The button should use the design system blue (#3B82F6), not green.
- **URL:** https://myapp.com/dashboard
- **Element:** `<button class="btn-primary">`
- **Selector:** `main > div > button.btn-primary`
- **Text:** "Submit Form"
- **Bounding Box:** 120x40 at (350, 680)
- **Styles:** display: flex, backgroundColor: rgb(34, 197, 94)
- **Screenshot:** ![screenshot-1](/Users/.../Downloads/visual-annotator/myapp-com-dashboard-1743564000000.png)

---
```

## 控制台输出

控制台按钮生成的 Markdown 如下：

```markdown
# Console Output — My App
**URL:** https://myapp.com/dashboard
**Messages:** 12 (2 errors, 1 warnings)

---

[ERROR] 10:30:15.123
Uncaught TypeError: Cannot read property 'foo' of undefined

[WARN] 10:30:16.456
Deprecation warning: componentWillMount has been renamed

[LOG] 10:30:17.789
App initialized
```

## 键盘快捷键

所有快捷键仅在工具栏可见且无文本输入框获得焦点时生效。

| 快捷键 | 操作 |
|--------|------|
| `Cmd/Ctrl+Shift+.` | 打开工具栏 + 开始标注 |
| `A` | 切换标注模式 |
| `X` | 清空所有标注 |
| `Escape` | 退出标注模式或关闭弹窗 |

> **提示：** 默认快捷键仅在 Chrome 获得焦点时生效。要使其全局生效（在任何应用中都能用），进入 `chrome://extensions/shortcuts`，找到 **Visual Annotator**，将范围从"在 Chrome 中"改为"全局"。

## 截图

截图以 PNG 文件保存到下载文件夹的 `visual-annotator/` 目录下：

- 按网页标题分组：`visual-annotator/{网页标题}/images/`
- 文件名使用可读时间戳：`screenshot-2026-09-28_132830_225.png`

## 导出分享包

点击「导出分享包」按钮，可将所有标注和截图打包为 ZIP 压缩包：

- ZIP 内含一层与 ZIP 同名的文件夹：`{网页标题}_{时间戳}/report_{时间戳}.md` + `images/`
- Markdown 中截图使用相对路径 `images/xxx.png`，解压后可直接被 AI 助手读取
- **高效协作**：双击打开 ZIP，直接把同名文件夹拖到项目的 `doc/` 目录即可，无需手动解压
- 同时截图会备份到本地 `visual-annotator/{网页标题}/images/` 目录
- 截图数量 ≥ 10 时，「保存截图」按钮会显示红色提醒

## 隐私

- 所有数据保留在浏览器中——无网络请求、无追踪、无分析
- 截图通过 Chrome 的 `captureVisibleTab` API 在本地截取，保存到下载文件夹
- 控制台日志在页面内捕获——不会发送到任何服务器

## 开发

```bash
# 修改 content.js、background.js、popup.js 或 manifest.json
# 然后在 chrome://extensions 中重新加载扩展
```

无需构建步骤。扩展是纯 JavaScript。

## 团队协作工作流

本插件的核心价值在于**用户反馈问题 → 开发者修复**的协作闭环，而非仅供个人使用。

### 典型流程

1. **用户侧**：在网页上标注问题、截图，点击「导出分享包」生成 ZIP
2. **用户侧**：将 ZIP 包发送给开发人员
3. **开发侧**：在项目中建立 `doc/` 文件夹，专门接收用户发来的 ZIP 包
4. **开发侧**：双击打开 ZIP，直接将里面带时间戳的同名文件夹拖入 `doc/` 目录（无需解压）
5. **开发侧**：在 AI 助手中引用该文件夹，附上一段通用提示词，例如：

   > 此文件夹为用户反馈的问题，包含 Markdown 说明与对应截图，请据此进行修复。

6. **开发侧**：AI 助手读取 `report_{时间戳}.md` 和 `images/` 截图，理解问题并给出修复方案

### 设计理念

- **一次反馈 = 一个文件夹**：一个 ZIP 解压后就是一个带时间戳的独立文件夹，可包含多条批注和多张截图，完整表达用户的一次反馈
- **相对路径图片**：Markdown 中的截图使用 `images/xxx.png` 相对路径，解压后即可直接被 AI 助手读取，不依赖任何人的本地绝对路径
- **可追溯**：文件夹名带时间戳，多次反馈互不覆盖，便于追溯问题演变

相比原作者"复制 Markdown 文本（含本地绝对路径图片）"的模式，本方案更适合团队协作——用户无需关心技术细节，只需导出并发送 ZIP；开发者解压后即可让 AI 直接消费。格局更大，协作更顺畅。

## 许可证

MIT