Tablestore：CLI 使用介紹

配置訪問憑證

tablestore-agent-cli configure set access_key_id '...'
tablestore-agent-cli configure set access_key_secret '...'
tablestore-agent-cli configure set region 'cn-beijing'

配置Table Store執行個體

tablestore-agent-cli configure set ots_endpoint 'https://<instance>.cn-beijing.ots.aliyuncs.com'
tablestore-agent-cli configure set ots_instance_name '<instance-name>'

未配置 ots_endpoint 與 ots_instance_name 時，CLI 會在執行 doctor 或實際操作時自動建立並複用託管Table Store執行個體。

配置記憶服務預設值

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'

配置預設值後，後續命令可省略對應參數。

設定檔與環境變數

設定檔路徑：

~/.config/tablestore-agent-cli/config.toml

環境變數優先順序高於設定檔，對應關係如下：

建立記憶庫

tablestore-agent-cli memory create --store agent_memory --description "Agent 長期記憶庫"

記憶庫建立後會非同步初始化二級索引，需等待約 1 分鐘索引就緒後才能正常寫入和檢索。

列出記憶庫

tablestore-agent-cli memory list
tablestore-agent-cli memory ls --limit 50 --next-token <token>

ls 是 list 的別名。該命令單頁返回，如需翻頁繼續讀取，請使用響應中的 nextToken。

查看記憶庫

tablestore-agent-cli memory describe --store agent_memory
tablestore-agent-cli memory show --store agent_memory

show 是 describe 的別名。

更新記憶庫

tablestore-agent-cli memory update --store agent_memory --description "新的描述"

刪除記憶庫

tablestore-agent-cli memory delete --store agent_memory
tablestore-agent-cli memory rm --store agent_memory -y

rm 是 delete 的別名。TTY 環境下刪除會提示確認，傳入 -y 跳過確認。

寫入文本

通過 --text 直接傳入預加工的文本：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "使用者喜歡喝咖啡"

同步寫入

預設寫入為非同步模式，文本由服務端在後台抽取記憶。需要寫入完成後立即可檢索時使用 --sync：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "使用者偏好簡潔的回答風格" \
  --sync

通過訊息檔案寫入

通過 --messages-file 傳入對話訊息列表，檔案內容必須為 JSON 數組：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --messages-file ./messages.json

附加中繼資料

通過 --metadata 傳入 JSON 字串，附加業務自訂欄位：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --text "使用者喜歡川菜" \
  --metadata '{"source":"chat","topic":"preference"}'

列出記憶單元

tablestore-agent-cli memory list-units --store agent_memory --app-id app-001
tablestore-agent-cli memory ls-units --store agent_memory --app-id app-001 --limit 20 --next-token <token>

ls-units 是 list-units 的別名。

擷取單條記憶

tablestore-agent-cli memory get \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

cat 是 get 的別名。

更新單條記憶

tablestore-agent-cli memory update-unit \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "使用者偏好咖啡，且喜歡簡潔回答"

刪除單條記憶

tablestore-agent-cli memory delete-unit \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

rm-unit 是 delete-unit 的別名。

查詢短期記憶

tablestore-agent-cli memory msg-list \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

短期記憶查詢要求 Scope 四級（app-id、tenant-id、agent-id、run-id）全部填寫，不允許使用萬用字元 *。ls-msgs 是 msg-list 的別名。

查詢請求審計

按 --operation 過濾指定操作類型的請求審計記錄，Scope 中 tenant-id、agent-id、run-id 支援反引號包裹的萬用字元 *：

tablestore-agent-cli memory req-list \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id '*' \
  --agent-id '*' \
  --run-id '*' \
  --operation AddMemories

ls-reqs 是 req-list 的別名。