AI-Project

# QA-Final-V4 — Azure DevOps QA 自动化 MCP 服务器 端到端的 **QA 自动化系统**，由 MCP（模型上下文协议）服务器提供支持，连接 Azure DevOps 与 Claude / Claude Code。该系统作为单一的智能 QA 管理器，处理整个生命周期：从 PBIs 中派生测试用例（两种分析模式：正常默认 / 深入），分类以便自动化，将用例注入 Azure DevOps，生成客户端 UAT 文档和最终用户功能手册，并在循环结束时，通过 Playwright（网页）和 Appium（移动）MCP 服务器准备和运行自动化测试。 > 由 iHorizons QA 团队构建。引擎是 **与项目无关的**：所有项目/业务细节都存放在 `.claude/context/` 中 — 交换这两个文件以重新定位到任何项目（它目前为一个共享仓库服务于多个客户端项目）。在写入时，MCP 从 **父 PBI 本身** (`System.TeamProject`) 中推导出 Azure 团队项目，因此一个组织级别的 PAT 可以服务于所有项目；`.env` 中的 `AZURE_PROJECT` 限定了冲刺级别的读取查询。 --- ## 概览 | 组件 | 数量 | 位置 | |---|---|---| | 技能（程序） | 15 | `.claude/skills/` | | 子代理 | 5 | `.claude/agents/` | | 项目上下文文件夹 | 每个客户端项目 — 使用 `python tools/set_project.py <name>` 切换 | `.claude/context/projects/` | | 已注册的 MCP 服务器 | 3（azure-devops，appium，playwright） | `.mcp.json`（从 `.mcp.json.example` 复制） | | 核心 Python 模块 | 8（包括 `bugs.py` — 阶段 3b） | `core/` | | **单元测试（pytest）** | **117** — 运行：`pytest tests/ -q` | `tests/` | | 现场 E2E 测试 | 1（`smoke_e2e.py` — 注入 → 读取 → 清理） | `scratch/` | **关卡规则**（其他一切都依赖于这四个不变的规则）： - 阶段 1 绝不写入 Azure — 该集合存在于聊天中，直到用户签 off。 - 阶段 2 绝不发明用例 — 它分类、传输和装饰。 - 阶段 3 绝不重新判断覆盖率 — Azure 集合是合同。 - 阶段 3b 绝不修复测试或过滤失败 — 每个失败都记录（去重，不是人类，防止重复）。它是 **唯一无关的写入者**。 **已启用 vs 延期：** | 功能 | 状态 | |---|---| | Azure PBI 读取 · 用例注入（多项目：从父 PBI 派生团队项目） · 套件读取 | ✅ | | 覆盖率审查看到 MCP 注入的用例（TestedBy 链接） | ✅ | | 分析中的标签分类法（每个用例的 `classification_source`） | ✅ | | 仅描述的 PBI（无 AC）流经标记，具有强制性假设 | ✅ | | 自动化测试运行失败时的自动错误报告（阶段 3b）— 通过 `TC:<id>` 去重，按 PBI 查询层次结构 | ✅ | | 代码中强制执行纯英文错误标题（`create_bug` 中的标题保护） | ✅ | | 按项目切换上下文（ADR-002） | ✅ | | **来自自动化运行的 Azure 测试结果反馈** | 🔜 延期 — 下一步计划 | | Windows/Linux 主机上的 iOS 自动化 | ❌ 需要 macOS — 报告为可行的 | **在生产中证明：** 2026 年 7 月 — 在一个现场客户端冲刺中运行完整的冲刺：11 个 PBIs 分析（其中 10 个仅描述，无 AC），分类和注入（~400 用例；样本 PBI：40/40 创建，30 自动化 / 10 手动，0 拒绝），然后通过 `review_test_coverage` 验证返回 100% 标签源分类。 --- ## 为什么存在 一个冲刺的 QA 工作通常分散在许多工具中：有人在 Azure 中读取 PBI，有人在 Word/Excel 中派生测试用例，有人手动将它们粘贴到 Azure 中，有人手动编写 UAT 文档，有人编写自动化测试。错误在各个阶段之间渗透：遗漏边缘情况，标签不匹配，手滚 UAT 格式化，过时的自动化。这个仓库将整个管道 collapse 到一个对话中：您将 QA 管理器指向一个 PBI ID，它将通过分析 → 审查 → 分类 → 注入 → UAT 文档/用户手册 → 自动化进行工作，在每个阶段都有明确的交接和签 off。 --- ## 高级架构 ```mermaid flowchart TB %% ═════════ LEGEND — 每个概念一个形状 ═════════ subgraph Legend["图例"] direction LR LP((P1)):::phaseStart LS[技能]:::skill LA{{子代理}}:::agent LM[(MCP 服务器)]:::mcp LG[/用户关卡/]:::gate LP -->|流程| LS LS -.委托.-> LA end User([用户 / QA 主管]):::user subgraph Brain["QA 管理器协调器（CLAUDE.MD）"] QM{{QA 管理器帽}}:::agent DM{{开发经理帽}}:::agent end subgraph Phase1["阶段 1 — 分析和生成（仅聊天）"] P1((P1)):::phaseStart Mode[/"模式：正常默认 / 深入"/]:::gate AP[分析-pbi]:::skill QT[快速测试用例]:::skill QE{{qa-工程师}}:::agent G1[/签 off 关卡/]:::gate end subgraph Phase2["阶段 2 — 分类，注入和交付成果"] P2((P2)):::phaseStart CLS[自动化 / 手动分类通过]:::skill IT[注入测试用例]:::skill CBQ[创建错误查询]:::skill BUD[生成 uat 文档]:::skill BCUD[生成聊天 uat 文档]:::skill CUM[创建用户手册]:::skill GSR[生成摘要报告]:::skill DR{{起草者}}:::agent end subgraph Phase3["阶段 3 — 自动化层（开发经理帽）"] P3((P3)):::phaseStart G3[/审批关卡/]:::gate PAE[准备自动化环境]:::skill RA[路由自动化]:::skill SAF[搭建自动化框架]:::skill EL[提取定位器]:::skill ATC[自动化测试用例]:::skill RAU[运行自动化]:::skill SWE{{高级网络自动化工程师}}:::agent SME{{高级移动自动化工程师}}:::agent end subgraph Phase3b["阶段 3b — 失败时的错误报告（自动 — 唯一无关的写入者）"] P3B((P3b)):::phaseStart QCE{{质量控制工程师}}:::agent CAB[创建 Azure 错误]:::skill end subgraph MCPs["MCP 服务器（.mcp.json）"] AZ[(azure-devops MCP)]:::mcp AP_MCP[(appium MCP)]:::mcp PW_MCP[(playwright MCP)]:::mcp end subgraph Quality["可靠性层"] TESTS["tests/ — pytest 套件（92 个测试）<br/>链接类型 · 标签分类器 · 验证关卡 · 错误查询 · 标题保护"]:::mcp SMOKE["scratch/smoke_e2e.py<br/>现场 E2E：注入 → 读取 → 清理"]:::mcp end TESTS -.保护.-> AZ SMOKE -.验证.-> AZ %% ═════════ 阶段 1 — 在用户提交 PBI 时开始 ═════════ User -->|"'分析 PBI <id> [深入]'"| P1 P1 --> 模式 --> AP QM --> 阶段 1 AP -.委托派生.-> QE QT -.可选读取.-> AZ AP -- get_story_for_analysis --> AZ QE --> G1 %% ═════════ 阶段 2 — 在用户明确批准时开始 ═════════ G1 -->|用户批准集合| P2 P2 --> CLS QM --> 阶段 2 QM -.委托分类.-> SWE QM -.委托分类.-> SME SWE -.分类网页.-> CLS SME -.分类移动.-> CLS CLS --> IT IT -- 执行 qa 反馈 --> AZ IT -->|最后一步，自动| CBQ CBQ -- 确保错误查询层次结构 --> AZ BUD -.委托格式化.-> DR BCUD -.委托格式化.-> DR CUM -.委托格式化.-> DR DR -- 截图通过 --> PW_MCP %% ═════════ 阶段 3 — 在用户请求自动化时开始 ═════════ QM -.换帽.-> DM DM -->|"用户：'自动化 PBI <id>'"| P3 P3 --> RA RA --> PAE PAE -- 验证和搭建 --> SAF RA --> G3 G3 -->|用户批准计划| ATC ATC -.委托网页.-> SWE ATC -.委托移动.-> SME SWE -- 网页自动化 --> PW_MCP SME -- 移动自动化 --> AP_MCP RA -- 读取标签=自动化 --> AZ RAU --> SWE RAU --> SME EL -.按需.-> SWE %% ═════════ 阶段 3b — 当运行失败时自动启动 ═════════ RAU -->|检测到失败 — 自动| P3B P3B --> QCE DM -.委托分类.-> QCE QCE -- 结构化失败列表 --> CAB CAB -- 查找现有错误 / 创建错误 / 添加错误出现 --> AZ QCE -- 摘要有效载荷 --> GSR %% ═════════ 样式 ═════════ classDef phaseStart fill:#37474f,color:#ffffff,stroke:#263238,stroke-width:2px classDef skill fill:#e3f2fd,color:#0d47a1,stroke:#1976d2 classDef agent fill:#fff3e0,color:#e65100,stroke:#fb8c00 classDef mcp fill:#e8f5e9,color:#1b5e20,stroke:#43a047 classDef gate fill:#fffde7,color:#f57f17,stroke:#fbc02d,stroke-width:2px classDef user fill:#f3e5f5,color:#4a148c,stroke:#8e24aa ``` ## 仓库布局 ``` azure-mcp/ ├─ server.py # MCP 入口点（FastMCP） ├─ core/ # MCP 业务逻辑 │ ├─ analysis.py # 覆盖率审查 + 质量保证仪表盘（标签-分类器） │ ├─ discovery.py # 冲刺 PBI 发现（可选验证门控） │ ├─ engines.py # 测试用例创建引擎（多项目：从父 PBI 的项目） │ ├─ output_manager.py │ ├─ reporting.py │ ├─ test_planner.py │ └─ utils.py # 共享：验证器，分类测试用例来自标签，双语优先级 │ ├─ bugs.py # 第三阶段：查找/创建/更新错误（通过 TC:<id> 标签去重） ├─ tests/ # pytest 测试套件（92 个测试）- 运行：pytest tests/ -q ├─ scratch/ # git-ignored：smoke_e2e.py + 发现源数据 ├─ deliverables/ # git-ignored：生成的客户端 .docx 文件 ├─ docs/ # git-ignored：审查/验证记录 ├─ requirements.txt ├─ .mcp.json # MCP 注册表（azure-devops + appium + playwright） ├─ CLAUDE.md # 质量保证经理提示/编排规则 ├─ README.md # 此文件（包括“概览”高管摘要） └─ .claude/ ├─ agents/ # 子代理定义（5 个代理） ├─ commands/ # 斜杠命令（qa-mode，dev-mode） ├─ context/ # 引擎知识（5 个文件 + 文档-资产/） ├─ skills/ # 15 个技能，每个文件夹一个 SKILL.md └─ settings.json ``` 生成的自动化框架（./automation/）位于项目根目录下，并且 **git-ignored** - 它不会被提交到此仓库。 --- ## 更新日志 - 故障报告（第三阶段，合并于 2026 年 7 月） 从团队的 `logging-bugs-on-latest` 分支（PR #5/#6）合并并与下面的强化工作（字典合同，第三阶段重新编号）相协调。 - **第三阶段** - 任何 `run-automation` 通过失败的自动尾随：`quality-control-engineer`（新子代理）将 Allure 结果分类到结构化的失败列表中 → `create-azure-bug` 文件或更新一个错误/失败。**设计上没有确认门控** - 去重，不是人类，防止重复（在 `TC:<test_case_id>` 标签上找到现有的错误；通过 `add_bug_occurrence` 重新打开已解决的错误）。 - **错误卫生规则：** 标题保持纯英文（来自 `actual_result`）；原始异常/堆栈跟踪在 *“Automation Failure Root Cause”* 下保存原样 - 绝不在标题中。固定标签：`Automated`，`TC:<id>`，`PBI:<backlog_id>`，以及从测试用例复制的服务/平台标签。标题带有 `[<PBI ID>]` 前缀（查询范围键 - 绝不改写）。 - **`create-bug-queries`** （新技能）+ `ensure_bug_query_hierarchy` （新 MCP 工具）：每个 PBI 查询文件夹层次结构的幂等性，以便归档错误在保存的查询中自动显示；作为 `inject-test-cases` 的最后一步提供，按需回填。 - **新模块 `core/bugs.py`** （查找/创建/更新错误）+ 3 个新测试文件。总套件：**85 个测试**。 - 合并协调：查询配置与字典返回合同对齐；CLAUDE.md 第三阶段重新编号为步骤 14-17，第三阶段重新编号后。 - ⚠️ 已知债务：`core/bugs.py` + `ensure_bug_query_hierarchy` 仍然返回 JSON 字符串（预硬化合同）- 功能正常，但应统一为字典。 --- ## 更新日志 - 2026 年 7 月强化（审查后修复） 对引擎的全面高级审查发现并修复了三个 P1 错误以及一组可靠性差距。所有修复都涵盖了新的 pytest 测试套件，并且针对实时 Azure DevOps（烟雾 E2E + 完整生产冲刺运行 11 个 PBI / 400+ 注入案例）进行了端到端验证。 **P1 错误修复** - **链接类型不匹配（盲点错误）：** 注入链接 TC → PBI 通过 `TestedBy-Reverse`，但 `review_test_coverage` / `generate_qa_report` 仅读取 `Hierarchy` 链接 - 覆盖率审查对 MCP 自己的注入案例是盲目的。现在两者都接受 **TestedBy + Hierarchy** （去重）。 - **错误标签模型上的分析：** 分类假设了旧属性标签（`positive` / `Functional` / ...），而统一的标签模型不再发出这些标签。新共享分类器（`classify_tc_from_tags`）了解当前分类法（Axis-4 类别 + Axis-1b 自动化/手动），回退到旧标签，然后是标题推断 - 并且每个案例报告其来源（`classification_source`）。 - **覆盖率有效载荷中缺少标签：** `review_test_coverage` 现在返回每个案例的 `tags` （`route-automation` 需要用于平台分类）+ 每个 Axis-4 类别的 `category_coverage` 。 **可靠性和正确性** - 多项目支持：测试用例创建从父 PBI 派生 Azure **团队项目** （`System.TeamProject`）- 修复了父项目位于与 `AZURE_PROJECT` 不同的项目时的 TF401346。 - 冲刺发现验证通过策略放松：**描述是硬性要求；缺少 AC 不再跳过 PBI** - 它被标记（`has_ac=false`，`no_ac_count`，强制假设注释），因此分析从描述开始，在审查门控处具有明确的假设。 - `execution_type` 词汇表规范化（`Automation` 标签 ⇄ `Automated` 属性）- 没有更多由于命名不匹配而导致的注入拒绝。 - TF401289 标签权限回退在两个创建路径上统一（每个案例报告 `tags_applied`）。 - 报告：工作项批量提取现在 **大声失败** 而不是静默下计数；测试点 **分页** （无截断在 2000）；所有报告工具返回字典（一个合同）。 - `assess_priority` 是双语的 - 阿拉伯语货币/访问关键词（دفع، شحن، رصيد，دخول…）现在像英语等价词一样达到 P1。 - `review_test_coverage` 的说明仅为信息性 **且模式感知** - 工具不再为范围外的间隙（正常模式）规定创建案例。 **测试基础设施（新）** - `tests/` - 59 个 pytest 测试：XML 往返，验证器，执行类型规范化，双语优先级，标签分类器（当前 + 旧版 + 推断），链接类型回归测试，TF401289 回退，发现验证门控。 - `scratch/smoke_e2e.py` - 实时 E2E 工具：注入 2 个标记的烟雾案例 → 通过完整管道读取 → 清理。 **配置和文档** - `playwright` MCP 在 `.mcp.json` 中注册（草稿截图 + Web 自动化）。 - 特定于机器的权限从共享 `.claude/settings.json` 中移出。 - CLAUDE.md：第三阶段步骤重新编号（10-13），`build-chat-uat-doc` 添加到技能路由器。 - 上下文文件支持 **本地每个项目覆盖** （横幅 + `git skip-worktree`）因此一个共享仓库为多个项目服务而不会发生冲突。 - 标准：测试用例创作语言遵循 PBI（EN PBI → 英文案例，AR → 阿拉伯案例）；库尔德语作为 UI 区域测试，但绝不作为创作语言。 --- ## 以前的 PR 添加了什么（历史） 此 PR 集成了 Appium MCP 集成和第三阶段编排层，使系统可在移动设备上端到端运行。它还与先前合并的 PR #4（分析模式 + create-user-manual）干净地合并。 **新技能** - `prep-automation-env` - 验证 MCP，主机（Node，Appium，驱动程序，ADB）和 `./automation/` 框架是否已准备好用于请求的表面；当缺少时自动搭建；如果在非 macOS 上使用 iOS，则报告为可操作。 - `route-automation` - 2.5 阶段混合路由器。从 Azure 读取注入的批次，根据平台标签分类，运行 `prep-automation-env` 每个表面，等待显式批准，然后委托工程师。iOS 以明确的“需要 macOS”警告跳过 - 绝不会被静默丢弃。 **编排更改** - `CLAUDE.md` 现正式化了 **开发经理角色** - 编排器在第 2 → 3 阶段边界处显式切换角色。第三阶段编号步骤（9-12）已添加。 - `analyze-pbi` 和 `quick-test-cases` 现包括 **表面检测** 步骤，第三阶段：质量保证经理扫描平台标签并在签发时显示检测到的自动化路径，并提供在平行环境中准备环境的要约。 **MCP** - 在 `.mcp.json` 中注册了官方的 `appium-mcp@latest`，与 Azure DevOps 一起。 **UAT / 用户手册** - `build-uat-doc` 和 `drafter` 现具有明确的 **RTL / LTR 处理**：阿拉伯语测试用例生成一个完整的 RTL 文档；英文生成 LTR；混合集被拒绝并带有明确的问题 - 绝不半阿拉伯语/半英文。 **质量/内部事务** - 删除了旧的 `smoke` / `sanity` / `mobile` / `automated` pytest 标记（与 `automation-standards.md` 对齐）。仅 `regression` + 平台标记（`web` / `ios` / `android` / `control_panel`）保留。 - 修复了 `senior-mobile-automation-eng.md` 和 `run-automation/SKILL.md` 中的空字节文件损坏。 - 在 `requirements.txt` 中添加了缺少的 `python-docx==1.2.0`。 - 清理了特定于项目的临时脚本；将它们移动到 `scratch/`（git-ignored）。 - 强化了 `.gitignore` 以阻止 `.env.*`，`*credentials*`，`*secrets*`，`*.pat`，`*.token`，`*.pem`，`*.key` 和其他凭据文件模式递归。 - 用架构图 + 第三阶段步骤重写了 `README.md` 和 `CLAUDE.md`。 --- ## 已经在 main 上（在此 PR 之前） 从 PR #4（分析模式 + create-user-manual）继承： - **两种分析模式** （默认普通/深入）跨框架，代理和 analyze-pbi / quick-test-cases 技能。 - **自动化/手动标签分类法** （主动/标准.md 中的 Axis 1b）- 每个案例都有一个，由自动化工程师在预注入分类过程中分配。 - `create-user-manual` 技能 - 修复了 iHorizons 品牌的文档模板，截图门控（直接提供，通过 Playwright MCP 用于网页，或通过 Appium MCP 用于应用程序）。 - 自动化工程师可以通过 `get_test_cases_from_suite` **读取** 从 Azure 注入的测试套件；回帖到 Azure 仍然 **延迟**。 --- ## 许可证 内部 - iHorizons 质量保证团队（多项目引擎）。