⚡

arkcli命令行对话（+chat）Skill arkcli-chat

本技能是 arkcli 命令行工具中 +chat 能力的使用指南：通过数据面 Responses API（POST /responses）发起大模型对话与推理。主要用途包括：纯文本问答；多模态输入（本地图片、视频、音频文件随请求上传）；流式输出去分推理与正式回答；用 --store 与 --previous-response-id 实现多轮会话接续；用 --instructions、--temperature、--top-p、--max-output-tokens、--reasoning-effort 调节指令与采样；用 --thinking、--caching 控制思考阶段与 prompt 缓存；用 --tools / --tools-file 接入联网检索与自定义 function 工具调用；用 --text-format json_schema --text-strict 做可校验的严格 JSON 结构化输出；用 --dry-run 做无副作用请求预演。同时给出决策规则：带文件且产出形态明确时改用 arkcli-understand，生成图片或视频时改用 arkcli-gen；并给出认证准入、模型与 Endpoint 资源解析、401/403/429 错误处理以及 Responses API capability/access 报错的只读排查流程。关键约束：一次用户请求只发起一次真实调用，失败必须如实报告，不得自动重试或替换响应。关键词：arkcli、+chat、Responses API、大模型对话、命令行对话、多模态、流式输出、多轮会话、store、previous-response-id、系统指令、temperature、reasoning-effort、thinking、prompt cache、工具调用、web_search、function calling、JSON Schema、严格 JSON、dry-run、Endpoint、API Key、arkcli-understand、arkcli-gen、模型能力排查。

AI应用 0 次安装 0 次浏览 更新于 11/11/2026
名称 arkcli-chat
版本 1.2.4
描述 “arkcli +chat：通过数据面 Responses API 实现快速对话与推理，支持多模态、流式、多轮、临时 API Key / Base URL / Endpoint 执行以及无副作用的 dry-run。当用户给出 Endpoint 但未说明工作流时，先用 resources resolve 识别候选项；当已经出现 Responses API capability/access 错误时，以只读方式用 models get 核对精确模型的 api_support，不重试真实调用。对于有明确产出形态的多模态理解任务，改用 arkcli-understand。” metadata: requires: bins: [“arkcli”] cliHelp: “arkcli +chat --help”

arkcli +chat

关键 — 开始前必须先使用 Read 工具读取 ../arkcli-shared/SKILL.md，其中包含认证前置检查、配置排查与命令选择顺序 关键 — +chat 在执行之前，务必先用 Read 工具读取 references/arkcli-chat.md，禁止在未读取该文档的情况下直接盲目调用命令。 关键 — 针对一次用户请求，只发起一次真实的 +chat 调用。如果首次响应不完整、严格 JSON 无效或不符合内容要求，必须保留并报告该次失败，不得自动重试，也不得用第二次响应替换；如果本地提取、保存或校验失败，只能修复本地交付内容。只有当用户明确要求进行新一轮调用或重新生成时，才再次调用。

核心概念

  • 当 --model 缺省时，CLI 会自动回退到当前 active profile 的 resources.text.default；如果用户显式传入不同的值，则按 ../arkcli-shared/references/profile-defaults.md 给出漂移提示。
  • +chat 是数据面 Responses API（POST /responses）的高层封装：一次请求即返回助手文本。
  • 支持多模态：使用 --input @photo.jpg 将本地文件随请求上传，模型可看图、看视频、听音频后回答。图片(.jpg/.png/.webp/...)、视频(.mp4/.mov/...)、音频(.mp3/.wav/.m4a/...)、通用文件按扩展名自动分流。
  • 支持流式：在 --stream 模式下逐段输出，先输出推理（thinking），再输出正式回答（response）。
  • 支持进度提示：非流式调用在 5s 后开始向 stderr 输出 arkcli +chat: still running… elapsed Xs 心跳行（每 10s 一次），避免长时间调用看不到任何输出；在脚本场景中可用 --no-progress 关闭该提示。stdout 不受影响。
  • 支持系统指令（system instructions）：--instructions "..." 用于注入系统级指令。
  • 支持采样调节：--temperature / --top-p / --max-output-tokens。
  • 支持思考强度：--reasoning-effort minimal|low|medium|high（仅在支持 reasoning 的模型上生效）。
  • 支持多轮接续：--store 持久化本次响应，下一次用 --previous-response-id <id> 接续。
  • 支持 Tools：--tools web_search（简单语法糖）或 --tools-file tools.json（function 等完整形态），配合 --tool-choice auto|required|none 与 --max-tool-calls。详见 references/tools.md。
  • 支持应答管理命令：arkcli chat get/delete/list-input-items <response-id> 可针对通过 --store 存储过的 response 执行查询、删除等操作，详见 references/chat-meta.md。
  • 支持缓存与思考：--caching enabled|disabled（配合 --cache-prefix）控制服务端 prompt 缓存；--thinking auto|enabled|disabled 控制思考阶段；--expire-at <epoch_sec> 为存储的 response 设置过期时间。详见 references/caching-thinking.md。
  • 支持流式事件：--stream --include-events 输出原始 SDK 事件 NDJSON（每行一个 JSON），供 autotest / agent 程序化消费。详见 references/stream-events.md。
  • 支持可验证的严格 JSON：--text-format json_schema --text-schema <file> --text-strict 不仅把约束传给服务端，还会在客户端确认响应是否完整、是否为直接 JSON 且符合 Schema；如果不符合，则以非零状态退出。严格流式模式会先缓冲，校验成功后才输出，避免输出不完整的 JSON。详见 references/text-format.md。
  • 输出 schema（务必先看）：+chat 的返回是 arkcli 扁平 schema（{id, model, content, reasoning_content, usage, ...}），不是 Responses API 原生的 output[].content[].text 嵌套结构；助手文本直接用 .content 取。--format 不会切换 shape。详见 references/arkcli-chat.md 的「返回值」段。
  • 当用户临时提供 --api-key / --base-url / Endpoint 时，必须读取 ../arkcli-shared/references/execution-context.md。不要根据 Key 文本来猜测套餐类型，也不要把临时值写入 profile。
  • --dry-run 只在本地构造 preview.v1 请求摘要和不含 secret 的执行上下文；不会读取在线元数据、刷新凭证、调用 Responses API、产生 token 用量或存储 response。在线依赖必须列为 unresolved。

快速决策

采用 +chat 的判断条件（三条全部满足）：

  1. 用户带图、视频或音频，但意图是开放对话、问答、推理、感想或评论（非固定产出形态）
  2. 不能映射到 arkcli-understand 12 个子技能之一
  3. 或者用户需要 --store / --previous-response-id 多轮接续

改用 arkcli-understand 的判断条件（满足任意一条即转）：

  • 用户要「转写/语音转文字/语音识别/ASR」→ understand
  • 用户要「字幕/打轴/SRT」→ understand
  • 用户要「多人对话/标说话人/会议转写」→ understand
  • 用户要「OCR/识别文字/识别图片文字/发票金额」→ understand
  • 用户要「框出来/标框/bbox/视觉定位」→ understand
  • 用户要「PDF 字段提取/文档提取/抽字段/合同提取」→ understand
  • 用户要「视频总结/分段/章节总结」→ understand
  • 用户要「视频问答/视频内容提问」→ understand

一句话：有 @file 且有明确产出形态 → understand；带图聊天、追问、开放感想 → chat。

Agent 快速执行顺序

首先把用户要求记录成可验收项：回答任务、指定模型/Profile、输入文件、输出格式、流式/多轮、明确的参数值与交付文件。如果只是预览请求，可以直接走本地 --dry-run，不要先联网查询认证或资源。

  1. 用户只给 ep-... 且任务不明确 → arkcli resources resolve <ep-id> --format json；只有在开放问答或追问场景下才选择 +chat。
  2. 用户提供了临时 Key/Base URL/Endpoint → 按共享 execution-context 组合规则决定参数，不要先切换 profile。
  3. 不确定认证状态且没有完整的 stateless 上下文时，先看 arkcli auth status；未登录或没有 API Key 时，改用 ../arkcli-auth/SKILL.md。
  4. 不确定模型名时，先改用 ../arkcli-models/SKILL.md。
  5. 使用本次资源确认的调用 ID，不要强制改成版本化名称。用户未指定模型时，保留当前 text default 或省略 --model；合法套餐别名（如 ark-code-latest）不追加版本。用 resources list --modality text 核对 default、invocable、required_overrides 与凭证类型；可见不等于可调用。能力查询的规范 Name/Version 与计费调用 ID 要分开，EP 始终保持 EP。只有未解析的模型族名才进一步查询，不要根据字符串猜测版本。
  6. 需要流式输出时加 --stream；需要多模态时加 --input @<file>（可多次）。
  7. 查模型实际支持的键、值和输入模态；不要把参数全集当成所有模型的能力。用户明确的 temperature、token 上限、thinking、store=false 等不得省略或换值；未指定时使用兼容默认，不额外开启联网、存储或工具执行。
  8. 发起真实请求前先确定交付路径；要求保存时按 reference 的单次捕获流程，让调用 stdout 直接进入临时响应文件。用首次真实返回验收：普通结果取 .content，严格 JSON 检查完整性/Schema；多轮必须引用真实上轮 ID 并保持相同调用上下文。流式保留 NDJSON，确认成功终态后提取正式正文，不能把推理文本或 Agent 自己的回答充当模型产出。保存文件必须与该次正文逐字一致；任何本地失败都不得触发第二次模型请求。

认证准入只陈述已验证的事实：本地登录、Key 清单状态为 Active 或资源可见，都不能单独证明当前数据面请求可用。如果实际调用报 401，核对当前 lane 凭证；对于 403/access 错误，按下文以只读方式核对能力和权限；对于 429，要区分限流与 quota exhausted。可以提醒可用候选，但不自动轮转 Key、切换 Profile 或收费路径，也不修改默认。stored response 不存在或过期时，要准确报告，不能悄悄去掉 previous-response-id 重新对话后声称上下文接续成功。

常见降级

  • 模型名不确定：先执行 models search。
  • endpoint ID 要用 +chat：直接传 --model ep-xxx（endpoint 本身已决定模态，无需额外 flag）。
  • Endpoint + 显式 API Key、未提供 Base URL：CLI 会读取 Endpoint region 后派生 Base URL；如果无法取得权威 region，再要求用户补充 --base-url。
  • 鉴权失败：改用 ../arkcli-auth/SKILL.md。

如何只读核对 Responses API capability 与 access 错误

当用户已经给出 model does not have access to responses api 这类错误时，本轮要做的是排障，而不是「再试一次」：

  1. 如果已知精确、完整的版本化模型 ID，只执行 arkcli models get <model-id> --format json；禁止用 models search 的候选摘要代替单模型详情。
  2. 在 api_support 数组中按 name / key / path 定位 Responses 项，以该项的 supported 作为模型声明事实；不要从模型名、lifecycle、tool 列表或其他 capability 反推。
  3. 如果 supported=true，但实际调用报 access 错误：说明「模型声明支持，但当前 Endpoint 或账号访问路径不可用」；如果用户还给了 Endpoint ID，可以再以只读方式执行 resources resolve / infer endpoint get 核对绑定与状态。
  4. 只有 supported=false 才能说模型目录声明不支持；如果 Responses 项缺失，则说明元数据不足，不做猜测。

全程禁止再次执行 +chat、自动 models activate、切换 profile 或修改默认资源。

命令一览

命令 说明
arkcli +chat --model <id> "<prompt>" 最简用法：纯文本对话
arkcli +chat --model <id> --stream "<prompt>" 流式输出（thinking + response 两段）
arkcli +chat --model <id> --instructions "你是简洁助手" "<prompt>" 系统级指令
arkcli +chat --model <id> --temperature 0.2 --max-output-tokens 256 "<prompt>" 采样调节
arkcli +chat --model <id> --reasoning-effort high "<prompt>" 提高思考强度
arkcli +chat --model <id> --input @file.jpg "<prompt>" 多模态（本地文件，支持图/视/音）
arkcli +chat --model <id> --input @a.jpg --input @b.jpg "<prompt>" 多文件
arkcli +chat --model <id> --store "<prompt>" 拿到 id 后再 --previous-response-id <id> "<下一句>" 持久化 + 多轮接续
arkcli +chat --model <id> --tools web_search --tool-choice auto "<prompt>" Tools：联网检索
arkcli +chat --model <id> --tools-file tools.json --tool-choice required "<prompt>" Tools：自定义 function
arkcli chat get <response-id> 取回 store 过的 response（含 function_calls）
arkcli chat list-input-items <response-id> --order desc --limit 5 列出输入项（多轮历史）
arkcli chat delete <response-id> 删除 store 过的 response
arkcli +chat --model <id> --caching enabled --store "<prompt>" 启用 prompt cache + 持久化
arkcli +chat --model <id> --thinking disabled --max-output-tokens 100 "<prompt>" 关思考压短输出
arkcli +chat --model <id> --text-format json_object "<prompt>" 强制模型出合法 JSON
arkcli +chat --model <id> --text-format json_schema --text-schema schema.json --text-strict "<prompt>" 用 JSON Schema 强约束 shape
arkcli +chat --model <id> --stream --include-events "<prompt>" 流式 NDJSON（每行一个 SDK 事件 JSON）
arkcli +chat --model <id> --dry-run "<prompt>" 无副作用预演；不调用 Responses API

详细文档

  • +chat 的所有参数、返回值、错误码、多模态文件自动上传机制等见 references/arkcli-chat.md。
  • +chat 的 Tools 能力（--tools / --tools-file / --tool-choice / --max-tool-calls，含 function 与 web_search）见 references/tools.md。
  • chat get / chat delete / chat list-input-items 三个应答管理命令见 references/chat-meta.md。这些命令操作的 response 必须是 +chat --store 过的。
  • +chat 的 --caching / --cache-prefix / --thinking / --expire-at 用法、回显字段与 autotest 对应见 references/caching-thinking.md。
  • +chat 的 --text-format / --text-schema / --text-schema-name / --text-strict 用法见 references/text-format.md。
  • +chat 的 --stream --include-events NDJSON 流式事件输出见 references/stream-events.md。