arkcli-chat
arkcli +chat:通过数据面 Responses API 快速对话/推理,支持多模态、流式、多轮、临时 API Key/Base URL/Endpoint 执行与无副作用 dry-run。当用户给出 Endpoint 但未说明工作流时,先用 resources resolve 识别候选;已经出现 Responses API capability/access 错误时,只读用 models get 核对精确模型的 api_support,不重试真实调用。有明确产出形态的多模态理解走 arkcli-understand。
arkcli +chat
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md,其中包含认证闸门、配置排查与命令选择顺序
CRITICAL — +chat 在执行之前,务必先用 Read 工具读取 references/arkcli-chat.md,禁止直接盲目调用命令。
CRITICAL — 一次用户要求的回答只发起一次真实 +chat。首次响应不完整、strict JSON 无效或不符合内容要求时,保留并报告该次失败,不自动重试或用第二次响应替换;本地提取、保存、校验失败也只能修复本地交付。只有用户明确要求新一轮或重新生成时才再次调用。
核心概念
--model缺省时 CLI 自动 fallback 到 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 做 CRUD,详见references/chat-meta.md。 - 支持缓存与思考:
--caching enabled|disabled(配--cache-prefix)控制服务端 prompt cache;--thinking auto|enabled|disabled控制思考阶段;--expire-at <epoch_sec>给 stored 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 时,MUST 读取../arkcli-shared/references/execution-context.md。不要从 Key 文本猜套餐类型,也不要把临时值写入 profile。 --dry-run只在本地构造preview.v1请求摘要与无 secret 的执行上下文;不会读取在线元数据、刷新凭证、调用 Responses API、产生 token 用量或存储 response。在线依赖必须列为unresolved。
快速决策
走 +chat 的场景:
- 纯文本问答、推理,或带图/视频/音频的开放式对话;不要求一定有附件。
- 接续已有 Responses 对话,使用
--store/--previous-response-id;单轮不要求开启存储。 - 若目标是下面列出的专项理解产出,优先转
arkcli-understand,不能仅因带附件就选择 chat。
用户要求关闭思考、比较延迟/缓存或交付 SDK 调用代码时,先读
references/caching-thinking.md;minimal 不等于关闭思考,
参数回显不等于缓存命中,也不能据此承诺固定的速度排序。
转 arkcli-understand 的判据(任一满足即转):
- 用户要「转写/语音转文字/语音识别/ASR」→ understand
- 用户要「字幕/打轴/SRT」→ understand
- 用户要「多人对话/标说话人/会议转写」→ understand
- 用户要「OCR/识别文字/识别图片文字/发票金额」→ understand
- 用户要「框出来/标框/bbox/视觉定位」→ understand
- 用户要「PDF 字段提取/文档提取/抽字段/合同提取」→ understand
- 用户要「视频总结/分段/章节总结」→ understand
- 用户要「视频问答/视频内容提问」→ understand
一句话:有 @file 且有明确产出形态 → understand;带图聊天/追问/开放感想 → chat。
- 用户要生成图片/视频(非对话):转
../arkcli-gen/SKILL.md。
Agent 快速执行顺序
先把用户要求记成可验收项:回答任务、指定模型/Profile、输入文件、输出格式、流式/多轮、
明确的参数值与交付文件。只预览请求时直接走本地 --dry-run,不先联网查认证或资源。
- 用户只给
ep-...且任务不明确 →arkcli resources resolve <ep-id> --format json;开放问答/追问才选择+chat。 - 用户给了临时 Key/Base URL/Endpoint → 按共享 execution-context 组合规则决定参数,不先切 profile。
- 不确定认证状态且没有完整 stateless 上下文时,先看
arkcli auth status;未登录/无 API Key 转../arkcli-auth/SKILL.md。 - 不确定模型名时,先转
../arkcli-models/SKILL.md。 - 使用本次资源确认的调用 ID,不强制改成版本化名称。用户未指定模型时保留当前 text default 或省略
--model;合法套餐别名(如ark-code-latest)不追加版本。用resources list --modality text核对 default、invocable、required_overrides与凭证类型;可见不等于可调用。能力查询的规范 Name/Version 与计费调用 ID 分开,EP 始终保持 EP。只有未解析的模型族名才进一步查询,不凭字符串猜版本。 - 需要流式输出时加
--stream;需要多模态时加--input @<file>(可多次)。 - 查模型实际支持的键、值和输入模态;不要把参数全集当成所有模型的能力。用户明确的 temperature、token 上限、thinking、store=false 等不得省略或换值;未指定时使用兼容默认,不额外开启联网、存储或工具执行。
- 发起真实请求前先确定交付路径;要求保存时按 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 类错误时,本轮是排障,不是「再试一次」:
- 若已知精确、完整的版本化模型 ID,只执行
arkcli models get <model-id> --format json;禁止用models search的候选摘要代替单模型详情。 - 在
api_support数组中按name/key/path定位 Responses 项,以该项的supported为模型声明事实;不从模型名、lifecycle、tool 列表或其他 capability 反推。 supported=true但实际调用报 access 错误:说明「模型声明支持,当前 Endpoint / 账号访问路径不可用」;若用户还给了 Endpoint ID,可再只读resources resolve/infer endpoint get核对绑定与状态。supported=false才能说模型目录声明不支持;Responses 项缺失则说明元数据不足,不做猜测。
全程禁止再次执行 +chat、自动 models activate、切 profile 或修改默认资源。
模型能力提示(stderr warn,不阻断)
+chat 真实执行时会在发请求前读一次 ArkModels 元数据,把模型差异以 warn: 前缀打到 stderr;请求照常发出。识别要点:
- 只警告、不阻断:出现
warn:行不代表请求失败。值为enabled/disabled、别名表、声明取值集都只是「模型声明」,服务端与 SDK 解码器才是裁决方。 - 不要把声明集当接受集。实测:
glm-5-2声明reasoning_effort为[none, minimal, high, max],但服务端拒绝none/minimal而接受low/medium(只出现在其mapping_config别名表里)。声明集与接受集可能近乎互补。 - 只按实际存在的元数据提示:缺少 reasoning 元数据时不得把其他 capability 当成 reasoning 声明;模型不在 ArkModels 中(如
kimi-k3)或查询失败时静默跳过,不产生任何 warn。 - 完整版本 ID 必须原样执行:可以用裸模型名查对应版本元数据,但不得把用户指定的旧版本自动改写成当前主版本。
- stderr 变化不影响 stdout 契约:
--format json的 stdout 结构不变,warn:行只进 stderr。需要稳定 JSON 时只解析 stdout,同时保留并检查 stderr,不得用2>/dev/null丢弃 warning。 --dry-run不读元数据:Client Preview 保持零网络,不会出现任何warn:行。
命令一览
| 命令 | 说明 |
|---|---|
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-eventsNDJSON 流式事件输出见references/stream-events.md。
- Downloads
- Security audit
- Pass
- Last updated
- 2d ago
- Current version
- v1.0.0
- License
- MIT-0
