介绍
# seekdb Documentation
通过集中式目录系统提供对 seekdb 数据库文档的全面访问。
## 快速开始
1. **定位技能目录**（参见下方的路径解析） 2. **加载完整目录**（1015 个文档条目） 3. **语义匹配查询**到目录条目 4. **从匹配条目读取文档**
## 路径解析（关键的第一步）
**问题**：像 `./seekdb-docs/` 这样的相对路径是从**当前工作目录**解析的，而不是从 SKILL.md 的位置解析的。当代理的工作目录与技能目录不同时，这会导致错误。
**解决方案**：在访问文档之前动态定位技能目录。
### 分步解析
1. **读取 SKILL.md 本身**以获取其绝对路径： ``` read(SKILL.md) // or any known file in this skill directory ```
2. **从返回的路径中提取目录**： ``` If read returns: /root/test-claudecode-url/.cursor/skills/seekdb/SKILL.md Skill directory: /root/test-claudecode-url/.cursor/skills/seekdb/ ```
3. **使用此目录构建路径**： ``` Catalog path: <skill directory>references/seekdb-docs-catalog.jsonl Docs base: <skill directory>seekdb-docs/ ```
## 文档来源
### 完整目录 - **本地**：`<skill directory>references/seekdb-docs-catalog.jsonl`（1015 个条目，JSONL 格式） - **远程**：`https://raw.githubusercontent.com/oceanbase/seekdb-ecology-plugins/main/agent-skills/skills/seekdb/references/seekdb-docs-catalog.jsonl`（备用） - **条目数**：1015 个文档文件 - **覆盖范围**：完整的 seekdb 文档 - **格式**：JSONL - 每行一个 JSON 对象，包含路径和描述
### 完整文档（本地优先，远程备用）
**本地文档**（如果可用）： - **基础路径**：`<skill directory>seekdb-docs/` - **大小**：7.4M，952 个 markdown 文件 - **文档路径**：基础路径 + 文件路径
**远程文档**（备用）： - **基础 URL**：`https://raw.githubusercontent.com/oceanbase/seekdb-doc/V1.1.0/en-US/` - **文档 URL**：基础 URL + 文件路径
**策略**： 1. **定位**：使用上面的路径解析确定 `<skill directory>` 2. **加载**：加载完整目录（1015 个条目）- 优先尝试本地，失败则使用远程 3. **搜索**：对所有目录条目进行语义搜索 4. **读取**：优先尝试本地文档，缺失时回退到远程 URL
## 工作流程
### 步骤 0：解析路径（首先执行此操作！）
```bash # Read this file to discover its absolute path read("SKILL.md")
# Extract directory from the path # Example: /root/.claude/skills/seekdb/SKILL.md → /root/.claude/skills/seekdb/ ```
### 步骤 1：搜索目录
首先使用 grep 进行关键字搜索。仅在必要时加载完整目录。
#### 方法 1：Grep 搜索（适用于 90% 的查询）
使用 grep 在目录中搜索关键字： ```bash grep -i "keyword" <skill directory>references/seekdb-docs-catalog.jsonl ```
**示例**： ```bash # Find macOS deployment docs grep -i "mac" references/seekdb-docs-catalog.jsonl
# Find Docker deployment docs grep -i "docker\|container" references/seekdb-docs-catalog.jsonl
# Find vector search docs grep -i "vector" references/seekdb-docs-catalog.jsonl ```
#### 方法 2：加载完整目录（仅在必要时）
仅在以下情况加载完整目录： - Grep 未返回结果 - 需要复杂的语义匹配 - 没有特定的关键字可搜索
``` Local: <skill directory>references/seekdb-docs-catalog.jsonl Remote: https://raw.githubusercontent.com/oceanbase/seekdb-ecology-plugins/main/agent-skills/skills/seekdb/references/seekdb-docs-catalog.jsonl (fallback) Format: JSONL (one JSON object per line) Entries: 1015 documentation files ```
**策略**： 1. 优先尝试本地目录：`<skill directory>references/seekdb-docs-catalog.jsonl` 2. 如果本地缺失，则从上述远程 URL 获取
**目录内容**： - 每行：{"path": "...", "description": "..."} - 所有 seekdb 文档均已建立索引 - 针对语义搜索和 grep 查询进行了优化
### 步骤 2：匹配查询
分析搜索结果以识别最相关的文档：
**对于 grep 结果**： - 查看来自 grep 输出的匹配行 - 从每个匹配项中提取 `path` 和 `description` - 选择其描述最符合查询的文档 - 考虑多个匹配项以提供全面的答案
**对于完整目录**： - 将每一行解析为 JSON 以提取路径和描述 - 对描述文本执行语义匹配 - 按含义匹配，而不仅仅是关键字 - 返回所有相关条目以提供全面的答案
注意：目录包含 `path` 和 `description` 字段。`description` 字段包含主题和功能关键字，使其适用于关键字和语义匹配。
### 步骤 3：读取文档
**本地优先策略**：
1. **优先尝试本地**：`<skill directory>seekdb-docs/[File Path]` - 如果文件存在 → 本地读取（快速） - 如果文件缺失 → 进入步骤 2
2. **回退到远程**：`https://raw.githubusercontent.com/oceanbase/seekdb-doc/V1.1.0/en-US/[File Path]` - 从 GitHub 下载
**示例**： ``` Query: "How to integrate with Claude Code?"
1. Resolve path: read(SKILL.md) → /root/.claude/skills/seekdb/SKILL.md Skill directory : /root/.claude/skills/seekdb/
2. Search catalog with grep: grep -i "claude code" /root/.claude/skills/seekdb/references/seekdb-docs-catalog.jsonl
3. Match query from grep results: → Found: {"path": "300.integrations/300.developer-tools/700.claude-code.md", "description": "This guide explains how to use the seekdb plugin with Claude Code..."} → This matches the query, select this document
4. Read doc: Try: /root/.claude/skills/seekdb/seekdb-docs/300.integrations/300.developer-tools/700.claude-code.md If missing: https://raw.githubusercontent.com/oceanbase/seekdb-doc/V1.1.0/en-US/300.integrations/300.developer-tools/700.claude-code.md ```
## 指南
- **始终先解析路径**：使用读取 SKILL.md 的技巧获取绝对路径 - **优先对关键字查询使用 grep**：仅当 grep 未返回结果或需要语义匹配时才加载完整目录 - **语义匹配**：按含义匹配，而不仅仅是关键字 - **多个匹配项**：阅读所有相关条目以提供全面的答案 - **本地优先，远程备用**：优先尝试本地文档，缺失时使用远程 URL - **可选的本地文档**：运行 `scripts/update_docs.sh` 在本地下载完整文档（速度更快） - **支持离线**：如果存在本地文档，则完全离线工作
## 目录搜索格式
目录文件采用 **JSONL 格式**（每行一个 JSON 对象）：
```json {"path": "path/to/document.md", "description": "Document description text"} ```
**搜索目录**：
- **关键字搜索**：使用 grep（参见步骤 1 中的示例）。每个匹配行都包含路径和描述。 - **当 grep 不够用时**：读取完整目录，将每一行解析为 JSON，然后对描述进行语义匹配。
## 常见安装路径
此技能可能安装在： - **Cursor**：`.cursor/skills/seekdb/` - **Claude Code**：`.claude/skills/seekdb/` - **自定义**：任何目录（路径解析会自动处理此问题）
**不要对这些路径进行硬编码**。请改用动态解析方法。
## 详细示例
请参阅 [examples.md](references/examples.md) 了解完整的工作流程示例，包括： - 完整目录搜索场景 - 本地优先查找场景 - 远程回退场景 - 集成查询 - 多轮对话
## 类别概览
- **入门**：快速开始、基本操作、概述 - **开发**：向量搜索、混合搜索、AI 函数、MCP、多模型 - **集成**：框架、模型平台、开发者工具、工作流程 - **指南**：部署、管理、安全、OBShell、性能 - **参考**：SQL 语法、PL、错误代码、SDK API - **教程**：分步场景