SuperAPI AI 工具集

extracting-code-structure

编程与开发

查看项目

更新于 10-16 08:20

技能介绍

用途

extracting-code-structure 用于从源文件中提取结构化的代码元数据。当用户想要的是「列出函数」「这个文件导入了什么」「找出导出的符号」「提取文档字符串」这类结构化信息,而不是原始语法树时,应使用该技能。

它通过 ts-pack process <file> 命令对源文件运行代码智能流水线,并打印 JSON 结果。

主要能力

process 支持以下特性标志,只有显式请求的特性才会被计算:

标志 提取内容
--structure 函数、类、方法、模块(跨度、嵌套、可见性)
--imports 导入语句及其来源
--exports 导出的符号及其种类
--comments 行内注释和块注释
--docstrings 附加到定义上的文档字符串
--symbols 所有标识符(用于搜索/索引)
--diagnostics 语法错误和错误节点及其位置
--all 启用以上所有特性
--chunk-size <bytes> 语法感知的分块
--language <name>(-l) 覆盖语言(否则从扩展名自动检测)

当未给出任何特性标志时,process 默认使用 --structure --imports --exports。传入任意单个特性标志会关闭该默认集合,因此需要列出所有想要的特性。

使用方式

基本用法:

# 默认特性:结构 + 导入 + 导出
ts-pack process src/app.ts

# 显式选择特性(只计算请求的内容)
ts-pack process src/app.ts --structure --imports --symbols --docstrings

# 全部特性
ts-pack process src/app.ts --all

process 始终打印 JSON。顶层键包括:

{
  "language": "python",
  "metrics": { "total_lines": 0, "code_lines": 0, "comment_lines": 0, "blank_lines": 0, "total_bytes": 0, "node_count": 0, "error_count": 0, "max_depth": 0 },
  "structure": [],
  "imports": [],
  "exports": [],
  "comments": [],
  "docstrings": [],
  "symbols": [],
  "diagnostics": [],
  "chunks": []
}

只要运行任何处理,metrics 就会被填充。chunks 仅在设置 --chunk-size 时出现。空集合会从 JSON 中省略,因此缺失的键表示「未找到任何内容」,而不是错误。

结构条目(structure items):每个结构条目包含 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 '.structure[] | {kind, name, line: .span.start_line}'

# 仅导入来源
ts-pack process src/app.ts --imports \
  | jq '.imports[].source'

# 语法错误数量(也可通过 metrics.error_count 获取)
ts-pack process broken.go --diagnostics \
  | jq '.diagnostics | length'

# 跨文件树构建符号索引
for f in $(git ls-files '*.rs'); do
  ts-pack process "$f" --symbols | jq -c --arg f "$f" '{file: $f, symbols: .symbols}'
done

SDK 等价用法:

from tree_sitter_language_pack import process, ProcessConfig

# ProcessConfig 是冻结数据类——在构造函数中设置字段。
# structure/imports/exports 默认为 True;添加其余想要的项。
config = ProcessConfig("python", symbols=True, docstrings=True)
result = process(source_code, config)
for item in result.structure:                 # ProcessResult 是对象,不是字典
    print(item.kind, item.name, item.span.start_line)

SDK 还暴露了解析后的树(get_parser(...) → Parser/Tree/Node),用于运行自定义 tree-sitter 查询;以及一个 data_extraction 配置标志,可从数据格式文件(JSON、YAML、TOML 等)中提取分层键/值树到结果的 data 字段——这两者均未在 CLI 上暴露。

适用场景

  • 需要列出源文件中的函数、类、方法或模块。
  • 需要了解文件的导入来源或导出的符号。
  • 需要提取文档字符串或注释。
  • 需要构建跨文件的符号索引。
  • 需要检测语法错误及其位置。
  • 需要语法感知的代码分块(配合 --chunk-size)。

限制

  • 当用户想要原始语法树而非提取的元数据时,应改用 ts-pack parse(参见 parsing-source 技能)。
  • 传入任意单个特性标志会关闭默认特性集合,必须显式列出所有想要的特性。
  • 空集合会从 JSON 中省略,缺失键表示未找到内容而非错误。
  • SDK 的解析树访问和 data_extraction 功能不在 CLI 上暴露。