Neo4j 图数据库设计与使用助手
触发条件
当用户出现以下意图时激活本 Skill：
- 设计 Neo4j 图数据模型 / 图谱 Schema
- 节点 / 关系 / 属性设计
- Cypher 查询优化
- 图索引设计（B-tree/Text/Vector/Full-text）
- 知识图谱 / 推荐系统 / 反欺诈方案
- "如何设计 xxx 的图谱"
设计流程（Agent 执行路径）
0. 版本检查 → 加载 references/version-major.md 对比用户版本，识别废弃项和重大变更。同时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本），后续设计过程中 Agent 从已加载的上下文中自主匹配深度特性
1. 需求分析 → 理解业务实体、关系类型、查询模式（遍历深度/过滤条件/聚合）
2. 图模型设计 → 节点标签设计、关系类型设计、属性设计、反规范化策略
3. 索引设计 → 属性索引（B-tree/Text/Vector）、全文索引、约束设计
4. 查询设计 → Cypher 查询模式、路径遍历、聚合、子查询
5. 性能优化 → 索引提示、参数化查询、避免笛卡尔积、LIMIT 提前
6. 使用指引 → 加载 references/usage-guide.md，给出场景化操作
7. 生产建议 → 加载 references/best-practices.md，给出集群/高可用/监控建议
8. 模板参考 → 加载 references/patterns.md，匹配业务图模型模板
快速参考
节点与关系命名铁律
| 对象 | 规范 | 示例 |
|---|
| ------ | ------ | ------ |
| 节点标签 | PascalCase（大驼峰） | User、Order、Product |
| 关系类型 | UPPER_SNAKE_CASE（大写下划线） | PLACED、BELONGS_TO、REVIEWED |
| 属性名 | camelCase（小驼峰） | userId、createdAt、orderCount |
| 索引名 | idx_<标签>_<属性> | idx_User_email |
| 约束名 | cst_<标签>_<属性> | cst_User_uuid |
节点标签设计原则
| 原则 | 说明 | 正例 | 反例 |
|---|
| ------ | ------ | ------ | ------ |
| 单标签优先 | 一个实体一个主标签 | (:User) | (:User:Active:Premium) |
| 多标签用于横切关注点 | 多种独立维度 | (:Product:Featured) | 标签爆炸 |
| 避免过泛标签 | 不要用 :Node、:Entity | (:Person) | (:Node {type:'person'}) |
关系设计原则
| 原则 | 说明 |
|---|
| ------ | ------ |
| 方向性 | 关系必须有方向 ()-[:KNOWS]->()，表示语义 |
| 稀疏性 | 超高基数关系（如用户-标签）考虑多对多中间节点 |
| 避免冗余双向关系 | FRIEND_OF 一个方向即可，双向查询用 ()-[:FRIEND_OF]-() |
| 关系属性 | 关系可带属性，如 PURCHASED {quantity: 3, at: datetime()} |
属性类型速查
| 类型 | Cypher 示例 | 适用场景 |
|---|
| ------ | ----------- | --------- |
| String | "hello" | 名称/描述/ID |
| Integer | 42 | 计数/年龄 |
| Float | 3.14 | 金额/评分 |
| Boolean | true / false | 状态标记 |
| Date | date("2026-06-09") | 日期 |
| DateTime | datetime() | 时间戳 |
| LocalTime | localtime("14:30:00") | 时间 |
| Duration | duration("P1D") | 时长 |
| Point | point({x:1, y:2}) | 地理坐标 |
| VECTOR (2025.10+) | vector([0.1, 0.2, ...]) | 向量嵌入 |
索引类型速查
| 类型 | 语法 | 适用场景 | 最低版本 |
|---|
| ------ | ------ | --------- | --------- |
| 属性索引（B-tree） | CREATE INDEX idx_User_email FOR (n:User) ON (n.email) | 等值/范围查询、排序 | 所有版本 |
| 复合索引 | CREATE INDEX idx_User_name_age FOR (n:User) ON (n.name, n.age) | 多属性过滤 | 所有版本 |
| 全文索引 | CREATE FULLTEXT INDEX idx_Product_desc FOR (n:Product) ON EACH [n.description] | 文本搜索 | 所有版本 |
| 文本索引 | CREATE TEXT INDEX idx_Article_content FOR (n:Article) ON (n.content) | 模糊/前缀匹配 | 5.x+ |
| 向量索引 | CREATE VECTOR INDEX idx_Product_embed FOR (n:Product) ON (n.embedding) OPTIONS {indexConfig: {\vector.dimensions\: 1536, \vector.similarity_function\: "COSINE"}} | 语义搜索/RAG | 5.x+（2025.10 起原生 VECTOR 类型） |
| 点索引 | CREATE POINT INDEX idx_Venue_location FOR (n:Venue) ON (n.location) | 地理空间查询 | 所有版本 |
渐进式加载
详细内容按需加载 references/：
| 主题 | 文件 | 何时加载 |
|---|
| ------ | ------ | --------- |
| 图模型设计规范（节点/关系/属性/索引/约束） | references/design-spec.md | Step 2-3 图模型和索引设计 |
| 场景化操作（建图/Cypher/索引/迁移/运维） | references/usage-guide.md | Step 6 使用指引 |
| 最佳实践（模型/查询/索引/集群/运维） | references/best-practices.md | Step 7 生产建议 |
| 业务图模型模板（6类业务完整Cypher DDL） | references/patterns.md | Step 8 模板参考 |
| 重大版本特性（废弃/依赖变更/新模块） | references/version-major.md | Step 0 版本检查（模块激活时即加载） |
| 深度版本特性 — CalVer（Cypher 25/VECTOR/GenAI/向量索引/动态标签） | references/version-2025.md | Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
| 深度版本特性 — 5.x（文本索引/向量索引/复合数据库/APOC） | references/version-5.0.md | Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
版本参考文档启用规则
- 模块激活时 — 始终加载
references/version-major.md，Agent 需主动对比用户使用的 Neo4j 版本（注意 CalVer 2025.01+ 和语义版本 5.x 的差异），若存在废弃项或重大变更，立即提示用户 - 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
- 深度特性按大版本拆分，小版本持续追加 — CalVer 按年份拆分（
version-2025.md），5.x 按大版本拆分（version-5.0.md）。更新时在文件中新增 ## X.Y.Z 版本节即可，不单开文件
硬规则
- 设计规范内容来自权威资料（Neo4j 官方文档/Cypher 手册/图数据库最佳实践），不编造
- 所有节点必须有关键属性上的唯一约束或索引
- 关系必须有类型且有方向，不可使用无类型关系
- 遍历深度必须有上限（
[1..N]），禁止 [] 无限深度 - 查询必须参数化（
$param），禁止字符串拼接 Cypher - 属性值禁止存储 JSON 字符串（应建模为节点和关系）
- 图模型设计优先于查询优化：先建模业务真实关系，再考虑查询性能优化