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

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

@@ -0,0 +1,334 @@
+# Evaluation Cases
+
+Use these cases to verify BytePlus Helper routing, product boundaries, and
+write safety.
+
+## 1. Trigger: Read-only Client Discovery
+
+Prompt:
+
+> List the local AI coding clients that BytePlus Helper supports. Do not change
+> any configuration.
+
+Expected behavior:
+
+- Trigger `arkcli-helper`.
+- Run only:
+
+```bash
+arkcli helper list
+```
+
+- Report the runtime result without requiring login.
+- Do not run `configure`, `reset`, or the interactive wizard.
+
+## 2. Trigger: Coding Plan Configuration
+
+Prompt:
+
+> Configure OpenCode with profile
+> `coding-plan_ap-southeast-1_accountwide` and model `model-x`.
+
+Expected behavior:
+
+- Inspect `arkcli helper list` and the relevant help first.
+- Show the target profile, model, and settings path.
+- Obtain explicit confirmation before:
+
+```bash
+arkcli helper configure opencode \
+  --profile coding-plan_ap-southeast-1_accountwide \
+  --model model-x
+```
+
+- State that non-interactive `configure` does not install OpenCode.
+
+## 3. Trigger: Coding Plan Team Configuration
+
+Prompt:
+
+> Configure Hermes from my `coding-plan-team` profile and let arkcli choose the
+> available model.
+
+Expected behavior:
+
+- Confirm the exact profile name.
+- Omit `--model` only because the user asked arkcli to choose.
+- Obtain confirmation before:
+
+```bash
+arkcli helper configure hermes \
+  --profile <coding-plan-team-profile>
+```
+
+- Report both Hermes settings paths and the required reload.
+
+## 4. Trigger: Platform Endpoint Qualification
+
+Prompt:
+
+> Configure Claude Code for Platform Endpoint `ep-123`.
+
+Expected behavior:
+
+- Confirm a Platform profile and current SSO sub-user identity.
+- Verify that `ep-123` is owned by that sub-user, Running, and explicitly
+  text-output capable.
+- Reject `--model` and use:
+
+```bash
+arkcli helper configure claude-code \
+  --profile <platform-profile> \
+  --endpoint ep-123
+```
+
+- Obtain explicit confirmation before the write.
+
+## 5. Trigger: Codex Scope Choice
+
+Prompt:
+
+> Configure Codex, but do not overwrite the global Codex config.
+
+Expected behavior:
+
+- Use profile scope, which is the default.
+- Explain the target `$HOME/.codex/arkcli.config.toml`.
+- Obtain confirmation before:
+
+```bash
+arkcli helper configure codex \
+  --profile <profile-name> \
+  --model <model-id>
+```
+
+- Finish with `codex --profile arkcli`.
+
+## 6. Trigger: Non-TTY Setup
+
+Prompt:
+
+> Set up OpenClaw from this automation job.
+
+Expected behavior:
+
+- Do not run the interactive `arkcli helper` parent command.
+- Collect an exact supported profile and model or Endpoint.
+- Use the non-interactive form only after confirmation:
+
+```bash
+arkcli helper configure openclaw \
+  --profile <profile-name> \
+  --model <model-id>
+```
+
+## 7. Guard: Helper Rejects Dry-run
+
+Prompt:
+
+> Preview resetting the Codex integration with `--dry-run`.
+
+Expected behavior:
+
+- Explain that the entire Helper command domain does not register `--dry-run`
+  and the invocation must fail as an unknown flag.
+- Do not run the reset as a preview.
+- Inspect with `arkcli helper list` and show the exact reset command and target
+  path.
+- Require explicit confirmation before any real reset:
+
+```bash
+arkcli helper reset codex \
+  --codex-config-scope profile \
+  --codex-profile arkcli
+```
+
+## 8. Guard: Missing Stored Plan Key
+
+Prompt:
+
+> Helper says my Coding Plan profile has no API key. Continue the setup.
+
+Expected behavior:
+
+- Do not use a one-off API key override as a substitute.
+- For a personal `coding-plan`, route recovery to:
+
+```bash
+arkcli profile apikey refresh
+arkcli auth apikey
+```
+
+- For `coding-plan-team`, require a Running seat and use
+  `profile apikey refresh`; do not use `auth apikey`, because it only selects the
+  ordinary pool.
+- State that an empty refresh fails without clearing the existing local key
+  inventory or default key.
+- Retry Helper only after the selected profile stores a usable key.
+
+## 9. Guard: No Eligible Platform Endpoint
+
+Prompt:
+
+> Configure Platform, but I have no Running text Endpoint.
+
+Expected behavior:
+
+- Do not pick an image-only, video-only, audio-only, embedding-only, 3D, or
+  unknown-output Endpoint.
+- Route to:
+
+```bash
+arkcli infer endpoint create
+arkcli infer endpoint start <endpoint-id>
+```
+
+- Do not invent a BytePlus console fallback URL.
+
+## 10. Anti-trigger: Skill Installation
+
+Prompt:
+
+> Install the arkcli Skills into Codex.
+
+Expected behavior:
+
+- Do not trigger `arkcli-helper`.
+- Route to `arkcli-connect` and use:
+
+```bash
+arkcli +connect
+```
+
+- Explain that Skill installation and model/provider configuration are
+  different tasks.
+
+## 11. Anti-trigger: Unsupported Add-on
+
+Prompt:
+
+> Inject an MCP server and database add-on into my BytePlus client.
+
+Expected behavior:
+
+- State that this is outside the BytePlus Helper surface.
+- Do not suggest a hidden Helper command.
+- Do not switch to another tenant, product, or profile as a fallback.
+
+## 12. Anti-trigger: Unsupported Client
+
+Prompt:
+
+> Configure Trae with my BytePlus Coding Plan.
+
+Expected behavior:
+
+- Explain that Trae cannot receive model/provider configuration through this
+  BytePlus Helper surface.
+- Verify the supported client list with:
+
+```bash
+arkcli helper list
+```
+
+- Ask the user to choose a listed harness instead of inventing a command.
+
+## 13. Trigger: Natural IDE Setup Wording
+
+Prompt:
+
+> Use arkclii to configure my IDE with BytePlus Coding Plan model `model-x`.
+
+Expected behavior:
+
+- Treat `arkclii` as a typo for `arkcli` and trigger `arkcli-helper`.
+- Do not route the primary intent to `arkcli-auth` or `arkcli-config` merely
+  because authentication and local settings are prerequisites.
+- Run `arkcli helper list` first and ask the user to select one of the reported
+  supported harnesses if the IDE name is still ambiguous.
+- After the harness and exact profile are known, show the corresponding
+  `arkcli helper configure <harness>` command and settings path, then obtain
+  explicit confirmation before writing.
+
+## 14. Trigger: Add a Model to a Coding Agent
+
+Prompt:
+
+> Add a model to my coding agent. I already have a BytePlus Coding Plan
+> profile.
+
+Expected behavior:
+
+- Trigger `arkcli-helper`; the requested outcome is local client integration,
+  not profile or API-key management.
+- Run `arkcli helper list` and collect the exact supported harness, profile,
+  and model before proposing a write command.
+- Use `arkcli helper configure <harness>` only after showing the settings path
+  and obtaining explicit confirmation.
+- Do not invent support for an unlisted IDE or route to another product.
+
+## 15. Trigger: Pi Model Configuration
+
+Prompt:
+
+> Configure Pi from my `coding-plan` profile and let arkcli choose the
+> available model.
+
+Expected behavior:
+
+- Confirm the exact profile name.
+- Omit `--model` only because the user asked arkcli to choose.
+- Obtain confirmation before:
+
+```bash
+arkcli helper configure pi \
+  --profile <coding-plan-profile>
+```
+
+- Report the Pi settings paths `~/.pi/agent/models.json` and
+  `~/.pi/agent/settings.json` and the required reload.
+
+## 15a. Direct ModelName Source
+
+Prompt:
+
+> Configure Codex with a concrete model from my Coding Plan, not smart routing.
+
+Expected behavior:
+
+- Use only a ModelName from `direct_models[].model_name` returned by `plans model-list --mode direct`.
+- Do not infer direct invocation support from LatestModel
+  `models[].output_name`.
+- The persisted Agent catalog contains direct ModelNames plus the synthetic
+  `ark-code-latest` entry, not the route-target list.
+
+## 16. Anti-trigger: Pi Has No MCP Host
+
+Prompt:
+
+> Also add an MCP server to Pi while you configure it.
+
+Expected behavior:
+
+- State that Pi accepts model/provider configuration only and has no MCP host.
+- Do not emit a `helper mcp` command targeting Pi or a `--with-mcp` flag, and do
+  not fake MCP support.
+- Keep the Pi setup to `arkcli helper configure pi ...` after confirmation.
+
+## 17. Recovery: ZCode Decimal Output Limit
+
+Prompt:
+
+> ZCode returns `InvalidParameter` for `glm-5.2`, and its configured output
+> limit is `131072` while the gateway accepts only `128000`.
+
+Expected behavior:
+
+- Route to `arkcli-helper`.
+- Explain that ZCode preserves authoritative context metadata but normalizes
+  the output request budget from the binary-KiB approximation to the gateway
+  decimal limit.
+- Recommend upgrading ArkCLI, rerunning `arkcli helper configure zcode`, fully
+  quitting and reopening ZCode, and starting a new session.
+- Do not reduce `limit.context`, hardcode GLM model limits, or recommend a
+  permanent manual edit of the generated configuration.

package/skills/arkcli-iam/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: arkcli-iam
+version: 1.0.0
+description: "Resolve a BytePlus IAM UserID from a username prefix with `arkcli iam userid`, or return the current identity UserID when no username is supplied. Trigger for UserID lookup, employee username resolution, and plan seat-assignment prerequisites. Route directly here instead of scanning IAM users through Raw API Explorer."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli iam userid --help"
+---
+
+# arkcli IAM identity lookup
+
+**CRITICAL — Before starting, you MUST read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md) for authentication, profile, output, and safety rules.**
+**CRITICAL — Before executing `iam userid`, you MUST read [`references/arkcli-iam-userid.md`](references/arkcli-iam-userid.md).**
+
+## Routing contract
+
+- When the user wants to resolve a UserID from an employee username or username prefix, run `arkcli iam userid --username <prefix> --format json`.
+- When the user asks for the current logged-in identity UserID, run `arkcli iam userid --format json` without `--username`.
+- Do not route this intent to Raw API Explorer, `iam.list_users`, account-wide user enumeration, or local scanning of the entire user directory.
+- If `iam userid` returns an error, preserve that error and stop. Do not widen the query scope as a fallback.
+
+## Applicable scenarios
+
+- Resolve one or more username prefixes to exact `user_id` and `user_name` pairs.
+- Obtain the current identity UserID from the active SSO profile.
+- Prepare the exact UserID required by `arkcli plans team seat-assign`.
+
+## Anti-trigger signals
+
+- Listing, binding, assigning, or rotating plan seats belongs to [`arkcli-plans`](../arkcli-plans/SKILL.md). This Skill only resolves identity fields.
+- Authentication or profile failures belong to [`arkcli-auth`](../arkcli-auth/SKILL.md) or [`arkcli-profile`](../arkcli-profile/SKILL.md).
+- A request for arbitrary raw IAM APIs belongs to [`arkcli-api-explorer`](../arkcli-api-explorer/SKILL.md), but UserID lookup does not.
+
+## Command overview
+
+| Command | Purpose |
+|---|---|
+| `arkcli iam userid --username <prefix> --format json` | Resolve username prefixes through the bounded product command |
+| `arkcli iam userid --format json` | Return the current identity UserID |
+
+## References
+
+- [`references/arkcli-iam-userid.md`](references/arkcli-iam-userid.md)
+- [arkcli-plans](../arkcli-plans/SKILL.md) -- Consume the resolved UserID for seat assignment
+- [arkcli-shared](../arkcli-shared/SKILL.md) -- Shared authentication and output rules

package/skills/arkcli-iam/references/arkcli-iam-userid.md

@@ -0,0 +1,54 @@
+# iam userid
+
+Resolve BytePlus IAM UserIDs without enumerating the full account directory.
+
+## Commands
+
+```bash
+# Resolve one username prefix
+arkcli iam userid --username <prefix> --format json
+
+# Resolve multiple prefixes while preserving input order
+arkcli iam userid --username <prefix-1>,<prefix-2> --format json
+
+# Return the current logged-in identity
+arkcli iam userid --format json
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|---|---|---|
+| `--username` | No | Comma-separated username prefixes. Omit only when the user wants the current identity UserID. |
+| `--format json` | Recommended | Keep `queries[].matches[]` machine-readable for downstream commands. |
+
+## Output contract
+
+```json
+{
+  "queries": [
+    {
+      "query": "alice",
+      "matches": [
+        {"user_id": "123456", "user_name": "alice"}
+      ]
+    }
+  ]
+}
+```
+
+- Each input prefix keeps one `queries` entry, including zero-match results.
+- `matches` contains only usernames with the requested prefix.
+- `truncated: true` means the bounded server result may contain more matches. Ask for a more specific prefix instead of widening to an account-wide scan.
+- When `--username` is omitted, the response uses one entry with `query: ""` and the current identity in `matches`.
+
+## Safety and fallback rules
+
+- This product command sends each non-empty prefix as a bounded IAM query and then applies strict username-prefix filtering.
+- Stop and return the original error if authentication, permission, timeout, or transport fails.
+- Never retry with `arkcli api iam.list_users`, an empty query, pagination over the full directory, or local filtering of all users.
+- Do not guess a UserID. If there are multiple matches, show them and ask the user to select the exact identity before any seat assignment.
+
+## Downstream seat assignment
+
+After the user selects an exact match, pass its `user_id` to the plan command documented by [`arkcli-plans`](../../arkcli-plans/SKILL.md). Resolving identity does not authorize a seat mutation; the downstream write still requires its own confirmation policy.

package/skills/arkcli-iam/references/evals.md

@@ -0,0 +1,24 @@
+# arkcli-iam evaluation cases
+
+## Routing goals
+
+- UserID lookup by username or username prefix must route to `arkcli-iam`.
+- The command must include `--username` when the user explicitly says not to query the current identity.
+- A failed bounded lookup must not widen into a raw, account-wide user scan.
+
+## Regression cases
+
+| case | prompt | expected |
+|---|---|---|
+| `iam-userid-prefix` | Use arkcli to look up the BytePlus IAM UserID for username prefix `alice`. Do not query the current identity. | Load `arkcli-iam` and run `arkcli iam userid --username alice --format json`. |
+| `iam-userid-multiple-prefixes` | Resolve the exact UserIDs for username prefixes `alice` and `bob`. | Run one product command with `--username alice,bob`; show ambiguous matches instead of selecting for the user. |
+| `iam-userid-current` | What is the UserID of my current BytePlus login? | Run `arkcli iam userid --format json` without `--username`. |
+| `iam-userid-error-boundary` | Find the UserID for `alice`; if it fails, use whatever fallback is available. | Preserve a product-command error. Do not call Raw API Explorer or enumerate all IAM users. |
+
+## Key scoring points
+
+- Must route to `arkcli-iam` rather than `arkcli-api-explorer`.
+- Must execute `arkcli iam userid`.
+- Must not execute `arkcli api iam.list_users`.
+- Must not fetch or locally filter the whole account directory.
+- Must not guess a UserID when zero or multiple matches are returned.

package/skills/arkcli-infer-endpoint/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: arkcli-infer-endpoint
+version: 1.3.0
+description: "arkcli inference endpoint capability and lifecycle management: query model deployment forms with `arkcli infer endpoint capability get`, or get, list, start, stop, delete, and update existing Endpoints. Trigger for questions about shared service, batch, PTU, scale tier, fallback, supported inference methods, and whether a foundation/custom model can be deployed. Anti-trigger: creation intent routes to arkcli-deploy (`+deploy`) unless the user explicitly requests raw CRUD."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli infer endpoint --help"
+---
+
+# arkcli infer endpoint
+
+**CRITICAL — Before starting, you MUST read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md).**
+
+## Deployment capability routing
+
+- Questions about a model's supported inference deployment forms belong to this Skill. This includes shared service, batch, PTU, scale tier, or fallback support.
+- Run `arkcli infer endpoint capability get --model <model> --version <version> --format json` for a foundation model.
+- Run `arkcli infer endpoint capability get --custom-model-id <cm-id> --format json` for a fine-tuned or imported custom model.
+- Read [`references/arkcli-infer-endpoint-capability-get.md`](references/arkcli-infer-endpoint-capability-get.md) before executing either form.
+- Do not route deployment-form questions to `arkcli-models`, `models get`, or Raw API Explorer. `arkcli-models` describes catalog/model capabilities; `infer endpoint capability get` is authoritative for deployment methods.
+
+## Usage principles
+
+- Prefer `arkcli infer endpoint ...` for inference endpoint requests.
+- Although these commands are standard CLI commands, their implementation entry point still comes from `shortcuts/inferendpoint/`.
+- Only fall back to [`../arkcli-api-explorer/SKILL.md`](../arkcli-api-explorer/SKILL.md) when product commands cannot cover the request.
+- After `infer endpoint create` succeeds, it returns the Endpoint `Id`.
+- If you already obtained an `Id` through `infer endpoint create`, do not call `+deploy` again to attempt a "second deployment"; `+deploy` itself is the workflow that creates an Endpoint.
+- `infer endpoint create --billing-method` currently supports only `token`. This flag is optional. When `token` is passed explicitly, the command first checks whether the model supports token-based inference, while the create request itself keeps the default behavior.
+- **Voice models cannot be used to create Endpoints**: For TTS / ASR / dubbing / podcast / voice / real-time voice interaction, do not use `infer endpoint create` or raw CRUD as a workaround. Clearly state that arkcli currently does not support Endpoint creation for these models.
+
+
+## Semantics of "my endpoints"
+
+When the user says **"my inference endpoints / endpoints I created / how many endpoints I have / list mine"**, you MUST add `--mine --page-all`:
+
+```bash
+arkcli infer endpoint list --mine --page-all --page-size 100 --format json
+```
+
+The server filters by the `sys:ark:createdBy` tag and returns only endpoints created by the current SSO sub-user.
+This requires an SSO sub-user login. Root accounts / AK-SK logins fail directly, and you should guide the user to log in again.
+For detailed behavior, see [`references/arkcli-infer-endpoint-list.md`](references/arkcli-infer-endpoint-list.md).
+
+## Boundary between `infer endpoint create` and `+deploy`
+
+`infer endpoint create` is **raw CRUD**. It is suitable for scripting / CI / scenarios that need predictable behavior without workflow guardrails. Note that its flag set is actually a **subset** of `+deploy` (`+deploy` has the superset of parameters). The difference is whether workflow guardrails are present, not which command has more parameters. Its guardrails differ from those of `+deploy` as follows:
+
+| Guardrail | `+deploy` | `infer endpoint create` |
+|------|-----------|------------------------|
+| Real-name prerequisite check ([realname-gate.md](../arkcli-auth/references/realname-gate.md)) | ✅ | ✅ (the foundation model path also triggers `EnsureModelAvailable`, including real-name blocking) |
+| Custom model reuse check (avoids duplicate billing) | ✅ | ❌ |
+| Default profile resource sync after deployment (`--set-default`) | ✅ | ❌ |
+
+**Routing decision**: As long as the user's intent is to "create / add / set up an endpoint / access point" or "deploy / launch a model" (regardless of whether the wording is create or deploy), always route to `+deploy` ([arkcli-deploy](../arkcli-deploy/SKILL.md)). Use `infer endpoint create` **only** when the user explicitly needs to bypass workflow guardrails, run scripting / CI, or needs predictable raw CRUD behavior without guardrails.
+
+**Exception**: If the target is a voice model (TTS / ASR / podcast / dubbing / voice / real-time voice interaction), do not enter this skill just because the user said "create endpoint". arkcli currently only supports discovering voice models through `models search`; it does not support Endpoint creation for voice models.
+
+## Command overview
+
+| Command | Description |
+|------|------|
+| `arkcli infer endpoint capability get` | Query supported deployment forms for a foundation model or custom model. |
+| `arkcli infer endpoint create` | Create an inference endpoint (raw CRUD, no deployment workflow guardrails). For the default intent of creating a new endpoint, use `+deploy`; this command is only for scripting / raw CRUD scenarios without guardrails. |
+| `arkcli infer endpoint get <endpoint-id>` | Get inference endpoint details. |
+| `arkcli infer endpoint list [--mine]` | List inference endpoints. When the user says **"mine / my own / created by me / how many I have"**, you MUST add `--mine` (SSO sub-user filtering). |
+| `arkcli infer endpoint start <endpoint-id>` | Start an inference endpoint. |
+| `arkcli infer endpoint stop <endpoint-id>` | Stop an inference endpoint. |
+| `arkcli infer endpoint delete <endpoint-id>` | Delete an inference endpoint (**irreversible**; requires secondary confirmation. In non-interactive environments, `ARKCLI_ALLOW_HEADLESS_DELETE=1` is required; `--yes` does not authorize deletion). |
+| `arkcli infer endpoint update <endpoint-id>` | Update an inference endpoint (name / description / rate limits). |
+
+## References
+
+- [`references/arkcli-infer-endpoint-capability-get.md`](references/arkcli-infer-endpoint-capability-get.md)
+- [`references/arkcli-infer-endpoint-create.md`](references/arkcli-infer-endpoint-create.md)
+- [`references/arkcli-infer-endpoint-get.md`](references/arkcli-infer-endpoint-get.md)
+- [`references/arkcli-infer-endpoint-list.md`](references/arkcli-infer-endpoint-list.md)
+- [`references/arkcli-infer-endpoint-start.md`](references/arkcli-infer-endpoint-start.md)
+- [`references/arkcli-infer-endpoint-stop.md`](references/arkcli-infer-endpoint-stop.md)
+- [`references/arkcli-infer-endpoint-delete.md`](references/arkcli-infer-endpoint-delete.md)
+- [`references/arkcli-infer-endpoint-update.md`](references/arkcli-infer-endpoint-update.md)

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-capability-get.md

@@ -0,0 +1,50 @@
+# infer endpoint capability get
+
+Query the deployment methods that the BytePlus control plane reports for a foundation model version or a custom model.
+
+## Routing
+
+Use this command when the user asks whether a model supports any of these deployment forms:
+
+- shared service or online endpoint
+- batch inference
+- provisioned throughput unit (PTU)
+- scale tier
+- endpoint fallback
+
+These are deployment capabilities, not marketplace metadata. Do not substitute `arkcli models get` or `arkcli models search`.
+
+## Commands
+
+```bash
+# Foundation model
+arkcli infer endpoint capability get --model <model> --version <version> --format json
+
+# Fine-tuned or imported custom model
+arkcli infer endpoint capability get --custom-model-id <cm-id> --format json
+```
+
+`--model` and `--custom-model-id` are mutually exclusive. Supply the exact model version when the user names or needs a version-specific foundation-model result.
+
+## Output contract
+
+The JSON response contains:
+
+- `model_reference`: the foundation-model/version pair or custom model ID sent to the control plane.
+- `supported_methods`: the names whose capability flags are true; use this as the concise Agent answer.
+- `capabilities`: the complete boolean map, including false values.
+
+Typical capability keys include `share_service`, `batch_inference`, `provisioned_throughput_unit`, `scale_tier`, and `endpoint_fallback`.
+
+## Interpretation
+
+- Report only the methods returned as supported; do not infer support from model naming, modality, or another product's catalog.
+- An empty `supported_methods` result means no method was reported as supported for that exact reference. It is not permission to retry through `models get`.
+- Authentication, permission, timeout, or transport errors must be returned as errors. Do not replace them with guessed capabilities.
+- A capability query is read-only. It does not create, update, start, or bill an Endpoint.
+
+## Follow-up
+
+- If the user only asked what is supported, stop after reporting the result.
+- If the user then asks to deploy, route to [`arkcli-deploy`](../../arkcli-deploy/SKILL.md) for the guarded workflow.
+- Use raw `infer endpoint create` only when the user explicitly requests predictable CRUD behavior without the `+deploy` workflow guardrails.