CntxtPY
通过知识图谱将 Python 代码库压缩为 LLM 高效消费的上下文，减少 75% token 消耗
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
通过知识图谱将 Python 代码库压缩为 LLM 高效消费的上下文，减少 75% token 消耗
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象你要帮一位朋友快速了解一栋陌生大楼的结构，你会给他看整栋楼的施工蓝图（几千页），还是一张标注了电梯、楼梯、消防通道的建筑平面图？答案不言而喻。
CntxtPY 正是这样一个工具——它能把一整个 Python 项目压缩成一份结构化的"知识图谱"，让大模型在消耗 75% 更少 token 的情况下，获得比直接读源码更清晰的项目理解。
这个数字并非营销话术。根据项目 README 的描述，它的压缩策略基于两个核心逻辑：一是只保留关系，不保留实现（把函数体用签名替代），二是用结构化符号替代自然语言（比如用 Class.method() 形式表达调用关系）。这样一来，一个 5 万 token 的中等规模项目可以压缩到 1.2 万 token 左右，直接省出一大截上下文窗口给真正的分析任务。
让 LLM 分析代码库并不是什么新鲜需求，但实践中有一个显著的痛点：token 成本与信息密度的矛盾。喂给大模型的代码越多，上下文窗口越容易溢出，响应质量也越不稳定。开发者们通常会手动写 prompt、复制关键文件片段、忽略无关目录——这套操作本质上就是在做"人工压缩"。
CntxtPY 的作者 brandondocusen 显然也遇到了这个烦恼，于是干脆把它自动化了。整个工具用 Python 原生写法 实现，不依赖任何重型 ML 框架，只靠标准库 + networkx 图库就能跑起来。这种"用 Python 分析 Python"的元编程思路本身就很优雅。
CntxtPY 会对指定目录做静态代码分析，遍历所有 .py、配置文件、构建脚本，提取以下结构信息：
import X 还是 from Y import Z）requirements.txt、pyproject.toml、Pipfile 解析出项目外部依赖及版本约束@dataclass、@property、@abstractmethod 等元编程工具.yaml、.ini、.cfg、.json 等配置文件的结构化提取所有这些信息最终被组织进一个 NetworkX 有向图，图中的节点代表类/函数/模块/依赖包，边代表它们之间的调用、继承或导入关系。
compression/compression.py 实现了知识图谱的二次压缩。这一步的核心思路是：用结构化符号替代自然语言描述。比如，把一条冗长的类文档字符串替换成一行 [CLASS: ClassName, METHODS: m1/m2/m3] 的紧凑格式。压缩后的结果写入 compression/compressed_knowledge_graph.txt，可以直接粘贴到任何 LLM 的输入框里。
CntxtPY.py 内置了基于 matplotlib 的可视化功能，能把知识图谱渲染成节点-边图。这对于理解大型项目的架构特别有帮助。
CntxtPY 的代码架构非常清晰，主文件 CntxtPY.py 承担图构建和文件遍历的调度职责，具体的解析逻辑全部下沉到 regex_components/ 目录下的 11 个专用模块：
| 模块 | 职责 |
|---|---|
CodeIdentifierExtractor | 提取类、函数、变量、常量，附带类型注解和参数签名 |
DependencyMapper | 分析 import 语句，构建模块依赖关系图 |
CommentProcessor | 提取行注释、块注释、docstring，区分注释类型 |
DocumentationAnalyzer | 解析 reStructuredText 和 Markdown 文档结构 |
ConfigFileParser | 解析 .ini、.cfg、.env 配置文件 |
BuildConfigExtractor | 解析 setup.py、pyproject.toml 等构建配置 |
LoggingAnalyzer | 提取 logging.info/warning/error 等日志语句 |
VersionAnalyzer | 提取代码中的版本约束字符串 |
FileTypeProcessor | 根据文件扩展名分类处理非 Python 文件 |
IntegrationMapper | 检测第三方 SDK 集成点 |
LocalizationProcessor | 提取国际化字符串 |
这种"一个解析器专注一件事"的组合模式，使得新增文件类型或分析维度时不需要改动核心逻辑，扩展性很好。代码整体遵循良好的类型注解规范，List、Dict、Optional、Set 等 typing 提示随处可见。
git clone https://github.com/brandondocusen/CntxtPY.git
cd CntxtPY-main
pip install pyyaml configparser toml chardet networkx
依赖列表非常轻量，没有 CUDA、没有 PyTorch、没有 transformers。networkx 是唯一的图形计算库，其余都是 Python 标准库的外围封装。
python CntxtPY.py
# 按提示输入目标代码库路径
# 输出在 ./compression/ 目录下
运行后会产生两个文件：
python_code_knowledge_graph.json：完整的图结构，便于程序化处理compressed_knowledge_graph.txt：供 LLM 直接消费的压缩文本eval()、exec()、__import__(name) 等动态行为无法被图谱捕获。随着 GPT-4、Claude 3 等大模型上下文窗口的扩大，"喂给 LLM 多少代码"已经不像 2022 年那样是绝对的瓶颈。但这不意味着压缩不重要——信息密度比信息总量更影响输出质量。一份冗余的代码上下文往往包含大量重复的模式和无关细节，这会稀释 LLM 对核心逻辑的关注度。
CntxtPY 的思路本质上是对大模型提示工程的工程化：把人工做的"筛选关键文件-复制关键片段-写引导 prompt"这一套流程自动化。这代表了 AI 开发工具的一个细分方向——让 AI 更好地理解代码的工具。
CntxtPY 是一款定位精准的 Python 代码理解工具，通过静态分析 + 知识图谱 + 压缩算法三板斧，把大型代码库变成 LLM 能高效消费的紧凑上下文。它安装简单、无硬件要求，适合作为开发流程中的辅助工具。对于需要频繁与代码打交道、又想借助 LLM 提升效率的开发者来说，这个工具值得一试。