# ai_pyclangd

**Repository Path**: lc168/ai_pyclangd

## Basic Information

- **Project Name**: ai_pyclangd
- **Description**: 计划使用ai调用 pyclangd
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyClangd AI Kernel Agent

> 基于 MCP（Model Context Protocol）+ Skill Prompt 工程的 Linux 内核智能分析助手

---

## 项目简介

本项目构建了一套完整的 **AI Agent 流水线**，使大语言模型（LLM）能够精准定位 Linux 内核中的符号定义（函数、宏、结构体等）。

核心思路：

1. 使用 `libclang` 对内核源码进行静态解析，将符号索引写入 SQLite 数据库
2. 基于 **MCP（Model Context Protocol）** 将数据库查询能力封装为标准工具
3. 通过 **Skill Prompt** 约束 LLM 的行为，强制其先查数据库再作答
4. Agent 框架实现工具动态派发，支持多工具扩展

---

## 技术栈

| 层次 | 技术 |
|------|------|
| 本地 LLM | Ollama + Gemma 4 |
| 工具协议 | MCP (Model Context Protocol) via `fastmcp` |
| Prompt 工程 | Skill Markdown（角色约束 + 调用逻辑） |
| 符号索引 | libclang 静态解析 → SQLite |
| 开发语言 | Python 3 |

---

## 项目结构

```
ai_pyclangd/
├── pyclangd_mcp.py       # MCP Server：将数据库查询封装为 LLM 可调用工具
├── clang_mcp_server.py   # MCP Server 扩展版（支持更多工具）
├── kernel_skill.md       # Skill Prompt：定义 AI 的角色和工具调用逻辑
├── symbol_expert.md      # Skill Prompt：Linux 内核符号专家角色
├── test_ai_agent.py      # Agent 主程序：工具动态派发 + 两轮对话
└── start_mcp.sh          # 一键启动脚本
```

---

## 核心实现

### 1. MCP Server（`pyclangd_mcp.py`）

使用 `fastmcp` 将 SQLite 查询封装为 LLM 工具：

```python
@mcp.tool()
def search_symbol(name: str) -> str:
    """在内核数据库中查询符号定义。"""
    query = "SELECT * FROM symbols WHERE name = ? AND role = 'def' LIMIT 3"
    ...
```

- 工具的 docstring 即为 LLM 的工具描述，自动传递给模型
- 符合 MCP 标准，可对接任意 MCP 客户端（Claude Desktop、VS Code 插件等）

### 2. Skill Prompt（`kernel_skill.md`）

```markdown
# Skill: Kernel Expert
1. 当用户询问内核函数或宏时，你必须使用 search_symbol 工具。
2. 严禁凭空想象源码路径。
3. 得到路径后，结合你的知识解释该符号在 RK3568 内核中的作用。
```

- 强制约束 LLM 行为，防止幻觉（hallucination）
- 与 `tools=[]` 参数配合，将"能调用工具"和"知道何时调用"分离设计

### 3. Agent 动态工具派发（`test_ai_agent.py`）

```python
TOOL_REGISTRY = {
    "search_symbol": search_symbol,
    # 扩展更多工具只需在此添加
}

tool_name = tool['function']['name']   # AI 自主选择的工具
fn = TOOL_REGISTRY.get(tool_name)
result = fn(**tool_args)               # 动态调用
```

- AI 自主决定是否调用工具及调用哪个工具
- 注册表模式，新增工具无需修改核心逻辑

---

## 运行效果

```
用户: 查找内核宏 CONFIG_COMMON_CLK_SCMI 的定义位置
--- AI 决定调用工具: search_symbol({'name': 'CONFIG_COMMON_CLK_SCMI'}) ---
AI 专家: CONFIG_COMMON_CLK_SCMI 定义于：
  文件: include/generated/autoconf.h，行号: 7，类型: MACRO_DEF
  该宏由 Kconfig 系统生成，表示内核启用了通过 SCMI 协议管理时钟的支持...
```

---

## 设计亮点

- **MCP 标准协议**：工具定义与 Agent 逻辑解耦，可复用于任意 MCP 兼容客户端
- **Skill + Tool 双轨机制**：Skill 控制"行为"，Tool 提供"能力"，职责清晰
- **动态派发**：单一 Agent 框架支持任意数量工具，扩展成本极低
- **幻觉抑制**：Skill 明确禁止模型猜测路径，所有路径来源均为真实数据库查询

---

## 数据库 Schema

```sql
CREATE TABLE symbols (
    file_path TEXT,   -- 源文件路径
    s_line    INTEGER, -- 起始行
    s_col     INTEGER, -- 起始列
    e_line    INTEGER, -- 结束行
    e_col     INTEGER, -- 结束列
    usr       TEXT,    -- 符号唯一标识（libclang USR）
    role      TEXT,    -- 角色: def / ref / inc
    name      TEXT,    -- 符号名
    kind      TEXT     -- 类型: MACRO_DEF / FUNCTION / STRUCT 等
);
```

---

## 环境依赖

```bash
pip install ollama fastmcp libclang
# 本地运行 Ollama 并拉取模型
ollama pull gemma4:e2b
```