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