通过 tablestore-agent-cli 和 Agent Skill 接入知识存储服务 - 表格存储

前提条件

已开通表格存储服务并创建实例。支持地域详见快速开始。
已完成 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 和表格存储实例信息。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 配置和表格存储实例连接，无需额外操作。

使用示例

配置完成后，在对话中以自然语言操作知识库：

帮我创建一个叫 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 后再执行检索。

表格存储：通过 CLI 和 Skill 接入