Alibabacloud Pds Intelligent Workspace

PDS (Cloud Drive)

Please read this entire skill document carefully

Features

• For getting drive/drive_id, querying enterprise space, team space, personal space -> read references/drive.md
• For uploading local files to enterprise space, team space, personal space → read references/upload-file.md
• For downloading files from enterprise space, team space, personal space to local → read references/download-file.md
• For searching or finding files → read references/search-file.md
• For document/audio/video analysis, quick view, summarization on cloud drive → read references/multianalysis-file.md
• For image search, similar image search, image-text hybrid retrieval → read references/visual-similar-search.md
• For mount app, install mount app, uninstall mount app, stop mount app → read references/mountapp.md
• For image editing, image processing → read references/image-editing.md
• For archive download, batch download, packaging multiple files into zip → read references/archive-download.md
• For PDS file sharing, share, share-link, share link, shared link, external sharing, create/cancel/update/search share links, or share permission control → read references/share-link.md

Agent Execution Guidelines

• Must execute steps in order: Do not skip any step, do not proceed to the next step before the previous one is completed.
• Must follow documentation: The aliyun pds cli commands and parameters must follow this document's guidance, do not fabricate commands.
• [MUST] CLI User-Agent — Every aliyun CLI command invocation must include:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Core Concepts:

• Domain: PDS instance with a unique domain_id, data is completely isolated between domains
• User: End user under a domain, has user_id
• Group: Team organization under a domain, divided into enterprise group and team group
• Drive: Storage space, can belong to a user (personal space) or team (team/enterprise space)
• File: File or folder under a space, has file_id
• Mountapp: PDS mount app plugin, used to mount PDS space to local, allowing users to access and manage files in PDS space conveniently
• Share / Share Link: PDS file sharing for files, folders, or an entire drive. In this skill, "share", "share-link", "share link", "shared link", and "external sharing" all refer to PDS file Sharing.

---

Installation Requirements

Step 1: Verify Aliyun CLI version

```bash

aliyun version # requires >= 3.3.16

```

If not installed or version is below 3.3.16, refer to references/cli-installation-guide.md for installation or upgrade.

>

Step 2: Enable auto plugin installation (after CLI version is satisfied)

```bash

aliyun configure set --auto-plugin-install true

```

>

Step 3: Verify PDS plugin version

```bash

aliyun pds version # requires >= 0.3.1

```

If version is below 0.3.1, run:

```bash

aliyun plugin update

```

---

CLI Initialization (MUST run before Core Workflow)

At the start of the Core Workflow (before any CLI invocation):

[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace"

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow success, workflow failure, error/exception, user cancellation, session end, or any other scenario where no further CLI commands will be executed. AI-mode is only used for Agent Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

---

Authentication Configuration

Prerequisites: Alibaba Cloud credentials must be configured

>

Security Rules:

- Forbidden to read, output, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is forbidden)

- Forbidden to ask users to input AK/SK directly in conversation or command line

- Forbidden to use aliyun configure set to set plaintext credentials

- Only allowed to use aliyun configure list to check credential status

>

Check credential configuration:

```bash

aliyun configure list

```

>

Confirm the output shows a valid profile (AK, STS, or OAuth identity).

>

If no valid configuration exists, stop first.

1. Obtain credentials from Alibaba Cloud Console

2. Configure credentials outside this session (run aliyun configure in terminal or set environment variables)

3. Run aliyun configure list to verify after configuration is complete

Quick Setup (only if prerequisites above are not met):

# 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-Specific Configuration

Before executing any PDS operations, you must first configure domain_id, user_id, and authentication type -> read references/config.md

References

Error Handling

1. If file search fails, please read references/search-file.md and strictly follow the documented process to re-execute file search.

PDS Archive Download Guide

Scenario: When you need to download multiple files/folders as a single zip archive from PDS Purpose: Package multiple files into one zip file and download it

---

Prerequisites

• The archive download feature must be enabled for the PDS domain (it's a paid add-on feature)
• You need read and download permissions on all files to be archived
• You must have the drive_id and file_id list of the files to archive

Limitations

• Archive format: only zip is supported
• Maximum 500 files in the top-level file list; maximum 10,000 files after recursive traversal
• Maximum total file size: 10GB

---

Step 1: Create Archive Task

Create an archive download task using the aliyun pds archive-files command:

aliyun pds archive-files \
  --drive-id <drive_id> \
  --name "<archive_name>.zip" \
  --file-ids <file_id_1> <file_id_2> <file_id_3> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Description:

• --drive-id: The drive_id of the space where the files are located
• --name: Name for the generated zip archive (must end with .zip)
• --file-ids: Space-separated list of file IDs to be archived (supports files and folders). Do NOT use JSON array format.

Output: Returns a JSON object containing async_task_id:

{
  "async_task_id": "testAsyncTaskId"
}

Note: The HTTP response code is 202, indicating the task has been accepted and is being processed asynchronously.

---

Step 2: Poll Task Status

Archive download is an asynchronous operation. You need to poll the task status until it completes.

Use the automated polling script:

python3 /skills/pds/scripts/pds_archive_poller.py \
  --async-task-id <async_task_id> \
  --max-attempts 60

Parameter Description:

• --async-task-id: The async_task_id returned from Step 1
• --max-attempts: Maximum number of polling attempts (default: 60, with 5-second intervals)

Output on Success: The script prints the download URL when the task completes:

✅ Archive task completed!
Download URL: https://pds-data.aliyuncs.com/...

Alternative Manual Polling:

If the script is not available, you can manually poll using:

aliyun pds get-async-task \
  --async-task-id <async_task_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Polling Response Fields:

• state: Task state - Running (in progress), Succeed (completed), Failed (failed)
• url: Download URL for the archive (available when state is Succeed)
• message: Error message (available when state is Failed)

Example Success Response:

{
  "async_task_id": "testAsyncTaskId",
  "state": "Succeed",
  "url": "https://pds-data.aliyuncs.com/..."
}

---

Step 3: Download the Archive

Once you have the download URL from Step 2, save it to a variable first, then pass it to curl. This avoids shell parsing errors caused by special characters (&, %27, etc.) in the URL.

# Save URL to variable (from polling output or get-async-task response)
DOWNLOAD_URL="<download_URL_from_step2>"

# Download using the variable
curl -fL --max-time 3600 --retry 3 --retry-delay 5 -o <archive_name>.zip "${DOWNLOAD_URL}"

Parameter Description:

• -f: Fail on HTTP errors (returns non-zero exit code)
• -L: Follow redirects automatically
• --max-time 3600: Maximum time for the entire download operation (seconds)
• --retry 3: Retry up to 3 times on transient failures
• --retry-delay 5: Wait 5 seconds between retries

Important: Always use a shell variable for the URL rather than pasting it directly into the command. URLs from PDS contain query parameters with &, encoded quotes (%27), and security tokens that can break shell parsing if not handled correctly.

Note: The download URL has a default validity of 10 minutes. If expired, re-poll the task to get a new URL.

---

Complete Example

Archive three files from drive drive123 into project_files.zip:

# Step 1: Create archive task
aliyun pds archive-files \
  --drive-id drive123 \
  --name "project_files.zip" \
  --file-ids fileId1 fileId2 fileId3 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

# Step 2: Poll until complete (using the automated script)
python3 /skills/pds/scripts/pds_archive_poller.py \
  --async-task-id <returned_async_task_id> \
  --max-attempts 60

# Step 3: Save URL to variable and download
DOWNLOAD_URL="<download_URL_from_step2>"
curl -fL --max-time 3600 --retry 3 --retry-delay 5 -o project_files.zip "${DOWNLOAD_URL}"

---

Error Handling

1. If the archive task fails (state is Failed), check the message field for the error reason. 2. Common errors:

• Files exceed size limit (10GB total)
• Too many files (>500 top-level or >10,000 recursive)
• Insufficient permissions on one or more files
• Archive download feature not enabled for the domain

3. If polling times out, the task may still be running. Wait and retry polling with the same async_task_id.

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.16+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.16 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.16)
aliyun version

Using Binary

# Download
wget --timeout=600 https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget --timeout=600 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget --timeout=600 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget --timeout=600 https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "China East 1 (Hangzhou)"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.16+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

PDS Aliyun CLI Configuration Guide (Important)

Scenario: Required configuration when using aliyun pds cli for the first time Purpose: Configure domain_id, user_id, and authentication type for aliyun pds cli

---

Before executing any PDS operations, you must first configure domain_id, user_id, and authentication type:

Step 1: Verify if configuration already exists (only needs to be configured once during initialization)

aliyun pds get-user --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

If already configured successfully, it will return the current logged-in user information, and you can skip the subsequent steps.

Step 2: Query domain list using aliyun pds list-domains (skip this step if you already have the domain_id to configure)

aliyun pds list-domains --service-code edm --limit 100 --region cn-beijing --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

The returned JSON structure is as follows. Extract the domain list from the response and display it to the user in a table format with columns domain_id and domain_name, prompting the user to select one domain. (If there is only one domain, use it directly without asking)

{
	"items": [{
      "domain_id": "bj322",
      "domain_name": "beijing-31216",
      "region_id": "cn-beijing",
      "service_code": "edm"
    }],
	"next_marker": ""
}

This step requires obtaining the selected domain_id before proceeding to the next step.

Step 3: Query user list under the domain using aliyun pds list-user (skip this step if you already have the user_id to configure)

# First configure domain_id with ak authentication type
aliyun pds config --domain-id <domain_id> --authentication-type ak --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace
# Then list users under this domain
aliyun pds list-user --limit 100 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

The returned JSON structure is as follows. Extract the user list from the response and display it to the user in a table format with columns user_id, nick_name, phone, email, and role, prompting the user to select one user. (If there is only one user, use it directly without asking)

{
	"items": [
		{
			"nick_name": "SuperAdmin",
			"role": "superadmin",
			"status": "enabled",
			"updated_at": 1774159173066,
			"phone": "123",
            "email": "test@example.com",
			"user_id": "a34527bd247e48b6b7e48d5c381b23f3"
		}
	],
	"next_marker": ""
}

This step requires obtaining the selected user_id before proceeding to the next step.

Step 4: Configure domain_id, user_id, and authentication type to aliyun pds cli using aliyun pds config

aliyun pds config \
  --domain-id <domain_id> \
  --user-id <user_id> \
  --authentication-type token \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Description:

• --domain-id: PDS domain ID (e.g., bj31216), provided by PDS user, check if included in the prompt
• --user-id: PDS user ID (e.g., a34527bd247e48b6b7e48d5c381b23f3), provided by PDS user, check if included in the prompt
• --authentication-type: Must be set to `token` if user_id parameter is provided, indicating access with user identity

Effect After Configuration:

• No need to pass --domain-id parameter for subsequent PDS API calls
• CLI will automatically use the configured domain_id and user_id

Verify Configuration:

# Test if configuration is effective, get-user API without parameters returns current logged-in user information in token scenario
aliyun pds get-user --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Extract the current logged-in user information from the returned JSON: domain_id: domain_id, user_id: user_id, nick_name: nick_name.

After successful configuration, notify the user: Current PDS DomainID: <domain_id>, logged-in user: <nick_name>(<user_id>)

Notes:

• Domain_id and user_id will be preset in CLI configuration
• User's token will be preset in Aliyun CLI configuration file
• After configuring once, no need to repeat configuration for subsequent operations

---

PDS File Download Guide

Scenario: When you need to download a file from PDS to local Purpose: Download file to local

---

Finding the File

Before downloading, you need the file's drive_id and file_id. Choose the method based on what you know:

---

Get File ID from File Path

If you want to download a file from a PDS drive but only have the file path (e.g., /Photos/2026/04/vacation.jpg), you need to traverse each level of the path to find the corresponding file's file_id. The steps are as follows: For example, to download the file /Photos/2026/04/vacation.jpg from a personal space:

1. First, use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id root --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace command to list all directories under the root directory (parent-file-id=root) and find the file_id of the Photos directory: a. If the Photos directory exists, note down its file_id b. If the Photos directory does not exist, the file path is invalid 2. Use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id <parent_file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace command to list all directories under the parent directory (parent-file-id=<Photos directory's file_id>) and find the file_id of the 2026 directory: a. If the 2026 directory exists, note down its file_id b. If the 2026 directory does not exist, the file path is invalid 3. Use the aliyun pds list-file --drive-id <drive_id> --type folder --parent-file-id <2026 directory's file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace command to list all directories under the parent directory (parent-file-id=<2026 directory's file_id>) and find the file_id of the 04 directory: a. If the 04 directory exists, note down its file_id b. If the 04 directory does not exist, the file path is invalid 4. Use the aliyun pds list-file --drive-id <drive_id> --type file --parent-file-id <04 directory's file_id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace command to list all files under the parent directory (parent-file-id=<04 directory's file_id>) and find the file_id of the vacation.jpg file: a. If the vacation.jpg file exists, note down its file_id b. If the vacation.jpg file does not exist, the file path is invalid 5. After obtaining the file_id of vacation.jpg, you can use this file_id to download the file

Note: When executing the aliyun pds list-file command, if there are no valid items returned and the next_marker is not empty, it means that the query is not complete and the next_marker needs to be used as the --marker parameter for the next list query until next_marker is empty.

---

Download File

Step 1: Get Download URL

Get the download link for the file:

aliyun pds get-download-url \
  --drive-id <drive_id> \
  --file-id <file_id> \
  --expire-sec 3600 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Description:

• --drive-id: The drive_id of the space where the file is located (obtained from search results)
• --file-id: The file_id of the file to download (obtained from search results)
• --expire-sec: Download link validity period (seconds), default 900, maximum 115200 (32 hours)

Output: Returns a JSON object containing url (download link), expiration, method, size, and other information.

Example Output:

{
  "url": "https://pds-data.aliyuncs.com/...",
  "expiration": "2024-01-15T11:30:00Z",
  "method": "GET",
  "size": 1048576
}

---

Step 2: Download File

Save the download URL to a variable first, then pass it to curl. This avoids shell parsing errors caused by special characters (&, +, =, security tokens) in PDS/OSS signed URLs.

# Save the URL from Step 1 response into a variable
DOWNLOAD_URL="<url_from_get-download-url_response>"

# Download using the variable
curl -fL --max-time 3600 --retry 3 --retry-delay 5 -o <output_filename> "${DOWNLOAD_URL}"

Parameter Description:

• -f: Fail on HTTP errors (returns non-zero exit code instead of saving error response to file)
• -L: Follow redirects automatically (PDS download URLs redirect to the actual OSS storage URL)
• --max-time 3600: Maximum time for the entire download operation (seconds)
• --retry 3: Retry up to 3 times on transient failures
• --retry-delay 5: Wait 5 seconds between retries

Important: Always use a shell variable for the URL. PDS download URLs contain query parameters with &, STS security tokens with +/=, and URL-encoded characters that will break if pasted directly into the command line without correct quoting. Using "${DOWNLOAD_URL}" with double quotes ensures the entire URL is passed intact.

Or use wget:

wget --timeout=3600 --max-redirect=10 -O <output_filename> "${DOWNLOAD_URL}"

---

Step 3: Verify Local File Exists

PDS Drive Concepts and API Reference

Scenario: Used when querying user's drive list (including personal space, enterprise space, team space, all spaces) Purpose: Get drive_id for user's personal space, team space, and enterprise space

---

Drive Concept Introduction

A PDS drive is a cloud storage space that can store files. A drive must have an owner, which can be either a user or a group.

• When a drive belongs to a user, it is that user's personal space.
• When a drive belongs to an enterprise group, it is an enterprise space.
• When a drive belongs to a team group, it is a team space.

Users have three types of spaces in a domain:

• Enterprise space
• Team space
• Personal space

When referring to "my PDS drive" without specifying which type of space, it should be understood as all spaces: including enterprise space, team space, and personal space

Drive Query API Reference

Query Method for Enterprise Space and Team Space

You can query using the list group drives API. The items field in the response contains the user's team space list, and the root_group_drive field contains the enterprise space object.

aliyun pds list-my-group-drive --limit 100 --marker "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Output: Returns JSON containing enterprise space and team space, including items, root_group_drive, next_marker, etc. Detailed explanation:

• items: Contains team space list. There may be multiple team spaces. If not all displayed on one page, next_marker will be returned. If there are no team spaces, this field returns empty.
• root_group_drive: Contains enterprise space object. There is at most one enterprise space. If none exists, this field returns empty.
• next_marker: Used for pagination, indicates the marker for next page. Pass the returned next_marker to the marker parameter to query the next page. If no next page, this field returns empty.

The JSON objects returned in items and root_group_drive are Drive objects. Important attributes of Drive objects include:

• drive_id: Unique space ID, commonly used in API parameters to identify a drive (important parameter for identifying a space, other APIs may require this field as input)
• drive_name: Space name, commonly used for display
• total_size: Total space size in bytes
• used_size: Used space size in bytes
• owner_type: Owner type, either user or group
• owner: Owner ID

Example Output:

{
  "items": [
    {
      "category": "",
      "created_at": "2026-03-22T06:00:12.951Z",
      "creator": "a34527b***c381b23f3",
      "description": "",
      "domain_id": "bj12",
      "drive_id": "100",
      "drive_name": "Test Team Space 1",
      "drive_type": "normal",
      "encrypt_data_access": false,
      "encrypt_mode": "none",
      "owner": "e71ce9***c5862d5",
      "owner_type": "group",
      "permission": null,
      "relative_path": "",
      "status": "enabled",
      "store_id": "fb651***943990a",
      "total_size": 107374182400,
      "updated_at": "2026-03-22T06:00:12.952Z",
      "used_size": 138194
    },
    {
      "category": "",
      "created_at": "2026-03-22T06:00:12.951Z",
      "creator": "a34527***81b23f3",
      "description": "",
      "domain_id": "bj12",
      "drive_id": "101",
      "drive_name": "Test Team Space 2",
      "drive_type": "normal",
      "encrypt_data_access": false,
      "encrypt_mode": "none",
      "owner": "e71ce9***b7fc5862d5",
      "owner_type": "group",
      "permission": null,
      "relative_path": "",
      "status": "enabled",
      "store_id": "fb6516****45c943990a",
      "total_size": 107374182400,
      "updated_at": "2026-03-22T06:00:12.952Z",
      "used_size": 138194
    }
  ],
  "next_marker": "",
  "root_group_drive": {
    "category": "",
    "created_at": "2026-03-22T05:55:03.280Z",
    "creator": "system",
    "description": "",
    "domain_id": "bj12",
    "drive_id": "103",
    "drive_name": "Test Space",
    "drive_type": "normal",
    "encrypt_data_access": false,
    "encrypt_mode": "none",
    "owner": "9c251e****b9f952f",
    "owner_type": "group",
    "permission": null,
    "relative_path": "",
    "status": "enabled",
    "store_id": "fb651****43990a",
    "total_size": 107374182400,
    "updated_at": "2026-03-23T07:08:40.098Z",
    "used_size": 240062520
  }
}

In the above example output, team space drive_ids are: 100 and 101, enterprise space drive_id is: 103

Query API for Personal Space

You can query using the list my drives API. The items field in the response contains the user's personal space list.

aliyun pds list-my-drives --limit 100 --marker "" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

The JSON array in the items field returned by the personal space query API contains personal space Drive objects. Important attributes of Drive objects include:

• drive_id: Unique space ID, commonly used in API parameters to identify a drive (important parameter for identifying a space, other APIs may require this field as input)
• drive_name: Space name, commonly used for display
• total_size: Total space size in bytes
• used_size: Used space size in bytes
• owner_type: Owner type, either user or group
• owner: Owner ID

{
    "items": [
        {
            "category": "",
            "created_at": "2026-03-22T05:59:33.037Z",
            "creator": "a34527b***81b23f3",
            "description": "",
            "domain_id": "bj31216",
            "drive_id": "108",
            "drive_name": "SuperAdmin (Test)",
            "drive_type": "normal",
            "encrypt_data_access": false,
            "encrypt_mode": "none",
            "owner": "a34527b***81b23f3",
            "owner_type": "user",
            "permission": null,
            "relative_path": "",
            "status": "enabled",
            "store_id": "fb6516***c943990a",
            "total_size": 107374182400,
            "updated_at": "2026-03-23T08:45:35.541Z",
            "used_size": 950709133
        }
    ],
    "next_marker": ""
}

In the above example output, personal space drive_id is 108

PDS Image Editing Guide

Scenario: Already obtained drive_id, file_id, revision_id, need to perform image editing operations

Purpose: Edit images through the Process interface, including scaling, cropping, rotation, segmentation, removal, watermark and other features, and save the results to PDS

---

Image Editing Capabilities Overview

PDS image editing capabilities are implemented through x-pds-process=image/xxx, supporting basic image processing such as scaling, cropping, rotation, as well as AI image processing such as segmentation and removal.

Basic Image Processing

Basic image processing capabilities are provided by OSS. For detailed parameters and usage of each feature, please refer to the reference links in the overview table.

For image watermarks in watermark processing, the watermark image's pds_schema format is required, i.e., pds://domains/{domain_id}/drives/{drive_id}/files/{file_id}/revisions/{revision_id}, which needs to be URL-safe base64 encoded before use.

Watermark Processing

Image Watermark

Watermark image pds_schema format: pds://domains/{domain_id}/drives/{drive_id}/files/{file_id}/revisions/{revision_id}

>

The pds_schema needs to be URL-safe base64 encoded before use.

AI Image Processing

Feature Combination

Multiple image editing capabilities can be combined, separated by /, executed from left to right in order:

Note: Only the first operation needs the image/ prefix, subsequent operations can be written directly without the prefix.

image/crop,x_50,y_50,w_200,h_200/resize,w_100/sharpen,90
image/rotate,90/resize,p_150

---

Core Workflow

Image Editing and Save-as

Save edited image to specified PDS location.

Step 1: Construct x-pds-process parameter and save to variable

Important: Since x-pds-process parameter contains base64 encoding (which may include special characters like =), parameters must be passed using variables to avoid shell parsing errors from direct hardcoding.

# Generate parameter and save to variable
X_PDS_PROCESS=$(python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" \
  --saveas \
  --target-domain-id ${TARGET_DOMAIN_ID} \
  --target-drive-id ${TARGET_DRIVE_ID} \
  --target-file-id ${TARGET_FILE_ID} \
  --target-revision-id ${TARGET_REVISION_ID} \
  --file-name "edited_image.jpg")

Save-as Parameter Description:

• --saveas: Enable save-as functionality
• --target-domain-id: domain_id of the save-as target (required)
• --target-drive-id: drive_id of the save-as target (required)
• --target-file-id: target file ID or parent folder ID (required)
• --target-revision-id: target version ID (required when overwriting existing file, leave empty when creating new file)
• --file-name: saved file name (required)

Step 2: Execute save-as request

aliyun pds process \
  --resource-type file \
  --drive-id ${SOURCE_DRIVE_ID} \
  --file-id ${SOURCE_FILE_ID} \
  --x-pds-process "${X_PDS_PROCESS}" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Success Response (HTTP 200):

{
  "drive_id": "drive_id of saved file",
  "file_id": "file_id of saved file",
  "revision_id": "revision_id of saved file version"
}

---

Common Scenario Examples

Scenario 1: Image Scaling and Save-as

# Scale to width 200px, height adjusted proportionally, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "resized_image.jpg"

# Scale to height 200px, width adjusted proportionally, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/resize,h_200" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "resized_image.jpg"

# Limit maximum width and height, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/resize,l_200" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "resized_image.jpg"

Scenario 2: Image Rotation and Save-as

# Rotate 90 degrees and save-as
python scripts/render_image_editing_process.py \
  --operations "image/rotate,90" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "rotated_image.jpg"

# Auto-orient (based on EXIF information) and save-as
python scripts/render_image_editing_process.py \
  --operations "image/auto-orient,1" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "auto_oriented_image.jpg"

Scenario 3: Auto Segmentation and Save-as

# Automatically identify and extract subject, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/segment" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "segmented_image.png"

Scenario 4: Rectangle Segmentation and Save-as

# Extract top-left 100x100 area, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/segment,boxes_(x_0,y_0,w_100,h_100)" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "cropped_image.png"

Scenario 5: Text-based Segmentation and Save-as

# Segment by text description, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/segment,prompt_5bCP5aqr" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "segmented_cat.png"

Note: prompt parameter needs to be base64 encoded first, for example "kitten" in Chinese base64 encodes to "5bCP5aqr"

Scenario 6: Rectangle Area Removal and Save-as

# Remove top-left 50x50 area, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/remove,boxes_(x_0,y_0,w_50,h_50)" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "removed_image.jpg"

Scenario 7: Combined Operations and Save-as

# Scale first then rotate, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" "rotate,45" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "processed_image.jpg"

# Scale + sharpen + quality adjustment, and save-as
python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" "sharpen,100" "quality,q_80" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id" \
  --file-name "processed_image.jpg"

Scenario 8: Edit and Save-as

# Scale image and save-as to specified location
python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "parent_folder_id_123" \
  --file-name "resized_image.jpg"

# Overwrite existing file
python scripts/render_image_editing_process.py \
  --operations "image/resize,w_200" \
  --saveas \
  --target-domain-id "bj31216" \
  --target-drive-id "1020" \
  --target-file-id "existing_file_id_456" \
  --target-revision-id "revision_789" \
  --file-name "resized_image.jpg"

---

Error Handling

Common Errors

1. Feature Not Enabled

{
  "code": "OperationNotSupport",
  "message": "This operation is not supported."
}

Solution: Contact PDS technical support to enable image editing functionality.

2. Insufficient Permissions

{
  "code": "ForbiddenNoPermission.file",
  "message": "No Permission to access resource file"
}

Solution:

• Ensure current user has DownloadFile permission for source image
• Ensure current user has DownloadFile permission for watermark image
• Ensure current user has CreateFile permission for save-as target location

3. Invalid Parameter (InvalidParameter.XPdsProcess)

{
  "code": "InvalidParameter.XPdsProcess",
  "message": "The input parameter x-pds-process is not valid."
}

Common Causes:

• Directly hardcoding x-pds-process parameter in command line, special characters like = in base64 encoding are incorrectly parsed by shell
• Parameter contains invisible characters (such as line breaks)

Solution:

• Use variable to pass parameter (recommended):

  X_PDS_PROCESS=$(python scripts/render_image_editing_process.py \
    --operations "image/resize,h_150" \
    --saveas \
    --target-domain-id "bj31216" \
    --target-drive-id "101" \
    --target-file-id "folder_id" \
    --file-name "output.png")
  
  aliyun pds process \
    --resource-type file \
    --drive-id "101" \
    --file-id "source_file_id" \
    --x-pds-process "${X_PDS_PROCESS}" \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

• Ensure there are no extra spaces or line breaks in the parameter
• Check if base64 encoding is correct

---

Best Practices

1. Operation Order Optimization

Image editing operations are executed from left to right. Arranging operations in optimal order improves processing efficiency:

• Crop first then scale: reduces data volume for subsequent processing
• Rotate first then crop: avoids coordinate changes after rotation

2. Coordinate Determination

Before using point-based or rectangle operations, it is recommended to obtain image dimensions first to ensure coordinate values are within valid range.

---

FAQ

Q: How to get image dimension information?

A: You can use aliyun pds get-file command to get file information, the returned data includes image width and height information.

aliyun pds get-file \
  --drive-id <drive_id> \
  --file-id <file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

response example:

{
  "file_id": "5d79206586bb5dd69fb34c349282718146c55da7",
  "name": "example.jpg",
  "image_media_metadata": 
    {
      "width": 1920,
      "height": 1080
    }
}

Q: What is the difference between segmentation and removal operations?

A:

• Segmentation (segment): Extract the main subject from the image, background becomes transparent
• Removal (remove): Remove content from specified area in the image, AI automatically fills the background

Q: What is the execution order when multiple operations are combined?

A: Operations are executed from left to right in the order they appear in x-pds-process.

Q: Will save-as operation modify the source file?

A: No, save-as operation creates a new file, the source file remains unchanged.

---

Image Limitations

• Size Limit: Only supports images within 20MB
• Format Limit: Only supports the following formats
• jpg, jpeg, bmp, png, heic, webp, tiff, avif

Permission Requirements

• Need DownloadFile permission for the image being edited
• Need DownloadFile permission for watermark images
• Need CreateFile permission for save-as target location

---

Mount App Installation Guide

Overview

mountapp is a PDS cloud drive mount plugin that supports mounting PDS cloud drive storage to local computer, allowing access to files in PDS cloud drive like local files. It supports Windows, macOS, and Linux systems. The following sections describe the download, installation, startup, and mounting process of the mount app, including:

• Get plugin latest version and download URL
• Download software installation package
• Execute installation process
• Start mount app
• Complete mounting
• Verify installation results
• Query mount app status
• Query mount configuration
• Modify mount app configuration

Prerequisites

Before installing mount app, verify that aliyun-cli and PDS plugin are installed and configured correctly

---

Workflow

Step 1: Check if Mount App is Already Installed and Running

Check if installed:

• Windows/macOS systems:
• Check if there are mountapp related files in ~/.edm/plugins/mountapp directory
• View version number via ~/.edm/plugins/mountapp/plugin.json

If already installed, view the plugin configuration in mountapp directory to get the installed version number:

{
  "id": "mountapp",
  "name": "mountapp",
  "version": "0.8.2",
  "manifest_version": "v2",
  "client_id": "GzpsX2VzKLNKNsxProd",
  "redirect_uri": "https://web-sv.aliyunpds.com/plugin_callback",
  "scripts": {
    "start": "chmod +x bin/start.sh;bin/start.sh ${port} ${user_id}",
    "install": "chmod +x bin/install.sh;bin/install.sh",
    "upgrade": "chmod +x bin/upgrade.sh;bin/upgrade.sh",
    "stop": "chmod +x bin/stop.sh;bin/stop.sh",
    "uninstall": "chmod +x bin/uninstall.sh;bin/uninstall.sh"
  }
}

For example, the version field in the above configuration is the installed version number.

• Linux systems:
• Check if there are mountapp related files in /opt/mountapp directory
• View service list via systemctl list-units --type=service | grep mountapp
• View service status via systemctl status mountapp
• View installed rpm packages via rpm -qa | grep mountapp
• View installed dpkg packages via dpkg -s mountapp

---

Step 2: Get Mount App Plugin Download URL

Use command line tool to get the latest mount app version:

aliyun pds mountapp --action get-latest-version --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Response format:

{
  "version": "0.8.2",
  "url": "https://example.com/mountapp-0.8.2.zip"
}

Version comparison logic:

• If installed version matches latest version, skip Step 3 and go directly to Step 6
• If installed version differs from latest version, continue with Step 3 to download latest installation package
• If not installed locally, proceed to Step 3 to download latest installation package

---

Step 3: Download Installation Package

Based on current operating system and download URL from Step 2, download mount app plugin installation package to temporary directory.

Different operating systems require different installation package types:

• Windows: zip
• macOS: zip
• Linux: rpm

Download command example:

# Get download URL
latest_info=$(aliyun pds mountapp --action get-latest-version --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace)
download_url=$(echo "$latest_info" | jq -r '.url')
version=$(echo "$latest_info" | jq -r '.version')

# Download to temporary directory
curl --max-time 600 -fL -o "/tmp/mountapp-${version}.zip" "$download_url"  # Windows/macOS
curl --max-time 600 -fL -o "/tmp/mountapp-${version}.rpm" "$download_url"  # Linux

---

Step 4: Execute Installation

Execute installation based on operating system and installation package type:

Windows Installation

1. Extract ZIP package:

# Extract to ~/.edm/plugins/
Expand-Archive -Path "$env:TEMP\mountapp-${version}.zip" -DestinationPath "$env:USERPROFILE\.edm\plugins\" -Force

2. Install Dokan Driver: Before installing Dokan driver, check if already installed using cmd query command:

sc query dokan1

Expected output: If service status is displayed (RUNNING or STOPPED), it is installed; if service does not exist, Dokan driver needs to be installed.

# Use extracted Dokan MSI installation file
$dokanInstaller = "$env:USERPROFILE\.edm\plugins\mountapp\pkg\Dokan_x64-noVC.msi"
Start-Process msiexec.exe -ArgumentList "/i `"$dokanInstaller`" /qn /norestart" -Wait -Verb RunAs

macOS Installation

1. Extract ZIP package:

# Extract to ~/.edm/plugins/
unzip -o "/tmp/mountapp-${version}.zip" -d ~/.edm/plugins/

Grant execute permissions to extracted folder

chmod +x ~/.edm/plugins/mountapp/bin/DasfsWorker
chmod +x ~/.edm/plugins/mountapp/bin/dasd
chmod +x ~/.edm/plugins/mountapp/bin/*.sh

2 Apple Silicon Special Settings:

If current machine has Apple silicon processor (M1/M2/M3, etc.), additional Apple settings need to be modified to allow system extension loading.

Please refer to Apple Official Documentation to complete configuration.

3 macFUSE Dependency Notes:

⚠️ Important: macOS depends on macFUSE driver, which needs to be installed manually.

macFUSE is a FUSE (Filesystem in Userspace) implementation for macOS that allows users to run their own file systems without kernel support. When installing macFUSE, it needs to match the current operating system version, otherwise compatibility issues may occur. The correspondence is as follows: Here is the macOS system version and recommended macFUSE driver version correspondence table:

Based on current macOS version, guide users to complete installation.

• If not currently installed, guide users to download and install the corresponding version of macFUSE.
• If currently installed macFUSE version does not match system version, guide users to uninstall and install the corresponding version of macFUSE.

After macFUSE installation, if prompted System Extension Blocked, follow these steps:

• Click to open Security & Privacy Preferences, navigate to System Settings > Privacy & Security
• In Security area, select Allow apps downloaded from App Store and identified developers
• Authorize macFUSE (Developer: Benjamin Fleischer) to load.

After modifying above settings, you may need to restart the computer.

Linux Installation

1. CentOS/RedHat (RPM systems):

# Directly install RPM package
sudo rpm -ivh /tmp/mountapp-${version}.rpm

2. Ubuntu/Debian (DEB systems):

# Install conversion tool
sudo apt-get install -y alien

# Convert RPM to DEB
cd /tmp
sudo alien mountapp-${version}.rpm

# Install converted DEB package
sudo dpkg -i mountapp_${version}_*.deb

3. Check FUSE2 Dependency:

⚠️ Important: Linux systems require fuse2 version.

# Check if fuse2 is installed
dpkg -l | grep fuse  # Debian/Ubuntu
rpm -qa | grep fuse  # CentOS/RedHat

# If fuse2 is not installed, install it first
sudo apt-get install -y fuse  # Ubuntu/Debian (fuse2.9.9)
sudo yum install -y fuse      # CentOS/RedHat

Notes:

• Must install fuse2 (e.g., fuse2.9.9)
• If system has fuse3, no need to uninstall fuse3, you can directly install fuse2, both can coexist

---

Step 5: Verify Installation

Verify installation results based on operating system:

Windows Verification

1. Check if files exist:

# Check mountapp directory
Test-Path "$env:USERPROFILE\.edm\plugins\mountapp"

Expected output: True

2. Check Dokan service status:

# Query Dokan service
sc query dokan1

Expected output: Should display service status (RUNNING or STOPPED)

macOS Verification

# Check mountapp directory
ls -la ~/.edm/plugins/mountapp

Expected output: Should display mountapp related files and directories

Linux Verification

# Check mountapp directory
ls -la /opt/mountapp

Expected output: Should display mountapp related files and directories

---

Step 6: Start Software

Pre-start check: First check if mount app is already running. If running, skip this step and go directly to Step 7.

Check Method

• Windows: View Task Manager, check if DasfsWorker process is running
• macOS: Check if DasfsWorker process is running
• Linux: Use command systemctl status mountapp to check if mountapp service is running

Windows Start Mount App

If not running, use following steps to start:

1. Get User ID:

$userIdJson = aliyun pds mountapp --action get-user-id --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace
$userId = ($userIdJson | ConvertFrom-Json).user_id

2. Generate Random Port and Save:

# Randomly select a port from range 49152~65535
$port = Get-Random -Minimum 49152 -Maximum 65536

# Write to port file (no newline)
[System.IO.File]::WriteAllText("$env:USERPROFILE\.dasfs-worker-port", $port)

3. Create startup script `start-task.ps1`:

$binDir = "$env:USERPROFILE\.edm\plugins\mountapp\bin"
$logDir = "$env:USERPROFILE\.pdsdrive\log"

# Ensure log directory exists
New-Item -ItemType Directory -Path $logDir -Force | Out-Null

# Create startup script
$script = @"
`$logDir = `"$logDir`"
cd `"$binDir`"
.\start.bat $port $userId 2>&1 | Out-File -FilePath `"`$logDir\mountapp-task.log`" -Append
"@

$script | Out-File -FilePath "$binDir\start-task.ps1" -Encoding UTF8

4. Register Windows Scheduled Task:

$taskName = "PDS MountApp Service"

# Define task action
$action = New-ScheduledTaskAction `
  -Execute "powershell.exe" `
  -Argument "-ExecutionPolicy Bypass -WindowStyle Hidden -File `"$binDir\start-task.ps1`"" `
  -WorkingDirectory $binDir

# Define task principal (run as current user)
$principal = New-ScheduledTaskPrincipal `
  -UserId "$env:USERDOMAIN\$env:USERNAME" `
  -LogonType S4U `
  -RunLevel Limited

# Define trigger (at system startup)
$trigger = New-ScheduledTaskTrigger -AtStartup

# Define task settings (auto restart on failure)
$settings = New-ScheduledTaskSettingsSet `
  -AllowStartIfOnBatteries `
  -DontStopIfGoingOnBatteries `
  -RestartCount 999 `
  -RestartInterval (New-TimeSpan -Minutes 1)

# Register scheduled task
Register-ScheduledTask `
  -TaskName $taskName `
  -Action $action `
  -Principal $principal `
  -Trigger $trigger `
  -Settings $settings `
  -Force

# Start task
Start-ScheduledTask -TaskName $taskName

5. Verify Startup:

Wait 5-10 seconds, then check process:

Get-Process | Where-Object {$_.ProcessName -like "*DasfsWorker*"}

Expected output: Should display DasfsWorker process running

---

macOS Start Mount App

Use launchd (plist) method to start mount app, which is the most stable and reliable startup method on macOS.

1. Get User ID and Generate Port:

# Get user ID
user_id_json=$(aliyun pds mountapp --action get-user-id --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace)
user_id=$(echo "$user_id_json" | jq -r '.user_id')

# Generate random port
port=$((49152 + RANDOM % 16384))

# Write to port file (no newline)
echo -n $port > ~/.dasfs-worker-port

2. Create plist file:

Create ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Global unique identifier -->
    <key>Label</key>
    <string>com.aliyun.pds.mountapp</string>

    <!-- Use bash to execute DasfsWorker directly -->
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd $HOME/.edm/plugins/mountapp/bin &amp;&amp; ./DasfsWorker start --port=PORT_PLACEHOLDER --userId=USERID_PLACEHOLDER --dataPath=$HOME/.pdsdrive --logPath=$HOME/.pdsdrive/log</string>
    </array>

    <!-- Auto start when user logs in -->
    <key>RunAtLoad</key>
    <true/>

    <!-- Auto restart after process exits (only on non-successful exit or crash) -->
    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
        <key>Crashed</key>
        <true/>
    </dict>

    <!-- Working directory -->
    <key>WorkingDirectory</key>
    <string>$HOME/.edm/plugins/mountapp/bin</string>

    <!-- Environment variables -->
    <key>EnvironmentVariables</key>
    <dict>
        <key>HOME</key>
        <string>$HOME</string>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>

    <!-- Log output -->
    <key>StandardOutPath</key>
    <string>$HOME/.pdsdrive/log/mountapp.out.log</string>
    <key>StandardErrorPath</key>
    <string>$HOME/.pdsdrive/log/mountapp.err.log</string>

    <!-- Startup interval: avoid frequent restarts after crash -->
    <key>ThrottleInterval</key>
    <integer>10</integer>
</dict>
</plist>

Note: Placeholders in plist file need to be replaced:

• Replace PORT_PLACEHOLDER with actual port number
• Replace USERID_PLACEHOLDER with actual user ID
• Replace $HOME with current user's home directory path

3. Load and Start launchd Service:

# Ensure log directory exists
mkdir -p ~/.pdsdrive/log

# First time load and start
launchctl load ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist
sleep 2
launchctl start com.aliyun.pds.mountapp
sleep 3

# If already loaded, unload first then reload
# launchctl unload ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist 2>/dev/null
# sleep 1
# launchctl load ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist
# sleep 2
# launchctl start com.aliyun.pds.mountapp

4. Verify Startup:

Wait 3-5 seconds, then check if process started successfully:

ps aux | grep DasfsWorker | grep -v grep

Expected output: Should display DasfsWorker process running

Note: After using launchctl unload to stop service, it is recommended to wait 1-2 seconds before reloading to ensure process completely stops.

---

Linux Start Mount App

Linux starts automatically after installing rpm or deb package, no additional startup needed. The port number is already written to ~/.dasfs-worker-port file.

If manual startup is needed:

# Start service
sudo systemctl start mountapp

# Set to start on boot
sudo systemctl enable mountapp

# View status
systemctl status mountapp

---

Step 7: Check and Enable Mount App Feature

Before mounting, you need to enable mount app feature using command line:

aliyun pds mountapp --action enable-mountapp --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Success output:

{"mount_app_enable": "success", "domain_id": "bj123"}

Notes: 1. If enabling fails, check:

• Whether PDS drive DomainId, UserID, etc. are configured
• Whether the configured account has permission to enable mount app feature

2. Enabling mount app only needs to be done once. If already enabled successfully, no need to repeat

---

Step 8: Complete Mounting

8.1 Query Mount App Status

Query mount app status before mounting. If already mounted, skip mounting step:

aliyun pds mountapp --action get-status --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Example output:

{
    "UserId": "123456",
    "DomainId": "bj123",
    "Username": "root",
    "MountedStatus": "MountSuc",
    "Message": ""
}

Status description:

• MountSuc: Already mounted successfully, no need to mount again
• Starting: Mounting in progress, continue querying status. If not completed within 2 minutes, report mounting failure, need to remount
• Init: Not mounted, need to execute mounting operation

---

8.2 Execute Mounting Operation

If status is Init, execute mounting:

# Basic mount command
aliyun pds mountapp --action mount --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

# Linux non-root users need to specify mount-user
aliyun pds mountapp --action mount --mount-user admin --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Note: For Linux systems, check current running user. If not root user, add --mount-user parameter.

Success output:

{"domain_id": "bj123", "user_id": "123456", "message": "mount success, please check status"}

---

8.3 Verify Mount Status

After command execution succeeds, confirm mounting completion by querying status:

aliyun pds mountapp --action get-status --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Expected output:

{
    "DomainId": "bj123",
    "Message": "",
    "MountedStatus": "MountSuc",
    "SubDomainId": "",
    "UserId": "123456",
    "Username": "user1"
}

If MountedStatus is MountSuc, mounting is successful!

---

8.4 Query Mount Configuration

After successful mounting, you can query mount app configuration:

aliyun pds mountapp --action get-config --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Example output:

{
   "DiskCachePath": "/Users/user1/.pdsdrive/cf8833674b2544b8aeeed2426bbdc4d9/cache",
   "DiskCacheSize": 5,
   "DomainId": "bj123",
   "Language": "zh",
   "MemoryCacheSize": 64,
   "MountPath": "/Users/user1/PDSDrive",
   "MountUser": "",
   "ShowIconPreview": true,
   "SubDomainId": "",
   "UserId": "cf8833674b2544b8aeeed2426bbdc4d9",
   "Version": "0.8.2"
}

Important: The MountPath field is the mount point path where mounting succeeded. Users can access this path to view mounted files.

---

8.5 About Boot Startup and Exception Handling

1. Not mounted after boot startup: If after boot startup, query status shows not mounted (Init), need to execute mounting using command aliyun pds mountapp --action mount --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

2. After process abnormal restart: If process has exception and restarts, query status shows not mounted (Init), need to execute mounting using command aliyun pds mountapp --action mount --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Step 9: Modify Mount App Configuration

Currently supports modifying mount app language. The command:

aliyun pds mountapp --action set-config --language zh --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Currently supports three languages:

• zh: Chinese
• en: English
• es: Spanish

Note: Changing mount language requires remounting to take effect

---

Success Verification

Verify Mount Point is Accessible

Access mount point based on operating system:

Windows:

# Default mount point: P:\
dir P:\

macOS/Linux:

# Default mount point: ~/PDSDrive
ls -la ~/PDSDrive

Expected output:

Personal Space
Team Space
Received Shares

Expect at least one of the above three directories to exist

Mount App Directory Structure

After successful mounting, top-level directory is read-only, with some system-level directories:

tree -L 1 ~/PDSDrive/
~/PDSDrive/
├── Personal Space
├── Team Space
└── Received Shares

Directory description:

• Personal Space: This directory allows direct read/write
• Team Space: This directory is read-only, lists team spaces with permissions. After entering team space, may be read-only or read-write depending on granted permissions
• Received Shares: This directory is read-only, lists shares with permissions. After entering share directory, may be read-only or read-write depending on granted permissions

Access Files

Windows:

# Access Personal Space
dir "P:\Personal Space"

macOS/Linux:

# Access Personal Space
ls -la ~/PDSDrive/Personal\ Space

---

Stop and Uninstall

Important: Stopping and uninstalling mount app are high-risk operations. Before operation, human confirmation is required: Please confirm all files opened under mount drive letter (such as P:\ on Windows) or mount directory (~/PDSDrive on macOS and Linux) have been saved and closed to avoid data loss. Only proceed with subsequent operations after human confirmation.

How to Stop Mount App

Windows

cd $env:USERPROFILE\.edm\plugins\mountapp\bin
.\stop.bat

Stop and unregister Windows scheduled task

Stop-ScheduledTask -TaskName "PDS MountApp Service" -ErrorAction SilentlyContinue
Unregister-ScheduledTask -TaskName "PDS MountApp Service" -Confirm:$false

macOS

# Use launchctl to stop service
launchctl stop com.aliyun.pds.mountapp
launchctl unload ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist

# Or use stop.sh script
cd ~/.edm/plugins/mountapp/bin
bash stop.sh

Linux

sudo systemctl stop mountapp

---

How to Uninstall Mount App Plugin

⚠️ Important: Must stop mount app service before uninstalling

Windows

1. Stop service:

cd $env:USERPROFILE\.edm\plugins\mountapp\bin
.\stop.bat

2. Delete scheduled task:

Unregister-ScheduledTask -TaskName "PDS MountApp Service" -Confirm:$false

3. Delete plugin files:

Remove-Item -Path "$env:USERPROFILE\.edm\plugins\mountapp" -Recurse -Force

macOS

1. Stop service:

launchctl stop com.aliyun.pds.mountapp
launchctl unload ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist
rm ~/Library/LaunchAgents/com.aliyun.pds.mountapp.plist

2. Delete plugin files:

rm -rf ~/.edm/plugins/mountapp

Linux

1. Stop service:

sudo systemctl stop mountapp
sudo systemctl disable mountapp

2. Uninstall software package:

RPM systems (CentOS/RedHat):

sudo rpm -e mountapp

DEB systems (Ubuntu/Debian):

sudo apt-get remove mountapp

---

Default Mount Points

Default mount points for different operating systems:

| Operating System | Default Mount Point | |---------|-----------|| | Windows | P:\ | | macOS | ~/PDSDrive | | Linux | ~/PDSDrive |

---

Usage Limitations

Mount app maps cloud drive storage to local file system, enabling access to PDS cloud drive files like local files. However, there are some limitations:

1. File type limitations:

• ✅ Supports upload/download of various file types
• ✅ Supports access to various documents, images, videos, etc.
• ❌ Does not support read/write of certain special files, such as: database files, git code repositories, svn, encrypted files, etc.

2. Collaboration limitations:

• ❌ Does not support simultaneous multi-user editing (collaboration)
• For multi-user collaborative editing, please use PDS cloud drive's online editing feature

3. Platform limitations:

• ❌ Does not support installation on Windows systems with ARM processors (e.g., some Microsoft Surface devices using Qualcomm Snapdragon processors)

4. Performance limitations:

• When simultaneously transferring more than 1000 files, may require longer time
• When single file size exceeds 1GB, may require longer time
• Recommendation: For large numbers of files or large file transfers, use enterprise cloud drive desktop client for best performance

5. Network requirements:

• Mount app has certain requirements for network bandwidth and stability
• When network bandwidth is low or network is unstable (e.g., mobile hotspot, restricted network environment), file upload/download may fail
• Recommendation: When network is poor, use sync backup or enterprise cloud drive desktop client

6. Windows 7 compatibility:

• ⚠️ Since Microsoft terminated Windows 7 support on January 14, 2020, some Windows 7 systems may not be able to use mount app
• Recommendation: Upgrade system to Windows 10 or Windows 11

---

Error Handling

Common Error Scenarios

| Error Type | Solution | |---------|---------|| | Download failed | Check network connection, retry or use mirror source | | Verification failed | Re-download, confirm file integrity | | Installation failed | Check permissions, confirm dependencies are met | | Version conflict | Prompt user to choose version or uninstall old version | | Startup failed | Check if port is occupied, check for process conflicts | | Mount failed | Check if service is running, check if driver is installed, view log files |

Log File Locations

Windows:

%USERPROFILE%\.pdsdrive\log\mountapp-task.log

macOS:

~/.pdsdrive/log/mountapp.out.log
~/.pdsdrive/log/mountapp.err.log

Linux:

journalctl -u mountapp -n 50

---

Best Practices

1. ✅ Always complete preparation before installation 2. ✅ Configure PDS-specific config (domain_id, user_id, authentication-type) 3. ✅ Check if already installed and version before installation 4. ✅ Verify driver/service is running 5. ✅ Windows uses scheduled tasks for boot startup 6. ✅ macOS uses launchd (plist) for stable startup 7. ✅ Linux ensure fuse2 dependency is installed 8. ✅ Set timeout when handling "Starting" mount status 9. ✅ Query actual mount path (do not assume default path) 10. ✅ Stop service before cleanup/uninstall

---

Task Progress Tracking

Use the following checklist to track mount app installation progress:

Mount app download, install, and startup progress:
- [ ] Step 1: Check if mount app is installed and current version
- [ ] Step 2: Get mount app plugin latest version and download URL
- [ ] Step 3: Download installation package (if update or first install needed)
- [ ] Step 4: Execute installation (extract/driver install/dependency install)
- [ ] Step 5: Verify installation results
- [ ] Step 6: Start mount app (check process/register boot startup)
- [ ] Step 7: Check and enable mount app feature (enable-mountapp)
- [ ] Step 8: Complete mounting (query status and execute mount command)

---

Reference Resources

PDS CLI Plugin Extended Commands for Mount App (mountapp) Feature:

| CLI Command | Description | Usage Scenario | |-------------|----------------|-------|| | aliyun pds mountapp --action get-latest-version | Get mount app latest version and download URL | Used in Step 2 for checking updates | | aliyun pds mountapp --action get-user-id | Get current user ID | Used in Step 6 to get user ID required for startup | | aliyun pds mountapp --action enable-mountapp | Enable mount app feature for cloud drive | Used in Step 7 to enable mount app feature | | aliyun pds mountapp --action mount | Execute mount operation | Used in Step 8 to mount cloud drive | | aliyun pds mountapp --action get-status | Query mount app status | Used in Step 8 to check mount status | | aliyun pds mountapp --action get-config | Query mount app configuration | Used to view current mount settings and mount point | | aliyun pds mountapp --action update-config | Update mount app configuration | Used to modify mount settings |

Note: All aliyun pds mountapp commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace flag.

###

Official Documentation

• PDS Cloud Drive Mount App Plugin: https://help.aliyun.com/zh/pds/drive-and-photo-service-ent/user-guide/mount-drives?spm=a2c4g.750001.0.i2
• Aliyun CLI Documentation: https://help.aliyun.com/zh/cli/

PDS Document and Audio/Video Analysis

Scenario: When you have obtained the drive_id, file_id, and revision_id of the file to analyze and need to perform analysis on that file Purpose: Perform analysis on files and get structured analysis results ---

Core Workflow

Flow 1: Submit Analysis Task and Poll for Results

Use Python script to automatically submit analysis task and poll until processing is complete.

# Document analysis polling
python scripts/pds_poll_processor.py \
  --drive-id "1" \
  --file-id "66e7e860a2360204b9414d5c866dd3a20af1974e" \
  --revision-id "123" \
  --x-pds-process "doc/analysis" \
  -o doc_result.json

# Audio/Video analysis polling
python scripts/pds_poll_processor.py \
  --drive-id "1" \
  --file-id "66e7e860a2360204b9414d5c866dd3a20af1974e" \
  --revision-id "123" \
  --x-pds-process "video/analysis" \
  -o video_result.json

Parameter Description:

• --drive-id: The space drive_id where the analysis file is located
• --file-id: The file_id of the file to analyze
• --revision-id: The revision_id of the file to analyze
• --x-pds-process: Processing type, doc/analysis (document) or video/analysis (audio/video). Since analysis is a synchronous API, x-pds-process must be used, not x-pds-async-process
• -o: Save raw JSON result to file (contains signed URLs)

Document Analysis Result Structure

{
  "summary": ["https://bucket/summary.json?sign=xxx"],
  "chapter_summaries": ["https://bucket/chapter_summaries.json?sign=xxx"],
  "keywords": ["https://bucket/keywords.json?sign=xxx"],
  "guiding_questions": ["https://bucket/guiding_questions.json?sign=xxx"],
  "method_description": ["https://bucket/method_description.json?sign=xxx"],
  "experiment_description": ["https://bucket/experiment_description.json?sign=xxx"],
  "conclusion_description": ["https://bucket/conclusion_description.json?sign=xxx"],
  "images": {
    "imgs/page_0_img_image_box_770_540_1367_860.png": {
      "Url": "https://bucket/imgs/page_0_img.png?sign=xxx",
      "Thumbnail": "https://bucket/imgs/page_0_img_thumbnail.png?sign=xxx"
    }
  }
}

Audio/Video Analysis Result Structure

{
  "markdown": "https://bucket/markdown.md?sign=xxx",
  "summary": ["https://bucket/summary.json?sign=xxx"],
  "chapter_summaries": ["https://bucket/chapter_summary.json?sign=xxx"],
  "keywords": ["https://bucket/keywords.json?sign=xxx"],
  "questions": ["https://bucket/questions.json?sign=xxx"],
  "transcript": ["https://bucket/transcript.json?sign=xxx"],
  "transcript_summaries": ["https://bucket/transcript_summary.json?sign=xxx"],
  "transcript_chapter_summaries": ["https://bucket/transcript_chapter_summary.json?sign=xxx"],
  "ppt_details": ["https://bucket/ppt_details.json?sign=xxx"],
  "images": {
    "ppts/video_snapshots_0.jpg": {
      "Url": "https://bucket/ppts/video_snapshots_0.jpg?sign=xxx",
      "Thumbnail": "https://bucket/ppts/video_snapshots_0_thumbnail.jpg?sign=xxx"
    }
  }
}

Flow 2: Use Formatter to Get Formatted Results

Analysis results contain multiple signed URLs pointing to different types of analysis files. Use formatting scripts to parse these files and generate readable output.

# Format document results
python scripts/doc_analysis_formatter.py doc_result.json -o formatted_output.txt

# Format audio/video results
python scripts/video_analysis_formatter.py video_result.json -o formatted_output.txt

Parameter Description:

• input_file: JSON result file path from analysis API (output from Flow 1)
• -o: Formatted output file path (optional, outputs to console if not specified)

Formatted Output Example

The formatting script automatically downloads all files pointed to by signed URLs and generates readable output according to preset templates:

````

================================================== 📄 【Full Summary】 ==================================================

{Summary text content}

🖼️ Image: {ImagePath} (Page {PageNumber})

================================================== 🏷️ 【Keywords】 ================================================== #{Keyword 1} | #{Keyword 2} | #{Keyword 3} | ...

================================================== 📚 【Chapter Summaries】 ==================================================

▶️ {Chapter Title} ---------------------------------------- {Chapter Content}

🖼️ Image: {ImagePath}

▶️ {Next Chapter Title} ---------------------------------------- ...

================================================== ❓ 【Guiding Questions】 ==================================================

Q1: {Question 1} A1: {Answer 1}

Q2: {Question 2} A2: {Answer 2} ````

Audio/video will also include dialogue transcripts and PPT extraction information.

---

Flow 3: Extract PPT from Video

If the analyzed video contains PPT, you can extract PPT from the results and generate a PPTX file.

Prerequisites

1. Video contains PPT content 2. Analysis results contain ppt_details field 3. Install Python PPT processing library

pip install python-pptx requests

Usage

Extract PPT from video analysis results and generate PPTX file:

python scripts/ppt_extraction.py video_result.json -o extracted_ppt.pptx

Parameter Description:

• input_file: JSON result file path from video analysis API
• -o: Output PPTX file path (default: extracted_ppt.pptx)
• --keep-aspect-ratio: Maintain image aspect ratio (default fills entire slide)
• --validate: Validate PPTX file after generation

Checklist

• [ ] PPTX file can be opened with PowerPoint/WPS/LibreOffice
• [ ] Slide count matches page count in ppt_details
• [ ] Each page image is clear, no stretching or distortion
• [ ] Page order matches appearance order in video
• [ ] (Optional) Notes contain timestamp information

Auto Validation

python scripts/ppt_extraction.py video_result.json --validate

Common Issues

1. Feature Not Enabled

{
  "code": "OperationNotSupport",
  "message": "This operation is not supported."
}

Solution: Contact PDS technical support to enable analysis feature.

2. Signed URL Expired

Cause: Download took too long, signed URL has expired.

Solution: Re-request analysis results, or download all images immediately after getting results.

RAM Permission Requirements

RAM Policy

If minimum required permissions principle is needed:

metadata:
  required_permissions:
    - "pds:ListDomains" — List domains: list-domains
    - "pds:ListUser" — List users: list-user
    - "pds:GetDomain" — Get domain info: get-domain
    - "pds:ListFile" — List or search files: list-file
    - "pds:GetUser" — Get user info: get-user
    - "pds:DownloadFile" — Download file: download-file
    - "pds:AssumeUser" — Access via user identity token: user upload (upload-file) / download (get-download-url) / process file (file-process) / get user personal space list (list-my-drive) / get user team/enterprise space list (list-my-group-drive) / user mount (mountapp)

API and Permission Reference Table (authentication_type: token, non-RAM authentication)

AssumeUser operation uses user identity access. In token scenario, except for domain management APIs and list user API, all other APIs operate after obtaining user token via AssumeUser, so the Required Permission for these operations is AssumeRole.

| API Action | Required Permission | Resource | |---------------------|---------------------|------------------------------------|| | list-domains | pds:ListDomains | "acs:pds:::domain/", | | get-domain | `pds:GetDomain` | "acs:pds:::domain/<domain_id>" | | list-user | `pds:ListUser` | "acs:pds:::domain/<domain_id>/" | | search-file | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | get-user | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | get-download-url | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | process | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | list-my-group-drive | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | list-my-drives | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" | | upload-file | pds:AssumeUser | "acs:pds:::domain/<domain_id>/" | | mountapp | `pds:AssumeUser` | "acs:pds:::domain/<domain_id>/" |

API and Permission Reference Table (authentication_type: ak, RAM authentication)

Using ak authentication method without user identity, only the following APIs are supported:

| API Action | Required Permission | Resource | |---------------------|---------------------|------------------------------------|| | list-domains | pds:ListDomains | "acs:pds:::domain/", | | get-domain | `pds:GetDomain` | "acs:pds:::domain/<domain_id>" | | search-file | `pds:ListFile` | "acs:pds:::domain/<domain_id>/" | | get-user | pds:GetUser | "acs:pds:::domain/<domain_id>/" | | list-user | `pds:ListUser` | "acs:pds:::domain/<domain_id>/" | | get-download-url | pds:DownloadFile | "acs:pds:::domain/<domain_id>/*" |

Notes

1. In addition to RAM permissions, PDS also requires assigning corresponding Drive space access permissions to users in the PDS Console 2. When calling with AK/SK method, ensure the RAM user has the above permissions 3. When calling with Bearer Token (OAuth) method, permissions are determined by the user role within PDS

PDS File Search

Scenario: When you have obtained the drive_id to search in and need to search for files under that drive Purpose: Search for corresponding files and get file attributes such as file_id

Core Workflow

Step 1: Semantic Query Analysis

Run the script python scripts/get_semantic_query_prompt.py, get the prompt from standard output (stdout), then use this prompt as the system prompt and the user's natural language query as user input, spawn a sub-agent to think and output JSON result, and report back to the main agent.

Step 2: Scalar Query Analysis

Run the script python scripts/get_scalar_query_prompt.py, get the prompt from standard output (stdout), then use this prompt as the system prompt and the user's natural language query as user input, spawn a sub-agent to think and output JSON result, and report back to the main agent.

Important: You need to prepend current time information UserQueryDatetime: {current time in ISO format} to the user input, because the scalar query prompt contains time-related examples that need to reference the current time.

Step 3: Build Query String

Pass the JSON outputs from Step 1 and Step 2 to scripts/build_query.py:

python scripts/build_query.py \
  --scalar-json '{JSON output from Step 2}' \
  --semantic-json '{JSON output from Step 1}'

The script will: 1. Recursively parse the Query object from scalar query into a query string 2. Convert semantic query to semantic_text = "..." format 3. Merge the modality from semantic query and category conditions from scalar query 4. Connect all parts with correct logical operators

Important: If the script execution fails, it is strictly forbidden to construct query and order_by on your own understanding for the next step, as this will very easily produce syntax errors. You should go back to step one and restart the query process from the beginning.

If the output has_query is false, do not execute the search, and kindly inform the user of the message content.

If has_query is true, use the output query and order_by for the next step.

Step 4: Execute Search

Use the query and order_by output from build_query.py to call the aliyun CLI tool:

aliyun pds search-file \
  --drive-id "drive_id" \
  --query "{query from build_query output}" \
  --order-by "{order_by from build_query output}" \
  --limit 50 \
  --recursive true \
  --return-total-count true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Pagination: If the response contains next_marker, you can pass it via --marker parameter in subsequent requests to get the next page. Add --return-total-count to get the total count of matches.

Step 5: Display Search Results

Parse the JSON output returned by the CLI tool and format the search results for display. The response structure contains an items array and optional next_marker, total_count fields. If there is a next_marker, it means there are more results available for pagination.

Output error messages to stderr on failure.

Best Practices

1. Prefer semantic search: When users describe file content or scenarios, semantic search is more accurate than keyword matching

2. Combine conditions appropriately: Semantic search can be combined with scalar conditions, e.g., "beach photos from this year" can use both time range and semantic description

3. Note pagination limits: limit maximum is 100, large result sets require pagination

4. Time format specification: Time conditions use UTC format YYYY-MM-DDTHH:mm:ss

5. Language consistency in semantic search: Semantic query text should maintain the same language as user input, do not translate

File Sharing (Share Link)

Overview

The file sharing feature allows users to create share links for files/folders in personal drives or team drives, supporting cross-organization sharing with external users. It supports access passwords, expiration periods, and permission controls (preview/download/upload/edit).

Prerequisites

1. PDS configuration is complete (domain_id, user_id, authentication-type). See references/config.md. 2. A super administrator or drive administrator has enabled the sharing feature: Admin Console > Security Policy > Share Settings Management > Enable "Share Settings".

Important Notes:

- A maximum of 500 share creations and 500 share accesses are supported per day.

- If a share link does not have "Only accessible by enterprise users" enabled, APK and IPA files are prohibited from downloading (to lift this restriction, an administrator must complete custom domain configuration).

- After the administrator enables share settings, if the share button does not appear in the user interface, refresh the webpage or restart the client.

---

Workflow

Before Creating a Share: Resolve the Target File

Creating a share requires first confirming the target drive's drive_id. Sharing regular files/folders also requires obtaining the file_id of the object to share; when sharing an entire drive, use --share-all-files true and do not resolve or pass --file-id-list.

• If the user has already provided drive_id and file_id, proceed directly to creating the share.
• If the user explicitly requests to share an entire drive, first obtain the drive_id, then create the share using --share-all-files true without passing --file-id-list.
• If the user provides a drive name, file name, or cloud path, resolve in the following order:

1. Read references/drive.md to identify the target drive and obtain the drive_id. 2. Read references/search-file.md to search for the target file/folder by name or path and obtain the file_id. 3. If multiple candidates are found, present the candidates' paths, types, and update times to the user and ask for confirmation. 4. If the target file/folder is not found, stop creating the share and inform the user that the target object cannot be located.

Do not guess file_id from file names, and do not create a share without confirming a unique target object.

Creating a Share

After confirming the drive_id, choose --file-id-list or --share-all-files true based on the target type, then create the share link:

aliyun pds create-share-link \
  --drive-id <drive_id> \
  --file-id-list <file_id_1> <file_id_2> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Expiration Time Rules:

• Only pass --expiration when the user explicitly requests the share to expire at a certain time.
• If the user explicitly states "expire after N days" (e.g., "expire after 7 days"), add the corresponding number of days to the current system time and convert to RFC 3339 format, e.g., 2026-05-28T15:04:05.000+08:00.
• If the user explicitly provides a specific date or time, convert it to RFC 3339 format and use it as --expiration.
• If the user does not explicitly specify an expiration time, do not pass --expiration, meaning the share link never expires.

Parameter Reference:

Response Example:

{
  "share_id": "<share_id>",
  "share_url": "",
  "share_pwd": "<share_pwd>",
  "share_name": "<share_name>",
  "expiration": "<RFC3339_expiration>",
  "created_at": "<RFC3339_created_at>"
}

Post-processing Before Returning to User:

• After creating the share, first check the share_url returned by create-share-link.
• If share_url is non-empty, return that URL directly to the user by default.
• If share_url is empty, first obtain the share_id, share_pwd, and domain_id, then query whether the current domain has a custom domain configured:

  aliyun pds get-domain \
    --domain-id <domain_id> \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

• Determine <share_host>:
• If the get-domain response contains a non-empty endpoints.app_endpoint, use that value as the custom domain; if the value includes an http:// or https:// prefix, strip the protocol prefix first.
• If the endpoints object does not exist, or endpoints does not contain an app_endpoint field, or app_endpoint is empty, it means no custom domain is configured; use the default domain <domain_id>.apps.aliyunfile.com.
• When share_url is empty, assemble and return the share URL according to the following rules:
• With a share password: https://<share_host>/disk/s/<share_id>?pwd=<share_pwd>&domainId=<domain_id>.
• If <share_pwd> is empty, do not include the pwd parameter: https://<share_host>/disk/s/<share_id>?domainId=<domain_id>.
• <domain_id> uses the user-provided or currently configured PDS domain ID; <share_id> uses the share_id returned from the create-share response; <share_pwd> uses the share password set or returned during share creation.

---

Listing Shares

List all shares created by the current user:

aliyun pds list-share-link \
  --limit 20 \
  --order-by created_at \
  --order-direction DESC \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Reference:

Pagination Handling:

If the response contains a non-empty next_marker, there is more data on the next page. Continue executing the same list-share-link command with the returned next_marker as the --marker parameter for the next request, until next_marker is empty. When counting, filtering, or batch-processing shares, all pages must be traversed first.

---

Searching Shares

Search share links by conditions (supports fuzzy name search, filtering by status/time):

aliyun pds search-share-link \
  --query "share_name_for_fuzzy = '<share_name_keyword>'" \
  --limit 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Reference:

Pagination Handling:

If the response contains a non-empty next_marker, there is more data on the next page. Continue executing the same search-share-link command with the returned next_marker as the --marker parameter for the next request, until next_marker is empty. When counting, filtering, or batch-processing shares, all pages must be traversed first.

---

Viewing Share Details

Query detailed information about a share link by share_id:

aliyun pds get-share-link \
  --share-id <share_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Modifying Share Settings

Modify permissions, password, expiration, etc. for an existing share. Only pass fields that the user explicitly requests to modify; do not pass fields that were not requested for modification:

aliyun pds update-share-link \
  --share-id <share_id> \
  --<requested-field> <value> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Parameter Reference:

---

Cancelling a Share

Cancel (delete) a share link:

aliyun pds cancel-share-link \
  --share-id <share_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Once cancelled, the share link becomes immediately invalid and recipients can no longer access it.

---

Anonymous Share Access (Optional)

Anonymously Get Share Information

View basic information about a share without logging in:

aliyun pds get-share-link-by-anonymous \
  --share-id <share_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Get Share Token

Obtain an access token using the share ID and extraction code:

aliyun pds get-share-link-token \
  --share-id <share_id> \
  --share-pwd <share_pwd> \
  --expire-sec 7200 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Common Scenarios

Create a Password-Free, Never-Expiring Share

aliyun pds create-share-link \
  --drive-id <drive_id> \
  --file-id-list <file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Create a Password-Protected, 7-Day, Preview-Only Share

aliyun pds create-share-link \
  --drive-id <drive_id> \
  --file-id-list <file_id> \
  --share-pwd "<share_pwd>" \
  --expiration "<current_time_plus_7_days_rfc3339>" \
  --disable-download true \
  --disable-save true \
  --require-login true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Create a Share That Allows External Users to Upload Files

aliyun pds create-share-link \
  --drive-id <drive_id> \
  --file-id-list <folder_id> \
  --creatable true \
  --creatable-file-id-list <folder_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

CLI Command Quick Reference

Note: All commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Error Handling

---

Best Practices

1. Always set an access password and expiration period when sharing sensitive files. 2. Use --require-login true to restrict access to logged-in users only, improving security. 3. Use --preview-limit / --download-limit to limit operation counts and prevent abuse. 4. Periodically clean up shares with disabled status:

First search for share links with disabled status, traversing all pages following pagination rules:

   aliyun pds search-share-link \
     --query "status = 'disabled'" \
     --limit 100 \
     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

For each share_id confirmed for cleanup, execute cancel-share:

   aliyun pds cancel-share-link \
     --share-id <share_id> \
     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

5. Confirm the file ID is correct before creating a share (use references/search-file.md to search for files and obtain the file_id).

PDS File Upload Guide

Scenario: When you have obtained the target drive_id and directory file_id and need to upload files to PDS drive Purpose: Upload local files to PDS drive (supports enterprise space, team space, personal space)

---

File Upload Command

Use the aliyun pds upload-file command to directly upload local files to PDS. This command automatically completes the three steps: create file, upload content, and complete upload.

aliyun pds upload-file \
  --drive-id <drive_id> \
  --local-path <local_file_path> \
  --parent-file-id <parent_file_id> \
  --name <cloud_file_name> \
  --check-name-mode <auto_rename|ignore|refuse> \
  --enable-rapid-upload <true|false> \
  --part-size <part_size> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Parameter Description

---

Common Examples

Basic Upload

Upload to root directory using local file name:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Specify Directory and File Name

Upload to specified directory with custom cloud file name:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --parent-file-id "root" \
  --name "my-photo.jpg" \
  --check-name-mode "auto_rename" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Enable Rapid Upload

Calculate file SHA-1 for rapid upload attempt (completes instantly if identical file exists in cloud):

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --enable-rapid-upload \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Large File Multipart Upload

Custom part size (suitable for large file uploads):

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/large-file.zip" \
  --part-size 10485760 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Upload File to Specified Directory

If you want to upload a file to a specified directory in a PDS drive, you need to convert the cloud directory name to the cloud directory file_id, and use this file_id as the value of the --parent-file-id parameter.

For example, to upload a file to the /Photos/2026/04 directory in a personal space, you need to traverse each level of the path to find the corresponding directory's file_id. If a directory does not exist in the cloud, you need to create it first.

Step 1: Find or Create Photos Directory

List all directories under the root directory to find the Photos directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id root \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

• If Photos directory exists: Note down its file_id
• If Photos directory does not exist: Create it first and get the file_id from the response:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id root \
  --name Photos \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Step 2: Find or Create 2026 Directory

List all directories under the Photos directory to find the 2026 directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id <Photos_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

• If 2026 directory exists: Note down its file_id
• If 2026 directory does not exist: Create it first:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id <Photos_directory_file_id> \
  --name 2026 \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Step 3: Find or Create 04 Directory

List all directories under the 2026 directory to find the 04 directory:

aliyun pds list-file \
  --drive-id <drive_id> \
  --type folder \
  --parent-file-id <2026_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

• If 04 directory exists: Note down its file_id
• If 04 directory does not exist: Create it first:

aliyun pds create-file \
  --drive-id <drive_id> \
  --parent-file-id <2026_directory_file_id> \
  --name 04 \
  --check-name-mode refuse \
  --type folder \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Step 4: Upload File

After obtaining the file_id of the 04 directory, use it as the --parent-file-id parameter value to upload the file:

aliyun pds upload-file \
  --drive-id <drive_id> \
  --local-path "/path/to/file.jpg" \
  --parent-file-id <04_directory_file_id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Note: When executing the aliyun pds list-file command, if there are no valid items returned and the next_marker is not empty, it means that the query is not complete. Use the next_marker as the --marker parameter for the next list query until next_marker is empty.

Upload File to Specified Parent File ID

When uploading a file to a specified parent file ID, first verify whether the parent directory with the specified ID exists using the Get File command:

aliyun pds get-file \
  --drive-id "100" \
  --file-id "1000" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Verification Logic:

• If the specified Parent File ID does not exist: The system will prompt that the parent directory does not exist. Ask the user to confirm again.
• If the directory exists: Take the response file's parent_file_id as the new Parent File ID and continue to query through Get File until the parent_file_id is root, indicating that the top-level directory has been found.

After finding all levels, concatenate them to get the full path of the file in this PDS drive space after upload.

Note: Before uploading, you must query the full path relative to the root directory. Only after that can you proceed with the subsequent upload operations.

Upload Command:

After completing the path query, use the following command to upload the file:

aliyun pds upload-file \
  --drive-id "100" \
  --local-path "/path/to/file.jpg" \
  --parent-file-id "1000" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Post-Upload:

After the upload is completed, inform the user that the file upload was successful and display the full path relative to the root directory. For example:

The file has been uploaded to the personal space (or team space) with the full path: /Photos/2026/04/01/file.jpg

---

Output Description

After successful command execution, returns a JSON object with complete file information, main fields include:

• file_id: Unique file ID
• name: Cloud file name
• size: File size
• created_at: Creation time
• updated_at: Update time
• parent_file_id: Parent directory ID

---

Notes

1. Same name file handling: Recommend using --check-name-mode auto_rename to avoid overwriting existing files 2. Rapid upload feature: Enable --enable-rapid-upload to complete upload instantly when identical file exists in cloud 3. Multipart upload: Large files are automatically uploaded in parts, adjust part size via --part-size 4. Network stability: Ensure stable network when uploading large files to avoid interruptions

Alibaba Cloud PDS Visual Similar Search Guide

Scenario: When you have prepared a local image file or have obtained the drive_id, file_id, revision_id of an image file, and want to perform image search, similar image search, visual similarity search, or multimodal image retrieval Purpose: Search for similar images in the cloud drive based on user-provided image

Step 1 [Optional]: Upload Local Image File to Drive System Space

Prerequisites

If the user has already provided the image file's drive_id, file_id, revision_id, skip this step

Step 1.1 Get System Space

Execute the following command to get the domain's system space configuration:

aliyun pds get-domain --domain-id <domain-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Response example:

{
  "domain_id": "bj1093",
  "system_drive_config": {
    "enable": true,
    "drive_id": 1,
    "resource_parent_file_id_map": {
      "value-add": "68d2348822056f5eea514146b4ad7183cdb94d2f"
    }
  }
}

Extract the system space ID and upload parent file ID from the response. In the above example, system space ID is 1, and upload parent file ID is 68d2348822056f5eea514146b4ad7183cdb94d2f (the value-add item).

If enable in system_drive_config is false, or drive_id is empty, or resource_parent_file_id_map does not contain value-add, there is an issue with system space configuration. Please contact PDS technical support for assistance.

Step 1.2 Upload Local File to Drive System Space

Upload the local file to the drive's system space, where drive_id is set to the system space ID obtained in the previous step, parent_file_id is set to the upload parent file ID obtained in the previous step, and record the file's file_id and revision_id.

Step 2: Construct x-pds-process

If the user searches using a local file, the source file information comes from the file uploaded to the drive in Step 1.2; otherwise, the source file information comes from the drive file information provided by the user.

Must call the existing Python script scripts/render_visual_similar_search_process.py to generate x-pds-process. The script will output x-pds-process to the terminal.

Parameter Description

• source_domain_id: Domain where the source image is located
• source_file_id: File ID of the source image
• source_drive_id: Drive ID of the source image
• source_revision_id: Revision ID of the source image
• query: Search semantic text, not required if none
• limit: Maximum number of similar images to return, not required if none

python scripts/render_visual_similar_search_process.py \
  --source_domain_id <SOURCE_DOMAIN_ID> \
  --source_file_id <SOURCE_FILE_ID> \
  --source_drive_id <SOURCE_DRIVE_ID> \
  --source_revision_id <SOURCE_REVISION_ID> \
  --query <QUERY> \
  --limit <LIMIT>

---

Step 3: Perform Image Search

Parameter Description

• search_drive_id: Drive ID to search in
• search_folder_id: File ID of the folder to search in

Search Entire Drive

aliyun pds process \
  --resource-type drive \
  --drive-id ${SEARCH_DRIVE_ID} \
  --x-pds-process ${X_PDS_PROCESS} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

Search Specific Folder

aliyun pds process \
  --resource-type file \
  --drive-id ${SEARCH_DRIVE_ID} \
  --file-id ${SEARCH_FOLDER_ID} \
  --x-pds-process ${X_PDS_PROCESS} \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pds-intelligent-workspace

---

Response

Success Response:

{
  "similar_files": [
    {
      "similarity": 0.95,
      "domain_id": "bj1093",
      "drive_id": "2",
      "file_id": "5d79206586bb5dd69fb34c349282718146c55da7",
      "name": "similar_image1.jpg",
      "type": "file",
      "category": "image",
      "size": 102400,
      "created_at": "2019-08-20T06:51:27.292Z",
      "thumbnail": "https://..."
    },
    {
      "similarity": 0.84,
      "domain_id": "bj1093",
      "drive_id": "2",
      "file_id": "69c0e5c9432208927ca14d1f8af5e897486c6337",
      "name": "similar_image2.jpg",
      "type": "file",
      "category": "image",
      "size": 102400,
      "created_at": "2023-08-20T06:51:27.292Z",
      "thumbnail": "https://..."
    }
  ]
}

Field Description:

• similarity: Similarity score, range [0, 1], closer to 1 means more similar
• drive_id: Drive where the result file is located (the search scope drive)
• file_id: Similar file ID
• name: File name
• thumbnail: Thumbnail URL

---

Error Handling

| HTTP Status | Error Code | Description | Solution | |------------|--------|------|---------|| | 400 | InvalidParameter.xxx | Invalid parameter | Check parameter format and encoding | | 400 | OperationNotSupport | Feature not enabled | Contact PDS technical support to enable feature | | 403 | ForbiddenNoPermission.xxx | No permission | Check AccessToken permissions |

Common Errors:

1. Feature Not Enabled

{
  "code": "OperationNotSupport",
  "message": "This operation is not supported."
}

Solution: Contact PDS technical support to enable image search feature.

2. Insufficient Permissions

{
  "code": "ForbiddenNoPermission.file",
  "message": "No Permission to access resource file"
}

Solution:

• Ensure current user has FILE.LIST permission on the search space or folder
• Ensure current user has FILE.PREVIEW permission on the source file

---

Best Practices

1. Set Appropriate limit Parameter

• Quick preview: l_10 or l_20
• Regular search: l_50
• Comprehensive search: l_100 (maximum)

2. Prefer Image-Only Retrieval

Unless the user explicitly requests image-text hybrid retrieval, prefer using image-only retrieval for better accuracy

---

FAQ

Q: Why are fewer results returned than expected? limit only indicates the maximum number of results, it does not guarantee that limit images will be returned. A: Possible reasons: 1. Actual number of similar images is less than limit 2. Some files were filtered due to insufficient permissions 3. Total number of images in search scope is small

Q: Can I search for videos or documents? A: Not supported, only similar image search is supported.