TestChimp

@testchimp/cli

TestChimp CLI 和 MCP 服务，用于调用带有 TESTCHIMP-API-KEY 的 TestChimp /api/mcp/* 端点。

此仓库文件夹在本地仍可能名为 testchimp-mcp-client；已发布的 npm 包名为 @testchimp/cli。

安装

npm install -D @testchimp/cli@latest

MCP（Cursor、Claude Code、VS Code 等中的 Agent）

注册该服务，使宿主运行：

npx -y @testchimp/cli@latest mcp

mcpServers.testchimp 示例：

{
  "command": "npx",
  "args": ["-y", "@testchimp/cli@latest", "mcp"],
  "env": {
    "TESTCHIMP_API_KEY": "your-project-key",
    "TESTCHIMP_BACKEND_URL": ""
  }
}

配置文件路径取决于宿主（例如，Cursor 通常使用 <repo>/.cursor/mcp.json）。工具名称使用短横线命名法（例如，get-requirement-coverage、create-user-story）。

CLI

export TESTCHIMP_API_KEY=...   # required unless TESTCHIMP_OAUTH_TOKEN is set (often read from project MCP env; never commit keys)
testchimp --help
testchimp get-requirement-coverage --branch-name main --help
testchimp create-user-story --platform-file-path plans/stories/foo.md --title "Checkout"
testchimp list-screen-states --json-input '{}'
testchimp upsert-screen-states --json-input '{"screenStates":[{"screen":"Checkout","states":["empty","filled"]}]}'
testchimp list-perf-runs --testchimp-id TC-123 --kind JOURNEY --limit 20
testchimp list-perf-runs --run-id 01ABC --include-raw
testchimp promote-perf-baseline --run-id 01ABC --env-class CI
testchimp compare-perf-to-baseline --run-id 01ABC --max-p95-regression-percent 10
testchimp list-related-perf-tests --scenario-titles "Checkout,Refund"
testchimp list-api-operation-interactions --operation-id 01XYZ --interaction-type REAL --limit 100
testchimp list-meetings --include-filter-options
testchimp list-meetings --from 2026-09-01 --to 2026-09-30 --domain customer.com --label Sales --search "pricing"
testchimp get-meeting-transcript --meeting-id <meeting-id> --summary-only
testchimp ephemeral-environment --action PROVISION --branch-name feat --no-wait
testchimp report-scan-findings --id scan-1 --scanner DAST --report-file zap.json
testchimp upsert-issue --title "Broken checkout"
testchimp list-issues --status ACTIVE --limit 10
testchimp get-release --release 1.2.0
testchimp upsert-release --release 1.2.0
testchimp manage-test-run --release 1.2.0 --title "Sprint 12"

• 标准输出： API 响应 JSON。
• 标准错误： 等待时 ephemeral-environment --action PROVISION 的进度信息（“仍在等待……”轮询）。仅触发创建/部署时，传入 --no-wait。
• 性能门禁： compare-perf-to-baseline 仍会输出其 JSON 响应，但当 regressed 为 true 时（顶层或 comparison 下），会以非零状态退出。
• 会议： list-meetings 仅涵盖团队级 Meeting Bots 会议（筛选条件与 Meetings 页面相同）。--include-filter-options 会返回标签／参与者／域名目录。--from／--to 接受 YYYY-MM-DD（含首尾的本地日期）、ISO 日期时间或 epoch 毫秒；--label、--participant、--domain 可重复指定或使用逗号分隔。
• 标志： 每个子命令的默认值；--json-input '<json>' 或 --json-input @file.json 会与标志合并（发生冲突时以 JSON 为准）。嵌套请求体（例如 TrueCoverage 范围）请使用 JSON。
• 发布标签： 在 get-release、upsert-release、manage-test-run 及其他发布筛选命令中使用 --release <label>（别名为 --release-version）。--version / -V 仅打印 CLI 版本。

身份验证和环境

变量	用途
TESTCHIMP_API_KEY	项目 API 密钥（作为 TestChimp-Api-Key 发送）。除非设置了 TESTCHIMP_OAUTH_TOKEN，否则为必填项。
TESTCHIMP_OAUTH_TOKEN	由 featureservice 签发的 OAuth 2.1 访问令牌（作为 Authorization: Bearer 发送）。两者都设置时会同时发送，后端优先使用 bearer。
TESTCHIMP_BOT_ID	QA bot ID（作为 bot-id 标头发送，用于归属标记）。必须为 1–64 个不含空格的可打印 ASCII 字符；否则会忽略该值并发出警告。
TESTCHIMP_BACKEND_URL	Featureservice 基础 URL（默认为 https://featureservice.testchimp.io）。
TESTCHIMP_INGRESS_URL	用于 bot 事件确认的 Ingress 基础 URL（默认为 https://ingress.testchimp.io）。
TESTCHIMP_HOME	存放 projects.json 的 TestChimp Studio／CLI 主目录（默认为 ~/.testchimp）。

工作区文件夹映射

将本地仓库文件夹映射到当前用户的 TestChimp 项目。映射保存在 ~/.testchimp/projects.json（或 $TESTCHIMP_HOME/projects.json）中，与 TestChimp Studio 使用同一个文件，因此从命令行映射的文件夹也会显示在 Studio 和无头 AgentWatch 守护进程中。

testchimp workspace map --project-id <id> --folder ~/code/shop [--project-name "Shop"] [--reassign] [--skip-repo-check]
testchimp workspace get --project-id <id>        # prints the mapping JSON; exit 1 when unmapped

workspace map 遵循与 Studio 相同的规则：

• 文件夹必须存在，且是 git 工作树。路径会以规范化的真实路径存储。
• 设置了 TESTCHIMP_API_KEY / TESTCHIMP_OAUTH_TOKEN 时，CLI 会加载项目已连接的仓库（get-git-folder-mapping）。如果已连接仓库，则文件夹必须是仓库根目录，且其中一个 git 远程仓库必须匹配（owner/repo，不区分大小写）。如果未设置凭据、未连接仓库或查询失败，则会跳过检查，并在 stderr 输出提示。查询使用凭据所属的项目，因此请使用同一项目的密钥或机器人令牌运行。--skip-repo-check 会完全跳过查询。
• 一个文件夹只能属于一个项目。将其映射到第二个项目会失败，除非传入 --reassign；此时映射会转移，若原项目不再有任何文件夹，则会移除该项目条目。
• 文件会以原子方式写入（临时文件，然后重命名），权限模式为 0600。其他项目保持不变，较新版本 Studio 写入的未知字段也会保留。若文件不是有效的 JSON 或不符合架构 v2，则会将其移至 projects.invalid.<millis>.json，并替换为空注册表。架构 v1 文件会迁移到 v2。

字节级格式由 fixtures/projects-registry/ 固定，并在 Studio 仓库中保留完全相同的副本。两个测试套件都会重放相同的 upsert 序列，并比较输出字节。

本地运行器的项目密钥（workspace save-creds）

本地运行器（Playwright reporter、此 CLI、k6）需要在其环境中使用项目 API 密钥。TestChimp Studio 将其保存在 <repo>/.testchimp/mcp.json 中；远程 MCP（OAuth）用户也会为每个仓库写入同一个文件：

# CLI: copy TESTCHIMP_API_KEY from the environment (or fetch when TESTCHIMP_OAUTH_TOKEN is set)
testchimp workspace save-creds --folder . --project-id <id> \
  [--project-name "Shop"] [--backend-url <backendUrl>] [--ingress-url <ingressUrl>] [--reassign]

# Local stdio MCP: tool save-workspace-creds { folder, projectId? } — never returns the key
# Hosted / plugin: get-project-credentials, then write .testchimp/mcp.json with a file-write tool
# Legacy: pipe the key on stdin (never as a command-line argument)
printf '%s' "$KEY" | testchimp workspace save-creds --folder . --project-id <id>

• 切勿将密钥放在命令中。标准输入和 TESTCHIMP_API_KEY 仍然可用。密钥绝不会被打印。
• 文件使用 Studio 的精确格式（由 fixtures/workspace-mcp-json/ 固定，并在 Studio 仓库中镜像）：权限模式为 0600，.testchimp/ 目录权限模式为 0700；文件中的其他服务会保留；.testchimp/ 会添加到 .gitignore。该文件夹也会像 workspace map 一样映射到 projects.json。
• 同一项目的现有条目会原样保留（包括 Studio 管理的二进制文件）；只有密钥发生变化时才会刷新。除非传入 --reassign，否则会拒绝另一个项目的条目。

回退机制： 未设置 TESTCHIMP_API_KEY 和 TESTCHIMP_OAUTH_TOKEN 时，CLI 会从当前目录或其上级目录中最近的 .testchimp/mcp.json 读取 TESTCHIMP_API_KEY、TESTCHIMP_PROJECT_ID、TESTCHIMP_BACKEND_URL 和 TESTCHIMP_INGRESS_URL。已导出的变量始终优先，且 --bot 绑定不受影响。该文件必须仅对你本人可读写（权限模式为 0600，与 Studio 和 save-creds 写入的设置相同）；权限允许组用户或所有用户读取的副本（例如提交到克隆仓库中的副本）会被忽略，并显示警告。其他运行器（Playwright、k6）仍需在各自的 shell 中导出这些变量。

QA 机器人

testchimp get-my-tasks --user-id <user-id>      # OAuth tokens imply the user
testchimp list-tests-awaiting-verification --limit 20
testchimp get-qa-posture
testchimp bot get-profile
testchimp bot register-profile --role QA_ENGINEER --responsibilities "Checkout + payments" \
  --capability E2E_AUTHORING --capability TEST_BATCH_FIX \
  --subscriptions-json '[{"eventType":"git-push","filters":[{"field":"author","op":"eq","value":"me"}]},{"eventType":"e2e-batch-completed"}]'
testchimp bot ack <eventId> [<eventId>...] --ack-url <delivery ackUrl>
testchimp bot compat --skill-version 1.0.53

bot ack 会为每个 ID 输出一行 eventId<TAB>status，当任一状态为 BOT_ACK_UNKNOWN_EVENT、BOT_ACK_NOT_A_TARGET 或 BOT_ACK_MISSING_BOT_ID 时，以非零状态码退出。显式指定的 --ack-url 必须使用 https（仅 localhost 可使用 http），且必须指向 TestChimp 主机或 TESTCHIMP_INGRESS_URL 主机。bot compat 以状态码 0 退出，并打印部署最低版本要求以及 cliUpgradeRequired / skillUpgradeRequired。

不使用 TestChimp Studio 的 AgentWatch

testchimp bot connect --project-id <id>       # browser approval (OAuth, "agentwatch" scope)
testchimp bot connect --pair --project-id <id> # or: no browser, your QA bot approves (see below)
npx -y @testchimp/agentwatch query --project-id <id>
testchimp bot disconnect --project-id <id>    # forget the stored keys

无头模式的 AgentWatch 会以用户身份运行，因此需要用户 ID、个人访问密钥和项目 API 密钥。bot connect 会通过环回重定向运行 OAuth 2.1 PKCE 登录，请求选择加入的 agentwatch 作用域（同意页面会提醒密钥将存储在本地），从 /bots/get_agentwatch_credentials 获取密钥，并将密钥和后端及入口 URL 一起写入 ~/.testchimp/agentwatch/credentials.json（权限模式为 0600，按项目存储）。它会立即撤销 OAuth 刷新令牌，并且绝不会打印密钥。批准操作也会让项目选择加入 AgentWatch。

配对（无需在第二个浏览器中同意；QA 机器人使用）。 每个通过 Use this connection as my QA bot 批准的连接都会带有 agentwatch_pair 作用域，因此密钥无需再次通过浏览器登录，也无需经过机器人，就能传送到用户的计算机：

1. 在用户的计算机上：testchimp bot connect --pair [--project-id <id>] 会将随机验证器保存在 ~/.testchimp/agentwatch/pairing.json（0600），并打印 {pairingCode, expiresAtMillis}；配对码是验证器的 SHA-256（base64url）。
2. 机器人使用自己的令牌批准配对：调用 MCP 工具 approve-agentwatch-pairing（或运行 testchimp bot approve-pairing <code>）。
3. 在用户的计算机上：testchimp bot connect --finish-pair 使用验证器兑换密钥（轮询时间最长为 --timeout-ms 指定的时长，默认 60 s），像上述方式一样存储密钥，并删除待处理文件。

配对码只能使用一次，且 10 分钟后过期。机器人只会看到配对码；没有验证器，该码毫无用处。

远程 MCP（Streamable HTTP）

testchimp mcp --http [--port 8080] [--host 0.0.0.0]

POST /mcp 上的无状态 Streamable HTTP。每个请求都必须携带 Authorization: Bearer <OAuth access token>；调用方的令牌会转发给 TestChimp，用于每次工具调用，且绝不会使用服务自身的 TESTCHIMP_API_KEY / TESTCHIMP_OAUTH_TOKEN / TESTCHIMP_BOT_ID。未携带 bearer 的请求会收到 401，并附带 WWW-Authenticate: Bearer resource_metadata="…"。其他端点：GET /.well-known/oauth-protected-resource（RFC 9728 元数据）、GET /healthz。请求正文上限为 1 MB。

按项目指定 URL。 POST /mcp?projectId=<id> 会将每次工具调用限定到该项目：项目 ID 会作为 TestChimp-Project-Id 发送，TestChimp 会检查令牌所属用户是否为项目成员（显式传入的 projectApiKey 参数仍优先）。每个仓库配置一个 URL（例如 {"url": "https://mcp.testchimp.io/mcp?projectId=<id>"}）；同一次登录适用于所有项目。401 挑战和受保护资源元数据都会回显查询参数，因此公布的 resource 与配置的 URL 一致。纯 /mcp 仍使用同意页面上选择的项目。托管式 / 插件 Agent 会调用 get-project-credentials 获取 Runner 密钥，并使用文件写入工具将其写入 <repo>/.testchimp/mcp.json（参见工作区文件夹映射）。本地 stdio MCP 可以调用 save-workspace-creds。

变量	用途
PORT	未提供 --port 时的监听端口（默认 8080；Cloud Run 会设置此值）。
TESTCHIMP_MCP_PUBLIC_URL	此服务的公开基础 URL（例如 https://mcp.testchimp.io）；用于受保护资源的 resource 和 WWW-Authenticate。默认为请求转发的 proto + host。
TESTCHIMP_OAUTH_ISSUER	元数据中公布的授权服务器（默认：TESTCHIMP_BACKEND_URL）。
TESTCHIMP_BACKEND_URL / TESTCHIMP_INGRESS_URL	上游 TestChimp 服务。
TESTCHIMP_PUBLIC_BACKEND_URL / TESTCHIMP_PUBLIC_INGRESS_URL	当上游 URL 为内部地址时，get-project-credentials 为本地 Runner 返回的主机（默认：上游 URL；入口地址根据 featureservice[-env].testchimp.io 推导）。

仓库中的 Dockerfile 会构建一个以非 root 用户运行 testchimp mcp --http 的镜像（适用于 Cloud Run）：

docker build -t testchimp-mcp .
docker run -p 8080:8080 -e TESTCHIMP_MCP_PUBLIC_URL=https://mcp.example.com testchimp-mcp

MCP API 2.0.0

@testchimp/cli 2.0.2 与 TestChimp MCP API 2.0.0（88 个工具）匹配。2.0.2 新增了 ask-user-question-async。2.0.0 共发布 87 个工具，包括全部 70 个 /api/mcp/* 路径以及 bot/workspace 辅助工具。若干 1.x 工具已合并：

旧工具	新工具
provision-ephemeral-environment-and-wait	ephemeral-environment（action=PROVISION，wait 默认值为 true）
report-dast-findings / report-sast-findings / …	report-scan-findings（scanner=DAST|SAST|DEPS|SECRETS）
list-workflow-executions / get-workflow-execution	get-workflow-executions
get-policy / list-policies	get-policies
list-api-operations / get-api-operation-detail	get-api-operations
create-issue / update-issue-status	upsert-issue
get-perf-run	list-perf-runs（runId）
get-release-details	get-release（version + detail=GATE；省略 version 以列出所有版本）

get-eaas-config 保留为独立的连通性检查工具。destroy-ephemeral-environment 未作更改，仍具有破坏性。完整映射请参阅：CHANGELOG.md 和 MIGRATION.md。

从 testchimp-mcp-client 迁移

npm 包 testchimp-mcp-client 已由 @testchimp/cli 取代。将 MCP args 更新为 ["-y", "@testchimp/cli@latest", "mcp"]，并将工具引用重命名为 kebab-case。请参阅 MIGRATION.md。

许可证

MIT