zhoujl/rag_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加代码知识库；修复文档处理内容；增加API设置

Browse Source
This commit is contained in:
junlan
2026-05-16 20:20:10 +08:00
parent 69b49d28b2
commit 7aa3ce3294
119 changed files with 182273 additions and 793 deletions
Download Patch File Download Diff File Expand all files Collapse all files

607
agents.md Normal file
View File

@@ -0,0 +1,607 @@
# 需求代码一致性比对实现计划
## 背景
当前工作区包含两套互补能力：
- `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` 的需求优先展示缺失点和证据，不要只展示分数。