致谢与源代码归属 (Acknowledgements and Source Attribution)

[English](./README.en.md) | **中文**

# 致谢与源代码归属 (Acknowledgements and Source Attribution)

本项目参考或直接使用了以下开源项目的代码和设计，在此致谢：

### 1. RevitSdkSamples — Jeremy Tammik

本 RAG 项目的训练数据（SDK 示例代码）来自 Jeremy Tammik 的 [RevitSdkSamples](https://github.com/jeremytammik/RevitSdkSamples) 项目。

- **License**: MIT License
- **用途**: 提取 C# 示例代码用于 RAG 检索和 Golden Code 生成
- 原始版权和授权详情，请参阅本项目根目录下的 `NOTICE` 和 `LICENSE` 文件

### 2. mcp-servers-for-revit — sparx-fire & mcp-servers-for-revit

本项目的 Revit 插件（`mcp_bridge` 模块）基于 [mcp-servers-for-revit](https://github.com/mcp-servers-for-revit/mcp-servers-for-revit) 项目的 Revit Plugin 和 CommandSet 组件。

- **License**: MIT License — Copyright (c) 2026 sparx-fire, mcp-servers-for-revit
- **用途**: 直接使用其编译的 Revit 插件 DLL（RevitMCPPlugin、RevitMCPCommandSet）作为 Revit 端的 TCP Socket 服务和命令执行器
- **参考内容**:
  - `plugin/Core/SocketService.cs` — TCP JSON-RPC 2.0 通信协议
  - `commandset/Commands/ExecuteDynamicCode/` — Roslyn 动态代码编译执行
  - `command.json` — 24 个预置命令定义
- **原始项目**: Fork of [revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp)

---

# Revit API RAG

基于 Revit API 文档和 SDK 示例代码的 RAG（检索增强生成）系统，帮助开发者快速生成 Revit C# 插件代码。

## 2025.03 重大更新

### 项目重构
- 旧版代码（AutoDL 本地训练）已迁移至 [`legacy/`](./legacy/) 目录保留 — **[查看旧版完整文档及逻辑图](./legacy/README.md)**
- 新版 Pipeline 迁移至 **Google Colab** 运行，利用免费 GPU + Google Drive 存储
- 项目结构重新组织，分离 `pipeline/`（训练）和 `server/`（部署）

### 架构概览

```
revit-api-rag/
├── pipeline/              # 数据处理 & 训练（Colab 运行）
│   ├── run_all.ipynb      # 主训练 Notebook
│   ├── api_parser/        # API 文档解析
│   │   ├── parse_chm.py   # CHM HTML → 结构化数据
│   │   └── quality_agent.py  # LLM 质量剪枝
│   ├── sdk_parser/        # SDK 代码解析
│   │   ├── extract.py     # .cs 源码提取
│   │   └── quality_agent.py  # Golden code 生成
│   ├── embedder/          # 向量化
│   │   └── embed.py       # SQLite → ChromaDB
│   ├── retriever.py       # 两层检索器
│   └── llm_client.py      # LLM 客户端（OpenRouter）
├── mcp_bridge/            # Revit 交互桥接层
│   ├── router.py          # FastAPI 路由（SSE 流式生成、健康检查等）
│   ├── code_generator.py  # RAG 上下文组装 + LLM 代码生成
│   ├── interactive.py     # LLM 意图分类 + Revit 数据查询
│   ├── atom_registry.py   # Revit 查询/交互原语注册表（20 个原语）
│   ├── revit_client.py    # TCP JSON-RPC 2.0 客户端
│   ├── client_pool.py     # 连接池（单例 + 自动重连）
│   ├── sandbox.py         # C# 代码安全审查
│   ├── tool_store.py      # Solidified Tool 持久化（健康检查 + 自动降级）
│   └── frontend/          # Gradio Web UI
│       └── app.py         # 多步交互界面（Thinking + Pipeline + 代码执行）
├── intent_bridge/         # Intent Bridge Agent — 意图解析 + 参数收集
│   ├── slot_engine.py     # 核心引擎（动态 RAG + LLM Agent + 问答队列）
│   ├── skill_loader.py    # Skill 加载器（三层匹配 + 热重载）
│   ├── router.py          # FastAPI 路由（会话管理、意图解析）
│   ├── llm_adapter.py     # LLM 适配器（primary/fallback + 重试）
│   ├── models.py          # Pydantic 数据模型
│   └── schemas/
│       ├── intent_registry.yaml  # 轻量 intent 注册表（~65 行）
│       └── skills/               # 模块化 Skill 系统
│           ├── _base.md          # 全局规则（反幻觉、参数来源声明）
│           ├── patterns/         # 操作模式（8 个 Skill）
│           ├── workflows/        # 工作流蓝图（净高计算、数据导出）
│           └── standards/        # 企业规范
├── revit_plugin/          # Revit 2026 插件（C# / .NET 8）
│   ├── plugin/            # RevitMCPPlugin — TCP Socket 服务
│   └── commandset/        # RevitMCPCommandSet — 24 个预置命令
├── config/                # 配置
│   └── config.yaml
├── data/                  # 生成的数据库文件
│   ├── sqlite/            # SQLite（API + SDK 结构化数据）
│   └── legacy_db/         # 旧版数据库（保留参考）
├── server/                # Web 服务（部署用）
├── legacy/                # 旧版代码（AutoDL 时期）
└── docs/                  # 文档
```

## 数据处理 Pipeline

> V1 旧版 Pipeline 的详细逻辑图和 Prompt 设计请参考 [legacy/README.md](./legacy/README.md)

### API 文档处理

![RevitAPI 解析流程](./docs/images/RevitAPI.png)

```
Revit 2026 API CHM
    ↓ 7z 解压
HTML 文件 (~27000+ 页)
    ↓ parse_chm.py 解析
结构化数据 (name, summary, syntax, parameters, remarks...)
    ↓ quality_agent.py (Gemini Flash 剪枝)
revit_api.db (SQLite)
    ↓ embed.py
ChromaDB 向量库 (API)
```

- **解析**: 从 CHM 解压的 HTML 中提取类名、方法签名、参数、备注等结构化信息
- **剪枝**: 使用 Gemini Flash 对低质量/冗余条目进行清洗，保留高质量 API 参考
- **存储**: SQLite 存储全量结构化数据，ChromaDB 存储 `name + summary` 的语义向量

![数据库结构](./docs/images/RevitEembeddingDatabse.png)

### SDK 代码处理

![RevitSDK 解析流程](./docs/images/RevitSDK.png)

```
Revit SDK Samples (~200+ 项目)
    ↓ extract.py (tree-sitter 解析)
.cs 源码 → 类/方法提取
    ↓ quality_agent.py (Gemini 生成 Golden Code)
SDK golden code (JSON)
    ↓ SQLite 存储
revit_api.db (sdk_code 表)
    ↓ embed.py
ChromaDB 向量库 (Code)
```

- **提取**: 使用 tree-sitter 解析 C# 源码，提取类定义、方法签名、关键代码块
- **Golden Code**: LLM 阅读项目 README + 源码，生成精炼的示例代码
- **存储**: SQLite 存储 golden code + 元数据，ChromaDB 存储代码语义向量

### Embedding 策略
- **API 向量化**: `name + summary` → OpenRouter Embedding API → ChromaDB
- **Code 向量化**: `golden_code summary` → OpenRouter Embedding API → ChromaDB
- **检索**: 查询 → ChromaDB 语义搜索 (top_k) → SQLite 回查全文内容
- **重排序**: 可选 rerank 模型对结果精排

## RAG 检索 & 代码生成

![RAG 主流程](./docs/images/workflow.png)

```
用户查询: "创建结构柱"
    ↓ Query Rewriting (LLM 提取 

... (truncated)