1. Aliyun CLI (>= 3.3.1)

Pre-check: Aliyun CLI >= 3.3.1 required This skill uses Aliyun CLI for all OSS operations except opening MetaQuery. If Aliyun CLI is already installed, ossutil does not need to be installed separately. Run the following command to verify the version:

aliyun version

If not installed or the version is below 3.3.1, refer to references/cli-installation-guide.md for installation instructions, then run:

aliyun configure set --auto-plugin-install true

This configuration enables automatic plugin installation.

1. Update the aliyun ossutil plugin

Troubleshooting:

--user-agent

unknown flag error If you encounter

Error: unknown flag: --user-agent

when running a command, the ossutil plugin version is too old. Run the following command to update to the latest version:

bash

aliyun ossutil update

After the update, re-run the original command.

undefined

Note: If the user's Bucket is in a region not listed above, vector-mode MetaQuery and content awareness cannot be enabled, and an EC Code

0037-00000001

error will be returned. Guide the user to create a new Bucket in a supported region.

• Supported: Images, videos, audio, documents
• Multipart uploads: Only objects that have been assembled via

  CompleteMultipartUpload

  are shown

This bandwidth and QPS is provided exclusively for vector search and does not consume the Bucket's QoS quota.

• Incremental updates: When QPS < 1250, latency is typically minutes to hours
• Search response: Sub-second, default timeout 30 seconds

• Delete Bucket:

  aliyun ossutil rm oss://<bucket-name> -b --user-agent AlibabaCloud-Agent-Skills

  -- Deletes the entire Bucket, irreversible
• Delete Object:

  aliyun ossutil rm oss://<bucket-name>/<object-key> --user-agent AlibabaCloud-Agent-Skills

  -- Deletes a specific file
• Batch Delete Objects:

  aliyun ossutil rm oss://<bucket-name>/ --recursive --user-agent AlibabaCloud-Agent-Skills

  -- Recursively deletes all files in the Bucket
• Close MetaQuery:

  aliyun ossutil api close-meta-query --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills

  -- Closes the metadata index; all indexed data will be cleared
• Open MetaQuery:

  python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint>

  -- Opens the metadata index; existing data will start being indexed. If the bucket has more than 1000 objects, confirm with the user first.
• Create Bucket:

  aliyun ossutil api put-bucket --bucket <bucket> --region <region-id> --user-agent AlibabaCloud-Agent-Skills

  -- Creates a Bucket

1. The specific operation to be performed
2. The scope of impact (which files/resources will be deleted or closed)
3. Whether the operation is reversible (most delete operations are irreversible)

BucketAlreadyExists

1. Immediately stop all subsequent operations
2. Inform the user: "The Bucket name is already taken"
3. Ask the user to choose:
   • Option 1: Use the existing bucket (requires explicit user confirmation)
   • Option 2: Choose a new bucket name (user provides the new name)
4. Wait for the user's response before continuing PROHIBITED:

• Automatically modifying the bucket name (e.g., appending

  -2

  ,

  -new

  , etc.)
• Using an existing bucket without asking the user

• Create Bucket
• Query Bucket info
• Query Bucket statistics
• Upload files
• Query MetaQuery status
• Execute semantic search
• Close MetaQuery
• Delete Object / Bucket Goal: Use the

  aliyun

  command uniformly, minimizing dependency on ossutil.

WARNING: You MUST use

python scripts/open_metaquery.py

to open MetaQuery. Using

aliyun ossutil api open-meta-query

is STRICTLY PROHIBITED (it cannot configure WorkflowParameters, which prevents enabling AI Content Awareness features ImageInsightEnable and VideoInsightEnable, severely degrading semantic search quality).

pip install oss2==2.19.1 alibabacloud-credentials==1.0.8

alibabacloud-credentials

~/.aliyun/config.json

aliyun configure

AccessDenied

1. Prepare the Bucket: a. If the user requests creating a new Bucket:
   • Run

     aliyun ossutil api put-bucket --bucket examplebucket --user-agent AlibabaCloud-Agent-Skills

     with the user-specified bucket name
   • If creation fails with a

     BucketAlreadyExists

     error:
     • Immediately stop the operation
     • Inform the user: "The Bucket name

       <bucket-name>

       is already taken (it may have been created by you or another user)"
     • You MUST ask the user: "Would you like to: 1) Use this existing bucket? or 2) Choose a new bucket name?"
     • Wait for the user's explicit response before continuing. Do not modify the bucket name or use the existing bucket without permission. b. If the user provides an existing bucket:
   • First verify the bucket exists using

     aliyun ossutil api get-bucket-info --bucket <bucket-name> --user-agent AlibabaCloud-Agent-Skills

   • If it does not exist, ask the user whether to create it
2. Verify Bucket object count: After the user provides a bucket, check the object count. If it exceeds 1000, warn the user that enabling MetaQuery will incur costs. Use the following command to get the bucket's object count:
   bash

   aliyun ossutil api get-bucket-stat --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

   The

   ObjectCount

   field in the response indicates the number of objects.
   • If the object count exceeds 1000, warn the user that enabling MetaQuery will incur costs and confirm whether to proceed.
   • If the object count is 0, ask the user which files to upload. Upload command:
     bash

     aliyun ossutil api put-object --bucket <your-bucket-name> --key <object-key> --body file://<local-file-path> --user-agent AlibabaCloud-Agent-Skills

3. Run the Python script: After the above steps are complete, attempt to open MetaQuery using the Python script. Python script example:

python scripts/open_metaquery.py --region <your-region> --bucket <your-bucket-name> --endpoint <your-endpoint>

get-meta-query-status

aliyun ossutil api get-meta-query-status --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

• Status is

  Deleted

  : MetaQuery is being closed. The user should retry later.
• Status is

  Running

  or

  Ready

  : MetaQuery has already been created. Check the following two conditions:
  • Whether

    MetaQueryMode

    is

    semantic

  • Whether

    WorkflowParameters

    contains the following configuration:
    xml

    <WorkflowParameters>
      <WorkflowParameter><Name>ImageInsightEnable</Name><Value>True</Value></WorkflowParameter>
      <WorkflowParameter><Name>VideoInsightEnable</Name><Value>True</Value></WorkflowParameter>
    </WorkflowParameters>

  If

  MetaQueryMode=semantic

  and both

  VideoInsightEnable

  and

  ImageInsightEnable

  are

  True

  , the user has successfully enabled MetaQuery in vector mode with content awareness (which greatly improves semantic search quality). No further action is needed. If these conditions are not met, recommend the user switch to a different bucket and start over.

1. Verify MetaQuery is enabled:
   bash

   aliyun ossutil api get-meta-query-status --bucket <your-bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

2. If MetaQuery is not enabled: Complete the enablement process first. Refer to Task 2 to enable it using the Python script.
3. Check index scan status: The

   Phase

   field from

   get-meta-query-status

   indicates the current scan phase:

   • FullScanning

     : Full scan in progress. Search is not available yet. Wait for the full scan to complete.

   • IncrementalScanning

     : Incremental scan in progress. The index has been largely built and search can be performed normally.
4. Verify MetaQuery state is

   Running

   : MetaQuery is only available when

   State

   is

   Running

   . If the state is

   Ready

   or any non-

   Running

   state, you may need to wait or re-enable it.

meta-query.xml

<MetaQuery>
<MediaTypes><MediaType>video</MediaType></MediaTypes>
<Query>person</Query>
</MetaQuery>

<MetaQuery>
<Query>{"SubQueries":[{"Field":"Size","Value":"30","Operation":"gt"},{"Field":"FileModifiedTime","Value":"2025-06-03T09:20:47.999Z","Operation":"gt"}],"Operation":"and"}</Query>
</MetaQuery>

meta-query.xml

aliyun ossutil api do-meta-query --bucket <bucket-name> --meta-query file://meta-query.xml --meta-query-mode semantic --user-agent AlibabaCloud-Agent-Skills

--meta-query-mode basic

For detailed command parameters, see the DoMetaQuery section in references/related-apis.md.

x-oss-process

aliyun ossutil presign oss://<bucket-name>/<video-object-key> --query-param x-oss-process=video/snapshot,t_0,f_png,w_0,h_0 --user-agent AlibabaCloud-Agent-Skills

t_0

f_png

w_0,h_0

aliyun ossutil presign oss://<bucket-name>/<image-object-key> --user-agent AlibabaCloud-Agent-Skills

Note: The

aliyun ossutil presign

command generates a signed temporary access URL that can be opened directly in a browser for preview during its validity period. For image files, you can also add image processing parameters via

x-oss-process

(e.g., resize, crop):

bash

aliyun ossutil presign oss://<bucket-name>/<image-object-key> --query-param x-oss-process=image/resize,w_200 --user-agent AlibabaCloud-Agent-Skills

This generates a thumbnail preview to reduce loading time.

VideoInsightEnable

ImageInsightEnable

True

WorkflowParameters

• The file's metadata index has not been fully built yet. Wait for the index scan to complete (check the

  Phase

  field via

  aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

  ).
• Without content awareness, search is based only on basic file metadata (filename, size, type, etc.) and cannot perform semantic understanding of file contents, resulting in limited search effectiveness.
• Recommendation: Suggest the user enable content awareness to improve search quality. Since existing MetaQuery configurations cannot be directly modified, recommend the user switch to a new bucket and re-enable MetaQuery with content awareness following the Task 2 process.

• File is still being processed: Content awareness requires deep analysis of files (e.g., image recognition, video understanding), which takes longer, especially for video files. Check the

  Phase

  field via

  aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

  :

  • FullScanning

    : The overall index is still in full scan mode. Wait patiently.

  • IncrementalScanning

    : Newly uploaded files are being processed incrementally. Usually wait a few minutes.
• Unsupported file format: Some file formats may not be supported by content awareness. In this case, search can only use basic metadata.
• Search keywords don't match: The user's search keywords may not semantically match the file content. Suggest the user try adjusting their search keywords to use descriptions closer to the actual file content.

aliyun ossutil api get-meta-query-status --bucket <bucket-name> --output-format json --user-agent AlibabaCloud-Agent-Skills

For detailed descriptions of returned fields (State, Phase, MetaQueryMode, etc.), see the GetMetaQueryStatus section in references/related-apis.md.