--- 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. **其他文本元素** **自动排除的区域：** - 导航栏：`