核心能力与定位
SurrealDB Skill 是一套面向 SurrealDB 3 的专家级开发工具链，定位为多模型数据库全栈开发助手。不同于传统 ORM 或单一查询工具，它整合了从数据建模、查询优化到生产部署的完整生命周期管理，特别针对 AI Agent 场景强化了 MCP 协议支持、向量检索和实时数据流能力。
显著优点
1. 多模型统一架构
文档、图、向量、时序、地理空间五种数据模型原生共存于单一数据库，无需 ETL 或跨库 JOIN。RELATE 语句实现真正的图遍历（非模拟），vector::similarity::* 函数内置 HNSW 索引支持，RAG pipeline 可直接在 SurrealQL 中完成。
2. AI 原生集成
官方 SurrealMCP 服务器让 Claude、Cursor、GitHub Copilot、n8n 等 AI 宿主直接读写数据库；LangChain Python 集成提供向量存储接口；SurrealFS 更是将数据库抽象为 AI Agent 的文件系统。这种"数据库即 Agent 记忆层"的设计在当前生态中较为罕见。
3. 开发与运维一体化doctor.py 健康检查脚本验证 CLI、连通性、认证、版本兼容性；schema.py 支持 schema 内省与 SurrealQL/JSON 双格式导出；onboard.py 生成 JSON 能力清单供 Agent 程序化消费。运维脚本采用 PEP 723 标准，依赖自动管理。
4. 极致的部署灵活性
单二进制文件（<100MB）、内存模式、RocksDB、自研 SurrealKV（支持时间旅行查询）、TiKV 分布式集群四种存储引擎，覆盖从本地开发到生产集群的全场景。WASM 扩展系统（Surrealism）允许用 Rust 编写自定义函数和分词器。
5. 语言生态覆盖
官方 SDK 达 10+ 种：JavaScript/TypeScript（Node/Deno/Bun/浏览器）、Python、Go、Rust、Java、Kotlin、.NET、C、PHP、Swift、Ruby。包括源码级 C 绑定和 Swift 原生支持（iOS/macOS/visionOS）。
潜在局限与风险
1. 版本边界复杂
SurrealML 和 LangChain JS 集成处于预览/撤回状态（v1.4.0 文档在 v1.4.1 被撤销），setup-surreal GitHub Action 也被澄清为 CI 专用非 CLI 引导工具。技能文档虽明确标注，但用户易混淆稳定 API 与实验特性。
2. 生产安全门槛
默认示例使用 root/root 凭证，虽多次标注"本地开发专用"，但脚本化工作流中仍存在误用风险。行级权限（DEFINE TABLE ... PERMISSIONS）和 JWT 认证需额外学习成本。
3. 网络依赖与审计
dcotor.py 和 schema.py 需 WebSocket 连接用户指定的 SurrealDB 端点；check_upstream.py 调用 GitHub API。虽声明无第三方网络调用，但企业内网环境需评估出站策略。
4. 向量索引限制
HNSW 为 v3 主推向量索引类型，brute-force 仅作为索引重建期间的降级方案，大规模向量场景需预规划内存与构建时间。
适合人群
- 全栈开发者：需要统一替换 PostgreSQL + Redis + Neo4j 技术栈的简化方案
- AI/LLM 应用开发者：构建需长期记忆、向量检索、实时数据流的 Agent 系统
- DevOps/SRE：管理 SurrealDB 集群，需要程序化健康检查与 schema 版本控制
- 数据架构师：设计支持图遍历、语义搜索、时序分析的混合负载 schema
常规风险提示
- 凭证管理：生产环境必须使用
DEFINE USER创建最小权限账户，禁用 root - 网络暴露：SurrealDB 默认无加密传输，生产需 TLS 终止或 VPN 保护
- 存储引擎选择：SurrealKV 时间旅行功能消耗额外存储，需评估保留策略
- WASM 扩展安全：Surrealism 模块运行于数据库内部，需审计第三方 WASM 二进制
- 上游漂移：技能基于 2026-05-03 快照，关键修复需定期运行
check_upstream.py