rag_agent/agents.md

# 需求代码一致性比对实现计划

## 背景

当前工作区包含两套互补能力：

- `rag-web-ui`：基础的基于文档的 RAG 知识库平台，负责文档上传、文档切分、向量化检索、GraphRAG、SRS 需求抽取和测试内容生成。
- `RAG-TEST-TOOLS`：新增的代码知识库工具，负责 C/C++ 源码解析、函数级摘要、函数 embedding、调用图谱和功能需求检索。

目标是在两套能力之间新增“需求代码一致性比对”能力，用结构化需求作为输入，用代码知识库作为证据源，输出需求到代码的可追溯矩阵、覆盖状态、缺失点、冲突点和建议。

## 当前架构分析

### 文档知识库侧

核心路径：

- `rag-web-ui/backend/app/services/document_processor.py`
  - 支持 PDF、DOCX、Markdown、TXT 文档加载。
  - 使用 `RecursiveCharacterTextSplitter` 切分 chunk。
  - 写入 MySQL 的 `DocumentChunk`，同时写入 Chroma 或 Qdrant 向量库。
  - 在 `GRAPHRAG_ENABLED` 开启时将文本片段送入 GraphRAG。
- `rag-web-ui/backend/app/services/retrieval/multi_kb_retriever.py`
  - 支持多知识库召回。
  - 组合向量排名、关键词分数和可选 reranker。
- `rag-web-ui/backend/app/services/graph/graphrag_adapter.py`
  - 封装 `nano_graphrag`，提供 local/global 图上下文。
- `rag-web-ui/backend/app/tools/srs_reqs_qwen/`
  - 从 SRS 文档抽取结构化需求。
  - 结果落表到 `SRSExtraction` 和 `SRSRequirement`。
- `rag-web-ui/backend/app/models/tooling.py`
  - `SRSRequirement` 已包含 `requirement_uid`、`description`、`acceptance_criteria`、`requirement_type`、`interface_name`、`data_source`、`data_destination` 等字段。

文档侧已有优势：

- 能从需求文档抽取结构化需求。
- 能保留需求来源章节、需求类型和接口字段。
- 已有任务、历史记录、前端工具入口和测试生成链路。

文档侧不足：

- 只知道需求和文档证据，不知道代码实现。
- 文档 chunk 粒度不适合直接映射函数。
- GraphRAG 当前是文档实体关系图，不是代码调用图。

### 代码知识库侧

核心路径：

- `RAG-TEST-TOOLS/code_parser.py`
  - 使用 tree-sitter 解析 C/C++。
  - 提取函数、注释、代码片段、调用表达式、类名和继承信息。
- `RAG-TEST-TOOLS/graph_builder.py`
  - 遍历源码工程。
  - 生成 File、Function、Class 节点。
  - 生成 CONTAINS、CALLS、EXTENDS 等边。
  - 调用 LLM 生成函数逻辑流和摘要。
  - 调用 embedding 模型生成函数向量。
  - 输出图谱 JSON、FAISS 向量库和 metadata。
- `RAG-TEST-TOOLS/feature_retriever.py`
  - 加载代码 FAISS、metadata 和知识图谱。
  - 对自然语言需求做函数级语义检索。
  - 结合调用链和多约束提示词让 LLM 判断需求是否被实现。

代码侧已有优势：

- 以函数为最小证据单元，更适合需求到代码映射。
- 具备函数摘要、逻辑流、调用者、被调用者和文件定位。
- 已有功能需求检索雏形。

代码侧不足：

- 当前是独立脚本，不是 Web 后端服务。
- metadata 字段命名不统一，例如有的地方使用 `name/file`，有的地方期望 `function_name/file_path`。
- `llm_processor.py` 存在硬编码 API Key，必须治理。
- 对比结果没有持久化表、任务 API 和前端页面。

## 总体方案

新增一个一致性比对层，让文档知识库负责需求来源和需求结构化，让代码知识库负责代码证据和调用链。

```text
SRS 文档
  -> SRS 需求抽取
  -> SRSRequirement
  -> 一致性比对服务
  <- 代码函数检索、代码图谱、调用链
  <- RAG-TEST-TOOLS 代码知识库
  -> 需求代码追踪矩阵
```

一致性比对服务不应直接依赖 `RAG-TEST-TOOLS` 的交互式 CLI。推荐先消费其生成产物：FAISS、metadata、knowledge graph JSON。后续再逐步把代码知识库构建能力服务化。

## 输出目标

每条需求输出固定结构：

```json
{
  "requirement_uid": "REQ-001",
  "requirement_title": "需求标题",
  "requirement_type": "functional",
  "requirement_text": "需求描述",
  "verdict": "implemented",
  "coverage_score": 0.86,
  "confidence": 0.78,
  "matched_functions": [
    {
      "node_id": "Function:InitAttEnv",
      "name": "InitAttEnv",
      "file": "AttEnvMod.c",
      "start_line": 12,
      "end_line": 86,
      "similarity": 0.82,
      "role": "初始化姿态环境参数",
      "evidence_summary": "函数摘要或关键逻辑证据"
    }
  ],
  "covered_points": ["已覆盖的需求点"],
  "missing_points": ["缺失的需求点"],
  "conflict_points": ["与需求冲突的代码行为"],
  "call_chain_evidence": ["caller -> function -> callee"],
  "suggestion": "后续修改或验证建议",
  "raw_judgment": {}
}
```

判定枚举：

- `implemented`：代码证据充分，需求已完整实现。
- `partial`：有相关实现，但需求点或验收准则未完全覆盖。
- `missing`：未找到可支撑实现的代码证据。
- `conflict`：代码行为和需求描述存在明确冲突。
- `uncertain`：证据不足或召回质量不足，不能可靠判断。

## 关键设计原则

1. 先做离线可验证能力，再接 Web UI。
2. 代码证据必须包含函数名、文件、行号和摘要，不能只给 LLM 自由判断。
3. LLM 只能基于输入证据输出结论，证据不足必须允许 `uncertain`。
4. 检索召回和 LLM 判定分层实现，便于调参和测试。
5. 一致性结果要可追溯、可导出、可复跑。

## 实现阶段

### M1：标准化代码知识库产物

目标：让 `RAG-TEST-TOOLS` 输出稳定、完整、可被 Web 后端读取的代码证据。

任务：

1. 统一 metadata 字段。

   每个函数 metadata 至少包含：

   ```text
   node_id
   name
   qualified_name
   file
   start_line
   end_line
   signature
   summary
   logic_flow
   code_snippet
   calls
   called_by
   includes
   embedding_model
   embedding_dim
   ```

2. 在 `graph_builder.py` 的 `save_results` 中补齐 metadata。
3. 确认 `project_code_knowledge_graph.json` 中节点与 metadata 的 `node_id` 可以互相映射。
4. 修复字段兼容问题。

   兼容读取：

   ```text
   name -> function_name
   file -> file_path
   summary -> summary
   calls -> calls
   called_by -> called_by
   ```

5. 移除 `llm_processor.py` 中的硬编码 API Key。

   推荐配置来源：

   ```text
   DASHSCOPE_API_KEY
   DASH_SCOPE_API_KEY
   QWEN_API_KEY
   ```

6. 加一个非交互式构建入口。

   示例：

   ```text
   python -m rag_test_tools.build_code_kb --project C:/path/project --output C:/path/code_kb
   ```

第一阶段验收：

- 能稳定生成 FAISS、metadata、graph JSON。
- 每个检索结果都能定位到文件和行号。
- 不再出现硬编码密钥。

### M2：新增代码知识库 Adapter

目标：在 `rag-web-ui` 后端新增统一读取代码知识库的服务层。

建议新增目录：

```text
rag-web-ui/backend/app/services/code_kb/
  __init__.py
  schema.py
  adapter.py
  retriever.py
  graph.py
  formatter.py
```

职责：

- `schema.py`
  - 定义 `CodeFunctionEvidence`、`CodeSearchHit`、`CodeGraphContext`。
- `adapter.py`
  - 加载 FAISS、metadata、graph JSON。
  - 做字段兼容和基础校验。
- `retriever.py`
  - 调用 embedding 模型生成需求向量。
  - 对 FAISS 检索结果做阈值过滤和排序。
- `graph.py`
  - 根据 `node_id` 扩展 caller/callee，支持 1 到 2 跳。
- `formatter.py`
  - 将函数证据压缩为 LLM 可读上下文。

核心接口：

```python
class CodeKnowledgeBaseAdapter:
    def load(self, vector_path: str, metadata_path: str, graph_path: str) -> None:
        ...

    def search_functions(self, query: str, top_k: int = 8) -> list[CodeSearchHit]:
        ...

    def get_function(self, node_id: str) -> CodeFunctionEvidence | None:
        ...

    def expand_call_context(self, node_id: str, max_hops: int = 2) -> CodeGraphContext:
        ...
```

第二阶段验收：

- 后端服务能加载现有 `RAG-TEST-TOOLS` 产物。
- 输入一条自然语言需求，能返回函数证据列表和调用链上下文。
- 不依赖交互式 CLI。

### M3：实现离线一致性比对服务

目标：输入一次 SRS 抽取结果和代码知识库，输出 JSON 追踪矩阵。

建议新增目录：

```text
rag-web-ui/backend/app/services/consistency/
  __init__.py
  schema.py
  prompt.py
  scorer.py
  comparator.py
  exporter.py
```

比对流程：

```text
读取 SRSRequirement
  -> 构造需求查询文本
  -> 代码函数召回
  -> 调用链扩展
  -> 证据压缩
  -> LLM 结构化判定
  -> 评分融合
  -> 生成一致性结果
```

需求查询文本构造：

- 功能需求：

  ```text
  description + acceptance_criteria + section_title
  ```

- 接口需求：

  ```text
  interface_name + interface_type + data_source + data_destination + description
  ```

- 性能、可靠性、安全需求：

  ```text
  指标 + 条件 + 约束 + 异常处理 + description
  ```

LLM 判定 prompt 要求：

```text
你是需求代码一致性审查助手。
只能基于输入的需求、验收准则、函数摘要、代码片段、调用链证据判断。
不得补充未给出的代码事实。
证据不足时输出 uncertain。
输出严格 JSON，不要 Markdown。
```

LLM 输出字段：

```json
{
  "verdict": "implemented | partial | missing | conflict | uncertain",
  "confidence": 0.0,
  "covered_points": [],
  "missing_points": [],
  "conflict_points": [],
  "primary_evidence": [],
  "reasoning": "简要理由",
  "suggestion": "建议"
}
```

评分融合：

```text
coverage_score =
  semantic_score * 0.25
  + acceptance_coverage_score * 0.30
  + evidence_strength_score * 0.20
  + call_graph_score * 0.15
  + exact_match_score * 0.10
```

评分说明：

- `semantic_score`：召回函数相似度均值或最高值。
- `acceptance_coverage_score`：验收准则覆盖比例。
- `evidence_strength_score`：是否有代码片段、摘要、逻辑流、文件行号。
- `call_graph_score`：调用链是否支撑需求场景。
- `exact_match_score`：接口名、函数名、数据源、数据目的地、关键术语命中。

第三阶段验收：

- 能对一个 `srs_extraction_id` 的全部需求生成 JSON 结果。
- 每条需求都有 verdict、分数、匹配函数和缺失点。
- 对召回不足的需求不会误判为已实现。

### M4：数据库和 API 接入

目标：把离线能力接入 Web 后端任务体系。

建议新增表：

```text
code_knowledge_bases
  id
  user_id
  name
  project_path
  vector_path
  metadata_path
  graph_path
  status
  metadata_summary JSON
  created_at
  updated_at

consistency_jobs
  id
  user_id
  srs_extraction_id
  code_kb_id
  status
  total_requirements
  completed_requirements
  output_summary JSON
  error_message
  started_at
  completed_at
  created_at
  updated_at

consistency_results
  id
  job_id
  requirement_uid
  verdict
  coverage_score
  confidence
  matched_functions JSON
  covered_points JSON
  missing_points JSON
  conflict_points JSON
  call_chain_evidence JSON
  suggestion TEXT
  raw_judgment JSON
  created_at
  updated_at
```

API 设计：

```text
POST /api/consistency/code-kbs
GET  /api/consistency/code-kbs
GET  /api/consistency/code-kbs/{code_kb_id}
DELETE /api/consistency/code-kbs/{code_kb_id}

POST /api/consistency/jobs
GET  /api/consistency/jobs
GET  /api/consistency/jobs/{job_id}
GET  /api/consistency/jobs/{job_id}/results
GET  /api/consistency/jobs/{job_id}/export
```

创建任务请求：

```json
{
  "srs_extraction_id": 12,
  "code_kb_id": 3,
  "requirement_uids": ["REQ-001", "REQ-002"],
  "top_k": 8,
  "max_call_hops": 2,
  "min_similarity": 0.55
}
```

第四阶段验收：

- 能通过 API 注册代码知识库。
- 能创建异步一致性比对任务。
- 能查询任务状态和结果。
- 能导出 Excel 或 Markdown 报告。

### M5：前端页面

目标：让用户在 Web UI 中完成完整流程。

页面建议：

```text
需求代码一致性
  -> 选择 SRS 抽取任务
  -> 选择代码知识库
  -> 选择需求范围
  -> 启动比对
  -> 查看矩阵
  -> 展开单条证据
  -> 导出报告
```

矩阵列：

```text
需求 ID
需求标题
需求类型
判定结果
覆盖分
置信度
匹配函数数量
主要文件
缺失点数量
建议
```

详情面板：

```text
需求原文
验收准则
匹配函数
文件和行号
函数摘要
关键代码片段
调用链
覆盖点
缺失点
冲突点
模型判定理由
```

第五阶段验收：

- 用户不用离线脚本即可启动比对。
- 结果可筛选 `missing`、`partial`、`conflict`。
- 单条结果可展开查看证据。
- 报告可导出。

## 最小可行版本

如果要尽快跑通，按以下最小范围实现：

1. 不做前端。
2. 不新增完整代码知识库管理页面。
3. 使用现有 `RAG-TEST-TOOLS` 的三个文件作为输入：

   ```text
   satellite_rag.faiss
   satellite_rag_metadata.json
   project_code_knowledge_graph.json
   ```

4. 新增后端离线脚本或管理命令：

   ```text
   python -m app.services.consistency.run_compare \
     --srs-extraction-id 12 \
     --vector-path C:/VS_program/zjl/RAG-TEST-TOOLS/satellite_rag.faiss \
     --metadata-path C:/VS_program/zjl/RAG-TEST-TOOLS/satellite_rag_metadata.json \
     --graph-path C:/VS_program/zjl/RAG-TEST-TOOLS/project_code_knowledge_graph.json \
     --output consistency_report.json
   ```

5. 输出 JSON 和 Excel。

最小版本完成后，再接数据库任务和前端。

## 风险和治理项

### 编码问题

当前多个中文文件显示为乱码。实现新功能时必须使用 UTF-8 保存新文件，不继续扩大乱码范围。对已有乱码文件只在必要时局部修改，避免大范围重写。

### API Key 治理

`RAG-TEST-TOOLS/llm_processor.py` 当前存在硬编码 Key。实现前必须移除，统一使用环境变量或 `rag-web-ui` 的配置体系。

### 字段不一致

代码 metadata 字段需要兼容和标准化。Adapter 层必须做字段归一化，不要让一致性服务直接依赖原始字段名。

### 召回误判

向量相似度高不等于需求已实现。最终判定必须同时看验收准则、代码摘要、代码片段和调用链。

### LLM 幻觉

Prompt 要强制“仅基于证据判断”。当证据不足时输出 `uncertain`，不能为了完整性强行输出 `implemented`。

### 性能

需求数量多时，每条需求都调用 LLM 会慢。需要支持：

- top_k 限制。
- 证据压缩。
- 任务进度。
- 失败重试。
- 可选只比对选中的需求。

## 测试计划

### 单元测试

- metadata 字段归一化。
- FAISS 检索结果转换。
- 调用图扩展。
- verdict JSON 解析。
- coverage_score 计算。

### 集成测试

- 使用已有 SRS 抽取结果和 `RAG-TEST-TOOLS` 样例代码库跑完整比对。
- 校验每条结果都有 `requirement_uid`、`verdict`、`coverage_score`。
- 校验有匹配函数时必须包含文件和行号。

### 回归测试

- 文档上传和普通问答不受影响。
- SRS 抽取不受影响。
- 测试用例生成不受影响。

## 建议的实现顺序

1. 新增 `code_kb` Adapter，先只读现有产物。
2. 新增 `consistency` 离线 comparator。
3. 跑通样例需求到样例代码的 JSON 报告。
4. 加数据库表和 API。
5. 加 Excel/Markdown 导出。
6. 加前端页面。
7. 回头服务化 `RAG-TEST-TOOLS` 的代码知识库构建过程。

## 后续开发注意事项

- 不要把 `RAG-TEST-TOOLS` 的交互式菜单直接作为后端依赖。
- 先通过 Adapter 消费文件产物，后续再抽象构建服务。
- 所有新增 API 返回值必须可序列化，避免直接返回 FAISS、numpy 或 LangChain 对象。
- 一致性结果必须保留原始 LLM JSON，便于调试和复核。
- 对 `missing`、`partial`、`conflict` 的需求优先展示缺失点和证据，不要只展示分数。