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