全部产品
Search

搜索本产品

    表格存储：命令行工具

    文档中心

    表格存储：命令行工具

    更新时间：Jul 02, 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'

    可选配置

    根据使用场景按需配置以下信息。

    表格存储实例

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

    如果不配置表格存储实例，命令行工具会在北京地域自动创建一个托管实例，并使用公网域名访问。自动创建过程可能持续 30 秒。如需指定地域，请配置 region：

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

    OSS 对象存储 Bucket

    仅知识库的上传文档功能需要配置 OSS Bucket。

    说明

    知识库需要读写 OSS Bucket 的权限，通过以下链接一键授权：授权表格存储读写 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

    适用于在生产、预发、测试等多环境之间快速切换的场景。