@volcengine/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.2e2d76ea86c4

package/skills/arkcli-doctor/references/scope-account.md

@@ -0,0 +1,205 @@
+# `arkcli doctor account`（账号级诊断）
+
+> 这是 [`arkcli-doctor`](../SKILL.md) 的 **account scope reference**。当用户/Agent 遇到「我账号是不是有权限调 ark / 是不是被冻结 / 余额还够不够 / 子账号缺哪个策略 / VMP 是不是开通 / TOS 开通了没」这类**账号维度**问题时读这里。
+>
+> **CRITICAL — 开始前 MUST 先用 Read 工具读取**：
+> - [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序）
+> - [`../SKILL.md`](../SKILL.md)（doctor 总入口与路径决策表）
+
+## 它解决什么
+
+`arkcli doctor account` 一次性把「当前账号能不能顺利用 Ark 数据面 + 控制面」答清楚。四段结构：
+
+| 用户场景 | Agent 跑什么 |
+|----------|-------------|
+| 「我访问 API 告诉我没权限 / ArkFullAccess 是啥」                   | `arkcli doctor account` → 读 `permissions.iam_system_policies` |
+| 「我账号是不是被冻结了 / 实名了吗 / 还有钱吗」                    | `arkcli doctor account` → 读 `compliance.realname` / `compliance.balance` |
+| 「sub-account 缺 Ark 权限吧」                                    | `arkcli doctor account` → 读 `permissions.iam_system_policies.attached` |
+| 「VMP 跨服务授权 / 开通失败怎么办」                                | `arkcli doctor account` → 读 `ecosystem.vmp.type` + `hint` |
+| 「TOS 开通了吗 / 生视频回调存不下」                               | `arkcli doctor account` → 读 `ecosystem.tos.activated` |
+| 「刚装 arkcli 能连上方舟网关吗」                                  | ❌ **不属于本 scope**——跑 `arkcli doctor`（默认 scope）|
+| 「ep-xxx 状态怎么样 / 429 是不是配额压力」                        | ❌ **不属于本 scope**——跑 `arkcli doctor infer-endpoint <id>` |
+
+## 边界：不做什么
+
+- **不 mutate / 不自动修复**：命令只读诊断，未挂 IAM 策略 / VMP 未授权时给跳转链接（`guide_url` 字段），不自动挂策略 / 不自动开通订阅——这两步必须在控制台勾「同意条款」，CLI 不代理。VMP `--auto-bind`（自动建 workspace + 绑 telemetry）走 `doctor infer-endpoint <id> --auto-bind` / `doctor model <name> --auto-bind`，不在本 scope。
+- **不越权**：仅用当前 caller 的 AK/SK；IAM `ListAttachedUserPolicies` 服务端强约束只能列出 caller 自己账号的策略；不读平台内部数据；不跨账号横比。
+- **不枚举自定义策略**：`permissions.iam_system_policies.attached` 只列 Ark 4 个系统预置策略名的命中项，自定义策略不回显（隐私考量 + agent 输出精简）。`total_attached_count` 字段兜底提示"用户可能有自定义策略"的边缘场景。
+- **不替代 `arkcli auth login`**：未登录时 identity 段仍出本地字段，其他段 Reason 写明 `not authenticated`——但不 auto-run 登录。
+
+## 硬约束：与其他 scope 的边界
+
+> [!WARNING]
+> **`doctor account` 是账号维度**，跟 `doctor` (CLI 健康) / `doctor infer-endpoint` / `doctor model` / `arkcli usage` **不重叠也不互相兜底**：
+>
+> - ❌ 用户问「网络通吗 / TLS 握手成功吗」→ 跑 `arkcli doctor`（默认 scope），不是 `doctor account`
+> - ❌ 用户问「ep-xxx 报错 429 / 慢 / 挂了」→ 跑 `arkcli doctor infer-endpoint ep-xxx`，不是 `doctor account`
+> - ❌ 用户问「某错误码怎么修」→ 跑 `arkcli doctor error <code>`，不是 `doctor account`
+> - ❌ 用户问「免费额度还剩多少 / 套餐还剩几次 / 媒资库额度」→ 跑 `arkcli usage balance`（quota 额度），不是 `doctor account`
+> - ✅ 用户问「账号权限 / 实名 / **账户余额/账户里还剩多少钱/欠费/冻结** / 云产品开通」→ 跑 `arkcli doctor account`
+>
+> **『余额』语义消歧**：中文『账号余额 / 账户余额 / 还有多少钱』默认指**账户资金**（充值账户 CNY 余额），走本 scope 的 `compliance.balance`（QueryBalanceAcct）。**只有**用户明说『免费额度 / 套餐额度 / 媒资库额度』这类 **quota 语义** 才走 `arkcli usage balance`。两者数据源完全不同，别混。
+
+## 第一步：跑诊断
+
+```bash
+arkcli doctor account                      # 默认，无参
+arkcli doctor account --format json        # 完整结构化 JSON（默认）
+```
+
+> 命令本身就是**只读体检**，不注册 `--dry-run`；未登录也能跑（identity 段照出 `ok=false + reason`，其他段每个 check Reason 写明 `not authenticated`）。
+
+## 第二步：读输出（4 段）
+
+### ① Identity（本地派生）
+
+从 `auth.ActiveIdentity(cfg)` 派生，纯本地。**未登录 → `ok=false` + `reason`**，其他字段留空；**已登录 → 5 个字段完整**。
+
+| 字段                       | 含义                                       |
+|----------------------------|--------------------------------------------|
+| `identity.account_id`      | 主账号 ID（root 账号 ID，跟 STS 一致）     |
+| `identity.user_id`         | 当前身份的 IAM 子用户 ID（主账号为 root ID）|
+| `identity.user_name`       | 当前身份的 IAM 用户名（`ListAttachedUserPolicies` 传参用）|
+| `identity.is_root`         | **是否主账号** —— true 表示权限段短路视为已授权 |
+| `identity.auth_method`     | `sso` / `aksk` / `apikey` / `sts` / `none` |
+| `identity.ok`              | 归一化布尔 == (auth_method != none)        |
+| `identity.reason`          | ok=false 时的原因（SSO 过期 / 未配置 / 凭证不可用）|
+
+### ② Compliance（实名 + 余额）
+
+**在线段**，两个独立 check 各自降级：一个失败不阻塞另一个。
+
+| 字段                                | 含义                                                              |
+|-------------------------------------|-------------------------------------------------------------------|
+| `compliance.realname.verified`      | 是否已实名（**开通 / 部署 / 计费 前置**）                          |
+| `compliance.realname.identity_type` | `individual`（个人）/ `enterprise`（企业）/ `""`（未实名或未知）    |
+| `compliance.realname.reason`        | 探测失败时的原因                                                  |
+| `compliance.balance.available`      | 可用余额原值（字符串，保留精度）；空 = 未拿到                       |
+| `compliance.balance.currency`       | 币种（当前硬编码 `CNY`，未来 API 补 Currency 字段后透传）           |
+| `compliance.balance.reason`         | 探测失败时的原因                                                  |
+
+**关键点**：
+- 用户问「账号被冻结了吗」→ 看 `compliance.realname.verified` + `compliance.balance.available`。realname=false 或 balance ≤ 0 是常见冻结/欠费信号。
+- 用户问「余额还剩多少」→ 读 `available`，注意是**字符串**（用户可能拿 `-45.20` 表示欠费），不要 float 解析。
+- 用户问「怎么实名」→ 引导 `https://console.volcengine.com/account`（用户手动操作，本 CLI 不注册实名流程）。
+
+### ③ Permissions（IAM 系统预置策略）
+
+**核心：主账号短路**。`identity.is_root=true` 时 CLI 视为已授权，不再调 IAM API（跟 maasfe `useIamPolicyAuthorize` `userId === 0` 逻辑对齐）。
+
+| 字段                                                | 含义                                                               |
+|-----------------------------------------------------|--------------------------------------------------------------------|
+| `permissions.iam_system_policies.main_account`      | 是否主账号 —— **true 时其余字段的语义降级为"不适用"**            |
+| `permissions.iam_system_policies.authorized`        | 归一化布尔 == (main_account \|\| len(attached) > 0)              |
+| `permissions.iam_system_policies.attached`          | 已挂载且命中的 Ark 4 预置策略名列表（顺序稳定）                     |
+| `permissions.iam_system_policies.missing`           | 未命中的 Ark 预置候选（agent 建议可挂哪些）                          |
+| `permissions.iam_system_policies.total_attached_count` | 用户挂的**全部**策略数（含自定义）                                |
+| `permissions.iam_system_policies.guide_url`         | 无 Ark 策略时的控制台入口（IAM 系统预置策略页）                     |
+| `permissions.iam_system_policies.reason`            | UserName 缺失 / IAM 报错时的原因                                    |
+| `permissions.iam_system_policies.note`              | 当 `attached=[]` 且 `total_attached_count>0` 时给的自定义策略提示    |
+
+**Ark 4 个系统预置策略**（按权限从高到低）：
+- `ArkFullAccess` —— 完全访问
+- `ArkStandardGlobalAccess` —— 标准
+- `ArkReadOnlyAccess` —— 只读
+- `ArkExperienceAccess` —— 体验
+
+**Agent 消费提示**：
+- 一行判断：`main_account || len(attached) > 0` = 有 Ark 权限
+- `attached=[]` 且 `total_attached_count>0`：用户可能挂了自定义策略允许 ark 操作，本 check 覆盖不到，**不要断言"没有 Ark 权限"，转而说"未命中 Ark 系统预置策略，可能通过自定义策略授权，请对照 iam:ListAttachedUserPolicies 或控制台策略详情验证"**。
+- `attached=[]` 且 `total_attached_count=0`：确认无 Ark 权限，引导用户去 `guide_url` 挂系统预置策略（**不强制跳转 Modal，仅提示**——与 maasfe 一致）。
+- `reason` 非空：可能是子账号但 UserName 缺失、IAM API 4xx（授权不足自己看自己）、网络错。按 reason 文案分流。
+
+### ④ Ecosystem（VMP + TOS）
+
+推荐云产品依赖检查。VMP 三段（订阅 / 授权 / 工作区）+ TOS 开通。
+
+#### VMP（`ecosystem.vmp`）
+
+Precheck 短路语义：**第一步不过就不查第二步**，各字段布尔反映的是"检测到的状态"而不是"是否通过"—— agent 看 `type` 字段定夺。
+
+| 字段                              | 含义                                                              |
+|-----------------------------------|-------------------------------------------------------------------|
+| `ecosystem.vmp.ok`                | 归一化布尔 == (type == "" 即 PrecheckTypeOK)                       |
+| `ecosystem.vmp.enabled`           | VMP 订阅是否已开通                                                 |
+| `ecosystem.vmp.cross_service_auth`| Ark 跨服务授权（IAM `CheckServiceLinkedRole ServiceName=ark`）      |
+| `ecosystem.vmp.workspace_bound`   | ark telemetry 是否已绑定 VMP workspace                             |
+| `ecosystem.vmp.workspace_id`      | 已绑定的 workspace UUID（`ok=true` 时非空）                         |
+| `ecosystem.vmp.type`              | 状态类型（见下）                                                   |
+| `ecosystem.vmp.guide_url`         | 云产品开通页跳转（`LinkOpenMgmtCloudProduct`）                      |
+| `ecosystem.vmp.hint`              | 具体引导文案（中文，可直接给用户看）                                |
+| `ecosystem.vmp.reason`            | VMP service 不可用 / 网络错时的原因                                 |
+
+**`type` 值域**：
+- `""` / `vmp_ok` —— 三段全通过，`ok=true`
+- `vmp_not_open` —— 订阅未开通（enabled=false）
+- `vmp_slr_missing` —— 订阅通过但跨服务授权缺失（enabled=true, cross_service_auth=false）
+- `vmp_workspace_unbound` —— 前两段通过但 workspace 未绑（enabled=true, cross_service_auth=true, workspace_bound=false）
+
+**Agent 消费提示**：
+- `type=vmp_not_open` / `vmp_slr_missing` → 用户必须去控制台勾条款，CLI 无法代做，直接给 `guide_url`
+- `type=vmp_workspace_unbound` → 引导用户跑 `arkcli doctor infer-endpoint <id> --auto-bind` 或 `arkcli doctor model <name> --auto-bind`（这两个 scope 支持自动绑定；`doctor account` 本 scope 不做 mutate）
+
+#### TOS（`ecosystem.tos`）
+
+`GetAccountStatus` 一次拿开通状态。与 maasfe 云产品开通管理页 TOS 状态判定同源。
+
+| 字段                        | 含义                                                                                |
+|-----------------------------|-------------------------------------------------------------------------------------|
+| `ecosystem.tos.status`      | TOS 原状态值 —— `Activated` / `NonActivated` / `Stopping` / `Closed` / `Terminate` |
+| `ecosystem.tos.activated`   | 归一化布尔 == (status == "Activated")                                               |
+| `ecosystem.tos.guide_url`   | 未开通时的控制台入口（云产品开通页）                                                 |
+| `ecosystem.tos.reason`      | 探测失败时的原因                                                                    |
+
+**Agent 消费提示**：
+- `activated=true` → 一切 OK
+- `activated=false` + `status=NonActivated` → 未开通，用 `guide_url` 引导用户开通
+- `activated=false` + `status=Stopping|Closed|Terminate` → 欠费 / 已销户，**不同于未开通**，需要用户去处理账户状态（引导控制台账户中心而不是开通页）
+- `activated=false` + `status=""` + `reason` 非空 → 查询失败，可能是权限 / 网络，按 reason 文案分流
+
+## 常见 Finding → 修复路径
+
+| Finding                                              | 严重度 | 修复方向                                                                              |
+|------------------------------------------------------|--------|---------------------------------------------------------------------------------------|
+| `identity.ok=false`                                  | fail   | 未登录 / SSO 过期 → [`arkcli-auth`](../../arkcli-auth/SKILL.md) 走 `arkcli auth login` |
+| `compliance.realname.verified=false`                 | fail   | 未实名，控制台完成实名后重跑                                                            |
+| `compliance.balance.available` 为负 / 明显不足          | warn   | 欠费或余额不足，控制台充值                                                              |
+| `permissions.iam_system_policies.authorized=false` + `total_attached_count=0` | fail | 子账号无任何 Ark 策略，引导 `guide_url`（IAM 系统预置策略页）挂 `ArkFullAccess` 或最小 `ArkReadOnlyAccess` |
+| `permissions.iam_system_policies.authorized=false` + `note` 非空 | warn | 用户挂了自定义策略但本 check 覆盖不到，建议对照 IAM 详情验证自定义策略是否含 ark 操作     |
+| `ecosystem.vmp.type=vmp_not_open`                    | fail   | 用户去 `guide_url` 开通 VMP 订阅（勾同意条款）                                          |
+| `ecosystem.vmp.type=vmp_slr_missing`                 | fail   | 用户去 `guide_url` 授权跨服务访问（VMP SLR）                                          |
+| `ecosystem.vmp.type=vmp_workspace_unbound`           | warn   | 加 `--auto-bind` 走 `doctor infer-endpoint / model`；或控制台手动绑 workspace          |
+| `ecosystem.tos.status=NonActivated`                  | fail   | 生视频 / 存储回调依赖 TOS，用户去 `guide_url` 开通                                     |
+| `ecosystem.tos.status=Stopping/Closed/Terminate`     | fail   | 欠费或销户，控制台账户中心处理；开通页也无法直接恢复                                     |
+
+## 给用户看的话术
+
+1. **一句话结论**：账号是否 ready ——「身份 OK + 实名 + 余额充足 + Ark 权限 + VMP 三段 + TOS」6 个"是/否"。
+2. **关键问题**：摘 fail 级的 finding，一次说一个。多个 fail 同时命中时按 `identity → compliance → permissions → ecosystem.vmp → ecosystem.tos` 顺序引导用户修（前面不通谈后面没意义：未登录谈实名没意义；无 Ark 权限谈 VMP 精度没意义）。
+3. **修复动作**：CLI 层能修的只有 `doctor infer-endpoint/model --auto-bind` 那一个"自动绑 workspace"场景；其余（实名 / 挂 IAM 策略 / 开通 VMP / TOS）都必须去控制台。**给用户看 URL 前先说明控制台会做什么，让用户预期知情**。
+4. **下一步**：修完让用户重跑 `arkcli doctor account` 确认闭环；6 段全绿再引导跑 `doctor model` / `doctor infer-endpoint` 深入业务侧。
+
+## 安全与边界
+
+- **完全只读**：不 mutate 任何资源。VMP `--auto-bind` 走另外两个 scope，本 scope 不引入 mutate 分支。
+- **越权边界**：所有 API 都用当前 caller AK/SK；IAM `ListAttachedUserPolicies` 只能查 caller 自己账号；QueryBalanceAcct / GetAccountStatus / GetVerifyInfo 都是 body 空 + STS 身份推断，天然限定 caller 账号。
+- **敏感字段脱敏**：AK/SK / SSO token / apikey 明文不进 JSON 输出。IAM 自定义策略名**不枚举**（可能包含内部命名，隐私考量）。
+- **不 fail-fast**：identity 段未登录时命令仍出，其他段每个 check Reason 写明原因——onboarding 场景就是要在没登录时也能拿到诊断。
+- **主账号短路 IAM**：主账号（`is_root=true`）不发 `ListAttachedUserPolicies` 请求，与 maasfe UX 一致 + 避免 IAM 报错。
+
+## 何时 _不_ 用本 reference
+
+- 想看**装 / 网络 / 时钟 / apikey 校验** → [`scope-cli.md`](scope-cli.md)（`arkcli doctor` 默认 scope）
+- 想看**单接入点**状态 / 用量 / 配额 → [`scope-infer-endpoint.md`](scope-infer-endpoint.md)
+- 想看**跨接入点的模型整体**用量 / 配额 → [`scope-model.md`](scope-model.md)
+- 想查**某个错误码含义** → `doctor error <code>` → [`error-codes.md`](error-codes.md)
+- 想**登录 / 切 profile / 生成 apikey** → [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md)
+
+## 参考
+
+- [`../SKILL.md`](../SKILL.md) — 总入口与路径决策
+- [`scope-cli.md`](scope-cli.md) — CLI 健康检查（默认 scope）
+- [`scope-infer-endpoint.md`](scope-infer-endpoint.md) — 单接入点诊断
+- [`scope-model.md`](scope-model.md) — 单模型诊断
+- [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md) — 登录 / 认证管理
+- [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) — 共享执行协议

package/skills/arkcli-doctor/references/scope-cli.md

@@ -0,0 +1,217 @@
+# `arkcli doctor`（CLI 健康检查，默认 scope）
+
+> 这是 [`arkcli-doctor`](../SKILL.md) 的 **CLI scope reference**。当用户/Agent 遇到「刚装 arkcli 能用吗 / 命令突然报错跑不通 / 联通性异常 / 未登录跑不了 / 版本旧不旧」这类**环境/客户端本身**问题时读这里。
+>
+> **CRITICAL — 开始前 MUST 先用 Read 工具读取**：
+> - [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)（认证闸门、命令选择顺序）
+> - [`../SKILL.md`](../SKILL.md)（doctor 总入口与路径决策表）
+
+## 它解决什么
+
+`arkcli doctor`（无参调用）一次性把「这台机器上的 arkcli 现在能不能用」答清楚——本地二进制版本、能不能拉到 registry 的最新版、能不能解析并握手到 Ark 数据面、系统时钟对不对、当前 profile 有没有可用凭证，以及**本地存的 apikey 服务端仍是否可用 + profile 是否过期**（configuration 段会主动拉服务端最新 apikey 列表跟本地对比）。
+
+| 用户场景 | Agent 跑什么 |
+|----------|-------------|
+| 「刚装 arkcli 能用吗」                                    | `arkcli doctor`（无参） |
+| 「命令突然报错跑不通」                                    | 同上——先做环境四段体检（installation / connectivity / auth / configuration） |
+| 「显示未登录 / InvalidTimestamp」        | 同上（时钟偏差在 connectivity 段、凭证状态在 auth 段） |
+| 「网络能通吗 / 走不走代理有关系吗」                        | 同上（DNS/TCP/TLS 都在 connectivity 段） |
+| 「装的是不是最新版」                                      | 同上（installation.latest_version） |
+| 「我的 apikey 还有效吗 / 服务端删了没 / 套餐过期了没」     | 同上（configuration 段发 API 拉服务端 apikey 列表对比本地） |
+| 「账号权限 / 模型开通 / 接入点状态 / 用量」               | ❌ **不属于本 scope**——跳到 `doctor account` / `doctor model` / `doctor infer-endpoint` |
+
+## 边界：不做什么
+
+- **不查业务侧状态**（账号权限 / 模型开通 / 接入点存活 / 用量 / 配额）——这些走同族其他 scope。
+- **不改任何配置**——只读体检；发现未登录只给 hint（`arkcli auth login`），不替按。
+- **不下载升级**——`latest_version.up_to_date=false` 只提示，安装动作由用户执行 `npm install -g @volcengine/ark-cli`。
+- **不查代理 / 网卡明细**——只做端到端 DNS+TCP+TLS 三级探测，具体网络拓扑排查交给用户/运维。
+
+## 硬约束：connectivity ≠ auth，不许混
+
+> [!WARNING]
+> **网络联通性和登录状态是两件独立的事，不许互推**。这是本 skill 最容易被 agent 误伤的点，MUST 严格遵守：
+>
+> - `connectivity.*` 只回答「DNS 解析成没成 / TCP+TLS 握手到没到目标网关 / 服务端时钟对得上不」——**跟当前 profile 有没有凭证、AK/SK 对不对、apikey 服务端是否 active 完全无关**。
+> - `auth.*` 才是「有没有登录 / 什么方式登录 / 凭证在不在」，纯本地判 `~/.arkcli/config.yaml` + identity store，不发任何 API 调用。
+> - `configuration.api_key` 才是「服务端是否仍认可这个 key」，走 `ListApiKeys` 在线校验。
+>
+> 三段独立、并行、都会出结论——所以只要用户问「网络通吗 / 能不能连上方舟」，答案 MUST 只从 `connectivity` 段读，一个字都不许提「你没登录」「凭证过期」这类话。
+>
+> **严禁的错误路径（agent 曾经踩过的坑）**：
+>
+> - ❌ 用户问「网络通吗」→ agent 跑 `curl -o /dev/null -w "%{http_code}" https://ark.cn-beijing.volces.com` → 拿到 `401` → 结论「网络可达但未登录」
+>
+>   → 这是**双重错误**：
+>     1. 裸 curl 不带 Authorization 头，网关本来就会返 401——`401` 只说明「TLS 握手成了 + 网关识别我是无鉴权请求」，跟本机 arkcli 到底有没有登录**完全无关**（本机可能是 SSO / AK/SK / apikey 齐全的登录态）
+>     2. 用户问的是网络，你答的是登录——scope 错了
+> - ❌ 用户问「网络通吗」→ agent 跑 `curl` 判 HTTP 状态码 → 任何形式的『所以你需要 `arkcli auth login`』提示
+>
+>   → `arkcli auth login` 是 auth 段的修复动作，跟 connectivity 段的结论没有因果关系。
+>
+> **唯一正确姿势**：`arkcli doctor` 无参跑一次，只报 `connectivity.dns.ok` / `connectivity.tcp.ok` / `connectivity.clock_skew.ok` 三个字段的结论。用户如果**另外**问了登录状态，再从 `auth.*` 段读一次；两段不许串。
+>
+> **如果 agent 只想快速判「网络通不通」而不想跑完整 doctor**：也 MUST 走 `arkcli doctor` 而不是 curl；命令是只读的，未登录也能跑（onboarding 场景专用），比裸 curl 快不了多少却语义正确。真要 curl 探测，只允许看「TCP+TLS 是否握手成功」（e.g. `curl -o /dev/null -w "%{http_connect}\n%{http_code}\n" --max-time 5 https://ark.cn-beijing.volces.com`），**HTTP 状态码不许拿来解读登录状态**。
+
+## 第一步：跑诊断
+
+```bash
+arkcli doctor                              # 默认，无参
+arkcli doctor --format json                # 完整结构化 JSON（默认）
+arkcli doctor --debug 2>&1 | head -20      # 网络时序看得清
+```
+
+> 命令本身就是**只读体检**，不注册 `--dry-run`，不需要登录也能跑（onboarding 场景专用）。当前 profile 未配置时，`configuration` 段照出 `credentials_present=false` + 原因，不会 fail。
+
+## 第二步：读输出（4 段）
+
+### ① Installation（本地二进制）
+
+| 字段                        | 看什么                          | 失败/异常时                                                   |
+|-----------------------------|--------------------------------|--------------------------------------------------------------|
+| `installation.cli_version`  | 本地二进制版本（build 时注入）  | dev build 会显示 `dev`，无需担心                             |
+| `installation.latest_version.available` | 是否成功拉到 npm registry | `false` → 看 `reason`：dev build 会 skip；网络失败给具体错误 |
+| `installation.latest_version.up_to_date` | 当前版本 vs registry 最新 **仅在 `available=true` 时存在** | 缺失 → 说明 `available=false`，**不要**据此推断"要升级" |
+| `installation.path`         | 二进制绝对路径                  | 排查"跑的是哪份 binary"（PATH 覆盖 / 多版本共存）             |
+
+**latest_version.up_to_date=false → 修复**：
+```bash
+npm install -g @volcengine/ark-cli
+```
+
+### ② Connectivity（端到端网络）
+
+以 active profile 的 `BaseURL` 派生 host（未配置时兜底 `https://ark.cn-beijing.volces.com/api/v3`）依次探测。**前一步失败时后一步自动跳过并标 `reason: "skipped: <前置>"`**——排查时按 DNS → TCP → clock skew 顺序看。
+
+| 字段                          | 看什么                                                                                | 失败时                                                                              |
+|-------------------------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+| `connectivity.endpoint`       | 探测**派生源**（完整 URL 回显当前 profile 的 base_url）                             | —                                                                                  |
+| `connectivity.probe_target`   | **实际探测目标**（`host:port`，如 `ark.cn-beijing.volces.com:443`）——注意 probe 只到 TLS 握手层，`/api/v3` 路径**不会**被访问 | DNS 前置失败时缺失 |
+| `connectivity.dns.ok`         | DNS 解析                                                                             | `false` → 网络 / DNS 服务器 / VPN / hosts 覆盖问题                                 |
+| `connectivity.dns.latency_ms` | 解析耗时                                                                             | 200ms+ 表示 DNS 慢，考虑换 resolver                                                |
+| `connectivity.tcp.ok`         | TCP 建连 + TLS 握手一次到位                                                          | `false` → firewall / proxy MITM / 网关不可达 / TLS 版本不匹配                     |
+| `connectivity.tcp.tls_version`| 协商到的 TLS 版本（`TLS 1.3` / `TLS 1.2`）                                          | 低于 1.2 → 客户端 / 中间设备强制降级，通常是 MITM 代理                            |
+| `connectivity.clock_skew.ok`  | **系统时钟偏差是否在 5s 阈值内**                                                     | `false` → 见下方专段                                                              |
+| `connectivity.clock_skew.direction` | 偏差方向：`in_sync`（阈值内）/ `local_ahead`（本地快）/ `local_behind`（本地慢） | agent 建议 NTP 命令时**看这个字段**，不要靠 `offset_ms` 正负号自己反推           |
+
+### ③ Clock skew（时钟偏差专段）
+
+**为什么单独讲**：Volc V4 签名（AK/SK 请求）在服务端有严格时间戳窗口校验。本地时钟偏差过大会导致：
+
+- AK/SK 签名请求全部失败：报 `InvalidTimestamp` / `SignatureDoesNotMatch`
+- JWT token 判活异常：SSO IDToken 的 `exp` claim 被本地时钟当作过期强制重登
+- TLS 握手可能失败：极端偏差下证书 `notBefore/notAfter` 校验挂
+
+这是虚拟机 / 长时间挂起的笔记本 / dev container 的高频"莫名其妙"故障根因。
+
+**修复**（`clock_skew.hint` 已按当前 OS 给出对应命令）：
+
+| 系统    | 修复命令                                                                              |
+|---------|--------------------------------------------------------------------------------------|
+| macOS   | `sudo sntp -sS time.apple.com`                                                       |
+| Linux   | `sudo chronyd -q 'server pool.ntp.org iburst'` 或 `sudo ntpdate pool.ntp.org`        |
+| Windows | 以管理员身份运行 PowerShell：`w32tm /resync`                                         |
+
+修复后重跑 `arkcli doctor` 确认 `clock_skew.ok=true`。
+
+### ④ Auth（登录状态，本地）
+
+**这一段纯本地判断**——从 `~/.arkcli/config.yaml` + `~/.arkcli/identity_store/` 派生，不发任何 API 调用。未登录场景也会正常输出。
+
+| 字段                       | 看什么                                       |
+|----------------------------|---------------------------------------------|
+| `auth.logged_in`           | 是否持有可用凭证（等价于 `auth_method != "none"`） |
+| `auth.auth_method`         | 认证类型：`sso` / `aksk` / `apikey` / `sts` / `none`（**系统规范**，与 `core.CliConfig.AuthMethod()` 同源，跨命令一致） |
+| `auth.credential_state`    | ⚠️ **CLI scope 独有字段**（不是 arkcli 全局规范）：`active`（有凭证）/ `expired`（SSO 过期）/ `absent`（从未登录 / 已 logout）/ `unknown`（cfg 加载失败）—— 用于避免 agent 靠 reason 字符串推子状态。**不要**拿到别的 arkcli 命令的输出里做联合查询。 |
+| `auth.reason`              | `logged_in=false` 时的原因                    |
+
+**按 credential_state 修复**：
+
+- `active` → 无需处理
+- `expired` → SSO token 过期，跳 [`arkcli-auth`](../../arkcli-auth/SKILL.md) 走 `arkcli auth login` 刷新
+- `absent` → 从未登录或已 logout，同样跳 `arkcli-auth`
+- `unknown` → cfg 加载失败（`reason` 里给具体原因），先解决配置文件问题再重试
+
+### ⑤ Configuration（profile 校验，**在线**）
+
+**这一段发 API 调用**——拉服务端最新 apikey 列表跟本地 profile 存的对比，同时读 `profile.ExpiresAt` 判套餐/席位过期。未登录/无 invoker 时降级为 `verified=false`，不阻塞其他段。
+
+| 字段                              | 看什么                                       |
+|-----------------------------------|---------------------------------------------|
+| `configuration.profile`           | 当前 active profile 名（Config 未加载时为空串） |
+| `configuration.profile_expires_at`| 套餐 / 席位到期时间戳（Unix 秒；`0` = 未知/永不过期） |
+| `configuration.profile_expired`   | profile 是否已过期（`ExpiresAt > 0 && now > ExpiresAt`） |
+| `configuration.api_key`           | 当前 apikey 的**服务端校验**结果（未验证时字段缺失） |
+| `configuration.api_key.key_masked`| 打码后的 apikey（如 `ark-****7364`；明文不进 JSON） |
+| `configuration.api_key.status`    | `active` / `disabled` / `notfound` / `unknown`（与 `arkcli auth status` 归一化后同款） |
+| `configuration.api_key.refresh_hint` | 非 active 时的刷新命令（`arkcli profile apikey refresh`） |
+| `configuration.verified`          | 是否成功完成在线校验                          |
+| `configuration.reason`            | `verified=false` 时的具体原因                 |
+
+**verified=false 的常见原因**（一律不阻塞其他段）：
+
+- `skipped: not logged in` —— 未登录场景（auth.logged_in=false），已经在 auth 段告诉用户要 login
+- `skipped: invoker unavailable: <原始 err>` —— cfg 加载 OK 但 ArkInvoker 构造失败，罕见
+- `no api key to validate (auth_method=sso)` —— 登录方式非 apikey 且 profile 里没缓存 apikey
+- `describe status: <原始 err>` —— 打到 ListApiKeys 失败（网络/权限）
+
+**按 api_key.status 修复**：
+
+- `active` → 无需处理
+- `disabled` → 本地 key 在服务端已被停用 → `arkcli profile apikey refresh` 拉最新 active key
+- `notfound` → 本地 key 在服务端已删除（key rotation / user 手动删）→ 同上 `arkcli profile apikey refresh`；仍不行走 `arkcli auth apikey` 重选
+- `unknown` → 服务端匹配上但状态字段异常，先 `arkcli auth status` 看详情
+
+**按 profile_expired 修复**：
+
+- `false` → 无需处理
+- `true` + Agent/Coding Plan 用户 → 引导控制台续订套餐
+- `true` + platform 用户 → 一般不会命中（platform profile 无 ExpiresAt），检查 profile 是否被误改
+
+> **敏感字段脱敏**：`arkcli doctor` 输出**不会**回显 AK/SK / token 明文；apikey 只出 masked（`ark-****xxxx`）。如果用户拿输出问"怎么这个字段没出来"，就是**因为脱敏，不是 bug**。
+
+## 常见 Finding → 修复路径
+
+| Finding                                                | 严重度 | 修复方向                                                                              |
+|--------------------------------------------------------|--------|---------------------------------------------------------------------------------------|
+| `installation.latest_version.up_to_date=false`         | info   | `npm install -g @volcengine/ark-cli` 升级；旧版可能缺失近期修复                       |
+| `installation.latest_version.available=false`（非 dev build）| warn   | 网络到 npm registry 不通；影响升级检查但不影响 CLI 使用                              |
+| `connectivity.dns.ok=false`                            | fail   | DNS 挂：排查 `/etc/resolv.conf`、VPN、hosts 覆盖；换 8.8.8.8 试试                    |
+| `connectivity.tcp.ok=false`（DNS 通）                  | fail   | TCP/TLS 挂：查 firewall、proxy 是否 MITM、公司网关是否阻断 volces.com                 |
+| `connectivity.tcp.tls_version` < TLS 1.2               | warn   | 中间设备做 TLS 降级；找运维检查企业出口代理                                           |
+| `connectivity.clock_skew.ok=false`                     | fail   | 按 `hint` 里的平台命令同步 NTP；不修则 AK/SK 请求会持续报签名类错误                   |
+| `auth.logged_in=false`（credential_state=expired）     | fail   | SSO 过期，跳 [`arkcli-auth`](../../arkcli-auth/SKILL.md) 走 `arkcli auth login` 刷新  |
+| `auth.logged_in=false`（credential_state=absent）      | fail   | 从未登录 / 已 logout，跳 `arkcli-auth` 登录                                          |
+| `configuration.api_key.status=disabled`                | fail   | 本地 apikey 被停用 → `arkcli profile apikey refresh`                                    |
+| `configuration.api_key.status=notfound`                | fail   | 本地 apikey 服务端已删 → `arkcli profile apikey refresh`；仍不行 `arkcli auth apikey` 重选 |
+| `configuration.profile_expired=true`                   | fail   | 套餐/席位到期，控制台续订                                                             |
+| `configuration.verified=false` + `reason=describe status: <err>` | warn   | 服务端 ListApiKeys 打不通（网络/权限），一般是临时故障，重试即可                     |
+
+## 给用户看的话术
+
+1. **一句话结论**：CLI 是否可用 —— 拆成"网络通了 + 时钟正常 + 已登录 + apikey 服务端仍有效"四个"是/否"。
+2. **关键问题**：摘 fail 级的 finding，一次说一个。多个 fail 同时命中时按 `connectivity → auth → configuration → installation` 顺序引导用户修（前面 block 掉后面：网络挂了谈登录没意义；未登录谈 apikey 校验没意义）。
+3. **修复命令**：**先给用户看、等确认**再让用户执行。特别是 `sudo` 类命令必须让用户明确同意；`arkcli profile apikey refresh` 也一样先展示等确认。
+4. **下一步**：修完让用户重跑 `arkcli doctor` 确认闭环；确认没问题后再引导他们跑真实业务命令（`doctor account` / `doctor model` / 等）。
+
+## 安全与边界
+
+- **本地为主，在线校验只调 apikey 列表**：installation / connectivity / auth 三段全本地；configuration 段发一次 `ListApiKeys` 拉服务端最新列表。不消耗推理 token，不发业务请求。
+- **越权边界**：DNS / TCP / TLS / HEAD 都是端到端标准协议探测；apikey 校验用当前 profile 已有的凭证签名，只读 caller 自己的 key 池，不跨账号。
+- **敏感字段脱敏**：AK/SK / SSO token 明文不进 JSON 输出；apikey 只出 masked（`ark-****xxxx`）。
+- **不 fail-fast**：未配置时命令仍能出结果——onboarding 场景就是要在没登录时也能拿到诊断。
+
+## 何时 _不_ 用本 reference
+
+- 想看**账号/模型/接入点**业务侧状态 → `doctor account` / `doctor model <name>` / `doctor infer-endpoint <ep-id>`（各自的 scope reference）
+- 想**登录 / 切 profile / 查身份** → [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md) / [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md)
+- 想**装 / 升级 CLI** → 直接 `npm install -g @volcengine/ark-cli`（不需要 doctor）
+- 想查**某个错误码含义** → `doctor error <code>`（→ [`error-codes.md`](error-codes.md)）
+
+## 参考
+
+- [`../SKILL.md`](../SKILL.md) — 总入口与路径决策
+- [`scope-infer-endpoint.md`](scope-infer-endpoint.md) — 单接入点诊断
+- [`scope-model.md`](scope-model.md) — 单模型诊断
+- [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) — 共享执行协议
+- [`../../arkcli-auth/SKILL.md`](../../arkcli-auth/SKILL.md) — 登录 / 认证管理