/alibabacloud-bailian-rag-knowledgebase

name: alibabacloud-bailian-rag-knowledgebase
description: "Alibaba Cloud Bailian Knowledge Base Retrieval Tool. Use HTTPS API to query and retrieve knowledge base content. Use when: User needs to query knowledge base, retrieve document content, or answer questions based on knowledge base. Prerequisites: (1) Configure DashScope API Key (2) Activate Bailian Knowledge Base service."

Bailian Knowledge Base Retrieval

This Skill provides query and retrieval capabilities for Alibaba Cloud Bailian Knowledge Base via HTTPS API.

API Key Security Management

Scripts automatically handle key retrieval via `api_key.py`. The Agent does not need to and should not manually extract, set, or pass API Key values.

• **Key retrieval is automated**: Scripts internally call `api_key.py` to automatically obtain keys from config files/environment variables. The Agent only needs to run the script command.
• **Never hardcode any form of key**: Including `api_key = "sk-..."`, `export DASHSCOPE_API_KEY="sk-..."`, and assigning keys in shell scripts.
• **Never extract keys from CLI output**: The Agent must not write key values into any script, variable, or file.
• **Never expose keys in any output**: Including generated scripts, shell commands, log files, and terminal output containing strings starting with `sk-`.
• **Never read or print keys from config files**: Do not use `cat`, `jq`, `python -c`, or other commands to read and output API Key values.
• **Mandatory self-check before task completion**: Run `grep -rn "sk-" <output_directory>/` to check all output files; if any strings starting with `sk-` are found (excluding `sk-xxx` placeholders), delete the affected files and regenerate.

🚀 Initial Setup (Required for First-time Use)

1. Configure API Key

API Keys are managed by the unified `scripts/api_key.py` module, with the following retrieval priority: 1. Alibaba Cloud CLI config `~/.aliyun/config.json` current profile's `dashscope.api_key` 2. Environment variable `DASHSCOPE_API_KEY` 3. Auto-create and save when Alibaba Cloud CLI is available (`generate_api_key()`)

# All scripts use this unified approach
from api_key import get_api_key
api_key = get_api_key()  # Returns str, raises ValueError if not found

Manual environment variable configuration:

export DASHSCOPE_API_KEY=sk-xxx

| Item | Description | |------|-------------| | **Key Format** | `sk-xxx` (standard DashScope API Key) | | **Not Supported** | `sk-sp-xxx` (Coding Plan Key, does not support knowledge base services) | | **Get Key** | https://bailian.console.aliyun.com/cn-beijing/?tab=app#/api-key |

Alibaba Cloud CLI Configuration (API Key Auto-Create/Delete)

The `scripts/api_key.py` module creates and deletes API Keys via `aliyun modelstudio` commands. Complete the following setup before use:

**1. Update Plugins**

# Update plugins to latest version
aliyun plugin update

**2. Install ModelStudio Plugin** (if not already installed)

aliyun plugin install --names aliyun-cli-modelstudio --enable-pre

**CLI Commands Used**:

| Command | Purpose | Called From | |---------|---------|-------------| | `aliyun modelstudio list-workspaces` | Get Bailian Workspace ID | `api_key.py: _get_workspace_id()` | | `aliyun modelstudio create-api-key` | Create DashScope API Key | `api_key.py: generate_api_key()` | | `aliyun modelstudio delete-api-key` | Delete cloud API Key | `api_key.py: _delete_cloud_api_key()` |

2. Important Prerequisite: Activate Bailian Knowledge Base Service

**Before using this skill, you must first activate the knowledge base service in the Alibaba Cloud Bailian console!**

1. Visit [Bailian Knowledge Base page](https://bailian.console.aliyun.com/cn-beijing/?tab=app#/knowledge-base) 2. Click the **"Activate Now"** button 3. Confirm activation and wait for the service to take effect (usually 1-2 minutes)

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) and export it as `SKILL_SESSION_ID`. This value must remain constant for the entire skill session.

Every `aliyun` CLI command and HTTPS API call must include a `User-Agent` identifier for traceability.

User-Agent Format

AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session-id}

• `{session-id}` = value of `SKILL_SESSION_ID` environment variable (32-char lowercase hex string)
• Scripts read it via `os.environ.get("SKILL_SESSION_ID", "")`; if empty, generate one with `secrets.token_hex(16)`

Per-Command --user-agent (CLI)

Every `aliyun modelstudio` business command MUST carry `--user-agent` on the command line:

aliyun modelstudio list-workspaces --region cn-beijing \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session-id}"

> **Prohibited**: Do NOT set User-Agent via global configuration commands. Only per-command `--user-agent` is allowed.

HTTPS User-Agent Header

All HTTPS API requests set the `User-Agent` HTTP header:

"User-Agent": f"AlibabaCloud-Agent-Skills/alibabacloud-bailian-rag-knowledgebase/{session_id}"

Applied Locations

| Location | Mechanism | |----------|----------| | `scripts/list_indices.py` | HTTPS `User-Agent` header via `_get_user_agent()` | | `scripts/retrieve.py` | HTTPS `User-Agent` header via `_get_user_agent()` | | `scripts/api_key.py` → `_get_workspace_id()` | `aliyun modelstudio list-workspaces --user-agent ...` | | `scripts/api_key.py` → `generate_api_key()` | `aliyun modelstudio create-api-key --user-agent ...` | | `scripts/api_key.py` → `_delete_cloud_api_key()` | `aliyun modelstudio delete-api-key --user-agent ...` |

Available Scripts

All scripts are located in the `scripts/` directory:

| Script | Purpose | Parameters | |--------|---------|--------