@volcengine/ark-cli-darwin-arm64 0.0.0-stage → 1.0.46-prerelease.46bd0d6dcc58

package/skills/arkcli-auth/references/api-key-query.md

@@ -0,0 +1,74 @@
+# API Key：查询、导出与注入
+
+先读 [共享协议](../../arkcli-shared/SKILL.md)。这里只处理用户明确要求的 Key 任务，不是所有业务命令的前置步骤；宿主对凭证与授权的限制始终优先。
+
+## 1. 元数据查询不改变当前 Key
+
+- “有哪些 Key / 谁的 Key / 哪把 Key 有用量”先用 `arkcli api apikey.list --params '{"PageSize":100}' --page-all --format json`，按实际 envelope 的 `Items` 读取 Id、名称、掩码、状态与 Project 等字段；检查分页完整性。
+- 账户 Key 列表不是 Profile 本地库存。不要用会选 Key 并写凭证的 `auth apikey` 代替 list，也不要为只读查询自动执行 `profile apikey refresh/use`。
+- `Key` 的掩码不能用作推理凭证，不能去掉星号或拼后缀“还原”。用户给名称/后缀时只在真实结果中匹配；0 个说明未找到，多个需要消歧，不取第一条。
+- 普通 Key 池、个人 Agent Plan 专属池、团队席位 Key 不是同一个池；普通列表有 Key 不证明 Plan Key 已就绪。
+- “最近使用哪把 Key”以本轮完整列表的 `LastAccessTime` 为依据，解析日期及其时区后比较最大值，保留并列候选；空值、无效日期与分页不完整都须明确说明。不能用第一项、名称中时间或 `CreateTime` 代替，也不能把某个候选叫作用户在外部客户端实际配置的 Key。
+- `auth status` 的选中 Key 只证明当前 ArkCLI 配置；`Active` 只证明管理状态；一次获准的试调用成功只证明该次 URL、协议、Key、模型与输入组合。用户原客户端的配置未知时，分别交付已验证的组合与待核对项，不声称已证明用户故障的根因；不能为消除这种未知而自动切换/轮换 Key。
+- 状态统计必须从完整结构化结果聚合；`TotalCount` 与截断输出中的若干 `Active` 项不能推出“全部启用”。完整结果留在当前运行域内，只交付数量、状态分布和相关精简元数据；读取不完整时报告已核实范围。
+- 方舟 API Key 池与豆包语音 App ID / Access Token / 对应服务的 API Key 是不同身份契约。只能按具体产品、接口及官方版本说明核验适用凭证，不能从“新版支持 API Key”推导为“本账号这把方舟 Key 可直接用于语音”。
+
+### 大列表：精简同一条记录，不手工拼字段
+
+终端预览截断或只显示最近若干项时，读取工具已保存的完整输出，或在受控进程内重新完整查询并立即投影。先按用户指定的真实名称/用途定位数字 `Id`；同名多条要消歧，不默认选最近一条。下面的 `key_id` 必须来自已读记录，`skill_dir` 是当前安装的 `arkcli-auth` 目录绝对路径；先确认环境有 `jq`。调用前补齐共享归因环境。
+
+```bash
+set +x
+# 仅查询与投影；不导出明文、不切换当前 Key。pipefail 确保 CLI 失败不会被管道掩盖。
+set -o pipefail
+arkcli api apikey.list --params '{"PageSize":100}' --page-all --format json |
+  jq -ec --arg id "$key_id" -f "$skill_dir/scripts/key-metadata.jq"
+```
+
+该模板校验 `Result.Items` 数量等于 `TotalCount`、数字 Id 唯一且可精确表示，输出全量状态分布和目标记录的 Id/SID/Name/ProjectName/Status/LastAccessTime/AccessControlInfo；不输出 `Key`。`missing_fields` 中的字段保持未知。投影失败时检查原始非敏感错误或用支持精确整数的解析器，不能手抄截断内容补齐。
+
+报告中的 SID、名称和权限都从这一个 `selected` 对象原样取值，不把名称中的日期与另一项 SID 后缀拼接，不从相邻 Key 或当前 Profile 补 Project/权限。`ProjectName` 是所属项目，不能单独证明访问“全部资源”；权限只按该条 `AccessControlInfo` 的实际语义说明，字段缺失就未核实。完整状态统计中存在未知或非 Active 项时不能说“全部启用”。
+
+## 2. 用户明确需要凭证时
+
+先确认精确目标和用途：当前 Profile 的 Key、某个账户 Key，还是注入已授权的客户端。不要从“列 Key”自动扩张成全量明文导出。
+
+- 当前 Profile 已存的 Key 有产品入口 `arkcli profile apikey get [--profile <name>] [--plain]`；它导出持久 Profile 凭证，不代表本次 `--api-key`/环境变量 override 的值。只在明确授权的导出/注入任务中使用。
+- 账户中指定 Key：list 定位真实数字 `Id`，再使用已注册 `apikey.get_raw`，请求字段为 `{"Id":123}`（示意 ID 不可实用）。返回的 `Result.ApiKey` 才是明文；不能把 `Id`、`KeyID`、`SID` 或名称混用。
+- `get_raw` 若返回可选的 `Result.SID`，与同一 Id 的 list 记录交叉核对；不一致时停止交付并核查目标，缺失时不能另造 SID。仅做元数据查询时不为补 SID 调用明文接口。
+- 当前 registry 提供 `apikey.get_raw` 和 `apikey.get_sid`，不要发明 `apikey.get` 作为替代。`get_sid` 是持有 ApiKey 后反查 SID/Project/状态，不是凭 Id 取明文；两者输入和返回值不同。先核对当前 `api --list`，不能用相似 Action 名碰撞。
+- `get_raw` 属于敏感凭证访问，个人 Plan 可能触发协议/Access 闸门；明确拒绝或状态不可确认时停止，不改走文件、另一 Action 或另一身份绕过。
+- 遵守共享“不输出完整凭证”的交付边界：明文只进入用户授权的配置/安全目标，不进入聊天、debug、临时报告、命令展示或版本库；反馈只写目标、名称/后缀和完成状态。宿主不允许导出时如实说明。
+- 区分产品查询能力、当前身份权限、获准的安全交付位置与聊天披露限制；未执行或被宿主限制时说明具体边界，不把它写成“CLI没有接口/任何方式都无法读取”。安全落点尚未确定时保留元数据并确认用途，不凭空声称已经导出或向聊天贴值。
+- 明确授权批量导出时仍需锁定目标清单、权限与安全落点，记录逐项成功/失败；默认串行，不自动轮换、创建、禁用或改默认 Key。
+
+## 3. 下游注入
+
+优先让 ArkCLI/Helper 按选定 Profile 自行消费凭证，不手工转抄。确需外部客户端时，在同一受控进程内取值并写入已授权位置，禁止 `set -x`、echo Key 或将秘密展开成可见命令；失败只报告非敏感摘要。
+
+**交付保真。** 将捕获响应中 JSON 解码后的完整 `Result.ApiKey` 直接交给目标写入器；不让模型根据前缀、掩码、长度或记忆重写，不截取成固定长度、不补字符、不删除值内部的连字符或空白。配置写入后，在同一受控进程内按目标格式回读并解码凭证字段，与原值逐字节比较；报告只输出是否相等、长度及安全落点，不输出明文。同长度、同前缀或文件存在都不能代替完整值一致。
+
+若不一致，交付尚未完成：在原授权目标内复用已捕获原值修复本地写入并再次比较，不重新创建 Endpoint、重新导出或轮换 Key。原值缺失、目标不可回读或宿主禁止导出时保留“未验证/未完成”，说明具体限制；不能凭日志中的片段补出一把看似完整的 Key。安全交接不等于客户端已加载或调用成功，后两者按实际证据分别报告。
+
+导出/注入与轮换完全不同：查询失败不意味着需要重置 Key，读取明文不意味着旧 Key 失效，配置写入成功也不证明下游已加载或可调用。需按目标客户端核验，不能默默更换费用主体。
+
+### 获准后、同一受控进程内的解析模板
+
+仅当宿主允许导出、用户已指定 Key 与安全落点，且不能通过 Helper 直接交接时采用。下面只描述取值步骤，**不是业务调用前置检查**：
+
+```bash
+set +x
+# key_id 来自已完整读取的 list；是数字 Id，不是掩码、名称或 SID
+key_params=$(jq -ecn --argjson id "$key_id" 'select(($id|type)=="number" and $id>0 and ($id|floor)==$id) | {Id:$id}') || exit 1
+# 实际调用前补齐共享协议要求的归因环境；不加 --debug
+key_response=$(arkcli api apikey.get_raw --params "$key_params" --format json) || exit 1
+resolved_key=$(printf '%s' "$key_response" | jq -er '.Result.ApiKey | select(type=="string" and length>0 and (contains("*")|not))') || exit 1
+# 只在此进程内交给已经获准的客户端/配置写入器；不 echo、不列进 argv 或报告
+# 按目标格式回读并精确比较完整值；不相等则仅修复本地交接，不报告成功
+# 完成交接后立即清理进程变量
+unset resolved_key key_response key_params
+```
+
+模板中的 handoff 步骤必须使用目标客户端真实接口，不能在清理变量后声称已注入。超出 JSON 工具可精确表达范围的数字 Id 使用支持精确整数的编码器，不能舍入后查询另一条记录。禁止用 `tr -d '"'` 代替 JSON 解码；非零退出、空值或掩码值均为失败，不暴力换 Id。
+
+批量导出只遍历用户批准的真实 Id 清单、默认串行；每项记录 Id/成功或失败/安全落点，不能把所有明文汇总进对话。交付前核对清单完整性、未改变默认 Key、秘密未进入 Trace，失败项如实报告而不轮换重试。

package/skills/arkcli-auth/references/arkcli-auth-init-volc.md

@@ -0,0 +1,58 @@
+# arkcli init-volc — 无交互环境变量引导
+
+`arkcli init-volc` 从 `VOLC_INIT_*` 环境变量无交互地生成一个火山 **platform** 类型 profile 并设为 default。用于**云开发机 / CI** 等已注入凭证的场景:外部把 STS / 账号 / API Key 通过环境变量注入后,一条命令即让 arkcli 处于 ready 状态,后续 arkcli / OpenCode 调用无需 SSO 登录或交互选择。
+
+## 何时用 / 何时不用
+
+- ✅ 云开发机启动后, 由注入方在写好 `VOLC_INIT_*` 后自动调用, 让机器内的 OpenCode / arkcli 开箱即用
+- ✅ CI / 自动化里已有火山 STS + ARK API Key, 想跳过交互式 SSO 引导
+- ❌ **不要**用于本地终端用户首次引导 —— 那走 `arkcli auth login`(SSO Gate 1+2)
+
+## 命令
+
+```bash
+arkcli init-volc            # 消费 VOLC_INIT_*, 零交互, 落 platform profile + 设 default
+```
+
+- 无参数(`NoArgs`), 全程**零交互**;缺必填环境变量 → 报错退出(非零 exit)
+- 幂等:同账号重跑覆盖同名 profile
+- 注入的 STS 落盘后会 best-effort 查询账号主体类型、缺失的 API Key 和 Plan；控制面查询失败只产生 warning，不阻断 platform profile 初始化
+- 该本地初始化命令不注册 `--dry-run`；执行前检查环境变量并明确确认目标 profile
+
+## 环境变量契约(`VOLC_INIT_*`)
+
+| 环境变量 | 必填 | 含义 | 缺省 |
+|---|---|---|---|
+| `VOLC_INIT_STS_ACCESS_KEY` | ✅ | 火山 STS AccessKeyId | — |
+| `VOLC_INIT_STS_SECRET_KEY` | ✅ | 火山 STS SecretAccessKey | — |
+| `VOLC_INIT_STS_SESSION_TOKEN` | ✅ | 火山 STS SessionToken | — |
+| `VOLC_INIT_ACCOUNT_ID` | ✅ | 火山主账号数字 id | — |
+| `VOLC_INIT_API_KEY` | 可选 | ARK 数据面 API Key；缺失时尝试通过控制面拉取 | 空 |
+| `VOLC_INIT_REGION` | 推荐 | region code, 如 cn-beijing | cn-beijing |
+| `VOLC_INIT_USER_ID` | 推荐 | IAM 子用户数字 id;root 留空 | 空 |
+| `VOLC_INIT_IS_ROOT` | 推荐 | 是否主账号 root:true / false | false |
+| `VOLC_INIT_USER_NAME` | 可选 | 用户名(owner_trn 展示) | 空 |
+| `VOLC_INIT_PROJECT_NAME` | 可选 | project;空 = 账号全部资源 | account-wide |
+| `VOLC_INIT_STS_EXPIRE` | 可选 | STS 过期 epoch 秒 | now+12h |
+| `VOLC_INIT_TRN` | 可选 | 真实 IAM trn;给了优先, is_root 从 `:root` 后缀推 | 按 IS_ROOT 构造 |
+
+## 落地行为
+
+- **STS** → 写 `.env` + identity store, 供控制面 V4 签名(`models` / `resources`)
+- **API Key** → profile 数据面 key, 供 `+chat` / `+gen`
+- **account_id / user_id / is_root** → 持久化为当前 active 身份, 后续命令 cfg 直接读到
+- **identity_type** → 通过 `GetVerifyInfo` 判断并写入当前 Identity Store，固定为 `individual` 或 `enterprise`
+- 产出 profile 名:`platform_<region>_<project|accountwide>`, 设为 default
+
+## 输出
+
+```json
+{"ready":true,"profile":"platform_cn-beijing_accountwide","type":"platform","region":"cn-beijing","project":"账号全部资源","identity_key":"volc-2100000001","identity_type":"enterprise","is_root":false,"has_api_key":true}
+```
+
+不回显任何凭证明文。
+
+## Agent 路由提示
+
+- 用户说"云开发机引导 / 无交互初始化 / 已注入 VOLC_INIT 怎么让 arkcli ready" → 本命令
+- 用户说"我要登录 / 首次配置 / 选 project / 选 key" → `arkcli auth login`(见 [`arkcli-auth-login.md`](arkcli-auth-login.md))

package/skills/arkcli-auth/references/arkcli-auth-login.md

@@ -0,0 +1,125 @@
+# auth login
+
+## 推荐顺序
+
+交互式（推荐）：
+
+```bash
+arkcli auth login
+```
+
+明确指定方式时：
+
+```bash
+arkcli auth login volc-sso                                      # 火山 SSO (浏览器)
+arkcli auth login --no-browser                                  # 火山 SSO 无浏览器 (TTY 交互 / 非 TTY 出 Phase 1)
+arkcli auth login --no-browser --code <授权码>                  # 无浏览器 Phase 2 (agent/沙箱喂码完成登录)
+```
+
+> **0.1.16 暂关 AK/SK 登录通道**：`--access-key/--secret-key` flag 已注释、交互菜单也移除了 "AK/SK" 选项。CI / 自动化 / agent / 沙箱场景请改用 `arkcli auth login --no-browser`（见下方「无浏览器两段式」）。**`--no-browser` / `--code` 由 `auth login` 注册并可被 `volc-sso` 继承；也支持 `auth login volc-sso --no-browser`。** AK/SK 通道恢复将在后续版本同步更新本文档。
+
+## 无浏览器两段式跨进程 flow（agent / 沙箱 / CI 必读）
+
+**根因**：老 `--no-browser` 是单进程交互式 —— 打印 URL 后当场 `阻塞读 stdin` 等你粘授权码。agent / 沙箱里每条命令是独立短命进程，stdin 不是真人终端（常是 `/dev/null`），`读 stdin 立刻 EOF`，进程在拿到授权码前就崩（`读取授权码失败: EOF`）。解法是把单进程拆成**两段跨进程命令**，中间用一次性落盘 session 接力 PKCE（对齐 lark-cli `auth login --no-wait` / `--device-code` split-flow）。
+
+> ⚠️ **两段必须在同一运行环境执行**：Phase 1 把 `code_verifier`+`state` 落到 `~/.arkcli/.sso-pending.json`，Phase 2 靠读这个文件接力。**两条命令必须共享同一 `HOME` / 同一持久化卷**（同一容器 / 同一开发机）。若无状态调度把两步派到不同 worker、不同容器或不同 `HOME`，Phase 2 找不到 pending 会报「没有待完成的…会话」。
+
+**CLI 按 stdin 是否 TTY 自动分流，agent 无需判断**：
+
+```text
+arkcli auth login --no-browser [--code X]
+  ├─ 有 --code X ──────────► Phase 2: 读盘换 token + 激活（须与 Phase 1 同一 HOME）
+  └─ 无 --code
+       ├─ 非 TTY(agent/沙箱) ► Phase 1: 出 URL + 落盘 PKCE/state + 立即退出（不读 stdin）
+       └─ 是 TTY(真人) ──────► 一条命令交互式（打印 URL → 当场粘贴），行为同旧版
+```
+
+> `--code` **必须与 `--no-browser` 一起用**（它只是无浏览器 Phase 2 的喂码入口）；单独写 `auth login --code X` 会报 `--code 仅在 --no-browser 模式下有效`。
+
+**agent 执行步骤**：
+
+1. **Phase 1** —— 跑 `arkcli auth login --no-browser`。stdout 是结构化 JSON：
+   ```json
+   {"stage":"authorize_pending","method":"sso_no_browser",
+    "authorize_url":"https://signin.volcengine.com/authorize/oauth/authorize?...",
+    "next_command":"arkcli auth login --no-browser --code <授权码>","expires_in_sec":600}
+   ```
+   把 `authorize_url` **原样**转发给用户（不要改写/编解码），请他在任意设备浏览器完成 SSO，复制页面显示的 **base64 授权码**回来。命令已退出（exit 0），不会挂住。
+2. **Phase 2** —— 拿到授权码后跑 `arkcli auth login --no-browser --code <授权码>`（`--code` 必须连 `--no-browser`，且与 Phase 1 同一 `HOME`）。CLI 读 Phase 1 落盘的 `~/.arkcli/.sso-pending.json`（含 PKCE `code_verifier` + `state`）换 token、激活身份、删盘。成功后输出 `{"auth_method":"sso_no_browser","path":"..."}`。
+
+**出错恢复（先看 pending 还在不在，再决定重跑 Phase 1 还是重试 Phase 2）**：
+
+| 报错 | pending 状态 | 怎么办 |
+|------|-------------|--------|
+| 会话过期（超 `expires_in_sec`，TTL 默认 10min） | 已被清 | **重跑 Phase 1** 拿新 URL |
+| `没有待完成的…会话` / pending 不存在（含 Phase 1、2 不在同一 HOME） | 无 | **重跑 Phase 1**（并确保两段同一 HOME） |
+| `base64 解码失败` / `state 不匹配(CSRF)` / token 交换失败 | **仍在盘** | **TTL 内直接重试 Phase 2**：纠正后重跑 `--code`——贴对当前 `authorize_url` 的码；token 交换瞬时失败可让用户从**同一 authorize_url** 重新授权拿新码（PKCE/state 仍有效，**无需**重跑 Phase 1） |
+
+> `state 不匹配(CSRF)` 最常见原因是粘了**上一轮 / 别处** authorize_url 的码，不是攻击；pending 未删，粘当前这轮的码重试 Phase 2 即可。真疑似被注入时再手动重跑 Phase 1 换全新会话。
+
+**其它**：
+- 凭证可移植仍可用：有浏览器的机器登录后把 `~/.arkcli/` 拷进沙箱复用，与两段式互补。
+
+## 说明
+
+- `volc-sso` 适合火山方舟交互式开发
+- `--no-browser` 是真正的 cross-device 流（对齐 volcengine-cli `ve login --remote`）：
+  - CLI 不监听任何端口
+  - 用户在 **任意设备**（手机/远程电脑/平板）浏览器打开 authorize URL
+  - 完成登录后，浏览器页面显示一段 **base64 字符串**（不是 URL，不是 6 位数字）
+  - 把这段 base64 串粘贴回 CLI 提示符 `授权码:` 处即可
+- 登录成功后凭证写入 identity store，并绑定或切换到对应 tenant 的 profile（同 tenant 重登更新当前 profile 的 identity_key；跨 tenant 登录创建以 tenant 命名的新 profile 并设为 default）
+- `arkcli auth apikey` 只用于选择普通 API Key；`arkcli auth apikey create` 只用于创建、验证并保存普通 API Key 到当前身份，非交互环境收到 `requires_confirmation` 后必须走共享 Skill 的宿主确认流程。已有 Profile 要切换默认 Key 时仍用 `profile apikey refresh/use`。这些命令都不能修复 Agent Plan 个人版专属 Key 或团队版 Running 席位 Key，普通池里有 Key 不代表 Plan profile 可用。
+- SSO 首次登录会按 profile 类型从不同来源拉 Key，并把选中的 Project 写入对应 profile：`platform` / `coding-plan` 个人版走普通池，`agent-plan` 个人版走 `Scene=RealAgentPlanPersonal`，团队版走 `GetSeatInfo.Result.ApiKey`。
+- 真人 TTY 下，普通池为空会询问是否创建一把全资源 Key；Project 使用当前具体值，账号全部资源/空值回退 `default`，名称与控制台一致为 `api-key-YYYYMMDDHHmmss`。确认后只写一次，再最多读 3 次状态；拒绝或非 TTY 时不创建。
+- Agent Plan 个人版若专属记录存在但状态非 Active（如 `Restricted`），TTY 会说明旧 Key 将立即失效并询问是否轮转。确认后只轮转一次，再最多读 3 次状态；第一轮 Active 即结束。无专属记录、仍有 Active 记录但明文不可读、拒绝或非 TTY 时不轮转。
+- 如果所选 profile 的 API Key 获取报错（例如 Agent Plan 轮转后检查 3 次仍为 `Restricted`），TTY 不再让该局部故障回滚整个 SSO：已选 region/project 保持不变，失败类型从本轮候选中移除，然后重新展示消费场景选择。失败类型不会在后续 backfill 中再次调用 fetcher；用户改选 Coding Plan/platform 时各自仍使用自己的 Key 池，不发生跨池降级。
+- 临时选择另一套已存在的上下文使用 `--profile <name>`；永久切换使用 `arkcli profile use <name>`
+- 需要重选 Project 时使用 `arkcli profile project [<name>]`。根命令不再提供 `--project-name`，`ARK_PROJECT_NAME` 也不参与运行时解析
+
+## volcengine-cli 登录态借用 (v3, 1.0.4 起, 仅火山 SSO 交互式登录)
+
+**触发条件** (三个都满足才走):
+1. 用户跑 `arkcli auth login` 交互式菜单里选**浏览器 SSO** (case 0) 或**无浏览器 SSO** (case 1); 显式 `arkcli auth login volc-sso --no-browser` 不走 (它跳过交互菜单直接进 OAuth)
+2. 本机 `PATH` 上有 `ve` 可执行 (`exec.LookPath`), `ve -v` 版本 >= `1.0.45`, `ve --help` 输出含 `ecs` 关键字 (火山官方 CLI 指纹)
+3. `ve` 已 `ve login` 且当前登录态可用 (SDK `clicreds.NewCliCredentials("", "").Get()` 返 STS 且 `sts.GetCallerIdentity()` 返 `IdentityType="User"`)
+
+**接管动作**:
+1. 复用 ve 的 STS + IAM 身份 (AccountID / UserID / Trn / UserName / IsRoot 来自 `GetCallerIdentity()` 服务端权威值)
+2. 通过 `sso.ActivateIdentity` (source=ve 分支) 落盘 arkcli identity: `identity_store/volc-<AccountID>/metadata.json` (`source="ve"` + 身份事实) + `sts.json` (STS 三元组 + expires_at_ms) + `user_id.json`; **不落 `token.json`** (arkcli 侧不再持 IDToken/refresh_token/ClientID, 这些字段由 volcengine-go-sdk 内部管)
+3. 触发 `BuildFirstProfileSet` 派生 platform / agent-plan / coding-plan profile (跟原生 SSO 一样)
+4. `.env` 只落 STS 三元组 + expires_at + user_id, **不落** `VOLCENGINE_ID_TOKEN` / `VOLCENGINE_REFRESH_TOKEN` / `VOLCENGINE_OAUTH_CLIENT_ID`
+
+**降级条件** (任一不满足即降级 arkcli 原生 SSO OAuth 流, **不阻断登录**):
+- 未装 ve / 版本 <1.0.45 / 不是火山官方 CLI (指纹校验失败)
+- ve 未登录 / login cache 缺 refresh_token / refresh_token 过期 (SDK 抛 `CliConsoleLoginRefreshTokenExpired` / `CliConfigLoginSessionMissing` 等 8 个白名单 code 之一)
+- ve 登录态是 SSO Identity Center (`IdentityType != "User"`, 语义跟 arkcli IAM 用户对不上)
+- 借用途中 `sts.GetCallerIdentity()` 网络失败 / SDK IO 异常等环境异常
+
+**跟原生 SSO 的差异对照**:
+
+| 维度 | 原生 SSO | v3 ve handoff |
+|------|---------|--------------|
+| 浏览器授权 | 需要 (每次登录) | **不需要** (借用 ve 已有 refresh_token 状态) |
+| identity_store 落盘 | `token.json` + `sts.json` + `user_id.json` + `metadata.json.source="arkcli"` | 无 `token.json`; `sts.json` + `user_id.json` + `metadata.json.source="ve"` |
+| `.env` 里 IDToken/RT/ClientID | 有 | **没有** |
+| STS refresh | arkcli 用 `token.json` 的 refresh_token 走 OIDC endpoint 换 | volcengine-go-sdk 内部持 refresh_token 自动 refresh (arkcli 侧只调 `clicreds.Get()`) |
+| `auth whoami.auth_method` | `"sso"` | `"sts"` (合法登录态, `logged_in=true`) |
+| 身份切换语义 | SSO clean-slate | 同上 (source 字段不影响 identity_key 判定) |
+
+**Agent 使用要点**:
+- 用户跑 `arkcli auth login` 后 `auth whoami` 显示 `auth_method="sts"` 时**不要**误以为是"未登录 / init-volc / AK/SK 态", 那可能是 v3 ve handoff 正常结果 — 看 `identity_store/<key>/metadata.json.source` 值区分 (`"ve"` = 借用 ve, `"arkcli"` = 原生 SSO)
+- 引导用户重登时不再需要主动说"先跑 ve login" — arkcli 会自动检测 + 降级
+- `arkcli auth logout` 只清 arkcli 自己的 identity_store, **不动 ve 的登录态** — 用户如果想彻底登出, 还需要额外跑 `ve logout`
+
+## --no-browser 跟浏览器流的 OAuth2 差异（agent 排障用）
+
+| 维度 | `volc-sso`（浏览器） | `--no-browser`（cross-device） |
+|------|-----|-----|
+| client_id | `trn:signin:::devtools/same-device` | `trn:signin:::devtools/cross-device` |
+| redirect_uri | `http://127.0.0.1:<port>/oauth/callback` | `https://signin.volcengine.com/authorize/oauth/authorize` |
+| CLI 本地端口 | 需要（callback server） | 不需要 |
+| 用户粘贴内容 | — (自动 callback) | base64 串 |
+| refresh token | 必须用 same-device client_id refresh | 必须用 cross-device client_id refresh |
+
+`.env` / identity store 都持久化了 `client_id`（`VOLCENGINE_OAUTH_CLIENT_ID` / `IdentityToken.client_id`），后续 `TryRefreshVolcToken` 会用对的 client_id 续期。**用户/agent 不应手动改这个字段**，否则 refresh 会被 server 拒（RFC 6749 §6）。

package/skills/arkcli-auth/references/arkcli-auth-status.md

@@ -0,0 +1,41 @@
+# auth status / logout
+
+## 查看状态
+
+```bash
+arkcli auth status
+```
+
+输出通常包含：
+
+- `volc_sso` 或 `aksk`（取决于当前 profile 的 tenant 和登录方式）
+- 顶层 `identity_type`：当前账号主体类型，固定为 `individual`（个人）或 `enterprise`（企业）。它是账号级事实，与 SSO / AKSK / `init-volc` 等登录方式无关
+- `volc_sso.identity`：当前火山账号身份事实（`name` / `account_id` / `trn` / `is_root`），并附带账号实名认证状态：
+  - `verified`：是否完成实名认证（`true` / `false`）
+  - 实名探测失败（网络 / STS / 权限）时 `verified` 省略（与"未探测"语义一致，绝不假报已实名/未实名）
+  - 实名是账号级事实，与 profile / project / 登录方式无关；实名是"开通模型 / 开通云产品 / 创建推理接入点"的必要前提
+- `ark_api_key`：当前缓存的 ARK API Key
+- `ark_api_key.key / status`：当前 Key 掩码值，以及与远端列表对齐后的状态
+- `status` 取值为 `active`、`disabled`、`notfound`，远端不可判断时为 `unknown`
+- `project_name`：当前生效的 ARK Project Name
+
+敏感字段会做掩码处理，不会直接打印完整 token / secret。
+
+## Project Name 排障
+
+- 如果 `project_name` 不是预期值：
+  1. 先确认本次命令由 `--profile` / `ARK_PROFILE` / `default_profile` 选中了哪个 profile
+  2. 再看该 profile 的 `project` 字段（`arkcli profile create --project <name>` 或 `arkcli profile project [<name>]` 写入）
+  3. 老 profile 没有 `project` 时，再检查 identity store / `.env` 中由 SSO 或 `auth apikey` 留下的兼容值
+  4. 都不设置时，火山默认值为 `"default"`
+- 想固定 Project：使用 `arkcli profile project [<name>]`，或创建/切换到绑定该 Project 的 profile。只想让单次命令使用另一套上下文时传 `--profile <name>`
+- 根命令不再提供 `--project-name`，`ARK_PROJECT_NAME` 也不参与运行时解析
+- 老 `arkcli config init --project-name ...` 已废弃, 不应再建议
+
+## 退出登录
+
+```bash
+arkcli auth logout
+```
+
+该命令会删除本地存储的认证信息，执行前应确认用户确实要清理凭证。

package/skills/arkcli-auth/references/arkcli-auth-whoami.md

@@ -0,0 +1,128 @@
+# auth whoami
+
+## 用途
+
+返回当前认证态的用户身份。区别于 `auth status`：
+
+| | `auth status` | `auth whoami` |
+|---|---|---|
+| 关注点 | 凭证（token / api_key / aksk）健康度 | 身份（你是谁） |
+| 输出 | 嵌套（按凭证类型分组） | 扁平（脚本友好） |
+| 主要消费方 | 排障 | Skill / 脚本过滤"我的 xxx" |
+
+## 标准命令
+
+```bash
+arkcli auth whoami
+arkcli auth whoami --transform user_id   # 直接拿 IAM 用户 ID
+arkcli auth whoami --transform name      # 直接拿用户名
+```
+
+## 输出契约（SSO 已登录）
+
+```json
+{
+  "logged_in": true,
+  "auth_method": "sso",
+  "name": "alice",
+  "user_id": "10000001",
+  "account_id": "2000000001",
+  "trn": "trn:iam::2000000001:user/alice",
+  "is_root": false,
+  "project_name": "default",
+  "region": "cn-beijing"
+}
+```
+
+字段语义：
+
+- `user_id`：IAM 用户 ID。在 ARK 各资源里以多种形态出现：
+  - 带 `sys:ark:createdBy` Tag 的资源（如 infer endpoints、自定义模型）：拼成 `IAMUser/<user_id>/<name>` 作为 Tag value
+  - API Key：火山走 `Filter.UserId` / 响应里的 `UserId` 字段
+  - usage / 已天然按账号 scope 的资源：不需要这个字段
+  ⚠️ 不存在跨资源通用的"我的 xxx"过滤公式 —— 具体怎么用 `user_id` 由各资源 skill 的 reference 决定。详见 [`identity-resolution.md`](identity-resolution.md) 的决策顺序与速查表。
+- `account_id`：火山账号 ID（JWT `sub` 声明）。同一账号下不同 IAM 用户共享。
+- `trn`：完整 IAM TRN，例如 `trn:iam::<account_id>:user/<name>` 或 `trn:iam::<account_id>:root`。
+- `is_root`：是否根账号身份。仅在能解出 `trn` 时出现。
+- `project_name` / `region`：当前生效的 project / region（已应用 flag / 环境变量 / `.env` 优先级解析）。
+
+## 边角场景
+
+### SSO 已过期但 .env 还有 token
+
+```json
+{
+  "logged_in": false,
+  "auth_method": "none",
+  "sso_expired": true,
+  "name": "alice",
+  "user_id": "10000001",
+  "account_id": "2000000001",
+  "trn": "trn:iam::2000000001:user/alice",
+  "is_root": false,
+  "project_name": "default",
+  "region": "cn-beijing",
+  "hint": "SSO token expired; run `arkcli auth login volc-sso` to refresh"
+}
+```
+
+身份字段仍然能从过期 token 解出来（用于"我曾经是谁"），但 `logged_in=false` 提示无法发起远端调用。Agent 命中 `sso_expired=true` 应按当前 profile tenant 引导用户重新登录（火山：`arkcli auth login volc-sso`）。
+
+### AK/SK 模式
+
+```json
+{
+  "logged_in": true,
+  "auth_method": "aksk",
+  "project_name": "default",
+  "region": "cn-beijing",
+  "hint": "AK/SK mode cannot resolve IAM user identity; run `arkcli auth login volc-sso` to identify yourself"
+}
+```
+
+AK/SK 模式拿不到 IAM 用户身份（无 IDToken）。"我的 xxx"语义在这种状态下无法满足，应引导 SSO 登录。
+
+### STS-only 模式（source=ve / init-volc）
+
+```json
+{
+  "logged_in": true,
+  "auth_method": "sts",
+  "name": "alice",
+  "user_id": "10000001",
+  "account_id": "2000000001",
+  "trn": "trn:iam::2000000001:user/alice",
+  "is_root": false,
+  "project_name": "default",
+  "region": "cn-beijing"
+}
+```
+
+`auth_method="sts"` 出现于两种场景：
+- **source=ve**：`arkcli auth login` 交互式登录时检测到本机 `volcengine-cli >= 1.0.45` 且已 `ve login`，直接接管其登录态（arkcli 不再自己跑 OAuth，也不落 IDToken/refresh_token；STS 由 volcengine-go-sdk 内部持 refresh_token 自动 refresh）
+- **init-volc / 云开发机 / CI**：`arkcli init-volc` 从 `VOLC_INIT_*` 环境变量落 STS
+
+这是 **合法登录态**：`logged_in=true`、身份字段（`name` / `user_id` / `account_id` / `trn` / `is_root`）来自 identity_store `metadata.json` 或服务端 `GetCallerIdentity`。控制面命令（`models` / `endpoint` / `apikey` / `usage`）能正常调；`--mine` 也支持（走 `hasInitVolcSTSIdentity` 判据）。**不要**按"未登录 / AK/SK 态"引导重登。
+
+### 完全未登录
+
+```json
+{
+  "logged_in": false,
+  "auth_method": "none",
+  "hint": "run `arkcli auth login` or `arkcli auth login volc-sso`"
+}
+```
+
+## Agent 使用要点
+
+- **不要解析 `~/.arkcli/.env` 里的 JWT**：whoami 已经做了这件事，直接读 `user_id` 就好
+- **不要把 `account_id` 当成 IAM 用户 ID**：两者语义完全不同，`account_id` 是账号级别（同账号下多个 IAM 用户共享），`user_id` 是 IAM 子用户级别
+- **`user_id` 怎么用，看具体资源 skill 的 reference**：whoami 只负责"告诉你你是谁"，不预设过滤公式。endpoint 走 Tag、API Key 火山走 `Filter.UserId`，机制不同 —— 详见 [`identity-resolution.md`](identity-resolution.md) 的速查表
+- 看到 `sso_expired=true` 或 `auth_method=aksk` 但缺 `user_id` 时，先回到 [`../SKILL.md`](../SKILL.md) 走登录流程，再回原任务
+- **`auth_method=sts` 不算未登录**：source=ve / init-volc 场景, `logged_in=true` + 身份字段齐全, 不要引导重登也不要按 AK/SK 态处理
+
+## 与 status 的关系
+
+- `auth status` 在 SSO 路径下也会暴露 `volc_sso.identity` 嵌套子对象（同字段集），但更适合排障语境
+- 脚本和 Skill 优先使用 `auth whoami`：扁平 + 稳定 schema + 支持 `--transform`

package/skills/arkcli-auth/references/auth-modes.md

@@ -0,0 +1,101 @@
+# 认证态边界与错误恢复（控制面 STS/AK-SK + API Key 数据面恢复）
+
+> 本文从 `arkcli-shared` 拆出。仅在以下两类**鉴权态相关**场景加载：① 当前是 AK/SK 态、要判断能调什么；② 数据面（Runtime）调用撞到 401/403/AccessDenied 类错误要恢复。常规读写任务不需要读本文。
+
+## 控制面用 STS 还是长效 AK/SK（agent 决策）
+
+> **先记结论：绝大多数情况都用不到长效 AK/SK。** 只要 SSO 登录过（`auth login` 现在唯一可用的登录方式就是 SSO），控制面就一直走 **SSO 派生的 STS**，长效 AK/SK 即便配过也是旁路、不参与签名。
+
+控制面（火山 OpenTOP）签名有三条路，**在建客户端时按 cfg 里"有 IDToken / 有 VolcControlPlaneSTS / 只有长效 AK/SK"分流定死**，运行时不再改：
+
+```
+有 cfg.IDToken（= SSO 登录过，含已过期但可 refresh）
+   → STS 路：arkcli 自签 V4，凭证是 SSO 派生的临时 STS（带 X-Security-Token 头）
+   → STS 过期 → 自动 refresh → refresh 不了才报错让你重登；【绝不回落到 AK/SK】
+
+无 cfg.IDToken 但 cfg.VolcControlPlaneSTS=true（STS-only 身份：source=ve 借用本机 volcengine-cli 登录态 / init-volc / 云开发机 / CI 注入 VOLC_INIT_* STS）
+   → STS 路：同上 V4 直签（走 identity_store 里的 sts.json，不吃 X-Security-Token 分支之外的差异）
+   → source=ve: STS 过期由 volcengine-go-sdk 内部拿 refresh_token 自动 refresh（arkcli 侧不持 refresh_token）
+   → init-volc / 云开发机: STS 过期需要 CI / 平台重新注入 VOLC_INIT_*，arkcli 不自愈
+   → 对应 `auth_method="sts"`；`arkcli auth whoami` 里 `logged_in=true`
+
+无 cfg.IDToken、无 STS、且配过 AK/SK（cfg.AK && cfg.SK）
+   → AK/SK 路：volcengine-go-sdk 用【静态长效 AK/SK】直接 V4 签名（无 session token、无 X-Security-Token 头）
+```
+
+要点（都经代码核实，别再写"AK/SK 派生 STS"——它不派生，是静态直签）：
+
+- **SSO 与长效 AK/SK 互斥，SSO 优先**：有 IDToken 就只用 STS，AK/SK 完全不碰（`NewArkClient`：`if cfg.IDToken != "" || cfg.VolcControlPlaneSTS { ... 走 STS 路 }`，根本不构造静态 AK/SK 客户端）。
+- **长效 AK/SK 真正被用，当且仅当**：`IDToken` 为空、`VolcControlPlaneSTS=false`、且配过 AK/SK。现状下 `auth login` 的 AK/SK 通道已关，AK/SK 只能由老版 `arkcli config init --access-key/--secret-key` 注入——所以这条路**几乎只出现在"专门配了 AK/SK 且从没 SSO / 从没 STS 借用"的小众场景**。
+- **STS ≠ 可降级成长效 AK/SK**：STS 必带 `X-Security-Token` 头，长效 AK/SK 不带；两者走不同代码路（自签 V4 vs SDK），不是等价请求。**别把 STS 里的 AK/SK 抠出来当长效用**——丢了 session token 头，server 判未授权。
+- **`auth_method="sts"` 是合法登录态**（source=ve 或 init-volc）——不要按"未登录"处理。命令入口的登录判据必须同时接受 `AuthMethod=="sso"` 和 profile-bound 火山控制面 STS（`VolcControlPlaneSTS=true` + 非空 `IdentityKey`），见 `shortcuts/common/mine.go` 的 `hasInitVolcSTSIdentity` 和 `cmd/auth/apikey.go` 的 `requireAuthForApikeySelection`。
+
+
+### 各平面怎么走
+
+- **控制面**（列模型 / endpoint / API Key / `+deploy` / infer endpoint 写操作）：火山按上面的 STS 或长效 AK/SK 二选一。
+- **数据面**（`+chat` / `+gen` / `+understand` / embeddings）：永远用 ARK API Key（`Authorization: Bearer <api-key>`），跟控制面 STS / AK-SK 之争无关。
+- **"我的 xxx"身份过滤**：长效 AK/SK 态拿不到 IAM 子用户身份（无 IDToken），自指过滤受限 —— 见 [`identity-resolution.md`](identity-resolution.md)。
+
+### Agent 判定规则
+
+1. 默认认为控制面走 SSO/STS（最常见态）。先看 `auth status` 的 `auth_method` 再决策，不要先发命令看 fallback。
+2. 看到 `requires Volc SSO STS` 报错 → STS 缺失 / refresh 失败，转 [`../SKILL.md`](../SKILL.md) 引导 `arkcli auth login volc-sso`，**不要原地重试、也不要指望它回落长效 AK/SK**（不会）。
+4. 只有当 `auth_method=aksk`（确实无 SSO、专配了长效 AK/SK）时才按长效 AK/SK 态思考；这是小众场景，别默认往这上面套。
+   - `auth_method=sts` 不是"未登录",是 STS-only 身份 (source=ve 借用本机 ve CLI 登录态 / init-volc 云开发机 STS 注入); 控制面能跑, `--mine` 也支持 (走 `hasInitVolcSTSIdentity` 判据),不要引导用户重登。
+5. 不要把 `arkcli api` 当绕过认证约束的后门——它走同一套客户端，认证态不对照样被拒。
+
+## API Key 模式的错误恢复（agent 决策）
+
+数据面（Runtime）调用——`+chat`、`+gen`、embeddings、image / video 生成等——使用 ARK API Key 鉴权（`Authorization: Bearer <api-key>`）。当 agent 在数据面调用中**遇到鉴权类或权限类错误**时，按下面规则恢复，不要原地重试。
+
+### 触发特征
+
+任一即满足，判定为 API Key 失效 / 缺失 / 不匹配 / 权限不足：
+
+- HTTP 401 / 403
+- 错误前缀含 `arkruntime.<action>:`（来自 SDK，标识 Runtime 数据面调用）
+- 错误码：`"code":"AccessDenied"`、`"code":"InvalidApiKey"`、`"code":"Unauthorized"`、`"code":"AuthenticationError"`
+- 错误文案含 `do not have access` / `Unauthorized` / `Authentication` / `api key` / `expired`
+- arkcli 内部报 `runtime auth failed` / `runtime API key not configured`
+
+典型样例：
+
+```
+error: arkruntime.create_responses: Error code: 403 - {"code":"AccessDenied","message":"The request failed because you do not have access to the requested resource. Request id: ..."}
+```
+
+### Agent 处置流程
+
+**先按症状分型**（决定走"自愈"还是"权限/重登"）：
+
+- **key 失效 / 过期 / 不匹配**（`InvalidApiKey` / `Unauthorized` / `AuthenticationError`，或文案含 `api key` / `expired` / `Authentication`）→ 多半后端已**轮换或改了 key**，本地 profile.yaml 那把变旧 → 走下面【自愈】。
+- **权限不足**（`AccessDenied` + `do not have access`，针对某模型 / endpoint）→ 不是 key 旧，是这把 key 没权限 → **跳过自愈**，直接看「边界场景」。
+
+**【自愈】优先动作（防御，仅"遇失败"反应式触发）：**
+
+> **触发时机（重要）**：只在业务命令**实际失败**、且症状落在上面"key 失效"那一类时才走自愈 —— **不要在每次命令前预防性 / 周期性 refresh**。refresh 每次都打控制面 + 写 profile.yaml，预防式刷是无谓开销，也会无谓改动 default。reactive（坏了才修），不是 proactive（每次都刷）。
+
+1. **自动同步后端 key**：当 key 来源是 profile.yaml（没被 env/flag 覆盖，见下方 caveat），agent 可**自动执行一次** `arkcli profile apikey refresh` —— 以后端为 SSOT 把当前 profile 的 key 池拉新，并自动把失效的 default 校正到有效 key（详见 [`../../arkcli-profile/references/arkcli-profile-keys.md`](../../arkcli-profile/references/arkcli-profile-keys.md)）。refresh 是幂等、低风险的同步，只改当前 profile 的 `available_api_keys` / `default_api_key`，**允许 agent 自动跑**，不必先问用户。
+2. **重试原命令一次**。成功 → 自愈完成，回原始任务，不要停在 refresh 结果上。
+3. 仍失败，或 `keys refresh` 自身报控制面鉴权失败（= SSO / 身份过期，不是 key 同步问题）→ 引导 `arkcli auth login volc-sso` 重登。
+4. refresh 后 key 池有多把、但默认那把不对 → `arkcli profile apikey use <序号>`。只有 `platform` / `coding-plan` 个人版使用普通 API Key 池时，才可以让用户亲自执行 `arkcli auth apikey` 交互选择；该命令不会读取或修复 Agent Plan 专属 Key，也不会读取团队席位 Key，不能把它的 `saved=true` 当成 Plan Key 已恢复。
+
+**⚠️ 自愈前必看的 caveat：**
+
+- **env/flag 覆盖**：若当前 key 来自 `ARK_API_KEY` 环境变量或 `--api-key` flag（优先级高于 profile.yaml），refresh 写 profile.yaml **不生效** —— 先让用户去掉覆盖，再 refresh。
+- **refresh ≠ rotate**：refresh 是把「已被改的」key 同步下来；主动「换一把新 key / 废弃泄露的 key」是 `arkcli plans personal|team rotate-apikey`（见 [`../SKILL.md`](../SKILL.md)）。别拿 refresh 当换 key 用。
+- **空结果不覆盖本地**：远端返回零把可用 Key 时，`profile apikey refresh` 必须报错并保留当前 `available_api_keys` / `default_api_key`；不能把一次空响应当作成功同步并清空本地配置。
+- **单 profile 范围**：refresh 只治当前 / `--profile` 那条；多 profile 共用被轮换的 key 时逐个刷。
+
+**边界场景：**
+
+- **`platform` / `coding-plan` 个人版的普通池为空** → 真人 TTY 的 SSO 登录会询问是否创建一把全资源 Key；也可以显式运行 `arkcli auth apikey create`。TTY 必须确认；非交互环境收到 `requires_confirmation` 后必须走共享 Skill 的宿主确认流程。两条路径都只创建一次、最多读 3 次状态，并且不输出明文 Key。控制台手动入口仍为 `https://console.volcengine.com/ark/region:ark+<region>/apiKey`；手动创建后再运行 `arkcli auth apikey` 或 `profile apikey refresh`。
+- **Agent Plan 个人版没有 Active 专属 Key** → 这是 `ListApiKeys(Filter.Scene="RealAgentPlanPersonal")` 所在的专属池问题，与普通池无关。专属记录存在但状态非 Active（如 `Restricted`）时，真人 TTY 登录可在明确提示旧 Key 会立即失效后，询问是否只轮转一次并最多读 3 次状态；无专属记录、用户拒绝或非 TTY 时不轮转。手动处理入口是 `https://ark.volcengine.com/region:<region>/subscription/agent-plan`，不要指向普通 API Key 页面或 `auth apikey`。
+- **团队版没有可用 Key** → Key 来自 `GetSeatInfo.Result.ApiKey`，要求存在 Running 席位；这是席位/套餐问题，不属于普通 API Key 池，也不能用 `auth apikey` 修复。转 [`../../arkcli-plans/SKILL.md`](../../arkcli-plans/SKILL.md) 的团队版流程。
+- **用户已有 API Key 但持续报 `AccessDenied` 类权限错误** → 当前这把 key 缺目标资源（模型 / endpoint）访问权限；**refresh / 重选都救不了**（同账号同权限，照样被拒）。引导去 console 给当前 key 加权限，或新建一把带正确权限的 key，再回来 `arkcli auth apikey` 切过去。
+
+### 与控制面的区分
+
+- 控制面接口（model / endpoint 管理 / usage 等）的鉴权错误，参考上面"控制面用 STS 还是长效 AK/SK"和 [`../../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) 的"认证闸门"；不要把控制面错误按本节流程引导到 `auth apikey`。
+- 区分线索：报错前缀是否是 `arkruntime.<action>:`，或路径是否是 OpenAI 兼容的 `/chat/completions`、`/embeddings`、`/images/generations`、`/responses` 等数据面端点。

package/skills/arkcli-auth/references/identity-resolution.md

@@ -0,0 +1,74 @@
+# 用户身份解析（"我的 xxx" 语义）
+
+> 本文从 `arkcli-shared` 拆出。触发场景：用户请求带"我的 / 我创建的 / 我部署的 / my <资源>"这类主语自指语义。属 arkcli-auth（身份）范畴，仅在该场景加载。
+
+用户请求出现"我的 / 我创建的 / 我部署的 / my <资源>"这类**主语自指**语义时，
+agent 必须把过滤限定到当前登录身份名下的资源，**不能**把"全部"列表当成"我的"列表返回。
+**绝对禁止**直接解析 `~/.arkcli/.env` 里的 JWT。
+
+> **本节只规定抽象决策框架。** 具体过滤入口（Tag 字符串拼装 / Filter 字段名 / 服务端
+> 参数 / 是否客户端 jq 过滤）**不在此写**，由该资源所属 skill 的 `references/*.md`
+> 自己声明。原因：**不存在跨资源通用的"我的"过滤公式** —— endpoint 走 `TagFilters`，
+> API Key 火山走 `Filter.UserId`，
+> usage 已经天然按账号 scope，机制完全不同。把 endpoint 专属的 `IAMUser/<uid>/<name>` Tag 公式
+> 硬套到 API Key / model 等资源上一定会得到错误结果。
+
+## 触发关键词（中英同义）
+
+- "我的 endpoint / 我创建的接入点 / 我跑的 / 我部署的"
+- "我的 API Key / 我的 key"
+- "我的用量 / 我用了多少 token / 我消耗了多少"
+- "my endpoint / my deployment / my usage / endpoints I created" 等英文同义
+
+## 决策顺序（严格按此优先级）
+
+1. **看该命令是否有内建 `--mine`（或同义服务端过滤 flag）**。有就直接用 ——
+   一行结束、不需要 `whoami`、不需要 jq、不会因身份串拼错漏数据。
+   判断方式：读该命令在所属 skill 的 `references/<cmd>.md`。
+2. **没有 `--mine` 时，读该资源 skill 的 reference**，按 reference 声明的入口走。
+   入口形态可能是请求侧 `Filter.<字段>`，可能是响应里 `Tags[]` 的客户端 jq 过滤，
+   也可能是已天然按账号 scope 无需额外过滤。**不替资源猜入口。**
+3. **reference 没说**：抽样一两页响应看实际过滤字段，并提示用户该 skill 缺文档。
+   不要自己拍脑袋套别的资源的过滤公式 —— 跨资源套用一定会错。
+
+## 资源-入口速查（详细规则在各 skill 自己的 reference 里）
+
+| 资源 | 详见 | 入口形态 |
+|---|---|---|
+| infer endpoints | `arkcli-infer-endpoint/references/arkcli-infer-endpoint-list.md` | 内建 `--mine`（服务端 `TagFilter sys:ark:createdBy`） |
+| API Keys | `arkcli-auth`（`arkcli auth apikey` 已内建 personal/all 切换） | 火山：服务端 `Filter.UserId` |
+| Foundation Models | `arkcli-models` | 公共目录，无"我的"概念 |
+| 自定义模型 | `arkcli-models/references/arkcli-models-list.md` | 当前**无**服务端 `--mine`，需 `--page-all` + 客户端字段过滤 |
+| Usage / 用量 | `arkcli-usage` | 默认即当前账号 scope，无需额外过滤 |
+
+新增资源时**在该 skill 自己的 reference 里**写明入口；不要把具体公式塞回本文。
+
+## Shell 变量名禁忌（与具体过滤入口无关，全局适用）
+
+如果某条 reference 让你在 shell 里临时存身份字段（如 `whoami` 输出），**禁止**使用
+`UID` / `EUID` / `HOME` / `PATH` / `PWD` / `USER` 等 POSIX shell 内置变量名。
+`UID` 在 zsh 下是 real user id，赋值会触发 `setuid()` syscall，普通用户报
+`failed to change user ID: operation not permitted`；bash 下报 `readonly variable`。
+**临时变量统一用小写**（`ark_uid` / `my_uid` / `arkcli_user`）。
+
+最稳的避坑方式：**优先走第 1 条决策**（命令内建 flag），根本不让 user_id 经手 shell 变量。
+
+## 认证态边角
+
+- `whoami` 显示 `auth_method=aksk`，或 `sso_expired=true` 且缺 `user_id`
+  → "我的 xxx" 无法满足，按当前 profile tenant 引导用户重新 SSO 登录（火山：`arkcli auth login volc-sso`），**不要用 AK/SK 模式重试**。
+  使用 `--mine` 的命令在这种态会直接报 `--mine requires an SSO sub-user login`。
+- `whoami` 显示 `is_root=true`（账号主身份）
+  → root 身份在部分 API 响应里 `UserId` 可能是 `0`；具体 root 处理（直接拒绝 / 走
+  AccountId / 双条件过滤等）由各资源 reference 自己声明，不给统一规则。
+- 命中限流（`AccountFlowLimitExceeded`）
+  → 调大 `--page-delay`（推荐 `800` ms），不要原地重试。
+
+## 禁止
+
+- 不要从 `~/.arkcli/.env` 读取 `VOLCENGINE_ID_TOKEN` 自己解 JWT；whoami 已经做了
+- 不要让用户自己提供 `user_id`；CLI 已经能拿
+- 不要把"全部资源"当成"我的资源"返回（特别是跨 project / 跨用户的列表）
+- 不要在命令已支持 `--mine` 时仍走 whoami + jq —— 优先级是反的
+- 不要把 endpoint 的 `IAMUser/<uid>/<name>` Tag 公式套到 API Key / usage / model 等
+  其它资源 —— 那不是全局机制，**只在带 `sys:ark:createdBy` Tag 的资源上有效**