2026Technology-Competition/docs/superpowers/plans/rag-task-3-report.md

RAG 迭代 Task 3 实现报告（含评审修订 D1 的 index_dir）

状态

GREEN — 已完成并通过测试

• 先写失败测试（RED：因 impact_rag.py 缺失触发 ModuleNotFoundError）
• 实现 ImpactRAG 及 D1 修订项 index_dir
• 重新运行测试：2 passed

Commit

feat(rag): 新增 ImpactRAG 索引/检索服务（含 index_dir）

涉及文件：

• src/genesis/rag/impact_rag.py（新增）
• tests/test_impact_rag.py（新增）

测试输出摘要

python -m pytest tests/test_impact_rag.py -q
2 passed in 2.86s

测试用例：

1. test_retrieve_returns_relevant_chunk：验证 index + retrieve 能做到 chunk 级语义召回（FakeEmbedder 词袋向量 + cosine），返回结果含 OrderController。
2. test_index_dir_reads_text_files：验证 index_dir 仅索引文本源文件（白名单扩展名），跳过 binary.bin 与非文本/空文件，返回索引片段数为 1，且可检索到内容。

自我审查

• index：将 (文件名, 文本) 切分为 chunk（默认 800 字，按段落聚合），前缀 [文件名]，批量 embed 后 store.add。
• index_dir（D1）：Path(root).rglob("*") 遍历，按扩展名白名单过滤，UTF-8 errors="ignore" 读取，跳过空文本与读取异常；返回实际索引文件数（即 sources 数，非 chunk 数 —— 与 brief 文档及测试断言 n == 1 一致）。
• retrieve：空查询直接返回 []；否则 embed 查询向量后调用 store.search。
• 测试中对 RagStore(":memory:") 采用 try/finally 包裹 close()，避免 ResourceWarning。

一句话摘要

实现 ImpactRAG 的 index/retrieve 与 D1 修订项 index_dir，2 项测试全绿，可为上传即索引（Task 5 接线）提供目录级源码索引能力。

顾虑

• 运行指定测试文件时，全局 pytest 覆盖率配置（要求 99%）会报 Required test coverage of 99.0% not reached，但本任务验证仅需 2 passed，不影响功能正确性；若 CI 以全量套件口径执行，需单独豁免或补充本模块覆盖率。
• index_dir 返回的是"索引文件数"而非"片段数"；brief 文档两处措辞略不一致（接口签名注释写"返回索引的片段数"，测试与示例暗示为文件数），当前实现以测试断言为准（文件数）。

修复后验证

状态

GREEN — 分支测试补全，覆盖率 100%

针对评审发现（空 query 行为未测 + fail_under=99 硬要求），补全 index/index_dir/retrieve 全部分支测试与防御性过滤，并更新 index_dir docstring 为"返回索引的文件数"。

修改摘要

涉及文件：

• src/genesis/rag/impact_rag.py
  • index：对 _split 结果过滤空片段（if piece.strip():），避免空向量噪声 chunk。
  • index_dir：docstring 由"片段数"更正为"文件数"；读取文本后叠加内容级跳过（空文本 if not text.strip(): continue、含 NUL 字节二进制误带扩展名 \x00 跳过）。
• tests/test_impact_rag.py：新增 10 个用例，覆盖空 query、空文本源、非目录 root、空文件、读取异常、大写扩展名、空目录、NUL 二进制、单段超长与多段拆行。

测试输出摘要

python -m pytest tests/test_impact_rag.py -q --cov=genesis.rag.impact_rag --cov-report=term-missing
src\genesis\rag\impact_rag.py      53      0     26      0   100%
12 passed in 0.28s

（注：若沿用全局 addopts 的 --cov=genesis，整体覆盖率会因只跑单文件而低于 99% 告警，但 impact_rag.py 本文件覆盖率为 100%、12 例全绿，符合本次验收口径。）

一句话摘要

补全 ImpactRAG 分支测试与防御后，impact_rag.py 达到语句/分支 100% 覆盖，原 2 例与新 10 例共 12 例全绿。