allure-agent-mode

Allure Agent Mode

在进行会更改测试的功能开发或缺陷修复、审查现有测试、审计覆盖率、分流失败的测试套件、调查证据不足，或调试不稳定且对环境敏感的失败时，请使用此技能。

为什么使用 Agent Mode

测试运行是一种检测手段，而不是可供提取的通过/失败结果。通过 allure agent 运行测试，可以将任何一次运行转化为可供审查的实际情况记录——包括步骤、HTTP 交互、SQL、浏览器会话和附件——以及针对测试本身的自动化发现，例如某项测试运行时没有断言，或某个 API 调用没有证据表明它确实发生过。控制台提供状态；Agent 输出则帮助你理解并评估情况，还会生成一份人类可以实际审查的报告。使用它，因为它能让工作做得更好。

• 有目的地运行。 allure agent --goal "<what this run should confirm>" -- <test cmd>。近期版本的 allure agent 会将运行摘要打印到 stdout——包括计数、带严重级别的发现、预期结果、报告链接以及输出中的相关指引——因此无需打开文件即可了解概要（可使用 --silent 选项减少透传噪声；请通过 allure agent --help 确认其效果）。阅读摘要后，再打开 Agent 输出查看详细内容：输出目录中的 AGENTS.md 指南、index.md、发现项以及每项测试的证据。报告会将目标与证据放在一起，因此你、上游 Agent 或人类都可以据此验证运行是否达成预期。
• 通过预期让证据可核验。 当必须证明某种行为时——例如 API 调用、附件或步骤——添加匹配的 --expect-* 选项。缺少预期证据会成为一项发现，而不是通过：这意味着你无法确定该行为是否实际执行过。
• 无需四处搜寻即可分流失败。 输出会准确列出失败项，并提供足够的上下文，方便就地修复。通过 Agent Mode 仅重新运行失败的测试，以确认是否存在不稳定性——使用 allure agent --rerun-latest（或 --rerun-from <prior-output>，通过 allure agent latest 找回先前的输出），并搭配匹配的 --rerun-preset；这样你就不必记住测试名称或此框架的筛选语法。请通过 allure agent --help 确认确切的标志。不要盲目重新运行，也不要提取日志。
• 无需本地复现即可调试 CI 问题。 对下载的 allure-results 运行 allure agent inspect，即可获得相同的审查视图和完整上下文——这往往足以修复无法在本地复现的失败（例如仅在 Windows 上失败、但你使用的是 Mac）。
• 将测试用作调试工具。 测试已设置好环境、执行了相关行为并捕获了证据——不要临时编写 bash 命令或手动操作浏览器 MCP，而应在 Agent Mode 下运行相关测试。
• 了解实际支持范围。 运行 allure agent capabilities，查看本地 CLI 实际支持哪些功能，而不是想当然。

运行时已将摘要概览打印到 stdout——阅读摘要后，再打开完整输出。使用 tail/grep/head 精简运行结果、通过 >/dev/null 丢弃输出，或只看到打印的计数就停止，都会丢掉其余内容：发现项、证据，有时甚至是整个测试二进制文件。Agent 输出才是关键信息。

首先阅读

如果项目中有 docs/allure-agent-mode.md，请在编写或审查测试之前阅读。

如果没有，请遵循此技能中的指导，并建议稍后使用 $allure-configure-agent-workflow。

在添加、更改、删除、跳过、抑制或审查测试之前，请阅读 references/test-design.md。

在添加、审查或修复 Allure 步骤、附件、参数、标签、描述或证据不足的发现项之前，请阅读 references/allure-evidence.md。

在创建或评估 Allure agent 预期之前，请阅读 references/expectations.md。请通过项目指南或 allure agent --help 确认本地预期机制。

工作流

1. 理解功能、问题或审查目标，并确定预期的测试范围。
2. 判断期望控制是否能降低本次运行的实际风险。如果能，则使用本地 Allure agent 支持的方式创建最小且全新的期望。
3. 按照测试设计规则编写或更新测试；如果任务仅涉及审查，则保持当前测试不变。
4. 自行执行测试时，先通过 allure agent 运行预期范围，再参考原始控制台输出。
5. 调查已生成原始 Allure 结果或转储产物的执行时，优先采用本地已确认的 allure agent inspect 流程，从这些产物生成 agent 可读的输出，然后再解析原始日志或生成的 HTML 报告。
6. 对仅限 agent 的迭代循环，支持时优先使用 --report off。进行最终验证或面向用户的审查运行时，优先使用 --report auto，或强制使用适当的 HTML 报告模式；如果生成了报告链接，请一并分享。
7. 输出运行结果或检查输出中的 index.md 路径，方便协作者快速打开概览。
8. 在检查源代码前，先审查 index.md、manifest/run.json、manifest/test-events.jsonl、manifest/tests.jsonl、manifest/findings.jsonl、manifest/expected.json（如果本次运行使用了期望），以及相关测试 Markdown 文件。
9. 如果证据不足，请通过真实步骤、附件或最少量的元数据来丰富测试。
10. 确认本次运行提供了可信信号：所选配置文件符合目标，没有重要测试被悄然排除，并且明确指出任何不作为门禁的本地或 CI 信号。
11. 如果针对同一预期范围仍有理由使用期望控制，请使用全新的 agent 输出目录和全新的期望重新运行。除非需要特定路径，否则使用 CLI 提供的临时输出路径。
12. 只有在范围匹配、覆盖仍有意义、证据足以审查、执行限制已明确说明，并且任何部分运行时建模都已指出时，才接受结果。

任务变体

这些是针对任务细化的主要工作流，不是独立流程——相同的“先运行，再审查 agent 输出”循环仍然适用。（失败调试已包含在上文的问题分类循环中；对于 CI 失败，应通过 allure agent inspect 检查下载的结果，而不是在本地重现。）

• 小型测试变更。 仅通过 allure agent 运行受影响的范围——即使是类型清理或 mock 重构等机械变更，也仍需通过 agent 模式进行冒烟检查——审查 agent 输出，然后才能说明回归安全性或正确性。
• 编写测试。 首先阅读 references/test-design.md 和 references/allure-evidence.md；编写或修改测试，使用 --goal 运行受影响的范围，然后审查发现和证据，而不仅是通过/失败结果；在使用全新输出重新运行前，补充薄弱的步骤、附件或元数据。
• 覆盖率审查。 将命令或包审计拆分为范围明确的分组；只有在分组范围已知时，才为每组分别生成 agent 输出和期望。运行每组后，先审查运行时产物，再查看源代码；在每组都通过匹配的期望、已审查的实际范围或明确的宽泛包健康度文档得到验证前，应将审查标记为未完成。

紧凑型覆盖率审查模式：

npx allure agent \
  <report mode: --report off for iterative loops, auto/awesome/config for final runs> \
  <minimal local expectation options when justified> \
  -- npm test -- <scope>

运行前，先确定哪些内容应该运行、哪些不应该运行、该范围为何足够，以及期望选项能否捕获实际错误。默认使用 CLI 提供的临时输出路径；只有需要特定路径时才添加 --output <path>。

要求

• 完整的 Agent 模式运行时证据需要 Allure CLI [email protected] 或更高版本，并支持 allure agent。
• 在依据 Agent 模式结论采取行动前，请确认本地项目封装程序支持 allure agent，且版本不低于最低要求。如果封装程序报告的版本较旧，请提醒用户，并将 Agent 模式证据视为不可用或不完整，直至 CLI 升级。
• 检查现有结果需要本地支持 allure agent inspect，该功能在 [email protected] 及更高版本中提供。通过项目封装程序运行 allure agent capabilities --json 和 allure agent inspect --help 进行确认。
• 对本地或下载的 allure-results 目录使用 allure agent inspect [<allure-results-dir-or-glob> ...]；对通过 allure run --dump 创建的转储归档，重复使用 --dump <archive-or-glob>。
• 控制可选报告生成时，使用 --report auto|off|awesome|config。默认的 auto 模式在存储的结果数量未超过本地 CLI 阈值时，可能会在 Agent 输出中生成 HTML 报告 awesome/index.html 和 manifest/human-report.json。
• 除非用户需要本次运行的 HTML 报告，否则在私有迭代循环中使用 --report off。对于最终验证或交接运行，优先使用 --report auto；使用 --report awesome 强制生成单文件 Awesome 报告，或者在应运行项目配置的报告插件时使用 --report config。
• 如果 allure agent inspect 不可用或无法处理该制品格式，优先采用高级回退方案：生成一个仅启用 agent 插件的临时 Allure 配置，然后运行 allure generate --config <generated-config> --output <agent-output> <results...>，并根据需要重复使用 --dump <archive-or-glob>。将显式指定的 <agent-output> 视为由调用方负责清理。
• 如果 agent inspect 和生成仅启用 agent 的配置这一回退方案都不可用，请检查原始 Allure 结果、转储内容或日志，但应将其视为较弱的回退方案。在支持的情况下，allure log <allure-results> 可作为结果文件夹的本地控制台回退方式，但它不是 Agent 输出。
• Agent 模式运行需要使用唯一的输出。未提供输出时，现代版 allure agent 会创建并打印一个临时输出目录；除非需要特定路径，否则使用此默认值。在 [email protected] 及更高版本中，每次 allure agent 运行都会自动移除上一次运行由 CLI 提供的临时输出，因此默认输出运行不会不断累积。
• Agent 模式只会检测当前运行生成的结果文件，因此无需在运行之间清空 allure-results——无论是否清空，它都会拾取新结果。是否清空或保留框架结果由项目自行决定，并非 Agent 模式的要求。
• 使用默认输出位置时，从 Agent 输出中获取生成目录；如果有支持的辅助命令，也可以使用 allure agent latest。
• 选择特定输出目录时，优先使用受支持的 --output 选项。显式指定的 --output 路径是唯一需要由 Agent 自行清理的内容——自动清理绝不会触及调用方提供的路径，因此完成后请删除或归档该 --output 目录。只有当本地 CLI 帮助、封装程序或官方文档明确记载某个与输出有关的环境变量时，才使用该变量；当前 CLI 支持的控制选项是 --output。
• Agent 输出、框架 Allure 结果和生成的报告是彼此独立的制品。不要将 ALLURE_RESULTS_DIR 等框架结果设置用于控制 Agent 输出。
• 除非项目指南、运行器配置、已安装的帮助信息、官方文档或适配器 README/源码确认本次运行需要，否则不要在 Agent 命令中添加或覆盖框架结果目录。如果需要为单次运行指定结果目录，请确保其最终路径组件为 allure-results，并确保本地 Allure 命令可以发现该目录。
• 切勿根据看似合理的名称臆造 Allure 环境变量。如果无法确认确切的变量或标志，请使用文档记载的 allure agent 选项，将该设置留作未知，或要求核实官方文档。
• 使用预期项的运行必须针对预期范围使用全新的预期项。
• 并发的 Agent 模式运行必须分别传入各自由调用方管理的 --output 目录；它们不能依赖默认临时输出，因为每次 allure agent 运行都会清除上一次运行的临时输出，从而覆盖并行运行的输出。切勿在并行运行之间共用输出路径或预期状态。
• 生成 HTML 报告的最终运行结束后，请读取 manifest/human-report.json，并将其中记录的报告路径与 Agent 输出目录结合解析，然后再分享该报告。
• 面向用户的输出中，将该制品简称为报告，不要将报告目标写在行内代码或代码块中。使用普通 Markdown 链接指向绝对本地报告文件，例如 [report](/absolute/agent-output/awesome/index.html)，并说明 Here is the report: <link>，以便 Codex 等客户端提供可点击或可预览的交互方式。切勿直接链接到相对清单值，例如 awesome/index.html。
• 在假定具体预期项选项名称之前，请先检查 allure agent --help。优先使用行内选项；仅在处理大型、生成式或受策略控制的契约时，才将基于文件的预期项用作高级模式。
• 不要出于防范目的添加预期项标志。如果预期项控制不可用或没有必要，请根据输出审查已观察到的范围，并指出范围检查较弱。
• 如果运行、本地命令或 CI 任务不具备门禁作用，或默认会排除重要测试，请在将其作为依据之前明确说明。
• 元数据丰富属于此循环的一部分，而非独立工作流。

守则

• 优先保证运行时，再考虑源码。
• 测试是行为契约；不要为了让运行通过而弱化断言、跳过测试或删除覆盖。
• 测试应简单直白。相比条件逻辑、循环、工厂或生成式测试（它们主要只是省下几行重复代码），优先选择可读、稳定、线性的测试。
• 不要通过运行时 if 分支、提前返回、条件式测试注册或掩盖覆盖缺口的辅助别名来硬跳过测试；应使用测试运行器原生的跳过、条件跳过或假设机制，并清楚说明理由。
• 步骤必须体现真实行为，而不是充数。
• 不要仅为让 Allure 证据非空，就用一个手动步骤包裹整个测试主体。
• 附件必须来自当前执行。
• 元数据应保持精简，只添加有助于审核或策略执行的标签。
• 每项测试的意图元数据应与测试内联：描述、标签、链接、参数以及定义意图的步骤名称，都必须在各测试位置明确写出。
• 优先在辅助函数边界添加埋点，而不是在调用方重复包装。
• 可复用的辅助函数可以处理机制，但不得通过包装器、查找表或测试名称映射来集中管理测试意图。
• 如果测试运行器可见的失败没有体现为逻辑测试，请检查全局 stderr，并将此次运行视为一次不完整的运行时审核。
• 不要将被忽略、排除、吞掉或不具门禁作用的测试描述为通过验证的依据。