QQ群“ai-proofreader 校对插件”：1055031650
一个用于文档和图书校对、基于大语言模型服务的VS Code扩展，支持选中文本直接校对和长文档切分后批量校对两种工作流，并集成了一些跟校对相关的辅助功能。这里是代码库。本扩展与相应的Python校对工具库的功能大致相同。
另外，你也可以设置自己的提示词，用于其他文本处理场景，比如翻译、注释、编写练习题等。
A VS Code extension for document and book proofreading based on LLM services, supporting two workflows: proofreading selected text directly and proofreading long documents after segmentation. Here is the code repository. This extension has roughly the same functions as the corresponding Python proofreading tool library.
Additionally, you can also set your own prompts for other text processing scenarios, such as translation, annotation, creating exercises, and more.
本文档仅以Windows系统为例
- 安装VS Code，用VSCode打开一个空文件夹，通过VS Code界面左侧的扩展按钮打开扩展管理窗口（Ctrl+Shift+X）
- 搜索AI Proofreader，点击安装按钮
install安装 - 到大语言模型服务平台（默认为Deepseek开放平台），通过注册、实名认证、充值、生成API秘钥等操作，获得有效的秘钥，复制秘钥
- 回到AI Proofreader扩展界面，后点击设置按钮⚙️，选中弹出菜单中的设置项Settings，把秘钥粘贴到对应平台的API秘钥框中
- Ctrl+N新建文档，后缀设为
.md（markdown文档），把你需要校对的文字粘贴到这里，选中其中的一段文字 - 在所选文字上打开右键菜单，使用其中的
AI proofreader: proofread selection项校对选中文本 - 弹出选项对话框时全部回车，即使用默认值
- 最后会自动展示校对前后的差异，效果如下，深红表示原文变动，深绿表示结果变动：
- 打开markdown文档，在每一个段落后添加一个空行（一个或多个空行是md的段落标记），打开右键菜单，使用
AI proofreader: split file选项，选择切分模式（默认按长度），把当前文档切分为JSON文档，结果会呈现在面板中 - 通过结果面板中的“校对JSON文件”按钮，批量校对切分好的片段
- 通过结果面板中的“比较前后差异”按钮，可以看到和上文相同的校对结果
打开markdown文件（或选中其中一段文字），或上述切分得到JSON文件，这时可以使用右键菜单访问与文本类型相关的命令，如切分或校对。
本扩展的所有功能，则可以通过命令面板（Ctrl+Shift+P）查找、访问：
目前作者端稿件多为docx类。排版端可能导出活文字PDF、死文字PDF（文字转曲转光栅，方正书版常见）、方正书版大样文件（常用于过黑马、方正审校）、纯文本（text，多数排版软件能导出）等。
本扩展默认支持Markdown文档，另支持text、ConTeXt、TeX、LaTeX（对后三者的支持没有经过充分测试），其他文档需要先转换为Markdown。此类转换工具很多，本扩展集成了两种。
- 文本文件只需要把后缀（比如纯文本的
.txt）改成.md即可 - docx文档（Word、WPS的通常格式），可以通过命令面板（Ctrl+Shift+P），使用convert docx to Markdown命令转换后进行校。本功能依赖多功能文档格式转换工具Pandoc，需要预先正确安装。安装后可能需要重启才能生效。
- 活文字PDF文档，可以通过命令面板，使用convert PDF to Markdown命令转换后进行校对。本功能依赖Xpdf command line tools中的
pdftotext.exe程序，需手动安装（在“系统变量”的Path中添加其所在路径），交流群备用bat辅助安装程序。安装后可能需要重启才能生效。- 所得文本如果没有使用空行分段，无法切分，可以使用整理段落（format paragraphs）命令中的“段末加空行”选项加以处理。
- Markdown中的段内断行是合法的，即使句子被断开，对大模型的影响也不大。当然，也可以用上述命令中的“删除段内分行”选项处理后再校对。
- 死文字PDF，需要通过OCR处理成活文字PDF、docx、text、Markdown等后进一步处理。QQ交流群中上传了一个OCR命令行工具rapiddoc.exe。加密码限制提取文字的活文字PDF，也如此处理，或尝试用SumatraPDF打开后复制文字。
- 方正书版大样文档，如果有方正智能审校工具，用它处理后即为活文字PDF（没有图），再进一步处理。另外，方正书版本身有一些间接导出活文字PDF的办法，但有各种问题，常常比不上用OCR工具处理。
文档转换后还有一些整理技巧，不过对于使用本扩展进行校对而言，进一步的整理工作通常不是必须的。常见的例外情形是，你希望按篇、章、节、标题等结构来切分、校对，以便保持语境连贯，那么你需要学习更多整理技巧，或者使用其他工具，以便得到有标题的Markdown文档。
过多的无效字符影响输出速度，如长串的表格分割线-、空格、链接等，可以通过查找替换、Ctrl+Shift+L选中所有相同项目等办法简化、删除。方正系排版软件可能使用半角标点，校对后通常会被改成全角，你也可以使用相同的方法加以替换，避免干扰。请参考上述讲整理技巧的文章。
!!! caution 批量替换有风险 批量替换的结果可能超出你的预期，即使你不准备原样使用处理后的文本，也有掩盖错误的风险。补强措施是：（一）备份文件。（二）先查找全部，复制到一个新文档中确认无误，然后再进行替换。（三）如果替换逻辑较为复杂，替换后还要比较文件（后文会提到），从头到尾确认所有更改。
我的经验，在一般语言文字和知识校对场景中，大语言模型一次输出六百到八百字会有比较好的效果。因此，一本十来万字的书稿需要切分成三百多段，然后交给大模型校对。
而校对前后一致性，比如多个人名、正文与注释、前后表述的一致性，则需要完整的语境，这时最好按章节切分、校对。
打开markdown文件，在编辑器窗口中打开右键菜单，可以看到切分选项 AI proofreader: split file
或通过命令面板查找更具体的选项：
- 按长度切分 (Split File by Length)，可输入目标切分长度（字符数）。
- 按标题切分 (Split File by Title)，可输入标题级别（如：1,2），适合有标题且题下正文长度合适（建议不要超过1500）的文档。
- 按标题和长度切分 (Split File by Title and Length)，适合有标题，但题下正文过长的情况。可配置标题级别、阈值（过大则切分）、切分长度和最小长度（过小则合并）。
- 按长度切分，以标题范围为上下文 (Split File with Title Based Context)，会给每一个片段配上所在标题范围的正文作为上下文，适合对上下文语境要求高的情景。可输入切分长度、题级级别。
!!! caution 费用警告 这样有可能极大地增加token数，增加输入服务费用——尽管在Deepseek等平台中，重复提交的上下文会记为“缓存命中”，并降低费率。注意查看切分后的JSON文档的字符数，以权衡利弊。
- 按长度切分，扩展前后段落为上下文 (Split File with Paragraph Based Context)，即在片段基础上添加前后段落，用作上下文。适合关注局部语境一致性的情形。可输入切分长度、前文段落数和后文段落数。
!!! caution 费用警告 这样可能较大地增加token数，增加输入服务费用。这样生成的上下文是变动的，因此无法享受“缓存命中”的低费率。注意查看切分后的JSON文档的字符数，以权衡利弊。
切分后都会生成同名的 .json（用于校对） 和 .json.md（可查看切分情况）两个结果文件。
还会生成日志文件（.log），记录切分统计信息，并摘要呈现在结果面板中；如有过长（如超过1500字符）片段时，可以手动加空行分段，然后再次切分。
结果面板有按钮提示用户选择查看结果的方式：比较前后差异（用分割线表示切分位置）、查看JSON结果或查看日志文件；还有一个校对JSON文件的按钮（面板失效后还可以打开JSON后用右键菜单开始校对）。
!!! note 切分文档依赖两种标记
本扩展默认用户需要校对的文档为markdown格式，文档切分依赖markdown文档中的两种标记：（1）空行。在markdown中，一个或多个空行表示分段，没有空行的断行在渲染时被忽略，即合并为一段。至少要有合适的空行，否则无法切分。（2）各级标题。如## 开头的是二级标题。
校对Markdown文档中选中的片段：
- 打开Markdown文档（其他纯文本文档可改为.md后缀，即为Markdown文档）
- 选中要校对的段落，不宜过长
- 从右键菜单、命令面板（Ctrl+Shift+P）中选择 Proofread Selection
- 可选择上下文范围、参考文件和温度。加入上下文是为大语言模型提供语境，以便参考，并保持一致性。参考文件可以是相关的词条、更权威的文献等。模型温度较低时，随机性、创造性、稳定性较低；反之则随机性、创造性、不稳定性变高。可以参考模型文档进行测试。使用不同温度多遍校对，或许可以覆盖不同的问题，值得尝试。
- 最后会自动展示校对前后的差异；并生成日志，以便再次查看结果
校对切分好的JSON文档：
- 打开已切分的 JSON 文件
- 通过右键惨带或命令面板选择Proofread File
- 显示当前配置请你确认。配置说明见上文。
- 在结果面板中有进度、结果等信息。可中途取消校对。下次接着校对，会根据校对结果
文档.proofread.json文件中的记录，跳过已经完成的部分；如果切分结果文档.json与校对结果文档.proofread.json条目数不一致，则会提示你手动对齐，或删除结果文档，从头重新校对。 - 最后会提示你查看结果：JSON结果、前后差异、日志文件，以及生成差异文件（类似带修改标记的Word文档）。
- 如有未完成的条目，可重新校对，重新校对时只处理未完成的条目
在当前markdown或json界面，使用右键菜单diff it with another file，如果当前是markdown则有两种模式：
- 调用vscode内置的diff editor比较。校对面板“前后差异”按钮的功能与此相同。对于长文本，diff editor有段落无法对齐的问题。此时，可以通过加空行或删除空行来帮助对齐。
- 用jsdiff生成HTML形式的比较结果文件，类似带修改标记的Word文档。本模式还支持JSON文件，自动拼接JSON一级元素或
target字段内容进行比较，支持每次比较的片段数量（默认0表示所有片段），生成多个有序的差异文件，避免过长文本无法渲染的问题；校对面板“生成差异文件”按钮的功能与此相同。
跟人工校对一样，要想提交校对质量，大语言模型也需要了解上下文语境，还需要工具书、参考资料等。
本扩展每次调用大语言模型时能提交三种文本：要处理的目标文本（target，必须）、参考资料（reference，可选）、上下文（context，可选）。比如以一篇文章中的一部分作为target，那么整篇就可以作为context，而在处理中有参考价值的资料，如相关词条，就可以作为reference。
假设你校对一本书，切分后得到包含300个target的JSON文件。那么可以准备相同数量、一一对应的上下文和参考文献，切分成包含相同数量target的JSON文件。然后使用合并命令，将上下文文本中的target作为context合并，将参考文本中的target作为reference合并。
合并 JSON 文件 (Merge Two Files)：
- 打开已切分的要校对的 JSON 文件
- 打开右键菜单，选择
AI proofreader: Merge Two Files（或通过命令面板）命令 - 选择要合并的文件
- 确定要处理的字段和资料来源字段，以及更新（覆盖）模式或拼接模式。比如你想把试题及其答案合并后校对，那么可用拼接模式，拼接到同一个target中。
组织校对语境是一个看起来有些麻烦，但非常有效的工作。比如校对练习册，有必要把练习和答案拼成语境（拼在一个target中更能节省费用）。而对一首古诗的解释如果不可靠，可以用一篇可靠的作为reference。包含人物的内容，则可以用词典中的任务条目作为reference。
本扩展会逐步增加语境组织功能。
本扩展目前默认提示词的功能是校对一般的语言文字错误和知识性错误，具体内容见代码库种的proofreader.ts文件。你可以设置自己的提示词，不限于校对工作。
通过命令面板（Ctrl+Shift+P）可以
- 管理提示词 (AI Proofreader: set prompts)，可增、删、改。没有编辑界面，请写好后粘贴进入。
- 选择当前使用的提示词 (AI Proofreader: select prompt)
也可以在配置文件中处理提示词，但不适合没有编程知识的用户使用。
为了写好提示词，你需要了解本扩展的工作原理：
- 把你的提示词作为系统命令/系统提示词交给大模型
- 在第一轮对话中提交
<reference>${reference}</reference>和<context>${context}</context>； - 在第二轮对话中提交
<target>${target}</target> - 接收、处理第二轮对话的输出作为结果
整个过程没有魔法，处理的目的和方法完全由提示词和三种文本及其标签（reference、context、target）来定义。这就是说，你可以通过自己的提示词，让AI根据三种文本做你期望的任何处理工作， 比如撰写大意、插图脚本、练习题、注释，绘制图表，注音，翻译，进行专项核查（专名统一性、内容安全、引文、年代、注释等），收集信息（如名词术语）……
需要注意的是，在自定义提示词中，必须对要处理的目标文本（target）、参考资料（reference）、上下文（context）进行说明，如果用不到后两者也可以不说明。并且这种**说明应尽可能与三种标签的字面意义相协调，**比如target可以用作“要处理的目标文本”，也可以用作“要得到的具体目标”（作为系统提示词的补充），但不宜作为参考文本、样例等类。
提示词示例：
你是一位专业的儿童文学翻译家…… 用户会提供一段需要翻译的目标文本（target），你的任务是把这段文本翻译成适合孩子阅读的汉语作品……
用户如果供参考文本（reference），翻译时请模仿参考文本的语言风格，遵照参考文本中的人名、地名、术语等实体的指定译法……
用户如果提供上下文（context），翻译时要根据上下文确定目标文本（target）的具体含义，确保翻译的准确性和连贯性……
输出要求：
- 翻译目标文本（target）后输出;
- 不要给出任何解释、说明；
- ……
本扩展计划预置更多提示词，也欢迎用户通过用户群等渠道交流、分享提示词。
本人有一个开源提示词库，但不是针对本扩展的，改造（对三种标签进行说明）后才能用于本扩展。
为了让用户能够核验、控制每一个步骤，扩展会以要校对的文档的文件名（以“测试.md”为例）为基础，生成一些中间文件，各自的作用如下：
- 测试.md，要校对的文档
- 测试.json，切分上述文档的结果，供检查后用于校对；可以进一步与别的切分结果进行合并，以便搭配target + context + reference一起提交处理
- 测试.json.md，拼合上项JSON文件中的target的结果，用于查看或比较原始markdown文件，比JSON直观
- 测试.log，切分日志，用来检查切分是否合理
- 测试.proofread.json，校对上述JSON文件的直接结果，其中的
null项表示还没有校对结果，重新校对时只处理null对应的条目，而不会重复处理已经完成的条目；校对前后的JSON长度不一致时（比如切分标准不一导致）会提示备份 - 测试.proofread.json.md，拼合上项JSON文件中的结果，比较最初的markdown文件即可看出改动处；如果这个文件已经存在，则自动备份，并加时间戳
- 测试.proofread.html：通过jsdiff库比较校对前后markdown文件所得的结果，与Word近似的行内标记，可通过浏览器打印成PDF。需要联网调用jsdiff库，并等待运算完成
- 测试.proofread.log，校对日志，校对文本选段的结果也会存在这里
请特别注意：除自动累加的日志文件和提示备份的测试.proofread.json、自动备份的测试.proofread.json.md，其余中间文件，每次操作都将重新生成！如有需要，请自行备份。
- 从md反查PDF：从markdown文件选择文本，使用
Search Selection In PDF命令，将调用PDF查看器SumatraPDF打开同名的PDF文件，并搜索选中文本。须先安装好SumatraPDF，在高级选项中设置ReuseInstance = true可以避免重复打开同一个文件。 - vscode提供的文档比较（diff）功能：通过文件浏览器右键菜单使用；本扩展在vscode中的比较即调用了本功能。vscode是这些年最流行的文本编辑器，有许多便捷的文字编辑功能，很适合编辑工用作主力编辑器。
- 转换半角引号为全角：使用
AI Proofreader: convert quotes to Chinese命令或菜单。也可在设置中设定为自动处理。
- 确保在使用前已正确配置必要的 API 密钥。请妥善保存你的秘钥！
- 一般的语言文字校对依赖丰富的知识、语料，建议使用大规模、非推理模型。某些推理模型、混合模型可能因为运行时间过长而导致错误，而服务器端可能已经实际运行并计费！
- 长文本建议先切分后校对，文本长度过程会影响校对质量，并增加失败的几率
- 注意所用模型 API 调用频率和并发数的限制，可通过配置调整
从VS Code界面左下角或扩展界面的⚙️，或从命令面板（Ctrl+Shift+P）查找命令Preferences: Open Settings (UI)都能进入扩展配置界面。
配置项的意义请参考本文档相关的部分，以及对应模型的文档。
参考：
- Deepseek限速：没有并发限制，但服务器在高流量时会延迟（需要注意观察）
- 阿里云百炼平台限流规则：qwen-max系列稳定版的rpm通常为600甚至更高，带日期的快照版通常为60，没有并发限制（建议为10）
- 谷歌rate-limits
⚠️ proofread.retryDelay与proofread.timeout的单位均为 秒。扩展会在内部自动转换为毫秒进行 API 调用，升级旧版本后请确认你的设置值。
目前支持这些大语言模型服务：
- Deepseek开放平台（默认）
- 阿里云百炼，模型列表
- Google Gemini，模型列表
- Ollama本地模型，对计算机性能、专业知识要求较高
每个模型用于校对的最佳温度需要耐心测试才能得到。
以往的经验是，温度为1时极少有错误和无效改动。
提高模型温度可以增加随机性，如此多次尝试有可能提高召回率，同时也增加不稳定和错误率。
以下是官方资料：
-
deepseek
temperature参数默认为 1.0。官方建议根据如下表格，按使用场景设置
temperature。场景 温度 代码生成/数学解题 0.0 数据抽取/分析 1.0 通用对话 1.3 翻译 1.3 创意类写作/诗歌创作 1.5 -
阿里云百炼平台
- deepseek v3/r1: temperature：0.7（取值范围是
[0:2)） - qwen系列: 取值范围是
[0:2)
- deepseek v3/r1: temperature：0.7（取值范围是
-
Google Gemini
默认为1
- 预置更多提示词，包括常用的专项校对
- 典型错误举例校对
- 标点符号用法错误
- 数字用法错误
- 年代、时间错误
- 语法错误
- 少见、可疑字词句的正常化、优化
- PDF/OCR纯文本整理
- 练习题就地回答
- 翻译
- 按小学语文教材标准加拼音
- 典型错误举例校对
- 取消接口改变的警示
- 数字连续性检查（以Python库相应模块为基础）
- 整理勘误表（以Python库句子对齐模块为基础）
- 勘误条目聚类
- 增量样例校对模式
- 人工核准界面
- 引文核对（以Python库相应模块为基础）
- 自主发现、提出、校对知识性问题
- 检索、核对互联网资料
- 检索、核对本地词典（以Python库mdict查询模块为基础）
- 多平台支持测试
- 内部git版本管理
- 推理模型无法使用的问题（可能单纯是因为运行时间过长）
- 在按长度切分的基础上调用LLM辅助切分（似乎仅仅在没有空行分段文本上有必要）
- 支持Copilot（尝试过一次，回文说API还没有开放。还需要研究参考项目。）
- 优化：支持直接从
*.proofread.json.md反查*.pdf - 优化：文档
- bug修复
- 优化：默认并发数改为10、rpm改为600、超时改为90秒
- 优化：外语校对提示
- !!! caution 设置中的毫秒改为秒
- 特性：段落整理：在原有段末添加空行基础上，增加了删除段内分行的功能
- 特性：在段末添加空行，适用于从PDF转出的断行、无空行文本
- 优化：“按长度切分，扩展前后段落为上下文”，修改为“按长度切分，以前后段落为上下文”，不再重复提交target自身
- 优化：合并JSON功能增加“拼接”模式
- 优化：只有当校对前后的JSON长度不一时才备份、删除，否则不备份；在参数确认后才开始备份；保持面板、菜单、命令各入口一致
- 优化：文档
- 修复：并发失效问题
- 修复：内容为空字符串问题（直接返回原内容）
- 优化：文件转换工具兼容多平台和常用终端
- 优化：统一文件备份逻辑为备份旧文件为bak
- 优化：支持 pdftotext 常用参数，模式、切边、页码等
- 优化：删除所有文件转换后的打开文件的功能
- 优化：处理面板中增加校对耗时信息；删除重复的校对结果统计信息
- 优化：取消用户设置提示词的数量限制
- 优化：删除调试日志功能
- bug修复：测试pdftotext是否存在改为更通用的方法
- 优化：使用前测试pandoc是否存在
- 增加使用pdftotext工具把PDF文件转换为Markdown文件（实际是纯文本）的功能
- result panel 优化：紧凑设计，减少冗余信息，尽量一屏展示；色调更淡雅
- 修复了转换子目录中的文档时不能正确处理图片的问题
- 更新了文档
- 新增功能：JSON批量提交LLM前展示所有参数，请用户确认或取消
- 显示文件路径、总段落数、处理参数（平台、模型、温度、并发数、请求频率、提示词）
- 用户可以选择确认开始或取消操作
- 支持所有触发方式：右键菜单、命令面板、webview面板按钮等
- 改进webwiew panel
- 增加进度条
- 呈现切分摘要信息，如段落数、超长段落等
- 查看日志文件时自动滚动到底部
- debug：重用webwiew报错
- 取消校对时生成jsdiff html，改成提示用户生成
- 切分和校对结果改成Webview Panel呈现，在一个切分、校对流程中可以重新打开
- 切分结果菜单增加一个“校对JSON结果”按钮
- 禁用Gemini模型思考功能
- 添加重试机制
- 新增功能：支持Ollama本地模型，无需网络连接即可使用本地大语言模型进行校对（适合专家用户）
- 优化：为本地模型增加了更长的超时时间，适应本地计算的特点
- 优化：完善校对过程中给用户的配置信息、日志文件中输出的配置信息
- 新增功能：markdown切分/选段校对时，可以加入前后段落作为context
- 优化：转换半角引号为全角的算法，避免跨行引号转换错误
- 扩展了jsdiff比较并生成html的功能，支持JSON文件，并允许用户指定每次比较的片段数量，避免过长文本无法渲染的问题
- 优化了文件切分功能，新增统一的切分入口
- 改进了校对进度显示和取消操作
- 增强了自动备份功能
- 优化了临时文件管理
- 修复了并发请求数的默认值问题
- 完善了错误处理和用户提示
# 安装依赖
npm install
# 开发时实时编译
npm run watch
# 打包
npm run package
# 构建 vsix 扩展安装文件用
npm run package-vsix
# 发布
npm run publish