@byteplus/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

package/skills/arkcli-models/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: arkcli-models
+version: 1.0.1
+description: "arkcli model query capability: activate, list, search, and get details for BytePlus ModelArk public foundation models. Prefer product commands `arkcli models ...` over direct Raw API calls. Note: use arkcli-custommodel to query/manage custom models uploaded or fine-tuned (`cm-xxx`) under the account; this skill covers only the public foundation model catalog. Voice/TTS/ASR/podcast/voice-design/real-time voice interaction models support only marketplace search and selection guidance; do not route them to +chat/+gen/+deploy/usage/pricing/onboard/auth apikey."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli models --help"
+---
+
+# arkcli models
+
+**CRITICAL — Before starting, you MUST use the Read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains authentication gates, configuration troubleshooting, and command selection order.**
+**CRITICAL — Before executing any `models` command, you MUST use the Read tool to read its corresponding reference document. Do not invoke commands blindly.**
+
+## Usage principles
+
+- Prefer `arkcli models ...` for model-related requests.
+- Although these are standard CLI commands, their implementation entry point still comes from `shortcuts/models/`.
+- Fall back to [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) only when product commands cannot cover the request.
+- This skill is not the default fallback entry point. Enter it only when the user explicitly asks for model queries, model asset inventory, model details, or model selection for an upstream command.
+- **Voice model boundary**: Voice models such as TTS / ASR / podcast / voice design / real-time voice interaction support only marketplace search and selection guidance in arkcli; there are currently no supported voice models. Finding one with `models search` does not mean it can be used with `+deploy`, `usage`, or `pricing`. Unless the user separately asks for official documentation, do not proactively provide non-arkcli integration steps or links for the console / OpenAPI / SDK.
+
+## Applicable scenarios
+
+- The user wants to search, filter, or compare BytePlus ModelArk models.
+- The user wants to view model details, versions, context, modalities, or lifecycle states.
+- Public foundation-model inventory; use arkcli-custommodel for uploaded/fine-tuned account assets and arkcli-plans for Coding Plan model lists.
+- The user wants to activate model / open model service / enable base | context-cache for a model.
+- Upstream `+chat` / `+gen` / `+deploy` needs to determine an available model name first.
+- The user asks whether voice models exist, which voice models are available, or what TTS/ASR models are called in the marketplace: answer only the marketplace search facts and the boundary that arkcli currently does not support downstream scenario capabilities.
+
+## Anti-trigger signals
+
+- The user only wants to chat directly, generate images/videos, or deploy an Endpoint: route to the corresponding skill first and return here only if the model name is missing.
+- The user explicitly requests a raw Action, OpenAPI listing, or low-level params: route to `arkcli-api-explorer`.
+- The user is troubleshooting authentication, profile, region, or base URL: route to `arkcli-auth` or `arkcli-config`.
+- Do not treat `arkcli models` as a default entry point; do not query models first for non-model questions.
+
+## Business positioning
+
+- This skill is a dependency of other business workflows, not a destination skill.
+- It normally serves three types of upstream goals:
+  - Find the correct model for `+chat` / `+gen`.
+  - Confirm a deployable model for `+deploy`.
+  - Confirm model details and versions for business troubleshooting.
+- Unless the user is explicitly performing a model query, return to the original task after finding the model.
+- **Exception**: A voice model query is itself the destination. After finding marketplace voice models such as podcast, voice design, or real-time voice interaction, stop after explaining "discoverable but arkcli does not support invocation/deployment/usage/pricing". Do not continue to `+deploy` / `usage` / `pricing` / `onboard`, and do not proactively add non-arkcli integration paths.
+
+## Quick decisions
+
+### Price lookup for a known model
+
+Read [`references/arkcli-models-get.md`](references/arkcli-models-get.md), then use `arkcli models get <model-id> --format json` and read `pricing.prices`. Match `service_type`, `label`, `dimensions`, `usage_unit`, `unit_code`, and optional `usage_period`; never select the first row or read the removed `pricing.charge_items` / `pricing.multi_charge_items`. `price: null` means unavailable; `0` is a zero rate for that condition. An empty array does not mean free or inactive. Activation and entitlements remain in `pricing.state`, `pricing.inference_free_usage`, and related fields. `--version` selects detail metadata; prices are queried by the returned foundation-model `name`, without a version-specific guarantee.
+
+### Step 0 (hard gate): read the scenario table before selecting a command
+
+**This is the first action for any "find a model by intent" request, before choosing `search` / `list` / `resources`. You MUST use Read to open [`references/arkcli-models-scenario-table.md`](references/arkcli-models-scenario-table.md), determine whether the intent matches a scenario label, and only then decide which command to run.** This manually curated `scenario label → recommended model` table is the **highest-priority signal for intent ranking and overrides all naming heuristics / modality / capability filtering below**.
+
+**Counterexamples that are easily intercepted (must read): the following intents may "sound like hard metrics", but are actually scenario labels. Check the scenario table first instead of instinctively dropping to the `--capability` / `--modality` fallback path:**
+
+| User says | ❌ Do not use directly | ✅ Scenario label matched in Step 0 → recommended |
+|---|---|---|
+| "Complex reasoning / multi-step / strongest-quality model" | `search --capability thinking` | Complex reasoning / Agent tasks → `dola-seed-2-1-turbo` |
+| "Which model should I use for image generation?" | Stop after `resources list --modality image` | Image generation → `dola-seedream-5-0-pro` |
+| "Video / role-play / field extraction" | `search --modality ...` | Video generation / role-play / information extraction → consult the table |
+
+After a match, follow the JOIN protocol in the table: take the recommended model family stem → run `arkcli models search <family stem>` to verify facts against the left table → rank the recommendation first + add 2–3 alternatives. **Versions/full IDs in the table are only starting points; use the real-time search response for matches** (actual testing shows that table IDs can become stale).
+
+**Skip the scenario table and fall back to `search` + naming heuristics below only in these two cases:**
+- The user provides an **explicit numeric/capability hard constraint** ("200K context", "must support functioncall"), and the scenario table has no corresponding label.
+- The user **names a third-party / open-source / historical model** (qwen, glm, Seedream 4.5, and others); do not forcibly replace it.
+
+> Distinguish carefully: "complex reasoning" is a scenario label (table → pro) and **does not mean** the user supplied the `thinking` hard metric. Only the latter uses the fallback path.
+
+**Layer boundary (important; do not mix layers): the scenario table is the "model marketplace selection layer". It answers "which model should be selected in the marketplace for this intent", and its data source is always `models search` (catalog).** It provides catalog-recommended model names (for example, image generation → `dola-seedream-5-0-pro`).
+
+- "Whether the current profile can invoke it and the exact callable ID" belongs to the **downstream availability layer**, handled by `resources list` → `models get` → `+gen` / `+chat` (arkcli-gen is implemented), and is **outside this table's responsibility**.
+- Therefore, for a **pure selection question** ("find/choose a model") → use only `models search`; **do not** query `resources list` and turn "selection" into "available-resource lookup". Descend to resources list to resolve the current profile's actual ID only when the user **truly wants to generate / invoke**.
+
+This applies only to the **intent-ranking path**. Enumeration / inventory / statistics is another path: use `list` without scenario-table reranking.
+
+### Command selection
+
+- The user knows only a fuzzy model name / wants to find by intent ("strongest video model", "200K-context LLM", "model supporting thinking"): use `search`, which provides fuzzy keyword matching + structured modality/context/capability filtering.
+- To enumerate by modality / pagination parameters, or perform exact-name matching: use `list`.
+- Public catalog inventory uses `models list --page-all`; uploaded/fine-tuned account models use `custommodel list/get`; Coding Plan availability uses `plans model-list --plan <plan>`. Clarify ambiguous "my models"; do not substitute the public catalog for account assets.
+- A specific model ID is already known: use `get`.
+- The purpose is only to find a model for `+chat` / `+gen` / `+deploy`: return to the original task immediately after finding it.
+- The user **proactively** wants to activate a foundation model ("activate dola-seed-2-1-turbo first", "preview the activation request first"): use `activate`, first reading [`references/arkcli-models-activate.md`](references/arkcli-models-activate.md). If the user only wants to deploy / create an endpoint, let deploy / infer-create trigger implicit activation and do not activate it separately first.
+
+## Agent quick execution order
+
+1. Confirm whether the user is logged in; if uncertain, first inspect `arkcli auth status`.
+2. When the user's description includes intent (modality / numeric capacity / capability), use `arkcli models search` + corresponding flags (`--modality`, `--min-context-window`, `--capability`, and others).
+3. When the user knows only a fuzzy name, still use `arkcli models search <keyword>` (returns all matches by default, without pagination).
+4. To fully enumerate by modality or calculate pagination statistics, use `arkcli models list`.
+5. For recently created custom/account models, use arkcli-custommodel and its actual output schema. Only public catalog date inventory uses `models list --page-all`.
+6. When a specific model ID is known and details are needed, use `arkcli models get`.
+7. When the user explicitly wants model activation (proactive activation, not immediate deployment), use `arkcli models activate <name> [--sub-services ...]`; add `--yes` in CI and use `--dry-run` only for local request preview, never as server validation.
+8. After finding / activating the model, return to the upstream workflow that initiated it: `+chat` / `+gen` / `+deploy`.
+
+## Typical business workflows
+
+### 0. Complete the full model ID for data-plane commands (required prerequisite)
+
+Preserve exact Endpoint/Custom Model IDs and valid Coding Plan invocation names returned by the current resource catalog. Build `<name>-<primary_version>` only when a versioned foundation-model ID is required. A Plan output name or routing alias must not receive a guessed date suffix. Follow the owning skill execution context; catalog discovery does not prove account access.
+
+The **`primary_version` format is not fixed**. **Do not use a regex to decide whether it "looks like a full ID".** Formats actually observed (about half of ~152 models do not use six digits):
+
+| Format | Example full ID | Common family |
+|------|--------------|----------|
+| `YYMMDD` (six-digit date) | `dola-seed-2-1-turbo-260628`, `seed-2-0-lite-260428` | dola family |
+| Qualifier prefix + date | `seed-2-0-code-preview-260328` | Preview / variant |
+
+**Two acquisition paths, in decreasing order of efficiency:**
+
+- **Path A (efficient; reuse existing results)**: After running `arkcli models search <keyword>` or `arkcli models list`, each returned JSON item includes `primary_version`. The Agent directly reads it and concatenates `<name>-<primary_version>` without an additional call. **`search` also returns structured fields such as `context_window` / `input_modalities` / `output_modalities` / `capabilities` (from ArkModels enrich). Downstream logic can determine suitability directly and avoid an extra `get` call.**
+- **Path B (standalone query)**: When only a bare name is known, `arkcli models get <name> --transform 'primary_version'` returns the version number directly.
+
+**Note**: `--transform` output includes JSON double quotes (for example, `"260328"`). Before shell concatenation, remove them with `tr -d '"'`:
+
+```bash
+VER=$(arkcli models get dola-seed-2-1-turbo --transform 'primary_version' | tr -d '"')
+# VER=260628  -> full ID: dola-seed-2-1-turbo-260628
+# VER="" (model with an empty string) -> use the family name directly: dola-seed-2-1-turbo
+if [ -n "$VER" ]; then
+  MODEL="dola-seed-2-1-turbo-$VER"
+else
+  MODEL="dola-seed-2-1-turbo"
+fi
+arkcli +chat --model "$MODEL" "hello."
+```
+
+### 1. Find a model for trial use
+
+`models search [--modality / --capability ...]` → `+chat` / `+gen`
+
+### 2. Find a model for production integration
+
+`models search [--min-context-window / --capability ...]` → `+deploy`
+
+### 3. Filter by hard metrics
+
+```bash
+# Find the newest and strongest text model with 200K+ context and thinking capability
+arkcli models search --modality text --min-context-window 200000 --capability thinking --strict-filter
+
+# Find video generation models
+arkcli models search --modality video --strict-filter
+
+# Find multimodal LLMs
+arkcli models search --multimodal --output-modality text --strict-filter
+```
+
+Adding `--strict-filter` is strongly recommended: the default behavior is "retain missing data" (to avoid false negatives); strict returns only models that satisfy the conditions with 100% certainty.
+
+## Evidence and token units
+
+For parameter support, unlisted-parameter behavior, search/get conflicts, or NotFound, read [the get evidence rules](references/arkcli-models-get.md#parameter-evidence-and-conflicting-queries). Missing fields are not negative evidence; preserve conflicting sources separately. Public catalogs cannot inventory account-owned custom assets.
+
+- Public catalog metadata does not prove deployment, console availability, valid credentials, balance, or permissions. Resolve Endpoint bindings first; a Custom Model's base lineage must not replace its actual `cm-*` binding.
+- A missing/null capability is unknown, not support. Read the exact `api_support` item; text output does not disprove image input.
+- Keep the exact `context_window` integer for filtering. Display 131072 as 128K, 262144 as 256K, and 1048576 as 1M tokens, with the exact number alongside. Use binary units; use the exact integer when no clean abbreviation applies.
+- Exact IDs/versions use `get` directly; fuzzy discovery uses `search`. Do not guess version suffixes or repeatedly activate models to repair an unresolved ID.
+
+## Common fallbacks
+
+- Authentication failure: route to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- Profile / region looks wrong: route to [`../arkcli-config/SKILL.md`](../arkcli-config/SKILL.md).
+- If the business goal is only to find a model name for `+chat`, `+gen`, or `+deploy`, prioritize "find the model, then return to the original task"; do not stop at models itself.
+
+## Command overview
+
+| Command | Description |
+|------|------|
+| `arkcli models search [keyword] [filters]` | **Agent's first choice**: full recall + ArkModels enrichment + structured modality/context/capability filtering + reranking; returned fields include `context_window` / `input_modalities` / `output_modalities` / `capabilities` |
+| `arkcli models list` | Full enumeration by modality, pagination statistics, and model asset inventory; lightweight, without enrichment |
+| `arkcli models get <id> [version]` | Complete details for one model (aggregates multiple APIs; heaviest and most complete) |
+
+## Tier naming heuristics (fallback only when the scenario table has no match)
+
+**Priority mnemonic: scenario-table match (★★★) > naming heuristics (★★, this section) > update_time.** First use the scenario table in "Quick decisions Step 0". Use this section's naming heuristics only when the scenario table does not cover the intent or the user names a third-party/open-source/historical model.
+
+After `search` and filters, multiple candidates often remain. Tier signals in model names can help the Agent perform the final ranking step. **This is a heuristic, not a hard rule**: hard metrics (context_window / capabilities / modality) always take precedence over naming.
+
+### Generation (major version): highest priority
+
+```
+2-x > 1-8 > 1-6 > 1-5 > ...
+```
+
+A generation jump usually matters **more than tier**. Example: `dola-seed-2-1-turbo` is stronger than `seed-2-0-pro` for most tasks because the base-model generation gap is larger than the size-tier gap.
+
+### Tier (size tier within the same generation)
+
+```
+pro  ≥  no suffix  >  lite  >  flash  >  mini  >  nano
+```
+
+- `pro`: flagship, largest size / strongest capability
+- No suffix (such as `dola-seed-2-1-turbo`): mainstream tier, normally ≈ pro
+- `lite`: cost/performance balance
+- `flash`: speed optimized
+- `mini` / `nano`: low latency, high concurrency, lowest cost
+
+### Specialty suffixes (not compared as tiers; select by use)
+
+```
+-code        → programming optimized (seed-2-0-code-preview, and others)
+-thinking    → enhanced thinking capability (longer reasoning)
+-vision      → enhanced vision understanding
+-character   → role-play / long narration
+-translation → translation-specific
+```
+
+A specialty model is **normally stronger than the same-generation general pro in its domain**, but does not transfer across tasks.
+
+### Notes on comparing `primary_version`
+
+- **Within the same family**: newer dates are better (`260215 > 251228 > 251015`).
+- **Across different families**: values **cannot be compared numerically**. `glm-5-2-260617` and `seed-2-0-pro-260328` both use six digits, but their numeric order says nothing about which is stronger.
+- To compare "which is newer", always use the `update_time` field (ISO 8601, lexicographically comparable); do not parse `primary_version`.
+
+### Decision mnemonic
+
+```
+filter (hard metrics; must be satisfied)
+   ↓
+generation (2-x > 1-x; cross-generation gap usually > same-generation tier gap)
+   ↓
+tier (pro > no suffix > lite > flash > mini > nano)
+   ↓
+update_time (when generation and tier match, newer first)
+```
+
+### Sorting is already implemented in `search`
+
+The Agent does not need to perform client-side reordering. `arkcli models search` uses two-stage sorting: "group by family first, then sort within each group":
+
+```
+1. bucket             — keyword visibility (name match > description match > fallback > hidden)
+   ↓
+2. across families:   sort by the family's "representative score" (max ctx among family members → max update_time → family name)
+   ↓                  → all members of the same family remain together
+3. within a family:   gen DESC → tier DESC → ctx DESC → update_time DESC → name ASC
+```
+
+**Key design points**:
+- **Family grouping precedes detailed sorting**. The dola-seed family (max ctx=260628) as a whole ranks before all families with ctx=null. This avoids non-transitive oddities such as "1-6-flash in the same family ranking above 1-8".
+- **Within the same family, generation precedes ctx**. A new version floats above an older version with existing ctx data even if ArkModels metadata has not yet been completed (`context_window=null`). Example: `glm-5-2` (gen=502, ctx=null) ranks before `glm-4-7` (gen=407, ctx=251222).
+- **Generation precedes tier**. Within the same family, `dola-seed-2-1-turbo` (gen=201, tier=50) ranks before `seed-2-0-lite` (gen=200, tier=80), because cross-generation gaps are normally greater than same-generation tier gaps.
+- **Do not compare generation/tier across families**. pro/lite/mini are naming conventions within a family and are not comparable across families. Family order is determined by the representative score (max ctx + max time).
+
+Legacy models tagged with any of `experience hiding` / `inference hiding` / `Square Hide` automatically sink to the bottom (they are not filtered from list/search but always appear last).
+
+> **Note**: `experience hiding` / `inference hiding` / `Square Hide` are legacy hidden-page tags in the BytePlus ModelArk platform's `customized_tags`. They are unrelated to this CLI command; arkcli reads them only for sorting.
+
+## Model lifecycle: Shutdown / Retiring / Published
+
+ArkModels assigns each model a `lifecycle_status` with three values, handled differently by Search:
+
+| status | Meaning | Default search behavior |
+|--------|------|----------------|
+| `Published` | Normal service | ✓ Display |
+| `Retiring` | Being retired (still callable; not recommended for new integration) | ✓ Display; the Agent should verbally tell the user "X is being retired; use Y instead" |
+| `Shutdown` | Offline (calls will fail) | **❌ Filtered by default** (returns only with `--include-deprecated`) |
+
+In addition, models whose `display_name` contains `abandoned` / `offline` / `not in service` / `deprecated` are handled as Shutdown (fallback because some legacy models lack ArkModels metadata and rely on manual labels).
+
+**Agent behavior contract**:
+- No client-side logic is needed to "filter Shutdown"; search already does it by default.
+- When a model with `lifecycle_status="Retiring"` appears, **proactively tell the user it is being retired** and try to find a newer version in the same family (use `search` + the correct keyword).
+
+## ❌ Wrong patterns (Agents must read)
+
+The following behaviors are wrong. Choosing the wrong command prevents the Agent from obtaining enrichment data (context_window / modalities / capabilities), hidden-item sinking, and weighted reranking, leading to incorrect recommendations.
+
+- ❌ **Do not use `list` to find a model**. Any "which model/find an X model" intent must use `search`. `list` does not perform fuzzy keyword matching or weighted reranking and does not return enrichment fields.
+- ❌ **Do not use `list --modality video` to select a video generation model**. Use `arkcli models search --modality video --strict-filter`; it combines ArkModels `output_modalities` with a `task_types` fallback, recalls more accurately, and supports additional `--min-context-window` / `--capability` filters.
+- ❌ **Do not use `list --modality text` to select an LLM**. Likewise, use `search --modality text --strict-filter`. `list --modality text` considers only one signal from foundation_model_tag.filter_domains and misses many models.
+- ❌ **Do not run `list`, then `get`, to verify context_window and similar parameters**. `search` already returns `context_window` / `max_input_tokens` / `max_completion_tokens`, saving one `get` call.
+- ❌ **Do not omit the keyword from `search` merely to "view the five most popular models"**. Omitting the keyword now returns **all 152 entries** sorted by UpdateTime descending; it is no longer a curated popular list. Use `--size 5` for a small result.
+- ❌ **Do not recommend a model with `lifecycle_status="Retiring"` for new integration**. Although still callable, the vendor has marked it for retirement. Proactively warn the user and search for a newer version.
+- ❌ **Do not perform client-side secondary filtering on `search` to compensate for list limitations**. Use `search`'s built-in `--modality` / `--min-context-window` / `--capability` flags directly.
+- For fuzzy names, use `search` to discover candidates and reuse its enrichment. For an exact model ID/version, call `get` directly when details are needed; a preliminary search is not mandatory.
+- ❌ **Do not explore Raw APIs with `arkcli api --list` merely because `models list` has no server-side time-filter flag**. First run `models list --page-all --format json`, then filter local JSON by `create_time`.
+- ❌ **Do not tell the user "the CLI does not have this capability; use the console"**, unless you have confirmed that the current `arkcli models list --help` truly has no enumerable output and local JSON filtering also cannot complete the requested statistics.
+
+The only valid uses of `list`:
+- ✓ Perform **full enumeration/auditing** by `--modality` (not to "find the strongest").
+- ✓ Obtain statistics such as `total_count`.
+- ✓ Exact matching with `--name foo` (rarely needed by Agents because search also finds it).
+- ✓ Inventory the public catalog; use arkcli-custommodel for account-owned assets.
+
+## References
+
+- [arkcli-chat](../arkcli-chat/SKILL.md) -- Enter the chat / inference workflow after finding a model
+- [arkcli-gen](../arkcli-gen/SKILL.md) -- Enter the generation workflow after finding an image/video model
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) -- Enter the Endpoint deployment workflow after finding a model
+- [`references/arkcli-models-list.md`](references/arkcli-models-list.md)
+- [`references/arkcli-models-get.md`](references/arkcli-models-get.md)
+- [`references/arkcli-models-search.md`](references/arkcli-models-search.md)
+- [`references/arkcli-models-scenario-table.md`](references/arkcli-models-scenario-table.md) -- Scenario recommendation table (highest priority for intent ranking) + JOIN verification protocol
+- [`references/arkcli-models-activate.md`](references/arkcli-models-activate.md)

package/skills/arkcli-models/references/arkcli-models-activate.md

@@ -0,0 +1,103 @@
+# models activate
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Proactively activate services for a specified foundation model (corresponding to the `OpenModelChargeItem` Action in section "3. Model activation" of URL2, with the API display name "Activate model service").
+
+## Difference from implicit activation by deploy / infer-create
+
+| Entry point | Trigger method | Applicable scenario |
+|------|---------|---------|
+| `arkcli models activate <name>` | The user **proactively** activates it | Prepare model availability for the business in advance; try a new model; preview the local request first |
+| `arkcli deploy ...` / `arkcli infer endpoint create ...` | **Passively** triggered: automatically prompts when the model has not been activated | The user's actual goal is deployment / endpoint creation, and activation is only a prerequisite |
+
+`activate` does not first call GetModelChargeItem to check the state. It directly initiates OpenModelChargeItem. Repeated calls for an already activated model are idempotent (handled by the backend).
+
+## Commands
+
+```bash
+# By default, activate only the base service (inference + fine-tuning), equivalent to SubServices=["base"]
+arkcli models activate dola-seed-2-1-turbo
+
+# Client Preview: show the local request without contacting the backend or entering the [Y/N] prompt
+arkcli models activate dola-seed-2-1-turbo --sub-services base,fast-infer --dry-run
+
+# Non-interactive (CI / scripting scenario; skips the [Y/N] confirmation prompt)
+arkcli models activate dola-seed-2-1-turbo --yes
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `<foundation-model-name>` | Yes | string | Foundation model name to activate; query it using `arkcli models list` / `search` |
+| `--sub-services` | No | string list | Sub-services to activate, comma-separated. Valid values: `base` / `context-cache` / `fast-infer`. **When omitted, the backend activates only `base` by default** |
+| `--yes` | No | bool | Skip the `[Y/N]` secondary confirmation. Required in CI / scripts |
+
+### `--sub-services` values (authoritative URL2 definition)
+
+| Value | Meaning |
+|----|------|
+| `base` | Base service (inference + fine-tuning) |
+| `context-cache` | Context cache |
+| `fast-infer` | Low-latency inference service |
+
+When omitted, the backend treats it as `["base"]`. The CLI first performs local validation: a non-enum value is immediately rejected, avoiding a request that the backend would reject with `InvalidParameter.SubServices`.
+
+### Client Preview
+
+`--dry-run` is a command-local Client Preview. It emits the locally built
+`OpenModelChargeItem` request in `preview.v1`, never contacts the backend, and
+never enters confirmation or polling. It does not prove that the model exists,
+permissions are valid, or the server will accept the request.
+
+## Return value
+
+Successful response (JSON):
+
+```json
+{
+  "foundation_model": "dola-seed-2-1-turbo",
+  "state": "Available",
+  "sub_services": ["base", "context-cache"]
+}
+```
+
+Client Preview shape:
+
+```json
+{
+  "schema_version": "preview.v1",
+  "dry_run": true,
+  "mode": "client_preview",
+  "steps": [{
+    "target": "OpenModelChargeItem",
+    "payload": {
+      "FoundationModelName": "dola-seed-2-1-turbo",
+      "SubServices": ["base"]
+    },
+    "fidelity": "logical"
+  }]
+}
+```
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|---------|
+| `invalid --sub-services value "foo"` | The sub-service name is misspelled | Use `base` / `context-cache` / `fast-infer` |
+| `Operation canceled` | A value other than Y was entered at the `[Y/N]` prompt | Run the command again and confirm, or add `--yes` |
+| Model does not exist | `<foundation-model-name>` is wrong or the model has been taken offline | Use `arkcli models search` to find the correct name |
+| `timed out waiting for model to become available` | Activation succeeded, but the model did not become Available within five seconds | Usually harmless; retry `arkcli models get <name>` later to inspect the actual state |
+
+## Notes
+
+- Sub-services can be activated incrementally: for example, first `--sub-services base`, then `--sub-services context-cache` or `--sub-services fast-infer`; they do not conflict.
+- `--dry-run` makes no network request, activates nothing, and consumes no usage. It is a client preview, not server validation.
+- Activating an already activated model is idempotent (backend contract).
+
+## References
+
+- [arkcli-models](../SKILL.md) — Models skill overview
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication and global parameters
+- URL2 document section "3. Model activation" → `OpenModelChargeItem`

package/skills/arkcli-models/references/arkcli-models-get.md

@@ -0,0 +1,94 @@
+# models get
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+View model details, aggregating multiple underlying model metadata APIs to return complete information.
+
+## Commands
+
+```bash
+# Positional argument form (recommended)
+arkcli models get dola-seed-2-1-turbo-260628
+
+# Specify a version
+arkcli models get dola-seed-2-1-turbo-260628 260628
+
+# Explicit flag form
+arkcli models get --id dola-seed-2-1-turbo-260628 --version 260628
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `<id>` / `--id` | Yes | string | Model identifier, such as `dola-seed-2-1-turbo-260628` |
+| `[version]` / `--version` | No | string | Model version override, such as `260628` |
+
+## Return value
+
+Model details in JSON format, aggregated from multiple underlying APIs. Includes model name, version, capabilities, pricing, rate limits, and other information.
+
+`supported_params` is enriched for the exact model version in the detail result. Primary versions may reuse a fresh local ArkModels metadata cache; when that cache is unavailable, for explicit non-primary versions, or with `--no-cache`, the CLI uses exact-version `ListModelMetaDatas` instead. `models get` does not add ArkModels network calls for this enrichment, avoiding its low-QPS limit. `--no-cache` still bypasses both CardView and ArkModels metadata caches.
+
+- Missing field or empty array: no usable parameter catalog is currently available for that version, so `--transform supported_params` may print `null`.
+- Present but malformed upstream JSON: the CLI prints `warn: model supported_params enrichment failed: ...` with model/version context to stderr while stdout still returns the remaining model detail.
+
+## Parameter evidence and conflicting queries
+
+- A listed parameter with `support=true` is positive catalog evidence; check its type, range, enum, and required constraints. Report an explicit `support=false` faithfully. An unlisted parameter does not prove that the server rejects it, ignores it, or applies a particular default.
+- Parameter catalogs, API-specific `api_support`, and actual calls are separate evidence. Missing/unknown API entries cannot be inferred from another API, a model name, or a thinking capability.
+- If search/get disagree, first align the exact model version, query scope, and any returned cache/warning context. If the conflict remains, report each source separately; do not union their capabilities or silently prefer the more permissive value. Search metadata for a primary version does not override get for another version.
+- Runtime behavior of an unlisted parameter requires the relevant CLI/SDK/API contract or an authorized same-model/API/identity test. Do not initiate paid inference merely to answer a catalog question.
+- On NotFound, distinguish errors from empty results, preserve the supplied ID, and check supported name normalization and the requested version. Route `cm-*`, `ep-*`, and Plan aliases to their owning resource commands. For catalog troubleshooting, use a bounded search and change only an evidence-backed name/filter; include deprecated models when investigating historical resources. Do not guess version suffixes, silently substitute candidates, switch identity, or bypass the owning workflow's single-query budget.
+
+## Prices and entitlements
+
+Prices now use `pricing.model_name`, `pricing.prices`, and optional `pricing.dimension_attributes`. The old `pricing.charge_items` / `pricing.multi_charge_items` arrays have been removed. Scripts and Agents must migrate; do not filter by the old `type` field.
+
+```bash
+# Prices plus existing activation and entitlement fields
+arkcli models get dola-seed-2-1-turbo-260628 --format json --transform pricing
+
+# Unified price rows only
+arkcli models get dola-seed-2-1-turbo-260628 --format json --transform pricing.prices
+```
+
+| Field | Consumption rule |
+|------|------------------|
+| `service_type` | Distinguishes `infer`, `fast-infer`, `flex-infer`, `batch-infer`, `infer-storage`, `finetuned-infer`, and `finetuned`; never mix training and inference |
+| `label` | Billing item identifier, interpreted with its service and conditions; not the old `type` |
+| `dimensions` | Full applicability conditions, including windows, periods, and resolution; optional `ranges` describe their scope, and empty values are meaningful |
+| `usage_unit` / `unit_code` / `usage_period` | Usage unit, price unit, and optional period; preserve them, do not assume per-thousand tokens or infer currency |
+| `price` / `original_price` | Nullable numbers; `null` means unavailable, while `0` is a zero rate for that condition |
+| `discount_price_start_time` / `discount_price_end_time` | Optional discount validity times; do not invent missing values |
+| `group_index` | Original group position in this response, not a stable ID across requests; do not merge separate groups |
+| `dimension_attributes` | Model-level dimension attributes, including those not referenced by price rows |
+
+- Match the service, billing item, and all applicability conditions before displaying a rate. If multiple rows match, show their differences instead of taking the first or cheapest. If a dimension cannot be interpreted, explain the unknown condition and do not estimate a total.
+- `pricing.prices: []` means no prices for this query; it does not prove that a model is free, inactive, or nonexistent. Price request failures fail the command without falling back to legacy prices.
+- `pricing.state`, `inference_free_usage`, `resource_pack_items`, `sub_services`, and other existing non-price fields retain their paths and legacy entitlement source. Missing entitlements do not mean zero quota or inactive status.
+- Prices are queried by the resolved foundation-model name. `--version` is not a price filter. The query uses marketplace dimension defaults and global prices; the profile's physical region is not a pricing dimension.
+- This migration applies only to `models get`. `pricing models`, fine-tuning price lookup, and estimation retain their existing contracts; do not apply this schema to their outputs.
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|---------|
+| Model does not exist | The ID is misspelled or the model has been taken offline | Use `arkcli models search` to confirm the model name |
+| Authentication failed | Not logged in or credentials expired | Run `arkcli auth login` to re-establish BytePlus identity |
+
+## Notes
+
+- Both `id` and `version` support positional arguments and flags.
+- This command aggregates multiple underlying APIs and may be slightly slower than `list`.
+
+## Guards
+
+- If authentication fails, first return to `arkcli auth status`, then run `arkcli auth login`.
+- If the model ID is uncertain, first use `arkcli models search` or `arkcli models list --name` to confirm it and avoid repeatedly calling a nonexistent ID.
+- Prefer read-only queries. Do not switch profiles or modify local configuration while troubleshooting model details unless the user explicitly confirms.
+
+## References
+
+- [arkcli-models](../SKILL.md) -- All models commands
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- Authentication and global parameters

package/skills/arkcli-models/references/arkcli-models-list.md

@@ -0,0 +1,71 @@
+# models list
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List the BytePlus ModelArk public foundation-model catalog with pagination, modality filtering, and sorting. It is suitable for public catalog enumeration and statistics. If the user is looking for "which model is suitable for a task", still prefer `arkcli models search`.
+
+## Commands
+
+```bash
+# List all models (paginated by default)
+arkcli models list
+
+# Filter by modality
+arkcli models list --modality text
+
+# Case-insensitive substring filtering by name
+arkcli models list --name dola
+
+# Pagination control
+arkcli models list --page-size 20 --page-number 2
+
+# Sorting (sort-order must be Asc/Desc with an uppercase first letter)
+arkcli models list --modality text --sort-by UpdateTime --sort-order Desc
+
+# Retrieve the complete list for local script statistics/filtering
+arkcli models list --page-all --sort-by CreateTime --sort-order Desc --format json
+```
+
+## Parameters
+
+| Parameter | Required | Type | Description |
+|------|------|------|------|
+| `--modality` | No | string | Filter by modality: `text` / `image` / `video` / `audio` / `embed` |
+| `--name` | No | string | Case-insensitive substring filtering by model name |
+| `--page-number` | No | int | Page number (>=1) |
+| `--page-size` | No | int | Number of entries per page |
+| `--sort-by` | No | string | Sort field, such as `UpdateTime`, `CreateTime` |
+| `--sort-order` | No | string | Sort direction. Valid values: `Asc` / `Desc` (uppercase first letter) |
+
+## Public catalog versus account assets
+
+`models list` enumerates public foundation models, not account-owned custom models or deployed Endpoints.
+
+- For "my custom models" or recent custom-model creation counts, use [arkcli-custommodel](../../arkcli-custommodel/SKILL.md) and `arkcli models custommodel list --mine --page-all --format json`. Remove the personal scope only when explicitly asked for account-wide assets. Do not add `--ready` when counting all created models.
+- Filter actual asset creation timestamps in the user's timezone and time window. Missing timestamps or incomplete pagination mean unknown/partial counts. Never infer ownership from public catalog names, tags, model types, or creation timestamps.
+- Deployed resources belong to `infer endpoint list`; currently callable resources belong to `resources list`. Coding Plan catalogs use `plans model-list` for the explicit plan. These sets are not interchangeable.
+- Missing capability fields in `models list` are not negative evidence. Use exact-model/version `models search/get` metadata. An empty public catalog does not prove that the account has no custom assets or Endpoints.
+
+`--transform` extracts fields such as `items.#` or `items.#.name`; it is not full jq and cannot perform date arithmetic. Retain complete JSON before local projection/filtering, and do not count a truncated sample as the full inventory.
+
+## Return value
+
+A paginated JSON result with top-level fields `page_number`, `page_size`, `total_count`, and `items`. Each item normally includes fields such as `name`, `display_name`, `primary_version`, `access_type`, and `foundation_model_tag`.
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|---------|
+| Empty result | The `--name` substring matched no public models | Use `arkcli models search` for fuzzy search |
+| Authentication failed | Not logged in or credentials expired | Run `arkcli auth login` to re-establish BytePlus identity |
+
+## Notes
+
+- `--name` is a case-insensitive substring filter. For exact details, use `models get <id>`.
+- Combine with `--transform` to extract a field, such as `--transform 'items.0.name'`.
+- Select the correct public-catalog, custom-asset, Endpoint, or Plan command before pagination and filtering. A missing filter does not justify querying another resource class or guessing a Raw API.
+
+## References
+
+- [arkcli-models](../SKILL.md) -- All models commands
+- [arkcli-shared](../../arkcli-shared/SKILL.md) -- Authentication and global parameters