Show HN: Min.js style compression of tech docs for LLM context

Source | HN Comments

该项目旨在通过类似 `min.js` 的方式压缩技术文档，以优化 LLM 的上下文。它使用 Gemini AI 将文档提炼成高度结构化的摘要，生成 `llm-min.txt` 文件，该文件采用机器优化的 Structured Knowledge Format (SKF)，包含 DEFINITIONS、INTERACTIONS 和 USAGE_PATTERNS 三个部分。项目提供命令行工具和 Python 库，支持从包、URL 或本地文件生成压缩文档，并生成配套的 `llm-min-guideline.md` 文件，用于 AI 解释 SKF 格式。压缩后的文档 token 数量通常减少 90-95% 以上，从而提高 AI 工具处理效率。

Show HN：用于 LLM 上下文的 Tech Docs 的 Min.js 风格压缩

Navigation Menu (已移除)

marv1nnnnn / **llm-min.txt ** Public

Notifications You must be signed in to change notification settings
Fork 1
Star 125

用于 LLM 上下文的 Tech Docs 的 Min.js 风格压缩

License

MIT license 125 stars 1 fork Branches Tags Activity Star Notifications You must be signed in to change notification settings

Additional navigation options

marv1nnnnn/llm-min.txt

main Branches Tags Go to file Code

Folders and files

Name| Name| Last commit message| Last commit date ---|---|---|---

Latest commit

History

Repository files navigation

llm-min.txt: 用于 LLM 上下文的 Tech Docs 的 Min.js 风格压缩 🤖

📜 Table of Contents

llm-min.txt: 用于 LLM 上下文的 Tech Docs 的 Min.js 风格压缩 🤖

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

如果你使用过 AI 编码助手（例如 GitHub Copilot、Cursor 或其他由大型语言模型 - LLM 提供支持的助手），你可能遇到过它们不了解编程库最新更新的情况。这种知识差距的存在是因为 AI 模型有一个“知识截止点”——超过这个点，它们就没有学习到新的信息。由于软件发展迅速，这种限制可能导致过时的推荐和损坏的代码。

已经出现了几种创新的方法来应对这一挑战：

llms.txt 一个社区驱动的倡议，贡献者创建参考文件 (llms.txt)，其中包含专为 AI 消费而格式化的最新库信息。
Context7 一种动态地向 AI 提供上下文信息的服务，通常通过智能地总结文档来实现。

虽然这些解决方案很有价值，但它们面临着某些限制：

llms.txt 文件可能变得非常大——有些超过 800,000 个 tokens（单词片段）。这种大小可能会压倒许多 AI 系统的上下文窗口。许多较短的 llms.txt 变体仅包含指向官方文档的链接，要求 AI 单独获取和处理这些文档。即使是综合版本（llms-full.txt）也常常超过大多数 AI 助手一次可以处理的内容。此外，这些文件可能并不总是反映绝对最新的文档。
Context7 的运作方式有点像一个“黑盒子”——虽然有用，但其精确的信息选择方法对用户来说并不完全透明。它主要与 GitHub 代码存储库或现有的 llms.txt 文件一起使用，而不是任何任意的软件包。

llm-min.txt 提供了一种全新的方法：

受到 Web 开发中 min.js 文件（删除了不必要元素的 JavaScript）的启发，llm-min.txt 采用类似的理念用于技术文档。我们没有向 AI 提供大量冗长的手册，而是利用另一个 AI 将该文档提炼成超级浓缩、高度结构化的摘要。生成的 llm-min.txt 文件仅捕获理解库用法所需的最基本信息，并以针对 AI 助手而非人类读者优化的格式打包。

现代 AI 推理能力擅长这种提炼过程，创造出非常有效的知识表示，以最小的 token 消耗提供最大的价值。

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

llm-min.txt 文件使用 Structured Knowledge Format (SKF)——一种紧凑的、为高效 AI 解析而设计的机器优化格式，而不是人类可读性。这种格式将技术信息组织成具有精确关系的、截然不同的高度结构化部分。

SKF 格式的关键要素：

Header Metadata： 每个文件都以必要的上下文信息开头：
- # IntegratedKnowledgeManifest_SKF：格式标识符和版本
- # SourceDocs: [...]：原始文档来源
- # GenerationTimestamp: ...：创建时间戳
- # PrimaryNamespace: ...：顶级包/命名空间，对于理解导入路径至关重要
Three Core Structured Sections： 内容被组织成不同的功能类别：
- # SECTION: DEFINITIONS (Prefix: D)：描述库的静态方面：
  - 具有唯一全局 ID 的规范组件定义（例如，D001:G001_MyClass）
  - 相对于 PrimaryNamespace 的命名空间路径
  - 带有参数和返回类型的方法签名
  - 带有类型和访问修饰符的属性/字段
  - 静态关系，如继承或接口实现
  - 重要说明： 此部分有效地充当文件的词汇表，因为传统词汇表（G 部分）在生成期间使用，但为了节省空间而故意从最终输出中省略。
- # SECTION: INTERACTIONS (Prefix: I)：捕获库中的动态行为：
  - 方法调用 (INVOKES)
  - 组件使用模式 (USES_COMPONENT)
  - 事件产生/消费
  - 错误引发和处理逻辑，并引用特定错误类型
- # SECTION: USAGE_PATTERNS (Prefix: U)：提供具体的用法示例：
  - 核心功能的常见工作流程
  - 涉及对象创建、配置、方法调用和错误处理的逐步序列
  - 每个模式都有一个描述性名称（例如，U_BasicCrawl），并带有编号的步骤（U_BasicCrawl.1、U_BasicCrawl.2）
Line-Based Structure： 每个项目都按照精确的格式约定出现在其自己的行上，从而实现可靠的机器解析。

SKF 格式示例（简化）：

# IntegratedKnowledgeManifest_SKF/1.4 LA
# SourceDocs: [example-lib-docs]
# GenerationTimestamp: 2024-05-28T12:00:00Z
# PrimaryNamespace: example_lib
# SECTION: DEFINITIONS (Prefix: D)
# Format_PrimaryDef: Dxxx:Gxxx_Entity [DEF_TYP] [NAMESPACE "relative.path"] [OPERATIONS {op1:RetT(p1N:p1T)}] [ATTRIBUTES {attr1:AttrT1}] ("Note")
# ---
D001:G001_Greeter [CompDef] [NAMESPACE "."] [OPERATIONS {greet:Str(name:Str)}] ("A simple greeter class")
D002:G002_AppConfig [CompDef] [NAMESPACE "config"] [ATTRIBUTES {debug_mode:Bool("RO")}] ("Application configuration")
# ---
# SECTION: INTERACTIONS (Prefix: I)
# Format: Ixxx:Source_Ref INT_VERB Target_Ref_Or_Literal ("Note_Conditions_Error(Gxxx_ErrorType)")
# ---
I001:G001_Greeter.greet INVOKES G003_Logger.log ("Logs greeting activity")
# ---
# SECTION: USAGE_PATTERNS (Prefix: U)
# Format: U_Name:PatternTitleKeyword
#     U_Name.N:[Actor_Or_Ref] ACTION_KEYWORD (Target_Or_Data_Involving_Ref) -> [Result_Or_State_Change_Involving_Ref]
# ---
U_BasicGreeting:Basic User Greeting
U_BasicGreeting.1:[User] CREATE (G001_Greeter) -> [greeter_instance]
U_BasicGreeting.2:[greeter_instance] INVOKE (greet name='Alice') -> [greeting_message]
# ---
# END_OF_MANIFEST

llm-min-guideline.md 文件（与 llm-min.txt 一起生成）提供了详细的解码说明和模式定义，使 AI 能够正确解释 SKF 格式。它充当必不可少的配套文档，解释了文件中使用的符号、字段含义和关系类型。

Does it Really Work? Visualizing the Impact

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 个 tokens——完全在现代 AI 助手的处理能力范围内。

如何使用它？

只需在 AI 驱动的 IDE 的对话中引用这些文件，并观察你的助手立即获得有关该库的详细知识：

它的表现如何？

It's necessary to make a benchmark but incredibly hard. LLM code generation is stochastic and the quality of the generated code depends on many factors. crawl4ai / google-genai / svelte are all packages current LLM failed to generate correct code for. Using `llm-min` will largely improve the success rate of code generation.

Quick Start 🚀

llm-min 的入门非常简单：

1. Installation：

For regular users (recommended)：

pip install llm-min
# Install required browser automation tools
playwright install

For contributors and developers：

# Clone the repository (if not already done)
# git clone https://github.com/your-repo/llm-min.git
# cd llm-min
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies with UV (faster than pip)
uv sync
uv pip install -e .
# Optional: Set up pre-commit hooks for code quality
# uv pip install pre-commit
# pre-commit install

2. Set Up Your Gemini API Key： 🔑

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

Best practice： 设置一个名为 GEMINI_API_KEY 的环境变量，其中包含你的密钥值：

# Linux/macOS
export GEMINI_API_KEY=your_api_key_here
# Windows (Command Prompt)
set GEMINI_API_KEY=your_api_key_here
# Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key_here"

Alternative： 通过 --gemini-api-key 命令行选项直接提供你的密钥。

你可以从 Google AI Studio 或 Google Cloud Console 获取 Gemini API 密钥。

3. Generate Your First llm-min.txt File： 💻

选择以下输入源之一：

Option | Short | Type | What it does ---|---|---|--- --output-dir | -o | DIRECTORY | Where to save the generated files (default is a folder named llm_min_docs). --output-name | -n | TEXT | Give a custom name for the subfolder inside output-dir. --max-crawl-pages | -p | INTEGER | Max web pages to read (default: 200; 0 means no limit). --max-crawl-depth | -D | INTEGER | How many links deep to follow on a website (default: 3). --chunk-size | -c | INTEGER | How much text to give the AI at once (default: 600,000 characters). --gemini-api-key | -k | TEXT | Your Gemini API Key (if not set as an environment variable). --gemini-model | -m | TEXT | Which Gemini model to use (default: gemini-2.5-flash-preview-04-17). --verbose | -v | Show more detailed messages while it's working.

Key Command-Line Options：

Process the Python package typer，读取最多 50 个网页，并保存到名为 my_docs 的文件夹：

llm-min -pkg "typer" -o my_docs -p 50 --gemini-api-key YOUR_API_KEY_HERE

Example Commands：

# Process the "typer" package, save to "my_docs" folder
llm-min -pkg "typer" -o my_docs -p 50
# Process the FastAPI documentation website
llm-min -u "https://fastapi.tiangolo.com/" -o my_docs -p 50
# Process documentation files in a local folder
llm-min -i "./docs" -o my_docs

4. Programmatic Usage in Python： 🐍

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

from llm_min import LLMMinGenerator
import os

# Configuration for the AI processing
llm_config = {
  "api_key": os.environ.get("GEMINI_API_KEY"), # Use environment variable
  "model_name": "gemini-2.5-flash-preview-04-17", # Recommended model
  "chunk_size": 600000, # Characters per AI processing batch
  "max_crawl_pages": 200, # Maximum pages to crawl
  "max_crawl_depth": 3, # Link following depth
}

# Initialize the generator (output files will go to ./my_output_docs/[package_name]/)
generator = LLMMinGenerator(output_dir="./my_output_docs", llm_config=llm_config)

# Generate llm-min.txt for the 'requests' package
try:
  generator.generate_from_package("requests")
  print("✅ Successfully created documentation for 'requests'!")
except Exception as e:
  print(f"❌ Error processing 'requests': {e}")

# Generate llm-min.txt from a documentation URL
try:
  generator.generate_from_url("https://bun.sh/llms-full.txt")
  print("✅ Successfully processed 'https://bun.sh/llms-full.txt'!")
except Exception as e:
  print(f"❌ Error processing URL: {e}")

For a complete list of command-line options, run:

llm-min --help

Output Directory Structure 📂

当 llm-min 完成其处理时，它会创建以下有组织的目录结构：

your_chosen_output_dir/
└── name_of_package_or_website/
    ├── llm-full.txt       # Complete documentation text (original content)
    ├── llm-min.txt       # Compressed SKF/1.4 LA structured summary
    └── llm-min-guideline.md   # Essential format decoder for AI interpretation

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

my_llm_docs/
└── requests/
    ├── llm-full.txt       # Original documentation
    ├── llm-min.txt       # Compressed SKF format (D, I, U sections)
    └── llm-min-guideline.md   # Format decoding instructions

Important： llm-min-guideline.md 文件是 llm-min.txt 的重要补充。它提供了 AI 正确解释结构化数据所需的详细模式定义和格式说明。将 llm-min.txt 与 AI 助手一起使用时，始终包括此指南文件。