Wahajolla/annotate

annotate 是做什么的？

用户点击页面上的某个元素，写下一段笔记，Claude 就能获取该笔记及其选择器、附近文本、边界框和 URL，从而在代码中找到该元素并进行修复。

基于 Agentation 构建：agentation 工具栏（React 18+，仅桌面端）和 agentation-mcp 笔记服务器（基于 SQLite 的 HTTP API，可选 MCP 工具）。

先选择模式

如果不明显，请先询问用户：

• 本地模式：仅用户和 Claude 参与，在本机上运行。笔记服务器运行在 localhost:4747。无需部署任何内容。这是默认模式。
• 共享模式：同事们在托管站点上添加注释，所有人都能看到彼此的笔记。需要一个部署在公网 HTTPS 主机上的笔记服务器。参见 references/shared.md。该页面描述了架构和要求；由用户选择托管方式。

工具栏的放置方式

根据页面类型选择。两种模式下选项相同，只有 endpoint 和 session 不同。

1. 在用户的 React 应用中。 npm i -D agentation，然后在应用旁边渲染它，并通过条件限制使其永远不会进入生产环境：

   {import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
   

   针对哈希路由添加 useHashLocation，并添加 appName 来标记反馈来源。
2. 在用户控制的任意 HTML 页面中（无论是否使用 React）。 添加一个脚本标签。加载器 会在其自己的容器和 React 根节点中挂载工具栏，因此不会影响宿主页面：

   <script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>
   

   查询参数：endpoint、session、app、hash=1。或者，在脚本加载之前设置 window.ANNOTATOR_CONFIG = {endpoint, session, app, hash}。
3. 在不修改任何代码的情况下，用于任意网站。 使用书签脚本。给用户以下这行代码，将其保存为书签；点击即可切换工具栏的显示与隐藏：

   javascript:(()=>{const s=document.createElement('script');s.type='module';s.src='https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747&t='+Date.now();document.head.appendChild(s)})()
   

   需要告知用户的限制：
   • 具有严格内容安全策略（CSP）的网站（如 GitHub、许多银行和大型应用）会阻止注入的脚本，因此工具栏在这些网站上无法使用。
   • 在公网 https:// 站点上访问 localhost 时，浏览器可能会请求本地网络访问权限：请允许。
   • 笔记服务器必须允许该站点的来源（参见下面的 CORS）。
   • 笔记与站点 URL 绑定，工具栏的本地草稿保存在该站点的 localStorage 中。
4. Chrome 扩展。 这是为任意网站添加注释最稳健的方式。通过单击或 Alt+Shift+A 进行切换，适用于严格 CSP 的网站（如 GitHub、Notion 等），并且无需配置 CORS：请求通过扩展程序转发。安装：从 https://github.com/Wahajolla/annotator-skill/releases/latest 下载 annotator-extension.zip，然后进入 chrome://extensions → 开发者模式 → 加载已解压的扩展。笔记服务器在扩展选项中设置，默认为 http://localhost:4747；共享模式请使用托管 URL 加会话 ID。实时同步每 5 秒轮询一次。如果笔记服务器无法访问，扩展会显示一张“笔记服务器离线”卡片，其中包含启动命令，并且 #annotator-ext-root 会获得 data-annotator-server="offline" 属性（当服务器响应后变为 "online"）：如果你在驱动浏览器，请先检查此属性，再告知用户笔记已保存。在选项中，“通过 GitHub 登录”会用用户的登录名签署每条笔记，这样同事的笔记就能显示是谁留下的。

如果没有 endpoint，工具栏将仅运行纯复制模式。笔记保存在浏览器中，用户按下“复制”按钮后将 markdown 粘贴到聊天中。这无需服务器，因此当用户只想一次性使用时使用此模式。

本地模式

1. 运行笔记服务器。 选择一种方式：

   • MCP（反复使用的最佳选择）。 获得用户同意后：claude mcp add agentation -- npx -y agentation-mcp server。Claude Code 随后在每个会话中启动它，重启后会看到 agentation_* 工具：get_all_pending、resolve、reply 和 watch_annotations（用于免提循环）。
   • 纯 HTTP（无需重启）。 以后台命令运行 npx -y agentation-mcp server，然后通过 HTTP 读取笔记（参见下文）。

   使用 curl http://localhost:4747/health 检查，应返回 {"status":"ok"}。

2. CORS。 默认只允许开发源（localhost、*.localhost、127.0.0.1、私有 IP、.local、.test、.internal）。对于在公网站点上使用书签脚本的情况，请以 AGENTATION_CORS_ORIGINS=https://that-site.com 启动服务器（精确来源，逗号分隔）。* 也可以，但它允许任何打开的标签页写入笔记，因此建议使用精确来源。

3. 使用上述选项之一将工具栏放到页面上，并设置 endpoint=http://localhost:4747。

4. 验证。 通过工具栏添加一条测试笔记，检查 curl localhost:4747/pending 是否显示该笔记，然后删除它。

笔记持久化存储在 ~/.agentation/store.db 文件中。

读取和处理笔记（两种模式通用）

• MCP：agentation_get_all_pending，然后修复代码，再使用简短的摘要调用 agentation_resolve。
• HTTP：GET /pending（所有未关闭的笔记），GET /sessions，GET /sessions/:id。修复一条笔记后，发送 PATCH /annotations/:id 并设置 {"status":"resolved"}。
• 谁写的： 通过 Chrome 扩展并使用 GitHub 登录的笔记会携带 authorId: "github:<login>"，并且默认注释以 @<login>: 开头。没有 authorId 的笔记是匿名的（通过其他方式加载工具栏）。当你汇报时，请提及作者。
• 有用的字段包括 comment、url、element、elementPath、fullPath、nearbyText、selectedText、boundingBox 和 reactComponents（仅限开发构建）。
• 在删除任何内容之前，让用户做决定。

在截图中显示笔记

Agentation 只在悬停标记时显示笔记文本。要一次性显示所有笔记，请使用笔记层：每条笔记显示一个轮廓、一个编号和一张包含完整文本的卡片。绘制完成后，<html> 会获得 data-annotator-notes="<count>" 属性。

• 用户，在 Chrome 中： 在扩展中按 Alt+Shift+N（或右键单击图标 → 显示此页面上的所有笔记）。
• 你，在你自己驱动的页面上（Playwright、Chrome DevTools MCP 等）：设置你自己的笔记并加载图层，然后等待属性出现并截图：

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "太长了。改为“简单定价”", author: "claude" },
    { selector: "#cta", comment: "使用品牌蓝色" },
  ]
  const s = document.createElement("script"); s.type = "module"
  s.src = "https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/notes.js?t=" + Date.now()
  document.head.appendChild(s)
  

  每条笔记接受 selector（或页面坐标中的 boundingBox: {x, y, width, height}）、comment 和可选的 author。未匹配到任何元素的选择器会被跳过，并在控制台中显示警告，因此请检查计数是否匹配。除 ANNOTATOR_NOTES 外，还可以传递 ?endpoint=http://localhost:4747 来显示服务器上该页面的笔记；添加 &all=1 可包含已解决的笔记。使用新的 t 再次加载该脚本会隐藏图层。
• 严格 CSP 的网站（GitHub 等）会阻止该脚本。在 Playwright 中，使用 bypassCSP: true 创建上下文；否则请使用扩展。
• 要使你的笔记成为真实笔记（用户在工具栏中也能看到，并且可以解决它们）：先 POST /sessions 并设置 {"url": "<页面 url>"}，然后 POST /sessions/:id/annotations，并包含 comment、element、elementPath（CSS 选择器）、url、boundingBox 和 x/y（页面坐标）。然后通过 ?endpoint=… 显示它们。请先征得用户同意：这些笔记将成为共享笔记。

注意事项

• 工具栏仅支持桌面端。
• 笔记服务器没有认证，只有 CORS。任何浏览器来源被允许的人都可以写入和删除笔记。
• useHashLocation 按 #route 保持笔记。稍后启用它不会移动现有笔记。
• Agentation 使用 PolyForm Shield 许可证，适用于内部反馈场景。