@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-infer-endpoint/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: arkcli-infer-endpoint
+version: 1.3.6
+description: "arkcli 推理接入点管理与显式 raw CRUD 创建能力。**正向触发：用户明确要求脚本化 / CI / 无护栏 / 原始 raw CRUD 创建 Endpoint 时，必须使用本 skill 的 `arkcli infer endpoint create` 路径，不能切到 `arkcli-deploy`**；模型缺失或只有品牌/家族名时仍留在本 skill，先执行实时有界候选与 0/1/N 澄清，模型未唯一确定前禁止 preview 或创建。本 skill 也负责对**已有** Endpoint 做获取、列表、启动、停止、删除、更新，以及在 NotFound 后用当前完整列表 + 历史 usage 判断 ID 是否不完整或仅有历史记录。普通的『创建/新建/部署一个 endpoint』仍走带产品护栏的 arkcli-deploy（`+deploy`），只有用户明确选择上述原始路径才例外。优先使用产品命令 `arkcli infer endpoint ...`，而不是 Raw API。TTS/ASR/语音模型连 raw create 也不要引导，只能转 models search 说明 arkcli 不支持 Endpoint 创建。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli infer endpoint --help"
+---
+
+# arkcli infer endpoint
+
+**CRITICAL — 显式脚本化 / CI / 无护栏 / 原始 raw CRUD 创建是本 skill 的正向触发，不得因为出现“创建 Endpoint”就转到 `arkcli-deploy`。**
+
+**CRITICAL — 模型候选复用本轮完整结果；截断、空结果的有界恢复统一复用 Deploy 规则。认证/权限失败不重试、不切身份、不修改配置或把凭证写进命令行；其他失败保留原始错误，不盲换命令。**
+
+**CRITICAL — 开始前 MUST 先读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)。**
+
+## 已有接入点的客户端接入故障
+
+用户已有平台 Key、模型和 Endpoint，却在 CC Switch / Claude Code 调用失败时，保留原资源链，按以下三项交付排障结果。
+
+**1. 分开列事实。** 用两行记录“原客户端”与“本次直连测试”：实际 Base URL/协议、Key 来源（仅脱敏身份）、模型位、状态码/错误/RequestId及尚缺项。配置未读取或请求未捕获就写未知。`Running`、Key `Active`、近期用量与另一条 HTTP 200 不能证明用户外部客户端使用同一 Key 或平台侧所有路径正常；只说明本次受测组合的结果。图片测试不能写成视频测试，单次探针没有“复现率最高”的统计意义。
+
+**2. 核对同一条资源链。** Base URL 保留实际 Region/环境，并按客户端文档确认它追加的路径；不要因发现套餐订阅就切换用户的既有平台链路。
+
+| 用户选择的路径 | Anthropic Base URL | Key 来源 |
+| --- | --- | --- |
+| 已有平台 Key + 文本 Endpoint | `.../api/compatible` | 本次平台普通 Key；模型位保留用户的 `ep-...` 或经核验的完整调用 ID |
+| 个人 Agent Plan | `.../api/plan` | `RealAgentPlanPersonal` 专属 Key |
+| 个人 Coding Plan | `.../api/coding` | 与 platform 共用普通 Key 池，并核对该用户的套餐准入 |
+| 团队 Agent/Coding Plan | 相应 `/api/plan` 或 `/api/coding` | 对应有效席位 Key |
+
+OpenAI `/api/v3` 及套餐 `/v3` 是另一协议入口，不能直接当 Anthropic Base URL。只有用户选择套餐路径时再按 [plans](../arkcli-plans/SKILL.md) 展开，不为诊断切 Profile、轮换 Key 或重建资源。请求未发出、环境变量为空、401、404分别按原报文核查；不把它们都归为“Key失效”。
+
+**3. 给出可验证的下一步。** 先核对用户当前启用配置与新会话 `/status` 显示的 Base URL、Model 和认证来源，只检查凭证是否已赋值，不打印值。客户端模型位/fallback 行为以该版本实际配置或文档为准：“可能 fallback”仍是待核查条件，不能扩大成必然失败或自行补出标题生成等触发场景；直连404也不能代写客户端“完全无响应”。
+
+用户要求且授权真实试调用时，提供一次与原客户端相同协议的最小请求：平台兼容路径为 `POST .../api/compatible/v1/messages`，保留原调用 ID，用 `messages` 和明确的小 `max_tokens` 预算；Key由获准的受控进程注入，不放入聊天、可见argv或日志。记录状态码、非敏感错误/RequestId与实际响应；不要用默认走Responses的`+chat`当作Anthropic链路自证。未获准则交付此检查步骤，标注尚未执行。直连成功而原客户端仍失败时，继续比较实际生效配置、会话和网络/代理，结论保持原故障尚未定位，不承诺换配置必然修好。
+
+## 使用原则
+
+- 推理接入点相关需求优先使用 `arkcli infer endpoint ...`
+- 这些命令虽然是标准 CLI 类型，但实现入口仍然来自 `shortcuts/inferendpoint/`
+- 只有产品命令无法覆盖时，才回退到 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md)
+- `infer endpoint create` 成功后会返回 Endpoint `Id`
+- 这个 `Id` 应作为后续 `get / start / stop` 的输入，也可以传给 [`../arkcli-code-example/SKILL.md`](../arkcli-code-example/SKILL.md) 生成带真实 `endpoint-id` 的调用示例
+- 如果已经通过 `infer endpoint create` 拿到 `Id`，不要再调用 `+deploy` 试图"二次部署"；`+deploy` 本身就是创建 Endpoint 的工作流
+- `infer endpoint create --billing-method` 当前只支持 `token`；它是可选项，显式传 `token` 时会先校验模型是否支持 token 推理方式，创建请求本身保持默认行为
+- **语音模型不是 Endpoint create 目标**：TTS / ASR / 配音 / 播客 / 音色 / 实时语音交互，或模型名命中 `doubao-seed-tts-*`、`doubao-seed-asr-*`、`seedasr-*` 时，不要用 `infer endpoint create` 或 Raw CRUD 绕过；只转 [`arkcli-models`](../arkcli-models/SKILL.md) 说明"广场可搜，但当前 arkcli 不支持 Endpoint 创建"。
+
+## 「我的接入点」语义
+
+用户说**"我的推理接入点 / 我创建的 / 我有多少个 / 列出我的"** → 必须加 `--mine --page-all`：
+
+```bash
+arkcli infer endpoint list --mine --page-all --page-size 100 --format json
+```
+
+服务端按 `sys:ark:createdBy` tag 过滤，只返回当前 SSO sub-user 创建的 endpoint。
+需要 SSO 子账号身份；root 账号 / AK-SK 报错不算空结果，认证处理服从当前 shared 宿主协议，不自动重登。
+详细行为见 [`references/arkcli-infer-endpoint-list.md`](references/arkcli-infer-endpoint-list.md)。
+
+### 本人查询为空的三级恢复
+
+1. `--mine` 查询成功、完整且 `.TotalCount == 0` / `.Items == []` 才进入下一层；鉴权、权限、网络、参数错误及分页不完整均不能当空。
+2. 向用户说明接下来查“当前用户 API Key 用过的 EP”，不冒充“本人创建”。按 [usage stats](../arkcli-usage/references/arkcli-usage-stats.md) 使用 `arkcli usage stats --start <29天前日期> --end <今天日期> --mine --mine-by=apikey --by endpoint --format json`；原请求有时间范围就保留。对完整结果里的非空 `ModelEndpoint` 去重，逐个 `infer endpoint get <真实ID>`，保留原 `--status` / `--model` 条件（get 结果本地核对）。不能给 endpoint list 发明 `--mine-by`。历史 ID 当前 NotFound 时单列“历史调用过、当前不可见”，不称已删除；其他失败原样报告。
+3. 第二层也成功但没有非空历史 ID 时，询问用户是否查看账号全量；已明确授权该范围时可继续。执行 `arkcli infer endpoint list --page-all --page-size 100 --format json` 并保留原筛选条件，结果明确标“账号全量 fallback（已取消 --mine，不能保证本人创建）”。拒绝扩大范围则交付本人查询为空，不自动全账号。
+
+
+## Endpoint NotFound 的只读排障
+
+任何调用异常先读 [get reference 的排障分支](references/arkcli-infer-endpoint-get.md)，区分控制面状态、历史用量与真实调用证据；盘点/导出先读 [list reference](references/arkcli-infer-endpoint-list.md) 的分页、限流、时区与交付要求。已知精确 ID 时先直接 get，不为所有问题先列全账号。
+
+用户已经观察到 `InvalidEndpointOrModel.NotFound`，或 `get` 查不到某个 Endpoint 时，不要直接宣称「已删除」，也不要猜测尾部字符。按两个独立事实源收敛：
+
+**禁止仅按 ID 长度、形状、当前列表里的其他 ID 或常见格式，声称用户输入「缺少后缀 / 缺少随机字符 / 不是完整 ID」。** 只有当前列表返回了以用户输入为前缀的唯一真实 ID，才能把该完整 ID 作为证据复述；否则只能报告未找到。
+
+1. 查当前身份与 project 可见的完整列表，同时核对精确 ID 和用户所给前缀。列表可能很大，必须在 shell 内只保留匹配项，避免把无关 Endpoint 全量灌入 Agent 上下文：
+
+   ```bash
+   arkcli infer endpoint list --page-all --page-size 100 --format json \
+     | jq --arg id '<endpoint-id>' '[.Items[]? | select(.Id == $id or (.Id | startswith($id)))]'
+   ```
+
+   `<endpoint-id>` 必须替换为用户提供的原值；不得省略 `--page-all` 后只拿第一页下结论。
+2. 读取 [`../arkcli-usage/references/arkcli-usage-stats.md`](../arkcli-usage/references/arkcli-usage-stats.md)，再用 `arkcli usage stats --start <YYYY-MM-DD> --end <YYYY-MM-DD> --endpoint <endpoint-id> --format json` 核对历史用量。用户给了时间范围就照用；没给时默认查最近 30 天，必须把占位符换成实际日期。
+
+结论必须与证据强度对齐：
+
+- 当前列表找到唯一的完整 ID：复述真实 ID，说明原输入是否少尾部；不要凭格式自己补齐。
+- 当前列表无记录、但历史用量有记录：只能说「曾经有调用，当前不可见」，不能单凭这两步区分已删除、换身份或换 project。
+- 两处都没有证据：报告「未找到」，建议核对原始 ID、profile 和 region；禁止为了让任务继续而创建 Endpoint、切 profile 或走 Raw API。
+
+## `infer endpoint create` 与 `+deploy` 的边界
+
+`infer endpoint create` 是**原始 CRUD**，适合脚本化 / CI / 需要无护栏可预测行为的场景。注意它的 flag 集其实是 `+deploy` 的**子集**（`+deploy` 才是参数超集），差别在"有没有工作流护栏"，不是"谁参数更多"。它**不包含** `+deploy` 的以下护栏：
+
+| 护栏 | `+deploy` | `infer endpoint create` |
+|------|-----------|------------------------|
+| 实名前置校验（[realname-gate.md](../arkcli-auth/references/realname-gate.md)） | ✅ | ✅（foundation model 路径同样触发 `EnsureModelAvailable`，含实名拦截） |
+| 自定义模型复用检查（避免重复计费） | ✅ | ❌ |
+| 部署后 profile 默认资源同步（`--set-default`） | ✅ | ❌ |
+
+**路由判定**：只要用户意图是"创建 / 新建 / create 一个 endpoint / 接入点"或"把模型部署 / 上线"（无论用词是 create 还是 deploy），一律路由到 `+deploy`（[arkcli-deploy](../arkcli-deploy/SKILL.md)）；**只有**用户明确需要绕过工作流护栏、脚本化 / CI、或要无护栏的可预测 raw CRUD 行为时，才使用 `infer endpoint create`。
+
+**例外**：如果目标是语音模型（TTS / ASR / 播客 / 音色 / 实时语音交互），不要因为用户说了"create endpoint"就进入本 skill；语音模型在 arkcli 当前只支持 `models search` 发现，不支持 Endpoint 创建。
+
+## raw CRUD 创建前的模型澄清
+
+本节只在用户已经明确选择脚本化 / CI / 无护栏 raw CRUD 路径、但 `--model` 仍缺失或只有品牌、系列、家族名时生效。普通创建意图仍按上一节路由到 [`arkcli-deploy`](../arkcli-deploy/SKILL.md)，不能因为模型未定就改走 raw create。
+
+候选生成必须复用 [`arkcli-deploy` 的「创建意图中的模型澄清」](../arkcli-deploy/SKILL.md#创建意图中的模型澄清)契约：初次执行有界的实时 `arkcli models search [<keyword>] --size 10 --format json`，只从本轮结构化结果读取真实字段。过滤、完整模型 ID、创建时间排序、模态覆盖、0/1/N 处理及截断/空结果恢复均与 `+deploy` 一致，不能另立更严格的一次查询即停止策略。只有恢复仍不完整时才停止；禁止全量盲查、逐候选循环 get 或凭记忆补版本。
+
+- **0 个候选**：如实说明本轮没有查到，请用户补充用途、模态或关键词。
+- **1 个候选**：复述本轮返回的完整模型 ID，请用户确认。
+- **多个候选**：优先使用当前宿主提供的结构化选择能力，把本轮实时返回的精简候选直接列成选项；通用 Skill 不写死宿主工具名，如果宿主会自动补自由输入项，不要再添加“其他 / 手动指定”重复兜底。宿主没有结构化选择能力时，才退化为精简列表并要求用户明确回复一个完整 ID。
+
+选定唯一模型后，仍保持在 `arkcli-infer-endpoint` 的 raw CRUD 路径：先生成 `arkcli infer endpoint create ... --dry-run` 的本地 `preview.v1`；用户只要求预览时到此停止，要求真实创建时继续遵守共享写操作守卫。模型未唯一确定前，禁止执行 `--dry-run`、真实 `infer endpoint create`、`+deploy` 或 Raw API 创建。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `arkcli infer endpoint create` | 创建推理接入点（原始 CRUD，无部署工作流护栏）；**新建接入点的默认意图请用 `+deploy`**，此命令仅限脚本化 / 无护栏 raw CRUD 场景 |
+| `arkcli infer endpoint get <endpoint-id>` | 获取推理接入点详情 |
+| `arkcli infer endpoint list [--mine]` | 列出推理接入点；用户说**"我的 / 我自己的 / 我创建的 / 我有多少"**时必须加 `--mine`（SSO sub-user 过滤） |
+| `arkcli infer endpoint start <endpoint-id>` | 启动推理接入点 |
+| `arkcli infer endpoint stop <endpoint-id>` | 停止推理接入点 |
+| `arkcli infer endpoint delete <endpoint-id>` | 删除推理接入点（**不可逆**，需二次确认；非交互环境需 `ARKCLI_ALLOW_HEADLESS_DELETE=1`，`--yes` 不授权） |
+| `arkcli infer endpoint update <endpoint-id>` | 更新推理接入点（名称 / 描述 / 限流） |
+
+## 参考
+
+- [`references/arkcli-infer-endpoint-create.md`](references/arkcli-infer-endpoint-create.md)
+- [`references/arkcli-infer-endpoint-get.md`](references/arkcli-infer-endpoint-get.md)
+- [`references/arkcli-infer-endpoint-list.md`](references/arkcli-infer-endpoint-list.md)
+- [`references/arkcli-infer-endpoint-start.md`](references/arkcli-infer-endpoint-start.md)
+- [`references/arkcli-infer-endpoint-stop.md`](references/arkcli-infer-endpoint-stop.md)
+- [`references/arkcli-infer-endpoint-delete.md`](references/arkcli-infer-endpoint-delete.md)
+- [`references/arkcli-infer-endpoint-update.md`](references/arkcli-infer-endpoint-update.md)
+- [`../arkcli-code-example/SKILL.md`](../arkcli-code-example/SKILL.md)

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-create.md

@@ -0,0 +1,142 @@
+# arkcli infer endpoint create
+
+创建一个推理接入点（Endpoint）。
+
+## Usage
+
+```bash
+arkcli infer endpoint create [flags]
+```
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--model` | string | 模型 ID（基础模型或自定义模型） | Yes |
+| `--name` | string | Endpoint 名称 | Yes |
+| `--billing-method` | string | 计费 / 推理方式；当前仅支持 `token`，不传时保持默认行为 | No |
+| `--rpm` | int | 速率限制 RPM | No |
+| `--tpm` | int | 速率限制 TPM | No |
+| `--dry-run` | bool | 输出本地创建计划，不调用模型查询、开通或创建 API | No |
+| `-h`, `--help` | | help for create | No |
+
+Client Preview 的 `ModelReference` 与模型开通检查依赖在线信息，因此输出为
+`fidelity=partial` 并列出 `unresolved`。它不是服务端 validation，也不证明模型
+已开通或请求会被接受。
+
+
+## 模型未指定时
+
+`--model` 是必填参数。用户已经明确选择脚本化 / CI / 无护栏 raw CRUD，但没有给模型或只给品牌、系列、家族名时，不要凭记忆补全，也不要先用缺失参数试跑 `--dry-run`：
+
+1. 读取 [`../SKILL.md` 的「raw CRUD 创建前的模型澄清」](../SKILL.md#raw-crud-创建前的模型澄清)。
+2. 只执行一次有界的实时 `arkcli models search [<keyword>] --size 10 --format json`，从本轮结构化结果形成 0/1/N 候选。
+3. 多候选优先用宿主的结构化选择能力让用户选择；选项只能来自本轮返回，禁止全量 `models list`、逐候选 `models get` 或凭记忆补版本。
+4. 选定唯一完整模型 ID 后再运行本地 `--dry-run`。用户只要求预览时停止；真实创建继续遵守共享写操作守卫。
+
+普通“创建 / 部署 Endpoint”意图仍应走 [`arkcli-deploy`](../../arkcli-deploy/SKILL.md)；本节不能把普通创建降级成无护栏 raw CRUD。
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |
+
+## 示例
+
+```bash
+# 创建 Endpoint
+arkcli infer endpoint create \
+  --model doubao-seed-2-0-pro-260215 \
+  --name my-endpoint
+
+# 显式要求 token 推理方式（当前与不传时的创建 payload 保持一致，但会先校验模型是否支持 token）
+arkcli infer endpoint create \
+  --model doubao-seed-2-0-pro-260215 \
+  --name my-token-endpoint \
+  --billing-method token
+
+
+# 典型返回
+{
+  "Id": "ep-20260421180049-ngwkm"
+}
+
+# 只提取 Id，供后续命令复用
+endpoint_id=$(arkcli infer endpoint create \
+  --model doubao-seed-2-0-pro-260215 \
+  --name my-endpoint \
+  --transform Id)
+```
+
+## 返回值
+
+创建成功后返回新建 Endpoint 的 `Id`。例如：
+
+```json
+{
+  "Id": "ep-20260421180049-ngwkm"
+}
+```
+
+这个 `Id` 是后续操作的主入口。
+
+## 创建后的下一步
+
+### 1. 查看详情
+
+```bash
+arkcli infer endpoint get "$endpoint_id"
+```
+
+### 2. 管理生命周期
+
+```bash
+arkcli infer endpoint stop "$endpoint_id"
+arkcli infer endpoint start "$endpoint_id"
+```
+
+### 3. 生成调用示例
+
+`arkcli +code-example` 已迁到 OpenTOP，当前可用。按**基础模型名**生成示例（不接受 `--endpoint-id`）：
+
+```bash
+arkcli +code-example --model doubao-seed-2-0-pro --language python
+```
+
+详见 [`../../arkcli-code-example/SKILL.md`](../../arkcli-code-example/SKILL.md)。
+
+### 4. 不要再调用 `+deploy`
+
+如果你已经通过 `infer endpoint create` 拿到了 `Id`，说明 Endpoint 已经创建完成。
+
+此时不应该再执行：
+
+```bash
+arkcli +deploy ...
+```
+
+因为 `+deploy` 本身也是“创建 Endpoint”的工作流，它会创建新的资源，而不是复用刚创建出来的 `Id`。
+
+## 注意事项
+
+- `infer endpoint create` 偏向标准资源创建
+- `+deploy` 偏向”创建 Endpoint + 模型开通/复用检查/profile 同步”的任务工作流
+- 二者都会创建 Endpoint，不应串行重复执行
+- 语音模型（TTS / ASR / 配音 / 播客 / 音色 / 实时语音交互，或 `doubao-seed-tts-*` / `doubao-seed-asr-*` / `seedasr-*`）当前不能用本命令创建 Endpoint；只能通过 `arkcli models search <keyword>` 做广场发现和选型说明
+- `--billing-method` 目前只有 `token` 一个枚举值；传 `token` 时不会额外写入 CreateEndpoint 请求字段，只会在创建前校验对应模型是否支持 token 推理方式
+- 基础模型的支持方式来自 `ArkModels.data[].Features.ShareService`；自定义模型优先看可部署版本 `EndpointSupportedMethods.ShareService`，必要时兜底到 `AvailableDeploymentTypes=Shared`
+
+## 参考
+
+- [arkcli-infer-endpoint](../SKILL.md) -- infer endpoint 能力概览
+- [arkcli-infer-endpoint-get](arkcli-infer-endpoint-get.md) -- 查看 Endpoint 详情
+- [arkcli-infer-endpoint-start](arkcli-infer-endpoint-start.md) -- 启动 Endpoint
+- [arkcli-infer-endpoint-stop](arkcli-infer-endpoint-stop.md) -- 停止 Endpoint
+- [arkcli-code-example](../../arkcli-code-example/SKILL.md) -- 生成多语言调用示例（已迁到 OpenTOP，当前可用）

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-delete.md

@@ -0,0 +1,68 @@
+# arkcli infer endpoint delete
+
+Delete an infer endpoint (irreversible)
+
+## Usage
+
+```bash
+arkcli infer endpoint delete <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to delete | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit the local `DeleteEndpoint` Client Preview without reading or deleting the endpoint | No |
+| `--yes` | bool | Skip the interactive Y/N prompt (TTY only). **Non-interactive mode: this flag does NOT authorize deletion** — set `ARKCLI_ALLOW_HEADLESS_DELETE=1` instead. | No |
+| `-h`, `--help` | | help for delete | No |
+
+## 确认机制（高危，必读）
+
+删除是不可逆操作。`infer endpoint delete` 用**三分支确认门**：
+
+| 环境 | 行为 |
+|------|------|
+| 交互终端（TTY） | 弹强警告 + `[y/N]`，输入 `y` 才执行；`--yes` 跳过提问当确认 |
+| 非交互（agent / CI / 管道）+ `ARKCLI_ALLOW_HEADLESS_DELETE=1` | 打审计行后放行（给真·无人值守自动化） |
+| 非交互 + 未设 env | **hard-refuse**（`requires_headless_gate`）；`--yes` 在此被无视 |
+
+设计意图：任何 agent 都能反射地加 `--yes`，但 agent 的 stdin 不是真 TTY。所以「真 TTY 或显式 env」是 agent 造不出来的硬门槛，防止 agent 自批 `--yes` 替用户静默删除。对齐 `infer endpoint create` 开通的 `ARKCLI_ALLOW_HEADLESS_ACTIVATION` 模式。
+
+### Agent 调用须知
+
+agent（Claude Code / OpenCode 等）通过 skill 调用 `infer endpoint delete` 时是非交互环境：
+
+- **默认 hard-refuse**，即使带 `--yes` 也删不了。
+- 要在 agent / CI 中删除，必须显式设 env：
+
+  ```bash
+  ARKCLI_ALLOW_HEADLESS_DELETE=1 arkcli infer endpoint delete <id> --yes
+  ```
+
+- 交互式真人终端直接 `arkcli infer endpoint delete <id>`，按提示确认即可。
+
+`--dry-run` 只在客户端输出 `DeleteEndpoint` 请求计划，不调用 `GetEndpoint` 或
+`DeleteEndpoint`，也不进入确认门。预览只证明本地参数可构造，不证明 Endpoint
+存在、状态允许删除或服务端会受理。
+
+### 删除前建议
+
+删除前 endpoint 若为 `Running` 状态，部分场景需先 `stop` 再 `delete`；状态不允许时后端返回 `OperationDenied.EndpointStatus`，arkcli 翻译成「endpoint status does not allow this operation」并提示用 `infer endpoint get <id>` 检查状态。
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-get.md

@@ -0,0 +1,60 @@
+# arkcli infer endpoint get
+
+Get infer endpoint endpoint details
+
+## 调用异常：先取事实，再区分状态与可达性
+
+已知精确 ID 时直接 `get <endpoint-id>`，不用先全量 list。保留完整 ID，不能把 `ep-m-` 改成 `ep-`，也不能凭时间前缀补随机后缀。NotFound 按主 Skill 的当前列表 + 历史用量分支核对；当前不可见不等于已删除。
+
+1. 记录 `Status`、`StatusReason`、`ModelReference`、Project 与限流等实际返回字段；没有的字段标“未返回”，不补默认值。模型绑定有歧义时走 `resources resolve`，不能用 Custom Model 的基础模型 lineage 冒充实际绑定。
+2. 复用本轮身份、region、base URL 与请求时间上下文，保留错误码、RequestId 和脱敏报文。不要要求用户粘贴完整 Authorization / API Key，也不为了排障自动切 Profile、刷新/轮换 Key。
+3. `Running` 只证明控制面状态；`usage stats --endpoint <id> --start <日期> --end <日期>` 只证明该窗口的聚合用量，不提供单请求错误率或调用链。错误率/延迟诊断转 Doctor，近期无数据须说明聚合延迟。
+4. 用户已授权真实试调用时，才沿该模型支持的 API/模态做一次最小复现；文本对话使用 `+chat --model <endpoint-id>`，不是 `--endpoint`。需要图片/视频输入时保留原输入条件，不用纯文本探针证明多模态成功。未实测时明确写“数据面未验证”，不宣称一切正常。
+
+| 现象 | 需要核对的分支；不是仅凭错误码认定的根因 |
+|---|---|
+| 401 | 凭证类型、Bearer 格式、空白字符、有效期、身份匹配；仅展示脱敏信息，按宿主认证协议处理 |
+| 403 | 当前 Key 的资源范围、IAM 权限、region 与实际 Project；account-wide 不等于具备所有权限，也不能先认定 Project 隔离；不建议直接扩大到全部权限 |
+| 404 / NotFound | 原始 ID、版本、region、可见范围、base URL 与 API 路径；目录存在不证明该 Endpoint 可访问 |
+| 500 | API 与模型模态是否匹配、原请求参数、服务错误及 RequestId；不能把所有 vision 模型当 embedding，也不凭 500 断言是用户客户端或网络 |
+| ClosedEndpoint | `get` 核对状态；启动、重建是写操作，按用户意图与宿主授权执行，不为诊断自动修复 |
+
+OpenAI 兼容 SDK 通常自行拼 API 路径，base URL 不重复带 `/chat/completions`；Platform / Agent Plan / Coding Plan 路径不可混用。具体以执行上下文和客户端契约为准，不靠换路径碰运气。
+
+### 特惠区、保障包与删除的业务边界
+
+- `ClosedEndpoint` 或费用相关错误也可能与账号欠费有关：先核对 Endpoint 状态和错误原文，再引导用户在火山引擎控制台费用中心确认现金余额、欠费与恢复状态。`usage balance` 是套餐/资源额度，不是账户现金余额，Billing 账单也不能证明实时可用余额；本轮无法查到时明确交由费用中心核验，不直接认定已欠费或自动充值。
+- 从特惠区迁到保障包按新 Endpoint 迁移处理，不把更新名称/限流说成“原地升级保障包”。先确认目标计费产品和创建路径；新 EP 创建后单独验证数据面，再由用户确认切流与旧资源停用。
+- 旧 EP 的 `context_id` 不能直接复用于新 EP；重新建立目标上下文，不能复用旧缓存成功结果证明新链路可用。
+- 删除 Endpoint 不等于退订 TPM 保障包；包未退订可能继续计费。用户问扣费时转 Billing 核账与对应退订流程，不能承诺删 EP 即停止所有费用。
+- `OperationDenied.EndpointStatus` 时先 `get` 核对，必要的 stop/delete 仍分别受宿主写操作守卫约束。
+
+## Usage
+
+```bash
+arkcli infer endpoint get <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to get | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `-h`, `--help` | | help for get | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-list.md

@@ -0,0 +1,142 @@
+# arkcli infer endpoint list
+
+List infer endpoint endpoints
+
+## 全量盘点与导出
+
+- “我的”保留对应产品支持的本人范围；“账号所有在用”才按账号范围列 `--status Running --page-all --page-size 100`。不要因为本人范围空而自动改成全账号。
+- JSON 数组是 `Items`，不是 `items`。保存完整 stdout 后解析，stderr 单独保留；检查分页上限/告警和实际返回数量，不能把第一页或 `head` 截取结果当总清单。`--page-all` 可以与 `--page-size` 同用。
+- 交付 CSV/表格至少包含精确 ID、Name、实际绑定模型、Status、CreateTime、Description；用户要求 QPM/TPM 等列表未返回的详情时，才对已筛选的目标补 `get`。缺失字段与真实 0 分开表示。
+- 批量详情默认串行并遵守接口 QPS；需要并行时先确认限流，不照抄固定 8/10 并发。每个目标分别记录成功/失败，不将 `2>&1` 混入 JSON，不因部分失败输出“全量导出成功”。
+- 时间保留原始值，并明确展示时区；已带 offset 的时间只转换一次，不能再手动加八小时。汇总报告写明身份/范围、筛选条件、匹配数量、失败项及是否完整。
+- ID 与文件名分别处理：不要把外部返回值直接拼进 shell 代码或输出路径；解析完整结构化结果后，以引用参数传给 `get`。
+
+### 统计、逐个补详情与 CSV 模板
+
+下面假设用户已要求“账号所有在用 EP”；如要求“我的”，第一条必须保留 `--mine`，其余步骤不改变身份和范围。在允许脚本的宿主中执行；只允许单条 CLI 的宿主按相同步骤逐条调用工具。目录由 `mktemp` 创建，不覆盖已有交付。
+
+```bash
+ep_report_dir=$(mktemp -d)
+arkcli infer endpoint list --status Running --page-all --page-size 100 --page-delay 800 --format json > "$ep_report_dir/list.json" 2> "$ep_report_dir/list.stderr"
+# 仅在上述命令退出码为 0 后继续；先读 stderr 的分页告警。
+jq -e '(.Items | type == "array") and (.TotalCount | type == "number")' "$ep_report_dir/list.json"
+jq '{server_total: .TotalCount, captured: (.Items | length),
+     by_status: ([.Items[] | (.Status // "未返回")] | group_by(.) | map({(.[0]): length}) | add // {})}' "$ep_report_dir/list.json"
+```
+
+`captured` 与 `server_total` 不一致时先核对分页/服务端过滤及查询过程中资源变化；不能宣称完整。截断先读宿主保存的完整文件；确无完整捕获才同范围落盘补查一次。以下只对列表缺少所需详情的对象补查，已有完整详情时直接复用。不能把 RateLimit 缺失当成 0，也不能假定所有版本的 list 都不返回限流字段。
+
+```bash
+jq -er '.Items[] | select(.RateLimit.Rpm == null or .RateLimit.Tpm == null) | .Id | select(type == "string" and length > 0)' "$ep_report_dir/list.json" > "$ep_report_dir/detail-ids.txt"
+# 空待查集合正常（jq -e 此时可返回 4）；JSON 解析失败则停止，不执行循环。
+ep_seq=0
+while IFS= read -r ep_id; do
+  ep_seq=$((ep_seq + 1))
+  if arkcli infer endpoint get "$ep_id" --format json > "$ep_report_dir/$ep_seq.json" 2> "$ep_report_dir/$ep_seq.stderr"; then
+    jq -n --arg id "$ep_id" --arg file "$ep_seq.json" '{id:$id,ok:true,file:$file}'
+  else
+    jq -n --arg id "$ep_id" --arg file "$ep_seq.stderr" '{id:$id,ok:false,error_file:$file}'
+  fi
+  sleep 1
+done < "$ep_report_dir/detail-ids.txt" > "$ep_report_dir/details-manifest.jsonl"
+```
+
+每个成功响应先校验为对应 ID 的 Endpoint 对象，再按 `Id` 合并回列表；失败行保留并标注“详情未获取”，不得把错误对象或 stderr 合并进 `Items`。批量脚本的退出码不能代替逐项结果。
+
+生成展示字段时用标准时区转换，保留 UTC 原值；以下以 CN 用户的北京时间为例，其他用户使用其明确时区：
+
+```bash
+node - "$ep_report_dir/list.json" <<'JS' > "$ep_report_dir/display.json"
+const fs = require('node:fs');
+const data = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const fmt = new Intl.DateTimeFormat('sv-SE', {timeZone:'Asia/Shanghai',year:'numeric',month:'2-digit',day:'2-digit',hour:'2-digit',minute:'2-digit',second:'2-digit',hourCycle:'h23'});
+for (const item of data.Items) {
+  const time = Date.parse(item.CreateTime);
+  item.CreateTimeBeijing = Number.isFinite(time) ? fmt.format(new Date(time)) + ' +08:00' : '时间缺失或无效';
+}
+process.stdout.write(JSON.stringify(data));
+JS
+jq -r '
+  def binding:
+    if .EndpointModelType == "CustomModel" then .ModelReference.CustomModelId // "待解析"
+    elif .EndpointModelType == "FoundationModel" then
+      .ModelReference.FoundationModel as $m |
+      if ($m.Name // "") == "" then "待解析"
+      else [$m.Name, $m.ModelVersion | select(. != null and . != "")] | join("-") end
+    else "待 resources resolve 解析" end;
+  ["序号","EP-ID","Name","绑定模型","Status","CreateTime 原值","创建时间（北京时间）","RPM","TPM","Description"],
+  (.Items | to_entries[] | .key as $i | .value |
+   [$i+1,.Id,.Name,binding,.Status,.CreateTime,.CreateTimeBeijing,
+    (.RateLimit.Rpm // "未返回"),(.RateLimit.Tpm // "未返回"),(.Description // "")]) | @csv
+' "$ep_report_dir/display.json" > "$ep_report_dir/endpoints.csv"
+```
+
+当前字段叫 `Rpm` / `Tpm`，不是臆造的 `Qpm`；若用户称 QPM，说明对应请求/分钟口径。CustomModel 即便同时带 FoundationModel lineage 也只导出 `cm-*` 真实绑定。CSV 用 `@csv` 正确处理逗号、引号、换行；未知绑定单列待解析项，不能当成已完成。最终附文件路径、查询范围/条件、完整性、详情失败清单。
+
+## Usage
+
+```bash
+arkcli infer endpoint list [flags]
+```
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--format` | string | Output format: table \| json | No |
+| `--model` | string | Filter by model: a custom model ID (`cm-...`) or a foundation model name (`doubao-seedream-5-0-pro`, or the dotted DisplayName form `doubao-seedream-5.0-pro`) | No |
+| `--status` | string | Filter by endpoint status | No |
+| `--mine` | bool | 仅列出当前 SSO 子账号创建的接入点（服务端 `sys:ark:createdBy` Tag 过滤） | No |
+| `--page-number` | int | Page number (>=1) | No |
+| `--page-size` | int | Page size | No |
+| `-h`, `--help` | | help for list | No |
+
+## `--model` 语义
+
+`--model` 接受两类取值，由 CLI 分流：
+
+- `cm-` 前缀 → 按**自定义模型 ID** 过滤（`Filter.CustomModelIds`，大小写敏感）。
+- 其它 → 按**基础模型名**过滤：先归一化到 connector Name，再走
+  `Filter.FoundationModelNames`（服务端精确匹配）。
+
+归一化只做两件事，**不做机械字符替换**：先按 Name 全串匹配，再按 DisplayName
+大小写不敏感全串匹配。展示名与 Name 不总是同一变形 —— 例如模型
+`doubao-seedream-5-0` 的 DisplayName 是 `Doubao-Seedream-5.0-lite`（展示名带
+`lite`，connector Name 不带），所以把点号换成连字符会拼出一个不存在的名字。
+
+名字既不是 `cm-` ID、也匹配不上任何基础模型名时，命令**报错退出（非 0）**并给出
+提示，**不会**返回空表。不要因为拿到空结果就断言"这个账号没有该模型的接入点"。
+
+```bash
+arkcli infer endpoint list --model doubao-seedream-5-0-pro --page-all --page-size 100 --format json
+```
+
+## "我的接入点" 语义（覆盖 shared default）
+
+本命令**已内建 `--mine`**，按 [`../../arkcli-auth/references/identity-resolution.md`](../../arkcli-auth/references/identity-resolution.md) 的"决策顺序"必须**优先**走它，
+不要再退回 `whoami + jq` 客户端过滤。
+
+```bash
+arkcli infer endpoint list --mine --page-all --page-size 100 --page-delay 800 --format json
+```
+
+行为：
+
+- `--mine` 在 shortcut 层把当前 `cfg.UserID` / `cfg.UserName` 拼成 `IAMUser/<UserID>/<UserName>`，
+  作为 `TagFilters.{Key: "sys:ark:createdBy", Values: [...]}` 下发到 `ListEndpoints`。
+- 与 `--status` / `--model` / `--page-*` 可自由叠加（例如 `--mine --status Running`）。
+- 仅在 **SSO 子账号**登录态下可用。其它态会**直接报错**，不静默退化：
+  - 非 SSO（AK/SK / APIKey）：`--mine requires an SSO sub-user login`，运行 `arkcli auth login volc-sso` 重新建立 Volc 身份
+  - SSO root：`--mine is not supported for root logins`，引导改用 sub-user 登录
+  - SSO 但 UserID/UserName claim 缺失：引导重登刷新身份
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-start.md

@@ -0,0 +1,34 @@
+# arkcli infer endpoint start
+
+Start an infer endpoint endpoint
+
+## Usage
+
+```bash
+arkcli infer endpoint start <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to start | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit a local `StartEndpoint` Client Preview without calling the API | No |
+| `-h`, `--help` | | help for start | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-stop.md

@@ -0,0 +1,34 @@
+# arkcli infer endpoint stop
+
+Stop an infer endpoint endpoint
+
+## Usage
+
+```bash
+arkcli infer endpoint stop <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to stop | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit a local `StopEndpoint` Client Preview without calling the API | No |
+| `-h`, `--help` | | help for stop | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |