llm-min.txt: Min.js Style Compression of Tech Docs for LLM Context 🤖

📜 Table of Contents

• llm-min.txt: Min.js Style Compression of Tech Docs for LLM Context 🤖
  • 📜 Table of Contents
  • What is llm-min.txt and Why is it Important?
  • Understanding llm-min.txt: A Machine-Optimized Format 🧩
  • Does it Really Work? Visualizing the Impact
  • Quick Start 🚀
  • Output Directory Structure 📂
  • Choosing the Right AI Model (Why Gemini) 🧠
  • How it Works: A Look Inside (src/llm_min) ⚙️
  • What's Next? Future Plans 🔮
  • Common Questions (FAQ) ❓
  • Want to Help? Contributing 🤝
  • License 📜

---

What is llm-min.txt and Why is it Important?

If you've ever used an AI coding assistant (like GitHub Copilot, Cursor, or others powered by Large Language Models - LLMs), you've likely encountered situations where they don't know about the latest updates to programming libraries. This knowledge gap exists because AI models have a "knowledge cutoff" – a point beyond which they haven't learned new information. Since software evolves rapidly, this limitation can lead to outdated recommendations and broken code.

Several innovative approaches have emerged to address this challenge:

• llms.txt A community-driven initiative where contributors create reference files (llms.txt) containing up-to-date library information specifically formatted for AI consumption.

• Context7 A service that dynamically provides contextual information to AIs, often by intelligently summarizing documentation.

While these solutions are valuable, they face certain limitations:

• llms.txt files can become extraordinarily large – some exceeding 800,000 tokens (word fragments). This size can overwhelm many AI systems' context windows.

  

  Many shorter llms.txt variants simply contain links to official documentation, requiring the AI to fetch and process those documents separately. Even the comprehensive versions (llms-full.txt) often exceed what most AI assistants can process at once. Additionally, these files may not always reflect the absolute latest documentation.

• Context7 operates somewhat as a "black box" – while useful, its precise information selection methodology isn't fully transparent to users. It primarily works with GitHub code repositories or existing llms.txt files, rather than any arbitrary software package.

llm-min.txt offers a fresh approach:

Inspired by min.js files in web development (JavaScript with unnecessary elements removed), llm-min.txt adopts a similar philosophy for technical documentation. Instead of feeding an AI a massive, verbose manual, we leverage another AI to distill that documentation into a super-condensed, highly structured summary. The resulting llm-min.txt file captures only the most essential information needed to understand a library's usage, packaged in a format optimized for AI assistants rather than human readers.

Modern AI reasoning capabilities excel at this distillation process, creating remarkably efficient knowledge representations that deliver maximum value with minimal token consumption.

---

Understanding llm-min.txt: A Machine-Optimized Format 🧩

The llm-min.txt file utilizes the Structured Knowledge Format (SKF) – a compact, machine-optimized format designed for efficient AI parsing rather than human readability. This format organizes technical information into distinct, highly structured sections with precise relationships.

Key Elements of the SKF Format:

1. Header Metadata: Every file begins with essential contextual information:

   • # IntegratedKnowledgeManifest_SKF: Format identifier and version
   • # SourceDocs: [...]: Original documentation sources
   • # GenerationTimestamp: ...: Creation timestamp
   • # PrimaryNamespace: ...: Top-level package/namespace, critical for understanding import paths

2. Three Core Structured Sections: The content is organized into distinct functional categories:

   • # SECTION: DEFINITIONS (Prefix: D): Describes the static aspects of the library:

     • Canonical component definitions with unique global IDs (e.g., D001:G001_MyClass)
     • Namespace paths relative to PrimaryNamespace
     • Method signatures with parameters and return types
     • Properties/fields with types and access modifiers
     • Static relationships like inheritance or interface implementation
     • Important: This section effectively serves as the glossary for the file, as the traditional glossary (G section) is used during generation but deliberately omitted from the final output to save space.

   • # SECTION: INTERACTIONS (Prefix: I): Captures dynamic behaviors within the library:

     • Method invocations (INVOKES)
     • Component usage patterns (USES_COMPONENT)
     • Event production/consumption
     • Error raising and handling logic, with references to specific error types

   • # SECTION: USAGE_PATTERNS (Prefix: U): Provides concrete usage examples:

     • Common workflows for core functionality
     • Step-by-step sequences involving object creation, configuration, method invocation, and error handling
     • Each pattern has a descriptive name (e.g., U_BasicCrawl) with numbered steps (U_BasicCrawl.1, U_BasicCrawl.2)

3. Line-Based Structure: Each item appears on its own line following precise formatting conventions that enable reliable machine parsing.

Example SKF Format (Simplified):

# 集成知识清单_SKF/1.4 LA
# 源文档: [example-lib-docs]
# 生成时间戳: 2024-05-28T12:00:00Z
# 主命名空间: example_lib

# 第一部分：定义（前缀：D）
# 主要定义格式: Dxxx:Gxxx_Entity [DEF_TYP] [NAMESPACE "relative.path"] [OPERATIONS {op1:RetT(p1N:p1T)}] [ATTRIBUTES {attr1:AttrT1}] ("注释")
# ---
D001:G001_Greeter [组件定义] [NAMESPACE "."] [OPERATIONS {greet:Str(name:Str)}] ("一个简单的问候类")
D002:G002_AppConfig [组件定义] [NAMESPACE "config"] [ATTRIBUTES {debug_mode:Bool("只读")}] ("应用程序配置")
# ---

# 第二部分：交互（前缀：I）
# 格式: Ixxx:源引用 INT_VERB 目标引用或字面量 ("备注_条件_错误(Gxxx_ErrorType)")
# ---
I001:G001_Greeter.greet 调用 G003_Logger.log ("记录问候活动")
# ---

# 第三部分：使用模式（前缀：U）
# 格式: U_Name:模式标题关键词
#         U_Name.N:[参与者或引用] 动作关键词 (涉及目标或数据的引用) -> [结果或状态变化涉及的引用]
# ---
U_BasicGreeting:基本用户问候
U_BasicGreeting.1:[用户] 创建 (G001_Greeter) -> [greeter_instance]
U_BasicGreeting.2:[greeter_instance] 调用 (greet name='Alice') -> [greeting_message]
# ---
# 清单结束

llm-min-guideline.md 文件（与 llm-min.txt 同时生成）提供了详细的解码说明和模式定义，使 AI 能够正确解析 SKF 格式。它作为关键的配套文档，解释了文件中使用的符号、字段含义以及关系类型。

---

真的有效吗？可视化其效果

llm-min.txt 在大幅减少 token 数量的同时，保留了 AI 助手所需的核心知识。下图比较了原始库文档（llm-full.txt）与压缩后的 llm-min.txt 版本之间的 token 数量：

结果显示，token 减少幅度通常在 90% 至 95% 之间，某些情况下甚至超过 97%。这种极致的压缩结合高度结构化的 SKF 格式，使得 AI 工具能够比处理原始文本更高效地摄入和处理库文档。

在我们的示例目录中，您可以亲自查看这些令人印象深刻的成果：

• sample/crawl4ai/llm-full.txt: 原始文档（未压缩）
• sample/crawl4ai/llm-min.txt: 压缩后的 SKF 表示
• sample/crawl4ai/llm-min-guideline.md: 格式解码器配套文件，也可参见 llm-min-guideline.md

大多数压缩后的文件仅包含约 10,000 个 token，完全在现代 AI 助手的处理能力范围内。

如何使用？

只需在您的 AI 驱动 IDE 的对话中引用这些文件，您的助手便会立即获得关于该库的详细知识：

性能如何？

进行基准测试是必要的，但非常困难。LLM 代码生成具有随机性，生成代码的质量取决于诸多因素。例如，crawl4ai、google-genai 和 svelte 这些软件包目前仍难以被 LLM 正确生成代码。而使用 llm-min 将显著提高代码生成的成功率。

---

快速入门 🚀

开始使用 llm-min 非常简单：

1. 安装：

• 对于普通用户（推荐）：

  pip install llm-min
  
  # 安装所需的浏览器自动化工具
  playwright install
  

• 对于贡献者和开发者：

  # 克隆仓库（如果尚未完成）
  # git clone https://github.com/your-repo/llm-min.git
  # cd llm-min
  
  # 创建并激活虚拟环境
  python -m venv .venv
  source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
  
  # 使用 UV 安装依赖项（比 pip 更快）
  uv sync
  uv pip install -e .
  
  # 可选：设置 pre-commit 钩子以保证代码质量
  # uv pip install pre-commit
  # pre-commit install
  

2. 设置你的 Gemini API 密钥：🔑

llm-min 使用 Google 的 Gemini AI 来生成压缩后的文档。你需要一个 Gemini API 密钥才能继续：

• 最佳实践： 将你的密钥值设置为名为 GEMINI_API_KEY 的环境变量：

  # Linux/macOS
  export GEMINI_API_KEY=your_api_key_here
  
  # Windows（命令提示符）
  set GEMINI_API_KEY=your_api_key_here
  
  # Windows（PowerShell）
  $env:GEMINI_API_KEY="your_api_key_here"
  

• 替代方案： 直接通过 --gemini-api-key 命令行选项提供你的密钥。

你可以在 Google AI Studio 或 Google Cloud 控制台获取 Gemini API 密钥。

3. 生成你的第一个 llm-min.txt 文件：💻

从以下输入源中选择一个：

输入源选项	短选项	类型	功能
--input-folder	-i	DIRECTORY	📁 处理本地文档文件。 递归扫描指定目录中的 .md、.txt 和 .rst 文件。使用此选项时会跳过网页爬取。
--package	-pkg	TEXT	📦 处理 Python 包。 自动查找并爬取该包的文档网站。
--doc-url	-u	TEXT	🌐 处理文档网站。 直接爬取指定的 URL。

配置选项	短选项	类型	功能
--output-dir	-o	DIRECTORY	保存生成文件的目录（默认：llm_min_docs）。
--output-name	-n	TEXT	为 output-dir 内的子文件夹指定自定义名称。
--library-version	-V	TEXT	指定库版本（在使用 --input-folder 或 --doc-url 时有用）。
--max-crawl-pages	-p	INTEGER	最多读取的网页数量（默认：200；0 表示无限制）。仅适用于网页爬取。
--max-crawl-depth	-D	INTEGER	在网站上跟随链接的最大深度（默认：3）。仅适用于网页爬取。
--chunk-size	-c	INTEGER	每次传递给 AI 的文本量（默认：0，启用自适应分块）。如果为 0，llm-min 会自动确定最佳大小。
--gemini-api-key	-k	TEXT	你的 Gemini API 密钥（如果未设置为环境变量）。
--gemini-model	-m	TEXT	要使用的 Gemini 模型（默认：gemini-2.5-flash-lite-preview-06-17）。
--force-reprocess			即使存在 llm-full.txt 也强制重新处理，并忽略中间文件。
--save-fragments		BOOLEAN	保存中间片段以便调试和重试（默认：True）。
--verbose	-v		在运行时显示更详细的日志信息。

示例命令：

# 📦 处理 "typer" Python 包，保存到 "my_docs" 文件夹
llm-min -pkg "typer" -o my_docs -p 50

# 🌐 处理 FastAPI 文档网站
llm-min -u "https://fastapi.tiangolo.com/" -o my_docs -p 50

# 📁 处理本地文件夹中的文档文件
llm-min -i "./docs" -o my_docs

# 📁 处理本地文件，自定义输出名称和版本
llm-min -i "./my-project-docs" -o my_docs -n "my-project" -V "1.2.3"

# 📁 处理项目的整个文档目录结构
llm-min -i "/path/to/project/documentation" -o project_docs --verbose

本地文件夹处理详情： 📁

当使用 --input-folder 时，llm-min 会：

• 递归扫描指定目录中的文档文件
• 处理扩展名为 .md（Markdown）、.txt（纯文本）、.rst（reStructuredText）的文件
• 将所有找到的文件合并成一个内容流
• 完全跳过网页爬取（从而更快且无需互联网连接）
• 将原始合并内容保存为 llm-full.txt，并生成压缩后的 llm-min.txt

这特别适用于：

• 内部/专有文档，这些文档无法在线获取
• 本地项目文档，你正在开发的文档
• 离线处理，当互联网访问受限时
• 自定义格式的文档

4. 在 Python 中的程序化使用： 🐍

你也可以直接将 llm-min 集成到你的 Python 应用程序中：

from llm_min import LLMMinGenerator
import os

# 用于 AI 处理的配置
llm_config = {
    "api_key": os.environ.get("GEMINI_API_KEY"),  # 使用环境变量
    "model_name": "gemini-2.5-flash-lite-preview-06-17",  # 推荐模型
    "chunk_size": 600000,  # 每次 AI 处理的字符数
    "max_crawl_pages": 200,  # 最大爬取页面数（仅限网页爬取）
    "max_crawl_depth": 3,  # 链接跟随深度（仅限网页爬取）
}

# 初始化生成器（输出文件将保存到 ./my_output_docs/[source_name]/）
generator = LLMMinGenerator(output_dir="./my_output_docs", llm_config=llm_config)

# 📦 为 Python 包生成 llm-min.txt
try:
    generator.generate_from_package("requests")
    print("✅ 成功创建了 'requests' 的文档！")
except Exception as e:
    print(f"❌ 处理 'requests' 时出错：{e}")

# 🌐 从文档 URL 生成 llm-min.txt
try:
    generator.generate_from_url("https://fastapi.tiangolo.com/")
    print("✅ 成功处理了 FastAPI 文档！")
except Exception as e:
    print(f"❌ 处理 URL 时出错：{e}")

# 📁 从本地文档文件生成 llm-min.txt
try:
    # 读取并合并本地文件夹中的所有文档文件
    import pathlib
    docs_folder = pathlib.Path("./my-project-docs")
    
    # 收集支持的文件类型内容
    content = ""
    for ext in [".md", ".txt", ".rst"]:
        for file_path in docs_folder.rglob(f"*{ext}"):
            with open(file_path, encoding="utf-8") as f:
                content += f"# 文件: {file_path.name}\n\n"
                content += f.read() + "\n\n---\n\n"
    
    # 处理合并后的内容
    generator.generate_from_text(
        input_content=content, 
        source_name="my-project",
        library_version="1.0.0"  # 可选
    )
    print("✅ 成功处理了本地文档！")
except Exception as e:
    print(f"❌ 处理本地文件时出错：{e}")

如需查看完整的命令行选项列表，请运行：

llm-min --help

---

输出目录结构 📂

当 llm-min 完成处理后，会创建如下整齐的目录结构：

your_chosen_output_dir/
└── name_of_package_or_website/
    ├── llm-full.txt             # 完整文档文本（原始内容）
    ├── llm-min.txt              # 压缩后的 SKF/1.4 LA 结构化摘要
    └── llm-min-guideline.md     # 用于 AI 解读的重要格式说明文档

例如，运行 llm-min -pkg "requests" -o my_llm_docs 后，将生成：

my_llm_docs/
└── requests/
    ├── llm-full.txt             # 原始文档
    ├── llm-min.txt              # 压缩后的 SKF 格式（D、I、U 部分）
    └── llm-min-guideline.md     # 格式解码说明

重要提示： llm-min-guideline.md 文件是 llm-min.txt 的关键配套文件。它提供了详细的模式定义和格式说明，AI 需要这些信息才能正确解读结构化数据。在使用 llm-min.txt 与 AI 助手交互时，务必同时提供此指南文件。

---

选择合适的 AI 模型（为何推荐 Gemini） 🧠

llm-min 使用 Google 的 Gemini 系列 AI 模型进行文档处理。虽然您可以通过 --gemini-model 选项指定特定的 Gemini 模型，但我们强烈建议使用默认设置：gemini-2.5-flash-lite-preview-06-17。

该模型在文档压缩方面具备以下优势，能够实现最佳效果：

1. 高级推理能力： 在理解复杂的技术文档以及提取 SKF 格式所需的关键结构关系方面表现出色。

2. 超大上下文窗口： 具备 100 万标记的输入容量，可一次性处理大量文档内容，从而实现更连贯、更全面的分析。

3. 成本效益高： 相较于其他大上下文模型，其性能与价格比更为理想。

默认模型经过精心挑选，能够在广泛的文档风格和技术领域中为 llm-min 的压缩流程带来最佳结果。

---

工作原理：内部解析（src/llm_min）⚙️

llm-min 工具采用一套复杂的多阶段流程，将冗长的文档转换为紧凑且针对机器优化的 SKF 清单：

1. 输入处理： 根据您的命令行选项，llm-min 会从相应来源收集文档：

   • 包（--package "requests"）： 自动发现并抓取该包的文档网站
   • URL（--doc-url "https://..."）： 直接抓取指定的文档网站
   • 本地文件夹（--input-folder "./docs"）： 递归扫描 .md、.txt 和 .rst 文件，并合并其内容

2. 文本准备： 收集到的文档会被清理并分割成易于处理的小块。原始文本会以 llm-full.txt 的形式保留。

3. 三步 AI 分析流水线（Gemini）： 这是生成 SKF 清单的核心部分，由 compacter.py 中的 compact_content_to_structured_text 函数协调完成：

   • 步骤 1：全局术语表生成（仅内部使用）：

     • 每个文档块都会使用 SKF_PROMPT_CALL1_GLOSSARY_TEMPLATE 提示词进行分析，以识别关键的技术实体，并生成带有临时 Gxxx ID 的“块内”术语表片段。
     • 这些片段会通过 SKF_PROMPT_CALL1_5_MERGE_GLOSSARY_TEMPLATE 提示词合并，解决重复项并创建统一的实体列表。
     • 随后，re_id_glossary_items 函数会为这些合并后的实体分配全局连续的 Gxxx ID（G001、G002 等）。
     • 该全局术语表在整个过程中会保留在内存中，但不会包含在最终的 llm-min.txt 输出中，以节省空间。

   • 步骤 2：定义与交互（D & I）生成：

     • 对于第一个文档块（或当只有一个块时），AI 会结合全局术语表，使用 SKF_PROMPT_CALL2_DETAILS_SINGLE_CHUNK_TEMPLATE 生成初始的 D 和 I 条目。
     • 对于后续块，则使用 SKF_PROMPT_CALL2_DETAILS_ITERATIVE_TEMPLATE，同时提供全局术语表和先前生成的 D&I 条目作为上下文，以避免重复。
     • 随着每个块的处理，新识别的 D 和 I 条目会被累积起来，并被赋予全局连续的 ID（D001、D002 等以及 I001、I002 等）。

   • 步骤 3：使用模式（U）生成：

     • 类似于步骤 2，第一个块使用 SKF_PROMPT_CALL3_USAGE_SINGLE_CHUNK_TEMPLATE，接收全局术语表、所有已累积的 D&I 条目以及当前块的文本。
     • 后续块则使用 SKF_PROMPT_CALL3_USAGE_ITERATIVE_TEMPLATE，额外接收之前生成的 U 条目，以便延续模式并避免重复。
     • 使用模式会被赋予描述性名称（如 U_BasicNetworkFetch），并包含编号步骤（如 U_BasicNetworkFetch.1、U_BasicNetworkFetch.2）。

4. 最终组装： 完整的 llm-min.txt 文件通过以下内容组合而成：

   • SKF 清单头部（协议版本、源文档、时间戳、主命名空间）
   • 累积的“DEFINITIONS”部分
   • 累积的“INTERACTIONS”部分
   • 累积的“USAGE_PATTERNS”部分
   • 最终的 # END_OF_MANIFEST 标记

概念性流程概览：

用户输入      →  文档收集   →  文本处理   →  AI 步骤 1：术语表   →  内存中的全局    →  AI 步骤 2：D&I     →  累积的 D&I
(CLI/Python)       (包/URL)      (分块)           (提取 + 合并)        术语表（Gxxx）        （按块）          （Dxxx、Ixxx）
                                                                                                                                     ↓
           ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐                      ↓
           ↓                                                                                                 ↑                      ↓
最终 SKF 清单   ←   组装   ←   累积的使用   ←   AI 步骤 3：使用   ←   全局术语表 + 累积的 D&I
(llm-min.txt)            （D,I,U）        模式（U_Name.N）      （按块）              （生成有效 U 条目的必要上下文）

这种多阶段方法确保了 SKF 清单的全面性，避免了跨块内容的重复，并保持了实体、定义、交互和使用模式之间的一致性引用。

---

下一步？未来计划 🔮

我们正在探索几个令人兴奋的方向来进一步发展 llm-min：

• 预生成文件的公共仓库 🌐 如果能建立一个中央枢纽，供社区共享和发现常用库的 llm-min.txt 文件，这将非常有价值。这样可以省去用户反复生成这些文件的麻烦，并确保信息的一致性和高质量。主要挑战包括质量控制、版本管理和托管基础设施成本。

• 基于代码的文档推断 💻 一种有趣的可能性是利用源代码分析（通过抽象语法树）自动生成或补充文档摘要。尽管初步实验表明这在技术上颇具挑战性，尤其是对于具有动态行为的复杂库而言，但这仍然是一个很有前景的研究方向，有望实现更精确的文档生成。

• 模型控制协议集成 🤔 尽管从技术上可行，但将 llm-min 实现为 MCP 服务器并不完全符合我们当前的设计理念。llm-min.txt 的优势在于提供可靠、静态的上下文——这是一种确定性的参考，能够降低动态 AI 集成有时带来的不确定性。我们正在密切关注用户需求，以判断未来是否可以通过服务器端方式提供价值。

我们欢迎社区对这些潜在方向提出宝贵意见！

---

常见问题 (FAQ) ❓

问：生成 llm-min.txt 文件是否需要具备推理能力的模型？ 🧠

答：是的，生成 llm-min.txt 文件需要像 Gemini 这样具有强大推理能力的模型。这一过程涉及复杂的信息提取、实体关系映射以及结构化知识表示。不过，一旦生成，llm-min.txt 文件就可以被任何具备良好编码能力的模型（例如 Claude 3.5 Sonnet）有效使用，以回答与特定库相关的问题。

问：llm-min.txt 是否保留了原始文档中的所有信息？ 📚

答：不是。llm-min.txt 明确设计为一种有损压缩格式。它优先保留与编程相关的细节（类、方法、参数、返回类型、核心使用模式），而有意省略说明性文字、概念讨论及次要信息。正是这种有选择性的信息保留，才使得令牌数量大幅减少，同时仍能维持 AI 助手所需的基本技术参考信息。

问：为什么生成 llm-min.txt 文件需要花费时间？ ⏱️

答：创建 llm-min.txt 文件涉及一个复杂的多阶段 AI 流程：

1. 收集并预处理文档；
2. 分析每个代码块以识别实体（生成术语表）；
3. 整合各代码块中的实体；
4. 从每个代码块中提取详细定义和交互信息；
5. 生成具有代表性的使用模式。

这一密集型过程可能需要数分钟，尤其是对于大型库而言。然而，一旦生成，生成的 llm-min.txt 文件可以无限期重复使用，为 AI 助手提供更快捷的参考信息。

问：我收到了“Gemini 生成因 MAX_TOKENS 限制而停止”的错误提示，该怎么办？ 🛑

答：此错误表明 Gemini 模型在处理特别密集或复杂的文档代码块时达到了其输出限制。您可以尝试减小 --chunk-size 参数值（例如从 600,000 字符降至 300,000 字符），以便让模型每次处理较小的批次。虽然这可能会因更多独立调用而导致 API 费用略有增加，但通常可以解决令牌限制错误。

问：生成一个 llm-min.txt 文件的典型费用是多少？ 💰

答：处理成本因文档大小和复杂度而异，但对于中等规模的库，预计 Gemini API 的费用将在 0.01 至 1.00 美元 之间。影响成本的主要因素包括：

• 文档总大小；
• 处理的代码块数量；
• 库结构的复杂程度；
• 所选的 Gemini 模型。

有关当前定价详情，请参阅 Google Cloud AI 定价页面。

问：我能否在没有互联网连接的情况下处理本地文档文件？ 📁

答：可以！--input-folder 选项非常适合离线处理。使用此选项时，llm-min 将：

• 完全跳过网络爬取（无需互联网即可收集内容）；
• 仅在压缩过程中需要访问互联网以调用 Gemini API；
• 递归支持任意目录结构中的 .md、.txt 和 .rst 文件；
• 可用于处理内部或专有文档，这些文档并未公开发布在网上。

这使其成为处理私有文档、本地开发文档，或在互联网连接受限情况下工作的理想选择。

问：你是用代码来完成这个项目的吗？ 🤖

答：是的，当然。该项目是使用 Roocode 并结合名为 Rooroo 的自定义配置开发的。

---

想帮忙吗？贡献力量 🤝

我们欢迎各位为使 llm-min 更加完善而做出贡献！🎉

无论您是报告 bug、提出功能建议，还是通过拉取请求提交代码更改，您的参与都将帮助改进这款工具，造福所有人。请查看我们的 GitHub 仓库，了解贡献指南和当前的开放问题。

---

许可证 📜

本项目采用 MIT 许可证授权。完整详情请参阅 LICENSE 文件。

llm-min.txt 快速上手指南

llm-min.txt 是一个专为大语言模型（LLM）设计的文档压缩工具。它受 min.js 启发，利用 AI 将庞大的技术文档蒸馏为高度结构化、机器优化的 SKF (Structured Knowledge Format) 格式。相比原始文档，它能减少 90%-95% 的 Token 消耗，同时保留核心知识，显著提升 AI 编程助手对最新库的理解和代码生成准确率。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: Python 3.10 或更高版本
• API 密钥: 需要拥有 Google Gemini API Key（用于驱动文档压缩过程）
  • 获取地址：Google AI Studio 或 Google Cloud Console
• 浏览器自动化依赖: 需要安装 Playwright 以支持部分抓取功能

安装步骤

推荐普通用户直接使用 pip 安装，开发者可选择源码安装。

方式一：常规安装（推荐）

# 安装主程序
pip install llm-min

# 安装必要的浏览器自动化驱动
playwright install

国内加速提示：如果 pip 下载缓慢，建议使用国内镜像源：

pip install llm-min -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：开发者安装（源码模式）

如果你需要贡献代码或修改内部逻辑：

# 克隆仓库（假设已 git clone）
cd llm-min

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows 用户请使用: .venv\Scripts\activate

# 使用 UV 工具同步依赖（比 pip 更快）
uv sync
uv pip install -e .

# 可选：安装预提交钩子
# uv pip install pre-commit
# pre-commit install

基本使用

1. 配置 API 密钥

llm-min 依赖 Google Gemini AI 进行文档蒸馏。你可以通过环境变量或命令行参数提供密钥。

推荐方式：设置环境变量

• Linux / macOS:

  export GEMINI_API_KEY=your_api_key_here
  

• Windows (CMD):

  set GEMINI_API_KEY=your_api_key_here
  

• Windows (PowerShell):

  $env:GEMINI_API_KEY="your_api_key_here"
  

替代方式：命令行直接传入 在执行命令时添加 --gemini-api-key your_api_key_here。

2. 生成压缩文档

配置好密钥后，即可运行工具生成 llm-min.txt 文件。工具支持多种输入源（如 URL、本地路径等）。

最简示例：

假设你要为某个库的文档网址生成压缩文件：

llm-min --url "https://example-lib-docs.com" --output ./output_dir

执行成功后，输出目录中将包含：

• llm-min.txt: 高度压缩的 SKF 格式知识库（通常仅约 10,000 tokens）。
• llm-min-guideline.md: 格式解码指南，辅助 AI 理解 SKF 结构。

3. 在 AI 助手中使用

将生成的 llm-min.txt 和 llm-min-guideline.md 文件作为上下文提供给你的 AI 编程助手（如 Cursor, GitHub Copilot, VS Code + LLM 插件等）。

• 操作方法：在对话中引用这两个文件，或直接将其放入项目的 .cursorrules 或类似配置目录中。
• 效果：AI 将立即掌握该库的最新用法、类定义和交互模式，从而生成更准确的代码，即使该库超出了 AI 模型的原始训练截止日期。