CntxtPY：给大模型递上一份"精简版"代码字典

从"全文背诵"到"划重点"——LLM 读代码的新姿势

想象你要帮一位朋友快速了解一栋陌生大楼的结构，你会给他看整栋楼的施工蓝图（几千页），还是一张标注了电梯、楼梯、消防通道的建筑平面图？答案不言而喻。

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 了谁，以什么形式（import X 还是 from Y import Z）
• 类层级与方法签名：继承关系、类方法/实例方法的类型注解
• 依赖包列表：从 requirements.txt、pyproject.toml、Pipfile 解析出项目外部依赖及版本约束
• 装饰器与协议：Python 3.x 新引入的 @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 的可视化功能，能把知识图谱渲染成节点-边图。这对于理解大型项目的架构特别有帮助。

---

技术实现：11个专用解析器协同工作

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 直接消费的压缩文本

最佳使用场景

• 代码审查：让 Claude/GPT 帮你 review 一个陌生项目的架构
• 遗留代码理解：接手一个没有文档的老项目，快速建立全局认知
• 依赖审计：排查循环依赖、清理无用依赖
• 团队交接：新人 onboarding 时提供一份项目"地图"

---

局限与不足

1. 仅支持 Python：这是工具本身的定位限制，不算缺点。
2. 动态分析能力为零：纯静态分析，eval()、exec()、__import__(name) 等动态行为无法被图谱捕获。
3. 不生成代码建议：它只负责"理解"，不负责"修改"。
4. 无容器化支持：作者未提供 Dockerfile，工具本身适合本地安装使用。

---

行业意义：为什么这件事值得关注？

随着 GPT-4、Claude 3 等大模型上下文窗口的扩大，"喂给 LLM 多少代码"已经不像 2022 年那样是绝对的瓶颈。但这不意味着压缩不重要——信息密度比信息总量更影响输出质量。一份冗余的代码上下文往往包含大量重复的模式和无关细节，这会稀释 LLM 对核心逻辑的关注度。

CntxtPY 的思路本质上是对大模型提示工程的工程化：把人工做的"筛选关键文件-复制关键片段-写引导 prompt"这一套流程自动化。这代表了 AI 开发工具的一个细分方向——让 AI 更好地理解代码的工具。

---

总结

CntxtPY 是一款定位精准的 Python 代码理解工具，通过静态分析 + 知识图谱 + 压缩算法三板斧，把大型代码库变成 LLM 能高效消费的紧凑上下文。它安装简单、无硬件要求，适合作为开发流程中的辅助工具。对于需要频繁与代码打交道、又想借助 LLM 提升效率的开发者来说，这个工具值得一试。