tldr-code

TLDR-Code：完整参考

高效利用 Token 进行代码分析。相比直接读取原始文件，节省 95%。

快速参考

任务	命令
文件树	tldr tree src/
代码结构	tldr structure . --lang python
搜索代码	tldr search "pattern" .
调用图	tldr calls src/
谁调用 X？	tldr impact func_name .
控制流	tldr cfg file.py func
数据流	tldr dfg file.py func
程序切片	tldr slice file.py func 42
死代码	tldr dead src/
架构	tldr arch src/
导入	tldr imports file.py
谁导入 X？	tldr importers module_name .
受影响的测试	tldr change-impact --git
类型检查	tldr diagnostics file.py
语义搜索	tldr semantic search "auth flow"

---

五层栈

Layer 1: AST         ~500 tokens   Function signatures, imports
Layer 2: Call Graph  +440 tokens   What calls what (cross-file)
Layer 3: CFG         +110 tokens   Complexity, branches, loops
Layer 4: DFG         +130 tokens   Variable definitions/uses
Layer 5: PDG         +150 tokens   Dependencies, slicing
───────────────────────────────────────────────────────────────
Total:              ~1,200 tokens  vs 23,000 raw = 95% savings

---

CLI 命令

导航

# File tree
tldr tree [path]
tldr tree src/ --ext .py .ts        # Filter extensions
tldr tree . --show-hidden           # Include hidden files

# Code structure (codemaps)
tldr structure [path] --lang python
tldr structure src/ --max 100       # Max files to analyze

搜索

# Text search
tldr search <pattern> [path]
tldr search "def process" src/
tldr search "class.*Error" . --ext .py
tldr search "TODO" . -C 3           # 3 lines context
tldr search "func" . --max 50       # Limit results

# Semantic search (natural language)
tldr semantic search "authentication flow"
tldr semantic search "error handling" --k 10
tldr semantic search "database queries" --expand  # Include call graph

文件分析

# Full file info
tldr extract <file>
tldr extract src/api.py
tldr extract src/api.py --class UserService      # Filter to class
tldr extract src/api.py --function process       # Filter to function
tldr extract src/api.py --method UserService.get # Filter to method

# Relevant context (follows call graph)
tldr context <entry> --project <path>
tldr context main --project src/ --depth 3
tldr context UserService.create --project . --lang typescript

流程分析

# Control flow graph (complexity)
tldr cfg <file> <function>
tldr cfg src/processor.py process_data
# Returns: cyclomatic complexity, blocks, branches, loops

# Data flow graph (variable tracking)
tldr dfg <file> <function>
tldr dfg src/processor.py process_data
# Returns: where variables are defined, read, modified

# Program slice (what affects line X)
tldr slice <file> <function> <line>
tldr slice src/processor.py process_data 42
tldr slice src/processor.py process_data 42 --direction forward
tldr slice src/processor.py process_data 42 --var result

代码库分析

# Build cross-file call graph
tldr calls [path]
tldr calls src/ --lang python

# Reverse call graph (who calls this function?)
tldr impact <func> [path]
tldr impact process_data src/ --depth 5
tldr impact authenticate . --file auth  # Filter by file

# Find dead/unreachable code
tldr dead [path]
tldr dead src/ --entry main cli test_  # Specify entry points
tldr dead . --lang typescript

# Detect architectural layers
tldr arch [path]
tldr arch src/ --lang python
# Returns: entry layer, middle layer, leaf layer, circular deps

导入分析

# Parse imports from file
tldr imports <file>
tldr imports src/api.py
tldr imports src/api.ts --lang typescript

# Reverse import lookup (who imports this module?)
tldr importers <module> [path]
tldr importers datetime src/
tldr importers UserService . --lang typescript

质量与测试

# Type check + lint
tldr diagnostics <file|path>
tldr diagnostics src/api.py
tldr diagnostics . --project              # Whole project
tldr diagnostics src/ --no-lint           # Type check only
tldr diagnostics src/ --format text       # Human-readable

# Find affected tests
tldr change-impact [files...]
tldr change-impact                        # Auto-detect (session/git)
tldr change-impact src/api.py             # Explicit files
tldr change-impact --session              # Session-modified files
tldr change-impact --git                  # Git diff files
tldr change-impact --git --git-base main  # Diff against branch
tldr change-impact --run                  # Actually run affected tests

缓存

# Pre-build call graph cache
tldr warm <path>
tldr warm src/ --lang python
tldr warm . --background                  # Build in background

# Build semantic index (one-time)
tldr semantic index [path]
tldr semantic index . --lang python
tldr semantic index . --model all-MiniLM-L6-v2  # Smaller model (80MB)

---

守护进程（加快查询）

守护进程将索引保存在内存中，以便快速响应重复查询。

守护进程命令

# Start daemon (backgrounds automatically)
tldr daemon start
tldr daemon start --project /path/to/project

# Check status
tldr daemon status

# Stop daemon
tldr daemon stop

# Send raw command
tldr daemon query ping
tldr daemon query status

# Notify file change (for hooks)
tldr daemon notify <file>
tldr daemon notify src/api.py

守护进程功能

功能	描述
自动关闭	空闲 30 分钟后关闭
查询缓存	SalsaDB 记忆化
内容哈希	跳过未更改的文件
脏数据跟踪	增量重新索引
跨平台	Unix 套接字 / Windows TCP

守护进程套接字协议

向套接字发送 JSON，接收 JSON 响应：

// Request
{"cmd": "search", "pattern": "process", "max_results": 10}

// Response
{"status": "ok", "results": [...]}

全部 22 个守护进程命令：

ping, status, shutdown, search, extract, impact, dead, arch,
cfg, dfg, slice, calls, warm, semantic, tree, structure,
context, imports, importers, notify, diagnostics, change_impact

---

语义搜索（P6）

使用嵌入向量进行自然语言代码搜索。

设置

# Build index (downloads model on first run)
tldr semantic index .

# Default model: bge-large-en-v1.5 (1.3GB, best quality)
# Smaller model: all-MiniLM-L6-v2 (80MB, faster)
tldr semantic index . --model all-MiniLM-L6-v2

搜索

tldr semantic search "authentication flow"
tldr semantic search "error handling patterns" --k 10
tldr semantic search "database connection" --expand  # Follow call graph

配置

在 .claude/settings.json 中：

{
  "semantic_search": {
    "enabled": true,
    "auto_reindex_threshold": 20,
    "model": "bge-large-en-v1.5"
  }
}

---

支持的语言

语言	AST	调用图	CFG	DFG	PDG
Python	是	是	是	是	是
TypeScript	是	是	是	是	是
JavaScript	是	是	是	是	是
Go	是	是	是	是	是
Rust	是	是	是	是	是
Java	是	是	-	-	-
C/C++	是	是	-	-	-
Ruby	是	-	-	-	-
PHP	是	-	-	-	-
Kotlin	是	-	-	-	-
Swift	是	-	-	-	-
C#	是	-	-	-	-
Scala	是	-	-	-	-
Lua	是	-	-	-	-
Elixir	是	-	-	-	-

---

忽略模式

TLDR 遵循 .tldrignore（gitignore 语法）：

# .tldrignore
.venv/
__pycache__/
node_modules/
*.min.js
dist/

首次运行时会创建包含合理默认值的 .tldrignore。 使用 --no-ignore 可忽略该文件。

---

何时使用 TLDR 与其他工具

任务	使用 TLDR	使用 Grep
查找函数定义	tldr extract file --function X	-
搜索代码模式	tldr search "pattern"	-
搜索字符串字面量	-	grep "literal"
配置值	-	grep "KEY="
跨文件调用	tldr calls	-
反向依赖	tldr impact func	-
复杂度分析	tldr cfg file func	-
变量跟踪	tldr dfg file func	-
自然语言查询	tldr semantic search	-

---

Python API

from tldr.api import (
    # L1: AST
    extract_file, extract_functions, get_imports,
    # L2: Call Graph
    build_project_call_graph, get_intra_file_calls,
    # L3: CFG
    get_cfg_context,
    # L4: DFG
    get_dfg_context,
    # L5: PDG
    get_slice, get_pdg_context,
    # Unified
    get_relevant_context,
    # Analysis
    analyze_dead_code, analyze_architecture, analyze_impact,
)

# Example: Get context for LLM
ctx = get_relevant_context("src/", "main", depth=2, language="python")
print(ctx.to_llm_string())

---

修复 Bug 工作流（导航 + 阅读）

关键要点： TLDR 用于导航，然后你再阅读。不要只凭摘要尝试修复 Bug。

模式

# 1. NAVIGATE: Find which files matter
tldr imports file.py              # What does buggy file depend on?
tldr impact func_name .           # Who calls the buggy function?
tldr calls .                      # Cross-file edges (follow 2-hop for models)

# 2. READ: Get actual code for critical files (2-4 files, not all 50)
# Use Read tool or tldr search -C for code with context
tldr search "def buggy_func" . -C 20

这样做的原因

对于跨文件 Bug（例如字段名称错误、类型不匹配），你需要查看：

• 存在 Bug 的文件（处理程序访问 task.user_id）
• 定义契约的文件（模型定义 owner_id）

TLDR 会找出相关文件，然后你再阅读这些文件。

获取更多上下文

如果 TLDR 的输出不够：

• tldr search "pattern" . -C 20 - 获取带 20 行上下文的实际代码
• tldr imports file.py - 查看文件依赖项
• 如果需要完整实现，请直接阅读文件

Token 节省效果的证据

Raw file read:    23,314 tokens
TLDR all layers:   1,189 tokens
─────────────────────────────────
Savings:              95%

核心思路：调用图帮助定位相关代码，然后通过分层提供结构化摘要。你无需阅读无关代码。