Smart Annotator

智能批注器 (Smart Annotator)

把「批一处、改一处」变成「一次性批注 → 一次性批量修改」。两个阶段：A 打开工具批注、B 应用批注。同一对话里通常先 A 后 B。

支持格式：

• 轻量（工具内直接渲染）：Markdown、HTML、纯文本、CSV。
• 文档/视觉（转成可批注视图）：Word .docx、Excel .xlsx/.xls、.pdf、PPT .pptx、图片 .png/.jpg/.gif/.webp/.svg。这些会被转成 HTML 或逐页图片供批注，改写时回写原始文件并保留格式。

阶段 A —— 打开批注工具

何时：用户想开始批注某份内容或文件——刚生成了文稿/页面/文档/表格/幻灯片，说「批注这个」「圈几处再让你改」「用批注工具改这个 docx/pdf/xlsx」。

怎么做：

1. 确定输入：
   • 已是文件（.md/.html/.txt/.csv/.docx/.xlsx/.pdf/.pptx/图片）→ 直接用该文件路径。
   • 是你刚在对话里生成的文本 → 写入临时文件并用正确扩展名（如 /tmp/annot_input.html、.md、.csv）。
2. 运行注入脚本（会按扩展名自动转换：docx→HTML、xlsx→表格、pdf/pptx→逐页图片、图片→内嵌，其余按文本）：

   python scripts/build_annotator.py <文件1> [文件2 ...] --out /mnt/user-data/outputs/annotator.html [--lang zh] [--title "标题"]
   

   • 可一次传多个文件 → 工具里每篇一个标签，各自独立批注，导出时合并成一份批注单。
   • --lang：界面默认英文；用户用中文交流时传 --lang zh（用户也可在界面右上角一键切换）。
   • 若报缺少 Python 库，pip install --break-system-packages mammoth openpyxl pymupdf python-pptx 后重试；pptx 渲染需系统 soffice(LibreOffice)，缺失时脚本会自动回退为「逐页文字视图」。
   • 记住原始文件路径，阶段 B 要用。
3. 用 SendUserFile 交付 /mnt/user-data/outputs/annotator.html；桌面端可再 create_artifact 让它侧栏常驻。
4. 一两句话教用法：选中文字批注、悬停段落点 💬 整段批注、点「▭ 圈选批注」拖框批注图表/图片/幻灯片等视觉区域；批注完点 「⬇︎ 导出批注单 → 拖给 Claude」下载文件，拖回本对话发送（无需复制长文本）。
   • 带脚本的可交互 HTML 会自动进入「⚡交互模式」：页面可点击操作，再用圈选批注该状态。
   • docx/xlsx/pdf/pptx/图片呈现为视图（文字/表格/图片）：表格按单元格、文档按段落、pdf/pptx/图片按圈选批注。
   • Excel/CSV 视图带真实坐标：渲染出 Excel 式行号/列标栏，任一批注都会自动带上单元格地址（如 Sheet1!B3），圈选跨格则汇总为区域（Sheet1!B2:D5）；pdf/pptx 批注自动带真实页码。这些坐标会写进批注单，供阶段 B 精确定位。

交付工具后停下等用户批注，不要替他猜批注内容。

多篇一起批注：用户给了多个文件、或说「这几个一起改」时，一次性全部传给脚本。用户可在标签间切换、边看边批，最后一次导出包含所有文档的批注单。

阶段 B —— 应用批注

何时：用户回传批注结果——拖回 annotation-order-*.md（批注单，含原文视图+批注+指令）、附上 annotation-pack*.json（含 originalFile、annotations、圈选截图），或粘贴含批注结构的文本。

怎么做：

1. 解析出【批注清单】。判断原文是「文本」还是「转换视图」：
   • 批注单/JSON 里带 originalFile（如 report.docx） → 说明是二进制文件的视图。
   • 无 originalFile → 文本类（md/html/txt/csv），直接改文本、返回同格式。
2. 执行修改：
   • 文本类：按批注整体改写，只改涉及处、保持格式有效，输出完整新版并交付。
   • docx/xlsx/pptx/pdf：对原始文件按批注修改并保留原格式——调用对应技能（docx / xlsx / pptx / pdf）。
     • 优先用结构锚点定位：批注的「位置」若是 Sheet1!B3 / 'Q3 销量'!B2:D5 这类真实单元格地址（xlsx、CSV），或 第2页（pdf/pptx），就直接按该坐标定位修改，不要凭表格外观或文字相似度猜。区域地址表示这一整片单元格都在批注范围内。
     • 无锚点时（docx 段落等）再回退到用 quote 引用文本 / snippetHTML 定位。
   • 图片：文本模型改不了像素；把批注整理成明确的修改说明，交给图像生成/编辑工具，或据此重绘。如实告知这一限制。
3. 用 SendUserFile 交付原始格式的新文件（docx 还是 docx、xlsx 还是 xlsx），简述改了哪几处。
   • 多文档批注单：内容按 ===== 文档 i/N ===== / ===== DOCUMENT i/N ===== 分段，并要求按

     <<<FILE: 文件名>>>
     …修改后的完整内容…
     <<<END>>>
     

     逐个输出。请每篇都改、每篇都交付（各自保留原格式），不要只处理第一篇。
4. 逐条核对是否真的都改了。用户在工具里会看到「回执」：逐条比对每条批注是否检出改动。如果用户回来说「第 N 条没改」，或发来 annotation-followup-*.md（工具生成的追加请求，内含当前版本全文 + 仅未生效的批注），就只针对这些批注在当前版本上再改一次。
   • 这一步很重要：模型在指令密集时确实会漏执行靠后的条目，别假设一次就全中。
5. 想在新版上继续批注 → 回到阶段 A 用新文件再开一次。

注意事项

• 界面默认英文，右上角可一键中英切换；发给 AI 的批注单跟随界面语言。用户用中文交流时记得加 --lang zh。
• 回传的批注单/文本不含圈选截图（图片无法随文本传递），但圈选的 snippetHTML 已足够定位；需要「看到」视觉时，请用户把截图或 annotation-pack.json 附进对话。
• 工具单文件、离线、Key 只存内存；「导出批注单 → 拖回对话」是零配置最省事路径，优先引导。
• pdf/pptx 中用 <canvas> 或复杂排版渲染的内容：截图能看到、但回写受对应格式技能能力限制，如实说明。
• 工具内「改动」页支持逐块采纳/拒绝（像代码评审的 per-hunk），用户可能只接受了部分改动——以他最终交付/回传的版本为准。
• 资产：assets/annotator.html（工具，含预加载入口，支持划词/整段/圈选、静态/交互双模式、前后 diff）；scripts/build_annotator.py（按格式转换并注入内容）。