通過 tablestore-agent-cli 和 Agent Skill 接入知識儲存服務 - Tablestore

前提條件

已開通Table Store服務並建立執行個體。支援地區詳見快速開始。
已完成 OSS 授權（讀寫 OSS Bucket 許可權）。
已準備 AccessKey ID 和 AccessKey Secret。

CLI 與 Skill 概述

tablestore-agent-cli 是知識庫的命令列管理工具，所有命令預設輸出結構化 JSON，Agent 可直接解析。tablestore-agent-knowledge 是配套的 Agent Skill 包，Agent 學習後可根據自然語言指令調用 CLI 完成知識庫操作。

全域參數	說明
`-q`	去除響應外層信封（`code` / `message` / `requestId`），只返回業務資料，節省 Token 開銷。
`-y`	跳過確認提示，適用於指令碼和 CI 情境。
`--instance`	指定操作的執行個體名稱。未指定時使用 `default` 執行個體。
`--timeout`	設定命令逾時時間，預設 30 秒。

安裝與配置

安裝 CLI

CLI 基於 Node.js 18 或更高版本運行。執行以下命令安裝：

npm install -g @tablestore/tablestore-agent-cli --registry=https://registry.npmjs.org/

驗證安裝結果：

tablestore-agent-cli --version

配置憑證

只需手動設定 Region、AccessKey 和Table Store執行個體資訊。OSS Endpoint 和 Bucket 無需手動設定，首次執行 OSS 操作時 CLI 按 Region 自動派生預設值。

tablestore-agent-cli configure set region cn-hangzhou
tablestore-agent-cli configure set access_key_id <AccessKey ID>
tablestore-agent-cli configure set access_key_secret <AccessKey Secret>
tablestore-agent-cli configure set ots_endpoint https://<執行個體名>.cn-hangzhou.ots.aliyuncs.com
tablestore-agent-cli configure set ots_instance_name <執行個體名>

配置完成後，執行連通性診斷：

tablestore-agent-cli doctor

所有項 status=pass 表示配置可用。

Dashboard 可視化調試

CLI 內建可視化 Dashboard，一條命令啟動：

tablestore-agent-cli dashboard start

Dashboard 涵蓋知識庫和記憶庫的管理和調試，核心能力包括：

調整檢索參數和索引配置（searchType、TopK、Rerank 策略等）。
驗證端到端檢索效果。
掛載和切換多個知識庫進行對比測試。
與 LLM 直接對話，觀察檢索結果注入後的實際問答表現。

接入 Agent 架構

任何支援 Skill 或命令列調用的 Agent（如 OpenClaw、Hermes、QoderWork、CherryStudio、Claude Code）均可通過同一個 Skill 包和同一套憑證接入知識庫。接入方式統一為：

安裝 Skill（讓 Agent 學習技能包 URL）。
配置憑證（手動執行 configure set 或通過 Token 匯入）。
以自然語言操作知識庫。

安裝 Skill

在 Agent 對話中輸入以下指令，Agent 自動學習 Skill 並完成 CLI 安裝：

請學習 https://tablestore-doc.oss-cn-hangzhou.aliyuncs.com/aliyun-tablestore-ai/agent-storage/tablestore-agent-knowledge.zip 這個技能，並完成 CLI 的安裝。

配置

建議手動執行 configure set 命令配置 AccessKey，避免敏感憑證在 Agent 對話中明文流轉。Region 和執行個體資訊可由 Agent 協助填寫。

配置好 Region、AccessKey ID 和 AccessKey Secret 後，CLI 在首次使用時自動完成 OSS Bucket 配置和Table Store執行個體串連，無需額外操作。

使用樣本

配置完成後，在對話中以自然語言操作知識庫：

幫我建立一個叫 project_wiki 的知識庫，把 ./docs 目錄下的文檔上傳進去。
在 project_wiki 中檢索一下關於部署流程的內容。

Agent 將自然語言指令轉化為 CLI 命令執行，涵蓋知識庫管理員、文件管理、切片管理和檢索等操作。

跨裝置共用知識庫

源端配置完成後，匯出 Token 並在目標端匯入，即可讓多端訪問同一份知識庫。

匯出 Token

在源端執行 tablestore-agent-cli configure export 命令匯出：

tablestore-agent-cli configure export

輸出格式如下：

instance=<instance-name> token=tablestore_agent_storage://eyJ2IjoyLC...

匯入 Token

在目標端執行以下命令匯入：

tablestore-agent-cli configure import --name <instance-name> <token>

匯入完成後，通過 --instance 全域參數訪問該執行個體的知識庫：

tablestore-agent-cli --instance <instance-name> -q kb retrieve --kb product_docs --query "部署流程"

也可以直接將 Token 發送給目標 Agent，讓 Agent 執行匯入：

我的 Token 是 tablestore_agent_storage://eyJ2IjoyLC...，請幫我匯入知識庫配置。

注意事項

避免在 Agent 對話中傳遞明文憑證，AccessKey 應通過 configure set 命令直接配置。
Token 中編碼了 AccessKey 等憑證資訊，應通過安全渠道傳遞（如密碼管理工具），不要在公開渠道泄露。configure export 匯出的 Token 包含完整憑證。
執行個體名僅支援字母、數字和連字號，不支援底線或其他符號。
文檔上傳後由系統非同步完成解析和向量化。通過 kb doc-list 查看文檔狀態，等待 status 變為 completed 後再執行檢索。

Tablestore：通過 CLI 和 Skill 接入