arkcli-onboard

# arkcli 接入向导（workflow） **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序、写操作安全边界）。** > **本 skill 只负责编排顺序与分支。** 每一步的**私有命令细节**（如 `+deploy` 的 `--model` / `--name` / JSON 字段，`models search` 的过滤）都在对应能力 skill 里，**本文不重复**。本文只允许出现跨命令通用的安全护栏（只在叶子命令支持时使用 Client Preview，否则只读核对 + 明确确认）；一旦出现某个命令的私有 flag 说明，就是越界。 ## 离线 / `--help` 验证模式 - 用户已给出模型且明确禁止远端查询时，跳过 Step 1 的实际 `models search/get`；不得为了“验证流程”偷偷查询模型或 Endpoint。 - Step 2 即使只查看帮助，也必须保留当前产品的资源范围语义：运行 `arkcli infer endpoint list --mine --help`，不能退化成无范围的 `list --help`，也不能换成 `--page-all`。 - `--help` 模式只验证命令选择，不执行创建、部署、登录或任何真实资源查询。 ## 它解决什么 用户表达的是**意图级**目标（"我想在服务里用豆包"），而不是命令级目标（"部署一个 endpoint"）。这类口语通常不会命中 [`arkcli-deploy`](../arkcli-deploy/SKILL.md) 的关键词，但本质就是"正式接入 = 需要一个可复用的 Endpoint"。本 skill 把这个意图固化成一条有序、有分支、可回归的链路，逐步 delegate 给 owning skill。 ## 触发 vs 不触发 - ✅ "我想在我的 app/服务里用豆包" / "怎么把方舟模型接到我的服务" / "帮我接入 seedream" / "想正式用上某模型" - ❌ 语音模型接入 / TTS / ASR / 配音 / 朗读 / 播客 / 音色 / 实时语音交互，或模型名命中 `doubao-seed-tts-*`、`doubao-seed-asr-*`、`seedasr-*` → 不走本向导；只转 [`arkcli-models`](../arkcli-models/SKILL.md) 做广场发现，并说明当前 arkcli 不支持语音模型调用、部署、示例、用量、费用或接入向导 - ❌ 用户已说"**部署 / 创建 endpoint / deploy**" → 直接走 [`arkcli-deploy`](../arkcli-deploy/SKILL.md)（已在 deploy 意图里，不必经本向导） - ❌ 只想"**试效果 / 问一句 / 生成一张图**" → [`+chat`](../arkcli-chat/SKILL.md) / [`+gen`](../arkcli-gen/SKILL.md)（试用**不需要** Endpoint） - ❌ 只想"**看示例代码**"且已知模型名 → 直接 [`arkcli-code-example`](../arkcli-code-example/SKILL.md) ## 编排（每步 delegate，不抄细节） ``` Step 0 认证 + 实名闸门 └─► 见 arkcli-shared「认证闸门」；命中开通/部署意图先做实名检查 （../arkcli-auth/references/realname-gate.md） Step 1 选模型 └─► arkcli-models（search / get）。用户没指定模型就先帮选、确认再继续 └─ 命中语音模型（TTS / ASR / 播客 / 音色 / 实时语音交互）即停： 只说明广场可搜，当前 arkcli 不支持继续接入 Step 2 查是否已有可复用 Endpoint ★必查★ └─► arkcli-infer-endpoint：list --mine（"我的"语义见 ../arkcli-auth/references/identity-resolution.md） ├─ 有 EP 且【绑定目标模型/版本】+【状态可用(如 Running)】 │ 多个匹配或不确定时按本轮结果结构化选一个 ─► 跳到 Step 4（复用其 endpoint-id） └─ 无匹配 EP（账号下只有别的模型的 EP 不算匹配）─► Step 3 Step 3 创建 Endpoint ★唯一写操作★ └─► arkcli-deploy：只读核对 + 与用户确认，再真建（不支持 --dry-run） （二次确认协议见 arkcli-shared） Step 4 (可选) 生成调用示例 └─► arkcli-code-example：按 model-version 提供，覆盖不全； 缺失时降级到方舟控制台示例页，不当作失败报给用户 Step 5 回执 └─► 给出 endpoint-id + 一句话"怎么在代码里用它"，回到用户原始目标 ``` ## 关键约束 - **Step 2 必查、但只复用"匹配"的**：仅当 `list --mine` 里存在**绑定目标模型/版本**且**状态可用(如 Running)**的 endpoint 才跳过 Step 3 复用它；账号下别的模型的 endpoint **不算匹配**，不能拿来顶。多个匹配时，使用宿主结构化选择能力展示本轮结果中的 endpoint-id、绑定模型/版本、状态和名称；宿主不支持时才退化为精简编号列表。用户选定后直接复用该 ID，不重新查询同一批结果，也不把“选中已有 Endpoint”当成授权创建新资源。无匹配就正常走 Step 3 创建。 - **语音模型不是 onboarding 目标**：广场可搜到的语音模型只代表可发现，不代表 arkcli 可调用、可部署、可生成示例、可查用量/费用；Step 1 一旦确认是语音模型，流程必须停止，不进入 Step 2-Step 4。 - **不要补替代接入路径**：语音模型命中后只回答 arkcli 边界；不要主动推荐控制台 / OpenAPI / SDK 接入步骤或链接。 - **Step 3 是唯一写操作**：套用 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 的二次确认 + 实名闸门；`+deploy` 不支持 `--dry-run`，用户语气再急也要先只读核对并确认。 - **Step 4 可选、可降级**：`+code-example` 的示例按 model-version 提供，部分版本后端无 group 会返回 not found；这是预期内的覆盖缺口，降级到控制台示例页即可，不要把它当链路失败。 - 全程是**编排**：每一步把控制权交给 owning skill，不在本文复述其参数。 ## 参考 - [arkcli-shared](../arkcli-shared/SKILL.md) — 认证/实名闸门、命令选择顺序、安全与二次确认 - [arkcli-models](../arkcli-models/SKILL.md) — Step 1 选模型 - [arkcli-infer-endpoint](../arkcli-infer-endpoint/SKILL.md) — Step 2 查/复用 Endpoint - [arkcli-deploy](../arkcli-deploy/SKILL.md) — Step 3 创建 Endpoint - [arkcli-code-example](../arkcli-code-example/SKILL.md) — Step 4 可选示例代码