TLDR：面向 AI 代理的代码分析

为大语言模型提供它们真正需要的代码，不多也不少。

# 一行命令：安装、索引、搜索
pip install llm-tldr && tldr warm . && tldr semantic "你想要查找的内容" .

你的代码库有 10 万行。Claude 的上下文窗口是 20 万 token。原始代码根本放不下——即使放得下，大语言模型也会被无关细节淹没。

TLDR 不会直接输出文本，而是提取代码的结构。结果是：在保留理解与正确编辑代码所需信息的同时，token 数量减少了 95%。

pip install llm-tldr
tldr warm .                    # 索引你的项目
tldr context main --project .  # 获取适合大语言模型的摘要

---

工作原理

TLDR 构建了 5 层分析，每一层回答不同的问题：

┌─────────────────────────────────────────────────────────────┐
│ 第 5 层：程序依赖关系 → “第 42 行受哪些内容影响？”      │
│ 第 4 层：数据流           → “这个值会流向哪里？”          │
│ 第 3 层：控制流        → “这段代码有多复杂？”             │
│ 第 2 层：调用图          → “哪些地方会调用这个函数？”     │
│ 第 1 层：抽象语法树     → “有哪些函数存在？”              │
└─────────────────────────────────────────────────────────────┘

为什么采用多层设计？ 不同的任务需要不同深度的信息：

• 浏览代码？只需第 1 层（结构）。
• 重构？第 2 层（调用图）能显示哪些部分会受到影响。
• 调试空指针问题？第 5 层（切片）只展示相关代码行。

守护进程将索引常驻内存，实现100 毫秒级查询，而无需每次通过 CLI 启动耗时 30 秒的进程。

架构

┌──────────────────────────────────────────────────────────────────┐
│                         你的代码                                │
│  src/*.py, lib/*.ts, pkg/*.go                                    │
└───────────────────────────┬──────────────────────────────────────┘
                            │ tree-sitter
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│                     5 层分析                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐     │
│  │   AST   │→│  Calls  │→│   CFG   │→│   DFG   │→│   PDG   │     │
│  │   L1    │ │   L2    │ │   L3    │ │   L4    │ │   L5    │     │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘     │
└───────────────────────────┬──────────────────────────────────────┘
                            │ bge-large-en-v1.5
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│                    语义索引                                │
│  1024 维嵌入存储于 FAISS 中 → “查找 JWT 验证”                  │
└───────────────────────────┬──────────────────────────────────────┘
                            │
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│                       守护进程                                     │
│  内存中索引  •  100 毫秒查询  •  自动生命周期管理          │
└──────────────────────────────────────────────────────────────────┘

语义层：按行为搜索

真正的强大之处在于将所有 5 层结合成可搜索的嵌入。

每个函数都会被索引以下内容：

• 函数签名 + 文档字符串（L1）
• 它调用了什么以及谁调用了它（L2）
• 复杂度指标（L3）
• 数据流模式（L4）
• 依赖关系（L5）
• 实际代码的前 10 行左右

这些信息会被使用 bge-large-en-v1.5 编码为 1024 维向量。结果是：可以根据代码的行为进行搜索，而不仅仅是它的文字描述。

# “验证 JWT” 会找到 verify_access_token()，即使代码中没有完全匹配的文字
tldr semantic "验证 JWT 令牌并检查过期时间" .

为何有效？ 传统搜索只会根据变量名和注释找到“authentication”。而语义搜索则能理解 verify_access_token() 确实 执行了 JWT 验证，因为调用图和数据流揭示了它的实际用途。

设置语义搜索

# 构建语义索引（一次性操作，典型项目约需 2 分钟）
tldr warm /path/to/project

# 按行为搜索
tldr semantic "数据库连接池" .

嵌入所需的依赖项（sentence-transformers、faiss-cpu）已包含在 pip install llm-tldr 中。索引会缓存在 .tldr/cache/semantic.faiss 文件中。

保持索引最新

守护进程会跟踪脏文件，并在发生 20 次更改后自动重建索引，但你需要在文件变更时通知它：

# 通知守护进程文件已更改
tldr daemon notify src/auth.py --project .

集成方式：

1. Git 钩子（提交后）：

   git diff --name-only HEAD~1 | xargs -I{} tldr daemon notify {} --project .
   

2. 编辑器钩子（保存时）：

   tldr daemon notify "$FILE" --project .
   

3. 手动重建（必要时）：

   tldr warm .  # 完整重建
   

守护进程会在脏文件数量达到默认阈值（20 个）后，在后台自动重建语义嵌入。

---

工作流程

阅读代码之前

tldr tree src/                      # 查看文件结构
tldr structure src/ --lang python   # 查看函数和类

编辑代码之前

tldr extract src/auth.py            # 完整文件分析
tldr context login --project .      # 适合大语言模型的摘要（节省 95% token）

重构之前

tldr impact login .                 # 哪些地方会调用此函数？（反向调用图）
tldr change-impact                  # 需要运行哪些测试？

调试

tldr slice src/auth.py login 42     # 第 42 行受哪些内容影响？
tldr dfg src/auth.py login          # 追踪数据流

按行为查找代码

tldr semantic "验证 JWT 令牌" .   # 自然语言搜索

---

快速设置

1. 安装

pip install llm-tldr

2. 索引你的项目

tldr warm /path/to/project

这会构建所有分析层并启动守护进程。对于典型项目，耗时 30–60 秒，之后查询即可立即响应。

3. 开始使用

tldr context main --project .   # 获取某个函数的上下文
tldr impact helper_func .       # 查看谁调用了它
tldr semantic "错误处理"  # 按行为查找

---

真实案例：为什么这很重要

场景： 调试为什么第42行的user是空值。

不使用TLDR：

1. 阅读这个150行的函数
2. 手动跟踪每个变量
3. 因为bug隐藏在控制流中而错过它

使用TLDR：

tldr slice src/auth.py login 42

输出： 只有6行代码影响到第42行：

3:   user = db.get_user(username)
7:   if user is None:
12:      raise NotFound
28:  token = create_token(user)  # ← BUG：跳过了空值检查
35:  session.token = token
42:  return session

bug很明显。第28行直接使用了user，却没有经过空值检查的逻辑分支。

---

命令参考

探索

命令	功能
tldr tree [path]	文件树
tldr structure [path] --lang <lang>	函数、类、方法
tldr search <pattern> [path]	文本模式搜索
tldr extract <file>	整个文件分析

分析

命令	功能
tldr context <func> --project <path>	LLM友好的摘要（节省95%）
tldr cfg <file> <function>	控制流图
tldr dfg <file> <function>	数据流图
tldr slice <file> <func> <line>	程序切片

跨文件

命令	功能
tldr calls [path]	构建调用图
tldr impact <func> [path]	查找所有调用者（反向调用图）
tldr dead [path]	查找不可达代码
tldr arch [path]	检测架构层
tldr imports <file>	解析导入
tldr importers <module> [path]	查找导入某个模块的文件

语义

命令	功能
tldr warm <path>	构建所有索引（包括嵌入）
tldr semantic <query> [path]	自然语言代码搜索

诊断

命令	功能
tldr diagnostics <file>	类型检查 + 静态分析
tldr change-impact [files]	查找受更改影响的测试
tldr doctor	检查/安装诊断工具

守护进程

命令	功能
tldr daemon start	启动后台守护进程
tldr daemon stop	停止守护进程
tldr daemon status	检查状态

---

支持的语言

Python、TypeScript、JavaScript、Go、Rust、Java、C、C++、Ruby、PHP、C#、Kotlin、Scala、Swift、Lua、Elixir

语言会自动检测，也可以通过--lang指定。

---

MCP集成

适用于AI工具（Claude Desktop、Claude Code）：

Claude Desktop - 添加到~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "/path/to/your/project"]
    }
  }
}

Claude Code - 添加到.claude/settings.json：

{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    }
  }
}

---

配置

.tldrignore - 排除文件

TLDR会尊重.tldrignore（gitignore语法），用于所有命令，包括tree、structure、search、calls以及语义索引：

# 自动创建并带有合理默认值
tldr warm .  # 如果不存在，则创建.tldrignore

默认排除：

• node_modules/、.venv/、__pycache__/
• dist/、build/、*.egg-info/
• 二进制文件（*.so、*.dll、*.whl）
• 安全文件（.env、*.pem、*.key）

自定义可通过编辑.tldrignore实现：

# 添加你的模式
large_test_fixtures/
vendor/
data/*.csv

CLI标志：

# 从命令行添加模式（可重复）
tldr --ignore "packages/old/" --ignore "*.generated.ts" tree .

# 忽略所有忽略规则
tldr --no-ignore tree .

设置 - 守护进程行为

创建.tldr/config.json以配置守护进程设置：

{
  "semantic": {
    "enabled": true,
    "auto_reindex_threshold": 20
  }
}

设置	默认值	描述
enabled	true	启用语义搜索
auto_reindex_threshold	20	更改文件数达到阈值后自动重建索引

单体仓库支持

对于单体仓库，创建.claude/workspace.json以限定索引范围：

{
  "active_packages": ["packages/core", "packages/api"],
  "exclude_patterns": ["**/fixtures/**"]
}

---

性能

指标	原始代码	TLDR	提升
函数上下文的token数	21,000	175	99%节省
代码库概览的token数	104,000	12,000	89%节省
查询延迟（守护进程）	30秒	100毫秒	快300倍

---

深度解析

如需完整的架构说明、基准测试及高级工作流程：

完整文档

---

许可证

AGPL-3.0 - 详见LICENSE文件。

llm-tldr 快速上手指南

llm-tldr 是一款专为 AI Agent 设计的代码分析工具。它能提取代码的深层结构（如调用图、数据流），而非简单堆砌文本，从而在保留关键上下文的同时，将 Token 消耗降低 95%，让大模型更精准地理解你的代码库。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.8 及以上
• 前置依赖：无需额外安装系统级依赖，工具会自动处理 tree-sitter 解析器及语义嵌入模型（sentence-transformers, faiss-cpu）。

国内加速建议： 建议配置国内 PyPI 镜像源以提升安装速度：

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

安装步骤

使用 pip 一键安装：

pip install llm-tldr

基本使用

1. 初始化索引 (Warm Up)

首次使用前，需对项目建立索引。这会构建 5 层分析结构并启动后台守护进程（Daemon），实现毫秒级查询。

# 对当前目录项目进行索引（典型项目耗时约 30-60 秒）
tldr warm .

2. 获取 LLM 友好的代码摘要

不再需要粘贴整个文件。使用 context 命令获取经过压缩的结构化摘要，直接喂给大模型。

# 获取 main 函数的精简上下文（节省约 95% Token）
tldr context main --project .

3. 语义搜索 (按行为查找代码)

通过自然语言描述代码功能进行搜索，即使函数名或注释中不包含关键词也能找到。

# 查找“验证 JWT 令牌”相关的代码逻辑
tldr semantic "validate JWT tokens" .

4. 其他常用场景

• 查看项目结构：

  tldr tree src/
  

• 分析函数调用影响（重构前必用）：

  # 查看谁调用了 login 函数
  tldr impact login .
  

• 调试定位（程序切片）：

  # 找出影响 src/auth.py 中 login 函数第 42 行的所有相关代码行
  tldr slice src/auth.py login 42
  

5. 保持索引更新

当文件发生修改时，通知后台守护进程更新索引（也可配置 Git Hook 自动执行）：

tldr daemon notify src/auth.py --project .