potpie Parsing 模块实战用 tree-sitter 从代码仓库提取 Context Graph并构建轻量词法搜索【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiepotpie 是一个面向 AI Native SDLC 的开源项目其核心愿景是为 AI 编程助手提供可查询、可推理的Context Graph上下文图。而本篇文章聚焦的potpie/parsing模块正是这条数据链路的源头从任意代码仓库中提取结构化的代码图Code Graph。读完本文你将掌握如何通过 Rust 或 Python API 一行式地把仓库转成文件 → 类/函数 → 调用关系的图结构理解 tree-sitter 标签查询与跨文件引用解析的底层实现并学会用内置的 FFF Workspace Search 做纯词法的内存级文件/内容检索。模块定位Context Graph 的第一级数据入口在 potpie 的架构中解析模块承担着把源码变成图的职责。其 README 开篇即点明模块的单一职责Extract code graphs from repositories.结合 README.md 中的 Note 段落可以确认一个重要的边界该 crate 只负责建图graphs only不做嵌入embeddings与语义搜索。语义检索与向量索引由上层模块完成文档中提到的父模块采用 Qdrant Neo4j 作为存储与检索后端。也就是说解析模块输出的是一张干净的、可序列化的结构图至于如何把它灌入向量库、如何做语义召回是后续管道的事。从源码结构看该模块是一个典型的Rust 核心 Python 绑定双通道设计Cargo.toml 中crate-type [cdylib, rlib]同时以pyo3提供 Python 扩展Rust 侧负责高性能解析与并行处理Python 侧既可以直接调用parsing_rs原生绑定也保留了纯 Python 参考实现py_graph.py。整个模块由五大子功能组成子模块源码路径职责图提取src/tag_extract.rstree-sitter 标签查询、作用域解析、跨文件引用连接代码索引src/code_index.rs遍历仓库、识别二进制/文本文件、并行读取行数统计src/parse.rs快速统计文件行数mmap 优化Git 层src/git.rsbare clone、git tree 解析、文件清单FFF 搜索src/fff_search/工作区文件/内容词法索引与检索图模型节点与关系的设计解析模块产出的图模型非常克制只有三类节点和两类关系全部定义在 tag_extract.rs 的NodePayload/RelationshipPayload/GraphPayload中。节点类型Node TypesFILE源码文件本身作为整棵子图的根容器CLASS/INTERFACE类型定义类与接口FUNCTION函数与方法。每个节点带有完整的位置元数据id、node_type、file、line、end_line、name、class_name可选以及text仅 FILE 节点携带全文。关系类型Relationship TypesCONTAINSFILE → CLASS/FUNCTION表示包含关系即文件包含其内定义的类型与函数REFERENCESFUNCTION → FUNCTION/CLASS表示调用与使用关系跨文件同样适用。节点的id命名规范直接决定了引用解析的可行性从 tag_extract.rs 可以看到let node_id match tag.tag_type.as_str() { method | function { if let Some(ref class_name) class_for_id { format!({}:{}.{}, file.relative_path, class_name, tag.name) } else { format!({}:{}, file.relative_path, tag.name) } } _ format!({}:{}, file.relative_path, tag.name), };即类方法节点的 ID 形如services/user.py:UserService.get_by_id顶层函数节点 ID 形如main.py:bar文件节点 ID 就是相对路径本身如main.py。这种文件路径:类名.方法名的 ID 约定为后续跨文件引用解析提供了稳定的锚点——这也被 tests 中的断言 所验证。Rust API一行提取整个仓库的图README 给出了最直接的 Rust 用法。extract_graph(/path/to/repo)接受一个本地仓库目录路径返回GraphPayloaduse parsing_rs::{extract_graph, GraphPayload, NodePayload, RelationshipPayload}; let graph: GraphPayload extract_graph(/path/to/repo); // Nodes: FILE, CLASS, INTERFACE, FUNCTION for node in graph.nodes { println!({}: {} {}:{}, node.node_type, node.name, node.file, node.line); } // Relationships: CONTAINS, REFERENCES for rel in graph.relationships { println!({} → {}, rel.source_id, rel.target_id); }extract_graph在 lib.rs 中作为#[pyfunction]暴露给 Python内部委托给crate::tag_extract::extract_graph。其执行路径是并行遍历与读取create_code_indexes(repo_dir)通过ignore::WalkBuilder遍历目录遵循.gitignore规则、跳过.git目录与已知二进制文件见 code_index.rs随后以 rayon 并行读取文本文件内容逐文件建图每个文件交给extract_file_graph生成局部节点、CONTAINS边、定义表与引用表跨文件解析汇总所有定义与引用按标识符匹配并连接REFERENCES边。值得注意的优化细节文件读取前会做二进制嗅探——先排除已知二进制扩展名png、jpg、zip、so 等约 70 种再对前 8192 字节采样若 NUL 字节存在或不可打印字符比例超过 30%NON_TEXT_THRESHOLD 0.30则判定为二进制而跳过code_index.rs。这保证了建图过程不会被误入的二进制文件拖慢或污染。Python APINetworkX MultiDiGraph除原生绑定外模块还提供了一套纯 Python 参考实现入口是 py_graph.py 的create_graph返回NetworkX MultiDiGraphfrom parsing.py_graph import create_graph import networkx as nx G create_graph(/path/to/repo) # Returns NetworkX MultiDiGraph返回的图对象中每个节点的属性包含file、line、end_line、typeFILE/CLASS/INTERFACE/FUNCTION、name、class_name每条边的属性包含typeCONTAINS/REFERENCES与ident引用的标识符通过G.nodes、G.edges(dataTrue)即可直接接入 NetworkX 生态做后续的图分析、可视化或特征提取。从 pyproject.toml 可以看到 Python 侧的依赖设计networkx提供图结构grep-ast负责语言识别filename_to_langpygments负责词法回退当 tree-sitter 查询没有识别出引用时用词法分析器兜底提取 Name token 作为引用tree-sitter与tree-sitter-language-pack负责语法解析。Python 实现与 Rust 实现保持了几乎一致的语义同样先收集def与ref标签同样用file:class.method规则生成节点名同样通过seen_relationships集合防止双向重复边py_graph.py 的create_relationship中实现了与 Rust 侧is_valid_reference_direction相同的方向合法性判断。底层原理tree-sitter 标签查询与作用域解析图的质量取决于两个环节标签提取tags与作用域归属scope resolution。标签查询定义与引用extract_tagstag_extract.rs为每个文件选择对应语言的 tree-sitter 语法与查询文件.scm然后运行QueryCursor匹配所有捕获组。捕获名遵循约定name.definition.*→kind deftag_type取最后一段class / interface / method / functionname.reference.*→kind ref表示一次标识符引用。每个语言的查询文件存放在 potpie/parsing/parsing/queries/共 15 份Python、JavaScript、TypeScript、C、C#、C、Elixir、Go、Java、OCaml、PHP、Ruby、Rust、Elisp、Elm、QL 对应 16 个.scm文件其中 TypeScript 一份查询同时服务于typescript与tsx两种语言见load_query的匹配逻辑。这些查询文件通过include_str!在编译期嵌入二进制tag_extract.rs运行时不依赖外部文件。Java 方法调用的特例处理对 Java 的方法调用tree-sitter 的name.reference.method捕获的只是方法名本身这会丢失调用对象。因此 tag_extract.rs 做了特殊处理当父节点是method_invocation时读取object字段并拼接为object.method形式的完整引用名例如productService.listAllProducts()会被记录为productService.listAllProducts从而能精确解析到ProductService类中的同名方法。Python 参考实现 py_graph.py 保留了完全相同的逻辑。作用域解析引用归属到哪个函数引用的source_id即谁发起了这次引用通过 AST 包含关系确定。find_enclosing_scopetag_extract.rs从引用字节位置出发用descendant_for_byte_range找到最小节点再逐级向上遍历父节点命中class_definition/class_declaration/class_specifier→ 记录enclosing_class命中interface_declaration→ 记录enclosing_class命中method_declaration/function_definition/function_declaration/method_definition/constructor_declaration→ 记录enclosing_method。然后按类方法 → 仅方法 → 文件的优先级生成引用源 IDtag_extract.rs。跨文件引用解析与消歧extract_graph的第二阶段把所有文件的定义与引用汇总然后进行跨文件匹配tag_extract.rs。这里的几个关键决策方法引用使用非限定名查找对于object.method形式的引用用method部分最后一个点之后去定义表中查找因为定义按方法名登记同文件优先当同名定义既存在于本文件又存在于其他文件时优先连接同文件目标只有同文件无匹配时才回退到跨文件目标方向合法性过滤is_valid_reference_direction只允许FUNCTION → FUNCTION含 Impl 实现类特例、FUNCTION → 任意、任意 → CLASS、FILE → FUNCTION四种方向去重通过seen_relationships集合同时检查正向与反向键避免产生互为反向的重复边。这些行为都有对应的 Rust 单元测试锚定例如 test_extract_graph_cross_file_references验证main.py:bar → helper.py:foo的跨文件边、test_extract_graph_prefers_same_file_reference_when_duplicate_exists验证同名函数存在时同文件优先以及 test_extract_graph_cross_file_class_reference_from_function验证FUNCTION → CLASS跨文件边。FFF Workspace Search按需的词法内存索引除了建图模块还内置了一个轻量级搜索面——FFF命名取自目录fff_search。其定位在 README 中写得很清楚This is lexical, in-memory search only. It intentionally does not do semantic matching.即纯词法、纯内存、按需构建刻意不做语义匹配。它面向的场景是检出的工作区目录需要快速按路径/内容找文件。Rust 用法use parsing_rs::{build_workspace_index, search_files}; let index build_workspace_index(/path/to/workspace).expect(workspace should be indexed); let files index.search_files(auth, 5); assert!(!files.is_empty());Python 用法import parsing_rs index parsing_rs.build_workspace_index(/path/to/workspace) print(index.file_count(), index.content_file_count()) print([(r.path, r.score) for r in index.search_files(auth, 5)])Python 侧通过 fff_search/python.rs 暴露WorkspaceSearchIndex提供file_count()、content_file_count()、search_files(query, limit)、search_content(query, limit)四个方法search_content返回带path、line、snippet、score的结果。索引构成与检索打分build_workspace_indexworkspace.rs同时构建两个子索引文件索引FileIndex记录工作区全部文件路径检索时对路径与文件名打分。打分规则位于 file_index.rs完全匹配路径 1000 分、文件名或去扩展名主名完全匹配 950 分、路径前缀匹配 850 分、文件名前缀匹配 800 分、任意路径段前缀匹配 700 分、文件名包含 600 分、路径包含 500 分按分数降序截取 limit 条内容索引ContentIndex记录可索引文本文件的内容逐行匹配。打分规则位于 content_index.rs整行包含查询词得1000 出现次数分查询含多个词且一行全部命中时得700 命中词数分。snippet截取行首 200 字符。内容索引同样有二进制/大文件防护单文件超过 1MBMAX_CONTENT_BYTES 1_048_576或点开头隐藏文件如.env不进入内容索引路径仍会出现在文件索引中。与沙箱的衔接README 特别说明FFF 搜索Pre-sandboxlist_filesbehaviorpotpie/parsing/src/git.rsis unchanged即它不改变既有 Git 文件清单行为——git.rs中的list_files继续作为沙箱场景下列出仓库文件的标准接口。两者是互补关系git.rs面向远程 bare 仓库不需要 checkout 即可枚举文件树FFF 面向已检出的本地工作区直接索引磁盘内容。Git 层裸克隆与文件清单对于尚未检出到本地的远程仓库解析模块通过 git.rs 提供了两个 Python 可调用的能力bare_clone(repo_url, dest_path, git_ref, auth_token)以 bare --filterblob:none方式克隆仓库并拉取指定 ref随后用rev-parse --verify校验 ref 存在性git.rs。它还会做凭据处理ghs_开头的 token 使用x-access-token作为用户名其他 token 使用oauth2并会对 URL 中的特殊字符做百分号编码build_authenticated_urllist_files(bare_repo_path, git_ref)通过git ls-tree -r -t -z枚举指定 ref 下的全部文件与目录逐条解析为FileEntry含 path、name、dir、ext、depth、kind、sha子模块会被标记为submodule错误统一映射为 Python 侧的GitRepositoryNotFoundError、GitRefNotFoundError、GitParseError三类异常lib.rs。细节上list_files使用 NUL 分隔符-z解析 ls-tree 输出因此能正确保留文件名中的换行符等特殊字符validate_ref会拒绝空字符串、含换行或含..的 ref防止路径穿越git.rs。支持的语言与文件映射README 列出模块支持 16 种语言Python、Rust、JavaScript、TypeScript、Go、Java、C、C、Ruby、PHP、C#、Elixir、OCaml、Elisp、Elm、QL。文件扩展名到语言的映射定义在 tag_extract.rs 的filename_to_lang语言扩展名Python.pyJavaScript.js/.jsxTypeScript.ts/.tsxC.c/.hC.cpp/.cc/.cxx/.hpp/.hh/.hxxC#.csGo.goJava.javaRust.rsRuby.rbPHP.phpElixir.ex/.exsOCaml.ml/.mliElisp.elElm.elmQL.ql每种语言在 Cargo.toml 中都有对应的tree-sitter-*语法 crate 依赖并通过include_str!内嵌对应的.scm标签查询。Python 参考实现则通过tree-sitter-language-pack动态加载语法查询文件同样来自 queries 目录。构建与安装模块使用maturin作为构建后端Python 侧Rust crate 名为parsing_rs。README 中的构建命令cd app/src/parsing maturin develop在当前仓库中对应的目录为potpie/parsing即cd potpie/parsing maturin developmaturin develop会在当前 Python 环境内编译并安装 Rust 扩展module-name parsing.parsing_rs见 pyproject.toml使得import parsing.parsing_rs或按 README 示例直接import parsing_rs可用。构建要求 Python 版本3.12,3.15Rust 侧依赖 tree-sitter 0.26 及 15 个语言语法 crate。仓库内还附带 uv.lock 锁定完整的依赖树可用 uv 复现环境。若只需要 Rust 侧的 rlib如嵌入其他 Rust 程序Cargo 已配置crate-type [cdylib, rlib]可直接作为普通 Rust crate 依赖使用。边界与限制哪些事解析模块不做结合 README 的 Note 与源码实现使用本模块前需要明确三条边界只建图不做语义解析模块产出的是结构化图与词法搜索索引不生成 embedding、不做相似度检索。README 明确指出语义侧Qdrant Neo4j由上层模块负责引用解析基于标识符匹配REFERENCES边通过定义名/引用名一致来连接属于符号级解析而非完整语义解析不做类型推断、不做重载决议。同名函数的消歧策略是同文件优先、否则跨文件这一近似可能在某些场景如同名不同签名的重载产生合并FFF 是内存态词法检索工作区索引按需构建、驻留内存搜索为大小写不敏感的字符串匹配与子串计数打分不做拼写容错、同义词或语义排序。这些限制并非缺陷而是模块小而专的设计取舍——把高成本、高精度的语义层留给上层自己保证快、稳、可序列化。小结从仓库到图的完整链路纵观整个解析模块一条完整的数据链路清晰可见远程仓库 URL │ bare_clone()git.rs可选 ▼ 本地仓库目录 │ create_code_indexes()code_index.rs并行二进制嗅探 ▼ 文本文件集合 │ extract_tags()tree-sitter .scm 查询def/ref 标签 ▼ 逐文件局部图FILE/CLASS/INTERFACE/FUNCTION CONTAINS 边 │ 跨文件引用解析同文件优先 方向过滤 去重 ▼ GraphPayloadnodes relationships │ ├── Rustextract_graph() / Pythoncreate_graph() → NetworkX └── 上层向量化、语义检索Qdrant Neo4j同时build_workspace_index提供了一条平行的轻量路径对已检出的工作区做纯词法的路径/内容内存检索服务于沙箱等需要快速按需找文件的场景。无论你是要在 potpie 之上构建代码理解工具还是想借鉴这套tree-sitter 建图 词法索引的架构potpie/parsing都是一个结构清晰、测试完备的参考实现——其单元测试覆盖了同文件/跨文件/跨目录/类引用等多个边界场景可作为深入阅读的起点。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 potpie Parsing 模块实战：用 tree-sitter 从代码仓库提取 Context Graph，并构建轻量词法搜索
potpie Parsing 模块实战用 tree-sitter 从代码仓库提取 Context Graph并构建轻量词法搜索【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpiepotpie 是一个面向 AI Native SDLC 的开源项目其核心愿景是为 AI 编程助手提供可查询、可推理的Context Graph上下文图。而本篇文章聚焦的potpie/parsing模块正是这条数据链路的源头从任意代码仓库中提取结构化的代码图Code Graph。读完本文你将掌握如何通过 Rust 或 Python API 一行式地把仓库转成文件 → 类/函数 → 调用关系的图结构理解 tree-sitter 标签查询与跨文件引用解析的底层实现并学会用内置的 FFF Workspace Search 做纯词法的内存级文件/内容检索。模块定位Context Graph 的第一级数据入口在 potpie 的架构中解析模块承担着把源码变成图的职责。其 README 开篇即点明模块的单一职责Extract code graphs from repositories.结合 README.md 中的 Note 段落可以确认一个重要的边界该 crate 只负责建图graphs only不做嵌入embeddings与语义搜索。语义检索与向量索引由上层模块完成文档中提到的父模块采用 Qdrant Neo4j 作为存储与检索后端。也就是说解析模块输出的是一张干净的、可序列化的结构图至于如何把它灌入向量库、如何做语义召回是后续管道的事。从源码结构看该模块是一个典型的Rust 核心 Python 绑定双通道设计Cargo.toml 中crate-type [cdylib, rlib]同时以pyo3提供 Python 扩展Rust 侧负责高性能解析与并行处理Python 侧既可以直接调用parsing_rs原生绑定也保留了纯 Python 参考实现py_graph.py。整个模块由五大子功能组成子模块源码路径职责图提取src/tag_extract.rstree-sitter 标签查询、作用域解析、跨文件引用连接代码索引src/code_index.rs遍历仓库、识别二进制/文本文件、并行读取行数统计src/parse.rs快速统计文件行数mmap 优化Git 层src/git.rsbare clone、git tree 解析、文件清单FFF 搜索src/fff_search/工作区文件/内容词法索引与检索图模型节点与关系的设计解析模块产出的图模型非常克制只有三类节点和两类关系全部定义在 tag_extract.rs 的NodePayload/RelationshipPayload/GraphPayload中。节点类型Node TypesFILE源码文件本身作为整棵子图的根容器CLASS/INTERFACE类型定义类与接口FUNCTION函数与方法。每个节点带有完整的位置元数据id、node_type、file、line、end_line、name、class_name可选以及text仅 FILE 节点携带全文。关系类型Relationship TypesCONTAINSFILE → CLASS/FUNCTION表示包含关系即文件包含其内定义的类型与函数REFERENCESFUNCTION → FUNCTION/CLASS表示调用与使用关系跨文件同样适用。节点的id命名规范直接决定了引用解析的可行性从 tag_extract.rs 可以看到let node_id match tag.tag_type.as_str() { method | function { if let Some(ref class_name) class_for_id { format!({}:{}.{}, file.relative_path, class_name, tag.name) } else { format!({}:{}, file.relative_path, tag.name) } } _ format!({}:{}, file.relative_path, tag.name), };即类方法节点的 ID 形如services/user.py:UserService.get_by_id顶层函数节点 ID 形如main.py:bar文件节点 ID 就是相对路径本身如main.py。这种文件路径:类名.方法名的 ID 约定为后续跨文件引用解析提供了稳定的锚点——这也被 tests 中的断言 所验证。Rust API一行提取整个仓库的图README 给出了最直接的 Rust 用法。extract_graph(/path/to/repo)接受一个本地仓库目录路径返回GraphPayloaduse parsing_rs::{extract_graph, GraphPayload, NodePayload, RelationshipPayload}; let graph: GraphPayload extract_graph(/path/to/repo); // Nodes: FILE, CLASS, INTERFACE, FUNCTION for node in graph.nodes { println!({}: {} {}:{}, node.node_type, node.name, node.file, node.line); } // Relationships: CONTAINS, REFERENCES for rel in graph.relationships { println!({} → {}, rel.source_id, rel.target_id); }extract_graph在 lib.rs 中作为#[pyfunction]暴露给 Python内部委托给crate::tag_extract::extract_graph。其执行路径是并行遍历与读取create_code_indexes(repo_dir)通过ignore::WalkBuilder遍历目录遵循.gitignore规则、跳过.git目录与已知二进制文件见 code_index.rs随后以 rayon 并行读取文本文件内容逐文件建图每个文件交给extract_file_graph生成局部节点、CONTAINS边、定义表与引用表跨文件解析汇总所有定义与引用按标识符匹配并连接REFERENCES边。值得注意的优化细节文件读取前会做二进制嗅探——先排除已知二进制扩展名png、jpg、zip、so 等约 70 种再对前 8192 字节采样若 NUL 字节存在或不可打印字符比例超过 30%NON_TEXT_THRESHOLD 0.30则判定为二进制而跳过code_index.rs。这保证了建图过程不会被误入的二进制文件拖慢或污染。Python APINetworkX MultiDiGraph除原生绑定外模块还提供了一套纯 Python 参考实现入口是 py_graph.py 的create_graph返回NetworkX MultiDiGraphfrom parsing.py_graph import create_graph import networkx as nx G create_graph(/path/to/repo) # Returns NetworkX MultiDiGraph返回的图对象中每个节点的属性包含file、line、end_line、typeFILE/CLASS/INTERFACE/FUNCTION、name、class_name每条边的属性包含typeCONTAINS/REFERENCES与ident引用的标识符通过G.nodes、G.edges(dataTrue)即可直接接入 NetworkX 生态做后续的图分析、可视化或特征提取。从 pyproject.toml 可以看到 Python 侧的依赖设计networkx提供图结构grep-ast负责语言识别filename_to_langpygments负责词法回退当 tree-sitter 查询没有识别出引用时用词法分析器兜底提取 Name token 作为引用tree-sitter与tree-sitter-language-pack负责语法解析。Python 实现与 Rust 实现保持了几乎一致的语义同样先收集def与ref标签同样用file:class.method规则生成节点名同样通过seen_relationships集合防止双向重复边py_graph.py 的create_relationship中实现了与 Rust 侧is_valid_reference_direction相同的方向合法性判断。底层原理tree-sitter 标签查询与作用域解析图的质量取决于两个环节标签提取tags与作用域归属scope resolution。标签查询定义与引用extract_tagstag_extract.rs为每个文件选择对应语言的 tree-sitter 语法与查询文件.scm然后运行QueryCursor匹配所有捕获组。捕获名遵循约定name.definition.*→kind deftag_type取最后一段class / interface / method / functionname.reference.*→kind ref表示一次标识符引用。每个语言的查询文件存放在 potpie/parsing/parsing/queries/共 15 份Python、JavaScript、TypeScript、C、C#、C、Elixir、Go、Java、OCaml、PHP、Ruby、Rust、Elisp、Elm、QL 对应 16 个.scm文件其中 TypeScript 一份查询同时服务于typescript与tsx两种语言见load_query的匹配逻辑。这些查询文件通过include_str!在编译期嵌入二进制tag_extract.rs运行时不依赖外部文件。Java 方法调用的特例处理对 Java 的方法调用tree-sitter 的name.reference.method捕获的只是方法名本身这会丢失调用对象。因此 tag_extract.rs 做了特殊处理当父节点是method_invocation时读取object字段并拼接为object.method形式的完整引用名例如productService.listAllProducts()会被记录为productService.listAllProducts从而能精确解析到ProductService类中的同名方法。Python 参考实现 py_graph.py 保留了完全相同的逻辑。作用域解析引用归属到哪个函数引用的source_id即谁发起了这次引用通过 AST 包含关系确定。find_enclosing_scopetag_extract.rs从引用字节位置出发用descendant_for_byte_range找到最小节点再逐级向上遍历父节点命中class_definition/class_declaration/class_specifier→ 记录enclosing_class命中interface_declaration→ 记录enclosing_class命中method_declaration/function_definition/function_declaration/method_definition/constructor_declaration→ 记录enclosing_method。然后按类方法 → 仅方法 → 文件的优先级生成引用源 IDtag_extract.rs。跨文件引用解析与消歧extract_graph的第二阶段把所有文件的定义与引用汇总然后进行跨文件匹配tag_extract.rs。这里的几个关键决策方法引用使用非限定名查找对于object.method形式的引用用method部分最后一个点之后去定义表中查找因为定义按方法名登记同文件优先当同名定义既存在于本文件又存在于其他文件时优先连接同文件目标只有同文件无匹配时才回退到跨文件目标方向合法性过滤is_valid_reference_direction只允许FUNCTION → FUNCTION含 Impl 实现类特例、FUNCTION → 任意、任意 → CLASS、FILE → FUNCTION四种方向去重通过seen_relationships集合同时检查正向与反向键避免产生互为反向的重复边。这些行为都有对应的 Rust 单元测试锚定例如 test_extract_graph_cross_file_references验证main.py:bar → helper.py:foo的跨文件边、test_extract_graph_prefers_same_file_reference_when_duplicate_exists验证同名函数存在时同文件优先以及 test_extract_graph_cross_file_class_reference_from_function验证FUNCTION → CLASS跨文件边。FFF Workspace Search按需的词法内存索引除了建图模块还内置了一个轻量级搜索面——FFF命名取自目录fff_search。其定位在 README 中写得很清楚This is lexical, in-memory search only. It intentionally does not do semantic matching.即纯词法、纯内存、按需构建刻意不做语义匹配。它面向的场景是检出的工作区目录需要快速按路径/内容找文件。Rust 用法use parsing_rs::{build_workspace_index, search_files}; let index build_workspace_index(/path/to/workspace).expect(workspace should be indexed); let files index.search_files(auth, 5); assert!(!files.is_empty());Python 用法import parsing_rs index parsing_rs.build_workspace_index(/path/to/workspace) print(index.file_count(), index.content_file_count()) print([(r.path, r.score) for r in index.search_files(auth, 5)])Python 侧通过 fff_search/python.rs 暴露WorkspaceSearchIndex提供file_count()、content_file_count()、search_files(query, limit)、search_content(query, limit)四个方法search_content返回带path、line、snippet、score的结果。索引构成与检索打分build_workspace_indexworkspace.rs同时构建两个子索引文件索引FileIndex记录工作区全部文件路径检索时对路径与文件名打分。打分规则位于 file_index.rs完全匹配路径 1000 分、文件名或去扩展名主名完全匹配 950 分、路径前缀匹配 850 分、文件名前缀匹配 800 分、任意路径段前缀匹配 700 分、文件名包含 600 分、路径包含 500 分按分数降序截取 limit 条内容索引ContentIndex记录可索引文本文件的内容逐行匹配。打分规则位于 content_index.rs整行包含查询词得1000 出现次数分查询含多个词且一行全部命中时得700 命中词数分。snippet截取行首 200 字符。内容索引同样有二进制/大文件防护单文件超过 1MBMAX_CONTENT_BYTES 1_048_576或点开头隐藏文件如.env不进入内容索引路径仍会出现在文件索引中。与沙箱的衔接README 特别说明FFF 搜索Pre-sandboxlist_filesbehaviorpotpie/parsing/src/git.rsis unchanged即它不改变既有 Git 文件清单行为——git.rs中的list_files继续作为沙箱场景下列出仓库文件的标准接口。两者是互补关系git.rs面向远程 bare 仓库不需要 checkout 即可枚举文件树FFF 面向已检出的本地工作区直接索引磁盘内容。Git 层裸克隆与文件清单对于尚未检出到本地的远程仓库解析模块通过 git.rs 提供了两个 Python 可调用的能力bare_clone(repo_url, dest_path, git_ref, auth_token)以 bare --filterblob:none方式克隆仓库并拉取指定 ref随后用rev-parse --verify校验 ref 存在性git.rs。它还会做凭据处理ghs_开头的 token 使用x-access-token作为用户名其他 token 使用oauth2并会对 URL 中的特殊字符做百分号编码build_authenticated_urllist_files(bare_repo_path, git_ref)通过git ls-tree -r -t -z枚举指定 ref 下的全部文件与目录逐条解析为FileEntry含 path、name、dir、ext、depth、kind、sha子模块会被标记为submodule错误统一映射为 Python 侧的GitRepositoryNotFoundError、GitRefNotFoundError、GitParseError三类异常lib.rs。细节上list_files使用 NUL 分隔符-z解析 ls-tree 输出因此能正确保留文件名中的换行符等特殊字符validate_ref会拒绝空字符串、含换行或含..的 ref防止路径穿越git.rs。支持的语言与文件映射README 列出模块支持 16 种语言Python、Rust、JavaScript、TypeScript、Go、Java、C、C、Ruby、PHP、C#、Elixir、OCaml、Elisp、Elm、QL。文件扩展名到语言的映射定义在 tag_extract.rs 的filename_to_lang语言扩展名Python.pyJavaScript.js/.jsxTypeScript.ts/.tsxC.c/.hC.cpp/.cc/.cxx/.hpp/.hh/.hxxC#.csGo.goJava.javaRust.rsRuby.rbPHP.phpElixir.ex/.exsOCaml.ml/.mliElisp.elElm.elmQL.ql每种语言在 Cargo.toml 中都有对应的tree-sitter-*语法 crate 依赖并通过include_str!内嵌对应的.scm标签查询。Python 参考实现则通过tree-sitter-language-pack动态加载语法查询文件同样来自 queries 目录。构建与安装模块使用maturin作为构建后端Python 侧Rust crate 名为parsing_rs。README 中的构建命令cd app/src/parsing maturin develop在当前仓库中对应的目录为potpie/parsing即cd potpie/parsing maturin developmaturin develop会在当前 Python 环境内编译并安装 Rust 扩展module-name parsing.parsing_rs见 pyproject.toml使得import parsing.parsing_rs或按 README 示例直接import parsing_rs可用。构建要求 Python 版本3.12,3.15Rust 侧依赖 tree-sitter 0.26 及 15 个语言语法 crate。仓库内还附带 uv.lock 锁定完整的依赖树可用 uv 复现环境。若只需要 Rust 侧的 rlib如嵌入其他 Rust 程序Cargo 已配置crate-type [cdylib, rlib]可直接作为普通 Rust crate 依赖使用。边界与限制哪些事解析模块不做结合 README 的 Note 与源码实现使用本模块前需要明确三条边界只建图不做语义解析模块产出的是结构化图与词法搜索索引不生成 embedding、不做相似度检索。README 明确指出语义侧Qdrant Neo4j由上层模块负责引用解析基于标识符匹配REFERENCES边通过定义名/引用名一致来连接属于符号级解析而非完整语义解析不做类型推断、不做重载决议。同名函数的消歧策略是同文件优先、否则跨文件这一近似可能在某些场景如同名不同签名的重载产生合并FFF 是内存态词法检索工作区索引按需构建、驻留内存搜索为大小写不敏感的字符串匹配与子串计数打分不做拼写容错、同义词或语义排序。这些限制并非缺陷而是模块小而专的设计取舍——把高成本、高精度的语义层留给上层自己保证快、稳、可序列化。小结从仓库到图的完整链路纵观整个解析模块一条完整的数据链路清晰可见远程仓库 URL │ bare_clone()git.rs可选 ▼ 本地仓库目录 │ create_code_indexes()code_index.rs并行二进制嗅探 ▼ 文本文件集合 │ extract_tags()tree-sitter .scm 查询def/ref 标签 ▼ 逐文件局部图FILE/CLASS/INTERFACE/FUNCTION CONTAINS 边 │ 跨文件引用解析同文件优先 方向过滤 去重 ▼ GraphPayloadnodes relationships │ ├── Rustextract_graph() / Pythoncreate_graph() → NetworkX └── 上层向量化、语义检索Qdrant Neo4j同时build_workspace_index提供了一条平行的轻量路径对已检出的工作区做纯词法的路径/内容内存检索服务于沙箱等需要快速按需找文件的场景。无论你是要在 potpie 之上构建代码理解工具还是想借鉴这套tree-sitter 建图 词法索引的架构potpie/parsing都是一个结构清晰、测试完备的参考实现——其单元测试覆盖了同文件/跨文件/跨目录/类引用等多个边界场景可作为深入阅读的起点。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考