alibabacloud-tablestore-agent-storage：用于表格存储知识库的管理和文档的读写操作

Tablestore 知识库 Agent Skill

你负责帮助用户使用 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 调用的超时（默认 30 秒）。

6. 写操作必须幂等

Agent 可能因超时、网络抖动等重试。所有写操作必须幂等以安全支持重试。所有当前 Tablestore 知识库写 API 都是幂等的——无需额外幂等策略。

7. 所有删除操作严格禁止

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

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

即使用户明确要求删除操作，Agent 也必须拒绝并解释本 Skill 不支持删除操作。如果绝对必要，建议用户通过 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

1. 如果使用 pyenv 且安装挂起或超时：

   # 先尝试手动运行 pyenv rehash（~/.pyenv/shims/.pyenv-shim 可安全删除）
   rm -f ~/.pyenv/shims/.pyenv-shim && pyenv rehash
   
   # 然后重试 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

通过默认凭证链获取凭证

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

现在你可以将凭证保存到配置

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

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

详细实例操作见 [references/tablestore-instance.md](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": "", // 必须匹配：^http://ots-[a-zA-Z0-9\-]+.aliyuncs.com$

"ots_instance_name": "", // 必须匹配：^[a-zA-Z0-9-]+$

"oss_endpoint": "", // 必须匹配：^https?://[a-zA-Z0-9\-\.]+$

"oss_bucket_name": "", // 必须匹配：^[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](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 临时凭证，可选
    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"],        # 必须与 OTS 在同一地域
    oss_bucket_name=config["oss_bucket_name"],
    ots_endpoint=config["ots_endpoint"],
    ots_instance_name=config["ots_instance_name"]
)

关于子空间

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

• 创建知识库时设置 "subspace": true 以启用子空间功能
• 对于文档操作（添加/上传/获取/列出），subspace 是字符串，指定要操作哪个子空间
• 对于检索，subspace 是字符串列表，允许跨多个子空间同时搜索
• 未指定 subspace 时，使用 _default 子空间

创建知识库

基本创建：

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

带子空间 + 自定义元数据字段：

创建知识库时，可通过 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"}
    ]
})

列出知识库

列出所有知识库（支持分页）

client.list_knowledge_base({"maxResults": 20, "nextToken": ""})

查看单个知识库详情

client.describe_knowledge_base({"knowledgeBaseName": "my_kb"})

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

上传单个文件到默认子空间

client.upload_documents({

"knowledgeBaseName": "my_kb",

"documents": [

{"filePath": "/path/to/file.pdf"},

{"filePath": "/path/to/doc.docx", "metadata": {"author": "aliyun"}}

]

})

上传到特定子空间

client.upload_documents({

"knowledgeBaseName": "my_kb",

"subspace": "finance",

"documents": [

{"filePath": "/path/to/report.pdf", "metadata": {"version": 2}}

]

})

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

导入单个文件

client.add_documents({

"knowledgeBaseName": "my_kb",

"documents": [

{"ossKey": "oss://your-bucket/docs/file.pdf"}

]

})

导入 OSS 目录（支持文件类型过滤）

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

}

]

})

### 查询文档状态

按 docId 查询

client.get_document({

"knowledgeBaseName": "my_kb",

"docId": "your_doc_id"

})

按 ossKey 查询

client.get_document({

"knowledgeBaseName": "my_kb",

"ossKey": "oss://your-bucket/docs/file.pdf",

"subspace": "tech_docs"

})

文档状态：
- `pending` —— 处理中
- `completed` —— 已完成
- `failed` —— 处理失败

### 列出文档

列出知识库中所有文档（支持分页）

client.list_documents({

"knowledgeBaseName": "my_kb",

"maxResults": 20,

"nextToken": ""

})

列出特定子空间中的文档

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 种操作符，包括 equals、范围比较、列表包含、AND/OR 组合等。详细用法见 [references/metadata.md](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
3. 同步间隔（分钟，默认：5） 4. 文件类型过滤（默认：*.pdf, *.docx, *.txt, *.md, *.html）

你绝不能做的事

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

文档 7 / 7：alibabacloud-ddos-security-monitor