需要 token 高效理解、调试、重构代码库时，用…

在大型代码库中搜索、理解调用关系、分析复杂度/数据流/影响面、找死代码和受影响测试时，用 tldr 命令分层分析以节省 token。

适用场景

解决思路

1. 用 5 层栈做 token 高效分析：L1 AST 约 500 tokens 获取函数签名和导入；L2 Call Graph 约 +440 tokens 获取跨文件调用；L3 CFG 约 +110 tokens 获取复杂度、分支、循环；L4 DFG 约 +130 tokens 获取变量定义/使用；L5 PDG 约 +150 tokens 获取依赖和切片；总计约 1,200 tokens，对比原始 23,000 tokens 节省 95%。
2. 查看文件树：`tldr tree src/`。
3. 查看代码结构：`tldr structure . --lang python`。
4. 搜索代码：`tldr search "pattern" .`。
5. 构建调用图：`tldr calls src/`。
6. 查看谁调用 X：`tldr impact func_name .`。
7. 查看控制流：`tldr cfg file.py func`。
8. 查看数据流：`tldr dfg file.py func`。
9. 做程序切片：`tldr slice file.py func 42`。
10. 查找死代码：`tldr dead src/`。
11. 分析架构：`tldr arch src/`。
12. 查看导入：`tldr imports file.py`。
13. 查看谁导入 X：`tldr importers module_name .`。
14. 查找受影响测试：`tldr change-impact --git`。
15. 类型检查：`tldr diagnostics file.py`。
16. 语义搜索：`tldr semantic search "auth flow"`。
17. 导航：`tldr tree [path]`。
18. 导航过滤扩展名：`tldr tree src/ --ext .py .ts`。
19. 导航包含隐藏文件：`tldr tree . --show-hidden`。
20. 代码结构：`tldr structure [path] --lang python`。
21. 代码结构限制最大文件数：`tldr structure src/ --max 100`。
22. 文本搜索：`tldr search <pattern> [path]`。
23. 文本搜索示例：`tldr search "def process" src/`。
24. 文本搜索示例：`tldr search "class.*Error" . --ext .py`。
25. 文本搜索带 3 行上下文：`tldr search "TODO" . -C 3`。
26. 文本搜索限制结果：`tldr search "func" . --max 50`。
27. 语义搜索自然语言：`tldr semantic search "authentication flow"`。
28. 语义搜索限制 k：`tldr semantic search "error handling" --k 10`。
29. 语义搜索包含调用图：`tldr semantic search "database queries" --expand`。
30. 完整文件信息：`tldr extract <file>`。
31. 完整文件信息示例：`tldr extract src/api.py`。
32. 过滤到类：`tldr extract src/api.py --class UserService`。
33. 过滤到函数：`tldr extract src/api.py --function process`。
34. 过滤到方法：`tldr extract src/api.py --method UserService.get`。
35. 相关上下文跟随调用图：`tldr context <entry> --project <path>`。
36. 相关上下文示例：`tldr context main --project src/ --depth 3`。
37. 相关上下文示例：`tldr context UserService.create --project . --lang typescript`。
38. 控制流图：`tldr cfg <file> <function>`。
39. 控制流图示例：`tldr cfg src/processor.py process_data`，返回 cyclomatic complexity、blocks、branches、loops。
40. 数据流图：`tldr dfg <file> <function>`。
41. 数据流图示例：`tldr dfg src/processor.py process_data`，返回变量定义、读取、修改位置。
42. 程序切片：`tldr slice <file> <function> <line>`。
43. 程序切片示例：`tldr slice src/processor.py process_data 42`。
44. 程序切片向前：`tldr slice src/processor.py process_data 42 --direction forward`。
45. 程序切片按变量：`tldr slice src/processor.py process_data 42 --var result`。
46. 构建跨文件调用图：`tldr calls [path]`。
47. 跨文件调用图指定语言：`tldr calls src/ --lang python`。
48. 反向调用图：`tldr impact <func> [path]`。
49. 反向调用图指定深度：`tldr impact process_data src/ --depth 5`。
50. 反向调用图按文件过滤：`tldr impact authenticate . --file auth`。
51. 查找死/不可达代码：`tldr dead [path]`。
52. 死代码指定入口点：`tldr dead src/ --entry main cli test_`。
53. 死代码指定语言：`tldr dead . --lang typescript`。
54. 检测架构层：`tldr arch [path]`。
55. 架构层示例：`tldr arch src/ --lang python`，返回 entry layer、middle layer、leaf layer、circular deps。
56. 解析文件导入：`tldr imports <file>`。
57. 导入示例：`tldr imports src/api.py`。
58. 导入示例指定语言：`tldr imports src/api.ts --lang typescript`。
59. 反向导入查找：`tldr importers <module> [path]`。
60. 反向导入示例：`tldr importers datetime src/`。
61. 反向导入示例：`tldr importers UserService . --lang typescript`。
62. 类型检查 + lint：`tldr diagnostics <file|path>`。
63. 诊断示例：`tldr diagnostics src/api.py`。
64. 诊断整个项目：`tldr diagnostics . --project`。
65. 仅类型检查：`tldr diagnostics src/ --no-lint`。
66. 诊断人类可读格式：`tldr diagnostics src/ --format text`。
67. 查找受影响测试：`tldr change-impact [files...]`。
68. 自动检测变更文件：`tldr change-impact`。
69. 显式指定文件：`tldr change-impact src/api.py`。
70. 使用会话修改文件：`tldr change-impact --session`。
71. 使用 Git diff 文件：`tldr change-impact --git`。
72. 与分支 diff：`tldr change-impact --git --git-base main`。
73. 实际运行受影响测试：`tldr change-impact --run`。
74. 预构建调用图缓存：`tldr warm <path>`。
75. 预构建缓存指定语言：`tldr warm src/ --lang python`。
76. 后台构建缓存：`tldr warm . --background`。
77. 构建语义索引：`tldr semantic index [path]`。
78. 构建语义索引指定语言：`tldr semantic index . --lang python`。
79. 构建语义索引使用小模型：`tldr semantic index . --model all-MiniLM-L6-v2`。
80. 启动 daemon：`tldr daemon start`。
81. 启动 daemon 指定项目：`tldr daemon start --project /path/to/project`。
82. 检查 daemon 状态：`tldr daemon status`。
83. 停止 daemon：`tldr daemon stop`。
84. 发送原始命令：`tldr daemon query ping`。
85. 发送原始命令：`tldr daemon query status`。
86. 通知文件变更：`tldr daemon notify <file>`。
87. 通知文件变更示例：`tldr daemon notify src/api.py`。
88. Daemon 特性：30 分钟空闲自动关闭。
89. Daemon 特性：查询缓存使用 SalsaDB memoization。
90. Daemon 特性：内容哈希跳过未变更文件。
91. Daemon 特性：脏跟踪进行增量重建索引。
92. Daemon 特性：跨平台 Unix sockets / Windows TCP。
93. Daemon socket 协议：向 socket 发送 JSON，接收 JSON 响应；请求如 `{"cmd": "search", "pattern": "process", "max_results": 10}`，响应如 `{"status": "ok", "results": [...]}`。
94. Daemon 全部 22 个命令：ping, status, shutdown, search, extract, impact, dead, arch, cfg, dfg, slice, calls, warm, semantic, tree, structure, context, imports, importers, notify, diagnostics, change_impact。
95. 语义搜索设置：构建索引，首次运行下载模型：`tldr semantic index .`。
96. 语义搜索默认模型：bge-large-en-v1.5（1.3GB，最佳质量）；小模型：all-MiniLM-L6-v2（80MB，更快）：`tldr semantic index . --model all-MiniLM-L6-v2`。
97. 语义搜索配置在 `.claude/settings.json` 中设置 `semantic_search.enabled` 为 true、`auto_reindex_threshold` 为 20、`model` 为 `bge-large-en-v1.5`。
98. 按语言能力选择分析层：Python/TypeScript/JavaScript/Go/Rust 支持 AST、Call Graph、CFG、DFG、PDG。
99. Java/C/C++ 支持 AST、Call Graph，不支持 CFG、DFG、PDG。
100. Ruby/PHP/Kotlin/Swift/C#/Scala/Lua/Elixir 支持 AST，不支持 Call Graph、CFG、DFG、PDG（表中对应为 -）。
101. TLDR 遵循 `.tldrignore`（gitignore 语法），可写入 `.venv/`、`__pycache__/`、`node_modules/`、`*.min.js`、`dist/`。
102. 首次运行会创建带合理默认值的 `.tldrignore`。
103. 使用 `--no-ignore` 绕过忽略规则。
104. 找函数定义用 `tldr extract file --function X`，不要用 grep。
105. 搜索代码模式用 `tldr search "pattern"`，不要用 grep。
106. 字符串字面量搜索用 `grep "literal"`。
107. 配置值搜索用 `grep "KEY="`。
108. 跨文件调用用 `tldr calls`。
109. 反向依赖用 `tldr impact func`。
110. 复杂度分析用 `tldr cfg file func`。
111. 变量跟踪用 `tldr dfg file func`。
112. 自然语言查询用 `tldr semantic search`。
113. Python API 从 `tldr.api` 导入：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`；统一接口 `get_relevant_context`；分析 `analyze_dead_code`、`analyze_architecture`、`analyze_impact`。
114. Python API 示例：`ctx = get_relevant_context("src/", "main", depth=2, language="python")`，然后 `print(ctx.to_llm_string())`。
115. Bug 修复关键洞察：TLDR 用于导航，然后读取实际代码；不要只靠摘要修 bug。
116. Bug 修复第 1 步导航：用 `tldr imports file.py` 找 buggy 文件依赖什么。
117. Bug 修复第 1 步导航：用 `tldr impact func_name .` 找谁调用 buggy 函数。
118. Bug 修复第 1 步导航：用 `tldr calls .` 找跨文件边，对 models 跟随 2-hop。
119. Bug 修复第 2 步读取：读取关键文件的实际代码（2-4 个文件，不是全部 50 个）。
120. Bug 修复读取代码：使用 Read 工具或 `tldr search "def buggy_func" . -C 20`。
121. 跨文件 bug 需要看有 bug 的文件（例如 handler 访问 `task.user_id`）和定义契约的文件（例如 model 定义 `owner_id`）。
122. TLDR 找到哪些文件重要，然后读取它们。
123. 需要更多上下文时：`tldr search "pattern" . -C 20` 获取 20 行上下文代码。
124. 需要更多上下文时：`tldr imports file.py` 查看文件依赖。
125. 需要更多上下文时：直接读取文件获取完整实现。
126. Token 节省证据：原始文件读取 23,314 tokens，TLDR 所有层 1,189 tokens，节省 95%。
127. 核心洞察：调用图导航到相关代码，然后各层给出结构化摘要，不读无关代码。

适用边界 · 注意事项

• 不要用 TLDR 替代纯字符串字面量或配置键搜索；这些场景 `grep "literal"` 或 `grep "KEY="` 更合适。
• 不要只依赖 TLDR 摘要修跨文件 bug；必须读取有 bug 文件和契约文件的实际代码。
• 目标语言不支持所需层级时不要使用对应分析，例如 Java/C/C++ 不支持 CFG/DFG/PDG，Ruby/PHP/Kotlin/Swift/C#/Scala/Lua/Elixir 不支持 Call Graph/CFG/DFG/PDG。