在需要调用 Clerk Backend REST API…

需要浏览或执行 Clerk Backend API（用户、组织、邀请、元数据等）时使用，重点保证写/删操作前的密钥、权限与确认检查。

适用场景

解决思路

1. 在每次写请求（POST/PATCH/PUT/DELETE）前，必须完成 CRITICAL 区的全部强制检查。
2. 检查 CLERK_SECRET_KEY 是否已设置：运行 `echo $CLERK_SECRET_KEY | head -c 10`；若为空，停止并询问用户；没有有效 key 不得继续。
3. 检查 CLERK_BAPI_SCOPES：运行 `echo $CLERK_BAPI_SCOPES`；检查输出；若缺少或不包含所需写权限，告诉用户："This is a write operation and your current scopes may not allow it. Rerun with --admin to bypass?"；不要尝试请求后失败，先询问。
4. 对 DELETE 请求：明确警告该操作 IRREVERSIBLE，并精确列出将被永久销毁的数据（用户记录、所有会话、所有成员关系、所有关联数据）；要求显式确认后才继续；该警告 MANDATORY，绝不能跳过。
5. 对 metadata 操作：始终解释使用的是哪种 metadata 类型以及为什么（见 Metadata types）。
6. 常见操作走 FAST PATH：直接执行，不先抓取 spec；按模板替换 `$CLERK_SECRET_KEY`、`$USER_ID`、`$ORG_ID`、`$EMAIL` 等上下文变量。
7. 创建组织 + 邀请成员（两步）：Step 1 使用 `curl -s -X POST "https://api.clerk.com/v1/organizations" -H "Authorization: Bearer $CLERK_SECRET_KEY" -H "Content-Type: application/json" -d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}"` 创建组织，并用 `python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))"` 格式化输出。
8. Step 2 提取组织 ID：`ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")`。
9. Step 3 邀请成员：`curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" -H "Authorization: Bearer $CLERK_SECRET_KEY" -H "Content-Type: application/json" -d "{\"email_address\": \"user@example.com\", \"role\": \"org:admin\"}"`，角色使用 `"org:admin"` 或 `"org:member"`，始终带 `org:` 前缀。
10. SDK 等价写法（Next.js/TypeScript 项目使用 `@clerk/nextjs` 或 `@clerk/backend`）：`import { clerkClient } from '@clerk/nextjs/server'`；或 `import { createClerkClient } from '@clerk/backend'; const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`。
11. SDK 创建组织：`await clerkClient.organizations.createOrganization({ name: 'Acme Corp', createdBy: userId })`，`createdBy` 必填。
12. SDK 邀请成员：`await clerkClient.organizations.createOrganizationInvitation({ organizationId: org.id, emailAddress: 'user@example.com', role: 'org:admin' })`，role 可为 `org:admin` 或 `org:member`。
13. 更新用户 metadata 前，始终解释三类 metadata：public_metadata（客户端+服务端可读，仅服务端可写，用于前端读取的 plan tier、roles、feature flags）；private_metadata（仅服务端可读可写，用于 Stripe IDs、合规标志、内部标识）；unsafe_metadata（客户端+服务端可读可写，用于临时 UI 状态、onboarding 步骤，避免敏感数据）。
14. 对 `plan: 'pro'` 和 `onboarded: true` 使用 `public_metadata`：`curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" -H "Authorization: Bearer $CLERK_SECRET_KEY" -H "Content-Type: application/json" -d '{"public_metadata": {"plan": "pro", "onboarded": true}}'`，解析并打印更新结果。
15. SDK 更新 metadata 等价写法：`await clerkClient.users.updateUser(userId, { publicMetadata: { plan: 'pro', onboarded: true }, // privateMetadata: { stripeId: 'cus_xxx' }, // unsafeMetadata: { step: 'welcome' } })`；注意 REST 用 `snake_case`（`public_metadata`），SDK 用 `camelCase`（`publicMetadata`）。
16. 列出最近 7 天用户：`curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" -H "Authorization: Bearer $CLERK_SECRET_KEY" | python3 -c "..."`，用 python3 解析；若是列表，打印数量和每个用户 ID/email；否则 pretty-print。
17. 删除用户需要确认：只在用户显式确认后运行 `curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" -H "Authorization: Bearer $CLERK_SECRET_KEY" | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Deleted: {d}')"`，并解析打印删除结果。
18. 完整端点参考：Base URL 为 `https://api.clerk.com/v1`；每个请求都加 `Authorization: Bearer $CLERK_SECRET_KEY`。
19. Users：List users `GET /v1/users`，query params：`limit`（最大 500，默认 10）、`offset`、`order_by`（+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at）、`email_address[]`、`phone_number[]`、`username[]`、`web3wallet[]`、`user_id[]`、`query`、`created_at`（ISO 8601 range：gt:TIMESTAMP 或 lt:TIMESTAMP，Unix ms）；返回 User 对象数组。
20. Users：Get user `GET /v1/users/{user_id}`，返回 User 对象。
21. Users：Update user `PATCH /v1/users/{user_id}`，Body JSON 使用 `snake_case`：`{ public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... }`。
22. Users：Delete user `DELETE /v1/users/{user_id}` 是 IRREVERSIBLE；销毁用户记录、所有会话、所有成员关系、所有关联数据；返回 `{ id, object, deleted: true }`；始终警告并确认后再继续。
23. Organizations：Create organization `POST /v1/organizations`，Body：`{ name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? }`，返回含 `{ id, name, slug, ... }` 的 Organization 对象。
24. Organizations：List organizations `GET /v1/organizations`，query params：`limit`、`offset`、`query`、`order_by`。
25. Organizations：Invite member `POST /v1/organizations/{organization_id}/invitations`，Body：`{ email_address: string, role: string ("org:admin" 或 "org:member"), public_metadata?, private_metadata? }`，返回 OrganizationInvitation 对象。
26. 执行请求：始终用直接 `curl` 命令；可用 spec-extraction 脚本（`api-specs-context.sh`、`extract-tags.js`、`extract-endpoint-detail.sh`）发现端点，但实际 API 调用用 `curl`；不要用 `scripts/execute-request.sh`（本地开发辅助，不供 agent 使用）。
27. GET 请求模板：`curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" -H "Authorization: Bearer $CLERK_SECRET_KEY"`。
28. POST/PATCH 请求模板：`curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" -H "Authorization: Bearer $CLERK_SECRET_KEY" -H "Content-Type: application/json" -d '${BODY_JSON}'`。
29. DELETE 请求模板：`curl -s -X DELETE "https://api.clerk.com/v1${PATH}" -H "Authorization: Bearer $CLERK_SECRET_KEY"`。
30. 得到响应后：清晰解析并展示；用 `python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))"` pretty-print JSON；提取关键字段（id、email、name 等）并向用户总结。
31. API specs context：在 FAST PATH 之外做任何事之前，先运行 `bash scripts/api-specs-context.sh` 获取可用 spec 版本和 tags，用输出确定 latest version 和 available tags。
32. Caching：如果本次对话之前已抓取过 spec context，不要再抓；复用之前的 version 和 tags。
33. Rules：常见操作（list users、create org、invite、update metadata、delete user）使用 FAST PATH，不先抓 spec。
34. Rules：始终忽略与 `platform` 相关的 endpoints/schemas。
35. Rules：始终在写请求（POST/PUT/PATCH/DELETE）前确认。
36. Rules：DELETE 操作始终警告 irreversible，并说明会丢失的数据（user record、sessions、memberships）；警告 MANDATORY，绝不跳过。
37. Rules：写操作前检查 `CLERK_BAPI_SCOPES`；若缺失或不足，提前询问用户；不要尝试后失败；该检查 MANDATORY。
38. Rules：metadata 操作始终解释 public、private、unsafe 三种类型，并推荐合适的一种。
39. Rules：分页始终使用 `limit` + `offset`，并说明大数据集结果可能分页。
40. Rules：所有 API 调用使用直接 curl 命令，绝不用 `scripts/execute-request.sh`。
41. Rate limits：Production 1,000 requests / 10 seconds；Development 100 requests / 10 seconds；Single invitations 100 / hour；Bulk invitations 25 / hour；Org invitations 250 / hour；Frontend API sign-in creation 5 / 10 seconds；Frontend API sign-in attempts 3 / 10 seconds；List users max per page 500。
42. Rate limits gotcha：`currentUser()` 会发起真实 API 调用并计入速率限制；若只需要 session claims，用 `auth()`，它从 token 读取而不发起 API 调用。
43. Metadata overwrites：`updateUser({ publicMetadata: { role: 'admin' } })` 会 REPLACE 所有 public metadata，而不是 merge；要新增字段而不丢已有数据，先读、展开、再写。
44. Metadata overwrites wrong：不要直接 `await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } })`，这会删除其他 `publicMetadata` 字段。
45. Metadata overwrites right：先 `const user = await clerkClient.users.getUser(userId)`，再 `await clerkClient.users.updateUser(userId, { publicMetadata: { ...user.publicMetadata, newField: 'value' } })`。
46. Modes：根据 $ARGUMENTS 判断模式：`help`（空或仅 `help`/`-h`/`--help`）打印用法；`browse`（prompt 为 `tags` 或 tag 名如 `Users`）列出 tags 或该 tag 的 endpoints；`execute`（具体 endpoint 如 `GET /users` 或自然语言动作如 “get user john_doe”）查端点并执行；`detail`（endpoint + `help`/`-h`/`--help`，如 `GET /users help`）显示 endpoint schema，不执行。
47. 默认使用 API specs context 中的 LATEST VERSION；若用户指定不同版本（如 `--version 2024-10-01`），使用指定版本。
48. Step 0 Print usage：仅在 `help` 模式，跳过 browse/execute/detail；逐字打印给出的 Browse/Execute/Inspect/Options 示例；然后停止。
49. Step 1 Fetch tags：在 `browse`（prompt 为 `tags` 或未指定 tag）模式；若非 latest 版本，运行 `curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js`；否则使用 API specs context 中的 TAGS；用表格分享 tags 并提示用户选择查询。
50. Step 2 Fetch tag endpoints：在 `browse`（提供 tag 名）模式；运行 `curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}"`；分享 endpoints、schemas、parameters。
51. Step 3 Fetch endpoint detail：在 `execute`、`detail` 模式；对 `execute` 的自然语言提示，先检查是否匹配 FAST PATH，若匹配跳过本步并直接到 step 4 使用 FAST PATH 模板；其他 endpoint 通过 context 中的 tags 搜索匹配项，必要时先 fetch tag endpoints 解析精确 path/method；运行 `curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${path}" "${method}"`；`${path}` 如 `/users/{user_id}`，`${method}` 小写如 `get`；`detail` 模式分享 endpoint 定义和 schemas 后停止；`execute` 模式继续 step 4。
52. Step 4 Execute request：仅 `execute` 模式；1 运行 CRITICAL 强制检查；2 从 spec（step 3）或 FAST PATH 识别必填/可选参数；3 询问用户未提供的必填 path/query/body 参数；4 构建并执行直接 curl 命令，不要用 `scripts/execute-request.sh`；5 解析 JSON 响应并清晰展示，提取关键字段并向用户总结。
53. Step 4 示例：列出用户并解析响应：`RESPONSE=$(curl -s "https://api.clerk.com/v1/users?limit=10" -H "Authorization: Bearer $CLERK_SECRET_KEY")`，然后 `echo "$RESPONSE" | python3 -c "..."`。
54. 相关技能参考：`clerk-setup`（初始 Clerk 安装）、`clerk-orgs`（通过 API 管理组织）、`clerk-webhooks`（实时事件同步）。

适用边界 · 注意事项

• 没有 Clerk 账号、未配置 CLERK_SECRET_KEY（sk_*）或无法提供有效密钥时不要使用本技能。
• 只需要前端 Clerk 能力或只读 session claims 时不必调用 Backend API（可用 auth()，避免 currentUser() 的 API 调用）。
• 缺少写入所需 CLERK_BAPI_SCOPES 且用户不打算用 --admin 绕过时，不要执行 POST/PATCH/PUT/DELETE 写操作。