ve-tos-cli 支持作为 Skill 集成到 AI-Agent 生态，可通过标准化的能力描述、命令调用与结果解析，为 Agent 提供 TOS 对象存储的完整操作能力。本章节介绍 AI-Agent 指南。

六大设计原则

Agent 推荐流程

结构化输出 Envelope

字段	含义
success / status	请求是否成功。 success ：表示执行成功。 false ：表示执行失败。
command	本次操作对应的稳定命令路径（如 ve-tos object upload），可直接复制后重新执行。
request_id / status_code / ec	请求唯一标识符 / HTTP 响应状态码 / 业务错误码，用于问题定位与排查。
data	命令执行的结果数据，结构因命令类型而异。
pagination	分页信息。包含 next_token（下一页游标）、next_marker（下一页标记）、total_returned（本次返回数量）。
error	错误详情，包含以下子字段： code（错误码）、message（错误描述）、exit_code（退出码）、kind（错误类型）、category（错误分类）、suggested_action（建议操作）、fix_command（修复命令）、doctor_hint（诊断提示）、docs_url（参考文档链接）。

确定性退出码

退出码	含义	类别	说明
0	Success	Success	命令执行成功，无错误。
1	Unknown	Unknown	未知错误，通常由未预期的异常引起。
2	AuthFailed	AuthError	鉴权失败，AK/SK 无效或已过期，请检查凭证配置。
3	ConfigMissing	ConfigMissing	配置文件不存在或必填配置项缺失。显式指定 --config-path 且文件不存在时触发。
4	ResourceNotFound	NotFound	目标资源不存在，如桶或对象路径错误。
5	PermissionDenied	PermissionDenied	当前账号无权限执行该操作，请检查 IAM 策略配置。
6	ValidationError	InvalidParam	参数校验失败，请检查命令参数是否符合要求。
7	RateLimited	QuotaExceeded	请求被限流或超出配额，建议稍后重试或申请提升配额。
8	TransferFailed	Retryable	传输失败，属于可重试错误，通常由网络抖动或临时服务异常引起。
9	Conflict	Conflict	资源状态冲突，操作与当前资源状态不兼容，如并发写入冲突。

MCP 集成

MCP（Model Context Protocol）是一种开放协议，用于将外部工具、数据源或服务以标准化方式暴露给 AI Agent 调用。

ve-tos-cli 将 CLI 命令封装为 MCP 工具，使 AI Agent 可以直接调用 ve-tos-cli 的功能，而无需人工在终端输入命令。

工具名由 Skill 名转换而来：ve-tos ls > ve_tos_ls，ve-tos bucket create > ve_tos_bucket_create。

列举语义提醒（Agent 须知）

ve-tos 默认列举模式为 auto：

如需启用前缀级并发，请显式指定 --recursive-list-mode hierarchical，该选项同时影响 --list-concurrency 是否生效。