arkcli-api-explorer

arkcli api（Raw API Explorer）

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md，其中包含认证、配置覆盖排查与命令选择顺序 CRITICAL — 只有在现有产品命令和业务 skill 确实不覆盖时，才允许进入本 skill；禁止把 arkcli api 当默认入口。 CRITICAL — 任何 arkcli api ... 调用前，MUST 先用 Read 工具读取 references/arkcli-api.md，禁止盲目猜参数与输出结构。

使用原则

• 先产品命令：arkcli <domain> <verb> 或 arkcli +<shortcut>
• 再 skill / reference：确认是否已有稳定入口与正确参数
• 最后才 arkcli api：仅用于低频、专业或高风险的底层 Action 验证与兜底

不要因为某个 Action 存在，就反推出新的顶层 skill 或 cmd/ 命令；只有升级为稳定产品能力时，才考虑补 shortcuts/。

适用场景

• 现有产品命令确实无法覆盖需求（且该需求不值得做成标准命令或 +shortcut）
• 需要验证某个已注册 Action 的输入输出契约（例如排障、回归验证、确认 transport 可达）
• 需要确认 registry 中是否已存在某个 Action（用于开发或排查 “注册缺失”）

唤起信号（When To Trigger）

• 用户明确提到：action / operation / registry / “已注册 Action” / “契约验证”
• 用户给出：arkcli api ... --params ... 并需要你补全/排错
• 用户遇到：unknown action / 需要确认某个 Action 是否存在
• 开发场景：在 internal/apis/<domain>/ 新增 operation 后，要快速验证能否 --list 与可调用

反唤起信号（When NOT To Trigger）

• 用户目标是：对话（+chat）、生成（+gen）、部署（+deploy）、用量（usage）、查模型（models）等已有稳定产品路径
• 用户只是鉴权失败/未登录/环境 profile 混乱（应先走 auth/config，不要把问题导向 api）
• 用户只是想“找一个命令怎么用”（优先 arkcli <domain> --help + 对应 skill/reference）

Agent 快速执行顺序

1. 先判断用户目标是否已有产品入口：arkcli <domain> --help，并优先转对应业务 skill
2. 如果只是认证/配置问题，不要误判为需要 api：
   • 认证失败先转 ../arkcli-auth/SKILL.md
   • profile/base-url/region 覆盖混乱先转 ../arkcli-config/SKILL.md
3. 枚举已注册 Action（无参等价于 list）：
   • arkcli api --list
   • arkcli api
4. 定位契约与必填字段（禁止猜 JSON）：
   • 在代码中查 internal/apis/<domain>/ 对应的 req/resp 结构体
5. 先用叶子命令的 Client Preview 核对最终 descriptor 和 payload：
   • arkcli api <registered-action> --params '{...}' --dry-run
   • Preview 是纯本地行为，不登录、不请求后端、不证明权限、配额或资源存在
6. 只读优先；写操作在 Preview 后仍必须二次确认，然后去掉 --dry-run 执行：
   • arkcli api <registered-action> --params '{...}'
   • payload 自身的 "DryRun":true 是后端字段；未加 CLI --dry-run 时仍会发出真实网络请求
7. 输出尽量稳定、减少噪声：
   • 优先用全局 --transform '<gjson path>' 提取关键字段
   • 只有排障需要时才开 --debug（会输出请求/响应调试信息到 stderr）