[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.
bash
aliyun configure ai-mode disable
Pre-check: Aliyun CLI >= 3.3.3 required
Run aliyun version to verify >= 3.3.3. If not installed or version too low,
run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update,
or see references/cli-installation-guide.md for installation instructions.
Then [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
Then [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.
Pre-check: Alibaba Cloud Credentials Required
Security Rules:
NEVER read, echo, or print credential material (including environment-based secrets)
NEVER ask the user to paste long-lived secrets directly in the conversation or command line
NEVER use aliyun configure set with literal credential values
ONLY use aliyun configure list to check credential status
bash
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).
Requires Python 3.7+ (same baseline as Alibaba Cloud SDK for Python).
RAM Permissions
[MUST] RAM Permission Pre-check: Before executing operations, verify current user has required permissions.
Use ram-permission-diagnose skill to check permissions, then compare against references/ram-policies.md.
If any permission is missing, abort and prompt user.
Parameter Confirmation
IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks,
passwords, domain names, resource specifications, etc.) MUST be confirmed with the
user. Do NOT assume or use default values without explicit user approval.
Parameter
Required/Optional
Description
Default Value
biz-region-id
Required
Region ID
cn-hangzhou
db-instance-id
Required
Instance ID (format: gp-xxxxx)
-
manager-account
Required
Manager account name
-
manager-account-password
Required
Manager account password
-
namespace
Optional
Namespace name
public
namespace-password
Required
Namespace password
-
collection
Required
Knowledge base name
-
embedding-model
Optional
Embedding model
text-embedding-v4
dimension
Optional
Vector dimension
1024
Note: If the knowledge base is created in a custom namespace, all subsequent operations must specify the same namespace parameter.
Documentation placeholders: CLI examples use strings like <manager-account-password> and <namespace-password>. Replace them with real values from the user; never commit or log real passwords in docs, tickets, or chat.
Timeout Configuration
Timeout Rules: All operations must complete within reasonable time limits.
Standard operations: ≤10 seconds (create/list/query)
Upload document async: No timeout limit (async job, poll every 5-10s)
Use CredentialClient() with no arguments so the SDK resolves credentials via the default chain (same sources as the CLI). Do not parse credential files or pass raw keys in skill code. Set user_agent and HTTP timeouts on Config (milliseconds).
python
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_gpdb20160503.client import Client
from alibabacloud_tea_openapi.models import Config
client = Client(Config(
credential=CredentialClient(),
region_id='cn-hangzhou',
endpoint='gpdb.aliyuncs.com',
connect_timeout=10000,
read_timeout=10000,
user_agent='AlibabaCloud-Agent-Skills/alibabacloud-analyticdb-postgresql-knowledgebase-ops',
))
Core Workflow
1. Knowledge Base Management
Create Knowledge Base
Pre-checks (run in order; not silent idempotency):
Duplicate names: If a create step is run again when the resource already exists, the API returns a clear error (e.g. conflict / already exists). Do not create duplicate resources; interpret already-exists-style errors as “this step is satisfied” only when the response clearly indicates the resource is present, then continue the workflow.
Retries / ClientToken: For network-level retries (e.g. timeout), use ClientToken when the API or aliyun gpdb exposes it for that subcommand—check aliyun gpdb <subcommand> --help. The examples below omit it when the plugin does not list it globally.
Local files use Python SDK upload_document_async_advance. Do not paste multi-line Python into the skill; use the packaged script only (default credential chain, user_agent, Config timeouts, and RuntimeOptions timeouts — see scripts/upload_document_local.py).
