Arkcli Plans

arkcli plans

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../arkcli-shared/SKILL.md，其中包含认证闸门、配置排查与共享安全规则。 CRITICAL — 任何 plans buy / plans renew / plans personal rotate-apikey / plans team seat-assign / plans team rotate-apikey 在执行之前，务必先用 Read 工具读取对应 references/*.md，禁止盲目调用。 CRITICAL — Token 额度包 / Token 资源包是 platform 按量计费产品，不是本 skill 管理的 Agent Plan / Coding Plan。不得因「套餐」或价格字样调用 plans get/buy/renew；转 arkcli-profile 解释 platform + /api/v3 归属。

Agent Plan 控制台的超额后付费入口

用户问订阅页为何没有「超额后付费管理」按钮时，这是控制台套餐问题，不是 arkcli helper 的本机 TTY 矩阵问题。先用 arkcli plans get 核对当前身份是否持有生效的 Agent Plan 个人版或团队版；控制面查询失败时如实说明订阅状态未知，不把凭证错误当成未订阅。再读取官方超额后付费管理正文核对当前页面路径和前提，不用 Helper 状态代替控制台页面事实。

官方个人版文档将入口放在开通管理的 Agent Plan 页面「套餐信息」区域；进入后可分别管理模型与 Harness。用户所说的“订阅页”可能就是这个 Agent Plan 页面，不能断言“订阅页没有/不应有按钮”；先给文档的精确页面与区域，再核对用户实际所在页面。模型超额后付费要求先在「开通管理」开通模型服务，开启超额后付费前还需实名认证。Harness 也可在该页对应卡片管理，关闭该 Harness 的套餐抵扣会同时关闭其超额后付费。先问清个人版或企业版、模型服务开通状态；团队版额外核对管理员对席位的授权规则，不把个人版前提直接套到企业版。CLI 不能观察 Web 按钮是否实际渲染，不能仅凭文档断言某个前提就是这次缺按钮的根因；需要用户提供页面状态或由控制台排查。只作指引，不替用户开启真实计费开关。

Agent Plan 模型消失与下线通知

用户明确说 Agent Plan 中某个旧模型不见了，或问下线短信后是否要重设时，先读 Agent Plan 官方模型下线公告中该模型所在行及较新的后续迁移行，直接交付公告的停止新用户、正式停服时间与建议迁移模型；不要横查 Coding Plan 的模型概览或在多篇无关文档中耗尽本轮。公告是产品时间表，不是当前账号实时查询；用户问“我现在还可用吗”时再用 arkcli plans model-list --plan agent-plan --format json 核对本账号清单，失败就明确实时状态未知，不把 STS 错误当作模型已不可用，也不因模型广场仍显示 Published 就推翻套餐下线公告。

问“需要重新设置吗”时按配置类型区分：使用 auto/ark-code-latest 等自动路由者一般不需要改工具中的固定模型名；工具里写死旧 Model Name 者需在停服前改为当前仍受支持的目标并验证；本人自建且绑定旧模型的 ep-... 另需核对并迁移 Endpoint。不能从订阅存在或公告本身推断用户属于哪种配置；无法读到本人配置/资源时给条件化操作，不替用户改配置或创建接入点。若公告先推荐的迁移模型也进入后续下线期，以该公告更新的迁移链和当前支持列表为准，不把旧建议当永久可用。

购买意图的逐步收参与失败重入

购买信息缺失时按固定顺序逐个收敛，不把所有问题堆在同一轮：

1. 先问套餐家族：Agent Plan 还是 Coding Plan。
2. 再问版本与档位：只列已选家族的个人版档位及一个企业/团队版入口。个人版选择同时确定 --plan 与 --type；企业入口只确定团队 --plan。
3. 选择企业/团队版后，再单问同家族档位 --type，然后单问席位数 --quantity。Agent Plan 档位为 small/medium/large/max，Coding Plan 为 lite/pro。
4. 最后问时长 --duration，收齐后进入协议确认。

档位选项必须说明当前价格、典型场景和关键限制，按 buy 的档位说明 核对来源，不只显示裸档位名；未知价格/权益明确标未确认。时长可提供 1 / 3 / 6 / 12 月快捷选项，但仍接受 1–12 内的其他合法整数。

同时缺多项时，当前轮只问上述顺序中第一个未知决策。宿主有结构化选择能力时优先用，但通用 Skill 不写死工具名；没有时用简短选项文本退化。参数已全部明确且用户只要命令时，只给不带 --yes 的第一次协议闸门命令，不执行。

“当前轮只问一个决策”也限制当前轮可展示的信息：只列出该层的选项和必要差异，不得在说明、括号、示例或下一步预告中泄露后续层的选项名、合法值或 flag。比如套餐家族尚未确定时，回复中只能出现 Agent Plan 与 Coding Plan 及二者的简短区别，不能同时列出个人/团队、small/medium/large/max、lite/pro、时长或席位数。用户回答当前层后，下一轮再展示下一层。

payment_failed 且返回 Order ID 表示订单已经落库。必须复述该 Order ID，引导用户到 console 对这一单补付或取消；不重新收参，不执行 plans buy / plans renew，也不用 billing 出账记录代替已有订单的支付重入点。

ProductStockNotEnough 表示库存不足，不是参数错误；不重试、不重问已确认参数、不换档或拆单，按 buy 的失败语义 交付对应套餐控制台处理入口。transport error 同样保留本轮参数，不能重新开始购买向导。

续费不重新选档位：先确认 --plan 与续费月数，团队版从当前席位清单选择 --seat-ids；沿用原订阅/席位档位，不传购买专用的 --type 或 --quantity。用户已说清的参数不重复追问。仅询价走 pricing plans 或对应命令的 --estimate，不下单。

协议闸门返回后，把本次套餐、档位、时长、席位范围、实付价 total_amount_cny 与原价（如有）一起交付；价格和权益以当前返回为准，不用历史示例价承诺优惠、视频资格或有效期。超时/连接中断不能证明“未下单、未扣款”：保留错误和已有订单/席位 ID，先核对订单状态，不自动重放计费写操作。

🔒 协议闸门（plans buy / plans renew 强制流程）

plans buy / plans renew 是计费写操作，加 --yes 才真扣款。不传 --yes 不传 --estimate 时, CLI 不下单, 而是返回:

{
  "status": "agreement_required",
  "agreements": [{"title": "...", "url": "..."}, ...],
  "next_step": "arkcli plans buy ... --yes"
}

Agent 必须严格按以下顺序执行:

1. 第一次调用必须不带 --yes — 拿到 agreements 数组
2. 逐条把每条协议的 title 和 url 展示给最终用户(不能省略,不能合并)
3. 等待用户明确表达已阅读并同意全部协议(例如"我已阅读并同意"、"OK 我同意"等清晰表态);不能用模糊回答("好"、"嗯") 默认通过
4. 确认后才能加 --yes 重跑 next_step 字段里的命令(直接复制 next_step 即可,flag 已回显完整)

违反这条流程 = 帮用户跳过法律合规步骤。这跟 frontend 购买面板的 "我已阅读并同意《...》" checkbox 等价 — 必须真人看过才能勾。

--estimate 是在线询价路径,不下单也不需要协议确认；它不是 Client Preview。用户最终走 --yes 真下单时仍需先看协议。

业务定位

arkcli plans 管理两类 ARK 套餐：

• Agent Plan（agent-plan / agent-plan-team）：智能体调用套餐，按 tier 划档（small/medium/large/max）
• Coding Plan（coding-plan / coding-plan-team）：编程辅助套餐，按 tier 划档（lite/pro）

两类套餐都有个人订阅与企业/团队席位，但 Key 来源不能按 personal/team 一刀切：

personal 一个账号下一份订阅；team 是按席位（SeatID）粒度管理，每个席位绑一个子用户。

本 skill 不含套餐用量 / 配额查询（"用了多少 / 还剩多少 / 几号刷新 / 按模型拆分"）。plans get 只回答"我持有哪些套餐 + 状态(Effective/Running)"，不回答"用了多少"。配额视图在 ../arkcli-usage/ — 详见下方"快速决策"分流表。

套餐资源与接入配置的证据边界

• plans model-list 列的是套餐文本/路由模型，不是图片、视频资源的完整目录。用户问“我的 Agent Plan 能否生图/有哪些图片模型”时，先从本轮 arkcli auth status --format json 的 profiles_summary[] 按 type=agent-plan / agent-plan-team 找到实际 name，再执行 arkcli resources list --profile <完整 name> --modality image --format json，读取 items[].id、resource_kind、invocable 和 is_default。--profile 要填完整 Profile 名，不是 agent-plan 这样的类型字面量；多个同类型候选需核对身份/项目，不能猜选。不能因 plans model-list 没有 Seedream 就回答“不支持生图”，也不把示例数量当当前权益。
• “Coding Plan 下的接入点”要区分订阅、文本路由与 ep-xxx 推理接入点：ark-code-latest 是套餐模型路由别名，不是一个 ep-xxx Endpoint。用对应 Coding Plan Profile 的 resources list --modality text --format json 核对 items[].resource_kind / id 后回答是否存在 ep-xxx；不能用 plans get 查到订阅就推翻“没有接入点”的候选结论。Coding Plan 的图片/视频另走 platform Endpoint 池与后付费 Key，见 arkcli-resources。
• 给 SDK、Claude Code、OpenCode 等配置 Plan 时，先确认 Profile 类型：Agent Plan 数据面为 /api/plan/v3，Coding Plan 为 /api/coding/v3；普通 platform 才是 /api/v3。个人 Agent Plan 专属 Key、个人 Coding Plan 使用的普通池 Key、团队席位 Key 不可混用；只从本轮身份/Key 元数据与对应 Profile 类型矩阵确认，不把一个套餐的 Key 指向另一条计费路径。
• plans model-list 返回的展示名是 model_name，Plan 数据面及 Agent 配置中的 model 优先填 output_name（如实际返回的 auto 或无日期尾缀名称），仅在该字段为空时按 model-list 字段口径 回退；带版本的 model_id 主要用于精确查询/路由目标控制面写入，不能见到 selected_model_id 就直接抄进客户端环境变量。用户贴配置模板时逐个数清占位字段，不补造未出现的槽位。
• 用户问“我的 Plan Key 在哪/怎么取”时先转 arkcli-auth 的 Key 查询与交付 定位目标；apikey.get_raw/profile apikey get 有条件提供读取能力，不能声称 CLI 只能轮换、不能读取已有 Key。导出受 Access 与宿主限制，失败应如实报告；查询失败绝不自动触发破坏性的轮换，也不在聊天中回显完整 Key。

适用场景

• 查看当前账号下持有哪些套餐 → plans get
• 下单买套餐（含个人 / 团队）→ plans buy
• 续费已有套餐 → plans renew
• 看套餐支持的模型清单 → plans model-list
• 切换 ark-code-latest 的路由目标（Auto 智能调度或具体影子模型）→ plans model-apply
• Agent Plan 个人版轮换专属 APIKey → plans personal rotate-apikey；Coding Plan 个人版普通 Key 不走此命令
• 列出 / 筛选企业版席位 → plans team seat-list
• 把企业版席位绑给子用户 → plans team seat-assign
• 轮换企业版席位的 APIKey（自己 or 管理员批量）→ plans team rotate-apikey
• 查本机 AI Agent 上专属 Harness 能力装没装（只读）→ plans harness-status：按能力卡报豆包搜索 / 专业数据集 / Agent 记忆（MCP），外加全局火山引擎Supabase（CLI+Skill 装没装）。「我的 supabase / MCP 装好了吗」都走这里（Agent 记忆卡仅个人版 agent-plan；团队版报 absent 是预期、非漏装，详见其 reference）

反唤起信号

• 只问套餐已用/剩余额度、刷新时间或席位用量 → arkcli-usage，不是 plans get。
• 要读取/注入已有 API Key 的值而非轮换 → arkcli-auth 的 Key 查询流程；不要为只读需求调用 plans personal/team rotate-apikey。
• 要创建或管理普通 ep-xxx 接入点 → arkcli-deploy / arkcli-infer-endpoint；Plan 持有或 ark-code-latest 路由信息不能代替 Endpoint 查询。