SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qa

qa

测试与质量

查看项目

更新于 10-20 09:05

技能介绍

该技能（qa）用于在提交代码或创建 PR 之前，验证改动是否端到端正常工作。它定义了一套分步的 QA 流程，覆盖自动化检查、CLI 代理测试、传输与认证测试以及真实代理客户端测试，并附有人工测试参考。

用途

在提交或创建 PR 前，对改动进行端到端验证，确保其可正常工作。仅当通过 /qa 显式调用时使用。

主要能力与使用方式（分步骤）

第 1 步：运行质量门禁

执行：

pnpm run tsc && pnpm run lint && pnpm run test

如有失败需先修复再继续。

第 2 步：用 CLI 客户端（Agent）测试

这是主要 QA 方法，使用 AI 代理针对本地开发服务器调用 MCP 工具。

  • 启动开发服务器：后台运行 pnpm dev，默认地址为 http://localhost:5173。可用以下命令确认已启动：
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173/

若返回非 200 或连接失败，说明服务器尚未就绪，需等待后重试。

  • 运行测试查询。CLI 默认通过 HTTP 连接本地开发服务器（无需额外参数）：
# 验证认证与连通性
pnpm -w run cli "who am I?"

# 验证工具可用（数量随授予的技能而变化）
pnpm -w run cli "list all available tools"

# 测试与改动相关的特定工具
pnpm -w run cli "find my organizations"

输出中出现 Connected to MCP server (remote) 即确认已通过 HTTP 传输连接开发服务器。

  • 代理模式（可选）：测试 use_sentry 元工具而非各独立工具，速度约慢 2 倍：
pnpm -w run cli --agent "show me my recent errors"
  • 实验性工具：若改动涉及实验性工具：
pnpm -w run cli --experimental "your query"

第 3 步：在相关时测试 Stdio / 认证流程

当改动涉及 stdio 传输、认证、设备码流程、令牌缓存、npm 包行为或 mcp-test-client 时执行此步。

  • 快速 stdio 检查（无需浏览器）：
# 显式令牌 stdio 路径
pnpm -w run cli --transport stdio --access-token=TOKEN --list-tools

# 无令牌、非交互路径应因认证引导而失败
pnpm -w run cli --transport stdio --list-tools

显式令牌场景应出现 Connected to MCP server (stdio)；无令牌非交互场景应出现错误，提示需先交互式运行 sentry-mcp auth login。

  • 使用隔离缓存的设备码认证：使用独立缓存文件，避免 QA 依赖或覆盖 ~/.sentry/mcp.json：
AUTH_DIR=$(mktemp -d /tmp/sentry-mcp-auth.XXXXXX)
export SENTRY_MCP_AUTH_CACHE="$AUTH_DIR/mcp.json"
pnpm -w run cli --transport stdio --list-tools

此命令需在真实 TTY 中运行。服务器应打印 Sentry 设备码 URL 并等待授权；完成浏览器流程后，确认客户端连接并列出工具。

  • 缓存令牌复用：设备码登录成功后，用相同 SENTRY_MCP_AUTH_CACHE 再次运行同一命令，确认复用缓存令牌并列出工具，而不再启动浏览器登录。

第 4 步：在相关时测试真实代理 CLI

当验证 Claude Code、Codex 或仅在真实代理客户端中复现的问题时执行此步。仓库包含一个使用已安装本地 CLI 会话（而非 mcp-test-client）的测试脚手架包：

# Claude Code 针对本地开发服务器 MCP 条目
pnpm -w run agent-cli-test --provider claude --setup repo

# Codex 针对本地开发服务器 MCP 条目
pnpm -w run agent-cli-test --provider codex --setup repo

# Claude Code 针对仓库内签入的 stdio MCP 条目
pnpm -w run agent-cli-test --provider claude --setup stdio

# Codex 针对仓库内签入的 stdio MCP 条目
pnpm -w run agent-cli-test --provider codex --setup stdio

验证内容：CLI 已安装且能识别命名的 MCP 服务器；提供方可以针对 Sentry MCP 运行真实提示；最终答案包含 whoami 返回的已认证邮箱。若想测试托管服务器而非本地 sentry-dev 条目，可使用 --setup repo --server sentry。

签入的 stdio 设置使用 packages/agent-cli-test/projects/stdio/.sentry/mcp.json 作为隔离认证缓存。真实客户端不会给 stdio 子进程分配 TTY，因此首次运行的设备码流程需单独预热：

pnpm -w run agent-cli-test auth login

若脚手架失败，可直接重跑提供方并启用调试以查看 MCP 启动失败原因：

# Claude Code：为真实提示运行捕获调试日志
claude --mcp-config /tmp/claude-sentry-dev-config.json --strict-mcp-config --permission-mode bypassPermissions --no-session-persistence --debug-file /tmp/claude-sentry-dev.log -p 'Use the "whoami" tool from the MCP server named "sentry-dev". Call it exactly once. Reply with only the authenticated email address.'

# Codex：捕获 MCP 握手与传输日志
RUST_LOG=codex_core=debug,rmcp=debug RUST_BACKTRACE=1 codex exec --skip-git-repo-check --sandbox read-only --output-last-message /tmp/codex-sentry-dev-last.txt 'Use only the MCP server named "sentry-dev". Call the "whoami" tool exactly once. Reply with only the authenticated email address.'

需关注的典型现象：Claude 方面有 ToolSearchTool、mcp__sentry-dev__whoami、缺失服务器/工具选择、工具权限被拒；Codex 方面有 UnexpectedContentType、AuthRequired、resources/list failed。

第 5 步：仅人工测试（参考）

以下方式需要人工交互，代理无法执行，应在相关时建议用户操作。

  • MCP Inspector：用于以特定参数交互测试单个工具的 Web UI：
pnpm inspector          # HTTP 传输，打开 http://localhost:6274
pnpm inspector:stdio    # Stdio 传输，直接连接

  • 带 OAuth 的 Web UI：启动开发服务器 pnpm dev，打开 http://localhost:5173，通过 OAuth 流程认证，再通过聊天界面测试。约束测试可通过 URL 路径进行：

    • http://localhost:5173/mcp/org-slug — 组织范围
    • http://localhost:5173/mcp/org-slug/project-slug — 项目范围

  • Stdio / 生产构建测试（少见）：当需要专门测试已发布/打包构建而非本地开发服务器时：

# 先构建
pnpm -w run build

# 通过 stdio 传输和显式令牌测试
pnpm -w run cli --transport stdio --access-token=TOKEN "who am I?"

出现 Connected to MCP server (stdio) 即确认 stdio 传输正常。

适用场景

  • 提交代码或创建 PR 前的端到端验证。
  • 更改 MCP 工具、stdio 传输、认证（设备码、令牌缓存）、npm 包或 mcp-test-client 时的回归测试。
  • 验证 Claude Code、Codex 等真实代理客户端与 MCP 服务器的集成。

限制

  • 该技能仅在通过 /qa 显式调用时使用。
  • 设备码认证步骤需在真实 TTY 中运行；真实代理客户端不会为 stdio 子进程提供 TTY，需单独预热登录。
  • MCP Inspector、带 OAuth 的 Web UI 等步骤需要人工交互，代理无法执行。
  • 代理模式速度约为普通模式的两倍，较慢。
  • 文档未提供该技能的收费、价格或平台支持范围等信息。