EN

FreeReq

一个免费的开源需求管理工具。

我需要一个工具来管理个人的开源项目需求，但找不到合适的工具。因为大部分的需求管理工具都是收费的，并且比较重型。我期望的工具是这样的：

1. 免费，轻量级

2. 需求文件必须存储在本地，不能接受在线使用

3. 保存的需求文件必须为文本文件，即使不使用特定工具也能阅读，并且有利于git管理

4. 以树形的结构组织需求文档

5. 它应该支持Markdown编辑

由于找不到这样的工具，所以我决定自己写一个。

介绍

FreeReq可以将需求文档组织成树形结构。一个需求文档可以包含子需求文档。

一个需求文档包含以下基本信息：

• UUID - 文档唯一标识

• Req ID - 文档的需求ID（唯一的，不重复）

• Title - 文档标题，做为树的节点名

• Content - 文档内容，以Markdown格式编辑

• Last Editor - 最后一个编辑者，程序应自动读取系统用户名

• Last Updater Time - 最后的编辑时间，程序应自动填入保存时间

此外，用户还可以自定义字段，这些字段统称为Meta Data，这些数据会成为需求文档的一部分。

详细的需求说明可以参考FreeReq.req文件。

如何运行

你可以下载打包好的release exe直接运行，优点是方便，缺点是：

• 体积较大

• markdown的显示效果不好

因为打包成exe后QtWebEngine会丢失，导致HTML渲染效果不好

• 不支持插件功能

推荐的方式是直接用python运行FreeReq.py，

• 你可以使用pip install -r requirements.txt安装所有依赖。

• 或者直接运行“run.bat”来创建虚拟环境并自动安装依赖（推荐）。

如果运行不正常，可以删除“env”文件夹并重新运行“run.bat”

插件

FreeReq支持插件扩展。你可以将“doc/config_example.json”重命名为“config.json”并将其放在FreeReq根目录中。编辑它以启用更多插件。

当前已实现的插件如下：

ScratchPaper

有时候我们需要复制粘贴一些固定格式的文本，这个插件就是用来缓存常用文本的。

当该插件使能后，界面上会增加一个“ScratchPaper”按钮，点击该按钮打开草稿纸窗口。 你可以在草稿纸中加入预设的文本，其中的内容会自动保存，下次运行FreeReq时会自动载入。

ReqHistory

这个插件会在每次保存时将保存前的需求文件备份一份到backup目录，并保持最新的30个历史文件。

这个插件没有操作入口，只要使能便会在后台生效。

MarkdownStyle

这个插件能让用户自由选择Markdown渲染的风格。

当该插件使能时，界面上会增加一个选择框，里面会列出“plugin/MarkdownStyle”目录下所有的.css文件。 当你选择了一个样式文件后，Markdown预览窗口显示会实时更新为你选择的风格。

你也可以向”plugin/MarkdownStyle“目录加入你喜欢的CSS风格文件。

ResourceManager

该插件用以方便地清理attachment目录下未被引用的文件，以及检查文档中引用的图片和附件资源是否有效。

这个插件会列出现存的资源文件以及文档中引用的文件，并会检查其状态：

• OK - 文档中引用的文件有效

• Invalid - 文档中引用的资源不存在

• No Reference - 资源文件未被文档引用

该插件还提供一键清理功能，点击后会将attachment目录下状态为“No Reference ”的文件删除。

EmbeddingIndexing

基于KeyFaiss，使用embedding对需求项进行索引。借助向量数据库，用户可以通过自然语言对需求文档进行搜索。

请注意，embedding模型会影响搜索结果。理论上根据不同的语言，需要在程序中选择对应的embedding模型（需要改代码）。

这个插件需要faiss和text2vec库支持。

TestcaseLink

选择一个文件夹，扫描其中的文件，建立从Req ID到测试用例文件的映射。

当打开一个Req文件时，如果该目录下同时存在 Testcase 目录，该插件会自动扫描该目录。否则需要用户手动指定测试用例所在的文件夹。

当用户选择需求条目后，会根据Req ID显示该需求对应的测试用例列表。双击列表中的条目可以打开对应的测试用例文件。

索引器（扫描器）置于 plugin/TestcaseIndexer 默认实现了一个TestcaseFileNameScanner，适用于Req ID体现于测试用例文件名中的情况。

如果需要通过扫描文件内容获取该测试用例引用的Req ID，请替换 _extract_req_id_from_filename。

ChatReq - 和AI聊需求，最酷炫的功能

基于EmbeddingIndexing插件的搜索结果，使用LLM和用户进行对话。

理论上，有了嵌入搜索结果和正确提示。我们可以使用任何LLM来实现此功能。 LLM越强大，效果越好。

现在支持以下LLM：

• ChatGLM3

• 类ChatGPT API的LLM网络服务

该插件基于gradio提供网页聊天功能，选择不同的LLM需要修改代码。

更新

20230711

• 添加搜索功能，通过CTRL+F快捷键打开搜索窗口，可以搜索整个树和所有内容（F3 查找下一个，SHIFT + F3 查找上一个）
• 编辑器可以接受文件拖放。
• 编辑器支持图像和表格粘贴。
• 使用 QWebEngineView 进行 markdown 预览（可选），它比 QTextView 更好看。

20240117

• 添加打包脚本（build.py, clean.py）。
• 已知问题：pyinstaller对QtWebEngine支持不好，因此在exe中无法使用WebView，影响观感。

20240227

• 使用Chat-GLM2，调试和更新ChatReq插件
• 添加打印树功能。注意此功能依赖于 QWebEngineView。
• 添加MarkdownStyle插件。

20240305

• 修复拖动资源进入编辑器后的光标问题。

20240626

• 添加 ReqHistory 插件
• 添加 ResourceManager 插件
• 添加需求文件更改监视
• 添加 Req ID 批量分配
• 改进 ChatReq：添加 ChatLLM.py 和 WebChat.py

20240902

• 将程序界面框架改为QMainWidget并增加菜单功能
• 可以直接通过菜单新建Req文件，包括按模板新建Req文件
• 优化Markdown中打开链接的方法，在使用QWebEngineView的情况下可以直接调用系统命令打开链接中的文件

20240909

• 增加Meta Data统计表功能
• 增加展开/折叠树节点功能

20240912

• 增加TestLink功能，并加入基于文件名的TestcaseIndexer。如果需要分析内容获取测试用例对应的Req ID，可以按提示修改Indexer。
• 为了实现TestLink功能，增加了Hookable，并且改进了Observer的通知机制。

20241107

• 增加行号显示
• 增加编辑框搜索功能，原全局搜索需要焦点在树控件上按CTRL+F，或使用SHIFT + CTRL + F打开。

20250722

• 为全局搜索增加搜索选项
• 增加req内部跳转链接（req://<>）
• 增加复制需求项的UUID功能。

使用方法