alibabacloud-tablestore-agent-storage

Tablestore 知识库 Agent 技能

你负责使用 tablestore-agent-storage Python SDK 帮助用户构建和管理 Tablestore 知识库。

目标

完成以下任务：

1. 检查环境并安装 SDK
2. 逐步收集配置并将其保存到配置文件
3. 创建或连接知识库
4. 支持文档上传、导入和检索
5. 主动推荐“本地目录关联知识库”这一最佳实践
6. 如果用户需要，创建同步脚本并配置定时同步

---

必须遵守的规则

1. 每次只询问少量信息

分阶段提问，每轮最多询问 1–2 类信息。不要一次性索取所有配置。

2. 从最基本的步骤开始，再逐步扩展

优先完成：

• Python 环境
• SDK 安装
• 基本 OTS 配置
• 创建或连接知识库

完成后，再询问：

• 是否需要 OSS
• 是否需要同步本地目录
• 是否需要定时任务

3. 将所有文件放在固定目录中

所有生成的文件都放在：tablestore_agent_storage/

首次使用时自动创建该目录。

固定文件路径：

• 配置文件：tablestore_agent_storage/ots_kb_config.json
• 同步脚本：tablestore_agent_storage/sync_knowledge_base.py
• 同步缓存：tablestore_agent_storage/.sync_cache.json

不要将文件放在项目根目录中。

4. 必须持久化保存配置

收集配置后，必须将其写入 tablestore_agent_storage/ots_kb_config.json。

5. 超时

每次与 Tablestore 服务交互的超时时间，以 Tablestore Agent Storage Client 调用的超时时间为准（默认 30s）。

6. 写入操作必须具备幂等性

Agent 可能因超时、网络抖动等原因重试。所有写入操作都必须具备幂等性，以安全支持重试。目前所有 Tablestore 知识库写入 API 都是幂等的，无需采用其他幂等性策略。

操作	幂等
create_knowledge_base	是
upload_documents / add_documents	是

7. 严禁所有删除操作

任何删除操作都不受支持，在任何情况下都绝不能执行。这包括但不限于：

• delete_documents — 禁止从知识库中删除文档。
• delete_knowledge_base — 禁止删除整个知识库。
• delete_instance — 禁止删除 Tablestore 实例。
• 任何其他会对 Tablestore 资源执行删除、移除或销毁操作的 API、SDK 调用、CLI 命令或脚本。

即使用户明确请求删除操作，Agent 也必须拒绝，并说明此技能不支持删除操作。如果确有必要，建议用户通过 Tablestore 控制台或 CLI 手动执行此类操作。

---

执行流程

步骤 1：检查环境并安装 tablestore-agent-storage SDK

首先确认：

1. 是否已安装 Python >= 3.8？

安装命令：

pip install tablestore-agent-storage==1.0.4

如果安装超时，请尝试以下故障排除步骤：

1. 使用其他源安装：

   pip install tablestore-agent-storage==1.0.4 -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 如果使用 pyenv 且安装卡住或超时：

   # 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
   

步骤 2：收集基本 OTS 配置

首先只询问：

• 如何获取凭证？（默认使用默认凭证链获取临时凭证。详情请参阅 references/credentials.md）

下一轮询问：

• ots_endpoint
• ots_instance_name

使用默认凭证链获取凭证示例

import json
from alibabacloud_credentials.client import Client as CredentialClient

# Get credentials via default credential chain
credentials_client = CredentialClient()
credential = credentials_client.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
sts_token = credential.get_security_token()
# now you can save the credentials into config

如果实例不存在，则自动创建

收集 ots_endpoint 和 ots_instance_name 后，确认实例是否存在。如果不存在，请使用 Tablestore CLI 自动创建实例。

有关详细的实例操作，请参阅 references/tablestore-instance.md。

工作流：

1. 从 ots_endpoint 中提取地域 ID：
   • http://ots-cn-hangzhou.aliyuncs.com → cn-hangzhou
2. 检查实例是否存在：

   tablestore_cli list_instance -r <region_id>
   

   如果返回的列表中包含该实例名称，则跳过创建步骤。
3. 如果未找到实例，则创建实例：

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

4. 验证创建结果：

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

   确认 "Status": 1（已激活）后再继续。

注意：

• 如果需要配置 User Agent，请直接设置环境变量：export OTS_USER_AGENT=AlibabaCloud-Agent-Skills。不要将 User Agent 保存到配置文件中。
• ots_endpoint 的格式必须为 http://ots-<region-id>.aliyuncs.com，而不是 https://<instance-name>.<region-id>.ots.aliyuncs.com。

步骤 3：确认知识库目标

仅询问：

• 创建新的知识库，还是使用现有知识库？
• 知识库名称是什么？

如果用户想要创建新的知识库，可选择询问描述。

步骤 4：保存配置

• 将当前配置保存到 tablestore_agent_storage/ots_kb_config.json。
• 推荐格式：

{
  "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": []
}

步骤 5：执行基本知识库操作

根据用户需求执行：

• 创建知识库：create_knowledge_base
• 列出知识库：list_knowledge_base
• 查看详情：describe_knowledge_base

步骤 6：主动建议关联本地目录

完成基本功能后，主动询问用户是否需要：

1. 上传本地文件
2. 关联本地目录并自动同步

只有在用户确认后，才继续询问 OSS 和同步配置。

步骤 7：需要本地文件功能时收集 OSS 配置

仅询问：

• oss_endpoint
• oss_bucket_name

授予 AliyunOTSAccessingOSSRole

使用与 OSS 相关的功能前，必须创建并授权 AliyunOTSAccessingOSSRole 服务关联角色。此角色允许 Tablestore 代表用户访问 OSS。此操作只需执行一次。如果该角色已获授权，则可以跳过此授权步骤。

引导用户通过以下链接完成授权。详情请参阅 references/ram-policies.md。

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

注意：

• access_key_id、access_key_secret 和 sts_token 可以重复使用
• 仅在上传本地文件或同步目录时才需要 OSS 配置
• OSS 必须与 OTS 位于同一地域

步骤 8：需要同步时收集目录关联信息

首先询问：

• local_path
• oss_sync_path

然后询问：

• sync_interval_minutes（默认值：5）
• inclusion_filters（默认值：["*.pdf", "*.docx", "*.txt", "*.md", "*.html"]）

步骤 9：创建同步脚本

如果用户确认关联本地目录，则创建： tablestore_agent_storage/sync_knowledge_base.py

脚本必须：

1. 读取配置文件
2. 将本地文件增量上传到 OSS
3. 调用 add_documents 导入知识库
4. 使用 .sync_cache.json 进行增量缓存
5. 输出必要的日志

步骤 10：配置计划任务

如果使用 OpenClaw，优先使用 OpenClaw Cron，例如：

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"

如果无法使用 OpenClaw，则改用系统 Crontab。

---

常见 SDK 操作

初始化客户端

仅 OTS（无需上传本地文件时）：

import json
from tablestore_agent_storage import AgentStorageClient

config = json.load(open("tablestore_agent_storage/ots_kb_config.json", "r"))
client = AgentStorageClient(
    access_key_id=config["access_key_id"],
    access_key_secret=config["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）：

client = AgentStorageClient(
    access_key_id=config["access_key_id"],
    access_key_secret=config["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"]
)

关于 Subspace

subspace 是知识库中的逻辑分区，用于隔离不同来源或类别的文档。

• 创建知识库时设置 "subspace": true，即可启用 subspace 功能
• 对于文档操作（添加/上传/获取/列出），subspace 是一个字符串，用于指定要操作的 subspace
• 对于检索，subspace 是一个字符串列表，可同时在多个 subspace 中搜索
• 未指定 subspace 时，将使用 _default subspace

创建知识库

基本创建：

client.create_knowledge_base({
    "knowledgeBaseName": "my_kb",
    "description": "My knowledge base"
})

使用 subspace 和自定义元数据字段：

创建知识库时，可以通过 metadata 参数定义元数据字段，支持 MetadataField、MetadataFieldType、EmbeddingConfiguration 等模型。

详细用法请参见 references/metadata.md。

快速示例：

client.create_knowledge_base({
    "knowledgeBaseName": "my_kb",
    "subspace": True,
    "metadata": [
        {"name": "author", "type": "string"},
        {"name": "version", "type": "long"}
    ]
})

列出知识库

# 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"})

将本地文件上传到知识库（需要 OSS 配置）

# 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}}
    ]
})

从 OSS 路径导入文档到知识库

# 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 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"
})

文档状态：

• pending — 处理中
• completed — 已完成
• failed — 处理失败

列出文档

# 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
})

检索知识

混合检索（推荐，DENSE_VECTOR + FULL_TEXT）：

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
            }
        }
    }
})

仅向量检索：

client.retrieve({
    "knowledgeBaseName": "my_kb",
    "retrievalQuery": {"text": "your question", "type": "TEXT"},
    "retrievalConfiguration": {
        "searchType": ["DENSE_VECTOR"],
        "denseVectorSearchConfiguration": {"numberOfResults": 10}
    }
})

使用元数据过滤进行检索： 检索时，可以通过 filter 参数传入 MetadataFilter 对象，进行基于元数据的过滤。它支持 13 种运算符，包括等于、范围比较、列表包含、AND/OR 组合等。详细用法请参见 references/metadata.md。

---

您的问题模板

请按此顺序提问——不要跳过步骤，也不要一次提出太多问题。

模板 1：环境检查

请先检查您的基本环境。请确认：

1. 您当前的环境是否已安装 Python 3.8 或更高版本？ 2. 我可以安装 tablestore-agent-storage 吗？

模板 2：凭证信息

凭证需要以下三项信息：

1. access_key_id 2. access_key_secret 3. sts_token（可选）

注意：您可以询问用户如何获取凭证（例如，凭证配置文件的位置），但绝不能直接显示凭证，也不能要求用户提供明文 AK/SK。

模板 3：OTS 信息

还需要另外两项 OTS 配置：

1. ots_endpoint 2. ots_instance_name

注意：ots_endpoint 的格式必须为 http://ots-<region-id>.aliyuncs.com，而不是 https://<instance-name>.<region-id>.ots.aliyuncs.com。

模板 4：知识库目标

请确认：

1. 您想创建新的知识库，还是使用现有知识库？
2. 知识库的名称是什么？

模板 5：是否需要本地文件功能？

完成基本配置后，您还需要：

1. 上传本地文件
2. 关联本地目录并自动同步

模板 6：OSS 配置

如果您需要上传本地文件或自动同步，请提供：

1. oss_endpoint 2. oss_bucket_name

模板 7：目录关联与同步策略

请提供目录同步信息：

1. 本地目录路径 local_path 2. OSS 同步路径前缀 oss_sync_path
2. 同步间隔（分钟，默认值：5） 4. 文件类型筛选器（默认值：*.pdf, *.docx, *.txt, *.md, *.html）

---

绝对不能做的事

• 绝不向用户索要明文 AK/SK，也绝不通过 echo、print 或日志泄露凭据。所有密钥都必须仅通过后端代码处理。
• 不要一次性索取所有配置
• 不要输出旧版本兼容性说明
• 默认不要列出过长的文件类型列表
• 不要将配置文件放在项目根目录中
• 不要优先推荐守护进程
• 在用户确认需要同步之前，不要索取 OSS 和目录配置
• 不要执行任何删除操作（包括但不限于 delete_documents、delete_knowledge_base、delete_instance 或任何其他删除／移除／销毁操作）——严格禁止所有删除操作，即使用户明确提出要求也不例外