alibabacloud-tablestore-agent-storage

Tablestore ナレッジベースエージェントスキル

tablestore-agent-storage Python SDK を使用して、ユーザーによる Tablestore ナレッジベースの構築と管理を支援します。

目標

以下のタスクを完了します。

1. 環境を確認し、SDK をインストールする
2. 設定を段階的に収集し、設定ファイルに保存する
3. ナレッジベースを作成または接続する
4. ドキュメントのアップロード、インポート、取得をサポートする
5. 「ナレッジベースにリンクしたローカルディレクトリ」というベストプラクティスを積極的に推奨する
6. ユーザーが必要とする場合は、同期スクリプトを作成し、定期同期を設定する

---

必ず守るルール

1. 一度に尋ねることは少数にする

質問は段階的に行い、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. 書き込み操作は冪等にする

タイムアウトやネットワークの揺らぎなどにより、エージェントが再試行する場合があります。再試行を安全にサポートできるよう、すべての書き込み操作は冪等でなければなりません。現在の Tablestore ナレッジベース書き込み API はすべて冪等であるため、追加の冪等性対策は必要ありません。

操作	冪等
create_knowledge_base	はい
upload_documents / add_documents	はい

7. すべての削除操作を厳禁する

いかなる削除操作もサポートされておらず、いかなる状況でも絶対に実行してはいけません。これには、以下が含まれますが、これらに限定されません。

• delete_documents — ナレッジベースからドキュメントを削除することは禁止されています。
• delete_knowledge_base — ナレッジベース全体を削除することは禁止されています。
• delete_instance — Tablestore インスタンスを削除することは禁止されています。
• Tablestore リソースに対して削除、除去、破棄を行うその他の API、SDK 呼び出し、CLI コマンド、スクリプト。

ユーザーから削除操作を明示的に要求された場合でも、エージェントは拒否し、このスキルでは削除操作がサポートされていないことを説明する必要があります。どうしても必要な場合は、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 オブジェクトを渡すと、メタデータに基づくフィルタリングを行えます。等価比較、範囲比較、リスト内の要素の包含、AND／OR の組み合わせなど、13 種類の演算子をサポートしています。詳しい使い方は、references/metadata.md を参照してください。

---

質問テンプレート

次の順序に従ってください。手順を飛ばさず、一度に質問しすぎないでください。

テンプレート 1：環境の確認

まず、基本的な環境を確認します。次の点を確認してください。

1. 現在の環境で Python 3.8 以降を利用できますか？ 2. tablestore-agent-storage をインストールしてもよいですか？

テンプレート 2：認証情報

認証情報には、次の 3 つが必要です。

1. access_key_id 2. access_key_secret 3. sts_token（任意）

注：認証情報の取得方法（たとえば、認証情報の設定ファイルの場所）をユーザーに尋ねてもかまいませんが、認証情報を直接表示したり、ユーザーに AK／SK の平文を尋ねたりしてはいけません。

テンプレート 3：OTS 情報

OTS の設定項目があと 2 つ必要です。

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 のほか、削除、除去、破棄にあたる操作を含みますが、これらに限定されません）。ユーザーが明示的に要求した場合でも、すべての削除操作は厳禁です。