`ve-adrive-cli` 支持作为 Skill 集成到 AI\-Agent 生态，可通过标准化的能力描述、命令调用与结果解析，为 Agent 提供 ADrive 的完整操作能力。本章节主要介绍 AI\-Agent 指南。 ## Agent 推荐流程 * 若已获取资源名称，请添加 `--by-name` 参数。 * 若已获取资源 ID，请直接通过 URI 或对应 flag 寻址，无需额外解析。 ```Bash ve-adrive-cli capabilities --view compact --output json # 发现 ve-adrive-cli cp --describe --output json # 读契约 ve-adrive-cli rm adrive://i/s/p/ --recursive --dry-run --output json # 预览 ve-adrive-cli ls adrive://i/s/ --output json --query "data.entries[].name" # 执行 + 取值 ``` ## 结构化输出 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-adrive-cli` 将 CLI 命令封装为 MCP 工具，使 AI Agent 可以直接调用 ve\-adrive\-cli 的功能，而无需人工在终端输入命令。 * `stdio`（默认）不监听端口，由 MCP 客户端以子进程方式拉起； * `sse `模式绑定 `127.0.0.1:`，暴露 `/sse` 与 `/message` 端点。 * 工具名由 Skill 名转换而来：`ve-adrive ls` \> `ve_adrive_ls`。 * `tools`/`call `默认仅执行规划，不触发底层操作；传入 `execute: true `后才实际执行命令。

智能网盘服务