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

package/skills/arkcli-helper/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: arkcli-helper
+version: 0.1.2
+description: "Configure an IDE, editor, or supported local coding agent for BytePlus Platform, Coding Plan, or Coding Plan Team: use arkcli helper configure to connect Claude Code, Codex, OpenCode, OpenClaw, Hermes, Pi, or ZCode to a model/provider or Endpoint, helper list to inspect support, and helper reset for safe rollback. Prefer arkcli-helper over arkcli-auth or arkcli-config when the user's goal is wiring a model into a local coding client, even if profile or API-key setup is also mentioned. MCP injection and unsupported clients are outside the BytePlus Helper surface."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli helper --help"
+---
+
+# arkcli helper
+
+Read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) before running a
+command. This Skill covers the BytePlus client configuration surface only.
+
+## When To Trigger
+
+Use this Skill when the user wants to:
+
+- configure an IDE, editor, or coding agent for BytePlus, even when the user
+  does not name the exact harness yet;
+- add, install, connect, or wire a model/provider into a local coding client;
+- discover which local AI coding clients BytePlus Helper supports;
+- configure Claude Code, Codex, OpenCode, OpenClaw, Hermes, Pi, or ZCode;
+- connect a client to a BytePlus Platform Endpoint;
+- configure a client from a `coding-plan` or `coding-plan-team` profile;
+- inspect or remove configuration previously managed by arkcli;
+- choose Codex profile scope versus global scope.
+
+## When NOT To Trigger
+
+- Use [`arkcli-auth`](../arkcli-auth/SKILL.md) for login, logout, identity, or
+  API key selection.
+- Use [`arkcli-profile`](../arkcli-profile/SKILL.md) to inspect, create, or
+  switch profiles.
+- Use [`arkcli-connect`](../arkcli-connect/SKILL.md) to install arkcli Skills
+  into local agents. It does not configure model providers.
+- Use [`arkcli-infer-endpoint`](../arkcli-infer-endpoint/SKILL.md) to create,
+  start, or manage Platform Endpoints.
+- Do not route MCP injection, database add-on setup, or unrelated subscription
+  families through BytePlus Helper. Do not fall back to another product or
+  tenant.
+
+If a prompt mentions authentication or profiles only as prerequisites for
+configuring an IDE, editor, or coding agent, keep the primary route on this
+Skill and use `arkcli-auth` or `arkcli-profile` only for the blocking recovery
+step. Generic local configuration with no client-integration goal belongs to
+`arkcli-config`.
+
+## Product Boundary
+
+Supported profile types:
+
+- `platform`
+- `coding-plan`
+- `coding-plan-team`
+
+Supported harness IDs:
+
+- `claude-code`
+- `codex`
+- `opencode`
+- `openclaw`
+- `hermes`
+- `pi`
+- `zcode`
+
+Trae is not accepted because its current integration cannot write model
+provider configuration. Always use `arkcli helper list` as the runtime source
+of truth.
+
+A Coding Plan model may be the routing model `ark-code-latest`. Switching its
+route target (Auto smart scheduling or a pinned underlying model) is outside
+this skill — use `arkcli plans model-apply --plan <plan> --model <target>`
+(see [`../arkcli-plans/`](../arkcli-plans/SKILL.md)); it writes the control
+plane and stays in sync with the console. When configuring a concrete model,
+use only the VirtualModelID catalog exposed as `direct_models[].model_name` by
+`plans model-list --mode direct`; do not treat LatestModel route
+candidates in `models[].output_name` as directly invocable ModelNames.
+
+## Command Map
+
+| Command | Mode | Purpose |
+|---|---|---|
+| `arkcli helper` | Interactive, writes after confirmation | Select profile, Endpoint or model, and client in a TTY wizard. It may offer to install a missing client. |
+| `arkcli helper list` | Read-only | List supported clients, installation state, and settings paths. No login is required. |
+| `arkcli helper configure <harness>` | Non-interactive write | Write model/provider configuration for one supported client. It does not install the client. |
+| `arkcli helper reset <harness>` | Non-interactive write | Remove only arkcli-managed model/provider configuration and preserve unrelated settings. |
+
+## Execution Order
+
+Routine Helper admission starts with `arkcli helper list` and the user-selected
+target. Do not run `profile show/list/keys list` merely to fill in context:
+these commands can synchronize remote keys and write back the local key
+inventory or default key. Use them only for an explicit Profile task after
+explaining that impact.
+
+1. Run `arkcli helper list` and the relevant `--help` command first.
+2. Determine the exact harness, profile type, profile name, and model or
+   Endpoint.
+3. For a Platform profile, verify that the Endpoint is owned by the current
+   SSO sub-user, Running, and text-output capable.
+4. For Codex, decide whether to use the default `arkcli` profile scope or the
+   explicitly requested global scope.
+5. Before `configure` or `reset`, show the exact command and affected settings
+   files, then obtain explicit user confirmation.
+6. Run the command, report its result, and explain any required client reload
+   or Codex profile activation.
+
+```text
+request
+  |
+  +-- inspect only ----------> helper list
+  |
+  +-- guided setup in TTY ---> helper
+  |
+  +-- exact target known ----> helper configure <harness>
+  |
+  +-- remove managed config -> helper reset <harness>
+```
+
+## Configuration Contract
+
+- `platform`: `--endpoint <endpoint-id>` is required and `--model` is invalid.
+- `coding-plan` or `coding-plan-team`: `--endpoint` is invalid. `--model` is
+  optional; concrete choices come from the plan's VirtualModelID catalog. When
+  omitted, arkcli prefers the direct ModelName matching the current route and
+  otherwise uses `ark-code-latest` or the first direct model available.
+- `--profile` defaults to the active profile, but explicit profile selection is
+  safer for automated or non-interactive work.
+- Plan configuration uses the API key stored with the selected profile.
+  One-off API key overrides are not a substitute for a missing profile key.
+- ZCode writes model-specific metadata to
+  `$ZCODE_HOME/v2/config.json`. It preserves `limit.context` exactly and
+  normalizes binary-KiB `limit.output` values to the decimal token limit
+  enforced by the gateway. Plan API `ModelCapability` values win; ArkModels
+  fills only missing fields, then the built-in Plan model capability table may
+  fill fields still unknown. ZCode does not
+  hot-reload its provider registry, so fully quit the ZCode process, reopen it,
+  and start a new session after configuration.
+- `configure` writes immediately and does not install a missing client.
+- `reset` writes immediately and removes only arkcli-managed entries.
+
+## Codex Scope
+
+The default Codex scope is the named profile `arkcli`:
+
+```bash
+arkcli helper configure codex \
+  --profile <profile-name> \
+  --model <model-id>
+```
+
+This writes `$HOME/.codex/arkcli.config.toml`. Start Codex with:
+
+```bash
+codex --profile arkcli
+```
+
+Use `--codex-config-scope global` only when the user explicitly wants
+`$HOME/.codex/config.toml` changed. A custom `--codex-profile` must contain only
+letters, digits, underscores, or hyphens.
+
+## Guard Checklist
+
+- [ ] The requested profile is `platform`, `coding-plan`, or
+      `coding-plan-team`.
+- [ ] The harness appears in `arkcli helper list`.
+- [ ] Platform uses `--endpoint`; plan profiles use optional `--model`.
+- [ ] The target profile, model or Endpoint, Codex scope, and settings paths
+      have been shown to the user.
+- [ ] The user explicitly approved any `configure` or `reset` command.
+- [ ] Never add `--dry-run` to a Helper command. The entire `arkcli helper`
+      domain rejects it as an unknown flag because Helper is a TTY/local
+      configuration workflow, not API request preview.
+- [ ] No command, flag, profile, or fallback from another product is suggested.
+- [ ] Completion reports the command result and any reload or activation step.
+
+## Recovery Routing
+
+- Not logged in or session expired: follow
+  [`arkcli-auth`](../arkcli-auth/SKILL.md), then retry.
+- Wrong or unsupported profile: inspect and switch with
+  [`arkcli-profile`](../arkcli-profile/SKILL.md).
+- Missing stored API key: first run `arkcli profile apikey refresh`. For a
+  personal `coding-plan`, `auth apikey` can select from the ordinary pool; for
+  `coding-plan-team`, the key must come from a Running seat and the ordinary
+  pool cannot repair it. An empty refresh preserves existing local keys.
+- No eligible Platform Endpoint: create one with
+  `arkcli infer endpoint create`; start a stopped one with
+  `arkcli infer endpoint start <endpoint-id>`.
+- Parent wizard used without a TTY: use the explicit
+  `arkcli helper configure <harness> ...` form.
+
+## References
+
+- Read [`references/arkcli-helper.md`](references/arkcli-helper.md) for exact
+  command grammar, client paths, Endpoint eligibility, errors, and recovery.
+- Read [`references/evals.md`](references/evals.md) for trigger, anti-trigger,
+  guard, and happy-path evaluation cases.

package/skills/arkcli-helper/references/arkcli-helper.md

@@ -0,0 +1,298 @@
+# `arkcli helper` Reference
+
+Read [`../SKILL.md`](../SKILL.md) first. This reference documents the BytePlus
+Helper surface and its local configuration effects.
+
+## Exact Command Grammar
+
+```bash
+arkcli helper
+arkcli helper list
+arkcli helper configure <harness> \
+  [--profile <profile-name>] \
+  [--model <model-id>] \
+  [--endpoint <endpoint-id>] \
+  [--codex-config-scope profile|global] \
+  [--codex-profile <profile-name>]
+arkcli helper reset <harness> \
+  [--codex-config-scope profile|global] \
+  [--codex-profile <profile-name>]
+```
+
+Supported harness IDs are `claude-code`, `codex`, `opencode`, `openclaw`, and
+`hermes`. Verify them at runtime instead of assuming:
+
+```bash
+arkcli helper list
+```
+
+## Read-only Inspection
+
+The following commands do not modify client configuration:
+
+```bash
+arkcli helper --help
+arkcli helper configure --help
+arkcli helper reset --help
+arkcli helper list
+```
+
+`arkcli helper list` reads the local filesystem and does not require login. It
+shows supported clients, whether each client is installed, and the settings
+path that Helper knows about.
+
+## Interactive Wizard
+
+Run the parent command in a TTY when the user wants guided selection:
+
+```bash
+arkcli helper
+```
+
+The wizard can:
+
+1. ensure the user is logged in;
+2. select a supported profile;
+3. select an eligible Platform Endpoint or Coding Plan model;
+4. select a supported client;
+5. offer to install a missing client;
+6. write the chosen configuration after confirmation.
+
+Without a TTY, the wizard cannot prompt. Use the explicit `configure` form
+instead.
+
+## Non-interactive Configure
+
+`configure` is appropriate only when the exact target is already known:
+
+```bash
+arkcli helper configure <harness> \
+  --profile <profile-name> \
+  --model <model-id>
+```
+
+It writes configuration immediately. It does not install a missing client.
+Before running it:
+
+1. inspect `arkcli helper list`;
+2. show the exact harness, profile, model or Endpoint, scope, and settings
+   files;
+3. obtain explicit user confirmation.
+
+The entire Helper command domain rejects `--dry-run` as an unknown flag.
+Helper configures local harness state and is not an API request-preview
+surface. Do not generate either `arkcli --dry-run helper ...` or
+`arkcli helper ... --dry-run`.
+
+## Coding Plan Profiles
+
+Accepted plan profile types are:
+
+- `coding-plan`
+- `coding-plan-team`
+
+Example:
+
+```bash
+arkcli helper configure opencode \
+  --profile coding-plan_ap-southeast-1_accountwide \
+  --model <coding-model-id>
+```
+
+For a plan profile:
+
+- `--endpoint` is invalid;
+- `--model` is optional;
+- concrete `--model` values come from the plan VirtualModelID catalog, not the
+  LatestModel route-target list;
+- if `--model` is omitted, arkcli prefers the direct ModelName matching the
+  current route, then `ark-code-latest`, then the first direct model available;
+- the selected profile must contain its stored default API key.
+
+If a personal `coding-plan` stored key is missing, refresh its ordinary key
+inventory and, when interactive selection is needed, use:
+
+```bash
+arkcli profile apikey refresh
+arkcli auth apikey
+```
+
+For `coding-plan-team`, the key comes from
+`GetSeatInfo.Result.ApiKey` on a Running seat. `auth apikey` only selects an
+ordinary key and cannot repair the team profile. If the applicable remote
+source returns no usable key, refresh fails and preserves the existing local
+key inventory and default key.
+
+A one-off API key override does not replace the stored profile key used by
+Helper plan configuration.
+
+### ZCode model limits
+
+`helper configure zcode` writes `$ZCODE_HOME/v2/config.json` (default
+`$HOME/.zcode/v2/config.json`). For Plan models, each limit comes first from
+the Plan API `ModelCapability`; ArkModels fills only missing fields, followed
+by the built-in compatibility table for fields still unknown. Helper does not
+apply a uniform limit or dynamically infer limits from model names.
+
+- `limit.context` preserves `context_window` exactly for ZCode context
+  accounting and compaction.
+- `limit.output` becomes the request `max_tokens` budget. Known binary-KiB
+  approximations are normalized to the gateway decimal limit, including
+  `131072 -> 128000`, `262144 -> 256000`, and `393216 -> 384000`. Decimal and
+  unrecognized values remain unchanged.
+- A missing field is omitted independently. If both fields are unknown, the
+  entire `limit` object is omitted. `ark-code-latest` does not inherit a
+  static model limit when authoritative target metadata is unavailable.
+
+The interactive smart-routing picker uses only LatestModel route candidates.
+The concrete-model picker and persisted Agent model catalog use only
+VirtualModelID entries, plus a synthetic `ark-code-latest` entry. Load labels
+are shown only for `Load.Status=1` with `Load.Level=1/2/3`.
+
+For an `InvalidParameter` 400 caused by an old ZCode output limit, upgrade
+ArkCLI, rerun the original `arkcli helper configure zcode ...` command, and
+fully quit the ZCode process, reopen it, and start a new session. Switching
+models or continuing an existing session does not hot-reload the provider
+configuration. Do not convert `limit.context` to decimal or maintain a manual
+model-name override.
+
+## Platform Profiles
+
+For a Platform profile, the exact form is:
+
+```bash
+arkcli helper configure <harness> \
+  --profile <platform-profile> \
+  --endpoint <endpoint-id>
+```
+
+Platform rules:
+
+- `--endpoint` is required;
+- `--model` is invalid;
+- the current identity must be an SSO sub-user;
+- the Endpoint must be owned by that current sub-user;
+- the Endpoint must be Running;
+- the Endpoint must explicitly support text output.
+
+Text-output multimodal Endpoints are allowed. Image-only, video-only, 3D,
+audio-only, embedding-only, and unknown-output Endpoints are excluded.
+
+When no eligible Endpoint exists, use the dedicated Endpoint commands:
+
+```bash
+arkcli infer endpoint create
+arkcli infer endpoint start <endpoint-id>
+```
+
+BytePlus Helper does not invent a console fallback URL for this case.
+
+## Client Matrix and Settings Paths
+
+| Client | Harness ID | Settings path written or inspected | Reload or activation |
+|---|---|---|---|
+| Claude Code | `claude-code` | `$HOME/.claude/settings.json` | Restart or reload Claude Code. |
+| Codex | `codex` | `$HOME/.codex/<profile>.config.toml` by default, or `$HOME/.codex/config.toml` for global scope | Run `codex --profile <profile>` for profile scope. Restart an existing session. |
+| OpenCode | `opencode` | `$OPENCODE_CONFIG` or `$HOME/.config/opencode/opencode.json` | Restart or reload OpenCode. |
+| OpenClaw | `openclaw` | `$OPENCLAW_CONFIG_PATH` or `$HOME/.openclaw/openclaw.json` | Restart or reload OpenClaw. |
+| Hermes | `hermes` | `$HOME/.hermes/config.yaml` and `$HOME/.hermes/.env` | Restart or reload Hermes. |
+| ZCode | `zcode` | `$ZCODE_HOME/v2/config.json` or `$HOME/.zcode/v2/config.json` | Fully quit ZCode, reopen it, and start a new session; existing sessions do not hot-reload provider config. |
+
+`arkcli helper list` reports the Codex catalog path
+`$HOME/.codex/config.toml`. This is an inspection hint, not the default write
+scope. `configure codex` defaults to the named profile file
+`$HOME/.codex/arkcli.config.toml`.
+
+Trae is not supported by the BytePlus Helper command surface because its
+current integration cannot write model provider configuration.
+
+## Codex Scope
+
+Default profile scope:
+
+```bash
+arkcli helper configure codex \
+  --profile <profile-name> \
+  --model <model-id>
+codex --profile arkcli
+```
+
+The default Codex profile name is `arkcli`, and the default target is:
+
+```text
+$HOME/.codex/arkcli.config.toml
+```
+
+Custom profile:
+
+```bash
+arkcli helper configure codex \
+  --profile <profile-name> \
+  --model <model-id> \
+  --codex-profile byteplus
+codex --profile byteplus
+```
+
+Codex profile names may contain only letters, digits, underscores, and
+hyphens.
+
+Global scope:
+
+```bash
+arkcli helper configure codex \
+  --profile <profile-name> \
+  --model <model-id> \
+  --codex-config-scope global
+```
+
+Global scope writes `$HOME/.codex/config.toml`. Use it only when the user
+explicitly asks to change configuration shared by all Codex profiles.
+
+## Reset
+
+```bash
+arkcli helper reset <harness>
+```
+
+For Codex, reset the same scope and named profile used during configuration:
+
+```bash
+arkcli helper reset codex \
+  --codex-config-scope profile \
+  --codex-profile byteplus
+```
+
+Reset removes only arkcli-managed provider/model entries and preserves
+unrelated user configuration. It still writes immediately, and the Helper
+domain does not register `--dry-run`. Show the exact target and obtain
+explicit confirmation before running it.
+
+## Errors and Recovery
+
+| Symptom | Meaning | Recovery |
+|---|---|---|
+| Parent command cannot prompt | No interactive TTY is available. | Use `arkcli helper configure <harness> ...`. |
+| Login or session error | The selected operation needs a valid BytePlus identity. | Run `arkcli auth login`, then retry. |
+| Unsupported profile type | Helper accepts only Platform, Coding Plan, and Coding Plan Team profiles. | Use `arkcli auth whoami --format json` for the current summary. If the user explicitly asks to switch, explain that Profile reads may synchronize remote keys and write back local key state before entering the `arkcli-profile` workflow. |
+| Missing personal Coding Plan API key | The selected personal plan profile has no usable ordinary-pool key. | Run `arkcli profile apikey refresh`; use `arkcli auth apikey` only to interactively select an ordinary key. |
+| Missing Coding Plan Team API key | No usable key was returned for a Running team seat. | Restore or assign the seat, then refresh. Do not use `auth apikey`; its ordinary pool is unrelated. |
+| No user-owned Endpoint | No eligible Endpoint belongs to the current sub-user. | Run `arkcli infer endpoint create`. |
+| Endpoint is not Running | The selected Endpoint cannot serve requests. | Run `arkcli infer endpoint start <endpoint-id>`. |
+| Endpoint is filtered out | It is not an eligible text-output Endpoint. | Select or create a Running text-output Endpoint. |
+| Unsupported harness | The client cannot receive model/provider configuration through BytePlus Helper. | Re-run `arkcli helper list` and choose a listed harness ID. |
+| MCP or database add-on requested | That capability is outside the BytePlus Helper surface. | State the boundary; do not use another tenant or product as fallback. |
+
+## Completion Receipt
+
+After a successful write, report:
+
+- the harness;
+- the selected profile type and profile name;
+- the model ID or Endpoint ID;
+- the settings path or paths;
+- the Codex scope and profile name, if applicable;
+- the reload or `codex --profile <name>` activation step;
+- whether the client was already installed or was installed by the interactive
+  wizard.
+
+Never print full API keys, tokens, or other credentials.