Arkcli Agent

arkcli agent

CRITICAL — 开始前 MUST 先读取 ../arkcli-shared/SKILL.md。

当用户需要创建、查询、调试或联通 ARK Managed Agent 时使用本 skill。核心原则：先用稳定产品命令，不要直接猜 OpenTOP Action；Session 运行时资源、事件、线程、Files API 走数据面直联；MCP OAuth 登录先查后端 provider，再用 arkcli agent +mcp-login。

执行前按“先选路径”读取对应 reference；只读相关 reference，不需要一次性加载全部细节。用户请求如果已经明确是创建、复制、挂文件、聊天、MCP 登录等写操作，完成必要确认/消歧后直接执行，不要只给命令建议。

创建 Agent 的最小决策表

仅咨询参数含义、命令用法或解读已有完整 stdout 时，能从文档与当前证据回答就直接回答， 不为概念解释发起 live 查询。只有账号当前配置、资源状态或模型实时可用性等问题才查服务端。 已拿到完整结果时复用它；名称搜索/grep 无命中不等于资源不存在，先确认目标是 Agent、 Environment 还是 Session。用户提供明确 ID 时直接查对应资源，不先列全量清单。

业务目标澄清

模型、Agent、Skill、MCP provider 等目标无法唯一确定时，遵循 arkcli-shared 的 0/1/N 结构化选择契约：先做一次最小 只读查询，选项只取本轮完整结构化结果中的真实 ID 和区分字段。多个候选会改变远端结果 时使用宿主结构化选择能力；唯一候选直接继续。选择目标只完成消歧，不等于授权后续创建、 更新或删除。

创建任务的主模型选型例外：默认由 AI 按本轮 --query 详情、实时资格与用户意图 择优，复述真实 items[].model 和依据；不能只因有多个候选就停下来问，也不能把排序第一 当作证据或把择优说成“只有一个模型可用”。用户明确的硬指标须用对应版本 metadata 验证；不能自动换身份、计费路径、超出预算或替换用户明确给出的模型。 只有多个候选的能力、版本或费用会实质影响结果且无法从用户意图安全判断时，才进入 模型选择停点：展示真实候选，用户选定前不得查询 Agent Skill，也不得执行 preview、 agent agent create/update、+new-agent、+iterate 或准备后续参数。此时选项是当前 回合的最终输出，之后不再探测写命令 --help 或调用其他工具。择优不替代执行授权， 也不适用于复制、更新、删除时对已有 Agent 的目标消歧。

先选路径

模型查询：主模型与工具模型

• 默认 --usage agent 按 ep_agent.support 选择主模型；--usage tool 按具体版本的 epa_tool_model.support 选择工具模型，两者不取交集。两种查询都不默认加 --primary-only，也不默认按 primary_version 排除候选；只有用户明确要求“只看主版本”时才加。
• 工具候选使用返回的 items[].model，不是内部 id（如 epm-*）。只给支持绑定的工具配置 Models；字段含义与完整 Tools 替换示例见 工具模型绑定。
• 两种用途共享 5 分钟全版本 ArkModels 缓存，输出 cache.source/fetched_at/expires_at；只有需要刷新时才加 --refresh-cache，不要每次查询都强刷。失败冷却为 1 分钟，强刷也不能绕过；错误不等于空候选。
• 列表不截断数量；上下文/模态/能力筛选不再由 list flags 承担。只有用户明确提出这些要求时，才按候选的 name + version 查询 ListModelMetaDatas 后筛选；无额外要求不逐模型补查。流程、字段与缺失值处理见 按具体版本筛选。
• agent model config 查询运行参数，不提供工具支持性。用户明确给出的模型 ID 仍交给创建/更新接口判断，不把缓存查询变成写入硬拦截。完整参数、缓存隔离与 query 模式边界见 查询说明。

认证与 Profile

• 未显式提供 API Key 时，Managed Agent 使用 type=platform 的 Profile，不自动使用 Agent Plan / Coding Plan（含团队版）的套餐凭证。登录成功不代表默认 Profile 支持 MA。
• 需要使用 Profile 凭证时，用 auth status --format json 核对类型；默认是套餐类型时，对本次命令指定已确认的 --profile <platform-profile>，不自动执行 profile use 改全局默认。没有可用 Platform 或身份/项目不明确时，按 Profile Skill 处理并取得确认，不猜名称或跨账号重试。
• 数据面命令接受显式 --api-key 或 ARK_API_KEY，此时即使默认是套餐 Profile，也不会因其类型被拦截。优先级为 --api-key > ARK_API_KEY > Platform Profile 的 Key；Key 的有效性与权限由服务端验证，认证失败时停止，不跨账号重试。
• 未显式指定地址时，MA 根据当前产品、Region、--env 使用标准数据面地址，不继承 Profile 的套餐或自定义路由。仅提供 Key 即可调用数据面，无 Profile 也不必额外提供地址。显式 --base-url / ARK_BASE_URL 优先，但必须同时显式提供 Key；只覆盖地址不能替换套餐凭证。
• 控制面仍依赖登录凭证，纯控制面命令不接受 Key/地址覆盖；包含控制面步骤的混合流程也不能只靠 API Key 免登录。涉及控制面时先 arkcli auth status --format json，处理未登录、SSO 过期或 STS refresh 失败。仅使用显式 Key 的数据面调用不要求先登录。
• 真实执行返回 managed_agent_profile_required 时停止，不改走 raw API 绕过。离线 --dry-run 不检查在线资格，预览成功不代表真实调用成功。上述覆盖均只影响本次调用，不修改默认 Profile 或保存的 Key。
• 线上环境已就位，默认走 --env prod，不要再默认跑 stg。
• 用户明确要求 stg 时使用 --env stg 和配套 Key；未指定地址时 MA 数据面自动使用标准 stg 地址。若显式提供地址，确认它也属于目标环境（显式地址不会被 --env 改写）。
• 非交互 SSO 登录是两段式：先 arkcli auth login --no-browser 拿 URL；用户贴回 base64 code 后，再跑 arkcli auth login --no-browser --code <code>。

List 分页

• 支持分页契约的列表可加全局 --page-all；未显式传单页大小时，CLI 默认每页取 100 条。默认最多请求 10 页，可用 --page-limit <N> 调高，--page-delay <ms> 控制页间隔。
• 已支持：Agent/版本、Env、Session、Skill market/custom/ark/all、Memory Store/Memories、Vault/Credentials/OAuth Provider、Files、Session Events/Threads。CLI 会分别按后端契约使用 Page、PageNumber、PageToken、after，并合并结果。
• agent model list、memory-store creators、session resources list 没有可用分页契约，不要为它们假设 --page-all 能补全结果。命中 --page-limit 后应检查返回的 NextPage、has_more 或 TotalCount，判断是否仍有未拉取数据。