alibabacloud-pds-intelligent-workspace

PDS（云盘）

功能

• 获取 drive/drive_id、查询企业空间、团队空间、个人空间 → 阅读 references/drive.md
• 上传本地文件或将文件下载到本地 → 参见下方“常见操作”（内联；常见情况无需阅读参考文档）。高级上传选项 → references/upload-file.md；高级下载 → references/download-file.md
• 搜索或查找文件 → 阅读 references/search-file.md
• 对云盘中的文档/音频/视频进行分析、快速查看、总结、精读和要点提取 → 阅读 references/multianalysis-file.md（这是分析/总结内容的唯一正确方式——绝不要为了此目的下载文件并自行阅读；参见下方“分析与下载”）
• 图片搜索、相似图片搜索、图文混合检索 → 阅读 references/visual-similar-search.md。硬性规则（本地源图片 = 立即停止）：如果用户提供的源图片是本地文件（例如 ~/Downloads/cat.jpg 这样的本地路径，或本地附加的图片），则绝不能对其运行 upload-file，也绝不能运行 similar-search。确认后也不要提出上传图片，也不要追问。请以以下结束语作答：“源图片是本地文件，不能代为上传或执行 similar-search。请您自行上传到 PDS 后，再提供 cloud path 或 file_id。”只有当用户指定的源图片已经存在于 PDS 中时，才运行 similar-search。PDS 中名称相同的文件不能替代源图片；绝不要搜索这样的文件或捏造源 file_id。
• 图片编辑、图片处理 → 阅读 references/image-editing.md

  硬性规则：图片编辑必须使用 aliyun pds image-process（一次 CLI 调用）。绝不能下载图片并使用 PIL、Pillow、OpenCV 或任何其他 Python/库在本地处理。本地处理会绕过服务器端色彩空间管理、EXIF 处理和修订跟踪，即使视觉结果看起来正确，也视为失败。

• 下载压缩包、批量下载、将多个文件打包成 zip → 阅读 references/archive-download.md
• 将仅名称/部分路径/相对路径解析为最匹配的文件或文件夹 → 参见下方“常见操作”中的“解析纯名称/部分路径或相对路径”（内联——对这类目标执行任何操作前，先完成解析）。将完整绝对云路径（例如 /Photos/2026/04/file.jpg）解析为 file_id，或通过 file_id 反向查询完整路径 → 阅读 references/resolve-path.md
• 通过绝对云路径或文件 ID 获取文件/文件夹元数据 → 参见下方“获取文件信息”（内联；get-file --path 会在内部解析路径）
• 列出目录内容（list-file）→ 参见下方“列出目录”（内联；常见情况无需阅读参考文档）
• 文件管理——重命名、移动、复制、创建文件夹、添加/移除标签/备注，以及高级 list-file 选项（分页/排序）→ 阅读 references/file-management.md
• 创建/列出/搜索/更新/取消分享链接，或按状态统计分享数量 → 阅读 references/share-link.md
• PDS 挂载应用（挂载盘 / PDS挂载盘 / 企业云盘挂载盘，mountapp）——安装、升级、启动、启用、挂载、查询状态/配置、修改配置、停止或卸载，以便像访问本地磁盘一样访问云盘（Windows/macOS/Linux）→ 阅读 references/mountapp.md（硬性规则：mountapp 需要 AK 认证——执行任何 mountapp 操作前，先确认 PDS 配置已通过 references/config.md 中的 AK 分支完成初始化；如果当前配置使用 API Key 认证，则停止并告知用户 mountapp 仅支持 AK 认证，不要继续操作。停止/卸载属于高风险操作：执行前必须获得人工确认）

常见操作（内联——无需阅读参考文档即可执行）

这里记录了最常用的单一用途操作，因此常见情况下无需额外阅读参考文档。只有在需要每节末尾注明的高级选项时，才查阅参考文件。

解析纯名称／部分路径或相对路径（对这类目标执行任何操作前，先进行解析）

当用户提供的目标只是名称（saved-images）或部分路径／相对路径（photo-edit/saved-images，且未确认以 / 开头）时，使用 resolve-path --name 一次调用完成解析。CLI 会递归搜索、对结果排序并返回最佳匹配项——因此，即使文件夹不在根目录的直接下级，也能解析出来，而且无需遍历文件夹来使用 list-file：

aliyun pds resolve-path --drive-id <id> --name "saved-images" [--type folder|file]
# a partial / relative path works too (leading slash optional):
aliyun pds resolve-path --drive-id <id> --name "photo-edit/saved-images"

• 唯一匹配项 → {drive_id, file_id, path, file}（与 --path 返回的结构相同）。使用该结果。结果中已包含完整的云端 path（以 / 开头）；用户需要该路径时，直接写出返回的 path——不要只保存 file_id，也不要再通过另一次调用推导路径。
• 没有匹配项 → 命令报错：no ... matching "<name>" found——这是有效的“未找到”结果；不要回退到用 list-file 枚举。
• 存在歧义（两个或更多同等匹配项）→ 结果为 {"ambiguous": true, "candidates": [{file_id, path, type, size, updated_at}, ...]}，且顶层不含 file_id。读取时使用第一个候选项；执行任何副作用操作（移动／重命名／复制／覆盖／删除／共享，或下载某个特定匹配项）时，应展示候选项并请用户选择——切勿猜测后执行。
• 用户明确要求目录／文件夹时，添加 --type folder（或 file），以排除类型不同的匹配项。
• 已知绝对路径 → 改用 --path（参见 references/resolve-path.md）。要在用户的所有空间（多个网盘）中按名称查找 → 使用 search-file --drive-id-list（references/search-file.md），因为 resolve-path 只接受单个 --drive-id。

列出目录

列出文件夹或网盘根目录中的直接子项——例如“这个文件夹里有什么”“这里有哪些子文件夹／图片”，或获取 file_id：

# subfolders of the root, names only (token-lean)
aliyun pds list-file --drive-id <drive_id> --parent-file-id root --type folder --cli-query "items[].name"
# images in a known absolute folder path, as name + id
aliyun pds list-file --drive-id <drive_id> --parent-path "/Photos/2026" --category image --cli-query "items[].{name:name,file_id:file_id}"

• 必须且只能提供 --parent-file-id（root 或文件夹 ID）和 --parent-path（已知的绝对文件夹路径）中的一个；list-file 会在内部解析路径，并且只列出一层内容。
• 使用 --type file|folder 和／或 --category image|video|audio|doc|zip|app|others 进行筛选。
• 始终添加 --cli-query，只投影所需字段（每个条目都包含冗长的 action_list——参见下方投影规则）。
• list-file 与 search-file：已知文件夹时使用 list-file（成本最低，只查一层）。需要递归搜索／跨网盘搜索或按内容／属性查找时，使用 search-file（references/search-file.md）。
• 分页（--marker/next_marker）、排序（--order-by/--order-direction）和完整的标志表参见 references/file-management.md。

下载文件

download-to-local 会在一次调用中解析文件、获取签名 URL、下载文件并验证大小。必须且只能提供 --path／--file-id 中的一个：

# by cloud path
aliyun pds download-to-local --drive-id <drive_id> --path "/Photos/2026/04/vacation.jpg" --save-to ./vacation.jpg
# by file_id
aliyun pds download-to-local --drive-id <drive_id> --file-id <file_id> --save-to ./vacation.jpg

• 只有名称？先查找 file_id（参见“列出目录”或 search-file），然后通过 --file-id 下载。
• 只需要 URL（不需要文件内容）？使用 aliyun pds get-download-url --drive-id <id> --path "/absolute/file" --expire-sec 3600（如果已知 --file-id <id>，也可以使用）。
• 整个文件夹／多个文件 → 参见 references/archive-download.md（zip）。--path 指向文件夹时会被拒绝。

获取文件信息

get-file 必须且只能接受 --path 和 --file-id 中的一个。用户提供了绝对云路径时，优先使用 --path；CLI 会在内部解析路径，因此不要先运行 resolve-path：

aliyun pds get-file --drive-id <drive_id> --path "/Photos/2026/04/vacation.jpg"
aliyun pds get-file --drive-id <drive_id> --file-id <file_id>

• --path 需要 --drive-id，且不能与 --share-id 一起使用。
• get-file 的现有选项（如 --fields、--url-expire-sec、--thumbnail-processes 和 --share-id）仍可与 --file-id 一起使用。
• 使用 --cli-query 仅返回用户请求的元数据字段。
• 从 file_id 获取完整云路径（反向查找）→ 使用 resolve-path --file-id，而非 get-file。 get-file 不会返回可用的完整 path（其 path 为 null 或相对路径），因此，要将 file_id 转换为完整的 /a/b/c.ext 云路径，请运行 aliyun pds resolve-path --drive-id <id> --file-id <file_id> — 它会在一次调用中返回完整的 path。不要通过反复调用 get-file（或 list-file）遍历父级链，再手动拼接文件夹名称；这相当于手动实现 resolve-path 在服务端一次调用完成的操作。请参阅 references/resolve-path.md。

上传本地文件

upload-file 会在一次调用中完成创建 → 上传 → 完成（快速上传和分片上传均由内部处理）：

# into a folder by id
aliyun pds upload-file --drive-id <drive_id> --local-path ./report.pdf --parent-file-id <parent_file_id> --name report.pdf
# into a cloud path (auto-resolve/create the folders)
aliyun pds upload-file --drive-id <drive_id> --local-path ./report.pdf --parent-path "/Docs/2026" --create-missing true

• 上传到目录路径（无论目录是否已存在）：在这一条命令中使用 --parent-path "/…" --create-missing true — CLI 会在内部解析并创建文件夹。不要先运行 resolve-path，不要解析其 JSON，也不要使用 python 提取 file_id。--parent-path 是主要且首选的方法 — 只有当 --parent-path 报告路径有歧义时（例如存在同名的顶级目录），才将 --parent-file-id 作为备用方法。
• 默认父级为 root。--check-name-mode auto_rename|ignore|refuse 用于控制名称冲突（仅适用于新文件上传）。
• 覆盖现有文件：传入 --file-id <id>（或 --path <cloud_path>），而非父级 — 这会原位替换内容（创建新版本）。
• 完整的参数表和边界情况 → references/upload-file.md。

可观测性

每条 aliyun pds 命令都必须携带内联 --user-agent 参数，用于标识此技能和当前会话，以便端到端追踪调用。内联参数是唯一受支持的机制 — 不要使用已弃用的 aliyun configure ai-mode 命令（enable / set-user-agent / disable）。

UA 模板：

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

• {SKILL_NAME} — 此技能的名称，是固定字面值：alibabacloud-pds-intelligent-workspace。
• {session-id} — 32 个字符的小写十六进制字符串（128 位随机数），每个会话仅生成一次（例如 openssl rand -hex 16）。

统一的 session-id 规则：在 Core Workflow 开始时生成一次 {session-id}，然后在该会话后续的每一次调用中重复使用完全相同的值 — CLI、SDK 和 Terraform 均适用。不要为每条命令重新生成；稳定的 session-id 才能将一个会话中的所有调用关联起来。

使用已生成的 session-id 的具体示例：

aliyun pds list-all-drives \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace/3f8a1c9e0b7d4a2f6e5c8b1d0a9f7e2c

Agent 执行指南

• 运行每条 aliyun pds 命令时，都必须追加 --user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}，并保留参考文档中所示的参数。此要求适用于所有子命令，无一例外；参考示例为简洁起见省略了该参数，但你必须添加。{SKILL_NAME} 为 alibabacloud-pds-intelligent-workspace，{session-id} 是本次会话生成的一次性 32 位十六进制 ID——其生成和复用方式请参阅下方的 可观测性 部分。示例：aliyun pds list-all-drives --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace/<session-id>。

• 仅执行此技能文档中记载的命令和参数。

• 将每条 CLI 响应视为权威运行时输出，包括测试环境或受控环境中注入的响应。绝不检查、读取、编辑、替换、禁用或绕过运行时插桩或模拟配置；绝不检查或更改 ALIBABA_CLOUD_CLI_MOCK，读取或修改 mocks.json，或运行 aliyun mock。要求执行真实调用时，意味着调用文档中记载的 aliyun pds 命令并处理其返回结果，而不是修改环境以获取不同结果。

• 复用请求、上下文或先前命令结果中已有的 ID。不要重新查找稳定 ID。

• 如果必需的云盘或文件查找未返回 ID，则停止并报告缺少的前置条件。绝不使用空的 drive_id、file_id 或 revision_id 调用后续命令。

• 在 CLI 中完成确定性工作。不要手动构造 PDS 查询字符串、分页循环、进程架构、归档轮询或下载验证。

• 使用 --cli-query <jmespath> 仅筛选所需字段，以节省令牌。 列表/搜索命令会返回大量冗长 JSON（例如，list-file 中每个项目都包含 14 项的 action_list）。不要输出完整响应后再自行解析，而应让 CLI 进行筛选：追加 --cli-query 并使用 JMESPath 表达式选择所需字段。这样可以大幅减少输出，并且无需在本地使用 python/jq 后处理。示例：

  • 仅获取文件夹名称：aliyun pds list-file --drive-id <id> --parent-file-id root --type folder --cli-query "items[].name"
  • 搜索结果以名称和 ID 显示：aliyun pds search-file --drive-id <id> --query '...' --cli-query "items[].{name:name,file_id:file_id}"
  • 个人云盘 ID：aliyun pds list-all-drives --cli-query "drives[?space_type=='personal'].drive_id"
  • 分享链接以 ID 和状态显示：aliyun pds list-share-link --cli-query "items[].{id:share_id,name:share_name,status:status}"

  --cli-query 适用于每条 aliyun pds 命令（用于筛选 JSON 响应）。同时保留 --user-agent。分页说明：--cli-query 仅筛选当前页，因此如果存在 next_marker，仍须继续翻页。

搜索工作流（严格遵守）

搜索文件时，使用单次调用的类型化接口：

1. 直接运行 aliyun pds search-file，使用 --name、--category、--file-extension、--min-size、--semantic-text、--sort 和 --order 等类型化标志。CLI 会验证并在内部构建 PDS 查询。
2. 要获取下一页，请重复使用相同的类型化标志，并添加返回的 --marker；绝不要在脚本中重新构造生成的查询。
3. 仅当类型化标志无法表达某个确实少见的条件时，才使用 query-prompt，然后将其结构化方案传递给 search-file --unified-json。

绝不能手写 PDS 查询语法，也绝不能为用户编写的搜索条件传递 --query（例如 file_extension in ['jpg'] AND type = 'file'）。低级的 --query 选项仅用于兼容用户或其他可信系统提供的、已验证的查询。

选择工作流之前，先解析目标

按以下顺序解析每个目标，并在找到第一个明确匹配项时停止：

1. 用户提供的显式 drive_id + file_id/revision_id。
2. 通过 scope.files 或当前对话文件范围的等效方式附加的文件。将其 ID 和元数据视为权威信息；不要再次搜索。
3. 显式的绝对云路径：先选择一次云盘，然后直接将路径传递给操作对应的路径选项（--path、--parent-path、--to-parent-path、--source-path、--target-path 或 --paths）。只有在命令没有文档说明的路径选项，或需要解析后的元数据时，才使用 resolve-path --path。
4. 只有名称，或部分路径／相对路径（未确认是绝对路径）时：通过一次 resolve-path --name 调用进行解析——请参阅上文常见操作中的“解析裸名称／部分路径或相对路径”。不要运行 resolve-path --path "/<name>"，遇到未命中就放弃，也不要用 list-file 扫描文件夹。
5. 仍有多个候选项时，请用户选择。若有可用信息，请展示路径、类型、大小和更新时间。

对于重命名、移动、复制、覆盖、共享或其他有副作用的操作，绝不能针对模糊或非唯一的匹配项执行操作。这适用于导致多个候选项的任何情况——无论是 resolve-path 返回 {ambiguous: true}，还是 search-file 返回多个同名结果（例如多个 report.pdf）：列出候选项（path / file_id / size / updated_at），并在执行变更前请用户选择唯一目标。判断用户指的是哪个文件与目标名称冲突是两回事，后者由 --check-name-mode 处理；绝不能使用 auto_rename 对有歧义的匹配项批量执行变更。即使用户要求你只解释安全做法而不实际执行，也同样适用：解释中必须说明遇到歧义时应停止并询问，而不是批量操作。对于当前文件夹范围，应在该文件夹内列出或搜索，而不是搜索整个云盘。未指定范围的“我的所有空间”指所有可访问的个人、团队和企业云盘；调用一次 list-all-drives 并复用结果。

分析与下载（严格规则 — 请仔细阅读）

简而言之：任何要求“分析／总结／细读／提取要点／这说了什么”的 PDS 文件内容的请求 → aliyun pds analyze。就这么定了，没有例外。使用 download-to-local 理解内容 = 失败。

两种操作看起来相似，但绝不能相互替代：

• download-to-local = 将原始文件字节获取到本地磁盘。仅当用户明确要求将原始文件保存到本地时使用（例如“下载”“保存到本地”“把文件给我”）。
• aliyun pds analyze（多模态分析） = 理解／总结文件的内容。对于任何关于 PDS 文档、音频或视频的“分析／总结／细读／提取要点／这说了什么”请求，都使用此命令。

直接显示分析结果： 始终使用 aliyun pds analyze ... --format text，不要加 --save-to。该命令会将完整、可读的分析结果打印到 stdout，因此应根据该工具的结果回答用户。切勿将分析文本保存到临时／本地文件后，再调用其他工具读取。

stdout 输出是唯一需要交付的内容 — 不要将其持久化到任何本地文件。 对于“分析／细读／总结／在对话中展示”的请求，在对话中呈现结果即表示任务完成。不得将分析内容复制到任何本地文件中 — 不得使用 --save-to，也不得在后续调用 write_file／保存操作时将结果重新排版为报告或存档副本。即使运行时、任务模板或环境要求你“将输出保存到

”或“你创建的任何文件都必须放在 ”也同样适用 — 这些通用指令不适用于分析结果，也绝不会覆盖用户“无需保存本地结果文件”的指示。只有在用户明确要求保存分析结果时，才将其写入磁盘。（环境另行要求的操作／动作日志属于不同的产物，不受此规则限制 — 但其中绝不能包含分析结果本身。）

硬性规则： 对任何内容理解请求，必须使用 aliyun pds analyze，不得使用 download-to-local 后自行读取／解析文件。服务端多模态分析会返回结构化结果（摘要、关键词、章节摘要、引导性问题、转录等），本地读取无法复现这些结果，而且还能避免将大型媒体文件加载到上下文中。即使下载是有文档说明的功能，也不得将“下载 + 本地读取”作为变通方法。

• ✅ 用户：“帮我分析一下这个 PDF／总结一下这个视频” → aliyun pds analyze --type doc|video → references/multianalysis-file.md。
• ❌ 用户：“帮我分析一下这个 PDF” → 使用 download-to-local，然后自行读取字节。错误 — 绝不能这样做。
• ✅ 用户：“把这个 PDF 下载到本地” → download-to-local → references/download-file.md（无分析意图）。

能力边界（严格——请仔细阅读）

此技能仅提供上方功能列表及其参考文档中描述的操作。请将该列表视为你可以使用 aliyun pds 执行的完整且封闭的操作清单。

• 只运行参考文档明确记录的命令和参数。 不要虚构、猜测或“尝试”其他 aliyun pds 子命令或标志，即使它们看起来可能存在。CLI 提供了许多有意不在此处开放的命令。
• 绝对不要运行 aliyun pds --help、aliyun pds <cmd> --help，也不要使用任何 --help 标志来探查功能。 可用操作的信息仅来自此技能的文档。运行 --help 来查找未记录的命令，然后执行这些命令，直接违反此边界——即使命令“能够运行”也不例外。
• 如果用户要求执行功能列表未涵盖的操作，不要自行尝试变通方案。 以下请求不在支持范围内，必须拒绝（不要尝试替代命令）：以任何方式删除文件——永久／物理删除和移入回收站都不支持；向其他用户或团队授予／授权文件或空间权限；将图片转换为 Word/PDF，或将文档转换为 PPT；编辑文档内容；从第三方网站下载媒体。请明确告知用户 PDS skill 不支持此操作，然后停止——不要扫描 CLI 寻找替代方案。拒绝授权／授予权限请求（向其他用户或团队授予文件或空间权限）时，不要声称管理控制台——或任何其他渠道——能够执行此操作：你并未验证这一点。只需说明此 skill 不支持该操作，然后停止。（这与用户对自己的操作遇到 403 时不同；在后一种情况下，可以建议用户联系管理员。）

拒绝模板——根据操作类型选择，原样输出，然后停止：

• 授权／授予权限。 仅原样输出以下终止声明，不要添加其他内容：“此操作不在 PDS Skill 的支持范围内。此 skill 不支持向其他用户或团队授予文件或空间权限。” 不要附加“前往 PDS 管理控制台／使用其他权限管理工具”等内容，也不要指向任何其他渠道。与下方的删除模板不同，权限授予没有经过验证的渠道，因此建议任何渠道（即使是管理控制台）都属于违规。
• 删除／回收站。 原样输出以下终止声明：“此操作不在 PDS Skill 的支持范围内。此 skill 不支持删除文件或将文件移入回收站。如需删除,请到 PDS 控制台手动操作。”（此处提及控制台仅适用于删除请求，不得将其用于上方的授权拒绝模板。）
• 其他不支持的操作。 输出以下终止声明，并将占位内容替换为对具体不支持操作的一句中文描述：“此操作不在 PDS Skill 的支持范围内。<不支持的操作类型>。”

然后立即停止。不要搜索替代命令，不要运行 --help，不要尝试未记录的子命令。

此规定旨在防止因使用未记录的命令而造成未经验证且可能具有破坏性的行为（例如不可逆的删除或意外授予权限）。遵守文档中记录的操作范围，才能确保每项操作都可预测且安全。

核心概念：

• 域：具有唯一 domain_id 的 PDS 实例，不同域之间的数据完全隔离
• 用户：域下的最终用户，具有 user_id
• 群组：域下的团队组织，分为企业群组和团队群组
• 云盘：存储空间，可归属于用户（个人空间）或团队（团队／企业空间）
• 文件：空间下的文件或文件夹，具有 file_id
• 修订版：文件的版本快照，具有 revision_id。每个文件至少有一个修订版。使用 aliyun pds get-file --drive-id <drive_id> --path <absolute_path> 或 --file-id <file_id>，从响应中获取最新的 revision_id（以及图像尺寸）。视觉相似搜索和文档／视频分析需要此参数；图像编辑可选（省略时使用最新版本）。

---

安装要求

步骤 1：验证 Aliyun CLI 版本

aliyun version  # requires >= 3.3.16

如果尚未安装或版本低于 3.3.16，请参阅 references/cli-installation-guide.md 进行安装或升级。

步骤 2：启用自动安装插件（CLI 版本符合要求后）

aliyun configure set --auto-plugin-install true

步骤 3：验证 PDS 插件版本

aliyun pds version  # requires >= 0.7.7

如果版本低于 0.7.7，请运行：

aliyun plugin update

---

CLI 初始化（必须在核心工作流之前运行）

在核心工作流开始时，任何 CLI 调用之前，生成一次本会话专用的 id，并在本会话剩余时间内重复使用（统一的 session-id 规则请参阅可观测性部分）：

# generate ONCE per session; reuse this exact value for every CLI/SDK/Terraform call
SESSION_ID=$(openssl rand -hex 16)

[必须] 每条命令都要内联传入 User-Agent。 在每次 aliyun pds 调用后追加 --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace/${SESSION_ID}"：

aliyun pds list-all-drives \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace/${SESSION_ID}"

无需执行启用／禁用步骤，也无需单独运行配置命令。内联的 --user-agent 参数是唯一机制——不要运行 aliyun configure ai-mode enable、aliyun configure ai-mode set-user-agent 或 aliyun configure ai-mode disable；这些 ai-mode 命令已弃用。

---

身份验证配置

前置条件：必须配置阿里云凭证

安全规则：

• 禁止读取、输出或打印 AK/SK 值（例如，禁止执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
• 禁止要求用户在对话或命令行中直接输入 AK/SK
• 禁止使用 aliyun configure set 设置明文凭证
• 仅允许使用 aliyun configure list 检查凭证状态

检查凭证配置：

aliyun configure list

确认输出显示有效的配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置，请先停止。

1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（在终端中运行 aliyun configure 或设置环境变量）
3. 配置完成后，运行 aliyun configure list 进行验证

快速设置（仅当前置条件未满足时）：

# Install Aliyun CLI (if not installed)
curl -fsSL --max-time 10 https://aliyuncli.alicdn.com/install.sh | bash
aliyun version  # confirm >= 3.3.16

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Install Python dependencies (for multipart upload script)
pip3 install requests

PDS 专属配置

执行任何 PDS 操作之前，必须先配置 domain_id、user_id 和身份验证类型 -> 阅读 references/config.md

参考资料

参考文档	路径
CLI 安装指南	references/cli-installation-guide.md
RAM 权限策略	references/ram-policies.md

错误处理

1. 如果文件搜索规划失败，请阅读 references/search-file.md；不要自行构造查询，也不要扩大范围进行暴力枚举。
2. 403（无权限）：告知用户他们缺少所需权限，并建议联系管理员授予相应权限。**例外 — 应优先尝试有文档说明的回退路径，不要立即终止：**如果某项操作遇到 403，且有针对该类型或替代方案的文档说明路径，请先尝试该路径；只有回退方案也失败时，才报告权限问题。尤其是，list-all-drives 遇到 403 时，必须先回退为 list-my-drives + list-my-group-drive（参见 references/drive.md），然后才能判定用户无法访问其空间。
3. OperationNotSupport（400）：此域名未启用所请求的功能。告知用户，并建议联系 PDS 技术支持启用该功能。
4. InvalidParameter（400）：参数格式错误。对照文档检查命令，修正参数格式后重试。请勿编造参数。
5. 限流 / 超时：仅允许 CLI 对可安全重放的读取、列表和轮询操作进行重试。对于创建、更新、移动、复制、共享、处理和归档操作，模糊超时可能意味着服务器已提交更改；任何重试前都要先确认最终状态。
6. 结果不明确：说明是否成功尚不确定，尽可能按确切 ID/路径核对，并且绝不要声称操作成功或盲目重放变更操作。
7. CLI 以非零退出码结束且没有 JSON 正文：报告 stderr。仅对只读命令重试一次；变更操作按上述方式核对。