| name | arkcli-agent |
| version | 1.1.1 |
| description | arkcli agent：管理 ARK Managed Agents，包括 Agent / Skill / Env / Session / File / Memory Store / Vault / MCP OAuth。控制面优先走 ForTop/OpenTOP，Session 运行时和 Files 走数据面直联。 |
| metadata | {"requires":{"bins":["arkcli"]},"cliHelp":"arkcli agent --help"} |
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 的最小决策表
| 用户输入 | AI Agent 的处理 |
|---|
| 未指定模型 | 先用 agent model list --query 从 Managed Agent 白名单中选择精确 items[].model，不要凭印象拼模型 ID |
| 未指定 Skill | 先查本账号 custom skill；没有合适候选再查 market/SkillHub skill |
| 给出本地 Skill zip | 先调用 agent skill create --zip，拿到返回的 skill-... ID 和版本后再创建 Agent |
| 未指定工具 | 使用 CLI 注入的完整默认工具集；显式传 --tool 时全量替换默认工具 |
| 未指定环境 | 创建 Session 时自动选择当前项目最新环境；没有可用环境才提示创建或传入环境 ID |
| 创建成功 | 必须回读 agent agent get <agent-id> --format json，展示服务端最终的 Model、System、Tools、Skills、McpServers 和扩展配置 |
| 用户期待 Agent 回复 | 短请求使用 +new session ... --message 或 events send ... --stream；大 payload / 长耗时任务使用 events send --poll，或 send 立即返回后按 cursor 轮询 events / 使用 +tail，不要让所有任务都阻塞等待 |
先选路径
认证与 Profile
- 业务命令前先
arkcli auth status --format json。未登录、SSO 过期、STS refresh 失败时先处理登录。
- 当前数据面 Files / Session resources / events / threads 需要可用 ARK API Key。CLI 默认使用 profile / identity 解析出的 Key；也可用全局
--api-key 做本次调用覆盖。若同时自定义 --base-url，必须显式成对提供二者；无 Profile 的 stateless 模式也必须成对提供。
- 线上环境已就位，默认走
--env prod，不要再默认跑 stg。
- 非交互 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、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，判断是否仍有未拉取数据。
删除确认
- Managed Agent 的破坏性
delete 命令在真实 TTY 且未传 --yes 时会显示不可逆警告并询问 [y/N]；输入 y/yes 才会调用后端，其他输入会取消。
- 非交互环境（AI Agent、CI、管道）不会读取 stdin；未传
--yes 时返回 type=requires_confirmation，不会调用后端。只有用户已经明确确认删除目标后，调用方才可以补 --yes 重试。
--dry-run 不是全域能力。只有命令自身 --help 列出该 flag 时才可用；
当前主要覆盖可由本地 payload 确定的 Env/Session/Memory/Vault/Credential
写请求，以及 agent agent create/update/delete、agent skill create/update/delete
和 agent file upload/delete，以及会写本地文件的 agent skill download、
+export。+new-agent、+iterate、MCP login 与所有纯读命令都不注册。
Client Preview 只生成零网络 preview.v1 计划；它不代替真实执行前的开通、
版本/依赖校验或删除确认。
长流程执行规则
- 一个 shell/tool 调用只执行一个
arkcli 命令。不要把 session create、写入 ID、events send、events list 用 &&、;、管道或 heredoc 串成一个长命令。
session create、Agent 创建、文件上传等写操作成功后，立即从结构化输出提取并保存 ID；下一次调用使用已经确认的字面量 ID，不要依赖同一 shell 中的变量赋值继续执行。- 任一步超过预期时间时，先结束该步并单独执行
session get、events list 或 +debug 诊断；不要让后续命令被前一个阻塞步骤掩盖。
- 大 JSON 或大文本不要在同一个 shell 调用中通过 Python/Node 管道解析；先让
arkcli --format json 独立返回，再在下一步解析结果。这样即使请求超时，也能区分是创建、发送还是回查阶段失败。
超时与重试
- 只对网络超时、连接中断、429 或 5xx 做有限重试；参数校验、鉴权失败、未开通、权限不足和明确业务错误直接抛出，不要重试。
session create 超时后结果可能未知。先用 session list/get 按返回的标题、Agent、环境和创建时间检查是否已经创建，再决定是否重试；没有幂等键时不要盲目重复创建。events send 超时后也可能已经被服务端接收。先用返回的 event cursor、发送时间或最近的 user event 查询 events list；确认没有接收记录后才允许重试，避免重复发送用户消息。events send --stream 达到 stream 等待上限后会自动切换为 events list polling，默认再等待 120 秒；--wait 保留相同行为作为兼容别名。两阶段都超时才返回带 cursor 恢复命令的非 0 错误。此时不要重发原消息，继续 list/poll 同一个 cursor。events list/get 属于只读请求，可以使用有限次数、指数退避的重试；继续使用同一个 after cursor，不要因为重试而从历史开头重新读取。- 每一步都要保留步骤名、Session ID、event cursor、尝试次数和最后错误；达到重试上限后抛出带上下文的错误，不要把超时伪装成成功。
命令速查
| 命令 | 说明 |
|---|
arkcli agent agent list/get/create/update/delete/versions | Agent CRUD + 版本 |
arkcli agent model list | 查询 Managed Agent 模型白名单；--query 用模型目录详情增强/排序白名单；输出 items[].model 可直接作为 --model |
arkcli +new-agent | Agent create 增强入口；支持 --fork/--from 复制已有 Agent 后创建新 Agent |
arkcli +iterate | 更新 Agent 配置，创建新 Session，并进入 one-shot/REPL 试运行；--environment-id/--env-id 可选，省略时自动选择最新环境 |
arkcli agent skill search/list/get/create/update/delete/versions/download | Market skill 检索、本账号 custom skill 查询、custom Skill zip 上传、版本更新、版本列表和下载；删除须按“非 latest → latest → Skill”执行；custom 查询走 TOP ListSkills |
arkcli agent env list/get/create/update/delete | Environment CRUD；当前 env list 没有 --status，状态筛选规则见 session-files.md |
arkcli agent session list/get/create/update/delete | Session CRUD |
arkcli agent session resources list/add/get | 数据面 session resources；get 是 CLI 基于 list 的本地筛选 |
arkcli agent session events list/send/stream | 数据面 events；stream 默认请求 Event Deltas 并输出 SSE/NDJSON 行；--no-event-deltas 回退完整事件；user.custom_tool_result 必须带 custom_tool_use_id，user.tool_result 仅允许 self_hosted，CLI 会前置校验 |
arkcli agent session threads list/get | 数据面 threads |
arkcli agent file list/get/upload/wait/delete | 数据面 Files API |
arkcli agent memory-store list/get/create/update/delete | Memory Store CRUD |
arkcli agent memory-store memories list/get/create/batch-create/update/delete | Memory CRUD |
arkcli agent vault list/get/create/update/delete | Vault CRUD |
arkcli agent vault oauth-provider list |
复杂字段如 Tools、Skills、McpServers、Multiagent、Metadata、Tags 支持 JSON/YAML 文件、stdin 或结构化 flags。请求结构与 TOP CamelCase 对齐；inline 对象兼容常见 lower/snake case alias。创建成功回显必须展示服务端最终的身份、模型、System、Tools、Skills、MCP 和扩展配置，不能只展示摘要；需要核对完整结果时用 agent agent get <agent-id> --format json 或 --format yaml。
Memory get 的 --view 语义：默认按 basic 请求，只返回 metadata 和 ContentSha256；--view full 保留 Content。若服务端仍在 basic 下返回 Content，CLI 会在输出层剥离 Content，但这只能控制输出，不能挽回已经产生的网络传输；服务端仍需正确实现 View 参数以节省带宽。
参考
