qamap

# QAMap [](https://github.com/IvoryCanvas/qamap/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@ivorycanvas/qamap) [](LICENSE) **本地首选的AI生成PR质量保证技能。QAMap将PR差异转换为受影响的流程、缺失的证据和E2E草稿。无需云服务。无需LLM令牌。** QAMap是一个本地首选的CLI，它读取git更改、项目结构、运行者信号、选择器和可选的存储库QA内存，然后返回一个PR-ready QA草稿：哪些用户流程可能受到影响，哪些运行者适合，哪些E2E或检查清单应该存在，以及在合并之前哪些证据仍然缺失。 它适用于评审者询问的场景：“这个PR看起来很有道理，但它可能会破坏哪些用户流程，我们在合并之前应该测试什么？” QAMap不会调用LLM API，不会上传源代码，也不需要服务帐户。它在您已经拥有的存储库中运行。 核心循环非常简单： ```txt PR差异 -> qamap qa QAMap输出 -> PR评论草稿 + E2E/检查清单草稿 + 缺失证据 可选团队内存 -> .qamap/manifest.yaml -> 更好的未来PR推荐 ``` ## 安装和快速入门 需要Node.js 20或更新版本。 运行QAMap一次，无需添加依赖： ```sh pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD ``` 该命令故意不使用清单文件。它预览了一个PR评论/检查清单，列出了受影响的流程、推荐的运行者、草稿文件、缺失的夹具/选择器/断言证据和验证命令。 将结果交给编码代理而不是人类？使用紧凑的代理格式（参见[适用于编码代理](#适用于编码代理)）： ```sh pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD --format agent ``` 在存储库中安装QAMap以获得可重复的项目命令： ```sh pnpm add -D @ivorycanvas/qamap pnpm exec qamap qa . --base origin/main --head HEAD ``` 生成Markdown工件，代理或评审者可以将该工件粘贴到PR中： ```sh pnpm exec qamap qa . --base origin/main --head HEAD --output QAMAP_QA.md ``` 当您准备创建实际的测试文件草稿而不是PR评论预览时： ```sh pnpm exec qamap e2e draft . --base origin/main --head HEAD --dry-run pnpm exec qamap e2e draft . --base origin/main --head HEAD ``` 可选的精度升级：从默认分支创建存储库本地QA内存并审查它。匹配基于锚点路径，因此当更改的共享组件应映射到某个流程时，请将它们添加到流程的`anchors`中： ```sh git switch main pnpm exec qamap manifest context . pnpm exec qamap manifest init . git add .qamap/manifest.yaml git commit -m "添加QAMap验证清单" ``` 在不编写清单文件的情况下预览采用： ```sh pnpm exec qamap manifest init . --write /tmp/qamap-manifest.yaml pnpm exec qamap qa . --manifest /tmp/qamap-manifest.yaml --base origin/main --head HEAD ``` 在您想要存储库防护栏查找时使用较低级别的扫描器： ```sh pnpm exec qamap scan . ``` ## 30秒PR演示 预览当前分支的PR QA评论/检查清单： ```sh pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD ``` 本节故意使用文本输出而不是动画录制，以便README准确反映当前的CLI行为。新的GIF应仅从已发布的`@ivorycanvas/qamap`包和当前的`.qamap/manifest.yaml`流程记录。 QAMap读取更改的文件和项目信号： ```txt 输入 - git差异：origin/main...HEAD - 项目结构：package.json、路由、测试配置、选择器 - 可选团队上下文：.qamap/manifest.yaml、CONTEXT.md、ADR、目标、QA运行手册 ``` 然后它返回可审查的验证工作： ```txt 输出 - 此分支的PR评论/检查清单草稿 - 更改的领域语言和候选用户流程 - 推荐的E2E运行者或手动检查清单 - 草稿Playwright、Maestro、CLI、API或手动测试文件 - 准备状态：可运行候选、接近可运行或仅审查 - 阻止因素，例如缺少的运行者配置、选择器、夹具或断言 ``` 小型Next.js笔记页面更改的修剪后的实际`qamap qa`输出（在没有测试和清单的存储库中）： ```txt # QAMap QA草稿 > 本地首选PR QA技能输出。无需云服务。无需LLM令牌。清单文件是可选的，不需要第一次使用。 ## 摘要 - 项目：Web - 推荐运行者：Playwright - 清单文件：未找到；仅使用存储库信号和PR差异 - 准备状态：需要工作（54/100） - 草稿流程：1 ## 第一个E2E草稿引导 QAMap未找到此目标的已提交测试文件。下一步是创建第一个可运行的启动草稿，而不是停止在检查清单中。 - 推荐第一个运行者：Playwright - 创建命令：`qamap e2e setup . --runner playwright` - 安装命令：`npm install -D @playwright/test` - QAMap可以创建的草稿文件： - `playwright.config.ts` - `tests/e2e/notes-primary-journey.spec.ts` ``` ## PR评论草稿 ### 受影响的流程 - 笔记主要流程（领域语言） - 用户流程：用户-> 打开路由/notes。-> 通过填充Write A Note与现实数据保护Notes主要流程。 - 更改的文件：`app/notes/page.tsx` - 为什么：主要入口被推断为路由/notes [高]（app/notes/page.tsx）。 ``` 接受使用`qamap e2e setup . --runner playwright`启动并写入有效的`playwright.config.ts`和启动规范 - 真实的定位器来自更改的JSX，和诚实的烟雾断言而不是占位符失败： ```ts await test.step("打开路由/notes.", async () => { await page.goto("/notes"); }); await test.step("用现实数据填充Write A Note.", async () => { await page.getByPlaceholder("写一个笔记").fill("QAMap样本值"); }); await test.step("使用添加笔记激活主要笔记操作.", async () => { await page.getByTestId("add-note").click(); }); await test.step("确认可见的结果、保存的状态、导航或证明笔记工作的事件.", async () => { await expect(page.getByText("笔记")).toBeVisible(); }); ``` 此确切的启动规范在第一次运行（在chromium下1.3秒）时通过。第一个运行的断言是烟雾检查针对检测到的文本和选择器；草稿还带有覆盖率目标，人类（或团队的代理）应该将其转换为真正的领域断言，然后将规范提升为所需的CI证据。 参见[docs/quickstart-demo.md](docs/quickstart-demo.md)获取紧凑的演练，[docs/agent-skill.md](docs/agent-skill.md)获取代理交接用法，[docs/manifest.md](docs/manifest.md)获取验证清单循环，[docs/e2e-output-examples.md](docs/e2e-output-examples.md)获取更多输出形状。 ## 适用于编码代理 停止为每个PR向代理解释相同的QA上下文。QAMap在本地、确定性地回答“这个分支在合并之前应该证明什么？”，而无需在存储库探索上花费单个LLM令牌： ```sh qamap qa . --base origin/main --head HEAD --format agent ``` `--format agent`返回一个压缩的JSON对象（`schema: qamap.qa`，典型的小型PR约为2KB），其中包含受影响的流程、草稿路径和可运行状态、所需的证据、引导阻滞剂、PR检查清单和验证命令 - 完整报告的决策内容，上下文成本的一小部分。 该软件包附带三个集成点： - `skills/qamap-pr-qa/SKILL.md` - 便携式代理技能模板：任何本地代理工作流都可以读取可重用的指令，可以像最终的QA通行证一样运行QAMap。 - `qamap context . --write AGENTS.md` - 生成的代理指令现在包括预PR QA部分，以便存储库中的代理学习在自己的基础上运行`qamap qa`。 - `--output` - 将qa报告写入文件，代理或评审者可以将其粘贴到PR正文中。 将QAMap输出视为QA规划证据，而不是浏览器、设备或手动QA已通过的证明 - 输出本身就说明了这一点。 ## 为什么这是不同的 诸如浏览器或移动测试工作室之类的记录器在您已经知道要执行的流程时很有用。QAMap提前一步：它询问PR更改了什么，哪个存储库拥有的QA内存适用，以及在合并之前应该存在什么测试工件。 好的QAMap结果应该回答： - 哪个产品流程已更改 - 哪个清单领域、流程和检查导致了推荐 - 生成了哪个草稿测试文件或预览 - 草稿涵盖哪些成功、失败、边缘、合约或视觉用例 - 哪些选择器、夹具、身份验证、运行者或验证间隙仍然阻止受信任的回归证据 - 当推荐错误时要编辑哪个清单路径 这就是产品赌注：一次人类对存储库本地清单的纠正应该在没有另一个LLM提示的情况下改善未来的PR推荐。 您不需要清单文件即可开始。没有清单文件，QAMap使用PR差异、包信号、路由、选择器、运行者配置和现有测试。 ## QAMap的用途 QAMap故意很小： - 节省时间：它在代理工作成为审查混乱之前提供缺失的上下文、风险设置和验证间隙 - 默认静态：它不执行扫描的项目代码 - 默认无令牌：它不调用LLM API - 以验证为重点：它告诉评审者缺少什么证据，而不是如何编写代码 - PR QA技能输出：`qamap qa`将分支转换为PR-ready的影响流程摘要、建议的E2E/检查清单草稿、缺失的证据列表和可复制的检查清单 - 打包的代理技能：`skills/qamap-pr-qa/SKILL.md`为编码代理提供了一个紧凑的PR QA工作流，用于在交接前运行QAMap - 领域感知E2E草稿：它将分支更改转换为流程语言、草稿规范、准备状态和行动项 - 存储库本地验证基础：共享清单可以被提交，而生成的运行历史默认情况下被忽略 - 上下文感知基线生成：清单初始化可以使用存储库本地上下文、ADR、目标、代理指令、工具文件、技能和运行手册作为咨询引导信号 - 工具/技能角色提示：指令派生的上下文被分类为代理技能、工具配置、工作流生命周期、验证规则、安全策略、发布策略或测试运行者上下文 - 生态系统感知：它为JavaScript/TypeScript、Python、Go、Rust、Gradle和Maven项目建议验证命令 - CI友好：支持文本、JSON、Markdown和SARIF输出 - 可解释：每个发现都包含一个具体的修复 它适用于使用AI编码代理、MCP支持的工具或任何工作流的团队，其中代理可以读取、编辑、测试、提交或打开拉取请求。 对于PR验证，QAMap将存储库本身视为工作基础：提交的清单保存了持久的团队语言，忽略的本地历史保存了生成的运行观察结果，当前分支差异提供了现在更改的内容。 <details> <summary>中文介绍</summary> QAMap是一个用于AI编码代理创建的PR在评审前本地运行的QA草稿CLI。 它读取PR差异和存储库结构，了解哪些用户流程受到影响，哪些E2E或检查清单是必要的，哪些夹具/选择器/断言/运行者/验证依据缺失。它不使用云服务或LLM令牌。 ```sh pnpm dlx @ivorycanvas/qamap qa . --base origin/main --head HEAD ``` 当传递给代理时，使用 `--format agent` 可以获得一个压缩的JSON对象（`schema: qamap.qa`，典型的小型PR约为2KB），其中包含影响的流程、草稿路径和可运行状态、所需的证据、引导阻塞、PR检查清单和验证命令 - 完整报告的决策内容，上下文成本的一小部分。 目标是减少维护者在每次向代理解释项目上下文和验证方法时浪费的时间。清单文件是可选的，不需要第一次使用。重复的错误推荐可以通过`.qamap/manifest.yaml`进行纠正，从而改善未来的PR推荐。 </details> ## 快速命令 ```sh pnpm exec qamap qa . --base origin/main --head HEAD pnpm exec qamap qa . --base origin/main --head HEAD --format agent pnpm exec qamap qa . --manifest /tmp/qamap-manifest.yaml --base origin/main --head HEAD --output QAMAP_QA.md pnpm exec qamap scan . pnpm exec qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md pnpm exec qamap manifest context . pnpm exec qamap manifest init . pnpm exec qamap manifest validate . pnpm exec qamap manifest explain . --base origin/main --head HEAD pnpm exec qamap e2e draft . --base origin/main --head HEAD --dry-run ``` 在不将QAMap安装到目标存储库的情况下使用`pnpm dlx @ivorycanvas/qamap ...`进行一次性运行。 ## 存储库防护栏（二级） 上述QA草稿循环是核心产品。QAMap还附带一个静态防护栏扫描器，作为二级存储库防护栏：它检查代理指令、MCP配置、已提交的环境文件、有风险的包脚本、工作流权限和验证信号，在代理工作成为审查混乱之前。 对于在广泛使用代理之前存储库的基线运行： ```sh qamap scan . ``` ```txt 发现：6（高：3，中：2，低：1，信息：0） 高 - QM003 可疑的代理指令文本（AGENTS.md） 修复：删除不受信任的指令文本或将示例放入清晰的围栏文档中。 ``` 查看下面的规则表和[docs/rules.md](docs/rules.md)以了解扫描器检查的内容。 从源代码开发QAMap： ```sh git clone https://github.com/IvoryCanvas/qamap.git cd qamap pnpm install pnpm build node dist/cli.js scan /path/to/repo ``` QAMap `0.2.x`是一个本地首选的PR验证规划器，具有存储库级别的验证清单循环，而不是一个完成的自动QA机器人。好的结果是一个清晰的答案：“这个分支在合并之前应该证明什么？”，以及基于清单的E2E、夹具、选择器和验证工作，开发人员可以将其转换为真正的回归覆盖率。许多第一个草稿将正确报告`review-only`或`near-runnable`，直到项目添加运行者配置、稳定的选择器、确定性的夹具或团队拥有的清单条目。 ## QAMap生成的内容 在更改的分支上，QAMap尝试生成可审查的验证工件，而不是仅仅说“编写更多测试”： - 分支感知的验证计划，命名更改的领域、参与者、触发器、目标、成功信号和边缘情况 - 当存储库形状支持它们时，草稿Playwright、Maestro、CLI命令或手动检查清单文件 - 存储库级别的验证清单循环，人类一次纠正持久流程，之后的PR获得更锐利的路由/测试/检查建议 - 运行者设置提案，解释为什么Playwright或Maestro适合更改的表面以及如果团队接受它将创建哪些文件/命令 - 就缺少的运行者配置、选择器、夹具数据、断言、验证命令或流程清单而言的就绪证据 - 存储库本地建议`.qamap/domains.yml`、`.qamap/flows.yml`和忽略的`.qamap/runs/`历史记录，以便团队改进下一次运行而无需花费LLM令牌 这意味着QAMap在成为团队的验证基础时最有价值：人类定义持久的语言和关键流程，QAMap在每个PR上重用该基础，而生成的观察结果默认情况下保持忽略，除非团队故意推广它们到共享策略。 ## 命令 | 命令 | 用途 | | --- | --- | | `qamap scan .` | 扫描当前仓库并打印文本报告。 | | `qamap scan . --fail-on medium` | 当存在达到或超过阈值的发现时，以代码 `1` 退出。 | | `qamap scan . --json` | 为自定义自动化打印机器可读的 JSON。 | | `qamap scan . --format sarif --output qamap.sarif` | 为代码扫描集成生成 SARIF。 | | `qamap report . --output QAMAP_REPORT.md` | 为 PR 或审计生成 Markdown 报告。 | | `qamap doctor . --format markdown` | 总结仓库是否准备好进行 AI 辅助工作。 | | `qamap review . --base origin/main --head HEAD --format markdown` | 显示由分支引入的新发现和已更改的风险文件。 | | `qamap verify . --base origin/main --head HEAD --pr-body-file pr-body.md` | 结合审查发现、就绪度评分、领域测试和下一步骤。 | | `qamap eval . --base origin/main --head HEAD --pr-body-file pr-body.md` | 评估变更在意图、风险、测试和审查规模方面的就绪度。 | | `qamap github-action . --mode review --base origin/main --head HEAD` | 生成 GitHub Action 注解、步骤摘要和 PR 评论正文。 | | `qamap test-plan . --base origin/main --head HEAD --include-working-tree` | 为更改的文件建议领域测试场景。 | | `qamap e2e plan . --base origin/main --head HEAD` | 为更改的文件建议 E2E 运行器、引导步骤、用户流程、覆盖率目标、现有测试证据和缺失的测试能力钩子。 | | `qamap e2e plan . --base origin/main --head HEAD --record-history` | 在 `.qamap/runs/` 下保存一个紧凑的本地运行快照，同时保持 JSON/Markdown 输出可用。 | | `qamap e2e setup . --runner playwright` | 显式应用接受的运行器设置并创建第一个更改的流程 E2E 草稿，而不覆盖现有文件。 | | `qamap e2e draft . --base origin/main --head HEAD --dry-run` | 预览生成的 Maestro、Playwright 或手动 E2E 草稿，而不写入文件。 | | `qamap e2e draft . --base origin/main --head HEAD` | 编写生成的 Maestro、Playwright 或手动 E2E 草稿，包括流程语言、就绪度摘要和行动项目。 | | `qamap manifest init .` | 创建一个基准 `.qamap/manifest.yaml`，包含推断的领域、流程、锚点、检查、源和置信度。 | | `qamap manifest validate .` | 检查 `.qamap/manifest.yaml` 是否存在、是否可解析、是否锚定到真实文件，以及是否准备好形成 PR 证据。 | | `qamap manifest context .` | 预览仓库本地上下文源、角色分类、验证命令、安全规则和清单修复诊断。 | | `qamap manifest explain . --base origin/main --head HEAD` | 解释哪些清单领域、流程和检查与当前分支匹配，以及如果匹配错误，则编辑哪个清单路径。 | | `qamap flows init .` | 为团队批准的核心流程定义创建一个启动器 `.qamap/flows.yml`。 | | `qamap flows suggest . --base origin/main --head HEAD` | 根据更改的文件和 E2E 计划上下文，生成建议的 `.qamap/flows.yml` 条目，并提供提交就绪度指导。 | | `qamap domains init .` | 为共享产品/领域语言创建一个启动器 `.qamap/domains.yml`。 | | `qamap domains suggest . --base origin/main --head HEAD` | 根据更改的文件和推断的产品语言，生成建议的 `.qamap/domains.yml` 条目，并提供提交就绪度指导。 | | `qamap history init .` | 创建本地 QAMap 历史目录，并使用 `.gitignore` 保护生成的运行历史。 | | `qamap doctor services/offer --workspace-root .` | 在使用根护栏扫描单体仓库包。 | | `qamap context . --write AGENTS.md` | 为仓库生成启动器代理说明。 | | `qamap init .` | 创建一个启动器 `qamap.config.json`。 | 对于单体仓库，在扫描软件包时传递 `--workspace-root`。软件包本地检查仍使用软件包目录，而仓库级护栏（例如 `AGENTS.md`、`.github/workflows`、`LICENSE`、`SECURITY.md` 和 `CONTRIBUTING.md`）则从工作区根目录读取。 `qamap review` 将分支与基准引用进行比较，以适用于 PR 样式的工作流程。它将新引入的发现与已经在基准分支上存在发现但再次被修改的风险文件分开，这有助于审查者注意到当 PR 触及已知危险表面时，例如提交的 `.env` 文件、MCP 配置或发布脚本。 `qamap verify` 是最容易使用的 PR 命令。它将 `review`、`test-plan` 和 `eval` 结合成一个报告，包括审查发现、就绪度门控、建议的领域测试、建议的命令和下一步骤。 `qamap test-plan` 将更改的文件路径转换为审查就绪的领域测试检查清单。它还从 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、Gradle 文件和 Maven `pom.xml` 中发现常见的验证命令。添加 `--include-working-tree` 以获取本地的、未提交的更改。 `qamap e2e plan` 将更改的文件路径转换为第一遍 E2E 测试计划。它检测项目是否类似于 Expo/React Native、Web、API/服务或 CLI 软件包，建议一个运行器，例如 Maestro 或 Playwright，启动具有 API 合同检查清单的后端服务，启动具有 CLI 命令验证检查清单的可执行软件包，为测试历史很少或没有测试历史的仓库建议引导步骤，建议更改行为的领域语言，建议候选用户流程，添加覆盖率目标，将这些目标与现有测试套件证据进行比较（当存在测试时），标记需要模拟或固定响应 API 依赖的流程，并指出缺少稳定的选择器，例如 `testID` 或 `data-testid`，在任何人开始从空白文件编写测试之前。 计划还包括执行配置文件：检测到的启动命令、测试命令、Playwright `baseURL`、移动应用 ID、运行器配置文件、环境固定文件、置信度和阻止程序。这保持生成的 E2E 草稿对是否可运行的候选或仅限审查的脚手架保持诚实。 当仓库尚不存在选定的 E2E 运行器时，计划包括运行器设置提案，而不是静默更改项目。提案解释了为什么运行器适合更改的表面，哪个软件包命令安装库，哪些配置/脚本文件将被创建，以及显式接受命令，例如 `qamap e2e setup . --runner playwright`。 `qamap e2e setup` 是选择加入的申请步骤。对于 Playwright，它可以创建 `playwright.config.ts`、`tests/e2e/`、一个 `test:e2e` 脚本和第一个更改的流程 Playwright 规范。对于 Maestro，它可以创建 `.maestro/`、`.maestro/README.md`、一个 `test:e2e` 脚本和第一个更改的流程 YAML 草稿。现有的草稿文件将被跳过，除非传递 `--force`。它不会自动运行软件包安装；它打印安装命令，以便团队可以保持依赖策略的审查。 当在单体仓库根目录运行时，E2E 计划还会报告更改的应用/软件包目标。这有助于维护者从广泛的工作区差异转移到作用域命令，例如 `qamap e2e plan services/offer --workspace-root . --base origin/main --head HEAD`，其中软件包特定的运行器检测和流程命名通常更锐利。 每个候选流程还包括流程语言简介：参与者、触发器、目标、成功信号、审查问题和边缘情况。简介保持生成的测试与产品行为绑定，而不是仅与更改的文件名绑定。 引导部分回答了在将生成的草稿视为真正的回归覆盖之前必须发生什么。例如，没有测试的 Web 项目可以获得 Playwright 设置所需的步骤、第一个草稿生成、稳定选择器工作、固定/模拟数据以及缺少验证证据的推荐步骤，以及 `.qamap/manifest.yaml`、`.qamap/domains.yml`、`.qamap/flows.yml` 和本地历史记录的推荐步骤。 运行 `qamap manifest init .` 以创建基准验证清单。QAMap 从当前签出推断领域、流程、路由/组件锚点、检查、运行器提示、源和置信度。 > **重要：** 从仓库的默认分支创建共享团队基准，在拉取最新更改后。QAMap 不会静默切换分支或重写仓库状态，因此从功能分支运行 `manifest init` 会创建功能分支快照，而不是团队的默认 QA 地图。 ```sh git switch main git pull qamap manifest context . qamap manifest init . --write .qamap/manifest.yaml ``` `qamap manifest context .` 是存储库本地知识的只读预览，QAMap 可以在写入清单之前看到它。它报告上下文源，例如 `CONTEXT.md`、ADR、目标、运行手册、代理说明、套件文件和技能，然后显示角色分类、验证命令、安全规则和过时或缺失上下文的诊断。 在提交基准后，功能分支通常应运行 `manifest explain`、`e2e plan` 或 `e2e draft` 针对 PR 基准（例如 `origin/main`）。清单不一定在第一次运行完美。它旨在启动反馈循环：QAMap 根据清单推荐 E2E 工作，解释推荐的原因，并指出清单路径以编辑推荐错误时。 生成的清单包括 `$schema` 引用到 `schema/qamap-manifest.schema.json`，因此团队可以使用文档化的契约验证和编辑 `.qamap/manifest.yaml`。有关完整的领域指南和采用工作流程，请参见 [docs/manifest.md](docs/manifest.md)。 在将清单视为共享团队策略之前，请使用 `qamap manifest validate .`。它报告缺失的清单、无效的 YAML/模式形状、重复的 ID、缺失的领域路径、过时的锚定文件、可疑的路由提示和置信度低的推断条目，这些条目应被审查。 当您想要了解一个分支时，请使用 `qamap manifest explain . --base origin/main --head HEAD`。它读取 git diff，列出匹配的清单领域/流程/检查，显示声明的入口路由和所需的检查，并命名确切的清单路径以更新推荐错误时。 当存在 `.qamap/manifest.yaml` 时，`qamap verify`、`qamap e2e plan` 和 `qamap e2e draft` 包括清单推荐部分： ```txt 推荐原因： - 更改的文件与 Campaign Application Complete 流程的锚点匹配。 清单证据： - .qamap/manifest.yaml > flows.campaign-application-complete.anchors 下一步： - 为 Campaign Application Complete 流程起草或审查 E2E 覆盖。 - 覆盖声明的检查：成功提交 URL；对于无效 URL，显示验证错误。 如果这是错误的： - 更新 .qamap/manifest.yaml > flows.campaign-application-complete.anchors 修复提示： - 如果这些文件不属于此流程，请更新 .qamap/manifest.yaml > flows.campaign-application-complete.anchors。 - 如果推荐的断言感觉模糊不清，请在团队语言中重写 .qamap/manifest.yaml > flows.campaign-application-complete.checks。 ``` 当匹配的清单流程具有入口路由和检查时，`qamap e2e draft` 将其提升到启发式候选之上。生成的 Playwright、Maestro 或手动草稿带有清单证据，在可能的情况下使用清单路由作为入口点，并将清单检查转换为草稿步骤和所需的覆盖率注释。如果检查包括具体的提示，例如 `[data-testid=coupon-input]`、`with WELCOME10` 或可选的 `selector`、`value` 和 `steps` 字段，QAMap 在回落到模糊选择器推断之前使用这些事实。这是核心成本节约循环：人类一次修复耐用的 QA 上下文，然后未来的 PR 从更强的草稿开始，而不是空白的测试文件。 领域语言部分故意比原始文件列表更不面向实现。例如，`src/features/in-app-purchase/` 下的更改成为诸如 `In App Purchase` 之类的术语和诸如 `In App Purchase primary journey` 之类的场景。当更改的组件或服务文件命名具体行为时，QAMap 应优先使用该行为而不是通用主流程：`src/features/offer/components/ContentUrlSubmitModal.tsx` 可以成为 `Offer Content URL Submit`，而生成的草稿文件可以成为 `.maestro/offer-content-url-submit.yaml`。当存在 `.qamap/domains.yml` 时，声明的产品术语和路由获得更高的置信度。当存在 `.qamap/flows.yml` 时，团队批准的流程名称作为首选场景名称出现。 如果存在 `.qamap/domains.yml`，则 `qamap e2e plan` 还会将更改的文件与共享产品或领域语言进行匹配： ```yaml domains: - id: billing name: Billing aliases: - checkout - subscription files: - src/features/billing/** routes: - /billing scenarios: - title: Billing primary journey checks: - Start from the normal billing entry point. - Complete the primary billing action with realistic data. ``` 运行 `qamap domains init .` 以创建启动器领域清单。运行 `qamap domains suggest . --base origin/main --head HEAD` 时，QAMap 会根据当前分支起草清单条目，并将每个候选分类为 `commit-candidate`、`needs-review` 或 `low-signal`。使用领域进行命名和路由提示；使用核心流程时，团队希望定义一个耐用的验证旅程。 如果存在 `.qamap/flows.yml`，则 `qamap e2e plan` 还会将更改的文件与团队批准的核心流程进行匹配。这让维护者可以编码产品或领域流程，而这些流程是人类已经关心的： ```yaml flows: - id: checkout-purchase name: Checkout purchase priority: critical domains: - checkout files: - src/pages/checkout/** - src/features/checkout/** routes: - /checkout checks: - Complete checkout with a valid payment method. - Verify declined payment recovery. ``` 运行 `qamap flows init .` 以创建启动器清单。运行 `qamap flows suggest . --base origin/main --head HEAD` 时，QAMap 会根据更改的文件、推断的领域语言、路由和 E2E 检查起草流程条目，然后对哪些条目足够接近作为共享策略审查进行分类。与生成的运行历史记录不同，`.qamap/flows.yml` 旨在审查和提交，当这些流程定义应成为团队策略时。 当您希望 QAMap 保存 E2E 计划的紧凑本地快照到 `.qamap/runs/` 下时，请传递 `--record-history`。QAMap 自动使用 `.gitignore` 保护 `.qamap/runs/`、`.qamap/cache/`、`.qamap/tmp/` 和 `.qamap/*.local.json`，以便生成的历史记录默认保持本地。共享项目策略（例如 `qamap.config.json`、`.qamap/domains.yml` 和 `.qamap/flows.yml`）仍然保持对提交的友好。 `qamap e2e draft --dry-run` 预览相同的草稿分析，而不创建目录或文件。在评估新仓库或 PR 时，首先使用它。输出仍包括计划的文件路径、自检、就绪状态、行动项目、启动代码差距和执行阻止程序。 `qamap e2e draft` 从该计划中编写草稿文件。Expo 和 React Native 项目默认情况下会获得 `.maestro/` 下的 Maestro YAML 流程，Web 项目会获得 `tests/e2e/` 下的 Playwright 规范，API/服务项目会获得合同检查清单草稿，CLI 软件包会获得命令验证检查清单，直到记录项目特定的运行器。对于 Web 应用程序，QAMap 识别常见的 Next.js、React Router、Vite、Vue/Nuxt、Svelte、Remix、Astro 和 Angular 信号。它可以从 Next Pages Router 文件、Next App Router 文件（例如 `src/app/(group)/products/[id]/page.tsx`）、React Router `path` 对象、链接和命令式导航调用中推断路由。草稿推断稳定选择器，例如 `testID`、`accessibilityLabel`、`data-testid`、`aria-label`、占位符文本、基于角色的按钮或链接以及可见文本（如果可能）。它们还带有固定/模拟就绪度注释和推断的 API 端点提示。仅限客户端的流程可能会获得样本 Playwright 响应脚手架，但更改的端点由 PR 观察而不是使用合成响应拦截进行干预，因此生成的草稿不会隐藏正在测试的契约。当选择器或路由参数不完整时，QAMap 现在更喜欢具有安全烟雾断言和样本参数的可运行启动代码，而不是不可执行的占位符定位器。除非传递 `--force`，否则不会覆盖现有文件。 草稿结果不仅限于生成的代码，还包括 Markdown 和 JSON 输出： - `languageBrief`：每个草稿文件的参与者、触发器、目标、成功信号、审查问题和边缘情况 - `promotionStatus`：草稿是 `commit-candidate`、`needs-review` 还是 `low-signal` - `runnableStatus`：草稿是 `runnable-candidate`、`near-runnable` 还是 `review-only` - `selfCheck`：生成的草稿结构、未解析的占位符、启动代码质量和执行配置的静态运行器检查 - `status`：文件是 `--dry-run` 预览的、`created` 还是 `skipped` - `actionItems`：所需的和推荐的后续工作，按断言、固定程序、选择器、运行器、验证和清单分组 - `actionSummary`：总的所需/推荐操作计数、就绪文件计数和最常见的操作类别 - `readinessSummary`：0-100 的整体得分、就绪度级别、自检计数、启动代码差距、执行阻止计数和主要阻止因素 有关 Web、移动、API/服务、CLI、测试不足和单体仓库输出的紧凑示例，请参见 [docs/e2e-output-examples.md](docs/e2e-output-examples.md)。 生成的 Playwright 草稿使用流程语言作为 `test.step()` 名称，因此文件可读性类似于它所保护的用户旅程： ```ts await test.step("打开路由 /checkout.", async () => { await page.goto("/checkout"); }); 以下是翻译后的文档： ```markdown ## 工具列表 `qamap history init` 准备本地存储，显式地在不运行分析的情况下创建 `.qamap/runs/`、`.qamap/cache/` 和 `.qamap/tmp/` 目录，并将生成的历史忽略模式添加到 `.gitignore` 中。 `qamap eval` 评估分支是否有足够的验证证据、变更测试覆盖率、意图捕获、风险解释、域验证路径和可审查的大小。在 GitHub Actions 中，QAMap 可以从事件负载中读取拉取请求正文，并将评估附加到拉取请求评论中。 ## 检查内容 第一个版本专注于许多仓库都适用的高信号检查。 | 规则 | 严重程度 | 检查内容 | | --- | --- | --- | | `QM001` | 中等 | 缺失的代理指令文件。 | | `QM002` | 中等 | 冲突的代理指导。 | | `QM003` | 高 | 可误导代理的指令文本。 | | `QM004` | 中等/高 | 有风险的 MCP 命令配置。 | | `QM005` | 高 | MCP 配置中嵌入类似机密的值。 | | `QM006` | 中等 | 缺失或占位符测试脚本。 | | `QM007` | 低 | 缺失的 GitHub Actions 工作流。 | | `QM008` | 高 | 已提交的本地环境文件。 | | `QM009` | 高 | 可发布、推送、合并或运行不安全 shell 管道的包脚本。 | | `QM010` | 中等 | 广泛的工作流权限或有风险的工作流触发器。 | | `QM011` | 低 | 缺失的社区健康文件。 | | `QM012` | 中等/高 | 有风险的已提交代理设置、钩子或广泛的 shell 权限。 | | `QM013` | 低 | 仅在文档中记录的 API 端点，没有合约源。 | 请参阅 [docs/rules.md](docs/rules.md) 获取规则目录。 请参阅 [docs/ecosystem.md](docs/ecosystem.md) 获取 QAMap 跟踪的代理生态系统表面。 请参阅 [docs/api-contracts.md](docs/api-contracts.md) 获取 API 合约源检查。 请参阅 [docs/verify.md](docs/verify.md) 获取综合拉取请求验证报告。 请参阅 [docs/eval.md](docs/eval.md) 获取变更准备度评估。 请参阅 [docs/releasing.md](docs/releasing.md) 获取 npm 发布运行手册。 ## 配置 使用 `qamap.config.json` 或 `.qamap.json` 调整仓库策略。 ```json { "$schema": "https://raw.githubusercontent.com/IvoryCanvas/qamap/main/schema/qamap.schema.json", "failOn": "high", "ignoreRules": ["QM011"], "maxFiles": 2000, "validationCommands": ["make test", "make lint"], "severity": { "QM007": "info" } } ``` 请参阅 [docs/configuration.md](docs/configuration.md) 获取详细信息。 ## GitHub Actions QAMap 可以作为一个轻量级的拉取请求检查运行，带有注释、步骤摘要和粘性拉取请求评论： ```yaml name: QAMap on: pull_request: permissions: contents: read pull-requests: write jobs: qamap: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 with: fetch-depth: 0 - uses: IvoryCanvas/qamap@main with: mode: review base: ${{ github.event.pull_request.base.sha }} head: HEAD fail-on: high github-token: ${{ secrets.GITHUB_TOKEN }} ``` 拉取请求评论可以包括建议的域测试和变更文件的验证准备度评估。有关部署指南，请参阅 [docs/adoption.md](docs/adoption.md) 和 [docs/github-action.md](docs/github-action.md)。 ## QAMap 的位置 在 QA 端，QAMap 比测试编写工具更早一步 - 它决定了 PR 必须证明什么，在记录、生成或编写测试之前： | 工具类别 | 典型关注点 | QAMap 关注点 | | --- | --- | --- | | 测试记录器和工作室 | 将已知流程转化为脚本，通过观察您运行它。 | 在记录开始之前，决定 PR 影响哪些流程以及缺少哪些证据。 | | LLM 测试生成 | 从源代码中花费模型令牌编写测试代码。 | 免费的确定性 PR 到 QA 映射；草稿是代理或人类完成的起始脚手架。 | | 每次 PR 重新提示代理 | 在每个会话中重新推导仓库 QA 上下文。 | 仓库拥有的 QA 内存（`.qamap/manifest.yaml`）加上紧凑的 `--format agent` 切换。 | | 变更影响测试选择 | 选择要运行哪些现有的单元/CI 测试。 | 命名用户面向的流程和应该存在的 E2E/检查清单工作。 | 在防护方面，QAMap 并不试图取代更大的安全生态系统： | 工具类别 | 典型关注点 | QAMap 关注点 | | --- | --- | --- | | OpenSSF Scorecard | 广泛的开源安全态势。 | 仓库边界处的 AI 代理就绪性。 | | 机密扫描 | 代码或历史中暴露的凭证。 | 类似机密的值加上不安全的代理、工作流和脚本上下文。 | | MCP 安全扫描器 | 对 MCP 服务器、工具、提示和技能的深入分析。 | 不执行不受信任的 MCP 服务器的静态仓库检查。 | | 通用 linter | 代码样式、正确性或框架规则。 | 影响 AI 辅助开发安全性的防护措施。 | ## 路线图 QAMap 作为本地 CLI 启动，并应保持足够小，以便维护人员能够理解每个发现结果。 近期优先级： - 在代表性的清单、Web、移动、API/服务、CLI、monorepo 和测试轻仓库中保持 [发布验证](docs/release-validation.md) 清单的最新状态 - 使 [发布运行手册](docs/releasing.md) 与 npm 包和 GitHub Action 发布过程保持一致 - 在第一个公共包准备好后发布版本化的 GitHub Action 发布标签 - 改进分支感知的 `review` 变更行位置 - 用特定于框架的测试骨架改进生成的域测试计划 - 用更强大的应用特定选择器发现和自检循环改进生成的 Maestro 和 Playwright 草稿 - 将 `eval` 扩展到仓库特定的验证清单和品尝量表 - 继续扩展 Codex、Claude Code、Cursor、Copilot、Gemini 和相关工具的代理表面检测 - 从扫描器元数据生成规则文档 请参阅 [docs/roadmap.md](docs/roadmap.md) 获取更多详细信息。 ## 项目状态 QAMap 很早，版本低于 `1.0`。公共 API 可能会更改，但该项目旨在从第一个版本开始就保持可读、实用，并在实际仓库中保持有用。 ## 贡献 欢迎提出问题和拉取请求。维护人员权限归 IvoryCanvas 成员所有，`main` 受保护，外部贡献者无法直接推送或合并。 良好的首要贡献包括新的代理指令文件检测器、更好的 SARIF 位置、风险仓库示例和文档改进。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[GOVERNANCE.md](GOVERNANCE.md) 和 [SECURITY.md](SECURITY.md)。 ## 哲学 QAMap 不会取代代码审查、测试、威胁建模、分支保护或安全审查。它是一个小型预检，帮助团队尽早发现仓库级 AI 风险，以便采取措施。 ```