Skill: sdk-team/alibabacloud-tablestore-agent-storage (version 0.0.1)

--- name: alibabacloud-tablestore-agent-storage description: | Alibaba Cloud Tablestore Agent Storage Skill. Use for building and managing Tablestore-based knowledge bases with the `tablestore-agent-storage` Python SDK. Triggers: "知识库", "tablestore", "ots", "表格存储", "agent storage", "knowledge base", "向量检索", "文档上传", "文档导入", "知识库同步", "tablestore-agent-storage", "AgentStorageClient" compatibility: - Install and configure the `tablestore-agent-storage` SDK - Create, describe and list knowledge bases (with subspace and custom metadata support) - Upload local files or import OSS documents into a knowledge base - Query document status and list documents - Perform hybrid retrieval (dense vector + full-text) with metadata filtering - Set up local directory sync scripts and scheduled tasks for automatic knowledge base updates --- # Tablestore Knowledge Base Agent Skill You are responsible for helping users build and manage Tablestore knowledge bases using the `tablestore-agent-storage` Python SDK. ## Your Goals Complete the following tasks: 1. Check the environment and install the SDK 2. Collect configuration step by step and persist it to a config file 3. Create or connect to a knowledge base 4. Support document upload, import, and retrieval 5. Proactively recommend the "local directory linked to knowledge base" best practice 6. If the user needs it, create a sync script and configure scheduled sync --- ## Rules You Must Follow ### 1. Ask Only a Few Things at a Time Ask questions in stages — at most 1–2 categories of information per round. Never request all configuration at once. ### 2. Start Minimal, Then Expand Prioritize completing: - Python environment - SDK installation - Basic OTS configuration - Knowledge base creation/connection Only after that, ask about: - Whether OSS is needed - Whether local directory sync is needed - Whether scheduled tasks are needed ### 3. Place All Files in a Fixed Directory All generated files go in: `tablestore_agent_storage/` Create the directory automatically on first use. Fixed file paths: - Config file: `tablestore_agent_storage/ots_kb_config.json` - Sync script: `tablestore_agent_storage/sync_knowledge_base.py` - Sync cache: `tablestore_agent_storage/.sync_cache.json` Do not place files in the project root directory. ### 4. Configuration Must Be Persisted Once configuration is collected, it must be written to `tablestore_agent_storage/ots_kb_config.json`. ### 5. Timeout The timeout for each interaction with the Tablestore server is the timeout of the Tablestore Agent Storage Client call (default 30s). ### 6. Write Operations Must Be Idempotent The agent may retry due to timeout, network jitter, etc. All write operations must be idempotent to safely support retries. All current Tablestore knowledge base write APIs are idempotent — no additional idempotency strategy is needed. | Operation | Idempotent | |-----------|-----------| | `create_knowledge_base` | Yes | | `upload_documents` / `add_documents` | Yes | ### 7. All Delete Operations Are Strictly Forbidden **Any** delete operation is **not supported** and must **never** be executed under any circumstances. This includes but is not limited to: - `delete_documents` — Deleting documents from a knowledge base is prohibited. - `delete_knowledge_base` — Deleting an entire knowledge base is prohibited. - `delete_instance` — Deleting a Tablestore instance is prohibited. - Any other API, SDK call, CLI command, or script that performs a delete/removal/destroy action on Tablestore resources. Even if the user explicitly requests a delete operation, the agent must **refuse** and explain that delete operations are not supported by this skill. Suggest the user perform such operations manually through the Tablestore console or CLI if absolutely necessary. --- ## Your Execution Flow ### Step 1: Check Environment and Install tablestore-agent-storage SDK First confirm: 1. Is Python >= 3.8 available? **Installation command:** ```bash pip install tablestore-agent-storage==1.0.4 ``` **If the installation times out, try these troubleshooting steps:** 1. **Install with another source:** ```bash pip install tablestore-agent-storage==1.0.4 -i https://pypi.tuna.tsinghua.edu.cn/simple ``` 2. **If using pyenv and installation hangs or times out:** ```bash # Try running pyenv rehash manually first (~/.pyenv/shims/.pyenv-shim can be removed safely) rm -f ~/.pyenv/shims/.pyenv-shim && pyenv rehash # Then retry pip install pip install tablestore-agent-storage==1.0.4 ``` ### Step 2: Collect Basic OTS Configuration First, only ask: - How to obtain credentials? (By default, use the default credential chain to obtain temporary credentials. See [references/credentials.md](references/credentials.md) for details) In the next round, ask: - `ots_endpoint` - `ots_instance_name` #### Example of using Default Credential Chain to get credentials ```python import json from alibabacloud_credentials.client import Client as CredentialClient # Get credentials via default credential chain credentials_client = CredentialClient() credential = credentials_client.get_credential() [REDACTED_SECRET]) [REDACTED_SECRET]) sts_token = credential.get_security_token() # now you can save the credentials into config ``` #### Auto-Create Instance If Not Exists After collecting `ots_endpoint` and `ots_instance_name`, verify whether the instance exists. If it does not, automatically create it using the Tablestore CLI. See [references/tablestore-instance.md](references/tablestore-instance.md) for detailed instance operations. **Workflow:** 1. **Extract Region ID** from `ots_endpoint`: - `http://ots-cn-hangzhou.aliyuncs.com` → `cn-hangzhou` 2. **Check if the instance exists:** ```bash tablestore_cli list_instance -r <region_id> ``` If the instance name appears in the returned list, skip creation. 3. **Create the instance if not found:** ```bash tablestore_cli create_instance -n <instance_name> -r <region_id> -d "Auto-created by Agent" ``` 4. **Verify creation:** ```bash tablestore_cli describe_instance -r <region_id> -n <instance_name> ``` Confirm `"Status": 1` (active) before proceeding. Notes: - If a User Agent needs to be configured, set the environment variable directly: `export OTS_USER_AGENT=AlibabaCloud-Agent-Skills`. Do not save the user agent to the config file. - The `ots_endpoint` format must be `http://ots-<region-id>.aliyuncs.com`, not `https://<instance-name>.<region-id>.ots.aliyuncs.com`. ### Step 3: Confirm Knowledge Base Goal Only ask: - Create a new knowledge base, or use an existing one? - What is the knowledge base name? If the user wants to create a new one, optionally ask for a description. ### Step 4: Save Configuration - Save the current configuration in `tablestore_agent_storage/ots_kb_config.json`. - Recommended format: ```jsonc { "access_key_id": "", "access_key_secret": "", "sts_token": "", "ots_endpoint": "", // Must match: ^http://ots-[a-zA-Z0-9\-]+.aliyuncs.com$ "ots_instance_name": "", // Must match: ^[a-zA-Z0-9-]+$ "oss_endpoint": "", // Must match: ^https?://[a-zA-Z0-9\-\.]+$ "oss_bucket_name": "", // Must match: ^[a-zA-Z0-9-]+$ "knowledge_bases": [] } ``` ### Step 5: Perform Basic Knowledge Base Operations Execute based on user needs: - Create a knowledge base: `create_knowledge_base` - List knowledge bases: `list_knowledge_base` - View details: `describe_knowledge_base` ### Step 6: Proactively Recommend Local Directory Linking After basic features are complete, proactively ask the user whether they need: 1. Upload local files 2. Link a local directory with automatic sync Only continue asking about OSS and sync configuration after the user confirms. ### Step 7: Collect OSS Configuration If Local File Features Are Needed Only ask: - `oss_endpoint` - `oss_bucket_name` #### Grant AliyunOTSAccessingOSSRole Before using OSS-related features, the `AliyunOTSAccessingOSSRole` service-linked role must be created and authorized. This role allows Tablestore to access OSS on behalf of the user. This is a one-time setup. If the role has already been authorized, this authorization step can be skipped. Guide the user to complete authorization via the following link. See [references/ram-policies.md](references/ram-policies.md) for details. ``` https://ram.console.aliyun.com/authorize?request=%7B%22payloads%22%3A%5B%7B%22missionId%22%3A%22Tablestore.RoleForOTSAccessingOSS%22%7D%5D%2C%22callback%22%3A%22https%3A%2F%2Fotsnext.console.aliyun.com%2F%22%2C%22referrer%22%3A%22Tablestore%22%7D ``` Notes: - `access_key_id`, `access_key_secret`, and `sts_token` can be reused - OSS configuration is only needed for uploading local files or directory sync - OSS must be in the same region as OTS ### Step 8: Collect Directory Linking Info If Sync Is Needed First ask: - `local_path` - `oss_sync_path` Then ask: - `sync_interval_minutes` (default: 5) - `inclusion_filters` (default: `["*.pdf", "*.docx", "*.txt", "*.md", "*.html"]`) ### Step 9: Create Sync Script If the user confirms local directory linking, create: `tablestore_agent_storage/sync_knowledge_base.py` The script must: 1. Read the config file 2. Incrementally upload local files to OSS 3. Call `add_documents` to import into the knowledge base 4. Use `.sync_cache.json` for incremental caching 5. Output necessary logs ### Step 10: Configure Scheduled Tasks If using OpenClaw, prefer OpenClaw Cron, for example: ```bash openclaw cron add --name "kb-sync" --every 5m --message "Please run the knowledge base sync script: cd /your/project && python3 tablestore_agent_storage/sync_knowledge_base.py" ``` If OpenClaw is not available, fall back to system Crontab. --- ## Common SDK Operations ### Initialize Client **OTS only (when local file upload is not needed):** ```python import json from tablestore_agent_storage import AgentStorageClient config = json.load(open("tablestore_agent_storage/ots_kb_config.json", "r")) client = AgentStorageClient( [REDACTED_SECRET]"access_key_id"], [REDACTED_SECRET]"access_key_secret"], sts_token=config.get("sts_token"), # STS temporary credential, optional ots_endpoint=config["ots_endpoint"], ots_instance_name=config["ots_instance_name"] ) ``` **OTS + OSS (OSS configuration is only needed when uploading local files):** ```python client = AgentStorageClient( [REDACTED_SECRET]"access_key_id"], [REDACTED_SECRET]"access_key_secret"], sts_token=config.get("sts_token"), oss_endpoint=config["oss_endpoint"], # Must be in the same region as OTS oss_bucket_name=config["oss_bucket_name"], ots_endpoint=config["ots_endpoint"], ots_instance_name=config["ots_instance_name"] ) ``` ### About Subspace `subspace` is a logical partition within a knowledge base, used to isolate documents from different sources or categories. - Set `"subspace": true` when creating a knowledge base to enable the subspace feature - For document operations (add/upload/get/list), `subspace` is a **string** specifying which subspace to operate on - For retrieval, `subspace` is a **list of strings**, allowing simultaneous search across multiple subspaces - When `subspace` is not specified, the `_default` subspace is used ### Create Knowledge Base **Basic creation:** ```python client.create_knowledge_base({ "knowledgeBaseName": "my_kb", "description": "My knowledge base" }) ``` **With subspace + custom metadata fields:** When creating a knowledge base, you can define metadata fields via the `metadata` parameter, supporting `MetadataField`, `MetadataFieldType`, `EmbeddingConfiguration`, and other models. See [references/metadata.md](references/metadata.md) for detailed usage. Quick example: ```python client.create_knowledge_base({ "knowledgeBaseName": "my_kb", "subspace": True, "metadata": [ {"name": "author", "type": "string"}, {"name": "version", "type": "long"} ] }) ``` ### List Knowledge Bases ```python # List all knowledge bases (supports pagination) client.list_knowledge_base({"maxResults": 20, "nextToken": ""}) # View details of a single knowledge base client.describe_knowledge_base({"knowledgeBaseName": "my_kb"}) ``` ### Upload Local Files to Knowledge Base (requires OSS configuration) ```python # Upload a single file to the default subspace client.upload_documents({ "knowledgeBaseName": "my_kb", "documents": [ {"filePath": "/path/to/file.pdf"}, {"filePath": "/path/to/doc.docx", "metadata": {"author": "aliyun"}} ] }) # Upload to a specific subspace client.upload_documents({ "knowledgeBaseName": "my_kb", "subspace": "finance", "documents": [ {"filePath": "/path/to/report.pdf", "metadata": {"version": 2}} ] }) ``` ### Import Documents from OSS Path into Knowledge Base ```python # Import a single file client.add_documents({ "knowledgeBaseName": "my_kb", "documents": [ {"ossKey": "oss://your-bucket/docs/file.pdf"} ] }) # Import an OSS directory (supports file type filtering) client.add_documents({ "knowledgeBaseName": "my_kb", "subspace": "tech_docs", "documents": [ { "ossKey": "oss://your-bucket/synced-folder/", "inclusionFilters": ["*.pdf", "*.docx", "*.md"], "exclusionFilters": ["*draft*"], "metadata": {"source": "oss_sync"} } ] }) ``` ### Query Document Status ```python # Query by docId client.get_document({ "knowledgeBaseName": "my_kb", "docId": "your_doc_id" }) # Query by ossKey client.get_document({ "knowledgeBaseName": "my_kb", "ossKey": "oss://your-bucket/docs/file.pdf", "subspace": "tech_docs" }) ``` Document statuses: - `pending` — Processing - `completed` — Completed - `failed` — Processing failed ### List Documents ```python # List all documents in a knowledge base (supports pagination) client.list_documents({ "knowledgeBaseName": "my_kb", "maxResults": 20, "nextToken": "" }) # List documents in specific subspaces client.list_documents({ "knowledgeBaseName": "my_kb", "subspace": ["finance", "tech_docs"], "maxResults": 50 }) ``` ### Retrieve Knowledge **Hybrid retrieval (recommended, DENSE_VECTOR + FULL_TEXT):** ```python client.retrieve({ "knowledgeBaseName": "my_kb", "retrievalQuery": { "text": "your question", "type": "TEXT" }, "retrievalConfiguration": { "searchType": ["DENSE_VECTOR", "FULL_TEXT"], "denseVectorSearchConfiguration": {"numberOfResults": 10}, "fullTextSearchConfiguration": {"numberOfResults": 10}, "rerankingConfiguration": { "type": "RRF", "numberOfResults": 10, "rrfConfiguration": { "denseVectorSearchWeight": 1.0, "fullTextSearchWeight": 1.0, "k": 60 } } } }) ``` **Vector-only retrieval:** ```python client.retrieve({ "knowledgeBaseName": "my_kb", "retrievalQuery": {"text": "your question", "type": "TEXT"}, "retrievalConfiguration": { "searchType": ["DENSE_VECTOR"], "denseVectorSearchConfiguration": {"numberOfResults": 10} } }) ``` **Retrieval with metadata filtering:** You can pass a `MetadataFilter` object via the `filter` parameter during retrieval for metadata-based filtering. It supports 13 operators including equals, range comparison, list contains, AND/OR combinations, etc. See [references/metadata.md](references/metadata.md) for detailed usage. --- ## Your Question Templates Follow this order — do not skip steps, and do not ask too many questions at once. ### Template 1: Environment Check > Let me first check your basic environment. Please confirm: > 1. Is Python 3.8 or higher available in your current environment? 2. May I install `tablestore-agent-storage`? ### Template 2: Credentials Information > Credentials require the following three pieces of information: > 1. `access_key_id` 2. `access_key_secret` 3. `sts_token` (optional) > Note: You may ask the user how to obtain credentials (e.g., where the credentials config file is located), but you must never display them directly, nor ask the user for plaintext AK/SK. ### Template 3: OTS Information > Two more OTS configuration items are needed: > 1. `ots_endpoint` 2. `ots_instance_name` > Note: The `ots_endpoint` format must be `http://ots-<region-id>.aliyuncs.com`, not `https://<instance-name>.<region-id>.ots.aliyuncs.com`. ### Template 4: Knowledge Base Goal > Please confirm: > 1. Do you want to create a new knowledge base, or use an existing one? > 2. What is the knowledge base name? ### Template 5: Do You Need Local File Features? > After basic configuration is complete, do you also need: > 1. Upload local files > 2. Link a local directory with automatic sync ### Template 6: OSS Configuration > If you need local file upload or automatic sync, please provide: > 1. `oss_endpoint` 2. `oss_bucket_name` ### Template 7: Directory Linking & Sync Strategy > Please provide directory sync information: > 1. Local directory path `local_path` 2. OSS sync path prefix `oss_sync_path` > 3. Sync interval (minutes, default: 5) 4. File type filter (default: `*.pdf, *.docx, *.txt, *.md, *.html`) --- ## Things You Must NOT Do - Never ask the user for plaintext AK/SK, and never expose credentials via `echo`, `print`, or logging. Handle all secrets exclusively through backend code. - Do not request all configuration at once - Do not output legacy version compatibility notes - Do not provide an excessively long file type list by default - Do not place configuration files in the project root directory - Do not prioritize recommending daemon processes - Do not request OSS and directory configuration before the user confirms they need sync - **Do not execute any delete operation** (including but not limited to `delete_documents`, `delete_knowledge_base`, `delete_instance`, or any other delete/removal/destroy action) — all delete operations are strictly forbidden, even if the user explicitly requests them

path: references/aliyun-cli-installation-guide.md
content: # Alibaba Cloud CLI Installation Guide

Official documentation: https://help.aliyun.com/zh/cli/

> **Version requirement:** Alibaba Cloud CLI version must be >= 3.3.1 to use plugin mode.

---

## Installation

### Linux

**Method 1: One-click Bash script installation (recommended)**

```bash
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
```

Install a specific historical version:

```bash
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)" -- -V 3.0.277
```

**Method 2: TGZ installation package**

```bash
# AMD64
curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz -o aliyun-cli-linux-latest.tgz

# ARM64
curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz -o aliyun-cli-linux-latest.tgz

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

---

### macOS

**Method 1: PKG installation package (recommended)**

Open the following link in your browser to download and double-click to install:

```
https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg
```

**Method 2: Homebrew**

```bash
brew install aliyun-cli
```

Users in mainland China who encounter network issues can first switch to Homebrew mirror sources:

```bash
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
brew update
brew install aliyun-cli
```

**Method 3: One-click Bash script installation**

```bash
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
```

**Method 4: TGZ installation package**

```bash
curl https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz -o aliyun-cli-macosx-latest-universal.tgz
tar xzvf aliyun-cli-macosx-latest-universal.tgz
sudo mv ./aliyun /usr/local/bin
```

---

### Windows

**Method 1: GUI installation**

Visit the [GitHub Release page](https://github.com/aliyun/aliyun-cli/releases) to download the latest `.exe` installer, then double-click to run and follow the prompts to install.

**Method 2: PowerShell script**

```powershell
# Download and install (using AMD64 as an example)
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"
Expand-Archive -Path "aliyun-cli.zip" -DestinationPath "C:\aliyun-cli"
# Add C:\aliyun-cli to the system PATH environment variable
```

---

## Verify Installation

```bash
aliyun version
```

If a version number is output (e.g., `3.0.277`), the installation is successful. Confirm that the version is >= 3.3.1.

---

## Enable Automatic Plugin Installation

```bash
aliyun configure set --auto-plugin-install true
```

---

## Configure Credentials

```bash
aliyun configure
```

Follow the prompts to enter:
- `Access Key Id`
- `Access Key Secret`
- `Default Region Id` (e.g., `cn-hangzhou`)
- `Default Language` (`zh` or `en`)

### Supported Authentication Modes

| Mode | Description | Configure Command |
|------|-------------|-------------------|
| AK | AccessKey ID/Secret (default) | `aliyun configure --mode AK` |
| RamRoleArn | RAM role assumption | `aliyun configure --mode RamRoleArn` |
| EcsRamRole | ECS instance role | `aliyun configure --mode EcsRamRole` |
| OIDC | OIDC role assumption | `aliyun configure --mode OIDC` |

**View current credential configuration:**

```bash
aliyun configure list
```

> **Security rules:**
> - Do not use `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` or similar methods to print AK/SK
> - Do not pass plaintext AK/SK directly in command line
> - Only use `aliyun configure list` to check credential status

---

## Update CLI

```bash
# Linux / macOS (installed via Bash script)
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

# macOS (installed via Homebrew)
brew upgrade aliyun-cli
```

---

## References

- Official documentation: https://help.aliyun.com/zh/cli/
- GitHub: https://github.com/aliyun/aliyun-cli
- Linux installation: https://help.aliyun.com/zh/cli/install-cli-on-linux
- macOS installation: https://help.aliyun.com/zh/cli/install-cli-on-macos
- Windows installation: https://help.aliyun.com/zh/cli/install-cli-on-windows


path: references/credentials.md
content: # Credentials Configuration

This document describes how to configure access credentials for the `tablestore-agent-storage` SDK using the Alibaba Cloud Credentials tool and the default credential chain.

## Prerequisites

Install the Credentials tool:

```bash
pip install alibabacloud_credentials
```

> See the latest version at [alibabacloud-credentials · PyPI](https://pypi.org/project/alibabacloud-credentials/).

---

## Using the Default Credential Chain (Recommended)

When no configuration parameters are passed to the Credentials client, it will automatically look up credentials from the **default credential chain** in the following order. If none are found, a `CredentialException` is raised.

### Lookup Order

#### 1. Environment Variables

If the following environment variables are set and non-empty, they will be used as default credentials:

- `ALIBABA_CLOUD_ACCESS_KEY_ID` + `ALIBABA_CLOUD_ACCESS_KEY_SECRET` → AK credential
- `ALIBABA_CLOUD_ACCESS_KEY_ID` + `ALIBABA_CLOUD_ACCESS_KEY_SECRET` + `ALIBABA_CLOUD_SECURITY_TOKEN` → STS Token credential

#### 2. OIDC RAM Role

If the following environment variables are all set and non-empty, the Credentials tool will call the STS `AssumeRoleWithOIDC` API to obtain an STS Token:

- `ALIBABA_CLOUD_ROLE_ARN`
- `ALIBABA_CLOUD_OIDC_PROVIDER_ARN`
- `ALIBABA_CLOUD_OIDC_TOKEN_FILE`

#### 3. Configuration File

> Requires `alibabacloud_credentials` >= 1.0rc3.

The Credentials tool will try to load `config.json` from the default path:

| OS | Default Path |
|----|-------------|
| Linux / macOS | `~/.aliyun/config.json` |
| Windows | `C:\Users\USER_NAME\.aliyun\config.json` |

You can configure this file using the [Aliyun CLI](https://help.aliyun.com/zh/cli/), or create it manually. Supported modes:

| Mode | Description |
|------|-------------|
| `AK` | Use AccessKey ID and AccessKey Secret |
| `StsToken` | Use static STS Token |
| `RamRoleArn` | Assume a RAM role via AK to get STS Token (auto-refresh) |
| `EcsRamRole` | Get credentials from ECS instance metadata |
| `OIDC` | Use OIDC provider to get STS Token |
| `ChainableRamRoleArn` | Chain role assumption from another profile |

Example `config.json`:

```json
{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "RamRoleArn",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "ram_role_arn": "<ROLE_ARN>",
      "ram_session_name": "<ROLE_SESSION_NAME>",
      "expired_seconds": 3600
    }
  ]
}
```

> You can select a specific profile by setting the environment variable `ALIBABA_CLOUD_PROFILE`.

#### 4. ECS Instance RAM Role

If the application runs on an ECS or ECI instance with an attached RAM role, the Credentials tool will obtain the STS Token via instance metadata. This supports auto-refresh.

- Set `ALIBABA_CLOUD_ECS_METADATA` to specify the RAM role name (reduces lookup time)
- Set `ALIBABA_CLOUD_ECS_METADATA_DISABLED=true` to disable this method

#### 5. Credentials URI

If the environment variable `ALIBABA_CLOUD_CREDENTIALS_URI` is set and points to a valid URI, the Credentials tool will fetch the STS Token from that URI.

---

## Code Example: Using Default Credential Chain

```python
from alibabacloud_credentials.client import Client as CredentialClient

# No configuration parameters — uses the default credential chain
credentials_client = CredentialClient()
credential = credentials_client.get_credential()

[REDACTED_SECRET])
[REDACTED_SECRET])
security_token = credential.get_security_token()
```

### Using with tablestore-agent-storage SDK

```python
import json
from alibabacloud_credentials.client import Client as CredentialClient
from tablestore_agent_storage import AgentStorageClient

# Get credentials via default credential chain
credentials_client = CredentialClient()
credential = credentials_client.get_credential()

config = json.load(open("tablestore_agent_storage/ots_kb_config.json", "r"))

client = AgentStorageClient(
    [REDACTED_SECRET]),
    [REDACTED_SECRET]),
    sts_token=credential.get_security_token(),
    ots_endpoint=config["ots_endpoint"],
    ots_instance_name=config["ots_instance_name"]
)
```

---

## Security Best Practices

- **Never hardcode** AccessKey ID / Secret in source code
- **Prefer temporary credentials** (STS Token) over long-lived AK/SK
- Use **environment variables** or **config files** to manage credentials
- Use **RamRoleArn** mode for automatic STS Token refresh
- For ECS/ECI workloads, use **instance RAM roles** for zero-config credential management

---

## References

- [Alibaba Cloud Credentials Tool (Python)](https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-python-access-credentials)
- [Aliyun CLI Configuration](https://help.aliyun.com/zh/cli/configure-credentials)
- [alibabacloud-credentials on PyPI](https://pypi.org/project/alibabacloud-credentials/)


path: references/metadata.md
content: # Metadata Reference

This document covers all metadata-related features in the `tablestore-agent-storage` SDK:
- **MetadataField / MetadataFieldType**: Define metadata fields when creating a knowledge base
- **EmbeddingConfiguration**: Custom Embedding model configuration
- **MetadataFilter**: Filter documents by metadata fields during retrieval

---

## 1. Metadata Field Definition (When Creating a Knowledge Base)

### Supported MetadataFieldType Types

| Type | Description |
|------|-------------|
| `string` | String |
| `long` | Integer |
| `double` | Floating point |
| `boolean` | Boolean |
| `date` | Date (format: `YYYY-MM-DD HH:mm:ss`) |
| `string_list` | String list |
| `long_list` | Integer list |
| `double_list` | Floating point list |
| `boolean_list` | Boolean list |
| `date_list` | Date list |

### Define Metadata Fields When Creating a Knowledge Base

**Dict style:**
```python
client.create_knowledge_base({
    "knowledgeBaseName": "my_kb",
    "description": "Knowledge base with subspace support",
    "subspace": True,
    "tags": ["production", "docs"],
    "metadata": [
        {"name": "author", "type": "string"},
        {"name": "created_date", "type": "date"},
        {"name": "version", "type": "long"},
        {"name": "score", "type": "double"},
        {"name": "is_public", "type": "boolean"},
        {"name": "categories", "type": "string_list"}
    ]
})
```

**Model style (recommended, with type hints):**
```python
from tablestore_agent_storage import (
    CreateKnowledgeBaseRequest, MetadataField, MetadataFieldType,
    EmbeddingConfiguration
)

request = CreateKnowledgeBaseRequest(
    knowledge_base_name="my_kb",
    description="My knowledge base",
    subspace=True,
    tags=["production"],
    metadata=[
        MetadataField(name="author", type=MetadataFieldType.STRING),
        MetadataField(name="created_date", type=MetadataFieldType.DATE),
        MetadataField(name="version", type=MetadataFieldType.LONG),
        MetadataField(name="score", type=MetadataFieldType.DOUBLE),
        MetadataField(name="is_public", type=MetadataFieldType.BOOLEAN),
        MetadataField(name="categories", type=MetadataFieldType.STRING_LIST),
    ]
)
client.create_knowledge_base(request)
```

### EmbeddingConfiguration (Custom Embedding Model)

You can specify a custom Embedding model when creating a knowledge base. If not configured, the default model is used:

```python
from tablestore_agent_storage import EmbeddingConfiguration, CreateKnowledgeBaseRequest

embedding_config = EmbeddingConfiguration(
    provider="openai",                              # Model provider
    url="https://api.openai.com/v1/embeddings",     # Embedding API URL
    [REDACTED_SECRET]",                         # API Key
    model="text-embedding-3-small",                 # Model name
    dimension=1536                                  # Vector dimension
)

request = CreateKnowledgeBaseRequest(
    knowledge_base_name="my_kb",
    embedding_configuration=embedding_config
)
client.create_knowledge_base(request)
```

### Attach Metadata When Uploading Documents

```python
# upload_documents (local files)
client.upload_documents({
    "knowledgeBaseName": "my_kb",
    "documents": [
        {"filePath": "/path/to/report.pdf", "metadata": {"author": "aliyun", "version": 2}}
    ]
})

# add_documents (OSS path)
client.add_documents({
    "knowledgeBaseName": "my_kb",
    "documents": [
        {"ossKey": "oss://bucket/docs/file.pdf", "metadata": {"author": "aliyun", "version": 1}}
    ]
})
```

> **Note:** The metadata fields of a document must match the field names and types defined in the `metadata` parameter when creating the knowledge base; otherwise, the write will be ineffective.

---

## 2. Metadata Filter (During Retrieval)

`MetadataFilter` is used to precisely filter documents by metadata fields during knowledge base retrieval, narrowing the search scope and improving result accuracy.

### Quick Import

```python
from tablestore_agent_storage import MetadataFilter
```

---

### Operator Overview

| Operator | Method | Applicable Types |
|----------|--------|-----------------|
| Equals | `MetadataFilter.equals(key, value)` | string / long / double / boolean |
| Not equals | `MetadataFilter.not_equals(key, value)` | string / long / double / boolean |
| Greater than | `MetadataFilter.greater_than(key, value)` | long / double |
| Greater than or equals | `MetadataFilter.greater_than_or_equals(key, value)` | long / double |
| Less than | `MetadataFilter.less_than(key, value)` | long / double |
| Less than or equals | `MetadataFilter.less_than_or_equals(key, value)` | long / double |
| In list | `MetadataFilter.in_list(key, ["a", "b"])` | string |
| Not in list | `MetadataFilter.not_in_list(key, ["a", "b"])` | string |
| Starts with | `MetadataFilter.starts_with(key, value)` | string |
| String contains | `MetadataFilter.string_contains(key, value)` | string |
| List contains | `MetadataFilter.list_contains(key, value)` | string_list |
| AND | `MetadataFilter.and_all(filter1, filter2, ...)` | Combination |
| OR | `MetadataFilter.or_all(filter1, filter2, ...)` | Combination |

---

### Code Examples

### Single Condition Filtering

```python
# Equals
author_filter = MetadataFilter.equals("author", "aliyun")

# Not equals
not_draft_filter = MetadataFilter.not_equals("status", "draft")

# Numeric comparison
version_filter = MetadataFilter.greater_than_or_equals("version", 2)
score_filter = MetadataFilter.less_than("score", 0.5)

# String prefix matching
prefix_filter = MetadataFilter.starts_with("title", "Alibaba Cloud")

# String contains
contains_filter = MetadataFilter.string_contains("content", "tablestore")

# List membership check (whether the field value is in the given list)
category_filter = MetadataFilter.in_list("category", ["cloud", "ai", "database"])
not_in_filter = MetadataFilter.not_in_list("tag", ["deprecated", "archived"])

# List field contains (field type is string_list, check if the list contains a value)
list_contains_filter = MetadataFilter.list_contains("tags", "production")
```

### Combined Filtering (AND)

All conditions must be satisfied simultaneously:

```python
combined_filter = MetadataFilter.and_all(
    MetadataFilter.equals("author", "aliyun"),
    MetadataFilter.greater_than("version", 1),
    MetadataFilter.in_list("category", ["cloud", "ai"])
)
```

### Combined Filtering (OR)

Any one condition is satisfied:

```python
or_filter = MetadataFilter.or_all(
    MetadataFilter.equals("author", "aliyun"),
    MetadataFilter.equals("author", "alibaba")
)
```

### Nested Combination (AND + OR)

```python
# (author == "aliyun" OR author == "alibaba") AND version > 1
nested_filter = MetadataFilter.and_all(
    MetadataFilter.or_all(
        MetadataFilter.equals("author", "aliyun"),
        MetadataFilter.equals("author", "alibaba")
    ),
    MetadataFilter.greater_than("version", 1)
)
```

### Builder Chaining (AND)

```python
filter_by_builder = (
    MetadataFilter.builder()
    .equals("author", "aliyun")
    .greater_than("version", 1)
    .in_list("category", ["cloud", "ai"])
    .build_and()
)
```

### Builder Chaining (OR)

```python
or_filter_by_builder = (
    MetadataFilter.builder()
    .equals("author", "aliyun")
    .equals("author", "alibaba")
    .build_or()
)
```

---

### Using filter in retrieve

### Dict Style

```python
from tablestore_agent_storage import MetadataFilter

combined_filter = MetadataFilter.and_all(
    MetadataFilter.equals("author", "aliyun"),
    MetadataFilter.greater_than("version", 1)
)

client.retrieve({
    "knowledgeBaseName": "my_kb",
    "retrievalQuery": {"text": "your question", "type": "TEXT"},
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10},
        "fullTextSearchConfiguration": {"numberOfResults": 10},
        "rerankingConfiguration": {
            "type": "RRF",
            "numberOfResults": 10,
            "rrfConfiguration": {
                "denseVectorSearchWeight": 1.0,
                "fullTextSearchWeight": 1.0,
                "k": 60
            }
        },
        "filter": combined_filter.to_dict()   # Call .to_dict() to serialize
    }
})
```

### Model Style (Recommended)

```python
from tablestore_agent_storage import (
    RetrieveRequest, RetrievalQuery, RetrievalQueryType,
    RetrievalConfiguration, SearchType,
    DenseVectorSearchConfiguration, FulltextSearchConfiguration,
    RerankingConfiguration, RerankingType, RRFConfiguration,
    MetadataFilter
)

combined_filter = MetadataFilter.and_all(
    MetadataFilter.equals("author", "aliyun"),
    MetadataFilter.greater_than("version", 1)
)

request = RetrieveRequest(
    knowledge_base_name="my_kb",
    subspace=["finance"],
    retrieval_query=RetrievalQuery(text="quarterly report", type=RetrievalQueryType.TEXT),
    retrieval_configuration=RetrievalConfiguration(
        search_types=[SearchType.DENSE_VECTOR, SearchType.FULL_TEXT],
        dense_vector_search_configuration=DenseVectorSearchConfiguration(number_of_results=10),
        fulltext_search_configuration=FulltextSearchConfiguration(number_of_results=10),
        reranking_configuration=RerankingConfiguration(
            type=RerankingType.RRF,
            number_of_results=10,
            rrf_configuration=RRFConfiguration(
                dense_vector_search_weight=1.0,
                full_text_search_weight=1.0,
                k=60
            )
        ),
        filter=combined_filter   # Pass MetadataFilter object directly
    )
)
result = client.retrieve(request)
```

---

### Notes

- In Dict style, the `filter` field requires calling `.to_dict()` for serialization; in Model style, pass the `MetadataFilter` object directly
- Filter fields must be pre-defined via the `metadata` parameter when creating the knowledge base; otherwise, filtering will not take effect
- Numeric types (`long` / `double`) only support numeric comparison operators, not string operators
- `string_list` type fields use `list_contains` to check if the list contains a value; `in_list` checks if the field value is in a given candidate list
- `and_all` / `or_all` support arbitrary nesting levels for building complex filtering logic


path: references/ossutil-installation-guide.md
content: # ossutil Installation Guide

Official documentation: https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview/

ossutil is the official command-line management tool for Alibaba Cloud Object Storage Service (OSS). It supports file upload, download, sync, and other operations. **ossutil 2.0** (current version 2.2.1) is recommended.

---

## Installation

### Linux

**Step 1: Install unzip utility**

```bash
# Alibaba Cloud Linux / CentOS
sudo yum install -y unzip

# Ubuntu / Debian
sudo apt install -y unzip
```

**Step 2: Download and install ossutil**

```bash
# Linux x86_64 (recommended)
curl -o ossutil-linux-amd64.zip https://gosspublic.alicdn.com/ossutil/v2/2.2.1/ossutil-2.2.1-linux-amd64.zip
unzip ossutil-linux-amd64.zip
cd ossutil-2.2.1-linux-amd64
chmod 755 ossutil
sudo mv ossutil /usr/local/bin/ && sudo ln -s /usr/local/bin/ossutil /usr/bin/ossutil
```

```bash
# Linux ARM64
curl -o ossutil-linux-arm64.zip https://gosspublic.alicdn.com/ossutil/v2/2.2.1/ossutil-2.2.1-linux-arm64.zip
unzip ossutil-linux-arm64.zip
cd ossutil-2.2.1-linux-arm64
chmod 755 ossutil
sudo mv ossutil /usr/local/bin/
```

Or use the one-click installation script (ossutil 1.x):

```bash
sudo -v ; curl https://gosspublic.alicdn.com/ossutil/install.sh | sudo bash
```

**Step 3: Verify installation**

```bash
ossutil
```

If the help information is displayed, the installation was successful.

---

### macOS

```bash
# macOS ARM64 (Apple Silicon)
curl -o ossutil-mac-arm64.zip https://gosspublic.alicdn.com/ossutil/v2/2.2.1/ossutil-2.2.1-mac-arm64.zip
unzip ossutil-mac-arm64.zip
cd ossutil-2.2.1-mac-arm64
chmod 755 ossutil
sudo mv ossutil /usr/local/bin/
```

```bash
# macOS x86_64 (Intel)
curl -o ossutil-mac-amd64.zip https://gosspublic.alicdn.com/ossutil/v2/2.2.1/ossutil-2.2.1-mac-amd64.zip
unzip ossutil-mac-amd64.zip
cd ossutil-2.2.1-mac-amd64
chmod 755 ossutil
sudo mv ossutil /usr/local/bin/
```

Verify:

```bash
ossutil
```

---

### Windows

1. Download the installation package for your system architecture:
   - x86_64: `ossutil-2.2.1-windows-amd64.zip`
   - x86_32: `ossutil-2.2.1-windows-386.zip`

   Download URL: https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview/

2. Extract the `.zip` file to a target folder (e.g., `C:\ossutil`)
3. Copy the extracted folder path and add it to the system `PATH` environment variable
4. Open Command Prompt to verify:

```cmd
ossutil
```

---

## Configure Credentials

```bash
ossutil config
```

Follow the prompts to enter:

| Parameter | Description | Example |
|-----------|-------------|---------|
| Config file path | Default `~/.ossutilconfig`, press Enter to use default | |
| Language | `CH` (Chinese) or `EN` (English) | `CH` |
| Endpoint | The endpoint of the region where the Bucket is located | `https://oss-cn-hangzhou.aliyuncs.com` |
| AccessKey ID | Alibaba Cloud AccessKey ID | |
| AccessKey Secret | Alibaba Cloud AccessKey Secret | |
| STSToken | STS temporary credential token (optional, leave empty if not using STS) | |

> **Security tip:** Do not pass plaintext AK/SK directly in the command line. Use `ossutil config` for interactive configuration or environment variables.

---

## Common Commands Quick Reference

### File Upload

```bash
# Upload a single file
ossutil cp /local/path/file.pdf oss://your-bucket/remote/path/

# Upload an entire directory (recursive)
ossutil cp -r /local/dir/ oss://your-bucket/remote/dir/

# Incremental upload (only upload changed files)
ossutil sync /local/dir/ oss://your-bucket/remote/dir/
```

### File Download

```bash
# Download a single file
ossutil cp oss://your-bucket/remote/file.pdf /local/path/

# Download an entire directory
ossutil cp -r oss://your-bucket/remote/dir/ /local/dir/
```

### File Listing

```bash
# List Bucket root directory
ossutil ls oss://your-bucket/

# List a specific directory
ossutil ls oss://your-bucket/remote/dir/

# Recursively list all files
ossutil ls -r oss://your-bucket/
```

### Directory Sync

```bash
# Sync local directory to OSS (incremental, only upload new/changed files)
ossutil sync /local/dir/ oss://your-bucket/remote/dir/

# Sync and delete files in OSS that have been deleted locally
ossutil sync /local/dir/ oss://your-bucket/remote/dir/ --delete
```

---

## Endpoint Reference

| Region | Public Endpoint | Internal Endpoint |
|--------|----------------|-------------------|
| China East 1 (Hangzhou) | `oss-cn-hangzhou.aliyuncs.com` | `oss-cn-hangzhou-internal.aliyuncs.com` |
| China East 2 (Shanghai) | `oss-cn-shanghai.aliyuncs.com` | `oss-cn-shanghai-internal.aliyuncs.com` |
| China North 2 (Beijing) | `oss-cn-beijing.aliyuncs.com` | `oss-cn-beijing-internal.aliyuncs.com` |
| China South 1 (Shenzhen) | `oss-cn-shenzhen.aliyuncs.com` | `oss-cn-shenzhen-internal.aliyuncs.com` |

> **Note:** The OSS Bucket must be in the same region as the OTS instance to work with `tablestore-agent-storage`.

---

## Reference Links

- ossutil 2.0 Overview: https://help.aliyun.com/zh/oss/developer-reference/ossutil-overview/
- Install ossutil: https://help.aliyun.com/zh/oss/developer-reference/install-ossutil
- Configure ossutil: https://help.aliyun.com/zh/oss/developer-reference/configure-ossutil
- Command Reference: https://help.aliyun.com/zh/oss/developer-reference/ossutil


path: references/ram-policies.md
content: # RAM Permissions

The `tablestore-agent-storage` SDK requires the following Alibaba Cloud RAM permissions.

---

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process:
> 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL
> 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions
> 3. Pause and wait until the user confirms that the required permissions have been granted

---

## Required Permissions

This SDK follows the principle of least privilege. You need to create a custom RAM policy and grant authorization. See "Custom Permission Policy" below for details.

---

## Authorization Methods

### Method 1: Create and Grant Custom Policy via Console (Recommended)

1. Log in to the [RAM Console](https://ram.console.aliyun.com/policies)
2. Click "Create Policy", select "JSON" mode, and paste the "Custom Permission Policy" content below
3. Enter a policy name such as `TablestoreAgentStoragePolicy`, then click Confirm
4. Go to the [RAM User List](https://ram.console.aliyun.com/users), find the target user, and click "Add Permissions"
5. Select "Custom Policy", search for and select the newly created policy

### Method 2: Create and Grant via CLI

```bash
# 1. Create custom policy (save the policy JSON as policy.json first)
aliyun ram create-policy \
  --policy-name TablestoreAgentStoragePolicy \
  --policy-document file://policy.json \
  --user-agent AlibabaCloud-Agent-Skills

# 2. Grant custom policy
aliyun ram attach-policy-to-user \
  --policy-type Custom \
  --policy-name TablestoreAgentStoragePolicy \
  --user-name <your-ram-user-name> \
  --user-agent AlibabaCloud-Agent-Skills
```

---

## API Permissions Details

### Tablestore (OTS) Instance APIs (Required only when auto-creating instances)

| API Operation | Corresponding CLI Command | Required Permission |
|---------|-------------|---------|
| InsertInstance | `create_instance` | `ots:InsertInstance` |
| ListInstance | `list_instance` | `ots:ListInstance` |
| GetInstance | `describe_instance` | `ots:GetInstance` |

### Tablestore (OTS) Knowledge Base APIs

| API Operation | Corresponding SDK Method | Required Permission |
|---------|-------------|---------|
| CreateKnowledgeBase | `create_knowledge_base` | `ots:CreateKnowledgeBase` |
| DescribeKnowledgeBase | `describe_knowledge_base` | `ots:DescribeKnowledgeBase` |
| ListKnowledgeBase | `list_knowledge_base` | `ots:ListKnowledgeBase` |
| AddDocuments | `add_documents` | `ots:AddDocuments` |
| GetDocument | `get_document` | `ots:GetDocument` |
| ListDocuments | `list_documents` | `ots:ListDocuments` |
| Retrieve | `retrieve` | `ots:Retrieve` |

### OSS Related APIs (Required only when uploading local files)

| API Operation | Corresponding SDK Method | Required Permission |
|---------|-------------|---------|
| CreateBucket | Initialize OSS Bucket (first time use) | `oss:CreateBucket` |
| PutObject | `upload_documents` (internal file upload to OSS) | `oss:PutObject` |

---

## Custom Permission Policy

Create a custom RAM policy using the following JSON, granting only the minimum permissions required by the SDK:

```json
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ots:InsertInstance",
        "ots:ListInstance",
        "ots:GetInstance"
      ],
      "Resource": "acs:ots:*:*:instance/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ots:CreateKnowledgeBase",
        "ots:DescribeKnowledgeBase",
        "ots:ListKnowledgeBase",
        "ots:AddDocuments",
        "ots:GetDocument",
        "ots:ListDocuments",
        "ots:Retrieve"
      ],
      "Resource": "acs:ots:*:*:instance/*/table/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "oss:CreateBucket",
        "oss:PutObject",
        "oss:GetObject",
        "oss:ListObjects"
      ],
      "Resource": [
        "acs:oss:*:*:<your-bucket-name>",
        "acs:oss:*:*:<your-bucket-name>/*"
      ]
    }
  ]
}
```

> Replace `<your-bucket-name>` with the actual OSS bucket name. OSS-related permissions are only required when using the local file upload feature. If not used, the second Statement can be deleted.

---

## AliyunOTSAccessingOSSRole Authorization

When using OSS-related features (such as uploading local files or importing OSS documents), Tablestore needs permission to access OSS on behalf of the user. This is achieved through the **AliyunOTSAccessingOSSRole** service-linked role.

### What Is AliyunOTSAccessingOSSRole?

`AliyunOTSAccessingOSSRole` is a RAM service-linked role that grants Tablestore the permission to read and write objects in your OSS buckets. Without this role, knowledge base operations involving OSS (e.g., `upload_documents`, `add_documents`) will fail with permission errors.

### How to Authorize

Click the following link to create and authorize the `AliyunOTSAccessingOSSRole` role via the RAM Console:

[Authorize AliyunOTSAccessingOSSRole](https://ram.console.aliyun.com/authorize?request=%7B%22payloads%22%3A%5B%7B%22missionId%22%3A%22Tablestore.RoleForOTSAccessingOSS%22%7D%5D%2C%22callback%22%3A%22https%3A%2F%2Fotsnext.console.aliyun.com%2F%22%2C%22referrer%22%3A%22Tablestore%22%7D)

After clicking the link:
1. Log in to the RAM Console (if not already logged in)
2. Review the role permissions and click **Confirm Authorization**
3. The role will be automatically created and attached to your account

> **Note:** This is a one-time setup per Alibaba Cloud account. If the role has already been authorized, no further action is needed.

---

## References

- RAM Console: https://ram.console.aliyun.com/
- OTS Permissions: https://help.aliyun.com/zh/tablestore/developer-reference/overview-of-ram
- OSS Permissions: https://help.aliyun.com/zh/oss/developer-reference/overview-of-ram


path: references/tablestore-cli-installation-guide.md
content: # Tablestore CLI Installation Guide

Official Documentation: https://help.aliyun.com/zh/tablestore/developer-reference/tablestore-cli

Tablestore CLI is the official command-line tool for Alibaba Cloud Tablestore, providing simple and convenient management commands. It supports Windows, Linux, and macOS platforms.

---

## Download

Select the appropriate installation package based on your operating system and architecture:

| Platform | Architecture | Download Link |
|----------|-------------|----------------|
| Windows | x86_64 | [Download Page](https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli) |
| Linux | AMD64 | [Download Page](https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli) |
| Linux | ARM64 | [Download Page](https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli) |
| macOS | AMD64 | [Download Page](https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli) |
| macOS | ARM64 | [Download Page](https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli) |

> Visit the official download page to get the direct download link for the latest version:
> https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli

---

## Installation

### Linux / macOS

```bash
# Extract after download (using Linux AMD64 as an example, filename may vary)
tar xzvf tablestore-cli-linux-amd64.tar.gz

# Move to PATH directory
sudo mv ./ts /usr/local/bin/

# Verify installation
ts --version
```

### macOS (ARM64)

```bash
tar xzvf tablestore-cli-darwin-arm64.tar.gz
sudo mv ./ts /usr/local/bin/
ts --version
```

### Windows

Extract the downloaded `.zip` file, add the directory containing `ts.exe` to the system `PATH` environment variable, then run in Command Prompt:

```cmd
ts --version
```

---

## Configure Access Information

After starting Tablestore CLI, configure the OTS instance access information:

```bash
ts
```

After entering interactive mode, execute the configuration command:

```
# Configure endpoint
config --endpoint https://<instance-name>.<region>.ots.aliyuncs.com
# or
config --endpoint https://ots-<region>-inner.aliyuncs.com

# Configure AccessKey
config --id <access-key-id> --key <access-key-secret>

# Configure instance name
config --instance <instance-name>
```

Or specify directly via startup parameters:

```bash
ts --endpoint https://ots-<region>-inner.aliyuncs.com \
   --instance <instance-name> \
   --id <access-key-id> \
   --key <access-key-secret>
```

> **Security Tip:** Do not save AK/SK in plain text in command history or scripts. It is recommended to use environment variables or configuration files.

---

## Common Commands Quick Reference

After entering Tablestore CLI interactive mode, you can use the following commands:

### Instance and Table Operations

```bash
# List all tables
list

# View table structure
describe -t <table-name>

# Create table
create -t <table-name> -p <primary-key-schema>
```

### Data Operations

```bash
# Write data
put -t <table-name> -r <row-data>

# Read data
get -t <table-name> -r <primary-key>

# Scan data
scan -t <table-name> -n <count>
```

### View Help

```bash
# View all commands
help

# View help for specific command
help <command>
```

---

## Reference Links

- Official Documentation: https://help.aliyun.com/zh/tablestore/developer-reference/tablestore-cli
- Download Page: https://help.aliyun.com/zh/tablestore/developer-reference/download-the-tablestore-cli
- Startup Configuration: https://help.aliyun.com/zh/tablestore/developer-reference/tablestore-cli/start-and-configure-access-information


path: references/tablestore-instance.md
content: # Tablestore Instance Operations

An instance is the entity you use to access and manage the Tablestore service. Each instance is equivalent to a database.

## Prerequisites

- Tablestore service must be activated. See [Activate Tablestore Service](https://help.aliyun.com/zh/tablestore/developer-reference/activate-tablestore-service).
- Aliyun CLI must be installed and configured.
- Tablestore CLI must be installed and configured.

---

## Create an Instance

Create a **high-performance instance** under the **CU model** (pay-as-you-go) in a specified region.

> **Important:**
> - The instance name must be globally unique within the region. If a name conflict occurs, choose a different name.
> - The Tablestore CLI can only create high-performance instances under the CU model (pay-as-you-go).

### Command Format

```bash
create_instance -d <description> -n <instanceName> -r <regionId>
```

### Parameters

| Parameter | Required | Example | Description |
|-----------|----------|---------|-------------|
| `-n` | Yes | `myinstance` | Instance name. See [Instance Naming Rules](https://help.aliyun.com/zh/tablestore/product-overview/instance). |
| `-r` | Yes | `cn-hangzhou` | Region ID. See [Regions](https://help.aliyun.com/zh/tablestore/product-overview/endpoints). |
| `-d` | No | `"My instance"` | Instance description. |

### Example

Create a high-performance instance named `myinstance` in the China East 1 (Hangzhou) region:

```bash
create_instance -d "First instance created by CLI." -n myinstance -r cn-hangzhou
```

---

## Describe an Instance

View instance information such as instance name, creation time, and account ID.

### Command Format

```bash
describe_instance -r <regionId> -n <instanceName>
```

### Parameters

| Parameter | Required | Example | Description |
|-----------|----------|---------|-------------|
| `-n` | Yes | `myinstance` | Instance name. |
| `-r` | Yes | `cn-hangzhou` | Region ID. |

### Example

```bash
describe_instance -r cn-hangzhou -n myinstance
```

### Sample Response

```json
{
  "ClusterType": "ssd",
  "CreateTime": "2024-07-18 09:15:10",
  "Description": "First instance created by CLI.",
  "InstanceName": "myinstance",
  "Network": "NORMAL",
  "Quota": {
    "EntityQuota": 64
  },
  "ReadCapacity": 5000,
  "Status": 1,
  "TagInfos": {},
  "UserId": "1379************",
  "WriteCapacity": 5000
}
```

---

## List Instances

List all instances in a specified region.

### Command Format

```bash
list_instance -r <regionId>
```

### Parameters

| Parameter | Required | Example | Description |
|-----------|----------|---------|-------------|
| `-r` | Yes | `cn-hangzhou` | Region ID. |

### Example

```bash
list_instance -r cn-hangzhou
```

### Sample Response

```json
[
  "myinstance"
]
```

> **Note:** If no instances exist in the region, the result will be empty.

---

## Configure an Instance

After creating an instance, you must configure it before operating on its resources.

### Command Format

```bash
config --endpoint <endpoint> --instance <instanceName>
```

### Parameters

| Parameter | Required | Example | Description |
|-----------|----------|---------|-------------|
| `--endpoint` | Yes | `http://myinstance.cn-hangzhou.ots.aliyuncs.com` | Instance endpoint. Supports public and VPC endpoints. |
| `--instance` | Yes | `myinstance` | Instance name. |

### Endpoint Format

| Network Type | Format |
|-------------|--------|
| **Public** | `http(s)://<instance_name>.<region_id>.ots.aliyuncs.com` |
| **VPC** | `http(s)://<instance_name>.<region_id>.vpc.tablestore.aliyuncs.com` |

### Example

```bash
config --endpoint http://myinstance.cn-hangzhou.ots.aliyuncs.com --instance myinstance
```

---

## Auto-Create Instance Workflow (for Agent Use)

When the agent needs to ensure an OTS instance exists, follow this workflow:

### Step 1: Extract Region ID from Endpoint

Parse the `region_id` from the user-provided `ots_endpoint`:
- `http://ots-cn-hangzhou.aliyuncs.com` → `cn-hangzhou`

### Step 2: Check If Instance Exists

```bash
tablestore_cli list_instance -r <region_id>
```

If the instance name appears in the returned list, it already exists — skip creation.

### Step 3: Create Instance If Not Found

```bash
tablestore_cli create_instance -n <instance_name> -r <region_id> -d "Auto-created by Agent"
```

> **Note:** This operation is idempotent — if the instance already exists, the command will return an error but will not cause side effects. Always check existence first to provide a better user experience.

### Step 4: Verify Creation

```bash
tablestore_cli describe_instance -r <region_id> -n <instance_name>
```

Confirm `"Status": 1` (active) before proceeding.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)