SurrealDB专家

📌 Skill基础信息

Skill名称：surrealdb

简称：SurrealDB 3技能

来源：社区第三方（作者24601）

运行宿主：仅限支持OpenClaw规范的AI Agent工具（需兼容MCP协议）

核心定位：为AI Agent提供专业的SurrealDB 3数据库架构、开发与运维能力，支持多模型数据建模、向量搜索、图遍历等高级功能，适用于数据库设计、查询优化和全栈开发场景。

🧩 内部核心组成

该Skill包含以下核心组件：

子Agent集合：

• 数据库健康检查Agent（doctor.py）
• 架构分析Agent（schema.py）
• 集成引导Agent（onboard.py）

斜杠命令：

命令名	功能简述
doctor	检查SurrealDB连接状态和版本健康度
schema introspect	导出运行中数据库的完整架构
schema tables	列出所有数据表及字段索引信息
onboard --agent	生成AI Agent能力清单和集成配置

MCP工具：内置SurrealMCP服务器，支持snake_case命令规范（query/select/insert等）

模板文件：包含多个规则文档（surrealql.md, data-modeling.md, graph-queries.md等）

Hooks钩子：提供PEP 723脚本运行钩子，自动处理依赖安装

目录结构：

scripts/          # 主要脚本目录
  doctor.py       # 健康检查脚本
  schema.py       # 架构分析脚本  
  onboard.py      # 集成引导脚本
rules/            # 规则文档目录
skills/surrealmcp/# MCP服务器相关文件

🛠 安装与启用方式

前置依赖：

1. SurrealDB CLI：brew install surrealdb/tap/surreal
2. Python 3.10+ 环境
3. uv工具：brew install uv

环境变量要求：

export SURREAL_ENDPOINT="http://localhost:8000"
export SURREAL_USER="root" 
export SURREAL_PASS="root"
export SURREAL_NS="test"
export SURREAL_DB="test"

安装命令：

skills install --user 24601/surreal-skills

启动入口：通过uv运行相应脚本，如：uv run scripts/doctor.py

📋 标准工作流

1. 环境准备：用户配置SurrealDB连接环境变量
2. 健康检查：运行doctor.py验证数据库连接状态
3. 架构分析：使用schema.py获取数据库结构和元数据
4. 查询交互：通过MCP工具或直接执行SurrealQL查询
5. 结果处理：Agent处理查询结果并生成响应
6. 优化调整：根据性能分析结果进行查询优化或架构调整

典型链路：环境配置 → 连接验证 → 架构分析 → 查询执行 → 结果处理

⚠️ 关键限制、缺陷、注意事项

平台限制：

• 仅支持macOS和Linux系统（依赖Homebrew安装）
• Windows系统需要WSL或Docker环境

Token消耗：架构 introspection 操作可能消耗大量Token，大型数据库需谨慎使用

适合项目：

• 中小型多模型数据应用
• 图数据库和向量搜索场景
• 开发测试环境数据库管理

不适合项目：

• 超大规模生产环境（性能监控有限）
• 高安全性要求的金融系统（认证机制简单）

已知坑点：

• SurrealML功能处于预览阶段，API不稳定
• 默认使用root/root凭证，生产环境必须修改
• 部分SDK版本兼容性问题（如.NET v0.10.2 beta）

生产环境：可用于开发测试，生产环境需要额外安全加固和监控

✅ 适用场景 & ❌ 不适合场景

适用场景：

• 全栈开发者需要快速操作SurrealDB数据库
• AI Agent需要实现RAG检索和语义搜索功能
• 图数据分析和关系遍历应用开发
• 多模型数据架构设计和优化

不适合场景：

• 超高性能要求的实时交易系统
• 需要严格ACID事务保证的金融应用
• 已有成熟ORM框架的传统项目迁移
• 无SurrealDB基础的学习者（学习曲线较陡）

skills install --user 24601/surreal-skills

检测到隐私/敏感信息读取（预设模式 #3）