AIR 工具：一个语言无关的项目中间表示框架

项目背景

在日常开发中，我们经常需要处理多语言项目的结构分析和代码生成问题。无论是进行代码审计、项目迁移，还是 AI 辅助编程，都需要一种能够统一描述项目架构的中间表示。基于这个需求，我开发了 AIR（Application Interface Center）工具。

什么是 AIR？

AIR 是一个统一的命令行工具，用于 PIR（Project Intermediate Representation）的正向生成和逆向重构。PIR 是一种面向 AI 优化的项目中间表示，旨在用最少的 token 完整描述项目架构。

核心特性

• 多语言支持：支持 Python、Rust、C/C++、Java、汇编等多种编程语言

• 依赖关系池压缩算法：高效管理项目依赖关系

• Profile-Aware 语义推断：智能识别项目特征和架构模式

• 极简 Token 设计：用最精简的方式描述复杂项目结构

• 统一的命令行接口：简单易用的操作方式

架构设计

三大核心引擎

从项目的 PIR 描述可以看出，AIR 包含三个主要组件：

1. pirgen（正向生成引擎）

负责从源代码生成 PIR 文件，包含：

• 多语言分析器（C、Rust、Java、Python、汇编等）

• 项目模型构建

• 依赖关系解析

• Profile 识别系统

2. pcegen（证据生成引擎）

处理 PCR（Program Comprehension Request）请求，生成 PCES 静态证据：

• 语言检测器

• 证据构建器

• 引用解析器

• 序列化器

3. pir_reconstructor（逆向重构引擎）

从 PIR 文件重构项目：

• 模板系统（支持多种语言代码生成）

• 重构管道

• 结构层、关系层、文档层等多层处理

• 可视化输出（Graphviz、Mermaid、PlantUML）

模块化设计

每个组件都采用分层架构：

• 核心层（core）：提供基础数据模型和算法

• 分析器层（analyzers）：语言特定的分析逻辑

• 服务层（services）：业务逻辑封装

• 工具层（utils）：通用工具函数

安装和使用

安装方式

# 开发模式安装（推荐）
pip install -e .

# 正式安装
pip install .

基本使用

正向生成 PIR

air forward /path/to/project -o output.pir

逆向重构项目

air reverse project.pir output_dir/

生成代码证据

air peek request.pcr

技术亮点

1. 语言无关的中间表示

PIR 不依赖于特定编程语言，能够统一描述各种语言项目的结构特征。

2. 智能 Profile 识别

系统能够自动识别项目类型（如 python-framework），准确率达到 80% 以上。

3. 完整的工具链

从代码分析到项目重构，提供端到端的解决方案。

4. 丰富的可视化支持

支持多种图表格式，便于项目结构理解和文档生成。

实际应用场景

1. 代码审计和分析

快速理解大型项目的整体结构和依赖关系。

2. AI 辅助编程

为 LLM 提供结构化的项目信息，提高代码生成质量。

3. 项目迁移和重构

在不同语言或架构间进行项目转换。

4. 教学和文档生成

自动生成项目结构图和相关文档。

开发体会

在开发 AIR 的过程中，有几个关键的技术决策值得分享：

1. 中间表示的设计：PIR 需要在表达能力和简洁性之间找到平衡

2. 扩展性考虑：通过插件化的分析器设计，支持新语言的添加

3. 性能优化：依赖关系池和缓存机制大幅提升分析效率

未来规划

• 支持更多编程语言

• 增强 AI 集成能力

• 提供 Web 界面

• 优化大型项目处理性能

结语

AIR 工具虽然起源于个人需求，但其设计理念和实现方式具有普适性。希望通过开源分享，能够为有类似需求的开发者提供参考，也欢迎大家一起参与改进。

项目地址：https://github.com/daivy2333/air

欢迎大家 star、fork 和提交 issue！

以上是ai帮我生成的报告，hhh，算了

内容都大差不差，我用这个工具自描述给ai然后进行的优化，仨工具在v1版本都是勉强能用的。

后续的优化我会想能否不使用xml格式什么的，到时候这仨都会因此进化，不过是后来的事情了。

总之现在能用，在这里留一个blog做继续优化的誓言（）。

另外，感谢各位ai爹，包括但不限与通义，deepseek, gpt, gemini,GLM4.7。

以下是项目自描述，ai应该是能读懂的吧，而且是肉眼可见的有优化空间：

<pir>
<meta>
name: pirgen
root: /home/daivy/projects/air/pirgen
profile: generic
lang: PY
</meta>
<units>
u0: debug.py type=PY role=lib module=pirgen
u1: __init__.py type=PY role=lib module=pirgen
u2: min_token.py type=PY role=lib module=pirgen
u3: pirgen.py type=PY role=lib module=pirgen
u4: analyzers/c_analyzer.py type=PY role=lib module=analyzers
u5: analyzers/rust_analyzer.py type=PY role=lib module=analyzers
u6: analyzers/java_analyzer.py type=PY role=lib module=analyzers
u7: analyzers/base.py type=PY role=lib module=analyzers
u8: analyzers/asm_ld_analyzer.py type=PY role=lib module=analyzers
u9: analyzers/__init__.py type=PY role=lib module=analyzers
u10: analyzers/python_analyzer.py type=PY role=lib module=analyzers
u11: core/profile_canon.py type=PY role=lib module=core
u12: core/__init__.py type=PY role=lib module=core
u13: core/analysis_cache.py type=PY role=lib module=core
u14: core/project_model.py type=PY role=lib module=core
u15: core/pir_builder.py type=PY role=lib module=core
u16: core/profile_riscv.py type=PY role=lib module=core
u17: core/dep_canon.py type=PY role=lib module=core
</units>
<dependency-pool>
d0: import:[..core.project_model]
d1: import:[.analyzers]
d2: import:[.asm_ld_analyzer]
d3: import:[.base]
d4: import:[.c_analyzer]
d5: import:[.core.analysis_cache]
d6: import:[.core.dep_canon]
d7: import:[.core.pir_builder]
d8: import:[.core.profile_canon]
d9: import:[.core.project_model]
d10: import:[.java_analyzer]
d11: import:[.pirgen]
d12: import:[.project_model]
d13: import:[.python_analyzer]
d14: import:[.rust_analyzer]
d15: import:[core.evidence_builder]
d16: import:[core.extractor]
d17: import:[core.pcr_parser]
d18: import:[core.pir_index]
d19: import:[core.resolver]
d20: import:[core.serializer]
d21: import:[stdlib:py]
</dependency-pool>
<dependencies>
u0->refs:[d16 d19 d17 d18 d21 d15 d20]
u1->refs:[d11]
u2->refs:[d21]
u3->refs:[d7 d5 d21 d1 d6 d9 d8]
u4->refs:[d0 d3 d21]
u5->refs:[d0 d3 d21]
u6->refs:[d0 d3 d21]
u7->refs:[d0 d21]
u8->refs:[d0 d3 d21]
u9->refs:[d4 d10 d13 d14 d2]
u10->refs:[d0 d3 d21]
u11->refs:[d21]
u13->refs:[d21]
u14->refs:[d21]
u15->refs:[d12 d21]
u16->refs:[d21]
</dependencies>
<symbols>
is_source_file:u2 func
strip_c_comments:u2 func
minify_c_style:u2 func
minify_python:u2 func
process_directory:u2 func
main:u2 func entry=true
discover_source_files:u3 func
infer_unit_meta:u3 func
scan_project:u3 func
resolve_dependencies:u3 func
main:u3 func entry=true
CAnalyzer:u4 class
RustAnalyzer:u5 class
JavaAnalyzer:u6 class
BaseAnalyzer:u7 class
AsmLdAnalyzer:u8 class
get_analyzer:u9 func
PythonAnalyzer:u10 class
ProfileCanonicalizer:u11 class
AnalysisCache:u13 class
Unit:u14 class
Symbol:u14 class
Dependency:u14 class
ProjectModel:u14 class
PIRBuilder:u15 class
RISCVMemoryLayout:u16 class
get_riscv_extension_name:u16 func
is_riscv_special_symbol:u16 func
get_csr_address:u16 func
get_exception_code:u16 func
canonicalize_target:u17 func
canonicalize_dependencies:u17 func
</symbols>
<profiles>
  active: python-framework
  python-framework:
    confidence: 0.8
    tags:
      ◦ domain:language-tooling

      ◦ runtime:cpython

      ◦ stack:python-framework

    signals:
      ◦ layered-architecture

      ◦ multi-module

      ◦ semantic-classes

</profiles>
</pir>

<pir>
<meta>
name: pcegen
root: /home/daivy/projects/air/pcegen
profile: generic
lang: PY
</meta>
<units>
u0: test_pir.py type=PY role=lib module=pcegen
u1: test_resolve.py type=PY role=lib module=pcegen
u2: __init__.py type=PY role=lib module=pcegen
u3: pcegen.py type=PY role=lib module=pcegen
u4: analyzers/asm.py type=PY role=lib module=analyzers
u5: analyzers/cpp.py type=PY role=lib module=analyzers
u6: analyzers/c_backup.py type=PY role=lib module=analyzers
u7: analyzers/rust.py type=PY role=lib module=analyzers
u8: analyzers/python_extract_class.py type=PY role=lib module=analyzers
u9: analyzers/c_part1.py type=PY role=lib module=analyzers
u10: analyzers/ld.py type=PY role=lib module=analyzers
u11: analyzers/base.py type=PY role=lib module=analyzers
u12: analyzers/python.py type=PY role=lib module=analyzers
u13: analyzers/c_fixed.py type=PY role=lib module=analyzers
u14: analyzers/__init__.py type=PY role=lib module=analyzers
u15: analyzers/cpp_backup.py type=PY role=lib module=analyzers
u16: analyzers/rust_backup.py type=PY role=lib module=analyzers
u17: analyzers/python_new.py type=PY role=lib module=analyzers
u18: analyzers/c.py type=PY role=lib module=analyzers
u19: config/__init__.py type=PY role=lib module=config
u20: config/analyzer_config.py type=PY role=lib module=config
u21: models/evidence.py type=PY role=lib module=models
u22: models/need.py type=PY role=lib module=models
u23: models/__init__.py type=PY role=lib module=models
u24: models/resolved_ref.py type=PY role=lib module=models
u25: core/evidence_builder.py type=PY role=lib module=core
u26: core/extractor.py type=PY role=lib module=core
u27: core/language_detector.py type=PY role=lib module=core
u28: core/compressor.py type=PY role=lib module=core
u29: core/__init__.py type=PY role=lib module=core
u30: core/pir_index.py type=PY role=lib module=core
u31: core/pir_parser.py type=PY role=lib module=core
u32: core/resolver.py type=PY role=lib module=core
u33: core/pcr_parser.py type=PY role=lib module=core
u34: core/serializer.py type=PY role=lib module=core
</units>
<dependency-pool>
d0: import:[.analyzer_config]
d1: import:[analyzers.base]
d2: import:[core.evidence_builder]
d3: import:[core.extractor]
d4: import:[core.language_detector]
d5: import:[core.pcr_parser]
d6: import:[core.pir_index]
d7: import:[core.resolver]
d8: import:[core.serializer]
d9: import:[models.evidence]
d10: import:[models.need]
d11: import:[models.resolved_ref]
d12: import:[stdlib:py]
</dependency-pool>
<dependencies>
u0->refs:[d3 d7 d6 d5]
u1->refs:[d7 d6 d5]
u3->refs:[d2 d6 d7 d8 d5 d3 d12]
u4->refs:[d12 d1]
u5->refs:[d12 d1]
u6->refs:[d12 d1]
u7->refs:[d12 d1]
u8->refs:[d12]
u9->refs:[d12 d1]
u10->refs:[d12 d1]
u11->refs:[d12]
u12->refs:[d12 d1]
u13->refs:[d12 d1]
u15->refs:[d12 d1]
u16->refs:[d12 d1]
u17->refs:[d12 d1]
u18->refs:[d12 d1]
u19->refs:[d0]
u21->refs:[d12]
u22->refs:[d12]
u24->refs:[d12]
u25->refs:[d11 d12 d9]
u26->refs:[d4 d11 d12]
u27->refs:[d12]
u28->refs:[d11 d12 d9]
u30->refs:[d12]
u31->refs:[d12]
u32->refs:[d11 d12 d10]
u33->refs:[d12 d10]
u34->refs:[d12 d9]
</dependencies>
<symbols>
load_source_code:u3 func
process_pcr:u3 func
main:u3 func entry=true
ASMAnalyzer:u4 class
CppAnalyzer:u5 class
CAnalyzer:u6 class
RustAnalyzer:u7 class
extract_class:u8 func
CAnalyzer:u9 class
LDAnalyzer:u10 class
BaseAnalyzer:u11 class
PythonAnalyzer:u12 class
CAnalyzer:u13 class
CppAnalyzer:u15 class
RustAnalyzer:u16 class
PythonAnalyzer:u17 class
CAnalyzer:u18 class
get_analyzer_capabilities:u20 func
supports_view:u20 func
get_view_description:u20 func
get_supported_languages:u20 func
Evidence:u21 class
Need:u22 class
ResolvedRef:u24 class
EvidenceBuilder:u25 class
Extractor:u26 class
LanguageDetector:u27 class
Compressor:u28 class
PIRIndex:u30 class
PIRParser:u31 class
Resolver:u32 class
PCRParser:u33 class
PCESerializer:u34 class
</symbols>
<profiles>
  active: python-framework
  python-framework:
    confidence: 0.8
    tags:
      ◦ domain:language-tooling

      ◦ runtime:cpython

      ◦ stack:python-framework

    signals:
      ◦ layered-architecture

      ◦ multi-module

      ◦ semantic-classes

</profiles>
</pir>


<pir>
<meta>
name: pir_reconstructor
root: /home/daivy/projects/air/pir_reconstructor
profile: generic
lang: PY
</meta>
<units>
u0: errors.py type=PY role=lib module=pir_reconstructor
u1: cli.py type=PY role=lib module=pir_reconstructor
u2: __init__.py type=PY role=lib module=pir_reconstructor
u3: pir/validator.py type=PY role=lib module=pir
u4: pir/__init__.py type=PY role=lib module=pir
u5: pir/parser.py type=PY role=lib module=pir
u6: pir/model.py type=PY role=lib module=pir
u7: templates/asm.py type=PY role=lib module=templates
u8: templates/java.py type=PY role=lib module=templates
u9: templates/rust.py type=PY role=lib module=templates
u10: templates/ld.py type=PY role=lib module=templates
u11: templates/python.py type=PY role=lib module=templates
u12: templates/__init__.py type=PY role=lib module=templates
u13: templates/common.py type=PY role=lib module=templates
u14: templates/c.py type=PY role=lib module=templates
u15: templates/riscv.py type=PY role=lib module=templates
u16: reconstruct/interface.py type=PY role=lib module=reconstruct
u17: reconstruct/relations.py type=PY role=lib module=reconstruct
u18: reconstruct/__init__.py type=PY role=lib module=reconstruct
u19: reconstruct/documentation.py type=PY role=lib module=reconstruct
u20: reconstruct/pipeline.py type=PY role=lib module=reconstruct
u21: reconstruct/audit.py type=PY role=lib module=reconstruct
u22: reconstruct/layout.py type=PY role=lib module=reconstruct
u23: reconstruct/structure.py type=PY role=lib module=reconstruct
u24: reconstruct/enrichment/asm.py type=PY role=lib module=enrichment
u25: reconstruct/enrichment/java.py type=PY role=lib module=enrichment
u26: reconstruct/enrichment/rust.py type=PY role=lib module=enrichment
u27: reconstruct/enrichment/ld.py type=PY role=lib module=enrichment
u28: reconstruct/enrichment/base.py type=PY role=lib module=enrichment
u29: reconstruct/enrichment/python.py type=PY role=lib module=enrichment
u30: reconstruct/enrichment/__init__.py type=PY role=lib module=enrichment
u31: reconstruct/enrichment/c.py type=PY role=lib module=enrichment
u32: writers/filesystem.py type=PY role=lib module=writers
u33: writers/graphviz.py type=PY role=lib module=writers
u34: writers/graphviz_pipeline.py type=PY role=lib module=writers
u35: writers/graphviz_module.py type=PY role=lib module=writers
u36: writers/mermaid.py type=PY role=lib module=writers
u37: writers/__init__.py type=PY role=lib module=writers
u38: writers/graphviz_pipeline_old.py type=PY role=lib module=writers
u39: writers/graphviz_arch.py type=PY role=lib module=writers
u40: writers/plantuml.py type=PY role=lib module=writers
u41: utils/constants.py type=PY role=lib module=utils
u42: utils/hash.py type=PY role=lib module=utils
u43: utils/ordering.py type=PY role=lib module=utils
u44: utils/__init__.py type=PY role=lib module=utils
</units>
<dependency-pool>
d0: import:[...pir.model]
d1: import:[..errors]
d2: import:[..pir.model]
d3: import:[..templates]
d4: import:[..utils.constants]
d5: import:[..utils.hash]
d6: import:[..writers.graphviz]
d7: import:[..writers.graphviz_arch]
d8: import:[..writers.graphviz_module]
d9: import:[..writers.graphviz_pipeline]
d10: import:[..writers.mermaid]
d11: import:[..writers.plantuml]
d12: import:[.]
d13: import:[.asm]
d14: import:[.audit]
d15: import:[.base]
d16: import:[.c]
d17: import:[.documentation]
d18: import:[.enrichment]
d19: import:[.errors]
d20: import:[.interface]
d21: import:[.java]
d22: import:[.layout]
d23: import:[.ld]
d24: import:[.model]
d25: import:[.pir.parser]
d26: import:[.pir.validator]
d27: import:[.python]
d28: import:[.reconstruct.pipeline]
d29: import:[.relations]
d30: import:[.rust]
d31: import:[.structure]
d32: import:[pir.model]
d33: import:[stdlib:py]
</dependency-pool>
<dependencies>
u1->refs:[d19 d25 d28 d26 d33]
u3->refs:[d24 d33]
u5->refs:[d24 d33]
u6->refs:[d33]
u12->refs:[d12]
u16->refs:[d3 d33]
u17->refs:[d10 d9 d22 d6 d11 d8 d7 d33]
u19->refs:[d33]
u20->refs:[d29 d1 d31 d20 d17 d14 d18 d33]
u21->refs:[d4 d5 d33]
u22->refs:[d2 d33]
u23->refs:[d33 d1]
u24->refs:[d15 d33 d0]
u25->refs:[d15 d33 d0]
u26->refs:[d15 d33 d0]
u27->refs:[d15 d33 d0]
u28->refs:[d33]
u29->refs:[d15 d33 d0]
u30->refs:[d30 d15 d21 d23 d27 d16 d13]
u31->refs:[d15 d33 d0]
u32->refs:[d33]
u42->refs:[d33]
u43->refs:[d32 d33]
</dependencies>
<symbols>
ReconstructionError:u0 class
ValidationError:u0 class
ParserError:u0 class
LayerError:u0 class
main:u1 func entry=true
ValidationError:u3 class
validate_pir:u3 func
parse_pir:u5 func
Unit:u6 class
Symbol:u6 class
Dependency:u6 class
DependencyEdge:u6 class
PIRAST:u6 class
asm_label_template:u7 func
asm_func_template:u7 func
java_method_template:u8 func
java_class_template:u8 func
rust_func_template:u9 func
rust_struct_template:u9 func
rust_enum_template:u9 func
rust_trait_template:u9 func
ld_entry_template:u10 func
ld_symbol_template:u10 func
python_func_template:u11 func
python_class_template:u11 func
format_attributes:u13 func
generate_pir_comment:u13 func
generate_todo_comment:u13 func
c_func_template:u14 func
c_struct_template:u14 func
riscv_label_template:u15 func
riscv_func_template:u15 func
riscv_csr_template:u15 func
riscv_trap_template:u15 func
riscv_memory_barrier_template:u15 func
InterfaceLayer:u16 class
RelationLayer:u17 class
DocumentationLayer:u19 class
ReconstructionPipeline:u20 class
AuditLayer:u21 class
MemoryRegion:u22 class
Section:u22 class
RISCVLayoutGenerator:u22 class
generate_riscv_linker_script:u22 func
extract_memory_layout:u22 func
StructureLayer:u23 class
ASMEnrichmentLayer:u24 class
JavaEnrichmentLayer:u25 class
RustEnrichmentLayer:u26 class
LDEnrichmentLayer:u27 class
BaseEnrichmentLayer:u28 class
PythonEnrichmentLayer:u29 class
CEnrichmentLayer:u31 class
FileSystemWriter:u32 class
emit_graphviz:u33 func
emit_pipeline_graph:u34 func
emit_module_graph:u35 func
emit_mermaid:u36 func
emit_arch_graph:u39 func
emit_plantuml:u40 func
hash_tree:u42 func
topological_sort:u43 func
stable_sort_by_uid:u43 func
</symbols>
</pir>