用途
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 上暴露。