qai-consultant-mcp

QAI Consultant

一款开源 AI Agent，担任资深 QA 架构师——只需简单的项目描述，即可自动生成测试策略、风险登记册、工作量估算报告和测试计划；还可对现有内容进行确定性的QA 文档质量审查、测试结果分析和QA 成熟度评估。此外，它也可作为本地 MCP 服务使用，让 Claude Code、Claude Desktop 和其他 MCP 客户端依据相同的标准和数据开展 QA 工作。

🌐 在线演示：quality-ai-consultant.streamlit.app

🔌 MCP 服务：uvx qai-consultant-mcp——无需 API 密钥，也无需 Pinecone。请参阅下方的 MCP 服务或 PyPI 上的软件包。

🤖 由 Anthropic 的 Claude Code 构建。

---

截图

Web UI（Streamlit）

首页

侧边栏中的 MCP 面板

项目探索对话（已应用 Web 应用模板）

执行摘要 + 生成状态

风险登记册（风险台账表格）

工作量估算

测试策略

测试计划

QA 文档质量审查

QA 成熟度评估

CLI

---

快速开始

选项 A — 使用在线应用（无需设置）

👉 quality-ai-consultant.streamlit.app

选项 B — 在本地运行

# 1. Clone and install
git clone https://github.com/gvasile29/qai-consultant.git
cd qai-consultant
pip install -r requirements.txt

# 2. Set up API keys
cp .env.example .env
# Edit .env and fill in the 4 keys (see Prerequisites below)

# 3. Build the knowledge base (one-time, pushes to Pinecone)
python src/ingest.py

# 4. Run
python src/cli.py            # Terminal UI
streamlit run src/app.py     # Web UI → http://localhost:8501

📖 完整安装指南：INSTALL.md

---

问题

从头创建测试策略既耗时，又需要深厚的 QA 专业知识。大多数团队要么跳过这一步，要么草草了事，要么花上数天研究各种方法。

QAI Consultant 通过将成熟的 QA 方法、行业标准（ISTQB、OWASP、ISO 26262、A-SPICE）和专家知识融入一个以资深 QA 架构师方式思考的 AI Agent，消除了这一瓶颈。

---

适用对象

• QA 工程师，需要测试策略方面的结构化指导
• 工程经理，需要工作量估算和资源规划
• 开发团队，没有专职 QA 架构师
• QA 顾问，希望加快交付速度

---

QAI Consultant 生成的内容

通过一次包含 11 个问题的对话，QAI Consultant 会自动生成 四份文档：

文档	内容
⚠️ 风险登记册	风险矩阵、可能性／影响分析、每项风险的缓解措施
📊 工作量估算报告	基于 PERT 的细分估算、团队产能分析、置信度评分
📋 测试策略	根据你的技术栈、方法论和合规要求量身定制，并符合 ISTQB 标准
📝 测试计划	符合 IEEE 829 标准的计划，包含进入／退出准则、时间表和 AI 工具监督

在四个标签页上方，执行摘要会概述总体风险、QA 工作量范围、团队产能、置信度和排名前 3 的风险——这些内容根据风险登记册和工作量估算，以确定性方式计算，不会额外调用大模型。

所有输出都会保存为 Markdown 文件，并可下载为 PDF。

评估现有内容（以确定性方式评分，无需调用大模型）：

模式	功能
📝 QA 文档质量审查	从六个 ISTQB／IEEE 829 维度对现有测试计划／策略／测试用例列表进行 0–100 分评分，并提供发现和知识库引用
🧪 测试结果分析	根据 JUnit XML／CSV 分析不稳定、曾失败、从未运行和最慢的测试，并对失败进行聚类——还可选择用真实执行数据为风险登记册提供依据
📈 QA 成熟度评估	根据自由文本描述，在 10 个过程领域评估参考性 TMMi 等级（1–3），并检查 AI/ML 系统对《欧盟 AI 法案》第 9–15 条的准备情况

---

知识库

QAI Consultant 的建议以真实的 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 — Automotive SPICE 过程参考模型（SWE.4、SWE.5、SWE.6）
• 📋 IEEE 829 — 测试文档标准
• ⚙️ ISO/IEC 25010 — 软件产品质量模型
• 🇪🇺 《欧盟 AI 法案》 — 风险等级、提供者／部署者义务、第 50 条透明度要求、第 9–15 条对测试的影响
• 🧭 测试方法论 — 敏捷、BDD/TDD、探索式测试、基于风险的测试、测试金字塔
• 🔍 审计与过程评估 — TMMi、CMMI、ISO/IEC 33002、ISO 19011、OWASP ASVS、ISO 27001、SOC 2，以及公开的失败案例研究（Knight Capital、Boeing 737 MAX MCAS、CrowdStrike 2024）
• 🤖 AI 测试规划 — 17 个真实 AI SDLC 案例研究（2024–2025）
• 🧠 专家知识 — 来自从业者的真实 QA 场景和经验教训

---

前置条件

QAI Consultant 基于云 API 运行，无需本地 GPU。

你需要在 .env 文件中配置四个 API 密钥（均提供免费套餐）：

密钥	获取位置
MISTRAL_API_KEY	console.mistral.ai → API Keys（默认模型 ministral-14b-2512 可使用 Mistral 的免费套餐）
OPENROUTER_API_KEY	openrouter.ai/keys（备用；仅使用免费模型）
PINECONE_API_KEY	pinecone.io → API Keys
PINECONE_INDEX_NAME	你的 Pinecone 索引名称（例如 qai-consultant，维度：384，度量：cosine）

cp .env.example .env
# Edit .env and fill in all four values

---

架构

工作原理

You describe your project (11 questions)
        ↓
QAI retrieves relevant knowledge from Pinecone (parallel RAG, 3 threads)
        ↓
QAI analyzes risks from your context → Risk Register (Mistral API)
        ↓
QAI estimates effort using PERT + industry benchmarks → Effort Report
        ↓
QAI summarizes risk, effort, capacity and top risks → Executive Readout (no LLM)
        ↓
QAI generates a Test Strategy backed by QA standards → Test Strategy (Mistral API)
        ↓
QAI generates an IEEE 829-aligned Test Plan → Test Plan (Mistral API)
        ↓
Four documents ready for Markdown + PDF download

大模型调用主要使用 Mistral API（ministral-14b-2512），并自动回退到 OpenRouter 免费模型（Nemotron 3 Super → GLM 5.2）。

---

界面

Web UI（浏览器 — 推荐）

streamlit run src/app.py

你也可以使用在线托管版本：quality-ai-consultant.streamlit.app

除测试策略流程外，首页和侧边栏还提供审查现有 QA 文档和评估 QA 成熟度；生成内容前，可以在审查页面附加测试执行结果。

CLI（终端）

python src/cli.py                                   # interactive Test Strategy flow
python src/cli.py --results run1.xml run2.xml       # same flow, grounded in JUnit XML/CSV results
python src/cli.py --review path/to/test_plan.md     # QA Document Quality Review
python src/cli.py --maturity path/to/process.txt    # QA Maturity Assessment

MCP 服务（适用于 Claude Code、Claude Desktop 和其他 MCP 客户端）

已列入官方 MCP 注册表（io.github.gvasile29/qai-consultant-mcp）、Glama 和 Awesome MCP Servers。

QAI Consultant 也可作为本地、完全无需密钥的 MCP 服务使用—— qai-consultant-mcp。无需 Pinecone，也无需 Mistral/OpenRouter API 密钥：它会基于知识库中的 Markdown 文档构建本地嵌入索引（出于许可原因，不包含 ISTQB 和 OWASP PDF），并提供确定性的 QA 工作量估算、文档审查、测试结果分析和成熟度评估，让你自己的 AI 助手可以直接基于这些内容开展 QA 工作，无需单独调用大模型。它通过 stdio 在本地运行（需要 uv）；可从 claude.ai 连接的托管版本已列入路线图（v4.0）。

uvx qai-consultant-mcp

Claude Code：

claude mcp add qai-consultant -- uvx qai-consultant-mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "qai-consultant": {
      "command": "uvx",
      "args": ["qai-consultant-mcp"]
    }
  }
}

工具：

工具	功能
retrieve_qa_knowledge	提供知识库（KB）内容的依据片段（标准摘要——OWASP Top 10、IEEE 829、ISO/IEC 25010、ISO 26262、A-SPICE、EU AI Act——以及方法论、审计/评估指南和案例研究），可按类别筛选；没有匹配项时返回 low_relevance
list_kb_sources	按类别分组列出 KB 中的所有文档
estimate_qa_effort	基于 PERT 的确定性工作量估算（不生成大模型叙述，你可根据数字自行撰写）；warnings 会列出所作的任何假设
review_qa_document	对现有测试计划/策略/测试用例列表，按六个 ISTQB/IEEE-829 维度给出确定性的 0–100 质量评分，并提供发现和 KB 引文
analyze_test_results	从 JUnit XML/CSV 测试执行数据中计算确定性的健康指标——不稳定测试、曾经失败的测试、最慢的测试、失败聚类
assess_qa_maturity	根据自由文本描述，确定性地评估参考性的 TMMi 流程成熟度等级（1-3，绝不会给出认证等级 4-5）；当输入表明系统涉及 AI/ML 时，还会有条件地给出 EU AI Act 第 9-15 条准备度评分

提示词：qa_project_interview（与此应用使用的 11 个问题的采集流程相同）、risk_register_structure、test_strategy_structure、test_plan_structure——每个提示词都会通过 retrieve_qa_knowledge 为客户端生成的内容提供依据，并附上 [Source N] 引文。

**隐私：**匿名使用遥测默认开启（自 v3.7.0 起）；使用 QAI_TELEMETRY=0 或 DO_NOT_TRACK=1 可将其关闭。仅发送工具名称/成功状态/耗时/类别、版本和操作系统系列；每次服务运行都会生成一个随机 ID，且绝不存储——不会发送你的查询文本或项目详情。

---

反馈循环

每次生成后，QAI 都会询问：“这个策略有用吗？”

• 有用 → 策略保存到 knowledge_base/generated_strategies/，并纳入下一次重新摄取
• 部分有用 → 策略连同你的改进备注一起保存
• 没用 → 丢弃

这样就形成了一个反馈循环，QAI 会随着时间推移，从经过验证的真实输出中不断学习。

---

路线图

• v0.1 ✅ 核心 Agent + CLI + Streamlit Web UI
• v0.2 ✅ 反馈循环 — 经验证的策略会扩充知识库
• v0.3 ✅ 风险登记册 — 在测试策略中自动进行风险分析
• v0.4 ✅ 工作量估算报告 — 基于 PERT，并分析团队容量
• v0.5 ✅ 自动重新摄取 — 文件监视器 + 增量摄取 + 清单跟踪（文件监视器已在 v2.0 中移除）
• 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 ✅ EU AI Act 第 50 条透明度补丁 — 侧边栏 AI 交互提示 + 每份生成文档均显示“AI 生成内容”标签
• v2.6.0 ✅ EU AI Act 知识库支柱 — 风险等级、提供方/部署方义务、第 50 条透明度、第 9-15 条对测试的影响、合格评定、时间表
• v3.0.0 ✅ MCP 服务 MVP — 本地、无需密钥的 qai-consultant-mcp（基于标准的检索 + 确定性工作量估算）、应用内公告，以及机器可读的 AI 生成内容标记（EU AI Act 第 50(2) 条）
• v3.1.0 ✅ 评估套件 — QA 文档质量审查（采用确定性的 ISTQB/IEEE-829 评分标准评估现有测试计划/策略/测试用例列表，可选择附加 AI 叙述）和测试结果分析（从 JUnit XML/CSV 中提取不稳定/曾失败/最慢/失败聚类指标，让风险登记册以真实执行数据为依据）；可在 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”，与应用其他界面文案一致
• v3.1.4 ✅ 在 README_MCP.md（PyPI 长描述）中添加了 mcp-name 标记 — 这是将 qai-consultant-mcp 列入 Anthropic 官方 MCP 注册表的前提；无功能变更
• v3.1.5 ✅ 修复 — 上游 mcp SDK 发布存在破坏性变更的 2.0.0 版本后，移除了服务所依赖的 FastMCP 模块，导致 qai-consultant-mcp 无法启动（ModuleNotFoundError: mcp.server.fastmcp）；现在将 mcp 固定为 >=1.8.0,<2.0.0
• v3.1.6 ✅ 修复 — 缓存未预热时，qai-consultant-mcp 可能无法在 Claude Desktop 中完成连接（这是客户端握手超时，因为该服务过去会先完整嵌入整个知识库，再响应 initialize）；现在改为延迟构建完整索引，直到收到第一个实际请求
• v3.2 ✅ 完成 CI 质量门禁 — 新增独立的每夜工作流，运行真实的 Pinecone/Mistral/OpenRouter 契约测试，且不会阻止 PR
• v3.3 ✅ 在 Streamlit 侧边栏和所有生成文档的 PDF 导出中，采用 EU 官方 AI 生成内容图标（行为准则，AI Act 第 50(4) 条），进一步强化现有的文本/元数据披露
• v3.3.1 ✅ 修复 — qai-consultant-mcp 有时无法在 Claude Desktop 中完成连接，因为其 6 个运行时依赖项中有 4 个版本范围过宽，导致 uv 在任何无关上游版本发布时都可能重新解析并安装；现已将所有依赖项精确固定
• v3.4 ✅ 应用视觉重设计（“Calibration Bench”）— 基于令牌的颜色/排版系统（IBM Plex 字体，不使用字体 CDN）和可复用的“Signal Ledger”评分/严重性组件，已应用于文档审查、工作量置信度、结果分析、风险登记册和项目探索问题列表
• v3.4.1 ✅ 应用自身的 MCP 面板现在会显示分发链接（官方 MCP 注册表、Glama、Awesome MCP Servers），不再只在 README 中显示；已开始重设计着陆页（第 1 阶段，共 3 个阶段 — 详见 CHANGELOG）
• v3.4.2 ✅ 交互流程重设计（第 2 阶段，共 3 个阶段 — 详见 CHANGELOG）：项目探索对话、审查界面和侧边栏现在采用与着陆页一致的“Power-On Sequence”视觉语言（动画进度条、带单次入场动画的摘要磁贴、悬停反馈）
• v3.4.3 ✅ 输出界面重设计（第 3 阶段，共 3 个阶段，完成“Power-On Sequence”重设计 — 详见 CHANGELOG）：测试策略结果视图和文档审查界面现在采用一致的视觉语言（实时 4 阶段状态、带入场动画的评分磁贴、悬停反馈），着陆页还新增了“约 2 分钟内可获得什么”补充说明
• v3.4.4 ✅ 修复 — qai-consultant-mcp 再次可能无法在 Claude Desktop 中完成连接，这次是因为一个未固定版本的传递依赖（scipy，通过 scikit-learn 引入）在缓存未命中时获取了新版本；现已精确固定整个解析后的依赖树（约 99 个条目），而不仅仅是 6 个直接导入项
• v3.5.0 ✅ QA 成熟度评估（assess_qa_maturity）— 确定性的 TMMi 流程成熟度信号（10 个流程领域，参考等级 1-3），以及针对 AI/ML 项目的 EU AI Act 第 9-15 条条件式就绪度评分；可在 Web 应用（“📈 Assess QA Maturity”）、CLI（--maturity）和 MCP 服务（assess_qa_maturity）中使用
• v3.5.1 修复：QA 成熟度评分未能识别改述后的证据（以文字描述需求可追溯性、以“缺陷分流”/“通过率”描述进度跟踪）— 通过实时浏览器 QA 发现。已从 PyPI 撤回 — 原因见同日发布的 v3.5.2
• v3.5.2 ✅ 修复：无法安装 v3.5.1 的 MCP 软件包（从普通 PyPI 无法解析 torch==2.13.0+cpu）— 已恢复为普通的 torch==2.13.0 固定版本。这是 assess_qa_maturity MCP 工具首次成功发布到 PyPI，因为 v3.5.0 本身的发布步骤从未完成，而 v3.5.1 存在问题
• v3.5.3 ✅ qai-consultant-mcp 的本地索引将嵌入模型从 sentence-transformers/torch 切换为 fastembed（ONNX Runtime）— 检索质量相同（evals/local_index_parity.py：recall@5=0.91、MRR=0.86，保持不变），冷启动导入速度约快 3 倍，依赖列表也大幅缩短。移除了每周依赖漂移金丝雀工作流，因为在当前较小规模下已无必要。详情见 CHANGELOG.md。
• v3.5.4 ✅ 修复 2026-09-23 外部审计发现的可靠性问题：主 LLM 中途断开时，流式输出不再重复；工作量估算中的风险缓冲现在按风险矩阵实际行数计算（此前会因关键词匹配而膨胀至 35% 上限）；置信度评分不再将“None”或“functional safety”等明确答案视为含糊。详见 CHANGELOG.md。
• v3.6.0 ✅ 根据 2026-09-23 外部审计结果，增加公开应用防护和一目了然的摘要：服务器端每日生成限制（全局每日上限和每位访客上限，并保留现有的每会话 3 次运行上限），因此打开新标签页不再重置配额；在四个输出标签上方新增执行摘要 — 总体风险、QA 工作量范围、团队容量、置信度，以及最先处理的 3 项风险 — 根据风险登记册和工作量估算以确定性方式生成，不会额外调用 LLM。详见 CHANGELOG.md。
• v3.6.1 ✅ OpenRouter 备用方案现在仅使用免费层模型（通过 OpenRouter 的 models 备用链使用 Nemotron 3 Super → GLM 5.2），因此不再产生费用；AI 响应为空时会显示明确错误，而不是空白文档；应用内 AI 提示现在会警告，提交的文本可能会被 LLM 提供商记录并用于训练。详见 CHANGELOG.md。
• v3.6.2 ✅ 主模型切换为 Ministral 14B（Mistral Small 在 Mistral 免费计划中受到速率限制），输出预算提高至 6,500 个令牌，避免文档被截断；修复了粗体风险矩阵标题导致风险台账、执行摘要和工作量风险缓冲为空的问题
• v3.6.3 ✅ 修复了 MCP 知识库工具的崩溃问题：对于缓存了嵌入模型上游短暂损坏版本（fastembed 0.8.1）的安装，现在不会再出现 numpy“inhomogeneous shape”错误。详见 CHANGELOG.md。
• v3.7.1 ✅ MCP 遥测不会再发送无法识别的 category 值（该值可能包含自由文本）；analyze_test_results 文档现在与其对少于 3 次运行的测试的处理方式一致；新增 Agent 技能（skills/qai-consultant/），用于告知 AI Agent 何时调用各 MCP 工具。详见 CHANGELOG.md。
• v3.7.2 ✅ estimate_qa_effort 不再因为自动化文本中只是某个单词内部包含“no”（例如“CANoe”）就错误地应用“No existing automation”+20%；另修复 Streamlit 输出真实性保护（不虚构项目事实或无法核实的引文、不出现多余 Markdown），以及磁贴/徽标/按 Enter 提交/时间声明问题。
• v3.7.0 ✅ 着陆页显示实时采用情况数据（访问量、AI 运行次数、MCP 安装量、GitHub 星标；有数据后还会显示下载量和实用性），并增加下载和反馈计数器，默认启用 MCP 遥测且可选择退出。详见 CHANGELOG.md。
• v3.8.0 ✅ MCP 端到端 QA 修复：estimate_qa_effort 的单位/范围解析及警告、review_qa_document 对非 QA 文档/测试用例/语言的处理、retrieve_qa_knowledge 的 min_score/低相关性处理、analyze_test_results 的宽容解析；另修复 Streamlit 工作量/来源/下载/复制问题。
• v3.8.1 ✅ 在生成文档中标记超出适用范围的工具和虚构数量；支持下载全部内容为 .zip；为 retrieve_qa_knowledge 片段添加 match 强度标签；工作量叙述不再与表格矛盾。
• v3.9.0 ✅ 将 src/ 重新构建为 qai_consultant 软件包（wheel 分层为 common/core/mcp；工具和行为保持不变），按级别和功能对测试分组；执行摘要标题展示预期工作量，并将范围标注为规划区间。
• v3.9.1 ✅ 生成的文档不再彼此矛盾，也不再与确定性表格冲突（缺失项保护、工作量叙述、跨文档一致性、标记未经核实的监管机构）；刷新 MCP 依赖锁定版本（mcp 1.30.0、urllib3 2.8.0、pyjwt 2.15.0）。
• v3.9.2 ✅ 托管应用修复：zip 下载恢复正常（固定 Starlette 版本）；Streamlit/CLI 路径共用跨文档一致性检查；PDF 表格可正常呈现；生成过程改为显示阶段进度条，不再逐行流式输出。
• v3.9.3 ✅ MCP 终端用户 QA 修复：为 estimate_qa_effort 添加输入验证；对 assess_qa_maturity/review_qa_document 添加如实的适用性判断；改进检索；让 analyze_test_results 的警告更清晰。
• v4.0 远程 MCP — 可从 claude.ai 连接的托管服务，并提供服务器端使用指标

---

贡献

QAI Consultant 由 QA 社区为 QA 社区构建。

欢迎贡献：

• 📚 向 knowledge_base/ 添加新的知识来源
• 🧠 使用 knowledge_base/expert_knowledge/ 中的提示词分享专家知识
• 🐛 通过 GitHub Issues 报告 Bug 或提出功能建议
• 🔧 提交拉取请求

详细指南请参阅 CONTRIBUTING.md。

---

故障排除

问题	解决方案
"Missing required secret: 'MISTRAL_API_KEY'"	将密钥添加到 .env 或 Streamlit Cloud secrets
"Missing required secret: 'PINECONE_API_KEY'"	将 Pinecone 密钥添加到 .env
"Knowledge base is empty"	运行 python src/ingest.py，将文档推送到 Pinecone
"The AI providers are temporarily unavailable"	Mistral 和 OpenRouter 的免费模型均不可用——几分钟后重试；logs/qai_consultant.log 中记录了底层错误
Mistral 几乎没有使用量时返回 429 Rate limit exceeded（代码 1300）	在 Mistral 免费套餐中，Mistral Small/Medium 会被拒绝，而 Ministral 模型仍可使用——请保留默认的 ministral-14b-2512，或启用按量付费后再切换 MISTRAL_MODEL

📖 完整的故障排除指南：INSTALL.md