FormatLens

面向 Microsoft Word 的格式检查与修复 Agent。

A format inspection and repair agent for Microsoft Word.

FormatLens 不是写作、润色或续写工具。它专注于一件事：检查 Word 文档中的格式问题，定位问题，在受控范围内完成修复，并在修复后自动复查。

主要能力

• 按当前选区、当前章节、全文或自然语言指定范围检查文档；
• 检查页面设置、标题与编号、正文与列表、目录、题注与注释、文字与标点、样式一致性；
• 展示问题位置、当前值、建议值和修复风险，并可定位到 Word 原文；
• 支持单项、多选、按类别和全部可修复问题的批量处理；
• 修复后自动复查，最多执行 3 轮，连续无进展时停止；
• 用自然语言执行受限的批量格式调整，例如“把所有三级标题改为蓝色且不加粗”；
• 导入格式正确的 Word 文档，识别并保存为可切换的检查标准；
• 面向长文档做了分段扫描、快照复用、修复顺序和内存控制优化。

规则检查和多数快捷修复在本机完成，不会把整篇文档发送给模型。自然语言对话和需要理解上下文的指令才使用用户配置的 OpenAI 兼容接口。

安装

普通用户

1. 在 GitHub Releases 下载 FormatLens-<版本>.zip（请使用 v1.0.1 或更高版本）。
2. 完整解压压缩包，不要直接在压缩包内运行文件。
3. 双击 setup.exe，按提示完成安装。
4. 重新打开 Microsoft Word，在“开始”选项卡中点击 FormatLens。

安装程序会检查 VSTO Runtime。首次公开版本使用自签名测试证书，Windows 可能显示“未知发布者”提示；源代码、构建脚本和发布内容均在本仓库可审查。商业代码签名证书不在当前项目范围内。

运行要求：

• Windows 10/11；
• Microsoft Word 桌面版；
• .NET Framework 4.8；
• Microsoft Edge WebView2 Runtime；
• Microsoft Visual Studio Tools for Office Runtime。

当前不支持 Word for Mac、Word 网页版或 WPS。尚未在所有 Office 版本和干净电脑上完成兼容性验证，因此不会宣传“支持所有版本”。

v1.0.0 的安装订阅标识可能与早期开发版冲突，已停止推荐。v1.0.1 使用新的内部加载项标识，产品名称仍为 FormatLens。

更完整的安装与故障排查见 安装指南。

配置 LLM

安装后点击 FormatLens 顶部的齿轮按钮，只需填写：

1. API Key
2. Base URL，例如 https://api.example.com/v1
3. 模型名称

FormatLens 使用 OpenAI 兼容接口，不绑定单一模型提供商。API Key 使用 Windows DPAPI 以当前用户身份加密，保存在 %LOCALAPPDATA%\FormatLens\llm-settings.json；界面不会回显密钥，日志也不会记录密钥或文档正文。

保存时会检查三项是否完整以及 Base URL 是否有效，但不会主动发送联网测试请求。若 Key、模型名称或接口兼容性有误，会在首次发送消息时显示服务端错误。

开发者也可以使用环境变量覆盖界面设置：

FORMATLENS_LLM_API_KEY
FORMATLENS_LLM_BASE_URL
FORMATLENS_LLM_MODEL

环境变量只要出现任意一项，就必须三项完整。Base URL 默认要求 HTTPS；只有本机回环地址允许 HTTP。

不配置 LLM 时，确定性“仅检查”和“检查并修复”等快捷流程仍可使用；自然语言 Agent 无法使用。

使用方式

1. 在顶部选择“选区 / 本章 / 全文”。
2. 在“检查类别”中勾选需要检查的内容。
3. 点击“仅检查”查看问题，或点击主按钮“检查并修复”。
4. 需要一次性调整时，在输入框中描述明确格式，例如“只修复本章标题”。
5. 默认“安全模式”会在修改前确认；可点击切换为本次会话自动执行。

FormatLens 不自动保存 Word 文档。批量修改尽量合并为一次撤销记录，并绑定当前文档、范围和检查结果，失效的旧请求不会直接应用到新的文档状态。

从源码构建

开发环境需要 Visual Studio 2022 的 Office/SharePoint 开发组件、.NET Framework 4.8 Developer Pack、Node.js 和 Microsoft Word。

.\scripts\check-prerequisites.ps1
.\scripts\build.ps1 -Configuration Debug

生成本地测试签名发布包：

.\scripts\publish.ps1 -Version 1.0.1

输出位于 release/FormatLens-1.0.1.zip。证书私钥不会写入仓库；脚本使用当前 Windows 用户证书库中的 CN=FormatLens Development 测试证书。

项目结构与验证方法见 开发说明，详细功能边界见 项目概览。

隐私与安全

• 模型只能调用注册的 Word 白名单工具，不能执行任意 VBA、脚本或系统命令；
• 检查、修复请求绑定活动文档、范围和扫描结果；
• 复杂图文关系、语义内容和不可靠场景采用保守处理；
• 本仓库忽略 .env、密钥、证书私钥、日志、构建产物和本地 Word 文档；
• 发布前应继续使用 GitHub Secret Scanning 或同类工具检查提交历史。

如发现安全问题，请不要在公开 Issue 中粘贴 API Key、真实文档内容或包含私人路径的日志。

当前边界

• 这是个人开源项目，不是公司内部部署产品；
• 表格单元格内复杂格式和复杂图文环绕不是当前主要检查范围；
• 内容遗漏、章节是否应存在等语义审稿仍需人工完成；
• 自然语言自定义调整目前主要覆盖标题、正文、列表、题注和注释；“目录加粗”等含义不明确或尚无对应目标的表达可能需要用户说得更具体；
• 长文档性能受电脑、文档结构、图表密度和修复数量影响；
• v1.0.1 Preview 安装包已在当前电脑完成安装、连续两次 Word 冷启动、任务窗格、本地检查及修复复查验收；仍需继续补充干净电脑和不同 Office 版本的安装测试。

License

MIT License © 2026 Winterxin