进阶用法

本文档介绍 360disk CLI 的进阶用法，包括输出格式、错误码、管道集成和 CI/CD 场景。

更新时间：2026-03-24

输出格式

JSON 格式（默认）

所有命令默认输出标准 JSON 响应，包含 success、result、meta 三个字段：

{
  "success": true,
  "result": {
    "data": { "..." }
  },
  "meta": {
    "duration_ms": 156,
    "command": "dir ls"
  }
}

错误响应包含 error 和 code 字段：

{
  "success": false,
  "error": "未配置 API Key，请先执行 auth login --api-key <API_KEY> 或设置 API_KEY 环境变量",
  "code": 3,
  "meta": {
    "duration_ms": 0,
    "command": "dir ls"
  }
}

Text 格式

使用 --format text 获取人类可读的文本输出：

360disk --format text dir ls /
360disk --format text user info
360disk --format text file search "报告"

不同命令的 Text 格式输出：

dir ls / file search：表格格式（类型、名称、大小、时间、NID）
user info：列表格式（昵称、QID、空间、VIP）
file rm --batch：汇总 + 逐项状态
其他操作命令：简洁的成功/失败消息

静默模式

使用 --quiet 仅输出 result 数据，去掉 success 和 meta 包装层：

# 完整输出
360disk dir ls /
# → {"success":true,"result":{...},"meta":{...}}

# 静默输出（仅 result）
360disk --quiet dir ls /
# → {...}

提示

--quiet 适合程序处理场景，输出的 JSON 可直接用 jq 解析。 --format text 适合人类阅读，不建议程序解析。

错误码参考

当命令执行失败时，响应中包含 code 字段，进程退出码也与之对应。

退出码	名称	含义	典型场景
`0`	SUCCESS	成功	正常执行
`1`	GENERAL	一般错误	未分类的错误
`2`	INVALID_ARGS	参数错误	缺少必需参数、参数格式错误、互斥参数冲突
`3`	AUTH_ERROR	鉴权错误	未登录、API Key 无效或过期
`4`	NOT_FOUND	资源不存在	文件或目录不存在
`5`	PERMISSION_DENIED	权限不足	无权访问该资源
`6`	NETWORK_ERROR	网络错误	请求超时、网络不可达
`7`	CONFLICT	资源冲突	文件已存在、并发操作冲突
`8`	SERVER_ERROR	服务端错误	云盘 API 返回 5xx
`10`	QUOTA_EXCEEDED	配额超限	存储空间不足、请求频率限制

在脚本中使用错误码

360disk dir ls / 2>/dev/null
case $? in
  0) echo "成功" ;;
  3) echo "请先登录: 360disk auth login --api-key <KEY>" ;;
  6) echo "网络错误，请检查连接" ;;
  *) echo "执行失败，退出码: $?" ;;
esac

错误自动推断

除了显式的鉴权和参数校验错误外，CLI 会根据错误消息自动推断错误码：

错误特征	推断结果
包含「超时」「timeout」「aborted」	NETWORK_ERROR (6)
包含「api key」「未配置」「401」	AUTH_ERROR (3)
包含「参数」「required」「互斥」	INVALID_ARGS (2)
包含「不存在」「not found」「404」	NOT_FOUND (4)
包含「权限」「forbidden」「403」	PERMISSION_DENIED (5)
包含「已存在」「conflict」「409」	CONFLICT (7)
包含「500」「502」「503」	SERVER_ERROR (8)
包含「空间不足」「quota」「429」	QUOTA_EXCEEDED (10)

管道集成

360disk 遵循 Unix 管道哲学，支持标准输入/输出管道操作。

结合 jq 处理输出

# 获取所有文件名
360disk --quiet dir ls / | jq -r '.data.list[].name'

# 提取目录中文件的 NID 列表
360disk --quiet dir ls /工作目录/ | jq -r '.data.list[] | select(.is_dir != 1) | .nid'

# 搜索结果提取路径
360disk --quiet file search "报告" | jq -r '.data.list[].path'

# 获取分享链接
360disk --quiet file share /文件夹/报告.pdf | jq -r '.data.share_url'

stdin 管道输入

# 将文件内容保存到云盘
cat README.md | 360disk file save --stdin --dest /备份/ --filename README.md

# 将命令输出保存到云盘
date | 360disk file save --stdin --dest /日志/ --filename "timestamp.txt"

# 批量删除：从文件读取路径列表
cat paths-to-delete.txt | 360disk file rm _ --batch

# 将本地配置整文件写入云盘（config:write + --stdin）
cat local-config.json | 360disk file config --path /mcp/app.json --command config:write --type json --stdin

Windows 管道等价写法

cmd 无 cat：保存文件用 type report.md | 360disk file save --stdin ...；追加到云盘已有文件用 type local_log.md | 360disk file append /路径/文件.md --stdin；写入云盘配置用 type local-config.json | 360disk file config ... --stdin。PowerShell 用 Get-Content <路径> -Raw | ...。

勿用 echo -e ... | 360disk ...（cmd 下 -e 会进管道且编码易乱码）；多行中文优先 --content "...\n..." 或 UTF-8 文件 + type/Get-Content。

file exists --files 在 cmd 下勿用单引号包 JSON，应使用双引号并转义内部 "，或改用 --stdin（用 type 读 UTF-8 JSON 文件，勿用 echo '...' |）详见命令参考：file exists。

汇总速查见命令参考：Windows 速查。

组合命令

# 搜索文档并获取第一个结果的 NID，然后下载
NID=$(360disk --quiet file search "月报" | jq -r '.data.list[0].nid')
360disk file download "$NID" --dir ./

# 列出目录并统计文件数
360disk --quiet dir ls / | jq '.data.list | length'

# 获取分享链接并复制到剪贴板（macOS）
360disk --quiet file share /文件夹/报告.pdf | jq -r '.data.share_url' | pbcopy

超时与重试

超时设置

对于大文件上传或网络较慢的场景，可通过 --timeout 增加超时时间：

# 设置 60 秒超时
360disk --timeout 60000 file upload ./large-file.zip --dest /

# 设置 5 分钟超时（300 秒）
360disk --timeout 300000 file upload ./huge-archive.tar.gz --dest /备份/

失败重试

通过 --retries 指定失败后自动重试次数，采用指数退避策略：

# 失败重试 3 次
360disk --retries 3 file download abc123 --dir ./

# 组合使用
360disk --timeout 120000 --retries 2 file upload "./a.zip,./b.zip" --dest /备份/

重试间隔按指数增长：第 1 次重试等待 1 秒，第 2 次等待 2 秒，第 3 次等待 4 秒...

CI/CD 集成

基础用法

# 通过环境变量传递 API Key（推荐，避免在命令行中暴露密钥）
export API_KEY="${CLOUD_DISK_API_KEY}"

# 上传构建产物
360disk --quiet file upload ./dist.tar.gz --dest /releases/v1.2.3/

# 检查退出码
if [ $? -ne 0 ]; then
  echo "上传失败"
  exit 1
fi

GitHub Actions 示例

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Build
        run: npm run build

      - name: Upload to 360 Cloud Disk
        env:
          API_KEY: ${{ secrets.CLOUD_DISK_API_KEY }}
        run: |
          npx -y -p @aicloud360/mcp-server-disk@latest 360disk file upload ./dist.tar.gz --dest /releases/
          npx -y -p @aicloud360/mcp-server-disk@latest 360disk file share /releases/dist.tar.gz

自动化脚本示例

#!/bin/bash
# 自动备份脚本：打包并上传到云盘

set -euo pipefail

BACKUP_DIR="/备份/$(date +%Y%m%d)/"
BACKUP_FILE="backup-$(date +%Y%m%d_%H%M%S).tar.gz"

# 打包
tar -czf "/tmp/$BACKUP_FILE" ./data/

# 创建备份目录
360disk dir mkdir "$BACKUP_DIR" 2>/dev/null || true

# 上传（带超时和重试）
360disk --timeout 300000 --retries 3 file upload "/tmp/$BACKUP_FILE" --dest "$BACKUP_DIR"

# 验证上传结果
EXIT_CODE=$?
if [ $EXIT_CODE -eq 0 ]; then
  echo "备份成功: $BACKUP_DIR$BACKUP_FILE"
  # 生成分享链接
  360disk --quiet file share "$BACKUP_DIR$BACKUP_FILE" | jq -r '.data.share_url'
else
  echo "备份失败，退出码: $EXIT_CODE"
  exit $EXIT_CODE
fi

# 清理本地临时文件
rm -f "/tmp/$BACKUP_FILE"

常见问题

Q: 如何获取文件的 NID？

NID 是文件的唯一标识，可通过以下方式获取：

# 方式 1：列出目录
360disk --format text dir ls /工作目录/

# 方式 2：搜索文件
360disk --quiet file search "文件名" | jq '.data.list[] | {name, nid}'

Q: `--quiet` 和 `--format text` 有什么区别？

选项	输出格式	适用场景
默认	完整 JSON（含 success/meta）	通用
`--quiet`	纯 JSON（仅 result）	程序解析
`--format text`	人类可读文本	终端阅读

Q: 上传大文件超时怎么办？

增加超时时间和重试次数：

360disk --timeout 300000 --retries 3 file upload ./large.zip --dest /

Q: 全局选项放在哪里？

全局选项必须放在子命令之前：

# ✅ 正确
360disk --format text dir ls /

# ❌ 错误
360disk dir ls / --format text

Q: 多个文件路径如何分隔？

云盘路径（mv / rm / share）：用竖线 | 分隔
本地文件（upload）：用逗号 , 分隔

# 云盘文件
360disk file mv "/a.txt|/b.txt" /归档/

# 本地文件
360disk file upload "./a.txt,./b.txt" --dest /

下一步

命令参考 - 全部 18 个命令的详细说明
安装配置 - 安装方式和鉴权配置
MCP Server 文档 - MCP Server 的完整文档
Skills 文档 - Skill 模式介绍

输出格式​

JSON 格式（默认）​

Text 格式​

静默模式​

错误码参考​

在脚本中使用错误码​

错误自动推断​

管道集成​

结合 jq 处理输出​

stdin 管道输入​

组合命令​

超时与重试​

超时设置​

失败重试​

CI/CD 集成​

基础用法​

GitHub Actions 示例​

自动化脚本示例​

常见问题​

Q: 如何获取文件的 NID？​

Q: --quiet 和 --format text 有什么区别？​

Q: 上传大文件超时怎么办？​

Q: 全局选项放在哪里？​

Q: 多个文件路径如何分隔？​

下一步​