seekdb — 具备文档功能的AI智能体数据库命令行工具

此功能使AI智能体能够操作seekdb通过seekdb-cli命令并在需要时查阅seekdb文档快速入门指引

：请从seekdb ai-guide开始，以获取完整的命令行工具JSON自述文件。随后可直接运行命令——无需额外设置。第一部分：seekdb-cli 操作指南

---

seekdb-cli

专为AI智能体打造。所有输出均为结构化JSON格式，所有操作均为无状态执行，且内置安全防护机制可防止意外数据丢失。seekdb 部署方案

seekdb支持两种运行模式。请根据用户的操作系统和使用场景，参考本部分内容选择正确的部署路径。

嵌入式模式

seekdb作为库内嵌于应用程序中运行——

无需独立服务器进程no server process required. 通过安装pyseekdb:

pip install -U pyseekdb

支持平台: Linux (glibc ≥ 2.28), macOS 15+ ·架构: x86_64, aarch64

Windows 和旧版 macOS不支持嵌入式模式。请改用服务器模式。

服务器模式

一个持久的 seekdb 进程，可通过 MySQL 客户端或 seekdb-cli（远程 DSN）连接。按操作系统选择：

操作系统	推荐方法	快速开始
Linux (CentOS/RHEL/Anolis/openEuler)	包管理器 (RPM)	curl -fsSL https://obportal.s3.ap-southeast-1.amazonaws.com/download-center/opensource/seekdb/seekdb_install.sh | sudo bash
Linux (Debian/Ubuntu)	包管理器 (DEB)	sudo apt update && sudo apt install seekdb
macOS 15+	Homebrew	brew tap oceanbase/seekdb && brew install seekdb
任何支持 Docker 的操作系统	Docker	docker run -d -p 2881:2881 oceanbase/seekdb
Windows / macOS (图形界面)	OceanBase Desktop	从以下地址下载oceanbase.ai/download

在服务器模式部署后连接（默认端口 2881，用户root，密码为空）：

mysql -h127.0.0.1 -uroot -P2881 -A -Dtest
# or via seekdb-cli:
seekdb --dsn "seekdb://root:@127.0.0.1:2881/test" status

最低要求：1 个 CPU 核心，2 GB 内存，SSD 存储。

有关完整部署详情，请参阅部署文档。

先决条件

检查是否已安装 seekdb-cli：

seekdb --version

如果未安装，请选择与您环境匹配的方法：

推荐使用 — pipx（全局工作，不会污染系统 Python 环境）：

# Install pipx first if needed (Ubuntu/Debian)
sudo apt install pipx && pipx ensurepath
# Then install seekdb-cli
pipx install seekdb-cli

替代方案 — pip（当处于项目虚拟环境或在没有PEP 668的系统上时）：

pip install seekdb-cli

适用于 Ubuntu 23.04+ / Debian 12+ 的注意事项：直接使用pip install在系统级别安装已被PEP 668阻止。 请改用pipx——它会创建一个隔离的环境，同时保持seekdb命令在您的PATH中全局可用。

连接

seekdb-cli 会自动发现连接（环境变量、.env文件、~/.seekdb/config.env文件，或默认的~/.seekdb/seekdb.db文件）。无需设置——直接运行命令即可。

如果用户提供了特定的DSN，请通过--dsn参数传递（该参数必须位于子命令之前）：

# Remote mode
seekdb --dsn "seekdb://user:pass@host:port/db" schema tables

# Embedded mode (local database file)
seekdb --dsn "embedded:./seekdb.db" status
seekdb --dsn "embedded:~/.seekdb/seekdb.db?database=mydb" sql "SELECT 1"

DSN 格式：

• 远程： seekdb://user:pass@host:port/db
• 嵌入式： embedded:<路径>[?database=<数据库名>]（默认数据库：test）

获取完整 CLI 指南（首先运行此命令）

seekdb ai-guide

返回一个结构化的 JSON 文档，包含每个命令、参数、工作流程、安全规则和输出格式。在任何 seekdb 任务开始时运行此命令一次以熟悉环境。

推荐工作流程

SQL 数据库探索

1. seekdb schema tables              → list all tables (name, column count, row count)
2. seekdb schema describe <table>    → get column names, types, indexes, comments
3. seekdb table profile <table>      → data statistics (null ratios, distinct, min/max, top values)
4. seekdb relations infer            → infer JOIN relationships between tables
5. seekdb sql "SELECT ... LIMIT N"   → execute SQL with explicit LIMIT

向量集合工作流程

1. seekdb collection list            → list all collections
2. seekdb collection info <name>     → collection details and document preview
3. seekdb query <collection> --text "..." → hybrid search (default: semantic + fulltext)
4. seekdb add <collection> --data '...'  → add new documents

AI 模型设置工作流程

1. seekdb ai model list                                    → check registered models
2. seekdb ai model create <name> --type <type> --model <model_name>
3. seekdb ai model endpoint create <ep> <model> --url <url> --access-key <key>
4. seekdb ai complete "<prompt>" --model <name>           → test completion

命令参考

seekdb sql

执行 SQL 语句。默认为只读模式。

# Read query
seekdb sql "SELECT id, name FROM users LIMIT 10"

# Read from file
seekdb sql --file query.sql

# Read from stdin
echo "SELECT 1" | seekdb sql --stdin

# Include table schema in output
seekdb sql "SELECT * FROM orders LIMIT 5" --with-schema

# Disable large-field truncation
seekdb sql "SELECT content FROM articles LIMIT 1" --no-truncate

# Write operation (requires --write flag)
seekdb sql --write "INSERT INTO users (name) VALUES ('Alice')"
seekdb sql --write "UPDATE users SET name = 'Bob' WHERE id = 1"
seekdb sql --write "DELETE FROM users WHERE id = 3"

输出格式：

{"ok": true, "columns": ["id", "name"], "rows": [{"id": 1, "name": "Alice"}], "affected": 0, "time_ms": 12}

seekdb schema tables

seekdb schema tables

{"ok": true, "data": [{"name": "users", "columns": 5, "rows": 1200}, {"name": "orders", "columns": 8, "rows": 50000}]}

seekdb schema describe

seekdb schema describe orders

{"ok": true, "data": {"table": "orders", "comment": "Order table", "columns": [{"name": "id", "type": "int", "comment": "Order ID"}, {"name": "status", "type": "varchar(20)", "comment": "0=pending, 1=paid"}], "indexes": ["PRIMARY(id)", "idx_status(status)"]}}

seekdb schema dump

seekdb schema dump

返回所有CREATE TABLEDDL语句。

seekdb table profile

生成表的统计摘要而不返回原始数据。有助于在编写SQL前了解数据分布。

seekdb table profile <table>

{"ok": true, "data": {
  "table": "orders",
  "row_count": 50000,
  "columns": [
    {"name": "id", "type": "int", "null_ratio": 0, "distinct": 50000, "min": 1, "max": 50000},
    {"name": "user_id", "type": "int", "null_ratio": 0, "distinct": 1200, "min": 1, "max": 1500},
    {"name": "amount", "type": "decimal(10,2)", "null_ratio": 0.02, "min": 0.5, "max": 9999.99},
    {"name": "status", "type": "varchar(20)", "null_ratio": 0, "distinct": 4, "top_values": ["paid", "pending", "refunded", "cancelled"]},
    {"name": "created_at", "type": "datetime", "null_ratio": 0, "min": "2024-01-01", "max": "2026-03-10"}
  ],
  "candidate_join_keys": ["user_id"],
  "candidate_time_columns": ["created_at"]
}}

seekdb relations infer

通过分析列名模式（例如，user_id→users.id）和类型兼容性来推断表之间的JOIN关系。

# Infer all table relationships
seekdb relations infer

# Infer for a specific table only
seekdb relations infer --table orders

{"ok": true, "data": [
  {"from": "orders.user_id", "to": "users.id", "confidence": "high"},
  {"from": "orders.product_id", "to": "products.id", "confidence": "high"},
  {"from": "order_items.order_id", "to": "orders.id", "confidence": "high"}
]}

seekdb collection list

seekdb collection list

{"ok": true, "data": [{"name": "docs", "count": 1500}, {"name": "faq", "count": 200}]}

seekdb collection create

seekdb collection create my_docs --dimension 384 --distance cosine
seekdb collection create my_docs -d 768 --distance l2

选项：--dimension/-d（默认值：384），--distancecosine | l2 | ip （默认：cosine）。

seekdb collection delete

seekdb collection delete my_docs

seekdb collection info

seekdb collection info my_docs

{"ok": true, "data": {"name": "my_docs", "count": 1500, "dimension": 384, "distance": "cosine", "preview": {"ids": ["doc1", "doc2"], "documents": ["Hello world", "Test doc"], "metadatas": [{"category": "test"}, {}]}}}

维度和距离在集合元数据可用时会被包含。

seekdb query

使用混合（默认）、语义（向量）或全文模式搜索集合。

# Hybrid search (default: semantic + fulltext, RRF ranking)
seekdb query my_docs --text "how to deploy seekdb"

# Semantic (vector) only
seekdb query my_docs --text "how to deploy seekdb" --mode semantic

# Fulltext search
seekdb query my_docs --text "deployment guide" --mode fulltext

# With metadata filter
seekdb query my_docs --text "performance tuning" --where '{"category": "tech"}'

# Limit results (--limit or -n, default: 10)
seekdb query my_docs --text "seekdb" -n 5

{"ok": true, "data": {"results": [
  {"id": "doc1", "score": 0.92, "document": "How to deploy seekdb...", "metadata": {"category": "tech"}},
  {"id": "doc2", "score": 0.85, "document": "seekdb performance tuning...", "metadata": {"category": "tech"}}
], "count": 2}, "time_ms": 35}

seekdb get

通过ID或元数据过滤器从集合中检索文档。

# Get by IDs
seekdb get my_docs --ids "doc1,doc2"

# Get by metadata filter (--limit or -n, default: 10)
seekdb get my_docs --where '{"category": "tech"}' -n 20

seekdb add

向集合添加数据。必须且仅能指定一个数据源：--file、--stdin或--data。若集合不存在将自动创建。

# From file (JSON array, JSONL, or CSV)
seekdb add my_docs --file data.jsonl
seekdb add my_docs --file articles.csv --vectorize-column content

# Inline: single object or array
seekdb add my_docs --data '{"id":"1","document":"Hello world","metadata":{"source":"cli"}}'
seekdb add my_docs --data '[{"id":"a","document":"Doc A"},{"id":"b","document":"Doc B"}]'

# From stdin (JSON array or JSONL; use with pipes)
echo '{"id":"1","document":"from pipe"}' | seekdb add my_docs --stdin
some_script | seekdb add my_docs --stdin

记录格式：每条记录可包含id（可选）、document/text/内容（待向量化的文本），其他所有字段则变为元数据。如果嵌入向量存在，则直接使用。

seekdb export

将集合数据导出到文件。

seekdb export my_docs --output backup.json
seekdb export my_docs --output backup.jsonl -n 5000

选项：--output（必填），--limit/-n（默认值：10000）。

seekdb ai model list

列出数据库中注册的AI模型（来自DBA_OB_AI_MODELS/ DBMS_AI_SERVICE）。在远程和嵌入式模式下均可工作。

seekdb ai model list

{"ok": true, "data": [{"name": "my_llm", "type": "completion", "model_name": "THUDM/GLM-4-9B-0414", "model_id": 1}]}

seekdb ai model create

通过DBMS_AI_SERVICE.CREATE_AI_MODEL注册一个AI模型。需单独创建端点以将其用于补全。

seekdb ai model create my_llm --type completion --model "THUDM/GLM-4-9B-0414"
seekdb ai model create my_embed --type dense_embedding --model "BAAI/bge-m3"
seekdb ai model create my_rerank --type rerank --model "<rerank_model>"

类型：补全dense_embeddingrerankseekdb ai model delete删除一个AI模型。请先删除任何使用该模型的端点。seekdb ai model endpoint create / delete

创建或删除一个端点，该端点将AI模型绑定到URL和API密钥（以便数据库可以调用该模型）。

支持的

seekdb ai model delete my_llm

--provider

值：

seekdb ai model endpoint create my_ep my_llm \
  --url "https://api.siliconflow.cn/v1/chat/completions" \
  --access-key "<YOUR_API_KEY>" \
  --provider siliconflow

seekdb ai model endpoint delete my_ep

提供商供应商siliconflow

SiliconFlow（与OpenAI兼容）	openAI
OpenAI	deepseek
DeepSeek（与OpenAI兼容）	aliyun-openAI
阿里云（与OpenAI兼容）	aliyun-dashscope
阿里云灵积（DashScope）	Alibaba Cloud (OpenAI-compatible)
aliyun-dashscope	Alibaba Cloud DashScope
混元-openAI	腾讯混元（兼容OpenAI）

通用--url值（请使用具体的接口URL，而非基础URL）：

供应商	补全	嵌入	重排
SiliconFlow	https://api.siliconflow.cn/v1/chat/completions	https://api.siliconflow.cn/v1/embeddings	https://api.siliconflow.cn/v1/rerank
DeepSeek	https://api.deepseek.com/chat/completions	—	—
阿里巴巴（OpenAI兼容）	https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings	—
腾讯混元	https://api.hunyuan.cloud.tencent.com/v1/chat/completions	https://api.hunyuan.cloud.tencent.com/v1/embeddings	—

seekdb ai complete

使用数据库运行文本补全AI_COMPLETE函数。需要已注册的补全模型和端点。在远程和嵌入式模式下均受支持。

seekdb ai complete "Summarize this table structure" --model my_llm

{"ok": true, "data": {"model": "my_llm", "response": "The table has..."}, "time_ms": 1200}

seekdb ai-guide

输出一个包含所有命令、参数、工作流程和安全规则的结构化JSON指南，供AI智能体使用。执行一次即可了解完整的CLI。

seekdb ai-guide

seekdb status

seekdb status

返回CLI版本、服务器版本、数据库名称和连接状态。

安全特性

行保护

不带LIMIT的查询会自动被探测。如果结果超过100行，执行将被阻止：

{"ok": false, "error": {"code": "LIMIT_REQUIRED", "message": "Query returns more than 100 rows. Please add LIMIT to your SQL."}}

操作：添加一个明确的LIMIT子句并重试。

写入保护

写入操作（INSERT/UPDATE/DELETE）默认被阻止：

{"ok": false, "error": {"code": "WRITE_NOT_ALLOWED", "message": "Write operations require --write flag."}}

操作：添加--write标志以启用写入操作。

即使使用--write标志，以下操作也始终被阻止：

• 不带WHERE子句的DELETE/UPDATE
• DROP/TRUNCATE语句

错误自动纠正

当发生SQL错误时，CLI会自动附加架构提示：

未找到列→ 返回表的列列表和索引：

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Unknown column 'username'"}, "schema": {"table": "users", "columns": ["id", "name", "email"], "indexes": ["PRIMARY(id)"]}}

未找到表→ 返回可用的表名：

{"ok": false, "error": {"code": "SQL_ERROR", "message": "Table 'user' does not exist"}, "schema": {"tables": ["users", "orders", "products"]}}

操作：使用架构信息修正SQL并重试。

大字段截断

TEXT/BLOB类型字段默认截断至200字符，并标注原始长度：

{"content": "First 200 characters of content...(truncated, 8520 chars)"}

使用--no-truncate参数在需要时获取完整内容。

敏感字段脱敏

匹配敏感模式的列将自动脱敏：

匹配模式	输出示例
phone/mobile/tel	138****5678
email	z***@gmail.com
password/secret/token	******
id_card/ssn	110***********1234

输出格式

默认为JSON格式。可通过--format或-f现在所有格式都支持非行数据（例如，

seekdb -f table sql "SELECT id, name FROM users LIMIT 5"
seekdb --format csv sql "SELECT id, name FROM users LIMIT 5"
seekdb -f jsonl sql "SELECT id, name FROM users LIMIT 5"

架构表、集合列表）。CSV和JSONL格式将自动检测数据字段中的字典列表数据。退出代码

代码

含义	0
成功	1
业务错误（SQL错误、连接错误等）	2
用法错误（缺少参数、无效选项）	操作日志记录

所有命令都会记录到

~/.seekdb/sql-history.jsonl（seekdb-cli SQL执行历史记录）以供审计：第二部分：文档查阅

{"ts": "2026-03-12T14:23:01", "command": "sql", "sql": "SELECT id FROM users LIMIT 10", "ok": true, "rows": 10, "time_ms": 12}

---

Part 2: Documentation Lookup

当您需要理解seekdb概念、查找SQL语法、寻找配置细节或回答用户关于seekdb的问题时，请使用文档查找功能。

提示：对于实时数据库状态（表、模式、数据），请直接运行CLI命令。对于概念、语法和操作指南，请搜索文档。

何时使用文档查找

• 需要理解seekdb概念（向量搜索、混合搜索、HNSW索引等）
• 需要SQL或PL语法参考，且无法通过seekdb模式命令
• 来回答
• 需要部署、配置或集成指导

CLI返回错误，您需要从文档中理解原因

1. 路径解析阅读此SKILL.md文件以获取其绝对路径，并将父目录提取为
2. <skill_dir>目录：<skill_dir>references/seekdb-docs-catalog.jsonl如果本地缺失，请从以下地址加载：

文档工作流程

步骤1：搜索目录

在目录文件中搜索包含查询关键词的行。每一行都是一个JSON对象，包含路径、描述和分支字段。

# Example: search for "vector search" in the catalog
grep -i "vector search" <skill_dir>references/seekdb-docs-catalog.jsonl

步骤2：匹配查询

• 从搜索结果中提取路径、描述和分支信息
• 选择在语义上与查询最匹配的描述所对应的条目
• 考虑多个匹配项以提供全面的答案

步骤3：获取文档

从公共文档URL获取文档：

• URL：https://raw.githubusercontent.com/oceanbase/seekdb-doc/[branch]/en-US/[path]
• [branch]和[path]来源于目录条目（例如，V1.0.0、V1.1.0）

示例

Query: "How to integrate with Claude Code?"

1. Search catalog for "claude code"
2. Found: {"path": "300.integrations/300.developer-tools/700.claude-code.md",
           "description": "This guide explains how to use the seekdb plugin with Claude Code...",
           "branch": "V1.0.0"}
3. Fetch: https://raw.githubusercontent.com/oceanbase/seekdb-doc/V1.0.0/en-US/300.integrations/300.developer-tools/700.claude-code.md

更多工作流示例，请参阅references/doc-examples.md。

---

如果您在目录或CLI输出中找不到所需信息，请访问官方seekdb文档：oceanbase.ai/docs，以获取最完整和最新的参考信息。

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。