sugo

Sugo

精简文档。给大模型喂精华，而不是水分。

快速开始 · 功能介绍 · 对比 · MCP · 路线图 · 🇮🇹 意大利语

---

🔒 100% 本地 无云端、无遥测

✂️ 更少的令牌 重复页眉时减少 33–38%，真实法律文本约减少 3%

🧾 不会悄悄丢失内容 每项删减都有记录

🪶 轻量 无需 GPU，可在 8 GB RAM 上运行

Sugo 可将 PDF、Office 文件、屏幕截图和图像转换为简洁紧凑的 Markdown，供 RAG 系统、AI Agent 和大模型聊天使用。它会删除只会消耗令牌的内容（重复页眉和页脚、页码、隐藏文本、跟踪参数、屏幕截图周围的应用界面），同时保留正文、表格和结构。所有处理都在你的电脑上完成：无需云端 API、无遥测，也不会向任何地方发送数据。

在意大利语中，il sugo del discorso 意为“要点”，而 sugo 是一种酱汁，你需要不断收浓，直到只剩下浓郁的风味。这正是 Sugo 对文档所做的事。

功能介绍

一个小型生成的三页 PDF，纯文本提取器会将其如下提供给模型（第 1 页和第 3 页看起来相同）：

ACME S.p.A. - Annual Report 2025                Confidential
3.2 Revenue
Revenue grew by 12% in the second half, driven by the export market.
Details: https://acme.example/report?utm_source=newsletter&utm_medium=email
Page 14 of 120

运行 sugo report.pdf 后的输出：

ACME S.p.A. - Annual Report 2025

# 3.1 Costs

Costs fell by 3% thanks to the new suppliers.
Details: https://acme.example/report

# 3.2 Revenue

Revenue grew by 12% in the second half, driven by the export market.
Details: https://acme.example/report

# 3.3 Outlook

The board expects stable growth next year.
Details: https://acme.example/report

页眉只保留一次，而不是每页重复；页码、重复出现的 “Confidential” 和跟踪参数都已删除；正文保持不变。sugo stats 会计算差异：在这个小型生成示例中，令牌数从 180 → 97，节省 46%；页面装饰较少的真实文档，节省幅度要小得多（见下文）。每项删减都会记录执行清理的工具及原因，因此你随时可以检查哪些内容被删除。无法读取的文本会标记为无法辨认，绝不会猜测。

在包含五种语言的基准语料库中，没有任何文档丢失文本（3 张屏幕截图中 OCR 误读了少数字符，误读比例为 1–7%）。节省幅度很大程度上取决于文档：

文档	节省的令牌
带有重复页眉、页脚和页码的报告	33–38%
聊天或代码屏幕截图，与直接发送图像相比，使用 Markdown	便宜 94–98%（Claude、Gemini、OpenAI）
EUR-Lex 上的真实欧盟法规，主要是实质性法律文本	2.9–3.5%

它在普通电脑上也能快速运行，不需要新款电脑：在一台配有 2 核、无 GPU 的 2010 年台式机上，转换 100 页 PDF 只需 3.6 秒，转换手机屏幕截图只需 13.7 秒（完整数据见 TESTING）。

对比情况

使用相同的 31 份文档基准语料库（26 份由 Sugo 项目生成的合成文档，以及 5 份真实的欧盟法规 PDF）、相同的分词器和相同的基准事实，对比两个知名替代方案 — 完整方法、原始数据和局限见 docs/comparisons：

	Sugo	Docling	MarkItDown
转换后内容完整、未乱码的文档	28 / 31	25 / 31	14 / 31
聊天／代码截图 OCR	✅ 未丢失文本；3 张带重音符号的截图字符错误率为 1–7%	⚠️ 词语正确，但部分聊天内容顺序错误	❌ 输出为空
开箱即读 PDF	✅	✅	❌ 需要额外组件
真实欧盟法规 PDF，每条条款均保留	✅	⚠️ 5 份中有 2 份丢失条款	❌ 每份都丢失 2–7 条

丢失内容的工具在纸面上也会“节省”令牌 — 这不是压缩，而是数据丢失。上面的每个数字都对应着转换后实际保留下来的内容。

需要客观看待：语料库规模较小且大多为合成数据，并由 Sugo 作者构建，因此应将其视为合理性检查，而非定论。在报告类 PDF 上，Docling 在不丢失内容的情况下节省的令牌略多于 Sugo（约 38–48%，而 Sugo 为 33–38%）；在此语料库上的速度也慢了数倍。原始数据和完整的逐文档表格见链接中的对比报告。

状态

说明

v0.1.1 已发布，可在 PyPI 上获取，包名为 sugo-cli（v0.1.0 是首个签名发布版本）。目前仍处于 0.x 阶段；在 1.0 之前，接口约定可能会提前通知后变更。发布版本均可复现构建，并附带 SBOM、Sigstore 证明和 PyPI Trusted Publishing。

当前可用	后续计划
原生支持 PDF、DOCX、XLSX、PPTX、XML	扫描书籍清理工具、EPUB、电子邮件、网页
使用本地 OCR 处理图片和截图（PNG、JPEG、WEBP）	更大的表格、normal 和 quality 引擎级别
聊天和代码截图检测	日语、中文、韩语
Markdown，以及适用于向量数据库的 JSON Lines 分块	交互式 Shell、引导式设置
按提供商统计令牌用量（sugo stats）	后台服务和文件夹监视器
命令行、面向 Agent 的 MCP 服务、本地网页	工作配置和配方
英语、意大利语、西班牙语、法语、德语界面和文本规则

完整计划请参阅路线图。

快速开始

Sugo 需要 Python 3.12、3.13 或 3.14。安装后约占用 400 MB 磁盘空间，因为其中包含 PDF 库、OCR 引擎及其模型。最简单的安装方式是使用 uv：

uv tool install sugo-cli

也可以使用 pip：

pip install sugo-cli

如果使用 pip 安装后，sugo 显示“无法识别”或“找不到”，说明 pip 将它安装到了系统不会搜索的文件夹中。在 Windows 上，如果 pip 仅为当前用户安装（“Defaulting to user installation”），就会出现这种情况。你可以使用 uv tool install sugo-cli 安装，并运行一次 uv tool update-shell；或者将 pip 在警告中指出的文件夹（Windows 上为 %APPDATA%\Python\Python3XX\Scripts）添加到 Path，然后打开新的终端。

提示

该包名为 sugo-cli，因为 PyPI 上的名称 sugo 已被一个无关的空项目占用（名称转让申请正在处理中）。安装后使用的命令仍然是 sugo；sugo-cli 也可用。旧版说明中使用的 sugo-cli[lite] 仍然有效：现在默认已包含所有功能。

若要改为从源代码运行最新开发版本：

uv tool install git+https://github.com/Muralnick/sugo

转换文件并输出其 Markdown：

sugo report.pdf

你还可以：

sugo convert *.pdf -o out/            # one NAME.md per file, in out/
sugo convert report.pdf --chunks      # chunks as JSON Lines, ready for RAG
sugo stats screenshot.png             # tokens saved, per LLM provider
sugo clip                             # convert the screenshot in your clipboard
sugo ui                               # open the local web page: drop a file, get Markdown
sugo doctor                           # check the installation

添加 --json，即可输出脚本可读取的内容。

在 AI Agent 中使用（MCP）

Sugo 可以通过 MCP 为 Claude Code 或 Codex 等 Agent 提供服务。它只会读取你指定文件夹中的内容：

claude mcp add sugo -- sugo mcp --root ~/Documents

Agent 会获得两个工具：convert_document 和 estimate_savings。

卸载

按照安装时使用的方式移除程序：

uv tool uninstall sugo-cli

或者，如果你使用了 pip：

pip uninstall sugo-cli

如果你将 Sugo 添加到了某个 Agent，也请在该 Agent 中移除，例如 claude mcp remove sugo。

卸载程序不会删除 Sugo 创建的文件。这些文件仅保存在你的电脑上，你可以手动删除：

内容	Windows	macOS	Linux
设置（config.toml）	%LOCALAPPDATA%\sugo	~/Library/Application Support/sugo	~/.config/sugo
缓存（已转换文档的文本）	%LOCALAPPDATA%\sugo\Cache	~/Library/Caches/sugo	~/.cache/sugo

如果设置了 SUGO_CACHE_DIR，缓存则位于该文件夹中。缓存包含已转换文档中的文本，因此如果这些文档是私密的，请删除缓存。除了这两个文件夹以及你要求它写入的文件（例如 -o 输出文件或收据）之外，Sugo 不会在磁盘上保存其他内容。

在旧电脑上的表现

于 2026-11-03 在一台 2010 年的台式机上测得：Intel Core i5-650（2 核、4 线程、不支持 AVX）、8 GB RAM、SSD，没有可用的 GPU。性能低于 Sugo 所针对的 8 GB、4 核机器。

任务	结果	目标
原生 PDF，100 页，包含清理	3.6 秒，约 28 页/秒	≥ 20 页/秒
该 PDF 的峰值内存	98 MB	< 1 GB
密集的手机截图（30 行）→ 文本，OCR	30 行全部识别，字符错误率 0%，411 MB	< 1 GB
同一张截图，耗时	13.7 秒	< 2 秒

即使在这台机器上，原生文档的处理速度也远超目标。OCR 结果准确，但在不支持 AVX 的 CPU 上速度较慢；提升速度已列入路线图。详情和脚本见 TESTING。

支持的文件

类型	格式	大小限制
文档	PDF（带文本层）、DOCX、XLSX、PPTX	200 MB
图像	PNG、JPEG、WEBP（截图、文字照片）	50 MB
数据	XML	50 MB

旧版 .doc、.xls 和 .ppt 文件以及受密码保护的文件无法读取：请先另存一份新文件。

工作原理

flowchart LR
    F[Your file] --> E[Reader<br/>PDF · Office · OCR · XML]
    E --> IR[Document → Page → Block]
    IR --> C[Cleaners<br/>propose removals]
    C --> K[Core<br/>applies and records them]
    K --> M[Markdown]
    K --> J[JSONL chunks]
    K --> S[Token metrics]

每种读取器都会将文件转换为由页面和文本块组成的相同结构。清理器只会提出更改建议；核心负责应用这些更改，并标记每个被移除的文本块以及移除者和原因，而不是直接删除它。这使输出可供核查且可复现。完整设计见 ARCHITECTURE。

承诺

这些承诺记录在 PRINCIPLES 中，并通过测试进行检查：

• 以本地运行作为原则。 转换过程始终无需联网。不使用云 API，也不收集遥测数据。
• 绝不猜测。 无法读取的文本会标记为无法辨认，不会自行补全。
• 绝不悄然丢失内容。 每项移除都会连同原因一起记录。
• 如实呈现指标。 节省量会经过测算；如果发送原始图像更省，Sugo 也会告知你。
• 安全处理不可信文件。 限制大小和处理时间，安全解析 XML，并通过校验和验证模型。参见威胁模型。

文档

文档	内容
ARCHITECTURE	完整的系统设计
FEATURES	按引擎级别、工作配置和支持格式介绍功能
THREAT_MODEL	安全分析
TESTING	测试、基准测试、性能目标
ROADMAP	开发计划和首个版本的范围
ADRs	架构决策记录
PRINCIPLES	Sugo 始终坚守的承诺
AI_WORKFLOW	本项目如何借助 AI 构建

贡献和安全

请参阅 CONTRIBUTING。如需报告漏洞，请按照 SECURITY 中的说明私下报告，不要在公开议题中报告。

许可证

AGPL-3.0-or-later（参见 ADR-010）。