# cppParser

**Repository Path**: xiazanliang/cpp-parser

## Basic Information

- **Project Name**: cppParser
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CppAnalyzer 🔍

**C++ 工业级源码分析器** — AST / CFG / DFG / CallGraph / 多层提示词 / 七层记忆系统 / 梦境引擎

> 让 AI 真正理解大型 C++ 工程代码 — 从代码解析到智能上下文生成，一站式解决方案

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://gitee.com/xiazanliang/cpp-parser)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-green.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-106%20passed-brightgreen.svg)]()

---

## ✨ 核心特性

### 🔬 代码分析引擎

| 能力 | 描述 |
|------|------|
| 🌳 **AST 抽象语法树** | 完整的C++语法树，支持类/模板/命名空间/宏等 |
| 🔀 **CFG 控制流图** | if/for/while/switch/goto/协程控制流 |
| 📊 **DFG 数据流图** | 变量定义-使用链、参数流、返回值流 |
| 🔗 **CallGraph 调用图** | 跨文件全局调用链，虚函数/函数指针/模板实例化 |
| 🧩 **模板元编程** | 模板定义/实例化/特化/SFINAE/C++20 Concepts |
| 📝 **宏定义分析** | #define追踪、展开链、条件编译、宏依赖图 |
| 🎯 **指针/引用别名** | Steensgaard/Andersen别名分析、智能指针、内存风险检测 |
| 🔄 **增量分析** | 文件变更检测，只重分析变更部分 |

### 🧠 智能上下文系统（v2.0 新增）

| 能力 | 描述 |
|------|------|
| 🏗️ **七层记忆系统** | M1~M7 七层记忆架构（项目/架构/会话/交互/自动/压缩/系统），参考 Claude Code 四层设计 |
| 💭 **梦境引擎** | Auto Dream 自动记忆整理 — 定位→采集→整合→修剪四阶段，门控触发，低可信度衰减 |
| 🗜️ **上下文压缩** | Token预算分配、符号折叠、结构合并、注意力引导、增量差异 |
| 🌐 **域感知引擎** | OS/API/网络/并发模型自动检测，域特定约束生成 |
| 📋 **L0-L8 多层提示词** | 八层提示词（L0域层→L7代码模式），域特定AI指令，注意力标记 |
| 🔗 **关系识别引擎** | 7-Pass 分析：继承/组合/聚合/关联/依赖/接口实现/友元/模块归属 |
| 📊 **类实例图** | UML风格可视化 + PlantUML + DOT 三格式输出 |
| 🏷️ **标注系统** | 标注+描述+标签+重要性+架构角色+AI提示，持久化存储 |

---

## 🏗️ 系统架构

```
┌──────────────────────────────────────────────────────────────────┐
│                   Vue3 + Element Plus + vis-network 前端          │
│  Dashboard │ ProjectList │ AnalysisView │ GraphView │ MemoryView │
├──────────────────────────────────────────────────────────────────┤
│                      FastAPI REST API 后端                        │
│  /api/projects │ /api/analysis │ /api/graph │ /api/relationships │ /api/memory │
├──────────────────────────────────────────────────────────────────┤
│                         智能上下文层 (v2.0)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │ 七层记忆系统   │  │  梦境引擎     │  │  上下文压缩器          │ │
│  │ M1~M7        │  │ 4-Phase Dream│  │ Token预算+符号折叠     │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │ 域感知引擎    │  │ 关系识别引擎  │  │  多层提示词生成器       │ │
│  │ OS/网络/并发  │  │ 7-Pass       │  │ L0~L7 八层             │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
├──────────────────────────────────────────────────────────────────┤
│  Layer 1: clangd 索引层 (全量快速索引 + 增量更新)                  │
│  Layer 2: libclang 深度分析层 (AST/CFG/DFG/高级)                  │
│  Layer 3: NetworkX 图计算层 (CallGraph/全局关系)                   │
└──────────────────────────────────────────────────────────────────┘
```

**三层分析架构：**

- **纯 libclang** 无法跨文件分析，1M LOC 内存爆炸
- **纯 clangd** 无法导出完整 AST/CFG
- **三层组合**：clangd 做索引和增量，libclang 做深度分析，graph 层持久化全局关系

---

## 🧠 七层记忆系统详解

参考 Claude Code 的四层记忆架构（CLAUDE.md / Auto Memory / Session Memory / Auto Dream），适配 C++ 项目分析场景：

```
┌─────────────────────────────────────────────────────┐
│  M7 SYSTEM    — 系统层: 全局配置、C++标准约束          │
│  M6 COMPRESSED— 压缩层: 梦境整合后的精炼知识            │
│  M5 AUTO      — 自动层: 自动提取的架构/模式/依赖         │
│  M4 INTERACTIVE— 交互层: 用户标注、AI反馈、人工修正      │
│  M3 SESSION   — 会话层: 当前分析会话的临时上下文          │
│  M2 ARCHITECTURE— 架构层: 模块划分、依赖关系、设计决策    │
│  M1 PROJECT   — 项目层: 项目元信息、目录结构、技术栈      │
└─────────────────────────────────────────────────────┘
```

**信息流向：** M1(原始) → M5(自动提取) → M6(梦境压缩) → M7(系统级)

---

## 💭 梦境引擎 (Auto Dream)

灵感来自 Claude Code 的 Auto Dream 特性 — 在空闲时自动整理和压缩记忆：

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  定位     │ →  │  采集     │ →  │  整合     │ →  │  修剪     │
│ Locate    │    │ Gather   │    │ Consolidate│   │ Prune    │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
  扫描低效记忆    收集相关条目     合并冗余/升级    删除过时/低信
  识别冗余模式    构建关联图谱     可信度条目       度记忆
```

**门控触发机制：**
- 时间门控：每小时间隔最多一次自动梦境
- 容量门控：记忆条目超过阈值触发
- 手动触发：API 显式调用
- 会话结束触发：分析完成后自动检查

---

## 📋 L0~L7 八层提示词

| 层次 | 名称 | 内容 | AI 指令 |
|------|------|------|---------|
| **L0** | 域层 | OS/API/网络/并发模型、C++标准、约束 | 域特定指令（如网络服务器: 背压/限流/优雅关闭） |
| **L1** | 概览层 | 项目目标、核心功能、技术栈、目录结构 | 先理解再修改 |
| **L2** | 架构层 | 模块划分、依赖关系、数据流向 | 遵循架构约束 |
| **L3** | 模块层 | 各模块职责、核心类、对外接口 | 模块内聚 |
| **L4** | 类设计层 | 继承体系、组合关系、设计模式 | 保持设计一致性 |
| **L5** | 接口层 | 纯虚类/接口、方法签名、契约 | 接口优先 |
| **L6** | 实现层 | 关键函数逻辑、算法、数据结构 | 正确实现 |
| **L7** | 代码模式层 | 编码约定、命名规范、内存管理策略 | 遵循惯例 |

**注意力标记：** 每层内容自动标记 `[CRITICAL]` / `[IMPORTANT]` / `[INFO]` 优先级

---

## 🚀 快速开始

### 方式一：一键安装（推荐）

**Linux/macOS:**
```bash
git clone https://gitee.com/xiazanliang/cpp-parser.git cpp-analyzer && cd cpp-analyzer
chmod +x install.sh && ./install.sh
```

**Windows:**
```cmd
git clone https://gitee.com/xiazanliang/cpp-parser.git cpp-analyzer && cd cpp-analyzer
install.bat
```

### 方式二：Docker（开箱即用）

```bash
cd cpp-analyzer
docker compose -f docker/docker-compose.yml up -d

# 打开 http://localhost:8000
```

### 方式三：手动安装

```bash
# 1. 安装 LLVM >= 16 (包含 clangd)
# Ubuntu: sudo apt install llvm-18 clangd-18 libclang-18-dev
# macOS:  brew install llvm
# Windows: winget install LLVM.LLVM

# 2. 安装 Python 依赖
pip install -r backend/requirements.txt

# 3. 分析项目
python cli/cppanalyzer analyze /path/to/cpp/project

# 4. 启动 Web 服务
python cli/cppanalyzer serve --port 8000
```

---

## 📖 使用指南

### CLI 命令

```bash
# 环境检查
cppanalyzer check

# 全量分析项目
cppanalyzer analyze /path/to/project

# 分析单个文件
cppanalyzer analyze /path/to/project --file src/main.cpp

# 分析单个函数
cppanalyzer analyze /path/to/project --function main

# 指定C++标准和别名算法
cppanalyzer analyze /path/to/project --std=c++17 --alias-algorithm=andersen

# JSON输出（用于程序化处理）
cppanalyzer analyze /path/to/project --json > result.json

# 构建索引（单独执行）
cppanalyzer index /path/to/project

# 启动Web服务
cppanalyzer serve --port 8000 --reload
```

### Python API

```python
from engine.analyzer import CppAnalyzer, AnalysisOptions

# 创建分析器（含记忆系统和梦境引擎）
options = AnalysisOptions(
    generate_ast=True,
    generate_cfg=True,
    generate_dfg=True,
    generate_call_graph=True,
    analyze_templates=True,
    analyze_macros=True,
    analyze_aliases=True,
    alias_algorithm="steensgaard",  # 或 "andersen"
    cxx_standard="c++20",
    enable_memory=True,             # 启用七层记忆系统
    enable_dream=True,              # 启用梦境引擎
    enable_compression=True,        # 启用上下文压缩
    max_prompt_tokens=8000,         # 提示词最大token数
)
analyzer = CppAnalyzer("/path/to/project", options)

# 全量分析
result = analyzer.analyze()
print(f"分析: {result.files_analyzed} 文件, {result.functions_analyzed} 函数")

# 查看记忆系统状态
if result.memory_stats:
    print(f"记忆条目: {result.memory_stats['total_entries']}")
    print(f"各层分布: {result.memory_stats['layer_distribution']}")

# 查看梦境报告
if result.dream_report:
    print(f"梦境阶段: {result.dream_report['phases']}")
    print(f"整合条目: {result.dream_report['consolidated']}")
    print(f"修剪条目: {result.dream_report['pruned']}")

# 获取压缩上下文
if result.compressed_context:
    print(f"压缩后Token: {result.compressed_context['total_tokens']}")

# 获取域画像
if result.domain_profile:
    print(f"OS: {result.domain_profile['os_type']}")
    print(f"网络模型: {result.domain_profile['network_model']}")
    print(f"并发模型: {result.domain_profile['concurrency_model']}")

# 单文件分析
result = analyzer.analyze_file("src/main.cpp")

# 单函数分析
result = analyzer.analyze_function("main")
```

### 记忆系统 API

```python
from engine.memory_system import MemorySystem, MemoryLayer, MemoryType

# 初始化记忆系统
mem = MemorySystem(project_root="/path/to/project", project_name="my-project")
mem.initialize()
mem.start_session("analysis")
mem.scan_project_context()

# 手动添加记忆
entry = mem.add_entry(
    layer=MemoryLayer.M4_INTERACTIVE,
    mtype=MemoryType.ANNOTATION,
    content="TcpServer 是核心网络模块，使用 Reactor 模式",
    keywords=["tcp", "reactor", "network"],
    confidence=0.95,
    importance=0.9,
)

# 搜索记忆
results = mem.search("reactor pattern", max_results=10)

# 构建AI上下文
context = mem.build_context(query="network architecture", max_tokens=4000)

# 获取统计
stats = mem.get_stats()
mem.end_session()
```

### 梦境引擎 API

```python
from engine.dream_engine import DreamEngine, DreamConfig

# 配置梦境引擎
config = DreamConfig(
    enabled=True,
    auto_trigger=True,
    min_interval_seconds=3600,  # 1小时间隔
    prune_confidence_threshold=0.3,  # 低于0.3的条目被修剪
    max_age_days=90,  # 90天以上的低频条目降级
)

engine = DreamEngine(memory_system=mem, config=config)

# 手动触发梦境
report = engine.dream(force=True)
print(f"定位: {report.located} 条目")
print(f"整合: {report.consolidated} 条目")
print(f"修剪: {report.pruned} 条目")
print(f"耗时: {report.duration_ms:.0f}ms")

# 检查并自动触发（门控）
engine.check_and_trigger()
```

### REST API

```bash
# 创建项目
curl -X POST http://localhost:8000/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"my-project","path":"/path/to/cpp/project","cxx_standard":"c++20"}'

# 启动分析
curl -X POST http://localhost:8000/api/analysis/project \
  -d '{"project_name":"my-project"}'

# 获取AST图数据
curl http://localhost:8000/api/graph/ast/my-project

# 获取CallGraph图数据
curl http://localhost:8000/api/graph/callgraph/my-project

# 记忆系统 API
curl http://localhost:8000/api/memory/my-project/stats
curl http://localhost:8000/api/memory/my-project/search?q=reactor
curl http://localhost:8000/api/memory/my-project/context?query=architecture&max_tokens=4000

# 触发梦境
curl -X POST http://localhost:8000/api/memory/my-project/dream

# 域画像
curl http://localhost:8000/api/memory/my-project/domain-profile

# 上下文压缩
curl http://localhost:8000/api/memory/my-project/compress?max_tokens=8000
```

---

## 📂 项目结构

```
cpp-analyzer/
├── engine/                          # 分析引擎核心
│   ├── analyzer.py                  # 主入口（统一调度器）
│   ├── clang_parser.py              # Layer 2: Clang集成
│   ├── ast_builder.py               # AST构建器
│   ├── cfg_builder.py               # CFG控制流图构建器
│   ├── dfg_builder.py               # DFG数据流图构建器
│   ├── call_graph.py                # CallGraph调用图构建器
│   ├── indexer.py                   # Layer 1: clangd索引引擎
│   ├── lsp_client.py                # LSP客户端
│   ├── advanced_analysis.py         # 模板/宏/别名高级分析
│   ├── architecture.py              # 架构设计文档
│   ├── relationship_engine.py       # 7-Pass 关系识别引擎
│   ├── class_instance_graph.py      # UML类实例图
│   ├── annotation_system.py         # 用户标注系统
│   ├── domain_awareness.py          # 域感知引擎 (v2.0)
│   ├── memory_system.py             # 七层记忆系统 (v2.0)
│   ├── dream_engine.py              # 梦境整合引擎 (v2.0)
│   ├── context_compressor.py        # 上下文压缩器 (v2.0)
│   └── prompt_generator.py          # L0~L7 多层提示词生成器 (v2.0 深度优化)
├── backend/                         # FastAPI后端
│   ├── app/
│   │   ├── main.py                  # 应用入口
│   │   └── api/
│   │       ├── projects.py          # 项目管理API
│   │       ├── analysis.py          # 分析服务API
│   │       ├── graph.py             # 图可视化API
│   │       ├── relationships.py     # 关系/标注API
│   │       └── memory.py            # 记忆/梦境API (v2.0)
│   └── requirements.txt
├── frontend/                        # Vue3前端
│   ├── src/
│   │   ├── App.vue
│   │   ├── main.js
│   │   ├── router.js
│   │   └── views/
│   │       ├── Dashboard.vue        # 仪表盘
│   │       ├── ProjectList.vue      # 项目管理
│   │       ├── AnalysisView.vue     # 分析配置
│   │       ├── GraphView.vue        # 图可视化
│   │       ├── ClassGraphView.vue   # 类图+标注+提示词
│   │       └── MemoryView.vue       # 记忆管理+梦境+上下文 (v2.0)
│   ├── package.json
│   └── vite.config.js
├── tests/
│   └── test_all.py                  # 106个测试用例
├── cli/
│   └── cppanalyzer                  # CLI工具
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── docs/                            # 详细文档
│   ├── architecture.md              # 架构设计
│   ├── memory-system.md             # 记忆系统设计
│   ├── dream-engine.md              # 梦境引擎设计
│   ├── context-compressor.md        # 上下文压缩设计
│   └── prompt-layers.md             # 提示词层次设计
├── install.sh                       # Linux/macOS一键安装
├── install.bat                      # Windows一键安装
├── CHANGELOG.md                     # 变更日志
├── CONTRIBUTING.md                  # 贡献指南
└── README.md
```

---

## 🔧 高级配置

### 分析选项

```python
from engine.analyzer import AnalysisOptions

options = AnalysisOptions(
    # 基础分析
    generate_ast=True,
    generate_cfg=True,
    generate_dfg=True,
    generate_call_graph=True,
    analyze_templates=True,
    analyze_macros=True,
    analyze_aliases=True,
    alias_algorithm="steensgaard",    # steensgaard | andersen | none
    cxx_standard="c++20",             # c++11 | c++14 | c++17 | c++20 | c++23

    # 关系识别
    analyze_relationships=True,

    # 记忆系统 (v2.0)
    enable_memory=True,               # 启用七层记忆系统
    enable_dream=True,                # 启用梦境整合
    dream_auto_trigger=True,          # 自动触发梦境

    # 上下文压缩 (v2.0)
    enable_compression=True,          # 启用上下文压缩
    max_prompt_tokens=8000,           # 提示词最大token数
)
```

### 梦境引擎配置

```python
from engine.dream_engine import DreamConfig

config = DreamConfig(
    enabled=True,
    auto_trigger=True,
    min_interval_seconds=3600,        # 自动梦境最小间隔(秒)
    capacity_threshold=1000,          # 记忆容量阈值(触发梦境)
    prune_confidence_threshold=0.3,   # 低于此可信度的条目被修剪
    max_age_days=90,                  # 超过此天数的低频条目降级
    merge_similarity_threshold=0.8,   # 相似度超过此值的条目合并
)
```

### 别名分析算法选择

| 算法 | 复杂度 | 精度 | 适用场景 |
|------|--------|------|----------|
| **Steensgaard** | O(n·α(n)) | 近似（流不敏感） | 百万行级项目，快速扫描 |
| **Andersen** | O(n³) | 精确（流不敏感） | 中小项目，需要精确结果 |
| none | - | 不做别名分析 | 只需AST/CFG |

### 编译数据库

CppAnalyzer 依赖 `compile_commands.json` 获取精确的编译选项：
- CMake: `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..`
- Make: `bear -- make`
- 自动生成：如果没有编译数据库，CppAnalyzer会自动扫描生成

---

## 📋 依赖

| 组件 | 版本要求 | 用途 |
|------|----------|------|
| LLVM/Clang | >= 16.0 | C++解析引擎 |
| clangd | >= 16.0 | 全量索引 + 增量更新 |
| Python | >= 3.10 | 分析引擎 + 后端 |
| libclang | >= 16.0 | Python Clang绑定 |
| NetworkX | >= 3.2 | 图计算 |
| FastAPI | >= 0.104.0 | Web后端 |
| Node.js | >= 18.0 | 前端构建（可选） |

---

## 🧪 测试

```bash
# 运行全部测试
python -m pytest tests/ -v

# 运行特定模块测试
python -m pytest tests/test_all.py -v -k "memory"
python -m pytest tests/test_all.py -v -k "dream"
python -m pytest tests/test_all.py -v -k "compressor"
python -m pytest tests/test_all.py -v -k "prompt"
python -m pytest tests/test_all.py -v -k "domain"
```

当前测试覆盖: **106 个测试用例**，覆盖记忆系统/梦境引擎/压缩器/提示词/域感知/关系/标注/集成测试

---

## 📄 License

MIT License

---

## 🙏 致谢

- **Claude Code** — 记忆系统架构和 Auto Dream 设计灵感
- **LLVM/Clang** — C++ 解析引擎
- **NetworkX** — 图计算框架
- **vis-network** — 图可视化