SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsarkcli-chat

arkcli-chat

Agents & models

View repository

Updated 10-16 04:56

About this skill

arkcli +chat

CRITICAL — Before starting, you MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, configuration troubleshooting, and command selection order CRITICAL — +chat Before executing, be sure to first use the Read tool to read references/arkcli-chat.md, and do not directly call commands blindly. CRITICAL — For a single user-requested answer, initiate only one real +chat. If the first response is incomplete, the strict JSON is invalid, or it does not meet the content requirements, retain and report that failure; do not automatically retry or replace it with a second response. Local extraction, saving, or validation failures can only be fixed in the local deliverable. Call again only when the user explicitly requests a new round or regeneration.

Core Concepts

  • --model When omitted, the CLI automatically falls back to the active profile's resources.text.default; when the user explicitly passes a different value, follow ../arkcli-shared/references/profile-defaults.md to provide a drift warning.
  • +chat is a high-level wrapper around the data-plane Responses API (POST /responses): a single request returns the assistant text.
  • Supportsmultimodal: use --input @photo.jpg to upload local files with the request; the model can view images/videos/listen to audio and then answer. Images (.jpg/.png/.webp/...), videos (.mp4/.mov/...), audio (.mp3/.wav/.m4a/...), and general files are automatically routed by extension.
  • Supportsstreaming：--stream mode for segment-by-segment output, first outputting reasoning (thinking), then outputting the formal answer (response).
  • Supportsprogress indication: non-streaming calls begin outputting to stderr after 5s arkcli +chat: still running… elapsed Xs heartbeat lines (once every 10s), avoiding long calls with no visible output; in script scenarios, --no-progress can be used to disable it. stdout is unaffected.
  • Supportssystem instructions：--instructions "..." injecting system-level instructions.
  • Supportssampling adjustment：--temperature / --top-p / --max-output-tokens。
  • Supportsreasoning effort：--reasoning-effort minimal|low|medium|high(only effective on models that support reasoning).
  • Supportsmulti-turn continuation：--store persists this response; next time use --previous-response-id <id> to continue.
  • SupportsTools：--tools web_search(simple syntactic sugar) or --tools-file tools.json(full form such as function), together with --tool-choice auto|required|none and --max-tool-calls. See references/tools.md。
  • Supportsreconciliation commands：arkcli chat get/delete/list-input-items <response-id>, performing CRUD on responses that have been --store , see references/chat-meta.md。
  • Supportscaching and thinking：--caching enabled|disabled(with --cache-prefix) to control server-side prompt cache;--thinking auto|enabled|disabled controls the thinking phase;--expire-at <epoch_sec> adds expiration to stored responses. See references/caching-thinking.md。
  • Supportsstreaming events：--stream --include-events output raw SDK event NDJSON (one JSON per line), for programmatic consumption by autotest / agent. See references/stream-events.md。
  • Supportsverifiable strict JSON：--text-format json_schema --text-schema <file> --text-strict not only passes constraints to the server, but also confirms on the client that the response is complete, is direct JSON, and conforms to the Schema; otherwise it exits non-zero. Strict streaming buffers first and outputs only after validation succeeds, avoiding leaking half a JSON. See references/text-format.md。
  • Output schema (must read first)：+chat The return is arkcli flat schema（{id, model, content, reasoning_content, usage, ...}），not the Responses API native output[].content[].text nesting; assistant text is taken directly with .content .--format The shape will not be switched. See the "Return value" section of references/arkcli-chat.md .
  • When the user temporarily provides --api-key / --base-url / Endpoint, MUST read ../arkcli-shared/references/execution-context.md. Do not guess the plan type from the Key text, and do not write temporary values into the profile.
  • --dry-run Only constructs locally preview.v1 request summary and a secret-free execution context; it will not read online metadata, refresh credentials, call the Responses API, generate token usage, or store responses. Online dependencies must be listed as unresolved。

Quick decision

Criteria for going to +chat (all three must be satisfied):

  1. The user brings images/video/audio but the intent isopen-ended conversation/Q&A/reasoning/impressions/comments(not a fixed output form)
  2. Cannot be mapped to arkcli-understand one of the 12 sub-skills
  3. or the user needs --store / --previous-response-id multi-turn continuation

Criteria for switching to arkcli-understand (switch if any is satisfied):

  • The user wants "transcription/speech-to-text/speech recognition/ASR" → understand
  • The user wants "subtitles/timing/SRT" → understand
  • The user wants "multi-person conversation/speaker labeling/meeting transcription" → understand
  • The user wants "OCR/recognize text/recognize text in images/invoice amount" → understand
  • The user wants "box it out/draw boxes/bbox/visual grounding" → understand
  • The user wants "PDF field extraction/document extraction/extract fields/contract extraction" → understand
  • The user wants "video summary/segmentation/chapter summary" → understand
  • The user wants "video Q&A/ask about video content" → understand

In one sentence:Has @file and a clear output form → understand; chat with images/follow-up questions/open-ended impressions → chat。

Agent quick execution order

First record the user's requirements as acceptance items: answer task, specified model/Profile, input files, output format, streaming/multi-turn, explicit parameter values, and deliverable files. When only previewing the request, go directly through local --dry-run, without first checking authentication or resources online.

  1. The user only provides ep-... and the task is unclear → arkcli resources resolve <ep-id> --format jsonfor open-ended Q&A/follow-up questions +chat。
  2. The user provides a temporary Key/Base URL/Endpoint → decide parameters according to the shared execution-context composition rules, without switching profile first.
  3. When the authentication status is uncertain and there is no complete stateless context, first check arkcli auth status; if not logged in/no API Key, switch to ../arkcli-auth/SKILL.md。
  4. When the model name is uncertain, first switch to ../arkcli-models/SKILL.md。
  5. Use the call ID confirmed by this resource, and do not force it to a versioned name. If the user does not specify a model, keep the current text default or omit --model; legal plan aliases (such as ark-code-latest) do not append a version. Use resources list --modality text to verify the default,invocable、required_overrides and credential type; visible does not mean callable. The canonical Name/Version for capability queries is separate from the billing call ID, and EP always remains EP. Only unresolved model family names are queried further; do not guess versions from strings.
  6. Add when streaming output is needed --stream; when multimodality is needed, add --input @<file>(may be repeated).
  7. check the keys, values, and input modalities actually supported by the model; do not treat the full parameter set as the capabilities of all models. User-specified temperature, token limit, thinking, store=false, etc. must not be omitted or changed; when unspecified, use compatible defaults and do not additionally enable web access, storage, or tool execution.
  8. Before making a real request, first determine the delivery path; when saving is required, follow the reference's single-capture flow so that the call's stdout goes directly into a temporary response file. Accept based on the first real return: for ordinary results take .content, for strict JSON check completeness/Schema; multiple turns must reference the real previous-turn ID and maintain the same call context. For streaming, retain NDJSON, and after confirming a successful terminal state extract the official body text; reasoning text or the Agent's own answer must not be treated as model output. Saved files must match that body text verbatim; any local failure must not trigger a second model request.

Authentication admission only states verified facts: local login, a Key listing as Active, or resource visibility each alone cannot prove that the current data-plane request is usable. When an actual call returns 401, verify the current lane credentials; for 403/access errors, perform a read-only capability and permission check as described below; for 429, distinguish rate limiting from quota exhausted. Suggest available candidates, but do not automatically rotate Keys, switch Profiles/paid paths, or modify defaults. When a stored response does not exist or has expired, report it accurately; do not quietly remove previous-response-id, restart the conversation, and then claim the context was successfully continued.

Common fallbacks

  • Model name uncertain: first models search。
  • endpoint ID must use +chat: pass --model ep-xxxdirectly (the endpoint itself already determines the modality, no additional flag needed).
  • Endpoint + explicit API Key, no Base URL given: the CLI will read the Endpoint region and then derive the Base URL; if the authoritative region cannot be obtained, then ask the user to supply --base-url。
  • Authentication failure: switch to ../arkcli-auth/SKILL.md。

Read-only verification of Responses API capability/access errors

The user has already provided model does not have access to responses api type errors; this turn is troubleshooting, not "try again":

  1. If the exact, complete versioned model ID is known, only execute arkcli models get <model-id> --format json; it is forbidden to replace single-model details with the candidate summary from models search .
  2. In the api_support array, locate the Responses entry by name / key / path , and use that entry's supported as the model's declared facts; do not infer backwards from the model name, lifecycle, tool list, or other capabilities.
  3. supported=true but the actual call reports an access error: this indicates "the model declaration says it is supported, but the current Endpoint / account access path is unavailable"; if the user also provided an Endpoint ID, you may additionally read-only resources resolve / infer endpoint get to verify the binding and status.
  4. supported=false only then can you say the model catalog declares it unsupported; if the Responses entry is missing, state that the metadata is insufficient and do not speculate.

Throughout, it is forbidden to execute +chatagain, automatically models activate, switch profiles, or modify default resources.

Model capability warning (stderr warn, non-blocking)

+chat during a real execution will read the ArkModels metadata once before sending the request, and print model differences with the warn: prefix to stderr; the request is sent as usual. Key points for recognition:

  1. Warn only, do not block: the appearance of a warn: line does not mean the request failed. Values as enabled/disabled, alias tables, and declared value sets are all merely "model declarations"; the server side and SDK decoder are the arbiters.
  2. Do not treat the declared set as the accepted set. Measured:glm-5-2 declaration reasoning_effort as [none, minimal, high, max], but the serverrejects none/minimal whileaccepts low/medium(only appears in its mapping_config alias table). The declared set and the accepted set may be nearly complementary.
  3. Only hint based on metadata that actually exists: when reasoning metadata is missing, other capabilities must not be treated as reasoning declarations; when the model is not in ArkModels (e.g. kimi-k3) or the query fails,silently skip, without producing any warn.
  4. The full version ID must be executed as-is: the corresponding version metadata can be queried using the bare model name, but a user-specified old version must not be automatically rewritten to the current major version.
  5. stderr changes do not affect the stdout contract：--format json 's stdout structure remains unchanged,warn: lines only go to stderr. When stable JSON is needed, parse only stdout, while retaining and checking stderr; do not use 2>/dev/null to discard warnings.
  6. --dry-run does not read metadata: Client Preview stays zero-network, and no warn: lines will appear.

Command overview

Command Description
arkcli +chat --model <id> "<prompt>" Simplest usage: plain text conversation
arkcli +chat --model <id> --stream "<prompt>" Streaming output (thinking + response two segments)
arkcli +chat --model <id> --instructions "你是简洁助手" "<prompt>" System-level instructions
arkcli +chat --model <id> --temperature 0.2 --max-output-tokens 256 "<prompt>" Sampling adjustment
arkcli +chat --model <id> --reasoning-effort high "<prompt>" Increase thinking intensity
arkcli +chat --model <id> --input @file.jpg "<prompt>" Multimodal (local files, supports image/video/audio)
arkcli +chat --model <id> --input @a.jpg --input @b.jpg "<prompt>" Multiple files
arkcli +chat --model <id> --store "<prompt>" get the id and then --previous-response-id <id> "<下一句>" Persistence + multi-turn continuation
arkcli +chat --model <id> --tools web_search --tool-choice auto "<prompt>" Tools: web search
arkcli +chat --model <id> --tools-file tools.json --tool-choice required "<prompt>" Tools: custom function
arkcli chat get <response-id> Retrieve a stored response (including function_calls)
arkcli chat list-input-items <response-id> --order desc --limit 5 List input items (multi-turn history)
arkcli chat delete <response-id> Delete a stored response
arkcli +chat --model <id> --caching enabled --store "<prompt>" Enable prompt cache + persistence
arkcli +chat --model <id> --thinking disabled --max-output-tokens 100 "<prompt>" Disable thinking to shorten output
arkcli +chat --model <id> --text-format json_object "<prompt>" Force the model to output valid JSON
arkcli +chat --model <id> --text-format json_schema --text-schema schema.json --text-strict "<prompt>" Constrain the shape with JSON Schema
arkcli +chat --model <id> --stream --include-events "<prompt>" Streaming NDJSON (one SDK event JSON per line)
arkcli +chat --model <id> --dry-run "<prompt>" Side-effect-free dry run; does not call the Responses API

Detailed documentation

  • +chat For all parameters, return values, error codes, the multimodal file auto-upload mechanism, etc. of references/arkcli-chat.md。
  • +chat 's Tools capabilities (--tools / --tools-file / --tool-choice / --max-tool-calls, including function and web_search) see references/tools.md。
  • chat get / chat delete / chat list-input-items For the three reconciliation commands see references/chat-meta.md. The responses operated on by these commands must be +chat --store ed.
  • +chat 's --caching / --cache-prefix / --thinking / --expire-at usage, echoed fields, and autotest correspondence see references/caching-thinking.md。
  • +chat 's --text-format / --text-schema / --text-schema-name / --text-strict usage see references/text-format.md。
  • +chat 's --stream --include-events NDJSON streaming event output see references/stream-events.md。