--- name: page-annotator description: AI驱动的网页标注工具，支持高亮元素和添加文字批注。智能防重复、自动滚动、碰撞检测。兼容 GitHub 等严格 CSP 网站。适用场景：(1) 标记网页元素进行讲解 (2) 添加文字批注和注释 (3) 代码审查和设计评审 (4) 教学演示和用户引导 (5) Bug 报告和问题标记 --- ## 使用说明在当前网页上创建可视化标注层，支持高亮和文字批注两种标注方式，所有标注可一键清除。 **兼容性**: 通过浏览器扩展权限绕过 CSP 限制，可在 GitHub、Google 等严格安全策略的网站上正常使用。 **⚠️ 防止重复标注的关键：** 1. **强制使用长文本匹配**：必须使用完整句子（15+ 字符），避免短词匹配多处 - ❌ 错误：`"text": "YAML"` → 匹配 12 处（侧边栏、正文、小标题） - ✅ 正确：`"text": "Beyond the markdown content, you can configure skill behavior using YAML"` → 唯一匹配 2. **添加结构限制**：组合使用 `selector` 限定范围（如 `"selector": "main", "text": "长文本"`） 3. **默认只标注一个**：系统默认 `maxMatches: 1`，只标注第一个匹配项 4. **自动排除干扰区域**：系统自动跳过导航栏、侧边栏、页脚等区域 **💡 长文本匹配的优势：** - 精确定位：长文本在页面中通常是唯一的 - 避免歧义：不会匹配到导航、标题、侧边栏等重复内容 - 提高准确性：直接定位到目标段落或句子 ### 核心功能 1. **高亮元素** - 为指定元素添加高亮效果和标签 2. **文字批注** - 在元素旁添加批注气泡（支持气泡\/便签\/行内三种样式），自动在原文下方添加下划线标识 3. **智能匹配** - 支持 CSS 选择器和文本搜索双重匹配 4. **自动滚动** - 自动滚动到标注位置，避免标注"消失" 5. **碰撞检测** - 自动调整位置避免批注重叠 6. **防遮挡原文** - 批注始终显示在元素旁边，不会遮挡页面原有内容 7. **防重复执行** - 2秒内阻止相同标注重复执行 8. **诊断工具** - 检测和修复标注问题 9. **清除标注** - 一键移除所有标注 ### 脚本列表 | 脚本 | 功能 | 主要参数 | |------|------|----------| | `annotate.js` | 高亮元素并添加标签 | `selector\/text`, `label`, `color` | | `comment.js` | 添加文字批注 | `selector\/text`, `comment`, `position`, `style`, `color` | | `clear.js` | 清除所有标注 | 无 | | `debug.js` | 诊断标注问题 | 无 | ### 使用流程 1. 用户描述需要标注的内容（如"在登录按钮旁添加批注"） 2. **提取目标位置的完整句子或段落**（15+ 字符，确保唯一性） 3. 使用长文本进行精确匹配 4. 调用相应脚本执行标注 5. 如遇问题，使用 debug.js 诊断 **重要提示**：始终使用长文本（完整句子）而不是短词，这是避免重复标注的最有效方法。 ### 调用示例 **高亮元素（使用长文本匹配）：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/annotate.js", "arguments": { "text": "Click the button below to start the installation process", "label": "安装步骤", "color": "yellow" } } ``` **添加文字批注（长文本匹配）：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "text": "Beyond the markdown content, you can configure skill behavior using YAML", "comment": "这里说明了如何使用 YAML 配置", "position": "right", "style": "bubble", "color": "blue" } } ``` **添加文字批注（便签样式）：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "text": "Make sure to backup your data before proceeding with the upgrade", "comment": "⚠️ 升级前务必备份数据", "style": "sticky", "color": "orange" } } ``` **清除标注：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/clear.js", "arguments": {} } ``` **诊断问题：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/debug.js", "arguments": {} } ``` ### 参数说明 ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "text": "用户登录", "comment": "这是登录功能", "position": "right", "color": "blue", "style": "bubble" } } ``` **组合使用选择器和文本：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/annotate.js", "arguments": { "selector": "h1", "text": "欢迎", "label": "标题", "color": "yellow" } } ``` **禁用自动滚动：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "selector": ".footer", "comment": "页脚信息", "autoScroll": false } } ``` **限制匹配数量（避免重复）：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "text": "MCP", "comment": "Model Context Protocol", "maxMatches": 1 } } ``` **标注多个匹配项：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/annotate.js", "arguments": { "text": "重要", "label": "注意", "color": "red", "maxMatches": 5 } } ``` **包括隐藏元素：** ```json { "skill_name": "page-annotator", "script_path": "scripts\/comment.js", "arguments": { "text": "折叠菜单", "comment": "这是隐藏的菜单项", "onlyVisible": false } } ``` ### 参数说明 **通用参数（annotate.js 和 comment.js）：** - `selector` (string, 可选*): CSS 选择器，用于定位元素 - `text` (string, 可选*): 文本内容，用于搜索包含该文本的元素 - `color` (string, 可选): 颜色主题，支持 `yellow`\/`red`\/`blue`\/`green`\/`orange`，默认 `yellow` - `autoScroll` (boolean, 可选): 是否自动滚动到元素位置，默认 `true` - `maxMatches` (number, 可选): 限制标注数量，默认 `1`（只标注第一个匹配项） - `onlyVisible` (boolean, 可选): 是否只标注可见元素，默认 `true`（跳过隐藏元素） *注：`selector` 和 `text` 至少提供一个，推荐使用 `text` 更可靠 **高亮专用（annotate.js）：** - `label` (string, 可选): 标签文字，显示在元素上方 **批注专用（comment.js）：** - `comment` (string, 必需): 批注内容 - `position` (string, 可选): 批注位置，支持 `right`\/`left`\/`top`\/`bottom`，默认 `right` - `style` (string, 可选): 批注样式 - `bubble`（气泡）- 默认，圆角矩形，适合一般说明 - `sticky`（便签）- 方形带图标，适合重要提醒 - `inline`（行内）- 紧凑型，适合简短说明 - **注意**: 所有批注样式都会在原文下方自动添加下划线，清晰标识批注对应的内容 ### 颜色方案 | 颜色 | 用途 | 适用场景 | |------|------|----------| | `yellow` | 一般信息（默认） | 普通说明、提示 | | `red` | 错误、警告 | 问题标记、重要警告 | | `blue` | 信息、说明 | 功能讲解、步骤说明 | | `green` | 成功、推荐 | 正确做法、成功提示 | | `orange` | 注意、待优化 | 需要改进的地方 | ### 选择器建议 **强制使用长文本匹配（推荐）：** 长文本匹配是最可靠的方式，可以避免 99% 的重复标注问题。 ```json \/\/ ✅ 最佳实践：使用完整句子 { "text": "Beyond the markdown content, you can configure skill behavior using YAML frontmatter", "comment": "YAML 配置说明" } \/\/ ✅ 推荐：使用段落开头 { "text": "The installation process is straightforward and takes only a few minutes to complete", "label": "安装说明" } ``` **文本长度建议：** - 最少：15 个字符 - 推荐：30-100 个字符（完整句子） - 最佳：使用在页面中唯一出现的文本 **如何选择文本：** 1. 在页面上找到目标位置 2. 复制该位置的完整句子或段落 3. 使用 Ctrl+F \/ Cmd+F 验证文本唯一性 4. 如果有多个匹配，选择更长的文本 **文本搜索的智能优先级：** 当使用 `text` 参数时，系统会按以下优先级搜索元素： 1. **主内容区标题**（`

` 或 `

` 中的 `

`-`

`） 2. 主内容区文本（`
` 或 `
` 中的段落、列表等） 3. `.content` 区域的标题和文本 4. 页面中的所有标题 5. 其他文本元素自动排除的区域： - 导航栏：`
`, `.navigation`, `.navbar` - 侧边栏：`
`, `.sidebar` - 页眉页脚：`
`, `
`, `.header`, `.footer` 优先级评分机制： - `
` 标签内：权重 10（最优先） - `
` 标签内：权重 8 - `
` 标签内：权重 6 - 其他区域：权重 5 - 导航\/侧边栏\/页脚：权重 1（通常被过滤）这样可以确保标注始终定位到最相关的内容区域。使用 CSS 选择器（不推荐）：只在以下情况使用 CSS 选择器： - 目标元素没有文本内容（如图片、图标） - 需要标注特定的 HTML 结构 ```json \/\/ 可以使用的选择器 { "selector": "#unique-id", "label": "特定元素" } \/\/ 避免使用的选择器 { "selector": "div > div > div > button:nth-child(3)" \/\/ 太复杂，容易失效 } ``` ### 最佳实践 1. 强制使用长文本匹配（最重要） ```json \/\/ ❌ 错误：短词匹配多处 { "text": "YAML" } \/\/ 可能匹配 12+ 处 \/\/ ❌ 错误：短句仍可能重复 { "text": "配置文件" } \/\/ 可能匹配多处 \/\/ ✅ 正确：使用完整句子（15+ 字符） { "text": "Beyond the markdown content, you can configure skill behavior using YAML", "comment": "YAML 配置说明" } \/\/ ✅ 正确：使用唯一的长文本 { "text": "Click the button below to start the installation process and follow the on-screen instructions", "comment": "安装步骤说明" } ``` 2. 提取目标位置的完整句子 - 从页面复制完整的句子或段落 - 确保文本长度 ≥ 15 个字符 - 选择在页面中唯一出现的文本 3. 组合使用结构限制（可选） ```json \/\/ 在主内容区搜索长文本 { "selector": "main", "text": "This section describes the advanced configuration options available", "comment": "高级配置说明" } ``` 4. 避免使用的文本类型 - ❌ 单个词：`"YAML"`, `"配置"`, `"按钮"` - ❌ 常见短语：`"点击这里"`, `"了解更多"`, `"查看详情"` - ❌ 标题文字：通常在导航、侧边栏、正文中重复出现 5. 推荐使用的文本类型 - ✅ 完整句子：包含主语、谓语、宾语的完整表达 - ✅ 段落开头：段落的前 50-100 个字符 - ✅ 唯一描述：页面中只出现一次的描述性文本 6. 验证文本唯一性 - 使用浏览器的查找功能（Ctrl+F \/ Cmd+F） - 搜索你选择的文本 - 确保只有 1 个匹配结果 7. 遇到问题时先诊断 ```json { "script_path": "scripts\/debug.js" } ``` ### 常见问题 Q: 标注位置不准确？ - 确保浏览器缩放为 100% - 等待页面完全加载后再标注 - 使用 `autoScroll: true` 自动滚动到元素 Q: 出现重复的标注？ - 最重要：使用长文本（15+ 字符的完整句子）而不是短词 - 示例对比： - ❌ `"text": "YAML"` → 匹配 12 处 - ✅ `"text": "Beyond the markdown content, you can configure skill behavior using YAML"` → 唯一匹配 - 系统会自动阻止 2 秒内的重复执行 - 默认 `maxMatches: 1` 只标注第一个匹配项 - 使用浏览器查找功能（Ctrl+F）验证文本唯一性 - 使用 `debug.js` 检查重复情况 - 使用 `clear.js` 清除后重新标注 Q: 找不到元素？ - 首先检查文本长度：确保使用 15+ 字符的长文本 - 使用完整句子而不是短词或短语 - 从页面复制完整的文本内容 - 检查返回的 `suggestions` 字段获取建议 - 确认元素是否在 iframe 或 Shadow DOM 中 - 等待页面完全加载后再标注 Q: 批注相互重叠？ - 系统会自动进行碰撞检测和位置调整 - 如果仍然重叠，说明空间不足，考虑清除部分标注 Q: 批注会遮挡原文吗？ - 不会！系统会自动检测批注与原文的重叠 - 批注会自动调整位置，确保始终显示在元素旁边 - 即使空间有限，批注也会尽量避开原文内容 - 批注使用 `pointer-events: none`，鼠标可以穿透批注点击下方内容 Q: 如何只标注主内容区的元素？ ```json \/\/ 方法 1：使用长文本（推荐） { "text": "This is the main content paragraph that appears only once in the article", "comment": "主要内容说明" } \/\/ 方法 2：组合选择器和长文本 { "selector": "main", "text": "Complete sentence from the main content area", "comment": "说明" } ``` Q: 如何避免标注到导航栏的内容？ - 系统默认会自动排除 `
`, `
`, `
`, `
` 等区域 - 使用 `onlyVisible: true`（默认）会跳过隐藏元素 - 组合使用 `selector: "main"` 或 `selector: "article"` 限制范围 ### 高级功能详细文档请参考： - [长文本匹配最佳实践](LONG_TEXT_MATCHING.md) - 必读：如何使用长文本避免重复标注 - [批注功能指南](references\/comment-guide.md) - 批注样式和位置详解 - [选择器指南](references\/selector-guide.md) - CSS 选择器使用说明 - [故障排除](references\/troubleshooting.md) - 常见问题解决方案 - [使用场景](references\/use-cases.md) - 实际应用示例