用途
Auth Handler 用于在页面探索开始之前，确保存在一个有效的 MCP 浏览器会话。它面向 QA 探索代理，当代理需要访问受认证保护的页面时使用。该技能以流程清单（procedural checklist）的形式定义，而不是 LLM 提示词。
跳过条件
如果 setup/auth.ts 不存在，则完全跳过此技能。此时探索器将在无认证的情况下继续，仅访问公开路由。
使用方式
第 1 步 — 检查环境变量
从 .env 读取凭据：
- TEST_EMAIL 或 ADMIN_EMAIL — 管理员用户名
- TEST_PASSWORD 或 ADMIN_PASS — 管理员密码
如果两者都缺失，则停止并报告：
Auth handler: TEST_EMAIL and TEST_PASSWORD must be set in .env
第 2 步 — 通过 MCP 浏览器登录
MCP 浏览器始终以全新会话启动（无 cookie）。setup/auth.json 仅由 Playwright 测试运行使用，无法注入到 MCP 浏览器中。无论 auth.json 是否存在，此处都始终执行一次全新登录。
使用 Playwright MCP 工具按顺序执行以下步骤：
- 导航到 APP_URL — 等待页面稳定。
- 点击 Login 按钮（role button，name Login）。
- 用 TEST_EMAIL（或 ADMIN_EMAIL）填写 Username 字段（role textbox，name Username）。
- 用 TEST_PASSWORD（或 ADMIN_PASS）填写 Password 字段（role textbox，name Password）。
- 点击 Sign In 按钮（role button，name Sign In）。
- 等待 URL 不再包含 /sso — 使用 mcp__playwright__browser_wait_for，超时 20 秒。
- 等待 networkidle。
如果 20 秒后仍停留在 /sso，则停止并报告：
Auth handler: login failed — still on SSO page after Sign In. Check credentials in .env.
如果登录成功，则进入第 3 步。
第 3 步 — 向调用方确认
Auth handler: MCP browser session authenticated. Exploration can proceed.
适用场景
- QA 探索代理需要访问受认证保护的页面时。
- 需要在探索开始前建立有效 MCP 浏览器会话的场景。
限制与注意事项
- 此技能仅认证 MCP 浏览器会话，不会更新 setup/auth.json。测试执行使用 storageState: 'setup/auth.json'（由 npm run auth 单独管理）。MCP 探索使用此实时登录会话。
- 运行中途会话过期：如果探索期间出现意外重定向到 /login 的失败，请从第 2 步重新调用此技能以执行全新登录。
- 安全说明：setup/auth.json 必须位于 .gitignore 中。它包含实时会话令牌。切勿提交，切勿记录其内容。