arkcli-doctor

arkcli Doctor (diagnostic main entry point)

CRITICAL — before starting, MUST first use the Read tool to read ../arkcli-shared/SKILL.md(authentication gate, command selection order, output and security rules).

What it solves

arkcli doctor is the sole external diagnostic convergence point of Ark CLI. All diagnostic and remediation suggestions come from arkcli doctor [<scope>] [<id>] ; diagnostic commands are read-only by default; remediation actions are executed according to the suggestions output by the command and the corresponding reference. After the Agent receives the user's error / resource ID / vague question, it first uses this skill to decide which path to take, then delegates to the corresponding scope reference or error code reference.

Boundary:installation, version, login, profile, AK/SK authentication-type issues belong to arkcli-shared / arkcli-auth; here only covers the arkcli doctor command family (business-side diagnostics).

Eight Domains (one skill convergence point)

This skill covers eight parallel domains at once. Each domain has one reference, routed by user scenario:

Domain	Command	Reference	What it solves
CLI health(default)	`arkcli doctor`	`references/scope-cli.md`	local binary version / network connectivity / clock skew / current profile authentication — first check during onboarding
account	`arkcli doctor account`	`references/scope-account.md`	identity / realname / balance / IAM Ark system preset policies / VMP three segments / TOS activation
Error code	`arkcli doctor error <code>`	`references/error-codes.md`	translate a single error code into structured diagnosis + remediation (including 5 subtypes of video generation + general Ark/common codes)
infer-endpoint	`arkcli doctor infer-endpoint <id>`	`references/scope-infer-endpoint.md`	single endpoint status / usage / error rate / quota pressure
model	`arkcli doctor model <name>`	`references/scope-model.md`	overall model diagnosis across endpoints (usage / quota / top endpoint / modality-adaptive metrics)
metrics	`arkcli doctor metrics <id>`	`references/scope-metrics.md`	36 named PromQL queries (metric values output directly, without health judgment, to give LLM/SRE the data)
report	`arkcli doctor report`	`references/scope-report.md`	seedance 2.x effectiveness issue reporting (badcase → Ark troubleshooting platform)
verify-origin	`arkcli doctor +verify-origin ...`	`references/verify-origin.md`	create source feature verification tasks for 1-20 image/video URLs and poll for official results

Command family

arkcli doctor                                  # CLI 健康（默认 scope，install/connect/config）
arkcli doctor account                          # 账号级诊断（→ references/scope-account.md）
arkcli doctor infer-endpoint <ep-id>           # 单接入点诊断（→ references/scope-infer-endpoint.md）
arkcli doctor model <model-name>               # 模型维度诊断（→ references/scope-model.md）
arkcli doctor metrics <query-id>               # 具名 PromQL 查询（→ references/scope-metrics.md）
arkcli doctor error <error-code>               # 错误码查表（只读，→ references/error-codes.md）
arkcli doctor report --task-id ... --feedback ...   # seedance 2.x 效果问题上报（→ references/scope-report.md）
arkcli doctor +verify-origin <url> [url...]     # 1-20 个媒体来源特征验证（→ references/verify-origin.md）

ordinary diagnostic commands are flat verbs;+verify-origin is an explicit task-type workflow.--window <duration>(default 24h) controls the VMP time window; for structured output, prefer using --format json. Remediation suggestions are given by the diagnostic results and reference; do not concatenate unregistered parameters to doctor commands.

Source verification priority routing

When the user wants to verify whether one or more images/videos contain Ark, Seedance, or Seedream generation source features:

first read references/verify-origin.md；
pass all URLs in one command, at most 20, and do not start a separate process for each URL;
the first call does not include --yes, to obtain the full-batch cost disclosure; this step does not obtain an invoker, nor does it send Create/Get business requests;
fully display the disclosure, and after the disclosure wait for the user's explicit confirmation;
after the user confirms, forthe same batch of parameters add --yesonly once; that confirmation covers all URLs in the entire batch;
the CLI internally completes Create, 20 QPS pacing, and Get polling every 5 seconds; the Agent does not write shell loops;
The final stdout JSON must become the entire content of the reply, with no explanation, summary, translation, code fences, or prefix/suffix.

This route is not used to determine the truth or falsity of media content, fake news, copyright ownership, legal authentication, content safety, image quality, or playback quality.IsOfficial=True/False/Null It can only be forwarded as the original server-side value; the Agent must not draw its own conclusions.

Core paradigm: from user message to answer

[!IMPORTANT] Diagnostic intent takes precedence over reporting intent: first check whether the user is asking for a diagnostic action such as "check / diagnose / troubleshoot / analyze the cause / why / check health / check metrics". As long as any diagnostic intent exists, even if the user also says "and report it", you must first go through doctor model or doctor infer-endpoint; after the diagnosis returns report_suggestion and it is confirmed to be an effectiveness-type issue, then ask the user, and only enter report (Path A) if the user agrees. Only when the user explicitly requests "report directly / submit a badcase / feed back to Ark",and has no diagnostic request at all, and the context also confirms it is Seedance 2.x + effectiveness-type issue, may you skip diagnosis and enter scope-report.md Path B. When the user merely describes effectiveness issues such as "wrong subtitles / character drift / flickering" but does not say they want to report it, you likewise must not directly run report.

[!WARNING] The first step MUST be: scan the user message for any resource ID (model name like doubao-*/seed-* or ep-xxx）. Except for the pure reporting Path B above that already meets all thresholds and contains no diagnostic intent,as long as there is a resource ID, you MUST go through doctor <scope> <id>, regardless of whether there is also an error code. When a resource ID is present, directly doctor error <code> is anincorrect path—it will lose key diagnostic signals such as the error rate distribution, top endpoints, and quota pressure.

Counterexample self-check (if you are planning to do this, stop):

❌ The user says "my doubao-seedance-1-0-pro keeps reporting ContentRiskBlocked" → you run arkcli doctor error ContentRiskBlocked

✅ Correct approach: run arkcli doctor model doubao-seedance-1-0-pro, then load the error-codes.md subtype section according to the returned error code distribution

❌ The user says "ep-xxx reports ModelAccessDenied" → you run arkcli doctor error ModelAccessDenied

✅ Correct approach: run arkcli doctor infer-endpoint ep-xxx, then load error-codes.md the model_access_denied section

 用户消息（自然语言 / 错误 JSON / "看看 ep-xxx" / 错误码 / request_id）
        │
        ▼
 ① 抽取关键值：error_code / error_message / resource_id (ep-xxx / model-name) / request_id
        │
        ▼
 ② 按下表决定 Path（**有 resource_id 一律 Path 1 / Path 3**，不要降级到 Path 2）
        │
        ▼
 ③ 跑相应 doctor 命令 + 加载对应 reference
        │
        ▼
 ④ 摘 findings + recommended_fixes 给用户（不复述完整 JSON）
        │
        ▼
 ⑤ 修复命令一律先给用户看、等确认；不要替用户执行写操作

Path decision table

	Has error code	No error code
Has resource ID	Path 1 (most ideal): run `doctor <scope> <id>` + load `error-codes.md` the corresponding subtype	Path 3: run `doctor <scope> <id>` to see the overall picture (status/usage/error rate/quota)
No resource ID	Path 2: directly `doctor error <code>` look up the table → load `error-codes.md`; do not run scope	Path 4/5: only a request_id or nothing at all → ask the user for the resource ID or specific error information

Reverse lookup by request_id is not currently supported (it involves authentication and internal platform data). Do not guess for Path 4/5; ask directly.

[!IMPORTANT] Do not mistake Path 1 for Path 2: as long as the user message gives both anerror codeand aresource ID(model name / ep-xxx），MUST go through Path 1 (first doctor <scope> <id> Obtain the real distribution / proportion / top endpoint of that resource on that error code, then load error-codes.md the corresponding subtype interpretation and fix).Do notdirectly doctor error <code> treat it as Path 2 — that would lose model context (error rate distribution, top endpoint, quota pressure, and other key diagnostic signals).

Path 1 trigger condition examples:

"My doubao-seedance-1-0-pro keeps reporting ContentRiskBlocked" → doctor model doubao-seedance-1-0-pro，not doctor error ContentRiskBlocked

"ep-xxx reports ModelAccessDenied" → doctor infer-endpoint ep-xxx，not doctor error ModelAccessDenied

Only when the userprovides only an error code / error JSONand no resource ID (Path 2) should you look it up in the table directly.

[!NOTE] Do not make fallback pre-calls for doctor model / doctor infer-endpoint Fallback pre-call: these two commands already run model.exists / endpoint.existsinternally first, covering "whether the model/endpoint exists".Do notrun arkcli models list / arkcli infer endpoint list / arkcli auth status etc. before the call as an existence / identity fallback — when the doctor command fails it will clearly report the reason itself (404 / VMP precheck / authentication); just handle it according to its output. Extra fallbacks only increase token consumption.

Route to scope reference

Find the reference by scope:

scope	reference	Triggering user semantics
Default (CLI healthy)	`references/scope-cli.md`	Can I use arkcli right after installing it / it suddenly stopped working / network connectivity / clock skew / current profile authentication
`account`	`references/scope-account.md`	No permission / account frozen / sub-account has no Ark permission / VMP cross-service authorization / real-name verification / balance / TOS
`infer-endpoint`	`references/scope-infer-endpoint.md`	`ep-xxx` reports 429 / slow / abnormal status / reports a certain error code / wants to see usage and quota pressure
`model`	`references/scope-model.md`	View the model as a whole across endpoints; model-level quota pressure; modality-adaptive latency and generation duration metrics

Route to error code reference

All error code diagnostic details are centralized in one file:references/error-codes.md。arkcli doctor error <code> In the JSON returned by reference , thesubtype field tells you which section to jump to.

Full subtype routing

Business domain	subtype	Jump to section
Ark error codes	`input_real_face`	`error-codes.md` §1.1.1
Ark error codes	`input_copyright`	`error-codes.md` §1.1.2
Ark error codes	`input_content_safety`	`error-codes.md` §1.1.3
Ark error codes	`output_video_copyright`	`error-codes.md` §1.1.4
Ark error codes	`output_video_safety`	`error-codes.md` §1.1.5
Ark error codes	`model_access_denied`	`error-codes.md` §1.2
Ark error codes	`rate_limit_exceeded`	`error-codes.md` §1.3

The remaining Volc native codes are already covered in the error-codes.md section index tables (including HTTP / description / handling method).error-codes.md The top-level table of contents is the primary navigation entry point.

doctor'sprerequisite dependency gates(VMP / TLS / TOS cross-service authorization) are not API error codes; they are handled jointly by arkcli doctor account output + arkcli-shared / arkcli-auth .

New error code contribution process:CONTRIBUTING.md。

doctor output schema (consume as needed)

doctor command family outputTwo sets of JSON schema — split by command.

A. Each scope command (`arkcli doctor` / `account` / `infer-endpoint` / `model`）

arkcli doctor <scope> <id> --format json returns a structured JSON.Do not perform strict schema validation— fields will increase or decrease with versions (such as TTFT/TPOT/replicas, request_id reverse lookup); retrieve them as needed by field name.

Note: the default CLI scope (arkcli doctor no-arg) schema isa flat three-part（installation / connectivity / configuration), not aligned with the business scope's generic fields (checks[] / findings[])—the CLI section has fixed and few items, so just look at the fields. The business scope follows the table below:

Top-level field	Meaning
`scope`	`cli` / `account` / `model` / `infer-endpoint`
`subject`	Resource ID (model name / endpoint id); leave blank for CLI and account
`window`	VMP time window (e.g., `24h`）
`checks[]`	Raw results of each check item:`{ id, status: pass/warn/fail/skip, value, message }`
`findings[]`	Aggregated issue list:`{ severity, error_code?, root_cause, evidence }`
`recommended_fixes[]`	Fix suggestions:`{ id, kind: skill/url/command, target, reversibility }`
`error.blocking_dependency?`	Prerequisite dependency not passed (e.g., VMP three-part authorization failed): command terminates + guides fix

B. `arkcli doctor error <code>` single error code lookup

This command isread-only lookup—no login required, no inference tokens consumed—translates one error code into a structured diagnosis. Returned fields:

Field	Meaning
`category`	Top-level category (e.g., `policy` / `permission` / `quota` / `infrastructure`）
`subtype`	Subtype under the category (e.g., `input_real_face` / `model_access_denied` / `rate_limit_exceeded`）
`code`	The matched real Volcano error code (original value echoed back, to confirm the input original code)
`root_cause`	Root cause, a user-friendly one-sentence description
`hint`	Fix guidance (runnable commands, or actions the user needs to take)
`rules`	Trigger signal candidates;multiple = composite error code, requires disambiguation(choose one according to the determination steps in the reference)
`needs_backend`	Capabilities that are depended on but not yet launched (e.g., `deface`）——do not pretend it can be fixed automatically
`skill`	fixed `arkcli-doctor`(this skill itself)
`reference`	uniformly is `error-codes`(pointing to `references/error-codes.md`); use `subtype` / `code` to locate the specific section

when showing to the user: excerpt findings + recommended_fixes(scope command) or root_cause + the fix plan in the reference section (error command),do not restate the full JSON; suggested execution requires a second confirmation from the user.

Aggregation vs raw time series

doctor outputs by defaultaggregated statistical values(e.g., error_rate、ttft.p99、tpm_peak)—one number summarizing a period of time, enough to judge "is it healthy / is the quota sufficient".

The underlying data comes from VMP's Prometheus time-series stream, but doctor model / doctor infer-endpoint currently only returns aggregated statistics and does not provide a parameter to switch to raw time series. Aggregationaverages out bursts and jitter, and cannot answer "did it burst at a certain moment / is it steadily high or pulsing to the ceiling"; when raw time series are needed, switch to references/scope-metrics.md to check existing named queries or raw query capabilities, and do not fabricate parameters.

What the user asks	Which to use
"How is it now / is it healthy"	Aggregation (default)
"When did it start / how long did it last / burst or steady state"	Raw time series

For detailed decision rules and time-series analysis methods for each type of metric, see references/scope-infer-endpoint.md 's "Aggregation vs raw time series" section.

Security and boundaries

Read-only first：arkcli doctor performs a read-only health check by default, consumes no inference tokens, and changes no resources.
Source verification is an explicit exception：doctor +verify-origin will create a remote asynchronous task; creating a new batch on Volc may incur charges; the entire batch is confirmed only once, and fetching the invoker or sending any request is prohibited before confirmation.
Fix suggestions are not the same as automatic execution: the doctor diagnosis results and reference are only responsible for providing the fix path; before actually executing other commands, the impact must be shown first, and write operations continue to follow the corresponding command's confirmation gate.
Privilege escalation boundary: control plane calls use the current identity's AK/SK or SSO-derived STS signature; do not read platform internal data (k8s / scheduler, etc.), and do not perform cross-account comparisons.
Do not burn tokens on the user's behalf: the diagnosis itself does not burn tokens, but if the fix plan involves re- +gen / +chat, first show the command to the user and wait for confirmation.
Do not pretend to be able to fix capabilities that are not yet live：needs_backend When the field is non-empty (e.g. deface) truthfully tell the user that the capability is not yet live and provide a feasible alternative.

VMP precheck and `--auto-bind`

arkcli doctor metrics / model / infer-endpoint All three commands depend on VMP (managed Prometheus) data; before invoking the commands, three things are automatically checked in order:

VMP subscription（GetSubscription) — whether the account has activated VMP;
cross-service authorization SLR（IAM CheckServiceLinkedRole，ServiceName=ark) — whether a service-linked role has been created for ark;
Telemetry binding（Ark ListTelemetryConfigs) — whether some VMP workspace has been bound to ark observability.

If any step fails, the command directly reports *output.ExitError and attaches the LinkOpenMgmtCloudProduct jump link (cloud product activation page + cloudProduct drawer), and will not activate the subscription or create the SLR on the user's behalf — these two steps require checking "agree to terms" in the console.

Only in the single scenario of "the first two steps pass but the third step is missing a binding" can the CLI automatically finish up:

# 默认行为：未绑定时直接报错并提示加 --auto-bind
arkcli doctor metrics request.qpm

# 自动建 ark_default workspace（vmp.standard.15d / 防误删）+ 调
# CreateTelemetryConfig 绑到 ark observability
arkcli doctor metrics request.qpm --auto-bind
arkcli doctor model <model-name>          --auto-bind
arkcli doctor infer-endpoint <endpoint-id> --auto-bind

Behavior details:

If any workspace already exists under the account → reuse the first one; if none → create ark_default；
metrics When the subcommand explicitly passes --workspace-id <uuid> , skip precheck and respect multi-account / integration testing scenarios.

When it is recommended to add --auto-bind：

the agent automation path (confirm the account has subscribed + created the SLR), letting the command idempotently bind telemetry;
the user has already checked the terms in the console and only the final step of creating + binding a workspace remains.

Whennotto add:

The account has not yet subscribed to VMP / has not created the SLR — adding it is useless, and the CLI will still only provide the jump link; go to the console first.

Quota pressure thresholds (defaults)

doctor's thresholds for RPM/TPM quota pressure are hardcoded (user-configurable later):

Proportion	severity	Behavior
`≥95%`	fail	Already/about to be rate-limited, raise quota immediately
`≥80%`	warn	High pressure, recommend raising quota or adjusting traffic distribution
`≥50%`	info	Healthy but with room
`<50%`	pass	Ample

Default error rate threshold 5% : warn at or above; the reference for a specific scope may override this in its own detailed rules.

When not to use this skill

The user asks how to install arkcli / how to log in / how to switch profiles → arkcli-shared / arkcli-auth
The user wants todeploya new endpoint → arkcli-deploy(not diagnosis)
The user wants tolist/start/stop/update endpoint → arkcli-infer-endpoint
The user wants to viewusage details(without 'why/abnormal' judgment) → arkcli-usage
user wants to seemodel basic meta info(parameters / pricing / supported parameters) → arkcli-models

Reference

references/scope-cli.md — CLI health check (default scope) detailed rules
references/scope-account.md — account-level diagnostics detailed rules (identity / compliance / permissions / ecosystem)
references/error-codes.md — master catalog of error codes (video generation + general Ark + common codes)
references/scope-infer-endpoint.md — single endpoint diagnostics detailed rules
references/scope-model.md — single model diagnostics detailed rules
references/scope-report.md — seedance 2.x effectiveness issue report (badcase report)
references/verify-origin.md — 1-20 image/video source feature verification, whole-batch cost confirmation, and strict result handoff
references/evals.md — source verification trigger, one whole-batch confirmation, recovery and strict handoff regression
CONTRIBUTING.md — contribution entry point for adding error codes / scope check / fixer
arkcli-shared — authentication / command selection / safety rules
arkcli-infer-endpoint — endpoint CRUD (doctor does not reimplement)
arkcli-models — common base model query