testcase-rag

面向持续迭代需求的增量测试用例生成工具。它从 Word 需求文档中提取功能点，比较新旧版本，只为新增或修改的功能生成用例；未变功能的历史用例保持不动。

解决的问题

需求文档往往会在一个项目周期内不断更新。传统的全量重新生成会带来两个问题：

• 未变功能的用例被反复改写，难以追踪历史，形成“用例漂移”。
• 新需求只简短引用旧模块时，生成模型缺少旧功能的背景，结果容易不完整。

本项目通过稳定功能点标识、内容哈希和向量检索解决这两个问题：

• 功能点正文未变化：保留原有用例，不调用大模型生成。
• 功能点正文变化：仅重新生成该功能点的用例。
• 新增功能点：仅为新增功能生成用例。
• 删除功能点：归档功能点及其用例，不直接删除历史记录。
• 重命名或移动功能点：优先通过路径和名称对齐，必要时通过向量相似度复用旧功能点标识。
• 新功能引用旧功能：召回相关旧功能正文，作为生成用例的上下文。

环境要求

• Python 3.12 及以上
• 已安装 uv
• DeepSeek API 密钥

安装依赖并准备配置：

uv sync
Copy-Item .env.example .env

在 .env 中配置：

DEEPSEEK_API_KEY=你的密钥

可选配置：

配置项	默认值	说明
DEEPSEEK_BASE_URL	https://api.deepseek.com	DeepSeek 接口地址
DEEPSEEK_MODEL	deepseek-v4-flash	用例生成模型
EMBEDDING_MODEL	BAAI/bge-small-zh-v1.5	本地向量模型
DB_PATH	./testcase_rag.db	SQLite 数据库文件位置

不要将 .env 提交到版本库。

快速开始

首次导入一个项目的完整需求文档：

uv run tcr ingest -p crm -v v1.0 "CRM需求说明书V1.0.docx"

首次导入会为文档中所有识别出的功能点生成用例，并输出到 out/：

• crm_v1.0.xlsx：测试用例 Excel。
• crm_v1.0.xmind：测试用例 XMind。
• crm_v1.0_changes.md：功能点变更清单。

查看已管理的项目及当前用例数量：

uv run tcr list

日常版本迭代

当需求文档更新后，使用相同的项目名、不同的版本号导入新版完整文档：

uv run tcr ingest -p crm -v v1.1 "CRM需求说明书V1.1.docx"

系统会把 v1.1 与 v1.0 自动比较：

文档变化	处理方式
原功能点内容完全不变	保留旧用例，不重新生成
原功能点正文发生变化	将旧用例保留为历史快照，生成新版用例
文档中新增 L4 功能点	为新功能生成用例
旧功能点在新版文档中消失	归档该功能点及其用例

generate 是 ingest 的同义命令：

uv run tcr generate -p crm -v v1.1 "CRM需求说明书V1.1.docx"

完整新版文档与增量小文档

当前版本的导入语义是“完整新版需求文档”。也就是说，v1.1 应包含该项目仍然有效的全部功能点。

不要把一份只描述新增需求的独立小文档直接作为同一项目的新版本导入。文档中未出现的旧功能会被系统判定为已删除并归档。

正确做法是先把新增内容合并进完整需求文档，再以新的版本号导入。独立增量文档模式尚未实现。

多项目管理

-p 或 --product 是自定义且唯一的项目标识。同一项目的所有版本必须使用同一个项目名；不同项目使用不同项目名，数据会在同一 SQLite 数据库中逻辑隔离。

uv run tcr ingest -p crm -v v1.0 "CRM需求.docx"
uv run tcr ingest -p claim-system -v v1.0 "理赔系统需求.docx"
uv run tcr ingest -p crm -v v1.1 "CRM需求V1.1.docx"

项目之间的功能点、用例、版本记录和向量召回不会互相影响。

Word 文档约定

解析器使用 Word 标题层级构建需求树：

• 使用 Heading 1 至 Heading 4，或等价的 Word 大纲级别。
• 默认把四级标题（L4）视为一个可独立生成用例的功能点。
• L2、L3 标题作为功能路径；L1 通常视为文档元信息，不进入功能路径。
• L4 标题下的正文和表格都会作为功能需求内容参与差异比较与用例生成。

保持功能标题与层级尽量稳定，可以提升跨版本对齐准确性。

跨功能依赖写法

当新功能 B 建立在已有功能 A 的基础上时，建议在 B 的功能点正文中显式声明依赖。系统会把 A 的需求全文和 active 用例注入 B 的生成上下文，生成 B 对 A 的入口、状态、权限、数据和异常联调用例，而不是重复生成 A 自己的纯功能用例。

可在 Word 正文中写：

依赖功能：客户画像/入口
依赖类型：页面入口、权限
依赖说明：订单确认从客户画像入口进入，继承登录态和客户上下文。

也可在功能点下使用两列表格：

字段	内容
依赖功能	客户画像/入口
依赖类型	页面入口、权限
依赖说明	继承登录态和客户上下文

依赖功能支持填写功能名称或“路径/功能名称”。同一项目中名称必须能唯一定位；存在同名功能时，应填写路径以消除歧义。

导入后，系统会保存 B 到 A 的依赖关系。只有文档显式声明并成功唯一匹配的关系会进入依赖图；名称匹配和向量相似度仍只用于补充上下文，不会自动认定为依赖关系。

向量检索的作用

项目不依赖独立向量数据库。功能点的向量保存在 SQLite 中，并通过余弦相似度进行本地匹配。

• 当功能点改名或移动位置时，向量相似度用于辅助匹配旧功能点，尽量保住历史用例归属。
• 当新增或修改功能引用了旧模块时，向量相似度用于召回相关旧功能正文，补充大模型生成用例所需的背景。

当前实现适合几百到几千个功能点的本地场景；更大规模可再接入专用向量索引。

导出当前用例库

不导入新文档，只导出当前项目的 active 功能点和用例：

uv run tcr export -p crm -n crm-current

生成：

• out/crm-current.xlsx
• out/crm-current.xmind

为不同项目使用不同导出名称，避免文件相互覆盖。

命令速查

# 导入首版或完整新版需求文档
uv run tcr ingest -p <项目名> -v <版本号> "<需求文档.docx>"

# 与 ingest 等价
uv run tcr generate -p <项目名> -v <版本号> "<需求文档.docx>"

# 导出当前项目用例
uv run tcr export -p <项目名> -n <导出名称>

# 查看全部项目统计
uv run tcr list

架构概览

• Domain：产品、版本、功能点、用例、差异和引用等纯数据模型。
• Storage：SQLite 与 SQLAlchemy 持久化，保存版本、功能点、用例快照和向量。
• Adapter：Word 解析、DeepSeek 调用、本地向量模型、Excel/XMind 导出。
• Engine：功能点对齐、差异比较、上下文召回、增量生成、合并和归档。
• CLI：ingest、generate、export、list 命令。

开发与检查

uv run pytest
uv run ruff check src tests
uv run mypy src

当前测试覆盖首次导入、跨版本增量生成、改名对齐、删除后恢复、多项目隔离、表格解析、用例归档和导出。

详细设计见 MVP 设计文档。