用途:为 VitePress、Docusaurus、Obsidian、Jekyll 等 Markdown 知识库提供结构化数据管理,frontmatter 即数据源。存储布局 v2:每个文档恰好两个同目录文件,docs/<entity>/<id>.md(正文+YAML frontmatter)与 docs/<entity>/<id>.yaml(完整性 sidecar,含 SHA 与可选 HMAC);无 data/ 目录,无聚合 records.yaml/.integrity.yaml。不同 PR 修改不同文档时文件互不重叠,可零 git 冲突合并。
主要能力:schema 管理(list/show);文档增删改查(create/get/list/query/update/delete),支持 --format json;grep 搜索与语义搜索(--semantic --k);完整性检查与修复(doctor check / check --all / fix --recompute / sign --force);v1 到 v2 迁移(doctor migrate,幂等);知识图谱构建(index build,支持 --crawl)、邻居查询(graph neighbors --depth)、导出(graph export);从 git 提交生成事件(events emit)。doctor 默认仅扫描与 HEAD 不同的文件,--all 用于全量审计;非 git 仓库自动回退 --all。退出码 0 表示成功,非零表示错误,JSON 输出会列出每个文档的原因;漂移原因包括 content_sha、frontmatter_sha、record_sha 不匹配,bad_sig、missing-sidecar、missing-md。
使用方式:先确认安装与项目状态(which sbdb、test -f .sbdb.toml);缺失时 go install github.com/sergio-bershadsky/secondbrain-db@latest 或从 releases 下载 v2.0.0+;v1 布局执行 sbdb doctor migrate。创建文档先用 sbdb schema show -s <name> --format json 查看 schema,再以 JSON 经 stdin 提交,如 echo '{"id":"my-doc",...}' | sbdb create -s notes --input -。手动编辑 .md 后运行 sbdb doctor check;content_sha 不匹配需询问用户选择 sbdb doctor sign --force 接受或 git checkout 还原,仅 frontmatter_sha/record_sha 漂移可安全执行 doctor fix --recompute。切勿直接编辑 sidecar。可作为 Go 库嵌入:import github.com/sergio-bershadsky/secondbrain-db/pkg/sbdb,使用 sbdb.Open、Repo、Doc 及 WithLogger/WithIntegrityKey 等选项;子包含 schema、query、integrity、events、kg。
适用场景与限制:适合需完整性校验、防篡改与图谱能力的 Markdown 知识库。具体收费、价格、平台支持与性能数据暂未提供。