# Smart Annotator > 对 AI 产出的内容做批量批注，再让 AI 一次性批量修改。支持 Markdown / HTML / 纯文本 / CSV，以及 Word(docx) / Excel(xlsx) / PDF / PPT(pptx) / 图片——后几类会转成可批注视图，改写时回写原始文件并保留格式。当用户想对一份生成的文稿、页面、文档、表格、幻灯片或图片标注多处问题后统一修改，或说到「批注 / 圈选批注 / 批量改这个文件 / 批注后让你改 / annotate」时使用。 - Skill: `yx2557/smart-annotator` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add yx2557/smart-annotator` - Raw SKILL.md: https://api.skillmd.com/api/skills/yx2557/smart-annotator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: yx2557 (https://skillmd.com/u/yx2557) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yx2557/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 =====` 分段，并要求按 ``` <<>> …修改后的完整内容… <<>> ``` 逐个输出。请**每篇都改、每篇都交付**（各自保留原格式），不要只处理第一篇。 4. **逐条核对是否真的都改了**。用户在工具里会看到「回执」：逐条比对每条批注是否检出改动。如果用户回来说「第 N 条没改」，或发来 `annotation-followup-*.md`（工具生成的追加请求，内含**当前版本全文 + 仅未生效的批注**），就只针对这些批注在当前版本上再改一次。 - 这一步很重要：模型在指令密集时确实会漏执行靠后的条目，别假设一次就全中。 5. 想在新版上继续批注 → 回到阶段 A 用新文件再开一次。 ## 注意事项 - 界面**默认英文**，右上角可一键中英切换；发给 AI 的批注单**跟随界面语言**。用户用中文交流时记得加 `--lang zh`。 - 回传的批注单/文本不含圈选截图（图片无法随文本传递），但圈选的 `snippetHTML` 已足够定位；需要「看到」视觉时，请用户把截图或 `annotation-pack.json` 附进对话。 - 工具单文件、离线、Key 只存内存；「导出批注单 → 拖回对话」是零配置最省事路径，优先引导。 - pdf/pptx 中用 `` 或复杂排版渲染的内容：截图能看到、但回写受对应格式技能能力限制，如实说明。 - 工具内「改动」页支持**逐块采纳/拒绝**（像代码评审的 per-hunk），用户可能只接受了部分改动——以他最终交付/回传的版本为准。 - 资产：`assets/annotator.html`（工具，含预加载入口，支持划词/整段/圈选、静态/交互双模式、前后 diff）；`scripts/build_annotator.py`（按格式转换并注入内容）。