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

package/skills/arkcli-agent/references/mcp-vault.md

@@ -0,0 +1,111 @@
+# MCP 与 Vault
+
+## 查询可挂 MCP
+
+后端已注册、可被 Agent 使用的 MCP provider 通过下面命令查：
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+```
+
+- 返回结果里的 MCP server 信息可以作为创建 / 更新 Agent 时 `--mcp-server` 的来源；不要凭空猜 URL。
+- 如果用户想“给 Agent 加 GitHub / Notion / 飞书等 MCP”，先查 provider 列表，按 provider 的名称、URL、credential 类型筛选。
+- 挂到 Agent 时通常还要补一条 `mcp_toolset` 工具配置，`mcp_server_name` 要和 `--mcp-server` 里的 `name` / `Name` 对齐。
+- 如果 provider 需要 OAuth，先按下面的 OAuth MCP 登录链路拿 credential；如果是 static bearer，走 `agent vault credentials create`。
+
+## ENV Credential 与换签
+
+Credential 的 `Auth.Type` 支持 `environment_variable`。CLI 提供了和前端表单等价的快捷参数；敏感值支持 `@file`，不要写进 shell 历史：
+
+```bash
+arkcli agent vault credentials create <vault-id> \
+  --display-name github-token \
+  --secret-name GITHUB_TOKEN \
+  --secret-value @./github-token.txt \
+  --networking-type limited \
+  --allowed-host api.github.com \
+  --format json
+```
+
+这会构造 `Auth: {Type: environment_variable, SecretName, SecretValue, Networking}`。`--networking-type` 只能是 `limited` 或 `unrestricted`；limited 可以重复传 `--allowed-host`，unrestricted 不应同时传 host。
+
+MCP OAuth 的托管换签字段也可直接传入：
+
+```bash
+arkcli agent vault credentials create <vault-id> \
+  --auth-type mcp_oauth \
+  --mcp-server-url https://example.com/mcp \
+  --access-token @./access-token.txt \
+  --client-id <client-id> \
+  --client-secret @./client-secret.txt \
+  --refresh-token @./refresh-token.txt \
+  --token-endpoint https://example.com/oauth/token \
+  --scope read \
+  --format json
+```
+
+这会写入 `Auth.Refresh`，其中 client secret 位于 `TokenEndpointAuth.ClientSecret`，由后端负责托管换签。也可以继续使用 `--auth @./credential.json` 透传完整对象；快捷参数会覆盖对象中同名字段。
+
+## OAuth MCP 登录
+
+凭证必须与目标 provider 的服务语义匹配；不能为了让创建通过，把某服务的 Key 绑定到
+无关 provider，也不能写入 metadata/tags。不要逐个 curl/web_fetch 探测 provider URL，
+连接与授权结果以对应创建/登录命令的真实返回为准。OAuth 是外部授权流，不用聊天选择
+代替；metadata discovery 或授权失败时保留错误并停止，不擅自改用 token 绕过。
+多个符合用户目标的 provider 按共享协议消歧，使用本轮名称、URL、CredentialType；
+不能从记忆补出未注册的 provider。
+
+不要凭空猜 MCP OAuth URL。正确顺序：
+
+1. 查后端 provider：
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+```
+
+2. 只对 `CredentialType=mcp_oauth` 的 provider 使用 `arkcli agent +mcp-login`。当前实测可用示例是 GitHub MCP：
+
+```bash
+arkcli agent +mcp-login \
+  --vault-id vlt-xxx \
+  --name arkcli-github-mcp-oauth-<timestamp> \
+  --mcp-server-url https://api.githubcopilot.com/mcp/ \
+  --format json
+```
+
+3. `arkcli agent +mcp-login` 会本地启动 callback server，调用 `CreateVaultOAuthFlow`，打印/打开授权 URL，等待后端 callback 创建 credential，成功后输出 `credential_id`。
+4. 不方便自动开浏览器时加 `--no-open`，手动复制授权 URL。
+5. 完成后用 `agent vault credentials list <vault-id>` 查看已创建的 credential；需要查看非敏感字段时再使用 `get`。
+
+注意：
+
+- `CredentialType=static_bearer` 的 provider 不适合 `arkcli agent +mcp-login`，应走 `agent vault credentials create` 写 bearer auth。
+- 不要把用户 token 写进 agent metadata / tags。
+- `agent vault credentials get` 可能回显敏感 auth 字段，除非用户明确要求排障，否则优先用 `list`。
+- 实测 `https://mcp.notion.so/v1`、`https://mcp.larksuite.com/base` 在当前后端 metadata discovery 中失败；不要作为默认示例。
+
+## Agent 挂 MCP
+
+- 只有用户明确给 MCP server URL/name/credential，或上下文明确要求时才写 `--mcp-server`；如果用户只说要某类 MCP，先用 `agent vault oauth-provider list` 查可用 provider。
+- 挂 MCP 通常需要同时写 `McpServers` 和 `Tools` 中的 `mcp_toolset`。
+- 注意：`--tool` 是完整 `Tools` 数组替换。需要保留默认 bash/read/write/edit/glob/grep/web_fetch/web_search 时，必须把完整默认 `agent_toolset_20260701` 和 `mcp_toolset` 放在同一个数组里一起传，不要只传单个 `mcp_toolset`，也不要只写 `{type: agent_toolset_20260701}` 这种不完整占位。
+- 不确定默认 tools 结构时，参考 `references/agent.md#默认-agent-工具`；先用同一条 `agent agent create ... --dry-run` 检查 `preview.v1` 中的完整默认 `Configs` 与追加的 `mcp_toolset`，再经用户确认后真实创建。
+- 下例的 `tools-with-default-agent-toolset-and-github-mcp.json` 不是内置文件，表示调用方自行准备的完整 Tools 数组文件。
+
+```bash
+arkcli agent agent create \
+  --name arkcli-mcp-agent \
+  --model <items[].model from agent model list> \
+  --mcp-server '{type: url, name: github, url: https://api.githubcopilot.com/mcp/}' \
+  --tool @tools-with-default-agent-toolset-and-github-mcp.json
+```
+
+- `MCPConnectionFailed` 多数是 URL、协议、鉴权、`tools/list` 初始化失败，不等于 Agent 创建失败。
+
+## 示例
+
+```bash
+arkcli agent vault oauth-provider list --limit 100 --format json
+arkcli agent vault create --display-name arkcli-mcp-login-vault-20260706 --format json
+arkcli agent +mcp-login --vault-id vlt-xxx --name arkcli-github-mcp-oauth-20260706 --mcp-server-url https://api.githubcopilot.com/mcp/ --format json
+```

package/skills/arkcli-agent/references/model-config.md

@@ -0,0 +1,46 @@
+# 模型运行参数 metadata
+
+创建、更新 Agent，或对 Session 做 override、upgrade 前，需要配置模型运行参数时，先查询目标模型的 metadata。`agent model list` 用于选择模型，不提供这些参数的完整可选值。
+
+## 查询
+
+工具模型的 `epa_tool_model.support` 不由此接口提供；使用 `agent model list --usage tool` 读取完整 ArkModels 并按版本筛选，缓存及参数说明见 [工具模型查询](agent.md#查询工具模型与缓存)。不要将此处 key 查询为空解释为不支持工具模型。
+
+```bash
+arkcli agent model config <foundation-model-name> --provider ark --format json
+arkcli agent model config <foundation-model-name> --key thinking.support_value,thinking.default --key service_tier.support_value,service_tier.default --format json
+```
+
+| 输入 | 说明 |
+| --- | --- |
+| `<foundation-model-name>` | 必填，使用选中模型的 `agent model list` 结果中的 `name`，不是带版本的 `model`、模型 ID 或 `ep-*`。不要自行截断版本号推导名称。 |
+| `--provider` | 默认 `ark`，与前端查询一致；不是账号或产品切换参数。其他 provider 只有在已确认目标模型身份时使用。 |
+| `--key` | 可重复、可逗号分隔；不传时查询全部 metadata。key 原样交给服务端，不维护客户端白名单。 |
+
+命令是当前 profile 下的只读控制面查询，调用 `ListManagedAgentModelMetaDatas`；不接受模型版本、分页或 `--dry-run`。返回服务端 `ResponseMetadata` 和 `Result` 数组，每项包含 `FoundationModelName/Provider/Key/Data`。`Data` 是字符串数组，接口不返回内部 Schema。
+
+如果只有带版本模型标识，先从 `agent model list` 中匹配对应 `model`，读取该项 `name`；不要直接把 Endpoint ID 当作名称。查询失败应保留服务端错误，不自动切账号、产品或 provider 重试。
+
+## 参数逐项说明
+
+| 参数 | 含义 | 查询 key |
+| --- | --- | --- |
+| `speed` | 模型提供的速度模式；仅在目标模型支持时设置，不等同于所有模型都支持的通用加速开关。 | `speed.support_value`；当前契约未定义 `speed.default`。 |
+| `thinking` | 思考模式，例如部分模型支持 `enabled`、`disabled` 或 `auto`。 | `thinking.support_value`、`thinking.default` |
+| `reasoning_effort` | 推理投入程度，例如部分模型支持 `low`、`medium`、`high`。 | `reasoning_effort.support_value`、`reasoning_effort.default` |
+| `service_tier` | 模型服务档位，例如部分模型支持 `default`、`fast` 或 `auto`。不是 CLI 套餐选择。 | `service_tier.support_value`、`service_tier.default` |
+
+上述取值仅为示例，不是通用枚举，应读取目标模型 metadata。第三方 Protocol 与接入参数按 [BYOK 契约](byok.md)显式配置；不能用 Ark metadata 推断第三方模型能力。
+
+例如某次返回 `Key: "thinking.support_value", Data: ["enabled", "disabled"]` 与 `Key: "thinking.default", Data: ["enabled"]`，表示该目标模型声明这两个可选值，默认值为 `enabled`；不能推广到其他模型。
+
+## 使用规则
+
+- 按 `Result[].Key` 查找对应 `Data`；默认值通常为单元素数组，不能把 supported values 的第一个元素当默认值。
+- 未返回、空数组或默认值与支持值矛盾时，说明实际返回情况，不猜测缺失枚举或默认值。
+- 不存在的模型或 provider 也可能成功返回已知 key、但 `Data` 全为空；未知 key 可能返回 `Result: []`。因此 metadata 查询不能作为模型存在性校验。
+- metadata 是配置指引，不新增客户端业务拦截。用户明确提供的参数仍按创建、override、upgrade 各自的契约交给接口校验；保存成功也不能反推该值是 metadata 声明支持的值。
+- 不自动补写用户没要求的参数或默认值。尤其 upgrade 的省略字段按 upgrade 基线规则保留，不能用 metadata 默认值覆盖。
+- 用户切换模型时重新查询新模型，不能沿用旧模型的参数范围。查询成功不代表模型已开通，也不证明推理调用一定可用。
+
+参数写入位置和覆盖语义见 [Agent](agent.md)、[Session overrides](session-files.md)、[Session upgrade](session-upgrade.md)。

package/skills/arkcli-agent/references/self-hosted.md

@@ -0,0 +1,47 @@
+# Self-hosted Environment 与 Work Queue
+
+本页描述当前已实现的 API，不把 PRD 中的拟议 Worker Credential、lease_id、complete 或 Worker 列表当作现网契约。
+
+## 创建与绑定
+
+```bash
+arkcli agent env create \
+  --name enterprise-worker-env \
+  --runtime-type self_hosted \
+  --dry-run --format json
+```
+
+`--runtime-type` 仅在 env create 提供，映射为 `Config.Type`，优先于 `--config`/`--file` 中的 Type。也可继续使用 `--config '{Type: self_hosted}'`。不要附带 cloud 专用的 Networking、Packages、Env、SetupScript；CLI 不主动丢弃这些显式配置，由服务端判定是否合法。环境更新沿用 `env update`，不要把它当作 cloud/self_hosted 类型切换入口。
+
+创建前确认最终参数；创建后从结果取得 Environment ID 并用 `env get` 回读。Session 沿用 `agent session create --agent-id <agent-id> --environment-id <env-id>`。环境创建不代表 Worker 在线，Session 创建不代表任务已执行；必须有企业 Worker 消费队列并回传工具结果。
+
+## 查询和排障
+
+```bash
+arkcli agent env work stats <env-id> --format json
+arkcli agent env work list <env-id> --limit 100 --page-all --format json
+arkcli agent env work get <env-id> <work-id> --format json
+```
+
+- 上述命令走 `/api/v3/environments/{environment_id}/work` 数据面，复用当前产品/profile 的 API Key、Region、项目，不绕到 ArkBFF。显式 `--base-url` 必须与显式 API Key 配对；不要把 Key 写入文件、日志或报告。
+- list 返回 `data` 和可选 `next_page`。用 `--page <next_page>` 继续；它是不透明 cursor，不是数字页码。`--page-all` 默认最多 10 页、每页 100 条，支持 `--page-limit` 和 `--page-delay`；达到页数上限后保留 `next_page`，不能声称结果完整。
+- 当前 list 没有服务端 state/session_id/worker_id 过滤参数，不要编造 flags。按 Session 定位可用返回的 `data.id`；本期后端 Work ID 等于 Session ID，但优先使用实际返回值。
+- 状态为 `queued → starting → active → stopping → stopped`。`stopped` 只表示 Work 结束，不等于 Session 成功；结合 `session get`、events 或 `+debug` 核实业务结果。
+- `depth` 是未被 Poll 领取的 queued 数；`pending` 是已 Poll 但未 Ack 的 queued 数，不是 running 数。`workers_polling` 是最近 30 秒内具名 Worker 的 Poll 活动计数，不等于全部活跃任务的 Worker 数；0 不足以断定所有 Worker 离线。`oldest_queued_at` 覆盖 depth 与 pending。
+- get/list/stats 是只读命令，不支持 `--dry-run`。查询失败时报告服务端错误，不转向其他产品或账号。
+
+## 停止任务
+
+先 get 核对目标和状态；只预览时：
+
+```bash
+arkcli agent env work stop <env-id> <work-id> --dry-run --format json
+```
+
+只有用户确认目标与停止影响后才执行 `agent env work stop <env-id> <work-id> --yes`。默认请求 `force=false`（优雅停止）；用户明确要求强制停止才增加 `--force`。不传 `--yes` 时真实执行返回 `requires_confirmation` 且不发请求。Preview 是零网络计划，不需要 `--yes`，也不代替执行授权或在线校验。
+
+当前后端 stop 只接受 `force`，没有 `mode/reason` 参数。成功返回原始 Work 状态，不等候远端进程退出：优雅停止通常先进入 stopping；force 立即标记 stopped，但不能证明企业 Sandbox 已被杀死，也不能据此声称旧 Tool Result 一定被拒绝。之后单独 get 核对 Work 状态，并结合企业 Worker 日志核实清理结果；不要自动升级为强制停止。
+
+## 本期边界
+
+arkcli 提供环境/Session 管理与 Work 运维，不在本机常驻 Poll 或执行 Agent 下发的 bash/文件工具。Worker 接入使用前端已提供的官方 Go/Python/Java SDK；当前实现使用 API Key，不虚构 Environment Key 管理命令，也不把 Vault Credential 当作 Worker Credential。部署执行工具的 Worker 是独立操作，需要用户指定隔离环境并确认权限、工作目录与凭证边界。

package/skills/arkcli-agent/references/session-files.md

@@ -0,0 +1,157 @@
+# Session 与 Files
+
+`session resources list/get/add` 是数据面命令，支持显式 `--api-key` / `--base-url`。显式地址必须同时提供显式 Key，且地址应为 MA 数据面地址，不是 BYOK 模型的 BaseUrl；只提供 Key 时使用当前产品、Region、环境的 MA 标准地址，不继承套餐路由。这不改变 `session create/get` 等控制面命令的认证要求。
+
+## Env / Session
+
+### Session 项目一致性
+
+创建 Session（包括 `session create`、`+new session`、`+iterate`）时，所选 Agent、Environment 及其他带项目归属的关联资源必须与 Session 处于同一 Project；override 不豁免该要求。
+
+- 先通过 `auth status` 确认所选 Platform profile 的项目上下文，再用资源的 list/get 返回值核对实际 `ProjectName`。`account-wide` / “账号全部资源”只是查询范围，不是具体 Project，也不证明列出的资源属于同一项目。
+- 若 Session 的目标 Project 尚未确定、资源归属缺失或存在冲突，先补查或向用户确认，不按名称、同账号、可见性或创建时间推断。对没有项目归属的资源，不虚构 `ProjectName`。
+- 选择环境时先筛选同 Project 的候选，再按用户需求选择，并显式传 `--environment-id`（或入口支持的 `--env-id`）；不能依赖账号范围内“最新环境”的自动选择。没有同项目候选时，确认后在目标项目创建，不借用其他项目资源。
+- 使用已确认的项目级 Platform profile 完成创建；没有对应 profile 时按 Profile skill 处理，不擅自修改全局默认，不伪造全局 `--project-name`。创建后用 `session get` 回读项目与资源绑定；预览成功不能代替项目归属核对。
+
+```bash
+arkcli agent env create --name arkcli-<domain>-env-<timestamp> --config '{Type: cloud, Networking: {Type: unrestricted}}' --format json
+arkcli agent session create --agent-id <agent-id> --environment-id <env-id> --title arkcli-<domain>-session-<timestamp> --format json
+arkcli agent session get <session-id> --format json
+```
+
+Session 标准 CRUD 走 OpenTOP；Session resources / events / threads 走数据面直联。
+线上创建 cloud env 时需要显式带 `Networking: {Type: unrestricted}`；只传 `{Type: cloud}` 会被后端校验为缺少 `config.networking`。
+
+读取 Session 时保留 stdout、stderr 和退出码，先检查业务错误，再按实际 envelope 取字段：OpenTOP 通常为 `Result.Id` / `Result.AgentId`，其他入口可能包在 `data`；以完整 JSON 为准，不能把顶层 `.Id == null` 当作 Session 不存在。字段未回显、成功空结果、权限失败、鉴权失败和解析错误分别报告；已有完整响应只修正本地取值路径，不为取错层级重新查询，也不合并 stderr 后当 JSON 解析。
+
+### Session TOS 资源
+
+创建 Session 时可以直接绑定一个 TOS 目录。CLI 会把它编排为 `Resources` 数组中的一项，字段与前端及 OpenTOP 契约一致：`Type=tos`、`TosBucket=<bucket>`、`TosKey=<prefix>/`。
+
+只有用户明确要求绑定 TOS 且提供了地址时才传 `--tos-path`。用户未提到 TOS 时不要默认绑定；用户要求绑定但没有给出地址时，先询问完整的 `tos://<bucket>/<prefix>/`，不要猜 Bucket 或 Prefix。
+
+```bash
+arkcli agent session create \
+  --agent-id agent-xxx \
+  --environment-id env-xxx \
+  --tos-path tos://my-bucket/analysis/ \
+  --format json
+```
+
+`--tos-path` 也接受不带协议的 `my-bucket/analysis/`。它表示目录而不是单个对象，因此 prefix 必须非空并以 `/` 结尾；`tos://bucket/`、`bucket`、`bucket/path` 会在 CLI 层校验失败。已有的 `--resource '[...]'` 仍可使用；同时传两者时 TOS 资源会追加到原始资源数组中。
+
+`arkcli +new session` 和 `arkcli +iterate` 创建 Session 时同样支持 `--tos-path`。该参数只绑定已有 TOS 目录，不负责创建 Bucket、上传对象或申请 TOS 权限；调用前需确保账号已开通 TOS，并对 Bucket/Prefix 有读取权限。
+
+### 其他创建时资源
+
+复杂资源在 `session create --resource` 中声明，不等同于仅支持 file 的 `session resources add`。例如绑定用户已选定的 memory store：
+
+```bash
+arkcli agent session create --agent-id <agent-id> --environment-id <env-id> \
+  --resource '[{Type: memory_store, MemoryStoreId: ms-xxx, Name: user-memory}]' --format json
+```
+
+规范字段使用 PascalCase，类型值仍是 `memory_store` 等 snake_case。当前 CLI 也会把 `memory_store_id` 等已注册别名归一化为 `MemoryStoreId`，不能断言 snake_case 必然失败。遇到 required 错误，先检查资源对象层级、真实 ID 和本地 Preview 的最终 payload；不要反复猜字段、虚构 ID 或擅自创建替代资源。
+
+### Environment 自定义脚本
+
+Environment 的初始化脚本位于 `Config.SetupScript`。可以直接传文本，也可以用 `@` 读取本地脚本文件：
+
+```bash
+arkcli agent env create \
+  --name arkcli-analysis-env \
+  --config '{Type: cloud, Networking: {Type: unrestricted}}' \
+  --setup-script @./bootstrap.sh \
+  --format json
+```
+
+`--setup-script` 会覆盖 `Config.SetupScript`；复杂的 `Config` 仍可用 `--config @./env.yaml` 或 `--file` 透传。CLI 会把 `setup_script`、`networking` 等常见 lower/snake case 写法归一化成 OpenTOP 的字段。
+
+### Session overrides
+
+override 模型运行参数前，按[模型参数 metadata](model-config.md)查询目标模型；切换模型需重新查询，不自动注入默认值。
+
+Session 创建可以对已有 Agent / Environment 做一次性配置覆盖。override 内的 `System`、`Tools`、`McpServers`、`Skills`、`Multiagent` 和 Environment `Config` 是服务端定义的替换语义，非 nil 字段不会与基 Agent 自动合并；传数组时要传完整数组。
+
+```bash
+arkcli agent session create \
+  --agent-id agent-xxx \
+  --environment-id env-xxx \
+  --agent-overrides '{model: {id: doubao-seed-2-1-pro-260628, thinking: enabled, reasoning_effort: low, service_tier: auto}, Tools: [...]}' \
+  --environment-overrides @./environment-overrides.yaml \
+  --format json
+```
+
+`--agent-overrides` 映射为 `AgentWithOverrides`，`--environment-overrides` 映射为 `Environment`，缺少 override 对象中的 `Id` 时 CLI 会从 `--agent-id` / `--environment-id` 补齐。override 是服务端 one-of 变体，CLI 会在最终请求中移除对应的 `AgentId` / `AgentVersion` 或 `EnvironmentId`，避免同时传两个互斥变体。`arkcli +new session` 和 `arkcli +iterate` 也支持同名参数。需要传自定义 Agent 配置时不要同时使用 `--agent` 和 `--agent-overrides`。
+
+`AgentWithOverrides.Model` 支持 `Id/Provider/Protocol/BaseUrl/Headers/TokenLimits/InputModalities` 及 `Speed/Thinking/ReasoningEffort/ServiceTier`；不再过滤用户显式提供的模型接入字段。类型、省略语义和请求凭证见 [BYOK](byok.md)。按目标模型能力选择参数，不猜默认值，也不把配置保存成功当成推理成功。
+
+上述模型结构归一化同时适用于 `--agent-overrides`、`--agent-overrides @file` 以及通用 `session create --file` 内的 `AgentWithOverrides`。显式空值 `--agent-overrides=` / `--environment-overrides=` 是无效输入，CLI 返回 validation error，不创建 Session。
+
+### Environment 状态筛选
+
+当前 `arkcli agent env list` **没有注册 `--status`**，不要生成下面这种命令：
+
+```bash
+arkcli agent env list --status active
+```
+
+`ListEnvironments` 后端请求也没有 `Status` 过滤字段；返回的 Environment 对象只有可选的 `ArchiveTime`。需要按状态找环境时，先拉全量，再由调用 arkcli 的 AI Agent 本地筛选：
+
+```bash
+arkcli agent env list --page-all --format json
+```
+
+- `ArchiveTime` 非空：`archived`
+- `ArchiveTime` 为空或字段缺失：`active`
+- 前端领域类型虽然预留了 `updating`，但当前返回契约没有可可靠推导它的字段；不要声称支持 `updating` 筛选。
+- 不要只过滤默认第一页；状态筛选必须配合 `--page-all`，并关注全局 `--page-limit` 是否导致结果仍被截断。
+- env `--page-all` 默认使用 `Limit=100`，并把每页响应的 `NextPage` 作为下一次请求的 `Page`；`--page-limit` 限制的是最多请求页数，不是结果条数。
+
+## Files 与 Session Resources
+
+### 查看挂载资源
+
+先 `agent session get <session-id>` 核对 Session，再 `agent session resources list <session-id>` 查看接口实际返回的挂载项。需要单项时用 `resources get <session-id>` 按该命令 help 中的资源 ID/file ID/mount path 筛选；文件 metadata 用 `agent file get <file-id>`。列出的挂载项不等于完整 Sandbox 目录树，file get 也不等于下载内容。没有公开读取接口时直接说明边界，不生成 `fs tree`、任意 Sandbox path 读取或内部接口命令。
+
+Memory 挂载须使用返回的 store ID，再查询 `agent memory-store get` / `memories list` / `memories get --view full`。条目默认 basic 视图不包含正文；Path 更新后以响应中的 ID 和 Path 为准，不假设旧 ID 仍可用。不连接 OV 内部存储，也不据此绕过账号或资源权限。
+
+- 本地文件上传到 Files API：`arkcli agent file upload --path ./data.csv --purpose user_data --wait-active`。
+- URL/TOS 注册：`arkcli agent file upload --url https://... --purpose user_data` 或 `--url tos://bucket/path/file --tos '{bucket: b, prefix: arkfiles/}'`。
+- `agent file upload/delete` 支持命令级 `--dry-run`：只输出零网络 `preview.v1`，不会上传、轮询或删除。删除预览不要求 `--yes`，真实删除仍需要明确确认并传 `--yes`。
+- 视频/特殊文件预处理可传 `--preprocess-configs`；有效期可传 `--expire-at <unix-seconds>`。
+- 上传后等待状态：`arkcli agent file wait <file-id>`。
+- 查询已有文件：`arkcli agent file list --purpose user_data --limit 20`；全量遍历用 `arkcli --page-all agent file list`，CLI 默认 `limit=100` 并沿 `has_more + last_id -> after` 拉取。
+- 用户给本地路径并要挂到已有 session 时，优先一步完成：
+
+```bash
+arkcli agent session resources add <session-id> --path ./data.csv --mount-path data.csv
+```
+
+这会先上传 file，再等待 active，最后 add session resource。
+`session resources add --path` 支持透传上传相关参数：`--purpose`、`--tos`、`--preprocess-configs`、`--expire-at`、`--wait-timeout`、`--wait-interval`。
+
+边界：
+
+- `session resources add` 当前只支持 `type=file`、`file_id`、`mount_path`，不支持 PRD 中更复杂的 `github_repository` / `memory_store` 参数。
+- 后端会自动在 `mount_path` 前添加 `/mnt/session/uploads/`。CLI 在 add 前会向 stderr 提示这一点，但不会改写用户传入的路径；例如传 `reports/data.csv`，最终路径为 `/mnt/session/uploads/reports/data.csv`。避免重复传入 `uploads/` 或完整受管前缀，并且不要传包含 `..` 的越界路径。
+- `resources get` 是 CLI 派生能力：调用 list 后按 `resource_id` / `file_id` / `mount_path` 本地筛选。
+- 线上数据面当前没有原生 resources update/delete，CLI 保持 fail-fast unsupported。
+- `session resources add` 后端会复制源文件到 session 受管 uploads 路径，因此 resources list 看到的 file_id 可能不同于 add 时传入的源 file_id。
+- 不要调用 ArkBFF/NodeBFF 获取文件；CLI 只直连 `/api/v3/files` 数据面。
+
+## 调试与导出
+
+- 已知 Session ID 的异常定位用 `arkcli +debug <session-id> --format json`，结合 Session、近期 events、resources 和 threads 分清失败、等待确认与仍在运行；聚合结果中的 warnings 表示部分查询失败，不等于对应数据为空。
+- 用户需要诊断包时用 `arkcli +export <session-id> --output ./session-diagnostics.tar.gz`。它导出 CLI 可见的诊断数据，不是完整工作区、memory store 或环境快照；以 archive 的 manifest/notes、事件数量和 warnings 说明范围与限制。
+- 导出文件位于当前 CLI 宿主；交付前检查可能含有的消息、代码或业务数据。远端沙箱路径不能当成用户电脑路径，不自动上传或公开诊断包。
+
+## 示例
+
+```bash
+arkcli agent file upload --path ./sales.csv --purpose user_data --wait-active --format json
+arkcli agent session resources add sess-xxx --path ./sales.csv --mount-path sales.csv --format json
+```
+## 工具版本
+
+Session 的 AgentWithOverrides.Tools 是完整数组；不提供就沿用绑定 Agent 的配置，不自动升级旧工具集。显式选择 20260916 或提示词增强工具前，读取 [工具配置](agent.md#默认-agent-工具)，保留完整的其他工具、权限与 Models。

package/skills/arkcli-agent/references/session-upgrade.md

@@ -0,0 +1,64 @@
+# 已有 Session 运行配置升级
+
+用户要让**已有 Session** 使用另一个模型、同 Agent 的新版本或新运行配置时，使用 `agent session upgrade`；不要用 `agent agent update` 后假设老会话自动跟随，也不要用 `+iterate` 重建会话。只改标题/标签仍走 `session update`；创建时一次性 override 见 `session-files.md`。
+
+## 命令与输入
+
+配置或更换模型运行参数前，先查[模型参数 metadata](model-config.md)。查询结果用于说明可选值，不替代升级基线规则，也不新增客户端业务校验。
+
+```bash
+arkcli agent session upgrade <session-id> \
+  --model <selected-model-id> \
+  --thinking enabled \
+  --reasoning-effort low \
+  --dry-run --format json
+```
+
+```bash
+arkcli agent session upgrade <session-id> \
+  --agent-version 4 \
+  --agent '{skills: [], mcp_servers: []}' \
+  --environment '{config: {env: {LOG_LEVEL: debug}, packages: {pip: [pytest]}}}' \
+  --compact \
+  --dry-run --format json
+```
+
+| 参数 | 用法 |
+| --- | --- |
+| `<session-id>` | 必填；保持原 Session ID，不创建新会话 |
+| `--file <path>` | 本地 JSON/YAML 完整请求文件；不自动读 stdin，不支持 `--file -` |
+| `--agent <object>` | JSON/YAML 或 `@file`；支持 `type/id/version/model/system/tools/mcp_servers/skills/multiagent/display_name` |
+| `--environment <object>` | JSON/YAML 或 `@file`；支持 `type/id/config`；config 的 cloud 字段见下文 |
+| `--agent-version <int>` | 覆盖 `agent.version`；不传或 0 保留当前快照，不会选择最新版本 |
+| `--model <id或object>` | ID 只覆盖 `agent.model.id`；对象或 `@file` 替换请求中的 model 对象 |
+| `--speed/--thinking/--reasoning-effort/--service-tier` | 覆盖 `agent.model` 同名 snake_case 字段；显式空字符串会保留在请求中 |
+| `--vault-ids <array>` | JSON/YAML 数组或 `@file`；目标用户 Vault 绑定全集，非增量；`[]` 清空用户绑定 |
+| `--initial-events <array>` | JSON/YAML 数组或 `@file`；可省略或为 `[]`；非空时后端仅接受一条固定的 `/compact` 事件 |
+| `--compact[=false]` | true 构造固定 `/compact` initial event；false 显式设置 `initial_events: []`；与 `--initial-events` 互斥 |
+
+升级是数据面 `POST /api/v3/sessions/{id}/upgrades`，请求统一用 **snake_case**，不套用 TOP CamelCase 或创建时的 `AgentWithOverrides`。CLI 仅在 type 缺失时补 `agent_with_upgrades` / `environment_with_upgrades`；显式 type 原样交给后端。id 可省略，后端沿用当前绑定；如传入，只能是当前 Session 的 Agent/Environment ID，不能用来切换绑定。
+
+优先级：先加载 `--file`；`--agent/--environment` 整块覆盖文件中的对应对象；`--agent-version` 和模型独立 flags 再覆盖具体字段；事件/Vault flags 覆盖对应顶层数组。JSON/YAML 中未提供、`null`、`[]`、空字符串不会被 CLI 互相转换。除了补缺失的 type，CLI 不做在线查询、自动合并快照或业务白名单校验，服务端错误原样报告；但不要因此编造接口字段。
+
+## 配置语义
+
+- 后端要求 `agent/environment/vault_ids` 至少提供一个；`initial_events` 本身不是升级目标。upgrade 当前不支持 `title/tags/resources/checkpoint_id/environment_id` 等顶层字段。
+- 不传 version 时，以当前 Session Agent 快照为基线，未传子字段保留。指定正版本时，以该已发布版本配置为新基线，再应用本次显式覆写；旧 Session overrides 不保证自动保留。用户要“最新版”时先查询真实版本号，不发送字符串 `latest`，也不省略版本来表示最新版。
+- `tools/mcp_servers/skills` 非空数组整组替换，`[]` 清空，未提供或 `null` 保留基线；没有默认工具或 Skill 自动注入。
+- `agent.model` 支持 `id/provider/protocol/base_url/headers/token_limits/input_modalities` 和四个运行参数；创建 override 同样支持这些字段。upgrade 使用 snake_case，不改写 Headers 的 key/value。详见 [BYOK](byok.md)；不为省略字段补默认值。
+- cloud `config.networking` 整块替换；`config.env` 按 key 合并，本次同 key 覆盖旧值；`config.packages` 按包名合并，本次同名包替换旧 spec。空 env/packages 不会清空历史项。`setup_script` 显式值替换，空字符串可传。只给 environment id 不代表从 Environment 资源拉取最新配置；应明确提供期望 config。
+- self_hosted Session 可以升级 Agent；不支持 cloud/self_hosted 类型互切，不应发送自托管 Sandbox 的 networking/packages/env/setup_script。用户 TOS 配置不可通过升级修改。
+- `vault_ids` 非空数组替换用户 Vault 绑定全集，可新增、移除或更换；保留某项时必须把它包含在目标数组中。省略或完整请求中的 `null` 保留原绑定，`[]` 清空用户绑定；服务端内部授权 Vault 保留。相同集合可用于刷新凭证。后端校验 Vault 是否存在及账号/项目权限，不自动创建 Vault，不发送凭证密文。执行前展示绑定差异并取得确认，执行后回读核对；旧服务端若拒绝更换，报告兼容性问题，不自动改成其他操作。
+
+## 执行与结果核对
+
+1. 用 `session get` 核对目标、当前 Agent/环境快照及状态。后端要求 idle；已终止、升级中或上一轮未正常 end_turn 等情况会拒绝。CLI 不额外抢先判断这些业务状态，也不重试业务错误。
+2. 生成 leaf-local `upgrade ... --dry-run --format json`。这是零网络计划，不证明模型可用或资源状态合法。复述本次变化及可能重建 Sandbox/压缩上下文的影响，得到明确确认后再去掉 `--dry-run` 执行；此命令没有 `--yes`。
+3. 真实执行只提交一次，返回后端 Session 对象，不返回独立 upgrade task，也不等待后台结束。`status=upgrading` 只表示受理/处理中；不要汇报“模型已生效”。不编造 `/upgrades/{upgrade_id}` 查询命令。
+4. 后续单独 `session get` 回读，等待离开 upgrading，并检查模型 ID、版本、运行参数和目标配置。idle 单独不能证明升级成功；配置不符或异常时继续查询 events / `+debug`，不自动重发 upgrade。超时或响应不明确时，同样先回查，避免重复升级。
+5. 升级期间不要发消息、删除、打断或重复升级。若本次显式启用 compact，不要再独立发送第二次 compact。需要验证推理时，在配置回读确认后，取得用户测试授权再发最小消息。
+
+API Key 和项目来自当前产品/profile，显式 `--base-url` 需要配对显式 API Key。Preview 会对标准 Authorization/API Key 字段脱敏，但不要把任意环境变量或自定义 header 的值当成已全面脱敏；不要在对话、命令日志或报告中展示真实密钥。
+## 工具版本兼容
+
+Session upgrade 不自动把旧工具集升级为 20260916。用户明确要求时才在完整 `agent.tools` 中修改目标条目的 type/name，保留其余配置；参见 [工具版本说明](agent.md#默认-agent-工具)。

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

@@ -0,0 +1,94 @@
+# Skills
+
+## Skill 选择
+
+- 创建 Agent 的默认 Skill 选择顺序是 custom 优先、market 兜底。只要用户没有明确指定 market，先查本账号 custom skill；custom 没有合适候选后再搜索 market。用户明确指定 market 时可以跳过 custom。
+- Market skill：custom 没有命中或用户明确要求 market 时使用 `agent skill search/list`，创建时优先直接使用返回的 `AgentSkills`；SkillHub V1 列表不返回版本信息，缺省传 `{type: skill_hub, skill_id: <id>}`，由服务端解析最新可用版本。
+- Custom skill：本账号已有 custom skill 的默认选择流程是按需分页：先取第一页 100 条，由调用 arkcli 的 AI agent 按名称、描述和能力判断；没有合适候选时，再使用返回的 `NextPage` 继续取下一页，直到命中或没有下一页。不要一开始用用户描述做服务端 `Name` 过滤，也不要默认一次性拉完整 catalog。CLI 内部入口叫 `ListSkillsForTop`，实际 TOP Action 是 `ListSkills`。只使用该接口返回的 `skill-...` ID；同接口返回的 `s-...` 不作为 custom skill 使用。
+- 创建 Agent 时可直接传裸 custom ID：`--skill skill-xxx`。CLI 会省略 `Version`，由服务端始终解析最新版本；不会把 `latest` 字面量发送给服务端。裸 `--skill s-xxx` 会被拒绝；`s-...` 只从 SkillHub 链路来。
+- Custom skill：用户给本地 zip 时，用 `agent skill create --zip` 或 `agent agent create --skill-zip`，返回后作为 `{Type: custom, SkillId, Version}` 注入。
+- Custom skill 上传走数据面 `POST /api/v3/skills`，不是 TOP `CreateSkill`；需要当前 profile 有可用 ARK API Key。
+- `agent skill list/search` 支持 `market`、`custom`、`ark`、`all`：`market` 走公开 SkillHub；其他三种走 TOP `ListSkills`，其中 `all` 不发送 `Source`。`get` 和 `versions` 可读取 custom/ark；Ark Skill 是只读的，update/delete/download/set-protection 会在 CLI 侧拒绝。
+- TOP Skill 摘要保留 `DisplayTitle`、`Source`、`UpdateTime`、`Name`、`ProtectionEnabled`。Agent 挂载 Skill 的响应保留 `UseLatest`、具体 `Version` 和 `DisplayName`，不要把实际版本和“是否跟随最新”混为一谈。
+- `agent skill create --protection-enabled` 可在上传时设置保护开关；已有 custom Skill 用 `agent skill set-protection <id> --enabled=true|false`。该命令允许显式传 `false`，并调用 TOP `UpdateSkill`。
+- `agent skill update <id> --zip <file>` 不是原地修改旧版本，而是调用 OpenTOP `CreateSkillVersion` 上传新版本；可用 `agent skill versions <id>` 查看版本，再用 `agent skill download <id> --version <version>` 下载指定版本。
+- `agent skill download` 先调用 TOP `GetSkill`（未指定版本时取 `LatestVersion`），再调用 `GetSkillVersion` 获取 `PreSignedTOSURL`，最后用不携带 ARK 凭证的普通 GET 下载到本地；默认文件名为 `<skill-id>-v<version>.zip`。
+- `agent skill download ... --dry-run` 会零网络预览版本解析、下载和本地保存步骤。未显式传 `--version` 或 `--output` 时，必须把 `unresolved` 中的版本/文件名当作占位符，不能声称已在线解析，也不会创建或覆盖文件。
+- `agent skill delete <id>` 调用 TOP `DeleteSkill`；它不会级联删除 SkillVersion，只能在全部版本都已删除后执行。
+- `agent skill delete <id> --version <version>` 调用 TOP `DeleteSkillVersion`，只删除指定版本。删除 latest 版本前，必须先删除全部非 latest 版本。
+- `agent skill create/update/delete` 都支持命令级 `--dry-run`，用于零网络预览上传或删除请求。删除预览不要求 `--yes`，但不会在线校验版本依赖顺序；真实删除仍必须先读取完整版本列表，并在交互确认后执行或显式传 `--yes`。
+- Market skill 的 `agent skill search/list --source market` 直接调用无需鉴权的 SkillHub V1 `GET /v1/skills`，并在 CLI 内映射为原有 `ListMarketSkills` 输出；不得向 `skills.volces.com` 发送 Ark STS、AK/SK 或 API Key。custom skill 的 `agent skill list --source custom` 仍调用 TOP `ListSkills`。
+- 选择 market skill 时看 `Items[].Name`、`Description`、`Keywords`、`EvaluationScore`；创建入参直接取返回的 `AgentSkills`，或手动组 `{Type: skill_hub, SkillId}`。只有从其他可信接口明确拿到语义版本时才补 `Version`，不得从 `Metadata` 猜测版本。
+- 选择 custom skill 时先读取第一页完整 `Items`，综合比较 `Id`、`Name`、`Description`、`LatestVersion`，不要只看第一条或只依赖服务端关键词匹配；如果没有足够相关的候选，再用 `NextPage` 继续读取下一页。`AgentSkills` 只会包含 `skill-...` custom skill。确认候选后可直接取 `AgentSkills`，或传裸 `--skill <Items[].Id>`。
+- 多个候选接近时，使用宿主结构化选择能力展示本轮结果中的 `Id`、`Name`、`Description`、`LatestVersion`，宿主不支持时才退化为精简编号列表。用户明确要求自动完成时，只有相关度和版本证据能形成清晰第一名才自动选择并说明依据；否则仍需澄清，不能用“自动完成”授权任意挑选。通用数据分析优先考虑覆盖面广的分析 skill，再按需要追加 Excel/CSV/报表/可视化类 skill。
+- 分页选择优先使用“按需读取”：第一页使用 `--limit 100`，后续把上一次响应的 `NextPage` 原样传给 `--page`。只有用户明确要求完整清单、需要离线分析全部 Skill，或多页都没有命中时，才使用 `--page-all`；它受全局 `--page-limit` 限制，不能把截断的 catalog 当成完整候选集。
+- SkillHub V1 列表没有 `LatestVersionStatus`；创建 Agent 时 `SkillId` 使用 `Items[].Id`，默认省略 `Version` 以跟随服务端最新版本。
+
+## 从 GitHub 导入
+
+GitHub 导入固定使用公开仓库默认分支 HEAD，不支持私有仓库、branch 或 tag 参数：
+
+```bash
+arkcli agent skill github scan owner/repo --format json
+arkcli agent skill github import https://github.com/owner/repo --path skills/foo --path skills/bar --format json
+arkcli agent skill github import 'npx skills add owner/repo' --all --protection-enabled=true --format json
+arkcli agent skill github import owner/repo --selected @./selected.json --format json
+```
+
+- Agent 构造命令时，优先使用服务端已知的输入形式：`owner/repo`、完整 GitHub HTTPS URL，或完整的 `npx skills add ...` 字符串。这些是调用指引，不是 Agent 或 CLI 的输入白名单。
+- 用户给出仓库输入后，不要在 Agent 或 CLI 侧解析、改写或拒绝；应原样传给 `ScanGithubSkill.Input`，由服务端负责解释和校验。CLI 绝不启动 shell 或执行输入中的 npx。
+- `--path` 可重复，或用 `--all`；两者互斥，并且只能选择 scan 返回的有效候选。
+- `--selected` 文件是 `{Path, ProtectionEnabled}` 数组；它和全局 `--protection-enabled` 互斥。
+- scan 是只读命令；import 是 `WorkflowClientPreview`，`--dry-run` 只展示 scan、选择和 import 请求，占位符不会发网络。
+- import 会输出每个条目的 `ok`、`updated`、`skipped_duplicate` 或 `failed`；只要任一条失败，命令在保留完整结果后返回非 0。
+
+## Custom Skill 删除顺序
+
+Skill 删除有严格的依赖顺序。执行任何删除前，先用 `agent skill versions <id>` 获取完整版本列表并确认 latest 版本：
+
+1. 删除整个 Skill：先逐个删除全部非 latest SkillVersion，再删除 latest SkillVersion；确认版本列表为空后，最后删除 Skill。
+2. 删除 latest SkillVersion：先逐个删除全部非 latest SkillVersion；确认只剩 latest 后，才能删除 latest。
+3. 删除单个非 latest SkillVersion：可以直接删除指定版本，但删除后仍要重新查询版本列表确认结果。
+
+每次删除后重新执行 `agent skill versions <id>` 回查。不要假设 `DeleteSkill` 会自动级联删除版本，也不要在仍存在 SkillVersion 时调用它。每个破坏性命令单独执行，并遵守交互确认或 `--yes` 规则。
+
+## 常用命令
+
+```bash
+arkcli agent skill search "Excel 数据分析" --limit 10 --format json
+arkcli agent skill list --query "Excel 数据分析" --limit 20 --format json
+arkcli agent skill list --source custom --name "我的数据分析" --limit 20 --format json
+arkcli agent skill list --source custom --limit 100 --format json
+# 若上一页返回 NextPage 且没有合适候选，再继续：
+arkcli agent skill list --source custom --limit 100 --page '<NextPage>' --format json
+arkcli --page-all --page-limit 20 agent skill list --source market --format json
+arkcli agent skill create --zip ./my-skill.zip --display-title "My Skill" --format json
+arkcli agent skill create --zip ./my-skill.zip --display-title "My Skill" --protection-enabled=true --format json
+arkcli agent skill set-protection skill-xxx --enabled=false --format json
+arkcli agent skill list --source ark --limit 100 --format json
+arkcli agent skill list --source all --limit 100 --format json
+arkcli agent skill github scan owner/repo --format json
+arkcli agent skill github import owner/repo --all --format json
+arkcli agent agent create --name arkcli-local-skill-agent --model <items[].model from agent model list> --skill-zip ./my-skill.zip --format json
+arkcli agent agent create --name arkcli-existing-custom-skill-agent --model <items[].model from agent model list> --skill skill-xxx --format json
+arkcli agent skill update skill-xxx --zip ./my-skill-v2.zip --format json
+arkcli --page-all agent skill versions skill-xxx --format json
+# 将占位符替换为上一条 versions 响应中选定条目的 Version 原值；不要自行拼版本号：
+arkcli agent skill download skill-xxx --version '<Version-from-versions>' --output ./skill-selected-version.zip --format json
+# 用户只需最新版时省略 --version，由 CLI 解析 LatestVersion：
+arkcli agent skill download skill-xxx --output ./skill-latest.zip --format json
+# 删除整个 Skill 时，先逐个删除全部非 latest 版本：
+arkcli agent skill delete skill-xxx --version <non-latest-version> --yes --format json
+# 回查并确认只剩 latest 后，再删除 latest：
+arkcli --page-all agent skill versions skill-xxx --format json
+arkcli agent skill delete skill-xxx --version <latest-version> --yes --format json
+# 回查并确认版本列表为空后，最后删除 Skill：
+arkcli --page-all agent skill versions skill-xxx --format json
+arkcli agent skill delete skill-xxx --yes --format json
+```
+
+`agent skill list --source custom` 默认先输出一页 custom catalog 和 `AgentSkills`。调用 arkcli 的 AI agent 应先判断这一页；没有合适候选时沿 `NextPage` 继续请求，不要臆造 `SkillId`，也不要在当前页没有相关性判断时直接选第一条。需要完整 catalog 时再加 `--page-all`。
+
+`agent skill search --source custom "<name>"` 仍可用于用户明确指定 skill 名称、目录很大需要缩小候选，或对全量 catalog 做二次检索；它不是自然语言创建 Agent 时的默认入口。
+
+`agent skill list --page-all` 会自动使用每页 100 条：custom skill 沿 TOP `NextPage -> Page` 拉取；market skill递增 `PageNumber`，并根据 `TotalCount` 停止。全局 `--page-limit` 仍是最多请求页数。按需分页时，custom skill 的 `--page` 对应 TOP 的 `Page` token。

package/skills/arkcli-agent/references/todo-write.md

@@ -0,0 +1,37 @@
+# Todo Write 任务计划工具
+
+用户明确要求启用任务计划/待办工具时读本节。`todo_write` 是内置工具，复用 Agent create/update 的 `--tool`，不是 custom tool，也没有独立的 Todo CLI 命令。
+
+## 配置与前提
+
+- 配置名固定为 `todo_write`，属于 `agent_toolset_multimodal_20260825`；不要放进 `agent_toolset_20260701` 或 `agent_toolset_20260916` 等基础工具集。
+- 不需要 `Models`，不查询工具模型，也不因 toolset 名称含 multimodal 而开启生图/视频工具。
+- 火山后端 `release/20261013` 对普通 Agent 使用该 toolset 检查 `FrontendMutilmodalTools` 白名单。CLI 能构造配置不代表账号已获准使用；遇到权限/白名单错误，保留错误与 RequestId，停止重试，不换基础 toolset 或 Raw API 绕过。其他产品的上线和权限以其服务端为准，不从火山推断。
+
+下面是**一个工具集条目，不是完整 Tools 数组**。新添此 toolset 且仅需 Todo 时，显式关闭默认工具，再单独启用 Todo，避免省略 DefaultConfig 导致其他工具默认启用或触发模型依赖校验：
+
+```json
+{
+  "Type": "agent_toolset_multimodal_20260825",
+  "DefaultConfig": {
+    "Enabled": false,
+    "PermissionPolicy": {"Type": "always_allow"}
+  },
+  "Configs": [
+    {
+      "Name": "todo_write",
+      "Enabled": true,
+      "PermissionPolicy": {"Type": "always_allow"}
+    }
+  ]
+}
+```
+
+## 创建、更新与验证
+
+1. 创建时显式传 `--tool` 会替换默认工具；将上面的条目与用户需要的完整基础工具配置合成数组，不要只传 Todo 条目而丢掉 bash/read/write 等工具。
+2. 更新前先 `arkcli agent agent get <agent-id> --format json`。若已有该 toolset，只合并/修改它的 `Configs` 中的 `todo_write`，不要追加重复 toolset，也不要用示例的 DefaultConfig 覆盖已有设置。保留其他工具、模型绑定和 PermissionPolicy；前端隐藏权限控件不表示应删除权限字段。
+3. 用 `arkcli agent agent update <agent-id> --tool '<完整 Tools JSON 数组>' --format json` 提交，再 get 回读核对 Todo 与其他工具。关闭时把该项设为 `Enabled: false`，保留其余配置。
+4. 要验证实际调用，创建绑定新 Agent 版本的 Session；不要假设旧 Session 自动使用更新后的配置。发送明确要求使用 Todo 制定/更新计划的消息并检查工具事件。配置接受成功不等于工具已被调用；未出现工具事件时如实报告未验证调用。
+
+运行时事件名可能是 `todo_write` 或 `TodoWrite`（取决于 BaseAgent），二者都用于识别 Todo 调用；**写配置始终使用 `todo_write`**。Todo 由 Agent Loop 内置执行，不需要用户实现 custom tool 或手工回传 custom tool result。