全部產品
Search

搜尋本產品

    Tablestore：命令列工具

    文件中心

    Tablestore：命令列工具

    更新時間：Jul 03, 2026

    tablestore-agent-cli 是知識和記憶儲存服務推出的命令列工具，支援知識庫（Knowledge Base）和記憶庫（Memory）管理和操作，適用於開發調試、營運和資料治理情境。

    快速接入

    下載安裝命令列工具並配置訪問憑證，即可開始操作知識庫與記憶庫資源。

    安裝

    命令列工具發布在 npm 倉庫，通過 npm 全域安裝。

    環境要求：Node.js 18 及以上版本。

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

    npm 包地址：https://www.npmjs.com/package/@tablestore/tablestore-agent-cli。

    Dashboard

    命令列工具內建基於 Next.js 的 Web Dashboard，提供配置功能以及知識庫與記憶庫的可視化管理和檢索調試介面。

    啟動 Dashboard

    tablestore-agent-cli dashboard start                     # 預設監聽 127.0.0.1:3000
tablestore-agent-cli dashboard start -p 9999             # 自訂連接埠
tablestore-agent-cli dashboard start --host 0.0.0.0      # 自訂綁定地址

    啟動後在瀏覽器訪問對應地址即可。

    記憶庫 Scope 選擇規則

    在 Dashboard 進入指定記憶庫後，預設 scope 為 */*/*/*，此情境僅支援列出所有長期記憶和請求審計操作。

    如需執行記憶檢索，必須指定 AppId 和 TenantId，AgentId 和 RunId 可指定具體值或使用萬用字元 *。

    如需新增記憶，必須指定完整的 scope（AppId、TenantId、AgentId、RunId 全部為具體值）。

    配置訪問憑證

    如果不使用Dashboard，可手工配置訪問憑證並驗證連通性。

    必要配置

    配置阿里雲帳號的 AccessKey ID 和 AccessKey Secret。AccessKey 的擷取方式請參見建立AccessKey。

    tablestore-agent-cli configure set access_key_id 'LTAI5t...'
tablestore-agent-cli configure set access_key_secret 'xxx'

    可選配置

    根據使用情境按需配置以下資訊。

    Table Store執行個體

    tablestore-agent-cli configure set ots_endpoint 'https://xxx.cn-beijing.ots.aliyuncs.com'
tablestore-agent-cli configure set ots_instance_name 'xxx'

    如果不配置Table Store執行個體，命令列工具會在北京地區自動建立一個受管理的執行個體，並使用公網網域名稱訪問。自動建立過程可能持續 30 秒。如需指定地區，請配置 region：

    tablestore-agent-cli configure set region 'cn-beijing'

    OSS Object Storage Service Bucket

    僅知識庫的上傳文檔功能需要配置 OSS Bucket。

    說明

    知識庫需要讀寫 OSS Bucket 的許可權，通過以下連結一鍵授權：授權Table Store讀寫 OSS。

    tablestore-agent-cli configure set oss_endpoint 'https://oss-cn-hangzhou.aliyuncs.com'
tablestore-agent-cli configure set oss_bucket_name 'my-bucket'

    記憶庫預設 scope

    tablestore-agent-cli configure set memory_store_name 'agent_memory'
tablestore-agent-cli configure set memory_app_id 'app-001'
tablestore-agent-cli configure set memory_tenant_id 'tenant-001'
tablestore-agent-cli configure set memory_agent_id 'agent-001'
tablestore-agent-cli configure set memory_run_id 'run-001'

    配置預設 scope 後，記憶庫相關命令可省略對應參數。

    驗證連通性

    執行 doctor 命令檢查配置和連通性。

    tablestore-agent-cli doctor          # 全量診斷
tablestore-agent-cli doctor kb       # 僅知識庫診斷
tablestore-agent-cli doctor memory   # 僅記憶庫診斷

    每項檢查結果為 pass / warn / fail / skip。全部通過時退出碼為 0，有任何 fail 時退出碼為 1。

    doctor 在需要時會自動建立並複用託管的 OTS 執行個體和 OSS Bucket。更多資訊，請參見受管理的執行個體自動建立。

    操作樣本

    完成安裝與配置後，可通過以下樣本快速體驗知識庫與記憶庫的核心能力。

    知識庫樣本：建立知識庫並上傳文檔

    # 建立知識庫
tablestore-agent-cli kb create --name my_kb --description "產品文檔知識庫"

# 添加本地文檔
tablestore-agent-cli kb doc-add --kb my_kb --file ./report.pdf

# 語義檢索
tablestore-agent-cli kb retrieve --kb my_kb --query "系統架構設計"

    記憶庫樣本：寫入並檢索記憶

    # 建立記憶庫
tablestore-agent-cli memory create --store agent_memory --description "長期記憶庫"

# 寫入一條記憶
tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "使用者喜歡麻婆豆腐"

# 檢索記憶
tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "使用者喜歡什麼食物" --top-k 5

    進階配置

    設定檔位置

    ~/.config/tablestore-agent-cli/config.toml。檔案許可權自動設為 0600。

    環境變數

    環境變數的優先順序高於設定檔。

    環境變數

    對應配置項

    TABLESTORE_ACCESS_KEY_ID

    access_key_id

    TABLESTORE_ACCESS_KEY_SECRET

    access_key_secret

    TABLESTORE_ENDPOINT

    ots_endpoint

    TABLESTORE_INSTANCE_NAME

    ots_instance_name

    TABLESTORE_OSS_ENDPOINT

    oss_endpoint

    TABLESTORE_OSS_BUCKET_NAME

    oss_bucket_name

    TABLESTORE_REGION

    region

    TABLESTORE_MEMORY_STORE_NAME

    memory_store_name

    TABLESTORE_MEMORY_APP_ID

    memory_app_id

    TABLESTORE_MEMORY_TENANT_ID

    memory_tenant_id

    TABLESTORE_MEMORY_AGENT_ID

    memory_agent_id

    TABLESTORE_MEMORY_RUN_ID

    memory_run_id

    受管理的執行個體自動建立

    如果未配置 ots_endpoint 和 ots_instance_name，命令列工具會在 doctor 或實際操作時自動建立並複用託管 OTS 執行個體，建立過程可能持續 30 秒。建立結果寫入設定檔的 [managed_ots] 段，後續命令直接複用。手動設定明確顯示目標後，託管快取會被自動清理。

    OSS Bucket 同理。在 doctor kb 或 kb doc-add 等上傳鏈路中按需自動建立，緩衝於設定檔的 [managed_oss] 段。

    多執行個體管理

    支援在同一份設定檔中儲存多個具名執行個體，通過命令列或 Dashboard 頂部切換器快速切換。

    # 為指定執行個體配置 AccessKey
tablestore-agent-cli configure set --instance prod access_key_id 'LTAI...'

# 切換當前啟用執行個體
tablestore-agent-cli configure use prod

# 查看當前配置
tablestore-agent-cli configure show

    適用於在生產、預發、測試等多環境之間快速切換的情境。