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

package/skills/arkcli-agent/references/dream.md

@@ -0,0 +1,91 @@
+# Dream：整理会话记忆（仅火山）
+
+Dream 把一个 Memory Store 与若干 Session 作为输入，异步生成新的 Memory Store。创建可能产生模型与运行费用；用户仅要求查询或分析时不创建任务。当前仅火山版本提供这些命令。
+
+## 执行前：确认命令、身份与地址
+
+首次使用或排障时，先确认实际执行的 `arkcli --version` 和 `arkcli agent dream --help`。需要 `create/list/get/wait/cancel`；`unknown command` 是本地命令不可用，不是服务端 404。不要在非火山产品上改地址尝试启用 Dream。安装 CLI 不代表宿主已加载同版本 Skill；若实际加载的 Skill 缺少 Dream 指引，按 `arkcli-connect` 的流程同步当前二进制内嵌 Skill，不凭记忆补命令。
+
+通过 `auth status`、`profile list/show` 核对当前账号与选定 Profile 的 Region、Project。后续命令沿用同一 `--profile <已确认的名称>` 和 `--env prod|stg`；线上任务用 `prod`，不要沿用其他测试留下的 stg 设置，也不要为解决报错擅自切环境。
+
+| 操作 | 接口与认证 |
+| --- | --- |
+| `dream create` | MA 数据面 `POST /dreams`（标准地址下完整路径为 `/api/v3/dreams`），使用 API Key |
+| `dream list/get/wait/cancel` | 控制面 `ListDreams/GetDream/CancelDream`，使用有效的 SSO/STS 或 AK/SK；API Key 不能替代控制面登录 |
+
+没有显式 Key 时使用 Platform Profile，不使用 Agent Plan / Coding Plan 的 Key。用户显式提供 `--api-key` 或 `ARK_API_KEY` 时可覆盖默认 Profile 的 Key，即使默认是套餐 Profile，也不应要求用户先修改全局默认配置。
+
+未显式指定地址时，让 CLI 按产品、Region、环境选择 MA 标准数据面地址，不继承套餐路由。检查是否遗留 `--base-url` 或 `ARK_BASE_URL`：它们会覆盖标准地址；不要把 BYOK 上游模型地址当作 Dream 地址，也不要手工追加 `/dreams` 到 base URL。用户明确要求的自定义地址应保留，发现用途不符时先说明并确认，不静默替换。诊断只展示地址与凭证来源，不输出 Key。
+
+## 选择输入和模型
+
+先核对 Platform 身份、目标资源及权限。account-wide Platform Profile 可以使用，无需强制新建项目级 Profile；资源列表可见不代表可绑定，跨项目是否合法由接口判断。不要自动修改全局 Profile。
+
+用户未指定模型时，复用 `agent model list --format json` 的主模型候选及缓存；不加 `--usage tool`，也不默认加 `--primary-only`。多个候选时让用户选择。`--model` 接受返回的 `items[].model` 字符串，不接受 Agent 的 BYOK Model 对象；Dream 未开放 `--model-header-env`。
+
+这里调用的是 Dream API，不是 `+chat` 推理接口：直接传上述模型 ID，不套用普通 Platform 推理的 Endpoint 选择流程，不自动部署 Endpoint 或将模型 ID 改写为 `ep-*`。
+
+源 Memory Store 应可挂载且不处于 Dreaming，源 Session 不应是 Dream 自身生成的会话（`scene=dreams`）。先读取候选的实际字段；CLI 不额外硬编码资源状态或项目拦截，最终由后端验证。
+
+## 创建
+
+```bash
+arkcli agent dream create --memory-store-id <memstore-id> \
+  --session-id <session-id-1> --session-id <session-id-2> \
+  --model <model-id> --output-name "整理后的记忆" \
+  --instructions @dream-instructions.txt --format json
+```
+
+| 参数 | 含义 / 当前后端要求 |
+| --- | --- |
+| `--memory-store-id` | 一个源 Memory Store ID |
+| `--session-id` | 可重复；1–100 个非空、不重复的 Session ID |
+| `--model` | 模型 ID 字符串，必填 |
+| `--output-name` | 新 Memory Store 名称，1–64 个 Unicode 字符 |
+| `--output-description` | 可选，最多 300 个 Unicode 字符 |
+| `--instructions` | 可选，最多 4096 个 Unicode 字符，支持 `@file` |
+| `--file` | 原生 snake_case JSON/YAML；`-` 读 stdin，不隐式读取 stdin |
+
+长度、输入组合、权限和模型资格由接口校验。CLI 校验 payload 结构、类型及基本必填项，未知文件字段报错，避免拼写错误被静默忽略。
+
+```json
+{
+  "inputs": [
+    {"type": "memory_store", "memory_store_id": "<memstore-id>"},
+    {"type": "sessions", "session_ids": ["<session-id>"]}
+  ],
+  "model": "<model-id>",
+  "output_memory_store_name": "整理后的记忆"
+}
+```
+
+flags 覆盖文件中的对应字段；覆盖 `inputs` 时须同时传 `--memory-store-id` 和 `--session-id`，完整替换输入，不与文件隐式拼接。`create --dry-run` 只预览请求，不验证线上资格。
+
+创建仅请求一次，不自动重试网络错误、5xx，也不跟随重定向。响应不确定时先查询任务列表，不重发创建。成功返回 `Result.Id` 后保存 ID，再执行下一条命令。
+
+## 查询、等待和取消
+
+```bash
+arkcli agent dream list --limit 20 --page 1 --status running --format json
+arkcli agent dream get <dream-id> --format json
+arkcli agent dream wait <dream-id> --wait-timeout 600 --wait-interval 10 --format json
+arkcli agent dream cancel <dream-id> --yes --format json
+```
+
+list 支持可重复 `--status`、`--source-memory-store-query`（ID 精确或名称模糊匹配）、`--order asc|desc`。`--page` 是从 `1` 开始的数字字符串页码；下一页沿用 `NextPage`。`--limit` 为单页条数（后端 1–100，默认 20）；`--page-all` 默认单页 100、最多 10 页；`--page-limit` 是最多页数，不是单页大小。达到上限后检查 `NextPage`。
+
+单任务输出 `Result` 对象；list 输出 `Result` 数组及 `NextPage` / `TotalCount`。`Usage: null` 表示未知用量，不是零费用；保留 `SessionId`、`Outputs`、`Error` 和 `RunningTime`。
+
+wait 仅在 `completed` 时退出 0；`failed` / `canceled` 非零退出并保留任务 ID、状态和后端原因。未知状态报错，不无限轮询。默认等待 600 秒、间隔 10 秒；超时和中断都不取消任务，可用同一个 ID 继续 get/wait。get 查询到失败任务仍是正常查询成功。
+
+只有用户明确确认取消目标后才传 `--yes`。cancel 返回服务端实际状态，若竞态下已 completed，不宣称已取消；不会删除输入或已生成的输出库。create/cancel 支持离线 `--dry-run`，list/get/wait 不支持。完成后用 `agent memory-store get <Outputs[].MemoryStoreId>` 回读输出，而非只凭 completed 宣称记忆内容验证通过。
+
+## 遇到 404 时
+
+先保留失败步骤、脱敏后的完整命令、CLI 版本、产品、环境、Profile 的 Region/Project、目标 ID、HTTP 状态、后端错误码/消息及 RequestId（缺失就说明缺失），再定位：
+
+1. `list/get/wait/cancel` 与 `create` 不是同一条链路。列表成功只能证明控制面调用成功，不能证明创建使用的 Key、地址或数据面路由正确。
+2. 创建失败时核对上述地址覆盖与环境；查询失败时核对 Dream ID 是否来自同账号、环境和 Region，并结合后端错误判断资源不存在或不可见。单凭 404 不能断言“接口未发布”“模型不支持”或“Key 错误”。
+3. 有任务 ID 就查询该 ID；创建结果不确定且无 ID 时，用任务列表结合输入库、输出名和创建时间核对。未确认前不重发创建，也不通过换地址、换 Key、猜 raw API 路径反复试写。
+
+汇报时区分“创建已受理”“任务 completed”“输出内容已验证”。完整验收需查询输出库、列出输出记忆，并按用户目标读取内容核对；只拿到输出库 ID 或文件列表不能宣称内容正确。

package/skills/arkcli-agent/references/evals.md

@@ -0,0 +1,215 @@
+# arkcli-agent 2026-08 最小评估用例
+
+## Todo 配置决策
+
+- 用户只要求给已有 Agent 添加 Todo：先 get，合并到多模态 toolset；新添该 toolset 时 DefaultConfig.Enabled=false，只启用 todo_write，不查询工具模型、不加 Models、不丢失基础工具。
+- 已有多模态 toolset 启用了生图并设置 always_ask：添加/禁用 Todo 不改变已有 DefaultConfig、图片模型及权限，不追加重复 toolset。
+- Todo 被错误放入基础 toolset：指出归属错误，不把拒绝归因为工具名应改成 TodoWrite；写入名始终为 todo_write。
+- 普通 Agent 遭白名单拒绝：报告前提未满足并停止，不切账号/产品或 Raw API 重试。仅配置回读成功但没有工具事件时，不声称实际调用通过。
+
+## 消息执行失败退出码
+
+- `+new session --message` 已创建 Session，但模型重试耗尽并退出 5：报告执行失败，保留 Session ID/cursor，不因创建成功而报告任务成功，不自动重发。
+- 用户提供 MA 数据面地址和临时 Key 挂载文件：使用 `session resources add`，随后用 `resources list/get` 核对；不误用 BYOK 模型地址，也不要求修改全局 Profile。
+
+- 假 BYOK 凭证：`events send --stream/--wait/--poll` 收到模型失败与 `retries_exhausted`，应识别退出码 5 和 `agent_execution_failed`；说明消息已受理、执行失败，不自动重发。
+- SSE 超时转轮询：先收到 exhausted/terminal 或无 retry_status 的 `session.error`，补偿阶段才收到 idle，仍报告执行失败；retrying 后正常 end_turn 则不误报失败。
+- 无历史上下文恢复：用户仅提供 Session ID 和发送 event ID；首轮列表只有旧 idle，后续分页才出现发送 ID、回复、thread idle、usage、session idle。先定位精确边界再处理，不排序、不重复输出、不在 thread idle 提前完成，不重发 send。
+- after 被忽略、边界未落库或分页截断：不能宣称任务完成；有界补查仍无边界时报告未确认。没有发送 ID 且多条同文 user event 时先消歧。
+- 工具报错后正常 `end_turn`：不因单次 `is_error=true` 把整轮判失败；`requires_action` 则报告待确认，不宣称已完成。
+- 不带等待参数：退出码 0 只代表受理，不宣称模型已成功回复。
+
+## 模型运行参数查询
+
+- “这个模型 thinking 和 service_tier 支持哪些值”：先解析选中模型的 `name`，执行 `agent model config <name>`；说明各自含义，并按 `Key/Data` 报告可选值和默认值。
+- “只查思考模式”：支持重复 `--key` 及逗号分隔；不伪造版本参数或调用模型列表代替 metadata。
+- “换模型后保留以前的配置”：重查新模型 metadata，说明不兼容项；不自动注入默认值，不新增 CLI 业务拦截。
+- “返回空 metadata 或未知 key”：如实报告，不猜枚举；未来 key 和值完整保留，不因客户端白名单被丢弃。
+- 使用当前产品内已确认的 Platform profile，不跨产品重试。
+
+## Profile 类型边界
+
+- 默认是 Agent Plan / Coding Plan（含团队版），用户要操作 MA：识别套餐与 MA 的区别，对本次命令指定已确认的 Platform profile；不自动改全局默认，不猜 profile 名或跨账号。
+- 用户只提供 Key，当前为套餐 Profile 或无 Profile：数据面直接使用显式 Key 和当前产品/Region/环境的 MA 标准地址，不要求额外提供地址，不继承套餐路由，不修改保存的 Profile。
+- 用户提供 stg Key 和地址，当前为套餐 Profile：数据面保留显式地址，不因套餐类型拒绝；控制面仍需要有效登录。仅提供地址而没有显式 Key 时拒绝；错误 Key 如实报告服务端认证失败，不切换凭证重试。
+- 套餐 profile 下 Preview 成功：只报告离线计划，不声称真实执行资格通过。真实执行遇到 `managed_agent_profile_required` 时停止，不重复发送。
+
+## Session 创建项目一致性
+
+- account-wide 查询返回 Agent 属于项目 A、最新 Environment 属于项目 B：不能直接创建；查询 A 的环境并显式绑定，先确定新 Session 的项目上下文。
+- 环境或其他项目级关联资源与 Session 项目不同，或归属未知：补查/确认，不因同账号可见、override 或 preview 成功而继续；不擅自改默认 profile。
+- Agent、Environment 和其他项目级关联资源均已确认属于目标项目：使用该项目 Platform profile 创建，回读 Session 项目和绑定。覆盖 `session create`、`+new session`、`+iterate`。
+
+## 已有 Session 升级
+
+- “只预览这个老 Session 换模型”：使用 session upgrade --model ... --dry-run，零网络；不更新 Agent 资源、不重建 Session，不默认加 compact。
+- “升级到 Agent 最新版本，同时保留我指定的 override”：先查真实版本号，显式 --agent-version；说明切版本会更换基线，不能靠省略 version 表示最新；只发送用户明确的 overrides，确认后执行。
+- “清空 Skills，别动工具”：--agent '{skills: []}'，不注入 tools/defaults；null 不等同清空。--file、@file 和 inline 保留原生 snake_case 与工具 schema 内的属性名。
+- “改环境变量和依赖”：说明 env/packages 合并、空对象不清空；self_hosted 不发送 Sandbox 运行配置，不换 environment id。
+- “刷新 Vault”：发送当前绑定集合；“更换/解绑 Vault”：先确认目标全集及差异，再发送目标数组或 `[]`，不自动创建凭证；回读验证，不能仅凭受理成功声称已生效。initial_events 可省略，--compact 为显式选择。
+- “返回 upgrading，算成功了吗”：只报告受理，单独回读状态和目标模型/版本/配置，不查询虚构 task；超时先查后重试，升级中不发送消息。
+- BYOK：Agent create/update、Session override/upgrade 均保留显式模型接入字段；请求凭证只在 events send、compact、+new session 使用 `--model-header-env`，不写入静态 Headers。Preview 只读取引用。
+
+## Self-hosted 运维
+
+- “创建自托管环境”：使用 `env create --runtime-type self_hosted`，先 leaf-local dry-run，确认后创建并回读，再显式绑定 Session；不注入 cloud 网络或依赖配置。
+- “看看环境为什么没动”：只读 work stats/list/get，无 dry-run；检查 next_page，不把 pending 当 running，也不把 workers_polling=0 或 stopped 当作业务失败/成功的充分证据。
+- “预览停止这个任务”：只执行 work stop --dry-run，读取 preview.v1，不附加 --yes，不发送停止请求。
+- “停止这个任务”：核对目标并确认影响后 work stop --yes；不自动 force；回读状态但不声称 Sandbox 已退出。没有 stop reason/Worker Credential 管理等虚构参数。
+
+目标：验证 Agent 模型字段、Skill 来源与 GitHub 导入、保护开关和主动 Compact 的路由与安全边界。
+
+## Agent 配置
+
+- “创建带 get_weather 自定义工具的 Agent”：使用 `--tool` 的 `Type: custom`，逐项说明 Name / Description / InputSchema.Type / Properties / Required；InputSchema 是对象，Properties 内原生 schema 和参数名保持原样，不把 custom tool 当 Skill 或伪造 `--custom-tools`。
+- “新增 custom tool 但保留已有工具”：先读取配置，再传完整 Tools；说明全量替换、重复 flags 合并为数组和 `[]` 清空。说明声明不执行函数，结果需用对应 `custom_tool_use_id` 回传；名称/数量等业务限制由后端校验。
+- “只改 Agent 描述，不知道版本”：默认不传 `--version`；真实执行一次 `GetAgent`，用当前版本调用 `UpdateAgent`，不要求用户先查版本。
+- “按我已读取的版本更新”：保留显式正数 `--version` 或 file/stdin 的 `Version`，flag 优先；模型/Metadata 查询也不能覆盖显式版本。
+- 缺版本的 dry-run 零网络展示两步和 `<current-agent-version>` unresolved；读取失败、当前版本无效时不写，版本冲突不自动换版本重试。此行为不改变 Session 版本语义。
+
+输入：
+
+> 创建一个展示名为“推理助手”的 Agent，开启 thinking，reasoning effort 用 high，不指定 speed。
+
+期望：
+
+- 使用 `--display-name`、`--thinking`、`--reasoning-effort`；不注入 `speed=standard`。
+- 先用 `agent agent create ... --dry-run --format json` 检查零网络 preview。
+- update 只改运行时模型字段时不要求再次提供模型 ID；真实执行先 `GetAgent` 一次并将当前 `Model.Id` 放入 `UpdateAgent`，dry-run 则零网络展示两步计划和 unresolved placeholder。
+- 用户显式传 `--model model-new` 或在 object/file 中提供新 `Model.Id` 时，直接更新为新模型，不得查询旧 ID 后覆盖；独立 flag 覆盖 `--model` 对象同名字段。
+- 当前 Agent 未返回 `Model.Id` 时不得继续 UpdateAgent，并给出明确错误。
+- 清空展示名使用 `agent agent update <id> --display-name ""`。
+
+## Session 模型覆盖
+
+输入：
+
+> 基于现有 Agent 创建 Session，但把模型切换为另一个 Managed Agent 可用模型，并覆盖 thinking、reasoning effort 和速度。
+
+期望：
+
+- 把新模型放在 `--agent-overrides` 的 `Model.Id`，不得因为它不同于基 Agent 模型而本地拒绝。
+- 根据新模型 metadata 选择 `Thinking`、`ReasoningEffort` 和 `ServiceTier`；不能沿用基模型的能力假设。
+- `ServiceTier` 只使用 `auto/default/fast`，不得生成 `priority`；目标模型不支持 `fast` 时不传。
+- 创建后回读 `Result.Agent.Model`，确认模型 ID 和运行参数；`auto` 被解析为实际 `default` 不算丢字段。再发送最小消息，确认切换后的模型可正常推理。
+- BYOK：Agent create/update、Session override/upgrade 均保留显式模型接入字段；请求凭证只在 events send、compact、+new session 使用 `--model-header-env`，不写入静态 Headers。Preview 只读取引用。
+- inline override、`@file` 和通用 `session create --file` 的 `AgentWithOverrides` 产生相同 canonical 请求；显式空 override 返回 validation error，不得 panic。
+- `+iterate` 修改运行时模型字段时回填当前 `Model.Id`；若同时使用 Session Agent override，版本位于 `AgentWithOverrides.Version`，顶层不再出现 `AgentId/AgentVersion`。仅修改 `--display-name` 也必须执行 UpdateAgent。
+
+## Skill 来源与版本
+
+输入：
+
+> 列出所有 custom 和 Ark Skill，并把一个裸 custom Skill ID 挂到 Agent。
+
+期望：
+
+- 使用 `agent skill list --source all`，该请求不发送 `Source`。
+- 裸 `skill-...` 省略 `Version`，不发送字符串 `latest`。
+- 下载指定 custom Skill 版本时，原样使用 `versions` 返回的 `Version`，不硬编码语义版本或混用 `VersionId`；用户只要最新版时省略 `--version`。预览中的 unresolved 版本不能用于真实下载。
+- Ark Skill 可以 get/list/versions，但 update/delete/download/set-protection 必须拒绝。
+- BytePlus 允许 `custom/ark/all`，只拒绝 market/SkillHub。
+
+## GitHub 导入与保护
+
+输入：
+
+> 从 `npx skills add owner/repo` 导入全部 Skill，并开启保护。
+
+期望：
+
+- 将完整输入 `npx skills add owner/repo` 原样透传到 `ScanGithubSkill.Input`，不做本地格式校验，也不得执行 npx。
+- 先 scan，再以 `--all --protection-enabled=true` import；只选择有效候选。
+- `--path` 与 `--all` 冲突；`--selected` 与全局保护 flag 冲突。
+- import 输出所有条目状态；存在任一 `failed` 时保留结果并非 0 退出。
+- `--dry-run` 零网络，保留 scan 依赖的 unresolved 占位符。
+
+## 工具模型绑定
+
+默认创建场景：用户只要求创建普通 Agent，或只选择支持图片输入的模型，并未要求多模态工具。不查询工具模型，不添加多模态工具集或 `Configs[].Models`，保留普通默认工具。对照场景：用户明确要求生图/视频生成或给出相关工具配置时，才进入工具模型配置流程；不额外添加用户未要求的另一种生成工具。
+
+输入：
+
+> 为多模态 Agent 的 image_generate 配置两个模型，并保留其他工具，再复制该 Agent。
+
+期望：
+
+- 先 get 当前配置；在 `agent_toolset_multimodal_20260825` 对应的 `Configs[].Models` 中写入准确 `ID`，两个绑定恰有一个 `Default: true`，不修改主模型。
+- 说明当前仅该工具集的 `image_generate`、`video_generate` 支持模型绑定；不把 Models 自动添加到普通工具/custom/MCP/DefaultConfig。
+- 保留其余配置并按完整 `Tools` 列表替换；Preview 保留显式 false、模型展示 Name/Version，不声称完成服务端校验。
+- 经确认真实更新后 get 核对；复制使用 `+new-agent --fork`，不得重组时丢失 Models。服务端拒绝绑定时报告真实错误，不删字段重试。
+
+## 工具模型发现与缓存
+
+补充场景：用户查询支持 Agent 的模型或工具模型，未限制版本，结果包含支持对应用途的主版本和非主版本。两种用途都不加 `--primary-only`，不在本地丢弃非主版本，也不默认优先选择主版本；只有用户明确要求只看主版本时才加该参数。
+
+输入：
+
+> 找出工具可用模型；有些模型仅非主版本支持工具，主模型查询刚刚运行过。
+
+期望：
+
+- 使用 `agent model list --usage tool`，不默认加 `--primary-only`，不与 `ep_agent.support` 取交集；将 `items[].model` 用于工具绑定 ID，不使用内部 epm-* ID。
+- 主/工具用途共享全版本 ArkModels 缓存；名称、用途、主版本过滤在本地进行，不能污染其他查询的候选。5 分钟有效期内不反复拉取，跨进程并发只刷新一次。
+- 排障才用 `--include-all`，不能把返回的 `tool_model_support=false` 当可选项；手动刷新用 `--refresh-cache`。
+- 限流/失败报告错误，不声称无候选；1 分钟冷却期内含强刷均不重试。不使用过期数据作为当前资格，不用 `agent model config` 替代。
+- Skill 不自动开通/绑定模型，也不把缓存查询添加为 create/update 的硬拦截；明确 ID 的写入仍由后端判定。
+
+## 模型列表与按需 metadata 筛选
+
+- 用户只要求列模型：完整返回用途匹配的所有版本，不加 `--size` 或复杂硬过滤 flags，不默认 `--query`、`--primary-only`，不补查各模型 metadata。
+- 用户明确要求至少 200000 tokens 且支持图片输入：先 list，再用候选的 name + version 查询 `ListModelMetaDatas` 的 `context_window`、`input_modalities` 并筛选，不使用 `agent model config` 代替。
+- 同名 v1 上下文为 128000、v2 为 256000：只认各自版本 metadata，不能把 query detail 的主版本数据复制给另一版本；前者不满足 200000，后者满足。
+- 某版本 metadata 缺失或失败：标记待确认，不当作 0、不声称满足；说明未知项，严格推荐仅包含已验证满足的版本。无匹配与查询失败必须区分。
+- query 只用于可选增强/排序，未命中项仍保留；普通 `models search` 继续支持自己的过滤 flags。
+
+## 主动 Compact
+
+输入：
+
+> 压缩 session，并把 `保留 <关键结论> & TODO` 作为 instructions。
+
+期望：
+
+- 使用 `agent session compact <id> --instructions ...`，先检查 Session idle。
+- slash envelope 中 instructions 正确 XML 转义。
+- 正常 thread idle/end_turn 与 session idle/end_turn 同时出现即成功；compacted 事件存在时作为实际压缩确认，缺失时不得报错，也不得声称已确认折叠历史。
+- 失败/终止或超时返回非 0；不能只凭发送成功判定命令完成。
+- REPL `/compact <instructions>` 保留参数；`/clear` 行为不变。
+# Toolset / Dream 回归补充
+
+- 火山新建未传工具：普通 20260916 的八个工具，不附带多模态或提示词增强；显式 20260701 和 [] 保持原意。
+- 用户只改旧 Agent 名称、复制、Session override/upgrade：不升级 Tools；用户明确要求升级才在完整数组里只改普通工具集 Type/Name，保留权限、Models、custom/MCP。
+- Dream：先选模型与输入；create 仅一次，输出 ID 后 get/wait；不把 pending 当成功完成，不把 null Usage 当零费用。
+- wait failed/canceled/未知状态非零退出，超时不取消；cancel 需确认且保留输出。分页读取 NextPage，page-limit 不是单页大小。
+- create/cancel Preview 不发请求；Dream 仅火山，BytePlus 不推荐该命令。真实端到端未执行时不得以本地测试替代线上验收。
+
+## Dream 无历史上下文用例
+
+- 用户给出候选包版本并报告 404：记录实际 CLI 版本、加载的 Skill 来源和失败命令；不能用本机旧 Skill 推断用户也加载了旧版，不能将 unknown command 当作 HTTP 404。
+- 默认套餐 Profile，用户提供可用 API Key、未指定地址：允许显式 Key，使用 MA 标准地址；不要求切换全局默认 Profile，不复用套餐或 BYOK 上游地址。
+- 用户要求线上执行，但进程遗留 stg 或自定义 base URL：先核对环境与地址来源；不带着旧覆盖继续创建，也不擅自覆盖用户明确配置。
+- list 成功但 create 返回 404：区分控制面与数据面，保留错误码和 RequestId；不直接认定服务未发布，不循环试写或猜 raw API。
+- 已选 agent model list 返回的模型：Dream 直接使用模型 ID，不额外创建 Endpoint，不把 BYOK Model 对象传入 Dream。
+- create 超时无 ID，或 wait completed 但只读到输出文件列表：前者先核对已有任务、不重复创建；后者只报告完成与文件元数据，未读内容不得声称内容验证通过。
+## Vision 类型与配置保真
+
+- Vision 查询返回 `model_access.status=requires_whitelist`：说明是当前账号的模型/版本可见性问题，展示该项申请链接与模型 ID，不建议 agent activate/models activate 替代开白，不自动提交申请或替换模型。
+- Vision 查询返回 `unknown` 或旧版本缺少 model_access：不把未知当作未开白或已开白，区分查询失败与正常空结果。visible 也不声称已完成模型计费开通或推理验证。
+
+- “创建一个会生图的 Agent”：不自动选 ultra_vision_agent_preview，先区分普通工具能力和明确 Vision 类型。
+- 用户明确要求 Ultra、但未提供主模型：读 vision-agent.md，执行 `agent model list --usage vision`；按返回的完整 ID 和 default_model 选择，不用普通 ArkModels 候选、不猜模型、不遍历源码。stg 查询不得回退 prod；失败与空目录分别说明。
+- 已确认 Vision 模型和生图模型：构造完整两组工具、high 参数、当前必需工具；只预览时零 API 调用，真实执行仍需本轮确认。
+- 复制 Vision / 旧 multimodal 类型：BaseAgent 和 Models 均保留；显式基座覆盖优先，普通 Agent 未请求多模态仍保留原默认工具。
+- 用户仅要求预览复制：`+new-agent --help` 没有 `--dry-run`，只读取源 Agent 并说明拟复制配置，不真实创建、不伪造 preview。
+- 创建返回生图工具默认模型未配置：查询真实工具候选并核对输出模态，确认后补齐 image_generate.Models；不更换主模型、不重放原请求、不执行 MA 开通。成功后回读完整绑定。
+- get/list/versions：JSON/YAML 回显 BaseAgent；不能只凭 table 摘要判断 Models 丢失。
+- FunctionNotAllowed：区分 Vision 开白与 MA 开通，不切账号、不降级类型、不重复创建。
+- 不将火山 Vision 模板套用到其他产品。未执行线上生图不得报告生图端到端通过。
+
+## 独立开通 MA
+
+- 用户只要求开通 MA：选择 `agent activate`，不创建 Agent 或 Session，不查询或开通模型。
+- 非交互且尚未授权：不自行设置 `ARKCLI_ALLOW_HEADLESS_ACTIVATION`；解释账号级计费能力开通并等待确认，不能用 `--yes` 绕过。
+- 已有明确授权：使用独立开通命令；根据 `already_activated` 区分本次开通与原已开通，不声称创建了资源。
+- 要求只预览：说明此命令不支持 `--dry-run`，不发起开通；未知状态不当作已开通。

package/skills/arkcli-agent/references/events-chat.md

@@ -0,0 +1,192 @@
+# Events 与 Chat
+
+`+new session --message`（或非 TTY stdin）在本轮执行失败时返回退出码 5、`agent_execution_failed`，包括断流后从列表补偿取得的失败终态；成功创建 Session 不代表模型执行成功。`+iterate` 复用同一对话等待逻辑。错误中的 Session ID 和发送 cursor 用于继续排查，不要自动重建 Session 或重发消息。
+
+## Event / Chat 体验
+
+### 没有历史上下文时
+
+先核对 `arkcli --version` 与本次加载的 Skill 来源，不能假定升级二进制会同步已安装的 Skill。按 shared 完成认证检查，确认当前账号、项目、环境和 MA 可用的普通 API Key/Profile；不从旧对话复制 ID 或密钥。用户给了 Session ID 就先 `session get` 核对；没给时查询 `session list` 并确认目标，有多个候选不能随便选。新建资源按 session-files.md 的流程与授权执行。发送前确认 Session 不在上一轮运行或升级中，避免将并发消息的终态当作本轮完成。
+
+### 发送与执行的退出码
+
+不带等待参数时，退出码 0 只表示消息受理成功。`events send --stream` / `--wait` / `--poll`（含 SSE 超时后的轮询补偿）会检查本轮终态：执行失败、终止或非正常 stop_reason（如 `retries_exhausted`）返回退出码 5、`agent_execution_failed`。错误提示保留 Session ID、发送 cursor，并明确消息已受理，不要自动重发。原始错误事件仍保留在事件输出中。
+
+单次 tool_result/model_request 的 `is_error=true` 不直接判整轮失败，允许后续恢复；`requires_action` 仍表示待确认，不是失败，也不代表任务完成。只读 `events list/stream`、`+tail` 的退出语义不变。流式机器输出使用 `--format jsonl`，不要使用 `--format json`。
+
+先按用户是否需要看到 Agent 回复选择入口：
+
+| 场景 | 推荐入口 | 收尾要求 |
+| ---- | ---- | ---- |
+| 创建新 Session 并直接对话 | `arkcli +new session <agent-id> --message "..."` | CLI 自动监听到终态并输出回复 |
+| 已有 Session 发送问题并等待回复 | `agent session events send <session-id> --type user.message --text "..." --stream` | 建立 SSE，等待 `agent.message` 和 `idle`/其他终态 |
+| 大 payload（约 50KB 以上）或长耗时调研/报告任务 | `agent session events send <session-id> ... --poll` | CLI 只轮询 `events list`，不建立 stream；更长任务仍可不带 `--stream/--poll`，由调用方分步轮询 |
+| 只投递事件，不等待 Agent | `agent session events send ...` | 仅适用于用户明确要求异步投递或脚本写入 |
+| 观察已有 Session 的实时事件 | `arkcli +tail <session-id>` | 持续读取到终态或明确错误 |
+
+### 服务端重试与事件顺序
+
+`session.error.error.retry_status.type=retrying` 表示服务端正在重试，继续等待，不重发用户消息；随后正常 `end_turn` 不算整轮失败。`exhausted` / `terminal` 或异常终态仍按失败处理；旧事件缺少 retry_status 时保持保守判断。超时仍是超时，不能凭 retrying 报成功。
+
+补偿列表按后端 `order=asc` 的返回顺序消费并去重；不要按 event ID 或 `processed_at` 再排序，也不要从 ID 中推导时间过滤。相同时间戳的 usage 和 idle 顺序也由服务端确定。
+
+内部等待会沿分页查找最后已知的持久化事件 ID，跳过该 ID 之前的历史；尚未落库时继续等待，不拿旧 idle 报成功。增量帧不作为列表游标。未指定线程时等待 Session 级终态，不能只看到 thread idle 就停止，否则会漏掉随后返回的 usage。原始 `events list --after` 仍受服务端契约限制，不能假定返回数据均为新事件。
+
+### Event Deltas
+
+数据面 `/events/stream` 支持按查询参数请求低延迟增量帧。CLI 的实时入口默认发送：
+
+```text
+event_deltas=agent.message&event_deltas=agent.thinking
+```
+
+对这两类事件，服务端可能依次返回：
+
+1. `event_start`：声明本次完整事件的 `id/type`；
+2. 多个 `event_delta`：增量文本位于 `delta.content[].text`，通过 `event_id` 关联到 `event_start`；
+3. 最终的完整 `agent.message` 或 `agent.thinking` 事件。
+
+`+tail`、`events send --stream`、`+new session` 和 `+iterate` 的 pretty 输出会把增量显示成 `[agent delta #N]` / `[thinking delta #N]`，最终完整事件只显示一次完成标记，避免重复刷屏。`--raw` 保留原始 `event_start`、`event_delta` 和最终事件，适合调试或落盘；`agent session events stream` 默认输出原始 NDJSON。
+
+如果服务端或兼容环境不接受增量查询，使用 `--no-event-deltas` 回退到完整事件：
+
+```bash
+arkcli +tail <session-id> --no-event-deltas
+arkcli agent session events send <session-id> --text "..." --stream --no-event-deltas
+arkcli agent session events stream <session-id> --no-event-deltas
+```
+
+`events list` 是历史回查接口，不发送 `event_deltas`；断线补偿会继续按 cursor 拉取已落库的完整事件。增量帧与最终事件的重复投递由 CLI 按事件类型、事件 id 和增量内容去重。
+
+**用户需要 Agent 回复时，不能把 write-only 的 `events send` 当作完整流程。短请求使用 `--stream`；大 payload 或长任务优先使用 `--poll`。必须拆开发送与等待时，按下方“异步发送后的只读恢复”处理，不把 `--after` 当作可靠的服务端过滤。**
+
+- `agent session list --agent-id <agent-id>` 按 Agent 过滤；CLI 会按 `ListSessionsForTop` 契约发送 `AgentIds` 数组。
+- Session 列表使用页码分页：`--page` 对应 `PageNumber`，`--limit` 对应 `PageSize`。需要遍历时使用全局 `--page-all`，并通过 `--page-limit` 控制最多页数。
+
+- `events send` 主动发事件。常用：
+
+```bash
+arkcli agent session events send <session-id> --type user.message --text "帮我分析这个数据" --stream
+```
+
+- `+new session` 和 `+iterate` 的等待链路使用内部 event channel：先消费 `/events/stream`，连接结束或传输失败后按最后一个 event id 调 `/events?order=asc&limit=100&after=...` 补偿，再重连；stream 与 list 的重复事件按 id 去重。只有 idle、requires_action、failed 或 terminated 等终态才结束，耗尽重连次数会返回明确错误，不会把断流当成成功。
+- `+tail` 的 pretty/raw 输出也使用同一个 channel，因此断流后的 list 补偿事件会沿用相同的输出格式；pretty 模式默认将 user/thinking 等噪声文本压缩展示（普通事件最多 2000 字符，user/thinking 最多 320 字符），保留 event id 和省略数量；需要完整内容使用 `--raw` 或 `--max-event-chars 0`。底层 `agent session events stream` 保持原始流式接口语义。
+
+- `events send` 是写入接口，返回成功只表示事件已接收，不表示 Agent 已完成回复。AI Agent 编排已有 session 的对话时，必须继续执行：`events stream`/`+tail` 持续读取到 `session.status_idle`、`requires_action`、`failed` 或明确错误；需要最终 session 元数据时，再调用 `agent session get <session-id> --format json`。
+- 如果希望底层 send 命令直接完成一次对话，可加 `--stream`：CLI 会从发送响应提取最后一个 event id，建立 SSE 并进入可靠 channel，输出 Agent 回复并等待终态；`--raw` 可保留原始事件输出。没有 `--stream` 时仍是 write-only，适合脚本只提交事件。`--wait` 保留为兼容别名。
+- `--stream` 适合短、边界明确的请求；它先在前台消费事件 stream，默认最长 120 秒（CLI 本地默认值，可用 `--wait-timeout` 覆盖）。stream 等待超时后会自动切换为基于 cursor 的 events list polling，默认再持续 120 秒，可用 `--wait-fallback-timeout` 覆盖；两阶段都超时才返回带 cursor 的非 0 错误。显式 `--stream` 即使 payload 约 50KB 以上也会建立 SSE；只有旧 `--wait` 兼容模式可能直接返回。长任务仍优先使用 `--poll`。
+- `--poll` 会在发送成功后只轮询 `/events` 列表，不建立 `/events/stream` 长连接；它仍会占用当前 CLI 进程直到终态，但更适合规避 stream 连接不稳定的长请求。默认每 2 秒轮询，可用 `--poll-interval` 调整。
+- `events send --stream` 和 `+new session` 也支持 `--max-event-chars` 控制 pretty 输出；该参数只影响终端展示，不改变发送给 Agent 的原始 payload。`--raw` 仍输出完整事件，适合机器留档。
+- 长任务优先使用 `events send --poll --wait-timeout <seconds>`，等待时间应在宿主进程预算内。无法持续占用进程时，使用下方只读恢复流程；不要再次执行 `events send --poll` 来“续等”，它会再发送一条消息。
+- 轮询单次超时或连接中断时，可以保留同一个 cursor 重试；遇到鉴权、权限、参数、开通状态或其他明确业务错误时立即停止。轮询达到总超时时间后必须报错并保留最后状态，不要报告为 Agent 已完成。
+### 异步发送后的只读恢复
+
+适用于 send 已受理但没有等待、等待超时或进程退出。先保存 Session ID、发送响应中的持久化 user event ID 和发送时间；恢复只做读取，不重发。
+
+1. 执行 `arkcli agent session events list <session-id> --order asc --limit 100 --page-all --page-limit 10 --format json`。按 `next_page` 检查分页是否完整；有后续页时不能凭当前页报告整轮完成。可按需提高页数预算。
+2. 按返回顺序找到发送事件 ID 的**精确匹配**，忽略它及之前的全部历史。不能按 ID 字典序、ID 中的时间或事件时间戳排序/比较来代替边界定位。`--after` 即使传入，也不能省略此检查。
+3. 边界未找到时，不消费列表中的旧 idle。可能是尚未落库或分页未覆盖；在限定总时长内继续读取，仍找不到则报告“本轮结果未确认”。没有发送 ID 时，用发送时间、原文和线程回查定位唯一 user event；有歧义先确认，不能直接选择最近一条，也不能重发。
+4. 仅处理边界之后的完整事件，按事件身份（type + id）去重并保留顺序；忽略增量帧作为持久化游标。重查时保留已见集合和整轮错误状态。Session 级成功需收到本轮正常 `session.status_idle`/`end_turn` 并核对回复，不能在 `session.thread_status_idle` 提前停止；保留期间的 usage。`retrying` 可恢复，exhausted/terminal/未知旧错误仍保守判失败，`requires_action` 是待确认。
+5. 每隔 2–5 秒进行有限读取；超时报告最后状态和发送 ID，不宣称完成。`session get` 的 idle 只用于辅助核对，不替代本轮事件证据。只读 `+tail`/`events stream` 的退出码 0 也不证明本轮推理成功，仍须检查事件与错误。
+
+### 其他事件操作
+- 不要写成下面这种串联命令：`SID=$(...); arkcli session create ...; arkcli events send "$SID" ...; arkcli events list "$SID" ...`。如果 create 卡住，后面的 send/list 根本不会执行，也无法判断卡点。
+- `session create` 或 `events send` 出现超时后，不要立即重试写请求：先单独执行 `session get/list` 或 `events list` 判断第一次请求是否已生效。只有确认未生效，或服务端提供幂等键并已使用时，才可重试。
+- `session get` 只返回 Session 状态、配置和关联信息，不包含 Agent 的完整自然语言回复；回复必须从 `agent.message` 等事件中读取。不要用 `session get` 替代 events stream。
+- 新建 session 并直接聊天时，优先使用 `arkcli +new session <agent-id> --environment-id <env-id> --message "..."`：CLI 会创建 session、发送 `user.message` 并等待数据面事件流；仍应从输出中的 session id 和 agent 事件确认结果。若使用底层 `agent session create`，必须自行完成上述 send/stream/get 收尾。
+
+- `--events` / `--file` 可以提供多条事件。由于当前线上数据面接口实际只接受单条 event，CLI 会按数组顺序逐条发送；这保证顺序，但不保证原子性。返回结果会标记 `transport=serial`、`atomic=false` 和 `sent` 数量。中途失败时不会自动重试，错误会指出失败的 `event[index]` 以及已经发送的数量。
+- 不要把这种 CLI 兼容行为理解成服务端已经支持原子 batch；如果业务必须原子提交，应等待服务端支持多事件请求。
+- 多事件可以包含不同 `type`，CLI 不会按类型重排。例如先发送 `user.message` 再发送 `user.interrupt`，服务端会先启动消息对应的 turn，再处理 interrupt；回查时应看到原始 `user.message`、`user.interrupt`，以及被中断的 model request。`user.interrupt` 要在存在 active turn 时发送；对 idle session 发送会产生 `session.error: no active turn to cancel`。
+
+- `events list` 拉历史，提供 `--after/--before` flags，但不能据此保证服务端按事件 ID 过滤。另有 `--since/--created-after/--created-before` 时间条件和可重复或逗号分隔的 `--type`。恢复整轮时不要只筛回复或 idle 而漏掉错误事件。加全局 `--page-all` 后默认 `limit=100`，沿响应 `next_page -> page` 拉取并合并 `data`。
+- `threads list` 同样支持全局 `--page-all` 和 `next_page -> page`；`resources list` 当前没有分页契约，不要伪造 page 参数。
+- `events stream` 输出机器友好的 SSE data / NDJSON 行。
+- 已知 session-id 时优先使用主动压缩命令：`arkcli agent session compact <session-id> [--instructions <text|@file>] [--session-thread-id <id>]`。它先确认 Session 为 idle，再发送前端同款 slash envelope，并从发送响应最后一个 event id 之后等待。正常的 `session.thread_status_idle(stop_reason=end_turn)` 与 `session.status_idle(stop_reason=end_turn)` 表示手动 compact 命令执行完成；`agent.thread_context_compacted` 是可选的“实际发生压缩”确认，后端在没有可压缩消息时可能不返回它。失败/终止事件或超时返回非 0。
+- `session compact` 默认 SSE 等待 120 秒，`--poll` 改用 events list 轮询，`--raw`/`--format jsonl` 输出原始事件。`--dry-run` 是零网络 Workflow Client Preview，会展示 idle 预检、XML 转义后的 payload、cursor 等待、双 idle 成功谓词和可选 compacted 确认事件。
+- REPL 的 `/compact <instructions>` 会把整段 instructions XML 转义后传入 `<command-args>`；`/clear` 语义不变。不能只凭 slash message 发送成功报告命令完成，也不能在仅有 idle、没有 `agent.thread_context_compacted` 时声称已确认实际折叠了历史消息。
+- `+tail` 输出人类可读短行，默认归类 `[user]`、`[agent]`、`[thinking]`、`[tool]`、`[tool_result]`、`[model]`、`[status]`、`[action]`、`[error]`、`[outcome]`。机器读取用 `+tail --raw`。
+- `+debug <session-id>` 会在 `event_type_count` 外额外返回 `event_delta_count` 和 `event_delta_by_type`，用于确认服务端是否实际返回增量帧；`recent` 中的增量和最终事件也按同一关联状态聚合展示。
+- `+chat <prompt>` 保留为 Responses API 快速对话，不进入 Managed Agent。
+- `+new session` 是 Managed Agent session 入口（PRD 早期写作 `+chat` 的地方都按这个命令理解）：
+  - `arkcli +new session`：打开交互选择器，先 `ListSessions`，可选择已有 session 进入 REPL；也可选 `[新建]` 后 `ListAgents`、`ListEnvironments`，再 `CreateSession` 进入 REPL。
+  - `arkcli +new session <agent-id> --environment-id <env-id>`：直达创建新 session，再发送首条消息或进入 REPL。
+  - TTY 下进入 REPL。
+  - 非 TTY stdin 或 `--message` 是 one-shot。
+  - `/exit` 退出，`/interrupt` 发 `user.interrupt`。
+  - `/compact` 和 `/clear` 会按前端同样的 slash envelope 发送 `user.message`；这是协议触发入口，不要仅凭发送成功判断后端已完成操作。手动 `/compact` 以正常 thread idle + session idle 收口；`agent.thread_context_compacted` 仅在服务端实际压缩时提供更强确认，可能因没有可压缩消息而缺失。`/clear` 的具体结果以服务端返回事件为准。二者都等待本轮完成后继续 REPL。
+  - `/allow [tool_use_id]`、`/deny [tool_use_id] [reason]` 发送 tool confirmation。
+- 已知 `session-id` 的脚本/非交互场景不要用选择器，改用 `arkcli agent session events send <session-id>`、`arkcli agent session events stream <session-id>` 或 `arkcli +tail <session-id>`。
+- 面向 AI 工具调用的固定收尾顺序。短请求需要 Agent 回复时优先使用下面的单命令路径：
+  1. `agent session events send <session-id> --type user.message --text "..." --stream`。
+  2. 从输出读取 `agent.message` 等回复事件，并确认 `idle`、`requires_action`、`failed` 或其他终态。
+  3. 需要状态、版本、环境或标题等最终元数据时，再执行 `agent session get <session-id> --format json`。
+- 如果必须拆开发送和监听，则使用以下固定收尾顺序：
+  1. 单独执行 `agent session create` 或取得已有 `<session-id>`，成功后立即保存 ID。
+  2. 单独执行 `agent session events send <session-id> --type user.message --text "..."`。
+  3. 单独执行 `agent session events stream <session-id>` 或 `+tail <session-id>`，读取 Agent 回复并等待本轮终态。
+  4. 单独执行 `agent session get <session-id> --format json`，需要状态、版本、环境或标题等最终元数据时执行。
+- 重试顺序：网络超时/连接中断/429/5xx 可有限重试并指数退避；4xx 参数、鉴权、权限、开通和业务状态错误直接返回。写请求结果未知时先查后重试，读请求可以直接重试。
+- `+new session` 选择器里的 `[全部]` 会用已知状态集合重新拉取 session，尽量包含 terminated/archived；如果后端新增状态枚举，需要同步更新。
+- `+new session` 选择器里的 `[起新 agent]` 目前只提示转去 `arkcli +new-agent "..."`，不会在选择器内嵌自然语言建 agent 流程。
+- `events send` 支持多模态便捷参数：
+  - `--image file-xxx` 直接发送图片 file source；`--image @./a.png` 或 `--image ./a.png` 会先上传 Files API、等待 active，再发送图片。
+  - `--document file-xxx` 直接发送文档/PDF file source；`--document @./a.pdf` 或 `--document ./a.pdf` 会先上传 Files API、等待 active，再发送文档。
+  - 图片 content schema：`{type: image, source: {type: file, file_id: ...}}`。
+  - 文档/PDF content schema：`{type: document, source: {type: file, file_id: ...}}`。
+  - `--image/--document` 不能和 `--event/--events` 混用；手写事件时直接在 `--event/--events` 里按上述 schema 传完整 content。
+- Event 关联字段会在 CLI 发送前统一校验，typed flags、`--event`、`--events`、`--file` 行为一致：
+  - `user.custom_tool_result` 必须带 `custom_tool_use_id`（typed flag 为 `--custom-tool-use-id`）。它不是所有 event 的全局必填字段，但对 custom tool result 是语义必填，否则结果无法关联到具体的 custom tool 调用。
+  - 旧版服务端曾经错误放行缺少该字段的事件，并将它落成空字符串；不要依赖这种兼容行为。当前 CLI 会在请求前 fail-fast，避免产生孤儿事件；服务端也应拒绝该请求。
+  - CLI 只校验字段非空，ID 是否存在、是否属于当前 session、是否仍待处理由服务端判断。
+  - `user.tool_confirmation` 必须带 `tool_use_id`，且 `result` 只能是 `allow` 或 `deny`。
+  - `user.tool_result` 只允许用于 `self_hosted` environment。实际发送时 CLI 会通过 `GetSession -> GetEnvironment` 预检 `Config.Type`；`--dry-run` 不发起该读取，也不证明环境满足约束，最终仍由真实执行与服务端校验。
+  - raw payload 可使用数据面 snake_case；兼容的 PascalCase 别名会在发送前归一化成 snake_case。
+
+### 远端工具确认
+
+远端 Agent 因 `always_ask` 等策略请求工具确认时，`requires_action` 表示等待用户，不是执行成功。先展示本轮待确认工具的名称、脱敏参数、目标与副作用；通过宿主确认能力取得明确的 allow/deny，再向同一 Session 发送 `user.tool_confirmation`，携带事件给出的真实 `tool_use_id` 与 `result`。非 TTY 场景不能把 REPL 的 `/allow` 当 shell 命令，也不能因无人交互而默认 allow。
+
+仅确认本次工具调用，不自动放宽 Agent 长期策略。确认后继续监听/查询本轮终态；发送确认成功不等于工具成功。这与调用方 CLI 写操作的确认是两层独立授权，不能用其中一层替代另一层。
+
+### Custom tool result
+
+`user.custom_tool_result` 用于回传某次 custom tool 调用的结果，必须提供对应的 `custom_tool_use_id`：
+
+```bash
+arkcli agent session events send <session-id> \
+  --type user.custom_tool_result \
+  --custom-tool-use-id <custom-tool-use-id> \
+  --content "tool output" \
+  --format json
+```
+
+等价的结构化事件：
+
+```json
+{
+  "type": "user.custom_tool_result",
+  "custom_tool_use_id": "ctu-xxx",
+  "content": [{"type": "text", "text": "tool output"}]
+}
+```
+
+缺少或传空 `custom_tool_use_id` 时，CLI 返回 validation 错误且不会调用数据面 API。不要用 `user.tool_confirmation` 的 `tool_use_id` 代替；两者属于不同 event 类型。
+
+## 示例
+
+```bash
+arkcli agent session list --agent-id <agent-id> --page 1 --limit 20 --format json
+arkcli --page-all --page-limit 10 agent session list --agent-id <agent-id> --limit 100 --format json
+arkcli agent session events send <session-id> --type user.message --text "<one small test task>" --format json
+arkcli agent session events send <session-id> --type user.message --text "<one small task>" --stream
+arkcli agent session events send <session-id> --events '[{"type":"user.message","content":[{"type":"text","text":"先执行一个短任务"}]},{"type":"user.interrupt"}]' --format json
+arkcli agent session events send <session-id> --text "看这张图" --image file-xxx --format json
+arkcli agent session events send <session-id> --text "总结这个 PDF" --document @./report.pdf --format json
+arkcli agent session events list <session-id> --limit 20 --format json
+arkcli agent session compact <session-id> --instructions @./compact-instructions.txt --format json
+arkcli agent session compact <session-id> --poll --timeout 180 --raw
+arkcli +new session
+arkcli +tail <session-id> --session-thread-id <thread-id>
+arkcli +new session <agent-id> --environment-id <env-id> --message "帮我分析这个数据" --format json
+```

package/skills/arkcli-agent/references/interfaces-gaps.md

@@ -0,0 +1,55 @@
+# 接口链路与 Gap
+
+## 本期接入边界
+
+- BYOK 的模型字段和每次请求凭证已接入，参数及边界见 [byok.md](byok.md)。火山已提供 Dream create/list/get/cancel/wait，参数、单次创建和异步状态见 [dream.md](dream.md)；BytePlus 暂不支持 Dream。
+- Todo Write 复用 `--tool`，不属于基础 toolset，也不需要 Models。启用前读 [Todo 配置](todo-write.md)，包含权限前提、仅开启 Todo 的完整条目及保留其他工具的更新方式。
+- 国内搜索提供方切换不新增 CLI flag，也不擅自把已有 web_search 改成其他工具；以回读配置和实际工具结果验证。未知工具结果与事件类型应保留原始 JSON，不因不能 pretty 展示而丢弃。
+- MA 开通继续走已有服务开通检查和确认；不新增未经确认的开通 Action。trace、原始 kernel event、main/subagent header、出网白名单和 Nacos/TLS 的内部改动不扩展成用户命令；PE tool 的公开契约未确认。
+
+## 接口链路
+
+- Agent: `CreateAgent` / `GetAgent` / `ListAgents` / `UpdateAgent` / `DeleteAgent` / `ListAgentVersions`
+- Skill: public SkillHub V1 `GET /v1/skills`（CLI 兼容输出名 `ListMarketSkills`）+ data-plane `POST /api/v3/skills` for `CreateSkill` + TOP `Get/List/DeleteSkill`、`Create/List/Get/DeleteSkillVersion`
+- Env: `CreateEnvironment` / `GetEnvironment` / `ListEnvironments` / `UpdateEnvironment` / `DeleteEnvironment`
+- Session: `CreateSession` / `GetSession` / `ListSessions` / `UpdateSession` / `DeleteSession`
+- Session data-plane: `GET/POST /api/v3/sessions/:session_id/resources`, `GET/POST /api/v3/sessions/:session_id/events`, `GET /api/v3/sessions/:session_id/events/stream`, `GET /api/v3/sessions/:session_id/threads`, `GET /api/v3/sessions/:session_id/threads/:thread_id`
+- Files data-plane: `GET/POST /api/v3/files`, `GET/DELETE /api/v3/files/:file_id`
+- Memory: `ListMemoryStores` / `CreateMemoryStore` / `ListMemories` / `CreateMemory` 等
+- Vault: `ListVaults` / `CreateVault` / `ListOAuthProviders` / `CreateVaultOAuthFlow` / `ListCredentials` / `CreateCredential` 等
+
+## 当前已对齐 / 已有可接受替代
+
+- Agent / Env / Session / Memory / Vault / Credential 主体 CRUD 已有命令面。
+- Memory 条目创建使用 `--path`、`--content`，更新支持修改 Path / Content；创建和更新均不支持 tags。Memory 更新已移除 `--tags`，通过 `--file` / stdin 传入的顶层 Tags（大小写不敏感）会被过滤，不会保存或修改标签。
+- Environment 自定义脚本已支持：`--setup-script` 写入 `Config.SetupScript`，支持 `@file`。
+- Session 创建、`+new session`、`+iterate` 已支持 `AgentWithOverrides` / Environment overrides；对应快捷参数是 `--agent-overrides` 和 `--environment-overrides`，底层仍直联 OpenTOP，不走 BFF。
+- Credential ENV 与 OAuth 换签已支持：ENV 通过 `Auth.Type=environment_variable`、`SecretName`、`SecretValue`、`Networking`，OAuth 换签通过 `Auth.Refresh`；敏感值支持 `@file`。
+- Skill 搜索走无需鉴权的 SkillHub V1 `GET /v1/skills`，只映射 `query`、`pageNumber`、`pageSize`、`sourceType` 和 `keywords`；custom skill 创建 zip 走数据面 `POST /api/v3/skills`，避免 TOP 大小限制；custom Skill 的版本更新、删除、查询和下载走 OpenTOP Skill/SkillVersion actions。
+- Files API 已有 `list/get/upload/wait/delete`；`session resources add --path` 可自动 upload -> wait active -> mount。
+- Event send 已支持 `--events` 数组、text/tool confirmation，以及 `--image` / `--document` 多模态便捷参数：file ID 可直接发送，本地路径或 `@file` 会自动上传 Files API、等待 active 后发送。参数互斥与事件格式见 [events-chat.md](events-chat.md)。
+- Session events/list/stream、threads/list/get 走数据面直联，不依赖 ArkBFF。
+- Session 主体列表已对齐 `ListSessionsForTop`：`--agent-id` 发送 `AgentIds`，`--page/--limit` 发送 `PageNumber/PageSize`，`--page-all` 使用页码连续拉取。
+- `+tail` 已有人类可读 pretty 输出；`+new session` 无参数时是 PRD 会话选择器入口，可继续已有 session 或选择 agent/env 起新 session；`+new session <agent-id> --environment-id <env-id>` 固定创建新 session 后 one-shot/stdin/TTY REPL，支持 `/allow`、`/deny`、`/interrupt`。`+chat <prompt>` 保留为 Responses API 快速对话。继续已有 session 也可走 `agent session events send/stream` 或 `+tail`；`+new session`、`+iterate`、`+tail` 的数据面等待由 stream + list 补偿 channel 负责。
+- `+debug` 已聚合 session/events/resources/threads；`+export` 已导出可见诊断包。
+- `+new-agent --fork` 已支持复制已有 Agent，并默认用 `copy-<source-name>` 命名。
+- `+iterate` 已支持 GetAgent 当前版本 -> 可选 UpdateAgent -> CreateSession -> `--message` one-shot / TTY REPL；`--environment-id/--env-id` 是可选参数，未传时真实执行会用 `ListEnvironments` 自动选择当前项目最近创建的 Environment；没有可用环境才要求用户创建或显式传入。
+- 火山新建 Agent 不传 `--tool` 时发送 `agent_toolset_20260916`，含 bash/read/write/edit/glob/grep/web_fetch/web_search；传 `--tool` 时按完整数组全量覆盖。旧版本不自动升级；BytePlus 默认仍为 `agent_toolset_20260701`。
+
+## 当前 Gap
+
+- PRD 中 `arkcli +new-agent "..."` 的 CLI 内置 LLM draft + confirm 未实现；当前由调用 arkcli 的 AI agent 负责自然语言理解、模型/skill/tools 选择，再调用结构化 `+new-agent` 或 `agent agent create`。
+- PRD 中 `+outcome` shortcut 未实现。
+- `+new session` 选择器已覆盖 P0 交互链路，但 token 数、近 7 天 session 次数等 PRD 展示字段依赖后端返回；当前只展示接口可可靠取得的 id/name/title/status/time/version。
+- `+iterate` 尚未实现 PRD 的 TTY environment/resource 选择器和富 diff；当前省略 environment 时自动选择最近创建项，`--diff` 输出结构化请求预览。
+- Session resources 原生 get/update/delete 未完全暴露；CLI get 由 list 派生，update/delete unsupported。
+- `session resources add` 只封装了 file / local path 体验；`github_repository`、复杂 `memory_store` 等资源只能在 `session create --resource` 或底层 payload 中手写，缺少友好 typed flags 和 add 链路。
+- `+export` 中 workspace tarball / memory snapshot 暂无可用读取接口，只能在 manifest 中标 unsupported。
+- `arkcli agent +mcp-login` 只对后端 provider 列表中 `CredentialType=mcp_oauth` 的 URL 可靠；static bearer provider 走手动 credential create。Notion / Lark Base 等 provider 仍受后端 metadata discovery 可用性限制。
+- PRD 示例中的 inline/local skill 目录形态未做成直接 `--skill '{type:inline,...}'`；当前推荐路径是本地 zip 用 `agent skill create --zip` 或 `agent agent create --skill-zip` 上传成 custom skill。
+- `agent agent list` 默认拉单页；需要遍历全部候选时使用全局 `--page-all`，并按数据量设置 `--page-limit`。模糊复制/查找若仍返回多个候选，需要让用户确认。
+- Env 创建对线上后端需要显式 `Config.Networking`；PRD 中只传 `{Type: cloud}` 的简写不够用，skill 文档已按线上行为改为 `{Type: cloud, Networking: {Type: unrestricted}}`。
+- 数据面 `/api/v3/sessions/:id/events/stream` 支持重复的 `event_deltas=agent.message&event_deltas=agent.thinking` 查询参数；`events stream`、`+tail`、`events send --stream`（兼容 `--wait`）、`+new session` 和 `+iterate` 默认启用，`--no-event-deltas` 可回退到完整事件。CLI 会渲染 `event_start/event_delta` 并在最终完整事件到达时避免重复展示，断线补偿仍通过不带该查询参数的 `events list` 完成。
+- 前端的 `StreamManagedAgentSessionEvents` 仍是 ArkBFF 的 POST 流式 preview 协议。CLI 按“不直连 ArkBFF”的约束直联数据面，因此只对齐已确认的数据面 Event Deltas 语义，不依赖或宣称复用 BFF preview 的请求封装。
+- `[MA]开通时支持赠送额度包` 在需求单当前状态为已终止，现有 OpenTOP 仅有人工确认后的 `OpenChargeItems`，没有可确认的 gift quota 字段/Action；CLI 保持手动确认开通，不自动伪造赠送额度。
+- “企业自定义 Skill”若指当前账号/项目下的 custom Skill，CLI 已通过 TOP `ListSkills` 选择并以 `Type=custom` 挂载；若要求额外企业 Skill 空间/组织 scope，当前公开 `ListSkills` 请求契约没有可确认的 enterprise/space 字段，不能硬接。现有 `--skill-space-id` 不代表后端已支持该过滤字段。