arkcli-profile
arkcli profile 切面管理:列出、查看、新建、切换、删除、重命名 profile;管理 profile 内 API Key 列表;管理五类 profile 的默认资源与持久身份切面。也负责判断 Token 额度包/资源包应继续使用 platform profile 与 /api/v3,不能因「套餐」或价格字样误判为 Agent Plan/Coding Plan。临时 API Key/Base URL/Endpoint 调用不写回 profile,按 arkcli-shared 的 execution-context 契约执行。旧 config 子命令已 deprecated。
arkcli profile
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md,其中包含认证闸门、配置排查与命令选择顺序
CRITICAL — 一旦确定走 profile create、profile delete 或 profile project(重选 project 会重命名/重派生 platform profile),必须先复述对 config.yaml 的影响并征得用户确认;其他写操作(use / set-default / keys use / keys refresh / models refresh / rename)执行前也要复述目标 profile 名。
CRITICAL — profile 是本地身份切面管理,全域不注册 --dry-run。profile show/list/keys list 会做 best-effort 在线 Key 同步,可能回写本地 Key 库存或默认 Key;只在用户显式要求 Profile 管理时使用,并先说明该影响。其他写操作仍通过明确确认保护。
先区分核对与管理
- 只读核对当前身份、默认资源是否可见或凭证是否兼容,不是 Profile 管理;即使用户提供了 Profile 名称或 type,也先读取 Auth 与 Resources Skill 并交由它们处理。信息缺失不授权进入
profile show/list/keys list。 - 用户明确要管理 Profile、准备运行
show/list/keys list时,先在调用工具之前的用户可见文本中说明两项具体影响:尝试在线同步远端 API Key;可能回写本地 Key 库存或默认 Key。例如:“该管理查询会尝试在线同步 API Key,可能回写本地 Key 库存或默认 Key。” - “我会先解释”只是计划,不是披露;工具描述、内部思考和执行后的最终答复也不能替代这条前置说明。执行后不得把这些管理查询称为“纯只读”或据此保证“本地 Key 未变化”。
使用原则
- profile 是 0.1.16 引入的 统一身份切面,把
(type × region × project × owner_trn × api_keys)五个属性绑成一组 - profile 写操作(create / use / set-default / keys / models / delete / rename)一律走
arkcli profile <verb>;旧的arkcli config init/list/show/switch/delete已 deprecated,不要再引导用户用 - 普通身份准入使用
arkcli auth status/arkcli auth whoami,默认资源与路由检查使用arkcli resources list;不要为业务准入自动进入 Profile 管理 - 用户明确要查看或管理 Profile 时才运行
profile show/list/keys list,执行前先说明它们可能在线同步并回写 Key;脱敏 stdout 不代表本地配置无副作用 - ProfileType 五种:
platform/agent-plan/agent-plan-team/coding-plan/coding-plan-team;其 text/image/video 所需的数据面、凭证与资源不同 - 用户只想临时传 API Key / Base URL / Endpoint 时,不要创建、切换或修改 profile;先读
../arkcli-shared/references/execution-context.md
适用场景
- 用户问"我有哪些 profile / 当前 profile 是哪个 / 切换 profile"
- 用户要创建新 profile(platform,或 Agent/Coding Plan 的个人版/团队版)
- 用户问 default 模型 / 资源是什么、想换 default
- 用户的 API Key 列表过期、新 key 还没被拉进来,需要 refresh
- 业务命令
+chat / +gen / resources list报错"profile xxx 缺 ...",转回这里排查
反唤起信号
- 用户问鉴权 / 401 / SSO 失败 → 转
../arkcli-auth/SKILL.md - 用户问 base URL / region / API Key 优先级被覆盖 → 转
../arkcli-config/SKILL.md(config 现在专门讲解析归因 + reset) - 用户问"有哪些 endpoint / 模型可用" → 转
../arkcli-resources/SKILL.md - 用户问"我要找一个模型" / "哪个模型最强" → 转
../arkcli-models/SKILL.md
切换 profile 的硬状态机
- 执行
profile use前必须先跑一次arkcli profile list --format json;只有本轮已有完整、未截断的同源列表时可复用,不凭记忆认定目标存在。 profile list的结构化 stdout 是本地 profile 的唯一事实源;列表为空就报告未配置并停止,不再搜索文件系统、读取状态目录或猜测配置文件。用户给了精确名称时只做精确匹配;名称不存在就如实说明,并只从列表真实结果提供可用 profile。不得把该名称重解释为 project / region,也不得自动project/create/rename。- 用户只给了 type、用途或模糊描述时,只用列表里的
name / type / region / project等权威字段筛选,然后严格按arkcli-shared的 0 / 1 / N 候选规则消歧;用户选定前不执行写操作。 - 目标唯一且用户意图明确后才执行
arkcli profile use <name>,随后必须跑arkcli profile show --format json验证实际 active profile。 - 只有核验结果与目标一致才声称切换成功;报告
name / type / region / project / base_url这些生效切面,不把profile use的 exit=0 当成最终证据。
切换默认资源的硬状态机
- 用户没给具体资源 ID 时,先确定 modality,再只跑一次
arkcli resources list --modality <m> --format json取得当前或--profile指定切面的完整候选。 - 候选只能来自这次真实结果,按
arkcli-shared的 0 / 1 / N 规则处理:多候选优先调用宿主的结构化选择能力,通用 Skill 不写死工具名。 - 执行前复述目标 profile、modality 和精确 ID;使用
arkcli profile set-default --modality <m> <id>的默认 inline verify。除非用户明确要求并接受跳过校验的风险,不得自行添加--skip-verify。 - 写入后必须跑
arkcli profile show --format json或arkcli resources list --modality <m> --format json核验新 default;只有结构化结果与目标 ID 一致才声称切换成功。
--profile flag 的精确语义(0.1.16 修正)
优先级: --profile flag > ARK_PROFILE env > config.yaml default_profile
> 第一个 type=platform 的 profile > "default" sentinel
关键修正(codex P0-A):在 resources list / profile keys refresh / profile set-default / profile models refresh 这些命令上,--profile 不再只是改 target 对象名,而是真的切换执行身份 —— 内部用 Factory.RebuildForProfile(name) 重建 invoker,所以 arkcli profile keys refresh --profile B 会用 B 的 token / UserID 打控制面,而不是 active=A 的身份打完再写到 B。
Agent 行为约定:
- 用户跑
--profile B之类的子命令时,不要假设它跟 active profile 等价;告诉用户"将以 B 的身份操作" - 0.1.16 final clean-slate 模型: 整 arkcli 同一时间只 active 一个 identity. 新 SSO 完成时
sso.ActivateIdentity检测 newKey vscfg.DefaultProfile.IdentityKey: 一致 (alice 重登 alice) → 不动 yaml profile /--profile B用于同 identity 内跨 type 的临时切换; 不一致 (跨 sub / 跨 tenant) → 全清 yaml/.env/identities 三层重建 (BuildFirstProfileSet 火山多 type 派生)
Agent 快速执行顺序
- 普通业务只需当前身份/Profile 摘要 →
arkcli auth whoami --format json;不要调用 Profile 管理命令补齐普通准入 - 用户明确要查看 active profile 或本地 Profile 清单 → 先说明 Key 同步/回写影响,再用
arkcli profile show --format json或arkcli profile list --format json - 用户要切默认 profile → 按上面的硬状态机先
profile list,精确定位后profile use <name>,再profile show - 用户要新建 profile:先按下面决策树确认五类 type,读 create reference 后执行;只有用户明确要求同时切默认时才带
--set-default - 用户问 default 模型是什么 → plan 类用
arkcli profile models list,platform 用arkcli profile show看resources字段 - 用户要换 default 资源 → 按上面的硬状态机取真实候选、消歧、
profile set-default,再只读核验 - 用户的 default API Key 报错 / key 列表过期 →
arkcli profile keys refresh,然后arkcli profile keys list --format json看新清单。refresh 按 profile 类型取对应池:普通池、Agent Plan 个人版专属池或团队席位 Key;空结果会报错并保留本地 Key,不会成功清空。 - 用户要选别的 key 作 default →
arkcli profile keys use <api-key>(必须 ∈profile.available_api_keys) - 用户要换 active project(不重登)→
arkcli profile project(无参拉真实 ListProjects 交互选;先复述「会把 platform profile 重命名/重派生到新 project,个人版 plan profile 保留」并确认)
Token 额度包 / 资源包的 profile 归属
「19 元 Token 额度包」、「Token 资源包」、「预付费 Token 抵扣包」等产品仍属于标准 platform 按量调用的计费产品,不是 Agent Plan 或 Coding Plan 订阅身份:
- 应沿用
type=platform的 profile,数据面使用 platform/api/v3。 - 价格、「额度包 / 套餐」市场名称、Token 数量都不是 ProfileType 判据;只有明确的 Agent Plan / Coding Plan 订阅或团队席位才使用对应 plan profile。
- 用户只问「它属于哪类 profile」时直接解释分类,禁止自动执行
profile create/profile use/profile set-default。 - 用户要实际使用时,先用
arkcli auth whoami --format json核对当前持久 Profile 摘要;需要查看 Profile 详情或修改时,再按本 skill 的同步披露与写操作确认契约执行。
命令一览
| 命令 | 说明 | 改动来源 |
|---|---|---|
arkcli profile list | 列出所有 profile(含 type/region/project 切面) | 替代 config list |
arkcli profile show [name] | 显示当前/指定 profile 详细信息 | 替代 config show |
arkcli profile use [name] | 切换默认 profile(无参时交互选择) | 替代 config switch |
arkcli profile create --type ... | 新建 profile(interactive 或 inline) | 替代 config init(type 改为必选) |
arkcli profile delete <name> | 删除 profile(必须 --yes 才能跳确认) | 替代 config delete |
arkcli profile rename <old> --to <new> | 重命名 profile(校验格式 + 唯一性) | 0.1.16 新增 |
arkcli profile project [<name>] | 重选 active project(无参拉真实 ListProjects 交互选,列表置顶「账号全部资源」=不传 ProjectName/account-wide);把 platform profile 重派生到新 project,个人版 plan profile 原样保留;不重登 | 0.1.17 新增 |
arkcli profile keys list | 列 default + available API Keys(masked) | 0.1.16 新增 |
arkcli profile keys use <key> | 切 default API Key(key 必须 ∈ available list) | 0.1.16 新增 |
arkcli profile keys refresh | 按 profile 类型重拉普通池 / Agent Plan 专属池 / 团队席位 Key,非空时更新 available list | 0.1.16 新增 |
arkcli profile models list | plan 类 profile 的 PlanTier + Resources defaults | 0.1.16 新增 |
arkcli profile models refresh | 按目标 Plan 类型重拉文本模型并更新 Text.Default;会写配置 | 0.1.16 新增 |
arkcli profile set-default --modality <m> <id> | 设某 modality 的 default 资源 ID | 0.1.16 新增 |
ProfileType 选型速查
命令适用范围与空值
profile models list/refresh支持四类 Plan(Agent/Coding,个人/团队),不支持 platform;它不是公共模型目录或账号自定义模型列表。本表仅描述当前产品,不推导其他产品的身份契约。resources list/set-default依各 type × modality 的实际资源类型工作:platform 使用 Endpoint;Agent Plan 使用套餐模型;Coding Plan 图像/视频进入 platform lane。不要把一次文本配置推广到全部模态。current_default或某 modality 的 default 为空表示“未设置”,不是第一条候选、目录 primary version 或推荐项;不得把展示/排序顺序当成默认值。- 本地 Key 清单的掩码不是真实可调用 Key;查询元数据、导出凭证、刷新库存、轮转和切默认是不同动作。未要求更改时不能自动 use/refresh/rotate。
- 图像理解失败先核对输入模态、API 支持和客户端输入能力;
output_modalities=text不代表不支持读图,Plan 别名也不能只凭无版本后缀判无效。 - 批量推理权限与 Profile 切换不是同一个问题;先保留实际错误并核对模型/能力开通及权限,不把 account-wide 下的拒绝先归因为 Project,也不自动扩权或切身份。
| type | 适用 | 数据面 base URL | 控制面 | 视觉模型 (image/video) |
|---|---|---|---|---|
platform | 火山方舟 console 的标准用法 | /api/v3 | OpenTOP | ✓ 默认 endpoint |
agent-plan | 火山方舟 Agent Plan 订阅(个人版) | /api/plan/v3 | OpenTOP + Plan API | ✓ AgentPlanImage/VideoModels 硬编 |
coding-plan | 火山方舟 Coding Plan 订阅(个人版) | /api/coding/v3 | OpenTOP + CodingPlan API | text: 套餐内文本模型;image/video: 借道 platform 数据面 + 用户 +deploy 的 endpoint id (S10, commit f69be53) |
agent-plan-team | Agent Plan 团队席位 | /api/plan/v3 | OpenTOP + Plan API | text/image/video 都用套餐模型 + 团队席位 Key |
coding-plan-team | Coding Plan 团队席位 | /api/coding/v3 | OpenTOP + CodingPlan API | text 用套餐模型 + 团队席位 Key;image/video 用 platform Endpoint + 后付费 API Key |
Coding Plan 个人版的 text lane 使用后付费 API Key;Coding Plan Team 只有 text lane 使用团队席位 Key。完整矩阵见
../arkcli-shared/references/execution-context.md。
--plan-tier 手动声明仅适用于个人版;团队版档位与 Key 来自真实 Running 席位,不能用此 flag 绕过席位校验:
- agent-plan:
small/medium/large/max - coding-plan:
lite/pro
profile create 决策树
用户明确要求创建 Profile
|
+-- 标准按量 / Token 资源包 -----------------> platform
|
+-- 明确 Agent Plan
| +-- 个人订阅 -------------------------> agent-plan
| `-- 团队席位 -------------------------> agent-plan-team
|
+-- 明确 Coding Plan
| +-- 个人订阅 -------------------------> coding-plan
| `-- 团队席位 -------------------------> coding-plan-team
|
`-- 只说 "买了 plan" / 家族或个人团队不明 ---> 只澄清缺少的决策,不默认个人版
个人版由订阅 Detect 得到档位;用户明确确认实际个人档位且遇到可见性问题时才考虑 --plan-tier,它不证明订阅有效或有调用权限。团队版必须由当前绑定身份查到 Running 席位;失败时说明缺少的席位/权限,不改成个人版或拿普通 API Key 顶替。Vaka 的身份和授权由 shared 约束,不用创建/切换 Profile 修复宿主凭证错误。
常见错误
set-default: <id> 不在当前 profile (... ) 可用列表→ 用arkcli resources list --modality <m>核对可用 ID;不得自行用--skip-verify强写models list/refresh的类型不支持错误 → 核对目标是否属于当前产品支持的 Plan type;Volc 支持四类 Plan,不支持 platform。不要为消除报错擅自切 profile- S10 之后, coding-plan profile 下
profile set-default --modality image|video <ep>不再 fail-fast: verify 会借道 platform 控制面 ListEndpoints 校验 ep-id 是否存在 keys refresh: fetch api keys: NotLogin→ 控制面鉴权失败 (如登录态/STS 过期);fetcher 会用.env缓存单 key 兜底,profile.available_api_keys 仅含 1 项,恢复后再 refreshkeys refresh报没有可用 Key → 先按 profile type 判断:platform/coding-plan个人版去普通 API Key 管理页;agent-plan个人版去 Agent Plan 使用配置页检查专属 Key;团队版检查 Running 席位。不得把所有类型都引向普通 API Key 页面。arkcli auth apikey只操作普通 API Key 池;它返回saved=true也不表示 Agent Plan 专属 Key 或团队席位 Key 已恢复。- 切账号后 keys / models refresh 行为奇怪 → 检查
arkcli auth whoami,可能 active profile 仍绑旧 identity;P0-D 之后 STS / token 都在 per-identity store,但 active profile.identity_key 是 yaml 字段,跨账号要么profile use <new>,要么走 SSO Gate 2 自动新建
deprecated 命令自然语言重定向表
| 用户提到 | 实际执行 |
|---|---|
| "config init / 新建配置 / 初始化配置 / 新建 profile" | arkcli profile create --type ... |
| "config list / 看看有几个 profile / 列出 profile" | arkcli profile list |
| "config show / 看下我的配置 / 显示 profile" | arkcli profile show |
| "config switch / 切配置 / 切换 profile / 换 profile" | arkcli profile use [name] |
| "config reset / 全清掉 / 恢复出厂设置 / 配置乱了从头来 / 清空所有配置" | 转 arkcli-config:arkcli config reset(破坏性操作,必须先确认) |
| "我 agent-plan 下面有哪些可用模型 / 有哪些模型 / 模型列表" | arkcli profile models list(plan 类 profile)或 arkcli resources list |
参考
- Downloads
- Security audit
- Pass
- Last updated
- 2d ago
- Current version
- v1.0.0
- License
- MIT-0
