SuperAPI AI 工具集

extracting-code-structure

通用与其它

查看项目

更新于 10-16 07:18

技能介绍

用途:把源码文件转成结构化代码元数据,适合“列出函数”“这个文件导入了什么”“找导出符号”“取 docstring”等需求,而不是获取原始语法树。

主要能力:命令 ts-pack process <file> 运行代码智能流水线并打印 JSON。可通过标志选择提取内容:--structure(函数、类、方法、模块及其跨度、嵌套、可见性)、--imports(导入语句及来源)、--exports(导出符号及种类)、--comments(行内与块注释)、--docstrings(附在定义上的文档字符串)、--symbols(全部标识符,用于搜索/索引)、--diagnostics(语法错误与错误节点位置)、--all(启用全部上述特性)。未给出任何特性标志时,process 默认等于 --structure --imports --exports;一旦传入任一提取标志(--structure、--imports、--exports、--comments、--docstrings、--symbols、--diagnostics),该默认集合即被关闭,需自行列全所需特性。--chunk-size 与 --language 属于修饰符而非提取标志,不会关闭默认值,例如单独使用 --chunk-size 500 仍会输出 structure+imports+exports 并附加 chunks。

输出与结果形态:始终输出 JSON,顶层键包括 language、metrics,以及按需出现的 structure、imports、exports、comments、docstrings、symbols、diagnostics、chunks。metrics 在任何处理运行时都会填充,包含 total_lines、code_lines、comment_lines、blank_lines、total_bytes、node_count、error_count、max_depth;chunks 仅在设置 --chunk-size 时出现。空集合会按 skip_serializing_if 契约从 JSON 中省略,因此键缺失表示“未找到”,不是错误。structure 条目包含 kind(首字母大写,如 Function、Class、Method、Module、Struct、Trait,语言特有的种类序列化为 {"Other": "<kind>"})、name、visibility,以及嵌套的 span(start_byte/end_byte 与从零开始计数的 start_line/start_column/end_line/end_column)。嵌套通过 children 表达(例如类中的方法),而非父指针。可选字段有 decorators、doc_comment、signature、body_span。

使用方式示例:ts-pack process src/service.py --structure 后用 jq 取 kind、name 与行号;ts-pack process src/app.ts --imports 后取 .imports[].source;ts-pack process broken.go --diagnostics 后统计诊断数量;也可遍历文件为每个文件生成符号索引。SDK 等价用法:from tree_sitter_language_pack import process, ProcessConfig;ProcessConfig 是冻结 dataclass,structure/imports/exports 默认为 True,可在构造时添加所需字段,process(source_code, config) 返回 ProcessResult 对象而非字典,其 structure 项含 kind、name、span.start_line。SDK 还提供 get_parser(...) 返回 Parser/Tree/Node 以便运行自定义 tree-sitter 查询,并有 data_extraction 配置标志把 JSON、YAML、TOML 等数据格式的分层键值树放入结果的 data 字段;这两项在 CLI 上不暴露。

适用场景:需要批量提取函数、类、导入导出、符号、注释、docstring 或语法诊断以做搜索、索引、分析时使用。限制:若用户想要原始语法树,应改用 ts-pack parse;未提供收费、价格、支持语言清单或性能承诺等信息。