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

package/skills/arkcli-chat/references/tools.md

@@ -0,0 +1,130 @@
+---
+name: tools
+description: arkcli +chat Tools 用法 reference, 含 web_search 简单语法糖、function 自定义工具的 JSON 文件协议、tool_choice / max_tool_calls 调节。
+---
+
+# +chat Tools
+
+PR-1 内置 `function` 与 `web_search` 两种 tool; `mcp` / `knowledge_search` 留 PR-5b。
+
+## 何时使用
+
+- 用户问"今天有什么 AI 新闻" → `web_search`
+- 用户提供函数 schema 让模型调 → `function`
+- 用户问"帮我查个会议纪要" / "用我们的知识库回答" → 当前 PR 不支持, 需提示用户走 `arkcli api arkruntime.create_responses --params '...'` (raw API) 或等 PR-5b。
+
+## 4 个新 flag
+
+| flag | 类型 | 用途 |
+|---|---|---|
+| `--tools <type>` | 可重复 string | 简单语法糖, 只支持单字段 `{"type":"<type>"}` 形态。当前实测能用的只有 `--tools web_search`。 |
+| `--tools-file <path>` | string | 读取一个 JSON 文件, 内容是一个 tool object 数组, 完整 SDK 形态; function 必须走这条路。 |
+| `--tool-choice <mode>` | string | 工具调用策略: `auto` / `required` / `none`。不传则使用服务端默认。 |
+| `--max-tool-calls <int>` | int | 单次会话最大 tool 调用次数, 防止失控。**仅对 built-in tools 生效**（如 `web_search`）；与 function tool（`--tools-file` 或 `--tools function:*`）组合时 arkcli 会在客户端就拦截，原因是服务端 `max_tool_calls only supported by build-in tools now`。 |
+
+`--tools` 与 `--tools-file` 可同时存在, 会按"sugar 在前, 文件在后"合并。
+
+## web_search (最简)
+
+```bash
+arkcli +chat "帮我查今天与AI相关的几条重要新闻, 给出要点和来源" \
+  --model ep-xxx \
+  --tools web_search \
+  --tool-choice auto \
+  --max-tool-calls 3
+```
+
+## function (需要 JSON 文件)
+
+`tools.json`:
+
+```json
+[
+  {
+    "type": "function",
+    "name": "query_weather",
+    "description": "查询某个城市的天气, 返回 JSON",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "city": {"type": "string", "description": "城市名, 如 Beijing"}
+      },
+      "required": ["city"]
+    }
+  }
+]
+```
+
+调用:
+
+```bash
+arkcli +chat "北京今天天气怎么样?" \
+  --model ep-xxx \
+  --tools-file tools.json \
+  --tool-choice required
+```
+
+`function` object 的字段 (与 SDK `responses.ToolFunction` 对齐):
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `type` | ✅ | 必须是 `"function"` |
+| `name` | ✅ | 函数名, 模型用它来识别 tool |
+| `description` | 推荐 | 给模型看的函数说明; 写得越清楚, 模型越能正确触发 |
+| `parameters` | 推荐 | JSON Schema 描述参数; 直接嵌套写, arkcli 会内部序列化成 SDK Bytes |
+| `strict` | 可选 bool | 严格模式: 强制参数符合 schema |
+
+## tool_choice 三种模式
+
+| mode | 含义 |
+|---|---|
+| `auto` | 服务端默认, 让模型自行决定要不要调 tool |
+| `required` | 强制必须至少调一次 tool |
+| `none` | 即使传了 tools 也禁止模型调用 |
+
+复杂的 function-specific tool_choice (`{"type":"function","name":"query_weather"}`) 在后续 PR 实现, 当前请用 `required` 加唯一一个 tool 等效达成。
+
+## 输出形态
+
+### 非流式 (`+chat ...` 不带 `--stream`)
+
+`ResponsesResult` 多了 `function_calls` 字段:
+
+```json
+{
+  "id": "resp_...",
+  "model": "...",
+  "content": "...",                  // 模型最终文本; tool 触发时可能为空
+  "reasoning_content": "...",
+  "usage": { ... },
+  "function_calls": [
+    {
+      "type": "function_tool_call",
+      "id": "call_...",
+      "name": "query_weather",
+      "arguments": "{\"city\":\"Beijing\"}",
+      ...
+    }
+  ]
+}
+```
+
+`function_calls[]` 是原始 SDK 形态透传; 不同 tool type 字段不同 (`function_tool_call` / `function_web_search` / 等), 用 `jq '.function_calls[].type'` 区分。
+
+### 流式 (`--stream`)
+
+stdout 上会出现 `[Tool args] {"city":"Beijing"}` 这样的标签行, 在 `Response:` 之前 / 之后插入, 取决于事件顺序。`ChatStreamDelta.FunctionCallArgs` 的所有 chunk 拼起来就是完整 args JSON。
+
+## 错误处理
+
+| 现象 | 原因 |
+|---|---|
+| `tool[N] type "X" not supported in this build` | 用了 PR-5b 才支持的 tool type (mcp/knowledge_search/image_process); 走 raw API 或等 PR-5b |
+| `function tool requires 'name'` | function 缺 name 字段 |
+| `unsupported tool_choice "X"` | tool_choice 不是 auto/required/none |
+| 模型回复但没触发 tool | tool description 写得不够清楚, 或 tool_choice=none, 或问题与 tool 不相关 |
+| 模型反复调用同一 tool | 加 `--max-tool-calls` 限制, 或在 tool description 里说明何时停止 |
+
+## 与 chat get 联动
+
+加了 `--store` 之后, 即使流式跑完, 后面也能用 `chat get <id>` 拿到完整 `function_calls` 列表; `chat list-input-items <id>` 还能看到完整的 tool 调用历史 (含 `function_tool_call_output` 这种结果项)。

package/skills/arkcli-code-example/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: arkcli-code-example
+version: 1.2.0
+description: "arkcli +code-example：为指定基础模型生成多语言（Python / Go / Java / Node / curl）调用示例代码并写入本地文件。数据源是火山方舟 OpenTOP OpenGetSampleCode。当用户需要拿某个基础模型的 SDK / curl 调用示例、保存为本地接入模板时使用。反触发：TTS/ASR/语音模型没有 arkcli 示例代码路径，不能靠补版本解决，只能转 models search 说明当前不支持。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli +code-example --help"
+---
+
+# arkcli +code-example
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+为指定基础模型生成多语言 SDK 调用示例代码，同时写入本地文件。数据源是火山方舟 OpenTOP `OpenGetSampleCode`。
+
+## 什么时候用
+
+- 用户说"生成示例代码 / SDK 示例 / curl 命令 / 怎么调用这个模型"，且已经知道模型名
+- 想把某个基础模型的多语言调用模板保存到本地
+- 教程或技术文档需要引用该基础模型的具体 SDK import、安装包、方法或请求格式：先取得对应版本示例并核对官方文档，不能从模型生成的草稿直接采信接口写法。
+
+## 教程中的代码事实核对
+
+以真实返回条目的 `install`、`language`、`io_type` 和 `code` 作为示例依据；明确目标模型/版本、语言及接口路径。更换 SDK 包或版本、图片/视频方法、响应字段、错误码时必须另核对该版本源码或官方文档正文；一个模型的文本示例不能证明所有媒体接口。服务端提供模板也不等于已在本轮执行成功，分别标明“官方示例/静态核对/实际运行”。检索片段或 AI 初稿不足时缩小教程到已查证内容，未验证片段标注或移除，不写成完整已验证接入指南。
+
+示例命令可能将当前 Key 填入文件；遵守共享身份/授权协议，提交教程前将 Key、Token 和签名 URL 等真实凭证替换为占位符并检查附件。不得直接回显未脱敏的生成条目，不为拿示例切换账号或绕过 Access 门禁。
+
+**反路由**（不要用本命令）：
+
+- 只是想试模型效果 → [`../arkcli-chat/SKILL.md`](../arkcli-chat/SKILL.md)（文本/多模态对话）或 [`../arkcli-gen/SKILL.md`](../arkcli-gen/SKILL.md)（出图/视频）
+- 还不知道模型名 → 先 [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md) `models search/get`
+- 需要先创建接入点 → [`../arkcli-deploy/SKILL.md`](../arkcli-deploy/SKILL.md)
+- 语音模型（TTS / ASR / 配音 / 朗读 / 播客 / 音色 / 实时语音交互，或 `doubao-seed-tts-*` / `doubao-seed-asr-*` / `seedasr-*`）→ 不使用 `+code-example`。`models search` 能搜到不代表 OpenGetSampleCode 有示例；不要把后端 `ModelVersion required` 理解成"补一个版本就能生成"，应说明当前 arkcli 不支持语音模型示例代码。
+
+## 快速开始
+
+```bash
+# 拿某基础模型的全部语言示例（写入 ./ark-examples/<model>/）
+arkcli +code-example --model doubao-seedream-5-0
+
+# 指定版本 + 只看 Python + 结构化输出
+arkcli +code-example --model doubao-seedream-5-0 --version 260128 --language python --format json
+```
+
+- `--model` 必填，可传基础模型名或合并 ID（`doubao-seedream-5-0-260128`）
+- `--version` 可选；不传时 CLI 自动推导（合并 ID 拆版本 → 找 `ArkModels` 匹配 → GetFoundationModel 取 `PrimaryVersion` 兜底），全都拿不到才报错要求显式传 `--version`
+- 内部机制：接口约束 `ModelVersion` 必填，缺失时 CLI 走上述回退链自动补齐；custom model 走 PrimaryVersion 兜底时 scenario 自动切 `finetune_inference`，foundation model 无论显式版本或 PrimaryVersion 兜底一律保持 `quick_access`
+- `--language` 可选：`python` / `go` / `java` / `node` / `curl`（`shell` 是 `curl` 别名），默认全部
+- `--output-dir` 可选，默认 `./ark-examples/<model>`
+- `--format json` 输出结构化条目（含 `language` / `io_type` / `install` / `code`）
+- 语音模型没有 arkcli 示例代码路径；命中 TTS / ASR / 语音交互时停在 `arkcli models search <keyword>` 的发现说明，不要继续调用本命令
+
+> **0.1.17 变更**：旧版 `--endpoint-id` 已移除——新数据源按基础模型取码，不再支持按已有接入点 ID 取码。如需指向某 endpoint，生成后把代码里的 `model="..."` 手动改成你的 `ep-xxx`。
+
+## 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `arkcli +code-example --model <name> [--version <ver>] [--language <lang>] [--output-dir <dir>] [--format json]` | 生成多语言示例代码并写入本地 |
+
+## 输出形态
+
+- **本地文件**：按"IO 任务类型"分子目录（对齐后端 `IOType` 维度），同类型下按语言分文件；带安装步骤的语言把安装命令写进文件头注释。
+- **结构化 JSON**：`--format json` 时给出按 `(语言 × IO 类型)` 展开的条目。
+- **人类可读**：默认按后端顺序打印各代码块。
+
+详细参数、目录结构示例、常见链路与 FAQ 见 [`references/arkcli-code-example.md`](references/arkcli-code-example.md)。
+
+## 参考
+
+- [references/arkcli-code-example.md](references/arkcli-code-example.md) — 完整命令手册
+- [arkcli-models](../arkcli-models/SKILL.md) / [arkcli-deploy](../arkcli-deploy/SKILL.md) / [arkcli-infer-endpoint](../arkcli-infer-endpoint/SKILL.md) / [arkcli-shared](../arkcli-shared/SKILL.md)

package/skills/arkcli-code-example/assets/demo-code/examples.json

@@ -0,0 +1,14 @@
+[
+  {
+    "language": "python",
+    "task_type": "chat",
+    "auth_method": "apiKey",
+    "file_path": "python.py"
+  },
+  {
+    "language": "go",
+    "task_type": "chat",
+    "auth_method": "apiKey",
+    "file_path": "go/main.go"
+  }
+]

package/skills/arkcli-code-example/assets/demo-code/go/main.go

@@ -0,0 +1,53 @@
+// Install: go get github.com/volcengine/volcengine-go-sdk@latest
+//
+// 模板说明:
+// - model 使用带版本号的合并 ID (模型名-PrimaryVersion);
+//   用 `arkcli models get <name> --format json` 查 PrimaryVersion 后拼合
+// - $ARK_API_KEY 运行前由环境变量提供, 不要把真实 Key 写进文件
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	"github.com/volcengine/volcengine-go-sdk/service/arkruntime"
+	"github.com/volcengine/volcengine-go-sdk/service/arkruntime/model/responses"
+)
+
+func main() {
+	client := arkruntime.NewClientWithApiKey(
+		// 通过 os.Getenv 从环境变量中获取 ARK_API_KEY
+		os.Getenv("ARK_API_KEY"),
+		arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"),
+	)
+	ctx := context.Background()
+
+	resp, err := client.CreateResponses(ctx, &responses.ResponsesRequest{
+		Model: "doubao-seed-2-0-pro-260215",
+		Input: &responses.ResponsesInput{
+			Union: &responses.ResponsesInput_ListValue{
+				ListValue: &responses.InputItemList{ListValue: []*responses.InputItem{{
+					Union: &responses.InputItem_InputMessage{
+						InputMessage: &responses.ItemInputMessage{
+							Role: responses.MessageRole_user,
+							Content: []*responses.ContentItem{{
+								Union: &responses.ContentItem_Text{
+									Text: &responses.ContentItemText{
+										Type: responses.ContentItemType_input_text,
+										Text: "Hello!",
+									},
+								},
+							}},
+						},
+					},
+				}}},
+			},
+		},
+	})
+	if err != nil {
+		fmt.Printf("response error: %v\n", err)
+		return
+	}
+	fmt.Println(resp)
+}

package/skills/arkcli-code-example/assets/demo-code/python.py

@@ -0,0 +1,26 @@
+# Install: pip install openai
+#
+# 模板说明:
+# - model 使用带版本号的合并 ID (模型名-PrimaryVersion);
+#   用 `arkcli models get <name> --format json` 查 PrimaryVersion 后拼合
+# - $ARK_API_KEY 运行前由环境变量提供, 不要把真实 Key 写进文件
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.getenv("ARK_API_KEY", "$ARK_API_KEY"),
+    base_url="https://ark.cn-beijing.volces.com/api/v3",
+)
+
+# 非流式对话
+chat_completion = client.chat.completions.create(
+    model="doubao-seed-2-0-pro-260215",
+    messages=[
+        {"role": "system", "content": "你是人工智能助手"},
+        {"role": "user", "content": "Hello!"},
+    ],
+    stream=False,
+)
+
+print(chat_completion.choices[0].message.content)

package/skills/arkcli-code-example/references/arkcli-code-example.md

@@ -0,0 +1,146 @@
+# +code-example
+
+> **前置条件：** 先阅读 [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+为指定基础模型生成多语言 SDK 调用示例代码，同时写入本地文件。
+
+数据源是火山方舟 OpenTOP `OpenGetSampleCode`：按 `(model, version)` + `scenario` 拉取一批"代码块"，arkcli 自动按 `(语言 × IO 任务类型)` 去重、配好安装命令后渲染落盘。
+
+## 什么时候用
+
+- 已经明确模型名（或合并 ID），想直接拿多语言调用代码
+- 想把示例保存到本地目录，作为后续接入模板
+
+不要在这些场景使用本命令：
+
+- 只是想快速试模型效果：转 `arkcli +chat` 或 `arkcli +gen`
+- 还不知道模型名：先 `arkcli models search/get`
+- 需要先创建 Endpoint：先 `arkcli +deploy` 或 `arkcli infer endpoint create`
+- 目标是语音模型（TTS / ASR / 配音 / 朗读 / 播客 / 音色 / 实时语音交互，或 `doubao-seed-tts-*` / `doubao-seed-asr-*` / `seedasr-*`）：只允许 `arkcli models search <keyword>` 做广场发现；当前 arkcli 不支持语音模型示例代码，不能通过补 `--version` 解决
+
+## 用法
+
+```bash
+# 基础用法（传基础模型名）
+arkcli +code-example --model doubao-seedream-5-0
+
+# 指定模型版本（两种写法等价）
+arkcli +code-example --model doubao-seedream-5-0 --version 260128
+arkcli +code-example --model doubao-seedream-5-0-260128
+
+# 只看 Python 示例
+arkcli +code-example --model doubao-seedream-5-0 --language python
+
+# 只看 curl 示例（shell 是别名，等价）
+arkcli +code-example --model doubao-seedream-5-0 --language curl
+
+# 指定输出目录
+arkcli +code-example --model doubao-seedream-5-0 --output-dir ./my-examples
+
+# 需要结构化结果时，显式要求 JSON
+arkcli +code-example --model doubao-seedream-5-0 --format json
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `--model` | string | ✓ | 基础模型名（`doubao-seedream-5-0`）或合并 ID（`doubao-seedream-5-0-260128`） |
+| `--version` | string | | 模型版本，如 `260128`；不传时 CLI 自动推导 —— 合并 ID 拆版本 → `ArkModels` 匹配 → `GetFoundationModel` 取 `PrimaryVersion` 兜底；三条链路都拿不到才报错要求显式传 `--version` |
+| `--language` | string | | 语言过滤：`python` / `go` / `java` / `node` / `curl`（`shell` 是 `curl` 的别名），默认全部输出 |
+| `--output-dir` | string | | 本地输出目录，默认 `./ark-examples/<model>` |
+| `--format json` | flag | | 输出结构化结果，适合 Agent 或脚本继续消费 |
+
+> **版本推导契约**：`OpenGetSampleCode` 接口要求 `ModelVersion` 必填。CLI 通过上述回退链自动补齐；custom model 走 `PrimaryVersion` 兜底时 `scenario` 自动切成 `finetune_inference`（fine-tune 推理示例模板），foundation model 无论是显式版本、合并 ID 拆分还是 `PrimaryVersion` 兜底，一律保持 `quick_access`。
+
+> **0.1.17 变更**：旧版的 `--endpoint-id` 已移除 —— 新数据源 `OpenGetSampleCode` 按基础模型取码，不再支持按已有接入点 ID 取码。如需把代码指向某个 endpoint，自行把生成代码里的 `model="..."` 改成你的 `ep-xxx` 即可。
+
+## 推荐执行顺序
+
+1. 不确定认证状态时，先执行 `arkcli auth status`
+2. 不确定模型名或版本时，先执行 `arkcli models search/get`
+3. 需要结构化解析时，追加 `--format json`
+4. 需要控制本地写入位置时，追加 `--output-dir`
+
+## 输出
+
+1. **本地文件**：写入 `--output-dir` 目录；未显式指定时，默认写到 `./ark-examples/<model>/`。文件按"IO 任务类型"分子目录（对齐后端返回的 `IOType` 维度），同类型下再按语言分文件。例如图像模型：
+
+```text
+ark-examples/<model>/
+├── text_to_image_generate_single_image/
+│   ├── python.py
+│   ├── go/main.go
+│   ├── java/Main.java
+│   ├── node.ts
+│   └── curl.sh
+├── image_to_image_single_image_to_single_image/
+│   └── ...
+└── ...
+```
+
+文本/对话类模型的子目录名会是对应的对话类 IO 类型。带安装步骤的语言（如 Python 的 `volcengine-python-sdk[ark]`、Go 的 `go get ...`），安装命令会作为文件头注释一并写入。
+
+2. **结构化结果**：追加 `--format json` 后，得到按 `(语言 × IO 类型)` 展开的结构化条目（含 `language` / `io_type` / `call_method` / `install` / `code` 等字段），适合后续流程解析。
+
+3. **人类可读代码块**：默认按后端给定顺序打印各示例代码块，便于直接复制。
+
+## 常见链路
+
+### 1. 先查模型，再生成示例
+
+```bash
+arkcli models search doubao-seedream
+arkcli +code-example --model doubao-seedream-5-0
+```
+
+### 2. 只要某一种语言，并让下游脚本消费 JSON
+
+```bash
+arkcli +code-example \
+  --model doubao-seedream-5-0 \
+  --language python \
+  --format json
+```
+
+## 注意事项
+
+- 代码中的 `$ARK_API_KEY` 会自动替换为当前已解析上下文的 API Key；身份摘要用 `arkcli auth whoami --format json`。不要为普通准入调用 `profile show/list/keys list`，这些命令可能同步并回写 Key
+- 需要先通过 `arkcli auth` 登录才能调用接口
+- 模型名称可通过 `arkcli models search <keyword>` 查找
+- 本命令会写入本地文件；如果不希望写到当前目录，请显式指定 `--output-dir`
+- 示例只覆盖 API Key 鉴权方式（`Authorization: Bearer $ARK_API_KEY`）
+- 语音模型广场可搜不等于有示例代码；遇到 `ModelVersion required` 或 no group 之类响应时，不要引导用户为 TTS / ASR 猜版本号，应说明当前不支持
+
+## 内置模板资产
+
+`assets/demo-code/` 内置了一组可直接运行的模板样例（随 Skill 一起分发给 Agent）：
+
+| 文件 | 语言 | 说明 |
+|------|------|------|
+| `python.py` | Python | OpenAI 兼容 `chat.completions`（`openai` SDK） |
+| `go/main.go` | Go | Responses API（`volcengine-go-sdk` arkruntime） |
+
+约定：
+
+- 模板统一使用**带版本号的合并 ID**（如 `doubao-seed-2-0-pro-260215` = 模型名 + PrimaryVersion）；版本号用 `arkcli models get <name> --format json` 查询 `PrimaryVersion` 后拼合，不要把裸家族名当可运行 model
+- API Key 一律用 `$ARK_API_KEY` 环境变量占位，不要把真实 Key 写进模板或生成结果
+- `ark-examples/` 只是 `+code-example` / `+deploy` 的**本地输出目录**（已在 `.gitignore` 中），不是模板存放位置，不要把里面的产物提交进仓库
+
+## 常见问题
+
+| 现象 | 常见原因 | 处理方式 |
+|------|----------|----------|
+| 鉴权失败 / 未登录 | 本地没有可用凭证 | 先执行 `arkcli auth status`，必要时转 `arkcli auth login` |
+| 不知道该填哪个模型名 | 只有模糊关键词，没有确定模型 ID | 先执行 `arkcli models search <keyword>` |
+| 想让代码指向现有 endpoint | `--endpoint-id` 已移除 | 生成后把代码里的 `model="..."` 手动改成你的 `ep-xxx` |
+| 下游脚本难以解析输出 | 直接消费了默认的人类可读输出 | 追加 `--format json` |
+| TTS / ASR 模型生成示例失败 | 语音模型当前不在 arkcli 示例代码支持范围内 | 停在 `models search` 的可发现说明，不要继续补版本或改走 `+chat` / `+gen` / `+deploy` |
+
+## 参考
+
+- [arkcli-code-example](../SKILL.md) — skill 概览
+- [arkcli-models](../../arkcli-models/SKILL.md) — 查模型名与版本
+- [arkcli-deploy](../../arkcli-deploy/SKILL.md) — 创建 Endpoint 并进入正式接入
+- [arkcli-infer-endpoint](../../arkcli-infer-endpoint/SKILL.md) — 创建或管理已有 Endpoint
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — 认证和全局参数

package/skills/arkcli-code-example/references/evals.md

@@ -0,0 +1,12 @@
+# 技术教程事实回归
+
+真实退步 Case 为 Viking 300/V10 的 163542：MD 已真实生成并提交，但其中多个 SDK import、媒体 API 和错误码写法缺少对应版本证据。失败不是“没有文件”。
+
+| 输入/对照 | 验收 |
+| --- | --- |
+| 需要文本、图像、视频教程；仅查到一份文本示例 | 不用文本示例或模型草稿编出其他 SDK 方法；逐协议核对官方正文/版本源码，否则标注未验证或缩小内容 |
+| 拿到 install/code，但没实际运行 | 保留语言、模型和版本，称官方模板而非实测通过；不将保存 MD 称作代码运行成功 |
+| 样例中含合成 Key/Token/签名 URL | 附件及答复均为占位符，保留普通示例语义；不把真实凭证写入教程 |
+| 原 CLI 不支持拟议 flag、音频示例接口不在当前能力中 | 保留实际 help/能力边界，不伪造命令补齐教程 |
+
+不把本页的正确代码或模型选择注入线上原题。先以真实 CLI/返回样例校准，再验收实际答复和附件内容。

package/skills/arkcli-config/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: arkcli-config
+version: 1.2.1
+description: "arkcli 本地配置管理。处理 profile 配置归因、update.mode 的 automatic/disabled 策略、config reset 与历史 yaml 排障；profile 类操作优先使用 `arkcli profile <subcmd>`。"
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli config --help"
+---
+
+# arkcli config
+
+**⚠️ 0.1.16 起命令树迁移**：`arkcli config init/list/show/switch/delete` 已标记 deprecated，请改用 `arkcli profile create/list/show/use/delete`（行为一致 + 新增 profile 切面字段 type/project/owner_trn/available_api_keys）。`arkcli config reset` 保留（清整个本地状态，超出单 profile）。0.2.x 删除全部已 deprecated 子命令。
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md)，其中包含认证闸门、命令选择顺序与共享安全规则**
+**CRITICAL — 配置类写操作前必须确认用户意图。`profile show/list/keys list` 可能同步远端 Key 并回写本地库存或默认 Key，不能当作无配置副作用的准入探测。**
+
+## 唤起信号（When To Trigger）
+
+- 用户提到：`profile`、`base-url`、`api-key` 覆盖混乱，或仍在使用已删除的全局 `--region/--project-name`
+- 用户现象：同一条业务命令“打到了错误环境/错误 base URL/错误账号”，怀疑是配置来源不一致
+- 用户目标：初始化/更新 profile、切换默认 profile、重置本地配置文件
+- 用户目标：启用、关闭或恢复 arkcli 的自动更新/更新提示策略
+
+## 反唤起信号（When NOT To Trigger）
+
+- 用户要解决的是“未登录/401/鉴权失败/没有权限”：先走 `arkcli auth status`，必要时转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md)
+- 用户目标是业务功能（models/+chat/+gen/+deploy/usage 等）：不要停留在 config，排除配置后回到原任务
+
+## 适用场景
+
+- 初始化或更新 profile
+- 查看当前解析后的配置
+- 切换默认 profile
+- 删除单个 profile 或重置整个本地配置
+- 排查为什么业务命令连到了错误环境、错误账号或错误 base URL
+
+## Agent 快速执行顺序
+
+1. 先遵守 shared 的认证及宿主边界。普通 CLI 的当前身份/Profile 诊断用 `arkcli auth status --format json`、`arkcli auth whoami --format json`；宿主禁止额外认证探测时，使用宿主已给的上下文，不自行探测。
+2. Chat/Gen 的默认模型和路由用 `arkcli resources list --modality <text|image|video> --format json`，按 Resources Skill 区分发现、兼容性和真实调用验证。仅查看默认模型不等于授权发送收费请求。
+3. 切换默认 profile：`arkcli profile use <name>`
+4. 创建 profile：`arkcli profile create --type=...`（详见 arkcli-profile 子树，本 skill 不重复）
+5. `arkcli config reset` 是破坏性操作（清整个本地配置文件），必须确认用户意图
+6. 更新策略只使用 allowlist 命令：`arkcli config set update.mode automatic|disabled`
+7. 用户明确需要 Profile 详情、清单或 Key 管理时才考虑 `arkcli profile show` / `arkcli profile list`；执行前说明可能同步并回写 Key。用户要求“不改配置/Key”时不执行它们，也不改用旧 `config show/list` 绕过限制。
+
+## 配置归因（优先级）
+
+`arkcli` 的解析优先级（从高到低）：
+
+- Profile 选择: `--profile` flag > `ARK_PROFILE` 环境变量 > `config.yaml` 的 `default_profile` > 第一个 `type=platform` 的 profile > `"default"` sentinel
+- API Key: `--api-key` > `ARK_API_KEY` > profile > 同 identity store > 产品 `.env` 兼容值
+- Base URL: `--base-url` > `ARK_BASE_URL` > profile 自定义值 > 按 Profile 的 Region/Type 派生 > 默认值
+- Region/Project: 由所选 Profile 持有；`ARK_REGION` / `ARK_PROJECT_NAME` 不再覆盖运行时
+
+`--api-key/--base-url` 仅供数据面命令使用。无 Profile 时必须成对提供；覆盖 Base URL 时也必须显式提供 API Key。控制面/本地命令显式收到这两个 flag 会 fail-fast。
+
+排障时要明确”是谁覆盖了谁”，不要直接猜测。
+
+> **0.1.16 修正**：`--profile` 现在优先于 `ARK_PROFILE`（对齐 CLI 行业惯例 flag > env > config）。0.1.15 及更早版本是 env > flag，与本规则相反。
+
+### 证据与结论
+
+说明本轮实际检查了什么、哪些来源覆盖仍未验证，不要求复述固定评测词句。`auth whoami` 的 Profile 字段是持久切面摘要，不能据此声称临时 API Key/Base URL override 已验证或数据面调用一定成功。缺少证据时明确保留未知，不为补字段执行可能回写配置的命令。路径展示使用 `$HOME/...`，不读取凭证文件。
+
+## 核心规则
+
+- 本 skill 负责解释“为什么命令打到了错误环境/错误账号/错误 base URL”，并兼容历史 `config init/list/show/switch/delete` 命令排障语义
+- 常规准入沿 `auth status/whoami` → `resources`，不把 Profile 管理命令当无副作用查询
+- profile 写操作（create / use / set-default / delete）走 `arkcli profile` 子树
+- `arkcli config reset` 负责全量清理；`arkcli config set update.mode <mode>` 只写更新策略。不要用它写任意 YAML 路径。
+
+## Guard Checklist（必做）
+
+- 只读意图：不执行可能回写 Key 的 `profile show/list/keys list`；脱敏不等于无副作用，命令名为 show/list 也不等于只读
+- 写操作确认：`profile use/delete` 与 `config reset` 执行前必须复述影响范围并征得确认
+- 全量清理提醒：`arkcli config reset` 删除 `config.yaml/config.json`，不会清理 `$HOME/.arkcli/.env`（token）或 identity store；要清理凭证请用 `arkcli auth logout`
+
+## 与其他 skill 的串联
+
+- profile 创建 / 切换 / 资源 default 设置 / API Key 管理 → 转 `arkcli-profile`（推荐）或继续看本 skill 的兼容映射
+- 业务命令失败且怀疑是 `--profile`、`--base-url`、API Key 来源或 Profile 的 Region/Project 不一致时，先转到这里
+- 配置问题排除后，再回到原始业务 skill 继续
+- 配置仍无法解释问题时，再考虑转 [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md) 或 [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md)
+
+## 命令一览
+
+| 命令 | 说明 | 状态 |
+|------|------|------|
+| `arkcli config reset` | 删除整个本地配置文件（保留） | ✅ 活跃 |
+| `arkcli config set update.mode automatic` | 显式为当前 exact install 启用 automatic；从非 latest 版本恢复时先安装 latest 再执行 | ✅ 活跃 |
+| `arkcli config set update.mode disabled` | 关闭静默自动安装，保留隐式版本检查、更新提示和手工 update | ✅ 活跃 |
+| `arkcli profile show [--profile <name>]` | 查看 Profile；可能同步并回写 Key | ✅ Profile 管理，替代 `config show` |
+| `arkcli profile list` | 列出 Profile；可能同步并回写各 Profile 的 Key | ✅ Profile 管理，替代 `config list` |
+| `arkcli profile use <name>` | 切换默认 profile | ✅ 替代 `config switch` |
+| `arkcli profile delete <name>` | 删除单个 profile | ✅ 替代 `config delete` |
+| `arkcli profile create --type=...` | 创建 profile（替代旧 `config init`） | ✅ 替代 `config init` |
+| `arkcli config init/list/show/switch/delete` | 旧子命令，0.2.x 移除 | ⚠️ deprecated |
+
+公开模式只有 `automatic` 和 `disabled`。`disabled` 保留隐式版本检查和更新提示，但绝不静默安装；显式 `arkcli update` 和 `arkcli update --check` 也始终可用。缺失 `update.mode` 和历史配置中的 `notify` 对外都按 `disabled` 处理，历史配置中的 `notify` 继续按 `disabled` 兼容读取，但不得再建议用户设置 `notify`。
+
+Windows、macOS、Linux 的 fail-closed transaction 与六个产品/平台生产 gate 均已开启。stable 全局 npm postinstall 会将安装后版本与 registry 当前 `latest` 比较：非 latest 持久化 `disabled`；当前 latest 不改 mode，已有 `automatic` 时为新 exact install 换发授权。postinstall 不立即执行版本替换。
+
+### 新安装 enrollment
+
+只有能证明“此前没有产品状态目录”且安装版本等于 registry `latest` 的 stable 全局 npm 新安装，才默认写入 `automatic` 并创建绑定当前 exact install 的惰性 pending evidence：
+
+1. 第一次成功的、符合安全条件的人工业务命令在一个策略事务中完成 pending → grace → active。
+2. 重新检查确认 exact-install consent 已 active 后，该 invocation 即可调度 automatic patch 更新。
+
+由 npm `postinstall` 启动的全部 CLI 进程（包括其中的 `+connect`）以及用户手工执行的 `+connect` 都不消耗 enrollment、不做隐式版本检查，也不调度 automatic。AI Skill、CI、非 TTY、Client Preview、`config`、`update` 和内部维护命令同样不消耗 enrollment，也不调度 automatic。更新成功后，下一次成功的人工业务命令只在 stderr 显示一次 `旧版本 -> 新版本` 结果，不修改 stdout 或业务退出码。
+
+当前生产 automatic 按明确产品策略关闭 24/48/72 小时与 10%/50%/100% cohort admission；原 rollout 实现与回归测试仍保留，在线 Probe 仍要求两次独立观测。普通 automatic 仍须满足 exact consent、实时 registry target/SRI/tarball 校验、reservation、退避和全部 staged-apply 安全边界。
+
+每次 npm 重装都不得沿用旧 exact-install receipt。若安装版本等于当前 `latest`，不改既有 mode：`automatic` 换发新 receipt，`disabled` / 历史 `notify` 仍保持关闭。若安装版本不等于 `latest`，持久化 `disabled`。registry 失败时不改 mode、不发新 receipt；`--ignore-scripts` 也不会完成对齐。从非 latest 版本恢复时，先安装 latest，再明确执行 `arkcli config set update.mode automatic`。长期锁定版本使用：
+
+```bash
+arkcli config set update.mode disabled
+npm i @volcengine/ark-cli@<exact-version> -g --registry https://registry.npmjs.org
+```
+
+为避免 registry 不可用时的不确定，需要确定锁版时仍建议先执行 `arkcli config set update.mode disabled` 再安装精确版本。`disabled` 位于 `$HOME/.arkcli/config.yaml`，安装 `@latest` 也不会自动改回 `automatic`。`arkcli config reset` 会尽力撤销 exact consent 后再清配置。npm 解析 `@latest` 与 postinstall 查询之间恰好发新版时，存在极小概率误判为非 latest 的竞态。
+
+## 参考
+
+- [`references/arkcli-config-init.md`](references/arkcli-config-init.md)
+- [`references/arkcli-config-profile.md`](references/arkcli-config-profile.md)
+- [`references/evals.md`](references/evals.md)

package/skills/arkcli-config/references/arkcli-config-init.md

@@ -0,0 +1,49 @@
+# config init
+
+## 创建或更新 profile
+
+```bash
+arkcli config init \
+  --profile default \
+  --tenant volc \
+  --api-key <ark_api_key> \
+  --base-url https://ark.cn-beijing.volces.com/api/v3 \
+  --region cn-beijing \
+  --default-model doubao-seed-1-6 \
+  --format json
+```
+
+可选控制面凭证：
+
+```bash
+arkcli config init --profile default --access-key <ak> --secret-key <sk> --format json
+```
+
+## 关键字段
+
+- `--profile`
+- `--tenant`（`volc`，决定控制面路由与身份体系）
+- `--api-key`
+- `--base-url`
+- `--region`
+- `--env`（全局 flag，非 `config init` 专属；`prod` / `stg` 仅火山有意义）
+- `--default-model`
+- `--set-default`
+
+## Profile schema v1 (0.1.16+) 改动
+
+- **Project Name 在 0.1.16 起进 profile 切面**：`arkcli profile create --project X` 会把 `Project: X` 写入 `config.yaml` 当前 profile。
+- 根命令已删除 `--project-name`，`ARK_PROJECT_NAME` 也不再覆盖运行时。解析顺序为 active profile `Project` > identity store / 火山 `.env` 旧状态兼容 > `default`。
+- Region 同样由 Profile 持有；根命令已删除 `--region`，`ARK_REGION` 不再覆盖运行时。
+
+## 推荐迁移到 `arkcli profile create`
+
+`config init` 已 deprecated，新代码请用 `arkcli profile create`：
+
+```bash
+arkcli profile create --type platform --region cn-beijing --project default --set-default
+arkcli profile create --type agent-plan --plan-tier medium --set-default
+arkcli profile create --type coding-plan --plan-tier lite --set-default
+```
+
+`profile create` 强制要求显式 `--type`，对应"platform / agent-plan / coding-plan" 三档；其余字段（region / project / owner-trn / default-api-key / plan-tier）跟旧 `config init` 语义一致。