NornicDB 项目说明书

Doramagic 项目包 · 项目说明书

NornicDB 项目

NornicDB：面向 RAG 与 LLM 场景设计的图数据库。

项目概览

NornicDB 是一个面向 AI 时代设计的图数据库系统，定位于"AI-native database"，将图结构、向量检索与全文搜索融合在单一引擎内，专门服务于 LLM 智能体记忆、知识图谱、RAG（检索增强生成）系统等场景。资料来源：[README.md:1-100]()

章节 相关页面

继续阅读本节完整说明和来源证据。

核心定位与设计目标

NornicDB 的核心思路是把"语义检索"和"图遍历"合并到同一个查询路径中，从而省去传统 RAG 栈中多个独立系统之间的数据搬运与同步成本。资料来源：README.md:1-50

其主要设计目标包括：

融合检索引擎：在同一引擎内同时支持向量 + BM25 + 图遍历的混合检索。
Neo4j 兼容性：提供 Bolt 协议和 Cypher 查询语言支持，使官方 Neo4j 驱动几乎无需修改即可接入。
Qdrant 兼容：保留 Qdrant 风格的 gRPC 工作流（Points.Search、Points.Query），同时叠加图原生能力。
时序真值建模：支持版本化事实、时效窗口（temporal validity）、三时态事实（tritemporal）和"按时间点读取"（as-of reads），适用于审计与合规场景。
协议灵活性：通过 REST、GraphQL、Bolt/Cypher、Qdrant gRPC 以及附加的 Nornic gRPC 在同一平台上同时对外提供服务。

资料来源：README.md:50-120

主要子系统与能力

NornicDB 的能力由多个内置子系统协同提供，每个子系统对应一个独立的 Go 包或前端模块：

子系统	说明	来源文件
APOC 函数库	950+ 内置函数，覆盖文本、数学、集合、机器学习、时空等	apoc/README.md:1-40
Heimdall AI Assistant	内置 AI，可进行自然语言查询、插件执行、生命周期钩子	README.md:120-180
GPU 加速	支持 Metal（Apple Silicon）和 CUDA；HNSW 构建仍为 CPU 密集（见 issue #32）	README.md:180-210
链接预测（Link Prediction）	拓扑 + 语义混合打分：Common Neighbors / Jaccard / Adamic-Adar 等	pkg/linkpredict/README.md:1-60
Qdrant gRPC 兼容	保留 Qdrant 客户端接入路径，集合映射到数据库命名空间	pkg/qdrantgrpc/README.md:1-40
安全子系统	提供 CSRF / SSRF 等防护规范参考	pkg/security/README.md:1-20
浏览器 UI	组件化拆分的 Cypher 查询、语义搜索、节点详情面板	ui/src/components/browser/README.md:1-30
神经网络训练	提供 Cypher 生成、TLP 分类等微调数据集生成脚本	neural/README.md:1-60
桌面与 Docker 部署	macOS LaunchAgent + 菜单栏应用；多架构 Docker 镜像	macos/README.md:1-60、docker/README.md:1-80

这些子系统共同构成了"数据库 + 检索 + AI 编排"的整体形态，使 NornicDB 不同于传统图数据库或纯向量数据库。

典型使用场景

项目 README 明确列出了一组面向生产的使用场景，可以作为选型参考：

AI 智能体记忆（AI Agent Memory）：持久化、可查询的智能体长期记忆。
知识图谱与 RAG：自组织的知识库，把图遍历与混合检索合并到同一管道。
会话上下文：带衰减机制的对话历史。
金融与合规：用于贷款/风险状态重构、KYC/AML 状态变更、政策版本化以及审计回执。
AI 治理与血缘追踪：追踪模型断言、人工覆盖与事实来源随时间的演化。

资料来源：README.md:80-130

社区关注与已知问题

从近期 issue 反馈来看，用户最关心的几类问题集中在以下几个方向，概览页面有必要预先提示：

Cypher 正确性回归：v1.1.4 之后出现若干 SET / MATCH+CREATE 解析路径的回归（issue #192、#213）。
向量索引副作用：db.index.vector.queryRelationships 在 v1.1.7 返回 0 行（issue #219）；在 EMBEDDING_ENABLED=false 外部向量路径下，运行时写入不会刷新搜索底座，需要重启（issue #220）。
批量写入压力：0593642 版本在 Graphiti 批量抽取中触发 BuildIndexes / k-means 预热风暴，导致 CPU 挂起（issue #222）；社区已提出"批量导入 API + 延迟重建索引"的需求（issue #171）。
Neo4j 兼容性边界：默认 neo4j 数据库名与 3 参数全文过程形式尚未完全对齐（issue #214）。
文档/配置不一致：README 与 configuration.md 中展示的 async_writes YAML 与 pkg/config/config.go 不一致（仅支持环境变量）（issue #215）。
参数与类型处理：嵌套在 UNWIND $rows … row.created_at 列表/映射中的 datetime 被存为 Go 格式字符串而非时态类型（issue #221）。

这些问题说明 NornicDB 正在快速演进，使用方在生产部署前应关注版本变更与回归测试。

文档与入口

项目以"文档中心 + 议题索引"双入口组织：

公共文档站：<https://orneryd.github.io/NornicDB/>
文档中心：docs/README.md
议题索引（症状优先）：docs/issues-index.md

资料来源：README.md:200-260

Models 模块

Models 模块是 NornicDB 中负责管理、加载与调用机器学习模型的子层，覆盖嵌入模型（Embedding Model）、小型语言模型（SLM / Heimdall）、训练模型（Neural Trainer）以及插件模型四个方向。它既支撑向量索引的语义检索能力（通过 BGE 系列模型），又为 Heimdall AI 助手的自然语言理解提供本地推理后端；同时通...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与职责

Models 模块是 NornicDB 中负责管理、加载与调用机器学习模型的子层，覆盖 嵌入模型（Embedding Model）、小型语言模型（SLM / Heimdall）、训练模型（Neural Trainer） 以及 插件模型 四个方向。它既支撑向量索引的语义检索能力（通过 BGE 系列模型），又为 Heimdall AI 助手的自然语言理解提供本地推理后端；同时通过独立的训练管线允许用户微调并导出自定义 Cypher 生成器。

根据 README.md 的描述，NornicDB 将"Vector & full-text search"、"GPU acceleration (Metal, CUDA)"与"Heimdall AI Assistant"统一在同一发行版中对外提供，而 Models 模块正是这些能力共享的底层资源层。社区在 Issue #220 中提到的"外部向量 + EMBEDDING_ENABLED=false"场景，正是 Models 模块中嵌入管线被旁路时的典型分支。

模型类型与目录约定

Models 模块按用途划分多个目录：

模型类别	默认位置 / 文件	主要用途	来源
嵌入模型（BGE）	`models/bge-m3.gguf`	向量检索嵌入	docker/README.md
SLM（Heimdall）	`models/qwen3-0.6b.gguf` 等	AI 助手对话、动作选择	docker/README.md
训练产物	`models/cypher-expert/`	微调后的 Cypher 生成模型	neural/README.md
量化导出	`*.q4_K_M.gguf` / `q5_K_M` / `q8_0`	不同精度/体积的推理产物	neural/README.md
插件模型	`NORNICDB_MODELS_DIR` 指向目录	Heimdall 插件可执行的动作后端	plugins/README.md

docker/README.md 显示基础镜像、BGE 镜像、Heimdall 镜像分别通过 make build-arm64-metal、make build-arm64-metal-bge、make build-arm64-metal-bge-heimdall 目标构建；只有后两个目标会在构建阶段把 GGUF 模型打包进镜像。社区中 Issue #32 提出的"GPU 加速 HNSW 构造"规划也与该模块共享 GPU 计算资源。

加载、下载与生命周期管理

docker/README.md 提供了一组专用的 make 任务用于 Models 的生命周期管理：

make download-models   # 下载 BGE-M3 + qwen3-0.6b（约 750MB）
make check-models      # 校验模型文件是否就位

构建变体决定了哪些模型在镜像启动时即可用：

基础镜像（base）：不包含任何 GGUF 文件，体积最小，模型需运行时挂载。
BGE 镜像：内嵌 BGE-M3，可立即提供向量嵌入能力，适合纯 RAG 场景。
Heimdall 镜像：在 BGE 基础上叠加 qwen3-0.6b，启用完整对话与异常检测；构建时会自动调用 make download-models，参见 docker/README.md 的说明。

在运行期，plugins/README.md 指出可通过环境变量覆盖模型目录与具体模型文件名：

export NORNICDB_MODELS_DIR=/data/models
export NORNICDB_HEIMDALL_MODEL=phi-3.5-mini-instruct
# 实际加载 /data/models/phi-3.5-mini-instruct.gguf

这种"目录 + 文件名（不含 .gguf）"的约定让运维可以在不重建镜像的前提下替换 SLM，例如替换为 Phi-3.5-mini-instruct 等第三方模型。

训练与量化输出

Models 模块同时承担训练管线的产物管理职能。neural/README.md 描述的标准流程为：生成数据集 → 校验 → 训练 → 量化 → 部署：

# 1. 生成数据集
python scripts/generate_cypher_dataset.py --output data/cypher.jsonl --num-examples 2000
# 2. 校验
python scripts/validate_dataset.py data/cypher.jsonl
# 3. 训练
python train.py --preset qwen_1_5b --dataset data/cypher.jsonl \
  --output_dir models/cypher-expert --epochs 5
# 4. 导出 GGUF
python export_to_gguf.py --model_dir models/cypher-expert \
  --output cypher-expert-q4.gguf
# 5. 部署
cp cypher-expert-q4.gguf /data/models/

可用的量化档位同样在 neural/README.md 中以表格形式给出，涵盖 Q4_K_M（体积最小、质量良好）、Q5_K_M、Q8_0 与 F16。训练既支持基础模型的全量微调，也支持 LoRA 适配（lora_r=16、lora_alpha=32、target_modules 自定义），输出与 Heimdall 同源的 GGUF 格式，因此可直接复用插件加载路径。

与上层 API 的衔接

模型一旦就位，便通过 ui/src/utils/api.ts 中定义的接口被上层消费。该文件暴露了 MVCC 生命周期、保留策略分类等结构化类型，但更重要的是它定义了模型相关运行时监控所需的契约，例如嵌入状态、向量索引刷新等字段，供前端 Data Explorer 展示。需要注意的是，Issue #220 报告的"运行时外部向量不会立即刷新底层 HNSW 索引"问题，发生在嵌入模型生成向量后写入存储的路径上，属于 Models 模块与向量索引之间的衔接点而非嵌入模型本身，因此排查时需要同时观察模型端输出与索引端刷新。

故障与注意事项

模型未下载导致启动失败：Heimdall 镜像若未先执行 make download-models 且关闭了自动下载，会出现 model file not found。make check-models 可在 CI 中预先发现该问题。
环境变量与文档不一致：Issue #215 报告 async_writes_enabled 在文档中存在 YAML 示例但 pkg/config/config.go 仅识别环境变量；Models 模块相关变量（NORNICDB_MODELS_DIR、NORNICDB_HEIMDALL_MODEL）目前同样仅通过环境变量设置，部署时务必使用 env 而非 YAML。
嵌入开关与向量陈旧：当 EMBEDDING_ENABLED=false 且依赖外部向量时，运行时写入不会立即重建 HNSW 层 0 的 BM25 种子，需要重启或在批量导入完成后触发重建，参见 Issue #171 关于 Bulk Import API 的讨论。

Utils 模块

ui/src/utils/ 是 NornicDB 前端 UI 子项目的工具层目录，集中存放与数据库后端交互、路径解析、可视化样例数据生成以及 Cypher 语句辅助相关的纯函数与类型定义。该层不包含 React 组件本身，但为 components/browser/ 下的浏览器面板、查询面板、节点详情面板以及演示页 /demo 提供可复用的基础能力。资料来源：[ui/src...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 API 类型契约层（api.ts）

继续阅读本节完整说明和来源证据。

章节 路由与基础路径解析（basePath.ts）

继续阅读本节完整说明和来源证据。

章节 可视化样例数据生成（demoSeed.ts、cyberSeed.ts、cyberSim.ts）

继续阅读本节完整说明和来源证据。

模块概述

ui/src/utils/ 是 NornicDB 前端 UI 子项目的工具层目录，集中存放与数据库后端交互、路径解析、可视化样例数据生成以及 Cypher 语句辅助相关的纯函数与类型定义。该层不包含 React 组件本身，但为 components/browser/ 下的浏览器面板、查询面板、节点详情面板以及演示页 /demo 提供可复用的基础能力。资料来源：ui/src/utils/demoSeed.ts:1-6 注释中明确说明该文件"为 /demo 页程序化生成 3D 星系网格"。

模块按职责可划分为四组：API 类型契约层（api.ts）、路由与基础路径解析（basePath.ts）、可视化样例数据生成（demoSeed.ts / cyberSeed.ts / cyberSim.ts）、Cypher 语句构造辅助（cypherStatements.ts）。

核心文件与职责

API 类型契约层（api.ts）

ui/src/utils/api.ts 集中声明了 NornicDB 后端 REST/gRPC 响应在 TypeScript 端使用的强类型结构，避免散落在多个组件中重复定义。该文件暴露以下几族接口：

接口族	用途
`MVCCLifecycleDebtKey` / `MVCCLifecycleDebtResponse`	描述压缩债（compaction debt）键的逻辑键、命名空间、字节数与墓链深度
`MVCCLifecycleNamespaceMetrics`	命名空间维度的可清理/已清理字节数
`MVCCLifecycleRollup`	`prune_runs`、`keys_processed`、`fence_mismatches` 等累计指标
`MVCCLifecycleLastRun`	上一次修剪运行的瞬时指标
`MVCCSnapshotReaderInfo`	当前活跃的 MVCC 快照读取者信息（`ReaderID`、`StartTime`、`SnapshotVersion`）
`MVCCLifecycleStatus`	整合上述字段，并包含 `pressure_band`、`emergency_mode`、`mvcc_tombstone_chain_max_depth` 等运维信号
`RetentionCategory` / `RetentionPeriod`	保留策略分类枚举与周期定义，覆盖 `SYSTEM`、`AUDIT`、`PHI`、`PII`、`FINANCIAL` 等类别

资料来源：ui/src/utils/api.ts:1-60 中可见 MVCCLifecycleDebtKey、MVCCLifecycleNamespaceMetrics、MVCCLifecycleRollup 的字段定义；ui/src/utils/api.ts:95-120 中可见 MVCCSnapshotReaderInfo 与 MVCCLifecycleStatus 的完整字段；ui/src/utils/api.ts:130-150 给出 RetentionCategory 枚举与 RetentionPeriod 接口。

路由与基础路径解析（basePath.ts）

basePath.ts 负责把 NornicDB 服务可能部署在子路径下的情况抽象成统一访问函数（例如反代到 /nornicdb/...）。该层使得 UI 在根路径、嵌入式部署、容器化反代等场景下都能正确拼出 REST 端点（如 /nornicdb/search、/db/nornicdb/tx/commit）。该文件的具体实现细节未在当前抓取片段中直接呈现，但其语义与 ui/README.md 文档中列出的端点（/health、/status、/nornicdb/search、/nornicdb/similar、/db/nornicdb/tx/commit）相互印证。资料来源：ui/README.md:API Endpoints 表

可视化样例数据生成（demoSeed.ts、cyberSeed.ts、cyberSim.ts）

ui/src/utils/demoSeed.ts 是该组中最具代表性的文件，其注释清楚地说明算法目标：

"程序化生成 /demo 页使用的 3D 星系网格。布局：12 个扇区按斐波那契球面排列，每个扇区约 36 颗星，带扇区内超空间航道；扇区之间由少量网关星串接成链。从扇区 0 到扇区 11 的遍历必须跨越每个扇区边界——产生天然的 11 跳以上最短路径。"

资料来源：ui/src/utils/demoSeed.ts:1-6

文件导出的类型契约与字面量如下：

DemoStar：id、name、sector、hue、mass、x/y/z
DemoEdge：source、target、distance
DemoGalaxy：stars、edges、startId、endId、sectorCount
STAR_PREFIX：北欧神话词根数组，元素含 Yggdra、Nidh、Mim、Gjall、Heidr、Surt、Vidar、Hodr、Skuld、Urda、Verda、Bragi、Iduna、Freyja、Tyr、Vanir、Asgar、Mjoll、Gunn、Sleip、Hugin、Munin、Ratat、Fenris

资料来源：ui/src/utils/demoSeed.ts:32-50

与 demoSeed.ts 配套的 cyberSeed.ts 与 cyberSim.ts 命名暗示它们承担"赛博"主题演示的种子生成与物理/拓扑模拟（具体细节未在当前片段中直接展现）。

Cypher 语句辅助（cypherStatements.ts）

cypherStatements.ts 集中提供构造 Cypher 查询的辅助函数，常用于 QueryPanel.tsx、浏览器面板与示例查询中。结合 apoc/README.md 中列出的 CALL db.index.vector.queryNodes(...) 用法与 README 中展示的"vector + fulltext 混合搜索"示例，可推断该文件至少包含混合检索 Cypher 模板与常用调用包装。资料来源：apoc/README.md:plugins 目录列表展示了与 db.index.vector.queryNodes 相关的 APOC 包结构；README.md:Cypher (Neo4j-compatible) 段

关键数据模型与组件依赖

下面这张表汇总各工具文件的核心导出与其直接消费者，便于在修改类型时反向追踪。

文件	核心导出	典型消费者
`api.ts`	MVCC/Retention 接口族	`Browser`、`NodeDetailsPanel`、运维仪表盘
`basePath.ts`	路径解析函数	所有发起 fetch 的组件
`demoSeed.ts`	`DemoGalaxy` 工厂	`/demo` 演示页、3D 渲染组件
`cyberSeed.ts` / `cyberSim.ts`	赛博主题种子与模拟器	赛博主题演示页
`cypherStatements.ts`	Cypher 字符串构造器	`QueryPanel.tsx`、示例库

使用模式与扩展建议

新增后端接口类型：在 api.ts 中补充 TypeScript interface 后，由 fetch 层使用，组件层不应重复定义响应结构。
部署在反代子路径下：通过 basePath.ts 统一拼装 URL，避免硬编码 /nornicdb/... 前缀。
扩展演示数据：修改 demoSeed.ts 中 STAR_PREFIX、扇区数量或网关星规则即可调整 /demo 的拓扑难度。
构造 Cypher 模板：将高频 Cypher 集中放入 cypherStatements.ts，便于在 QueryPanel 中复用并支持参数注入。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal

可能增加新用户试用和生产接入成本。

high 来源证据：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-res…

可能增加新用户试用和生产接入成本。

high 来源证据：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart…

可能阻塞安装或首次运行。

high 来源证据：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：orneryd/NornicDB

摘要：发现 37 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal。

1. 安装坑 · 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/221 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-res…

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-resolution cosine search path)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/222 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart…

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/220 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/219 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安装坑 · 依赖 Docker 环境

严重度：medium
证据强度：runtime_trace
发现：安装/运行入口包含 Docker 命令：docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run
对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
复现命令：docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run
证据：identity.distribution | https://github.com/orneryd/NornicDB | docker run -d --name nornicdb -p 7474:7474 -p 7687:7687 -v nornicdb-data:/data timothyswt/nornicdb-arm64-metal-bge:latest # amd64 / CPU only docker run

6. 安装坑 · 失败模式：installation: [FEATURE] - Bulk Import API

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [FEATURE] - Bulk Import API
对用户的影响：Developers may fail before the first successful local run: [FEATURE] - Bulk Import API
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/171 | [FEATURE] - Bulk Import API

7. 安装坑 · 失败模式：installation: [PROPOSAL] OKF Format import/export - RFC

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: [PROPOSAL] OKF Format import/export - RFC
对用户的影响：Developers may fail before the first successful local run: [PROPOSAL] OKF Format import/export - RFC
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/217 | [PROPOSAL] OKF Format import/export - RFC

8. 安装坑 · 失败模式：installation: v1.1.7 - Black Math

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.1.7 - Black Math
对用户的影响：Upgrade or migration may change expected behavior: v1.1.7 - Black Math
证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.7 | v1.1.7 - Black Math

9. 安装坑 · 来源证据：Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/215 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安装坑 · 来源证据：SET silently fails on nodes that existed before v0→v2 storage migration

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SET silently fails on nodes that existed before v0→v2 storage migration
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/190 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

11. 安装坑 · 来源证据：[FEATURE] - Bulk Import API

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[FEATURE] - Bulk Import API
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/171 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

12. 安装坑 · 来源证据：[Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/214 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 安装坑 · 来源证据：[PROPOSAL] OKF Format import/export - RFC

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[PROPOSAL] OKF Format import/export - RFC
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/217 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 配置坑 · 可能修改宿主 AI 配置

严重度：medium
证据强度：source_linked
发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
证据：capability.host_targets | https://github.com/orneryd/NornicDB | host_targets=claude

15. 配置坑 · 失败模式：configuration: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/192 | Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing

16. 配置坑 · 失败模式：configuration: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/215 | Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)

17. 配置坑 · 失败模式：configuration: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, wri...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/191 | Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes

18. 配置坑 · 失败模式：configuration: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt,...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
对用户的影响：Developers may misconfigure credentials, environment, or host setup: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/189 | UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)

19. 配置坑 · 失败模式：configuration: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=fa...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/220 | Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart; degrades resolution during ingest

20. 配置坑 · 失败模式：configuration: [BUG] Cypher correctness (v1.1.5): `SET x = <map>` replacement drops properties; `SET += <UNW...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [BUG] Cypher correctness (v1.1.5): SET x = <map> replacement drops properties; SET += <UNWIND alias>, dynamic labels, and db.create.setNodeVectorProperty broken
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] Cypher correctness (v1.1.5): SET x = <map> replacement drops properties; SET += <UNWIND alias>, dynamic labels, and db.create.setNodeVectorProperty broken
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/213 | [BUG] Cypher correctness (v1.1.5): SET x = <map> replacement drops properties; SET += <UNWIND alias>, dynamic labels, and db.create.setNodeVectorProperty broken

21. 配置坑 · 失败模式：configuration: [BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/219 | [BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

22. 配置坑 · 失败模式：configuration: [Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg...

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/214 | [Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form

23. 配置坑 · 失败模式：configuration: v1.1.4 - Barracuda

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.4 - Barracuda
对用户的影响：Upgrade or migration may change expected behavior: v1.1.4 - Barracuda
证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.4 | v1.1.4 - Barracuda

24. 配置坑 · 失败模式：configuration: v1.1.6 - Cherry Bomb

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.6 - Cherry Bomb
对用户的影响：Upgrade or migration may change expected behavior: v1.1.6 - Cherry Bomb
证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.6 | v1.1.6 - Cherry Bomb

25. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/orneryd/NornicDB | README/documentation is current enough for a first validation pass.

26. 维护坑 · 失败模式：migration: SET silently fails on nodes that existed before v0→v2 storage migration

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: SET silently fails on nodes that existed before v0→v2 storage migration
对用户的影响：Developers may hit a documented source-backed failure mode: SET silently fails on nodes that existed before v0→v2 storage migration
证据：failure_mode_cluster:github_issue | https://github.com/orneryd/NornicDB/issues/190 | SET silently fails on nodes that existed before v0→v2 storage migration

27. 维护坑 · 失败模式：migration: v1.1.1 - Santeria

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v1.1.1 - Santeria
对用户的影响：Upgrade or migration may change expected behavior: v1.1.1 - Santeria
证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.1 | v1.1.1 - Santeria

28. 维护坑 · 失败模式：migration: v1.1.2 - Purple Haze

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v1.1.2 - Purple Haze
对用户的影响：Upgrade or migration may change expected behavior: v1.1.2 - Purple Haze
证据：failure_mode_cluster:github_release | https://github.com/orneryd/NornicDB/releases/tag/v1.1.2 | v1.1.2 - Purple Haze

29. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/orneryd/NornicDB | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/orneryd/NornicDB | no_demo; severity=medium

31. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/orneryd/NornicDB | no_demo; severity=medium

32. 安全/权限坑 · 来源证据：Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/192 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

33. 安全/权限坑 · 来源证据：Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after writes
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/191 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

34. 安全/权限坑 · 来源证据：UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/189 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

35. 安全/权限坑 · 来源证据：[BUG] Cypher correctness (v1.1.5): `SET x = <map>` replacement drops properties; `SET += <UNWIND alias>`, dynamic label…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Cypher correctness (v1.1.5): SET x = <map> replacement drops properties; SET += <UNWIND alias>, dynamic labels, and db.create.setNodeVectorProperty…
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/orneryd/NornicDB/issues/213 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

36. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/orneryd/NornicDB | issue_or_pr_quality=unknown

37. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/orneryd/NornicDB | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

NornicDB 项目

项目概览

核心定位与设计目标

主要子系统与能力

典型使用场景

社区关注与已知问题

文档与入口

See Also

Models 模块

概述与职责

模型类型与目录约定

加载、下载与生命周期管理

训练与量化输出

与上层 API 的衔接

故障与注意事项

See Also

Utils 模块

模块概述

核心文件与职责

API 类型契约层（api.ts）

路由与基础路径解析（basePath.ts）

可视化样例数据生成（demoSeed.ts、cyberSeed.ts、cyberSim.ts）

Cypher 语句辅助（cypherStatements.ts）

关键数据模型与组件依赖

使用模式与扩展建议

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：Datetime nested in a list/map parameter (UNWIND $rows … row.created_at) stored as Go-format string, not a temporal

2. 安装坑 · 来源证据：Regression in 0593642: bulk Graphiti extraction triggers BuildIndexes/k-means warmup storm → CPU-bound hang (entity-res…

3. 安全/权限坑 · 来源证据：Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=false) — stale until restart…

4. 安全/权限坑 · 来源证据：[BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

5. 安装坑 · 依赖 Docker 环境

6. 安装坑 · 失败模式：installation: [FEATURE] - Bulk Import API

7. 安装坑 · 失败模式：installation: [PROPOSAL] OKF Format import/export - RFC

8. 安装坑 · 失败模式：installation: v1.1.7 - Black Math

9. 安装坑 · 来源证据：Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)

10. 安装坑 · 来源证据：SET silently fails on nodes that existed before v0→v2 storage migration

11. 安装坑 · 来源证据：[FEATURE] - Bulk Import API

12. 安装坑 · 来源证据：[Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg fulltext procedure form

13. 安装坑 · 来源证据：[PROPOSAL] OKF Format import/export - RFC

14. 配置坑 · 可能修改宿主 AI 配置

15. 配置坑 · 失败模式：configuration: Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing

16. 配置坑 · 失败模式：configuration: Docs: async_writes yaml examples in README + configuration.md don't match config.go (env-only)

17. 配置坑 · 失败模式：configuration: Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, wri...

18. 配置坑 · 失败模式：configuration: UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt,...

19. 配置坑 · 失败模式：configuration: Vector search substrate not updated on runtime writes (external vectors, EMBEDDING_ENABLED=fa...

20. 配置坑 · 失败模式：configuration: [BUG] Cypher correctness (v1.1.5): `SET x = <map>` replacement drops properties; `SET += <UNW...

21. 配置坑 · 失败模式：configuration: [BUG] db.index.vector.queryRelationships returns 0 rows on v1.1.7 (node path works)

22. 配置坑 · 失败模式：configuration: [Feature] Neo4j drop-in compatibility: accept the default "neo4j" database name and the 3-arg...

23. 配置坑 · 失败模式：configuration: v1.1.4 - Barracuda

24. 配置坑 · 失败模式：configuration: v1.1.6 - Cherry Bomb

25. 能力坑 · 能力判断依赖假设

26. 维护坑 · 失败模式：migration: SET silently fails on nodes that existed before v0→v2 storage migration

27. 维护坑 · 失败模式：migration: v1.1.1 - Santeria

28. 维护坑 · 失败模式：migration: v1.1.2 - Purple Haze

29. 维护坑 · 维护活跃度未知

31. 安全/权限坑 · 存在评分风险

32. 安全/权限坑 · 来源证据：Cypher regressions in main since v1.1.4: MATCH+CREATE relationship-only and SET clause parsing

33. 安全/权限坑 · 来源证据：Multiple Cypher correctness bugs: OPTIONAL MATCH, CONTAINS quoting, elementId parameters, write counters, RETURN after…

34. 安全/权限坑 · 来源证据：UNWIND $list AS name returns variable name as string literal instead of iterating list (Bolt, v1.1.4)

35. 安全/权限坑 · 来源证据：[BUG] Cypher correctness (v1.1.5): `SET x = <map>` replacement drops properties; `SET += <UNWIND alias>`, dynamic label…

36. 维护坑 · issue/PR 响应质量未知

37. 维护坑 · 发布节奏不明确