meticulous-improve-test-env

当 Agent swarm 使用真实后端测试拉取请求（而非使用模拟的网络响应）时，它只能验证测试环境允许其访问的内容。由于环境原因而无法验证的情况——没有可操作的记录、测试用户没有所需角色、功能标志已关闭、登录失败、后端报错——会被报告为 已阻塞，Meticulous 会将其记录为带有类别、Agent 所见证据和建议修复方案的 环境设置阻塞项。此技能会将这些记录转化为对项目测试环境的具体更改。

开始之前，请运行 meticulous-cli-update 技能，确保 Meticulous CLI 和技能均为最新版本——除非它已在本次对话早些时候运行过；如果已运行，则跳过。

只有针对真实后端运行 Agent swarm 时，才会记录环境设置阻塞项。如果项目的 Agent swarm 运行使用模拟的网络响应，就不会有此类记录：请告知用户并停止。

第 1 步 -- 查看记录的环境设置阻塞项

# CLI (default: the last 30 days, newest first, 100 per page)
meticulous agent agent-swarm-setup-blockers [--since=<date>] [--category=<category>] [--runId=<swarmRunId>] [--limit=<n>] [--offset=<n>] [--project=<project>]

# MCP
get_agent_swarm_setup_blockers(since="<date>", category="<category>", runId="<swarmRunId>", limit=<n>, offset=<n>)

CLI 会先在 stderr 上打印所有匹配阻塞项中各类别的计数，然后输出一个 TSV 表格，其中包含 createdAt、swarmRunId、caseIndex、caseId、commitSha、category、blockedBy、caseTitle、summary、evidence 和 suggestedFix。--json 和 MCP 会返回相同的数据，格式为 { since, counts, setupBlockers }。如果响应提示还有更多结果，请使用 --offset 翻页后再下结论，或使用 --category 缩小范围。

从 counts 入手：阻塞项最多的类别，修复后能解除最多情况的阻塞。然后按根本原因对各类别中的行进行分组——例如相同类型的记录缺失、相同角色缺失或相同标志未开启——因为许多阻塞项通常只涉及少数几个原因。对于任何 evidence 过于单薄、无法据此采取行动的阻塞项，请查看完整情况，包括 Agent 执行的步骤：

meticulous agent agent-swarm-run-case --swarmRunId=<swarmRunId> --caseIndex=<caseIndex>
# MCP: get_agent_swarm_run_case(swarmRunId="<swarmRunId>", caseIndex=<caseIndex>)

如果没有环境设置阻塞项，但用户仍报告 Agent swarm 遇到阻塞，请使用 meticulous agent agent-swarm-runs --includeCounts 列出最近的运行（MCP：get_agent_swarm_runs），使用 meticulous agent agent-swarm-run --swarmRunId=<id> --status=blocked 打开包含大量已阻塞情况的运行，并查看这些情况。由 application 导致阻塞的情况源于应用自身的行为，而非环境；在此处只将 environment 情况视为候选项，并回到第 2 步，通过静态审查查找可能的缺口。

第 2 步 -- 梳理测试环境的设置方式

在提出任何建议之前，先查明测试环境的各个部分分别在哪里定义。在代码库中搜索：

• 种子数据和固定数据：种子脚本、插入数据的数据库迁移、工厂、固定数据文件，以及创建或重置环境时运行这些内容的命令或 CI 步骤。
• 测试用户：Agent swarm 登录所用账户的创建方式、分配的角色、权限、组织或套餐，以及该账户必须加入的任何允许名单。
• 功能标志：测试环境如何评估标志（标志服务、环境变量或配置文件），以及这些标志在该环境中的默认值。
• 身份验证：测试登录的工作方式——凭据、SSO 或 MFA 绕过方式、会话时长，以及它读取的环境变量或密钥。
• 后端配置：测试部署使用的环境变量、部署清单（例如 Docker Compose、Helm charts、Terraform 或平台配置文件）和服务 URL，包括哪些第三方服务是真实服务、沙盒服务或存根服务。

如果 .meticulous/agent-swarm-instructions.md 文件存在，也请阅读其中项目的 Agent swarm 说明：它可能已经描述了测试账户或预期数据，但内容可能已过时。

针对第 1 步中的每组阻塞项，记录控制其设置的文件或系统。如果阻塞项的原因位于代码库之外——例如标志管理面板、身份提供商、密钥管理器或托管数据库——请注明必须在相应位置进行更改。

步骤 3 —— 找出每组问题的修复方案

根据类别决定从哪里着手，并将阻碍项的 suggestedFix 作为起点，而非最终答案——请结合你在步骤 2 中的发现进行核实。

类别	通常表示什么	典型修复方案
missingTestData	测试用户没有流程所需的记录	扩充种子数据或固定数据，让测试用户在各个流程所需的每种状态下都有代表性记录（例如，既有空列表，也有已填充的列表；既有草稿，也有已发布的项目），并在重置时重新填充数据
testUserPermissions	测试用户无法查看或执行流程所需的内容	为测试用户授予流程所需的角色或权限，或者为每种角色添加一个测试用户，并在 Agent swarm 说明中逐一描述
featureFlag	流程受某个在测试环境中关闭的功能标志控制	为测试环境或测试用户启用该标志；对于仍在开发中的标志，在测试环境中将其默认设为启用
authentication	Agent 无法登录，或其会话已过期或遭拒绝	修复测试凭据或密钥，为测试用户禁用 MFA/CAPTCHA，或延长测试会话；确保无需人工介入即可登录
backendError	后端出错、超时或运行不正常	检查 createdAt 前后的测试后端日志，然后修复故障服务、其配置或资源限制；区分环境故障与拉取请求引入的实际问题
externalDependency	第三方服务（支付、电子邮件、地图等）无法访问或服务真实	让测试环境指向服务提供商的沙盒，或在测试环境中为该服务创建存根
other	不属于上述类别的设置问题	阅读 summary 和 evidence，然后根据具体情况判断

优先采用能让环境可靠复现的修复方案，例如每次重置时都会运行的种子脚本、配置中的标志默认值，而不是容易偏离预期的一次性手动修改。不要为了让测试通过而削弱生产环境的安全性：将任何放宽的登录、权限或标志设置限制在测试环境及其测试用户范围内。

如果 backendError 或其他阻碍项看起来是由拉取请求本身而非环境导致的，请明确指出，而不是建议修改环境——这是需要在此次变更中修复的错误。

步骤 4 -- 提出更改

向用户简要列出计划，并按每项修复预计解除的阻塞案例数量排序：

1. 对于每项修复，说明阻塞类别、可解决的阻塞数量（附上一两个案例标题作为示例）、根本原因和更改内容。
2. 代码库更改（种子数据、测试固定数据、测试用户设置、标志默认值、环境配置）：如果用户同意，就实施这些更改，并创建拉取请求，说明它们解决了哪些 Agent 群组设置阻塞问题。
3. 代码库之外的更改（标志面板、身份提供方、密钥、托管测试数据库）：列出用户需要执行的具体步骤，因为你无法在代码库中完成这些更改。
4. Agent 群组说明：如果 Agent 缺少无法自行发现的信息（例如各角色应使用哪个测试账户、种子数据的位置、哪些流程不可用是有意为之），请将这些信息添加到 .meticulous/agent-swarm-instructions.md，并包含在同一个拉取请求中。不要将密钥写入该文件。

未经用户明确同意，不要更改任何会影响共享环境或生产环境的内容。

步骤 5 -- 验证

更改部署到测试环境后，后续 Agent 群组运行应记录更少的设置阻塞问题。至少等一次新的运行完成后，再进行比较：

# Blockers recorded since the fix was deployed
meticulous agent agent-swarm-setup-blockers --since=<deploy time>

# Or a specific new run
meticulous agent agent-swarm-setup-blockers --runId=<swarmRunId>

检查已修复类别的问题数量是否减少，并查看这些类别中仍然存在的阻塞问题：如果修复只起到部分作用，或因此发现了新的阻塞问题，这里会显示出来。向用户报告更改前后的数量。