OOMOL Clerk 连接器

解决什么问题

把 Clerk 当作应用的身份与访问管理层时，运营侧总会冒出需要直接操作账号的请求：封禁一个骚扰用户、给某个用户补一条 metadata、清理一批遗留的测试账号。这类事要么在 Clerk Dashboard 里手工点，要么写一次性脚本，凭据、分页、错误处理全都得自己管。

oo-clerk 把这类操作收敛成一个可被 Agent 调用的技能。它封装了 Clerk 连接器的 11 个动作，你给出结构化的 JSON 输入，连接器负责翻译成对应的 API 调用，返回统一的执行结果。

技能如何工作

凭证由 OOMOL 服务端注入，本地不需要保存 Clerk 的 API key 或 token。执行一个动作分三步：

• 先看契约：用 oo connector schema 拉取权威的输入/输出 schema，不要凭记忆拼 payload。
• 再跑动作：--data 接收 JSON 对象字符串或 @path/to/file.json，不传则等价于 {}。
• 读执行 ID：响应统一是 { "data": ..., "meta": { "executionId": "..." } }，meta.executionId 要留好，便于事后排查。

11 个动作按用途分四类：

• 读取类：get_user、list_users、count_users
• 写入类：create_user、update_user、update_user_metadata
• 状态类：ban_user、unban_user、lock_user、unlock_user
• 危险类：delete_user

其中 update_user_metadata 是深度合并语义，适合只追加或更新某个键，而不是覆盖整段 metadata。

适用边界与注意点

安全模型是最主要的边界。读取类动作可以直接执行；但所有 create / update / send 类动作都会改变 Clerk 侧状态，必须在运行前向用户确认完整 payload 和预期效果。delete_user 属于破坏性操作，要明确指出目标并获得显式批准。

鉴权和连接只在命令真正失败时才处理，不要每次调用都重跑一遍登录。错误码指向不同的处理：scope_missing、credential_expired、app_not_ready 说明 Clerk 未连接、凭据过期或缺少 scope；HTTP 402 与 OOMOL_INSUFFICIENT_CREDIT 是额度问题，需要充值后再试。

另外，list_users 和 count_users 都支持可选过滤与分页。只需要某个条件下的用户总数时，用 count_users 比把分页全拉回来再自己数更省资源。