git clone https://github.com/your-org/cpp-semantic-graph.git
cd cpp-semantic-graph

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ...

bear -- make

project:
  name: "your_project"
  compile_commands: "/path/to/your/project/compile_commands.json"

# 源码范围 — 决定哪些代码算"项目代码"
source_paths:
  - "src"
  - "include"

# 生成代码路径（如 ARA COM src-gen、protobuf）
generated_paths:
  - "src-gen"

# 完全忽略的路径
exclude_paths:
  - "thirdparty"
  - "build"
  - "test/mock"

# libclang 路径（按你的系统调整）
libclang_path: "/usr/lib/llvm-18/lib/libclang.so.1"

parse_options:
  skip_function_bodies: false  # false 才能提取调用关系
  max_workers: 4               # 并行解析进程数

python3 -m cpp_semantic_graph full-parse \
  --config cpp_semantic_graph.yaml \
  --db semantic_graph_full.db

# 设置数据库路径
export CPP_GRAPH_DB=/path/to/semantic_graph_full.db

# 启动 MCP Server（stdio 传输）
python3 -m cpp_semantic_graph.mcp_server.server

{
  "mcpServers": {
    "cpp-semantic-graph": {
      "type": "stdio",
      "command": "python3",
      "args": ["/absolute/path/to/cpp-semantic-graph/mcp_server/run_server.py"],
      "env": {
        "CPP_GRAPH_DB": "/absolute/path/to/semantic_graph_full.db"
      }
    }
  }
}

{
  "mcpServers": {
    "cpp-semantic-graph": {
      "command": "python3",
      "args": ["/absolute/path/to/cpp-semantic-graph/mcp_server/run_server.py"],
      "env": {
        "CPP_GRAPH_DB": "/absolute/path/to/semantic_graph_full.db"
      }
    }
  }
}

cpp_search_class("SocUpdate")
→ ## 搜索结果：类 "SocUpdate"（1 个）
  ### update::SocUpdate
  - 文件: soc_update.h:15-120

cpp_search_function("PerformUpgrade", class_name="SocUpdate")
→ ## 搜索结果：函数 "PerformUpgrade"（1 个）
  ### SocUpdate::PerformUpgrade [virtual, override]
  - 签名: void PerformUpgrade() override
  - 文件: soc_update.cpp:45

cpp_get_inheritance("BasePeriUpdate", direction="down", depth=-1)
→ ## BasePeriUpdate 的子类（4 条）
  - update::SocUpdate --public--> BasePeriUpdate
  - update::McuUpdate --public--> BasePeriUpdate
  - ...

cpp_get_callers("GetSocBootChain")
→ ## 调用 "GetSocBootChain" 的代码（3 个）
  ### OtaManager::CheckBootChain
  - 文件: ota_manager.cpp:128
  - 调用类型: calls_direct

cpp_get_callees("PerformUpgrade", class_name="SocUpdate")
→ ## "PerformUpgrade" 调用的代码（8 个）
  ...

cpp_get_overrides("PerformUpgrade", class_name="BasePeriUpdate")
→ ## "PerformUpgrade" 的重写实现（4 个）
  ### update::SocUpdate::PerformUpgrade
  - 签名: void PerformUpgrade() override
  - 文件: soc_update.cpp:45
  - 重写基类: BasePeriUpdate

cpp_get_file_symbols("soc_update.h")
→ ## 文件符号：soc_update.h（共 12 个）
  ### 类/结构体（2 个）
    1. ### [class] update::SocUpdate
  ### 函数（10 个）
    ...

cpp_traverse_graph("SocUpdate", depth=2, max_results=30)
→ ## 遍历结果：从 "SocUpdate" 出发（18 个节点）
  深度: 2, 遍历边数: 22
  ### 关联节点
    - [class] update::SocUpdate (soc_update.h)
    - [class] update::BasePeriUpdate (base_peri_update.h)
    - [function] update::SocUpdate::PerformUpgrade (soc_update.cpp)
    ...

cpp_search_docs("升级", tag="架构设计")
→ ## 文档搜索："升级"（3 个结果）
  ### OTA 完整升级流程
  - 文件: docs/OTA_flow/OTA_COMPLETE_FLOW.md
  - 字数: 2450
  - 标签: 架构设计, OTA

  关联代码:
    - [class] BasePeriUpdate confidence=0.92
    - [class] SocUpdate confidence=0.88

# 搜索类
python3 -m cpp_semantic_graph search-class "SocUpdate"

# 查继承
python3 -m cpp_semantic_graph inheritance "BasePeriUpdate" --direction down --depth -1

# 搜索函数
python3 -m cpp_semantic_graph search-func "PerformUpgrade"

# 查文件符号
python3 -m cpp_semantic_graph file-symbols "soc_update.cpp"

# 查 include 依赖
python3 -m cpp_semantic_graph include "base_peri_update.h" --mode all

# 数据库统计
python3 -m cpp_semantic_graph stats

# 基于 git diff（默认 HEAD~1）
python3 -m cpp_semantic_graph incremental --base HEAD~1

# 手动指定文件
python3 -m cpp_semantic_graph incremental --files soc_update.cpp,base_peri_update.h

# 仅检测不执行
python3 -m cpp_semantic_graph incremental --files soc_update.cpp --dry-run

# 跳过文档关联重建（更快）
python3 -m cpp_semantic_graph incremental --files soc_update.cpp --skip-associations

┌─────────────────────────────────────────────────┐
│                  AI 工具层                       │
│  Claude Code / Cursor / Windsurf / 其他 MCP 客户端 │
└────────────────────┬────────────────────────────┘
                     │ MCP 协议 (stdio)
┌────────────────────▼────────────────────────────┐
│              MCP Server (9 工具)                 │
│  FastMCP + Lazy Init DB 连接 + Markdown 格式化    │
└────────────────────┬────────────────────────────┘
                     │ Python API
┌────────────────────▼────────────────────────────┐
│                查询层 (query/)                    │
│  GraphQuery │ CallQuery │ PolymorphismQuery      │
│  TraverseQuery │ DocQuery │ IncludeQuery          │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│             数据层 (db/)                         │
│  SQLite + 9 索引 + CASCADE 约束                  │
│  node │ edge │ include_dep │ parse_status        │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              解析层 (parser/)                     │
│  AST Visitor (libclang) │ CompileDB │ Config     │
│  ChangeDetector │ ImpactAnalyzer                 │
└─────────────────────────────────────────────────┘

1. ChangeDetector  ──→ 检测文件变更（git diff / 手动指定）
2. ImpactAnalyzer   ──→ 分析影响范围（.h → 递归 includer）
3. 删除旧数据        ──→ 删出边（不删共享节点）+ include_dep + parse_status
4. 重新解析          ──→ SemanticExtractor.parse() × 受影响 TU
5. upsert 新数据     ──→ 节点更新/边去重
6. 清理残留节点      ──→ 删除文件中已消失的函数/类
7. 重建文档关联      ──→ content_scan（可选 embedding）

doc_dirs:
  - "docs/"

exclude_patterns:
  - "*.html"
  - "*/build/*"

# 按目录自动打标签
tag_rules:
  - path_pattern: "architecture/**"
    tags: ["架构设计"]
  - path_pattern: "api/**"
    tags: ["接口规约"]

section_split:
  min_level: 2          # 按 ## 切片
  min_word_count: 20    # 少于 20 字的切片合并

# 手动精准关联（不侵入文档原文）
manual_links:
  - doc: "architecture/OTA_FLOW.md"
    heading: "升级流程"
    code:
      - "BasePeriUpdate"
      - "SocUpdate"
      - "PerformUpgrade"

pip install sentence-transformers

python3 -m cpp_semantic_graph full-parse \
  --config cpp_semantic_graph.yaml \
  --validate \
  --baseline validation/clangd_baseline.json

# 核心依赖
pip install clang PyYAML mcp

# 文档融合（可选）
pip install sentence-transformers

pip install -r requirements.txt        # 核心
pip install -r requirements-docs.txt   # 文档融合（可选）

cpp_semantic_graph/
├── __init__.py                  # 包声明
├── __main__.py                  # python -m 入口
├── cli.py                       # CLI 工具（search/inheritance/incremental/...）
├── pipeline.py                  # 全量解析流水线
├── incremental_updater.py       # 增量更新编排器
│
├── parser/                      # 解析层
│   ├── ast_visitor.py           #   AST 提取器（libclang）
│   ├── config.py                #   项目配置加载
│   ├── compile_db.py            #   compile_commands.json 解析
│   ├── change_detector.py       #   文件变更检测（git diff）
│   ├── impact_analyzer.py       #   影响范围分析
│   ├── doc_parser.py            #   文档解析器
│   ├── doc_association.py       #   文档-代码关联
│   ├── association_ingester.py  #   关联边入库
│   └── models.py                #   数据模型
│
├── query/                       # 查询层
│   ├── graph_query.py           #   类/函数/文件符号查询
│   ├── call_query.py            #   调用关系查询
│   ├── polymorphism_query.py    #   多态体系查询
│   ├── traverse.py              #   多跳遍历查询
│   ├── doc_query.py             #   文档融合查询
│   ├── include_query.py         #   include 依赖查询
│   ├── architecture_query.py    #   架构概览查询
│   └── fusion_query.py          #   融合查询
│
├── db/                          # 数据层
│   ├── graph_db.py              #   SQLite 操作
│   ├── importer.py              #   JSON→SQLite 导入
│   ├── schema.sql               #   建表+索引
│   └── relation_types.py        #   关系类型枚举
│
├── mcp_server/                  # MCP Server
│   ├── server.py                #   FastMCP Server + 9 工具
│   └── run_server.py            #   启动脚本
│
├── validation/                  # 正确性验证
│   ├── accuracy_validator.py    #   精度验证器
│   └── clangd_baseline.py       #   clangd 基线
│
├── config/                      # 配置模板
│   ├── doc_config.yaml          #   文档配置示例
│   └── template_whitelist.yaml  #   模板白名单
│
└── cpp_semantic_graph.yaml      # 项目配置（用户编写）

# 查看 clang 版本
clang --version

# 对应的 libclang 路径
ls /usr/lib/llvm-*/lib/libclang.so*