codebase-packager

TLDR Expert

概述

通过语义层、结构化摘要和高级上下文打包，以极低的 Token 成本实现高保真代码库理解。结合 Repomix 进行上下文打包、Gitingest 生成仓库摘要，以及 llm-tldr 进行基于图的代码分析。

适用场景： 减少大型代码库的提示词开销、快速熟悉陌生仓库、梳理跨文件依赖关系、创建经过 AI 优化的上下文包。

不适用场景： 小型单文件任务、最终实现调试（应阅读完整文件）、实时编辑代码。

快速参考

模式	工具 / 命令	要点
上下文打包	repomix --include "src/**" --compress	将子目录打包成经过 AI 优化的上下文包
仅提取签名	repomix --include "src/**" --compress	压缩功能通过 Tree-sitter 提取签名
仓库摘要	gitingest . -o digest.txt	便于用作提示词的摘要，帮助快速熟悉仓库
依赖上下文	tldr context funcName --project .	为函数生成适用于大模型的上下文，节省 95% 的 Token
调用方追踪	tldr impact functionName .	通过反向调用图评估变更影响范围
正向调用图	tldr calls .	构建整个项目的正向调用图
语义搜索	tldr semantic "session expiry" .	命名不一致时，按含义查找逻辑
架构审计	tldr arch .	检测循环依赖、分层违规和死代码
死代码查找	tldr dead .	查找没有任何调用方的不可达函数
文件提取	tldr extract src/file.ts	从文件中提取 AST（函数、类、导入）
密钥扫描	Repomix 内置的 secretlint	确保上下文包不包含密钥或 PII

常见错误

错误	正确做法
未先检查结构就读取整个大型文件	读取完整文件前，先运行 tldr extract 获取签名
使用 grep 跨文件追踪依赖	使用 tldr impact 生成可识别动态导入的反向调用图
将 node_modules 或 dist 打包进上下文包	配置 Repomix 忽略列表，排除生成目录和供应商目录
认为语义搜索结果已涵盖所有内容	对照实际源码核实排名靠前的结果，并使用 rg 交叉验证
对大型目录运行 Repomix 时不启用压缩	使用 --compress 标志，确保不超出上下文窗口限制
纳入无关上下文，削弱信息质量	按自上而下的优先级处理：索引、签名、核心逻辑，然后是相邻上下文

委派

• 探索仓库结构：使用 Explore Agent 梳理目录布局，并在构建上下文包前确定关键模块
• 多步骤上下文打包工作流：使用 Task Agent，依次运行 Gitingest 摘要、Repomix 压缩和 llm-tldr 索引
• 架构分析与规划：使用 Plan Agent，为大型单体仓库设计上下文工程策略

参考资料

• 上下文工程模式 -- 打包策略、XML 标记、信噪比优化、预热提示词
• Repomix 和 Gitingest 精通指南 -- 配置、压缩模式、摘要生成、Tree-sitter 提取
• 语义图分析 -- llm-tldr 命令行工具、影响分析、语义搜索、架构审查