内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/brand/qai_logo_horizontal_dark_1680.png">
<img alt="QAI Consultant" src="assets/brand/qai_logo_horizontal_1680.png" width="360">
</picture>
</p>
# QAI 咨询师
一款开源的 AI 代理，作为高级 QA 架构师 — 自动从简单的项目描述中生成 **测试策略**、**风险登记册**、**工作量估算报告** 和 **测试计划**，以及确定性的 **QA 文档质量审查** 和 **测试结果分析**，用于评估已存在的内容。同时也作为 **MCP 服务器** 提供服务，以便 Claude Code、Claude Desktop 和 claude.ai 可以在相同的标准和数字基础上进行 QA 工作。
> 🌐 **在线演示：** [quality-ai-consultant.streamlit.app](https://quality-ai-consultant.streamlit.app)
> 🔌 **新功能：** QAI 咨询师现已作为 MCP 服务器 — `uvx qai-consultant-mcp`。无需 API 密钥，无需 Pinecone。详见下文的 [MCP 服务器](#mcp-server-for-claude-code-claude-desktop-claudeai) 或 [PyPI 上的软件包](https://pypi.org/project/qai-consultant-mcp/)。
> 🤖 由 Anthropic 的 [Claude Code](https://claude.ai/code) 构建。
---
## 截图
### Web UI (Streamlit)
### CLI
---
## 快速入门
### 选项 A — 使用在线应用（无需设置）
👉 [quality-ai-consultant.streamlit.app](https://quality-ai-consultant.streamlit.app)
### 选项 B — 在本地运行
```bash
# 1. 克隆并安装
git clone https://github.com/gvasile29/qai-consultant.git
cd qai-consultant
pip install -r requirements.txt
# 2. 设置 API 密钥
cp .env.example .env
# 编辑 .env 并填写 4 个密钥（参见下面的先决条件）
# 3. 构建知识库（一次性，推送到 Pinecone）
python src/ingest.py
# 4. 运行
python src/cli.py # 终端 UI
streamlit run src/app.py # Web UI → http://localhost:8501
```
> 📖 完整的安装指南：[INSTALL.md](INSTALL.md)
---
## 问题
从头开始创建测试策略非常耗时，需要深厚的 QA 专业知识。大多数团队要么跳过这个步骤，要么做得很肤浅，要么花费数天研究方法论。
QAI 咨询师通过将成熟的 QA 方法论、行业标准（ISTQB、OWASP、ISO 26262、A-SPICE）和专家知识结合成一个 AI 代理，解决了这个瓶颈，该代理可以像经验丰富的 QA 架构师一样思考。
---
## 适用人群
- **QA 工程师** 需要结构化的测试策略指导
- **工程经理** 需要工作量估算和资源规划
- **开发团队** 没有专职 QA 架构师
- **QA 顾问** 希望加快交付速度
---
## QAI 咨询师生成的内容
从一个包含 11 个问题的简单对话中，QAI 咨询师自动生成 **四个文档**：
| 文档 | 内容 |
|---|---|
| ⚠️ **风险登记册** | 风险矩阵、可能性/影响分析、每个风险的缓解措施 |
| 📊 **工作量估算报告** | 基于 PERT 的分解、团队产能分析、置信度评分 |
| 📋 **测试策略** | 根据您的技术栈、方法和合规性量身定制的 ISTQB 对齐策略 |
| 📝 **测试计划** | IEEE 829 对齐的计划，包括入口/出口标准、时间表和 AI 工具监督 |
所有输出都保存为 Markdown 文件，并可用于 PDF 下载。
---
## 知识库
QAI 咨询师的建议基于现实的 QA 标准和方法：
- 📘 **ISTQB** — 14 个认证课程（CTFL、CTAL-TA、CTAL-TM、CTAL-TAE、CT-AI 等）
- 🔒 **OWASP** — WSTG v4.2、MASTG、Top 10 2021
- 🚗 **ISO 26262** — 汽车功能安全（ASIL 级别、HARA、V&V）
- 🏭 **A-SPICE** — 汽车 SPICE 过程参考模型（SWE.4、SWE.5、SWE.6）
- 📋 **IEEE 829** — 测试文档标准
- ⚙️ **ISO/IEC 25010** — 软件产品质量模型
- 🤖 **AI 测试规划** — 17 个现实世界的 AI SDLC 案例研究（2024-2025）
- 🧠 **专家知识** — 来自从业者的现实 QA 场景和经验教训
---
## 先决条件
QAI 咨询师 v2.0 运行在云 API 上 — 无需本地 GPU 或 Ollama。
您需要在 `.env` 文件中拥有四个 API 密钥（都有免费层）：
| 密钥 | 获取方式 |
|-----|----------------|
| `MISTRAL_API_KEY` | [console.mistral.ai](https://console.mistral.ai/) → API 密钥 |
| `OPENROUTER_API_KEY` | [openrouter.ai/keys](https://openrouter.ai/keys) |
| `PINECONE_API_KEY` | [pinecone.io](https://www.pinecone.io/) → API 密钥 |
| `PINECONE_INDEX_NAME` | 您的 Pinecone 索引名称（例如 `qai-consultant`，维度：384，指标：余弦） |
```bash
cp .env.example .env
# 编辑 .env 并填写所有四个值
```
---
## 架构
## 工作原理
```
您描述您的项目（11 个问题）
↓
QAI 从 Pinecone 检索相关知识（并行 RAG，3 个线程）
↓
QAI 分析您的上下文中的风险 → 风险登记册（Mistral API）
↓
QAI 使用 PERT + 行业基准估算工作量 → 工作量报告
↓
QAI 生成一个有 QA 标准支持的测试策略 → 测试策略（Mistral API）
↓
QAI 生成一个符合 IEEE 829 的测试计划 → 测试计划（Mistral API）
↓
四个文档准备好 Markdown + PDF 下载
```
LLM 调用使用 **Mistral API** 作为主要提供商，**OpenRouter** 作为自动备用。
---
## 接口
### Web UI（浏览器 — 推荐）
```bash
streamlit run src/app.py
```
或使用 **在线托管版本**：[quality-ai-consultant.streamlit.app](https://quality-ai-consultant.streamlit.app)
### CLI（终端）
```bash
python src/cli.py
```
### MCP 服务器（适用于 Claude Code、Claude Desktop、claude.ai）
QAI 咨询师也作为一个本地的、完全无密钥的 MCP 服务器 — `qai-consultant-mcp` 提供服务。无需 Pinecone，无需 Mistral/OpenRouter API 密钥：它在一个本地嵌入索引上运行知识库，并公开确定性的 QA 工作量估算，以便您的 AI 编码助手可以直接进行 QA 规划，无需单独的 LLM 调用。
```bash
uvx qai-consultant-mcp
```
**Claude Code：**
```bash
claude mcp add qai-consultant -- uvx qai-consultant-mcp
```
**Claude Desktop**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"qai-consultant": {
"command": "uvx",
"args": ["qai-consultant-mcp"]
}
}
}
```
**工具：**
| 工具 | 功能 |
|---|---|
| `retrieve_qa_knowledge` | 从知识库（ISTQB、OWASP、IEEE、ISO、欧盟 AI 法案）中获取知识片段，可按类别筛选 |
| `list_kb_sources` | 知识库中的每个文档，按类别分组 |
| `estimate_qa_effort` | 确定性基于 PERT 的工作量估算（无 LLM 叙述 — 您从数字中编写自己的叙述） |
| `review_qa_document` | 对现有的测试计划/策略/测试用例列表进行确定性 0-100 质量评分，涵盖六个 ISTQB/IEEE-829 维度，并附有发现 + 知识库引用 |
| `analyze_test_results` | JUnit XML/CSV 测试执行数据的确定性健康指标 — 容易失败的测试、一直失败的测试、最慢的测试、失败的集群 |
**提示：** `qa_project_interview`（该应用使用的相同 11 个问题访谈）、`risk_register_structure`、`test_strategy_structure`、`test_plan_structure` — 每个都在 `retrieve_qa_knowledge` 中将客户端的生成内容植入 `[来源 N]` 引用。
**隐私：** 默认情况下使用遥测数据已关闭。设置 `QAI_TELEMETRY=1` 以选择加入；即使如此，也只会发送工具名称/成功/持续时间和匿名安装 ID — 永远不会发送您的查询文本或项目详细信息。
---
## 反馈循环
每次生成后，QAI 都会询问：*“这个策略有用吗？”*
- **是** → 策略保存在 `knowledge_base/generated_strategies/` 中，并包含在下一次重新摄取中
- **部分** → 策略保存并附带您的改进笔记
- **否** → 丢弃
这会创建一个 **反馈循环**，QAI 会随着时间的推移从经过验证的现实输出中学习。
---
## 路线图
- **v0.1** ✅ 核心代理 + CLI + Streamlit Web UI
- **v0.2** ✅ 反馈循环 — 验证过的策略增长知识库
- **v0.3** ✅ 风险登记册 — 测试策略中的自动风险分析
- **v0.4** ✅ 工作量估算报告 — 基于 PERT 且包含团队产能分析
- **v0.5** ✅ 自动重新摄取 — 文件监视器 + 增量摄取 + 清单跟踪
- **v0.6** ✅ 置信度算法 — 基于评分（0-100）：PERT 传播 + 产能差距 + 数据质量 + 乘数幅度
- **v1.0** ✅ MVP — 错误处理、输入验证、日志记录、完整文档、测试、Apache 2.0 许可证
- **v2.0** ✅ 云迁移 — Ollama → Mistral API + OpenRouter 备用；ChromaDB → Pinecone；部署到 Streamlit Cloud
- **v2.0.1** ✅ 稳定性 — 修复 27 个错误：PERT 归一化、模板应用、PDF 缓存、会话状态、文件名清理、RAG 备用、每步异常隔离
- **v2.0.2** ✅ 稳定性 — 发布门控评估（估算完整性 + RAG 指标）、修复 5 个估算/验证缺陷、会话状态崩溃修复、叙述重复/截断修复、每步生成隔离以防止 LLM 中断
- **v2.5.0** ✅ 应用内发布说明 — 侧边栏面板 + 一次性“新增功能”横幅
- **v2.5.1** ✅ 知识库 — 新增 `evaluation_audit/` 支柱：过程/测试成熟度模型、审计方法论、安全/合规审计、现实公共失败案例研究
- **v2.5.2** ✅ 欧盟 AI 法案第 50 条透明度补丁 — 侧边栏 AI 交互通知 + 每个生成文档上的可见“AI 生成内容”标签
- **v2.6.0** ✅ 欧盟 AI 法案知识库支柱 — 风险层级、提供者/部署者义务、第 50 条透明度、文章 9-15 测试影响、一致性评估、时间线
- **v3.0.0** ✅ MCP 服务器 MVP — 本地、无密钥 `qai-consultant-mcp`（基于标准的检索 + 确定性工作量估算），应用内公告和机器可读 AI 生成标记（欧盟 AI 法案第 50(2) 条）
- **v3.1.0** ✅ 评估包 — QA 文档质量审查（确定性 ISTQB/IEEE-829 评分标准评估现有测试计划/策略/测试用例列表，可选 AI 叙述）和测试结果分析（JUnit XML/CSV 的 flaky/ever-failing/slowest/failure-clustering 指标，基于风险登记册的现实执行数据）；可在 Web 应用、CLI (`--review`, `--results`) 和 MCP 服务器 (`review_qa_document`, `analyze_test_results`) 中使用
- **v3.1.1** ✅ 访问计数器 — 侧边栏中显示的访问总数现在显示在 Pinecone 中，持续到重新部署
- **v3.1.2** ✅ 修复 — 3.1.1 版本的访问计数器实际上从未增加（Pinecone 拒绝其全零占位符向量）；现在正确运行
- **v3.1.3** ✅ 修复 — 访问计数器的标签是罗马尼亚语（“vizite”）而不是英语；现在读取“visits”以匹配应用 UI 副本的其他部分
- **v3.1.4** ✅ 在 `README_MCP.md` 中添加了 `mcp-name` 标记（PyPI 长描述）— `qai-consultant-mcp` 在官方 Anthropic MCP 注册表中列出的先决条件；无功能更改
- **v3.2** 远程 MCP + 分发 — 可连接的托管服务器来自 claude.ai、注册表提交
---
## 贡献
QAI 咨询师由 QA 社区为 QA 社区构建。
欢迎贡献：
- 📚 向 `knowledge_base/` 添加新的知识源
- 🧠 使用 `knowledge_base/expert_knowledge/` 中的提示分享专家知识
- 🐛 通过 GitHub 问题报告错误或建议功能
- 🔧 提交拉取请求
详见 [CONTRIBUTING.md](CONTRIBUTING.md) 中的详细指南。
---
## 故障排除
| 问题 | 解决方案 |
|---|---|
| "缺少必需的密钥：'MISTRAL_API_KEY'" | 将您的密钥添加到 `.env` 或 Streamlit Cloud 机密 |
| "缺少必需的密钥：'PINECONE_API_KEY'" | 将您的 Pinecone 密钥添加到 `.env` |
| "知识库为空" | 运行 `python src/ingest.py` 以将文档推送到 Pinecone |
| "Mistral API 和 OpenRouter 都不可用" | 检查 API 密钥是否有效且有积分 |
> 📖 完整的故障排除指南：[INSTALL.md](INSTALL.md#troubleshooting)
