| name | arkcli-api-explorer |
| version | 1.1.0 |
| description | arkcli Raw API Explorer：调用已注册的 Action 作为产品命令的兜底能力。当现有 `arkcli <domain> <verb>` 无法覆盖需求，或需要验证底层 Action 契约时使用。 |
| metadata | {"requires":{"bins":["arkcli"]},"cliHelp":"arkcli api --help"} |
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 快速执行顺序
- 先判断用户目标是否已有产品入口：
arkcli <domain> --help，并优先转对应业务 skill
- 如果只是认证/配置问题，不要误判为需要
api：
- 枚举已注册 Action（无参等价于 list）：
arkcli api --listarkcli api
- 定位契约与必填字段（禁止猜 JSON）：
- 在代码中查
internal/apis/<domain>/ 对应的 req/resp 结构体
- 只读优先、写操作必须二次确认，然后再执行：
arkcli api <registered-action> --params '{...}'
- 输出尽量稳定、减少噪声：
- 优先用全局
--transform '<gjson path>' 提取关键字段
- 只有排障需要时才开
--debug（会输出请求/响应调试信息到 stderr）
Guard Checklist（必须执行）
| 检查点 | 目的 | 做法 |
|---|
| 产品命令覆盖判断 | 防止误用 api | 先 arkcli <domain> --help 并对照对应 skill |
| 认证闸门 | 防止把鉴权问题误判为缺能力 | 先 arkcli auth status；失败转 arkcli-auth |
| 契约事实源 | 防止猜参数 | 必须从 internal/apis/<domain>/ 的 req/resp tag 生成 --params |
| 风险确认 | 防止写操作误触发 | 涉及创建/删除/修改/影响费用前，要求用户明确确认 |
| 噪声控制 | 防止整坨输出污染上下游 | 默认引导 --transform 提取关键字段；--debug 仅排障打开 |
示例
arkcli api --list
arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}'
arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --transform 'Result.Items.#.Name'
常见错误与处理
| 现象 | 常见原因 | 处理方式 |
|---|
unknown action "..." | Action 未注册或拼写错误 | 先 arkcli api --list；再在 internal/apis/ 中确认是否已注册 |
invalid --params JSON: ... | JSON 不合法（引号/转义/单引号包裹不当） | 确保 --params 是合法 JSON；必要时把 JSON 放到文件再用 shell 展开传入 |
| 输出字段和预期不一致 | 直接猜测了契约 | 先读 references/arkcli-api.md 并查看 internal/apis/<domain>/ 的 req/resp |
开发约束
- 如果 Action 未注册：补
internal/apis/<domain>/ 的 operation 注册与 req/resp 契约
- 不要直接因为 Action 缺失就新增
cmd/<action>；api 是兜底入口
- 只有当它升级为稳定产品能力时，才在
shortcuts/ 中补业务命令（并配套 skill/reference/test）
参考
