理解 Logseq 数据库 Schema

Logseq 自引入 DB 模式（基于 Datascript 数据库）后，许多用户的痛点从"如何写 block"转移到了"如何正确建模 entity、class、property 与 reference"。c0ntr0lledcha0s-understanding-db-schema 是面向 Claude、Codex、Claude Code 的 Logseq 知识图谱建模辅助技能，专门解决"实体如何标识、属性如何选类型、引用如何校验"等结构化难题。

技能简介

该技能由 C0ntr0lledCha0s 维护，遵循 MIT 协议，qualityScore 81、silver tier，已经过官方完整审计。它面向 Logseq DB 模式用户与插件开发者，把 Datascript 的实体-属性-值模型转化为可操作的提示词模板，让模型能像资深 Logseq 玩家一样回答 schema 设计问题。

核心能力

• Datascript 模型讲解：清晰解释 entity、attribute、value 三元组，以及 entity 在 Datascript 数据库里的 EAV）表示方式背后的核心思想。
• 属性类型与卡片语义：系统讲解 Logseq 的 reference、cardinality（one / many / many-to-one）、page / string / number / boolean / date 等类型差异。
• 内置类与继承：梳理 Logseq 内置的 page / block / class / property 等基础类，并解释它们的继承关系与命名空间。
• 配置键与校验：解释 Logseq 配置文件 :block/properties、db/ident、schema/name 等关键键的语义，以及 Malli 校验在 Logseq DB 模式里的工作流。
• 模板化 schema 编写：提供可直接复制的 user class 定义、typed property 示例、namespace 划分方案。
• 建模风险审计：识别常见错误，例如 cardinality 错选、命名冲突、namespace 不一致，并给出明确修正建议。
• 跨版本兼容性提示：在 Logseq 0.10 / 0.11 不同 DB schema 演进背景下提示 API 差异，避免脚本在新版本失效。

安装与配置

• 一行安装：执行 npx skillstore add c0ntr0lledcha0s/understanding-db-schema，Skillstore 自动同步到 claude-code-plugin-automations/logseq-expert/skills/understanding-db-schema。
• 手动安装：克隆 https://github.com/C0ntr0lledCha0s/claude-code-plugin-automations，把 logseq-expert/skills/understanding-db-schema 复制到任意项目 .claude/skills/ 下。
• 运行时依赖：纯文档型技能，不需要 Logseq 服务器、不需要 Datalog 编译器，可在 Claude / Codex / Claude Code 任一环境运行。
• 权限需求：声明 external_commands 与 network 风险因子，模型可能调用 git、curl 等基础命令以演示 schema 校验。
• 版本要求：示例基于 Logseq 0.10+ DB 模式，使用前请确认本地 Logseq 版本，文件式 graph 模式不适用。

使用步骤

1. 加载技能：在 Claude / Codex / Claude Code 中说"使用 understanding-db-schema 技能"，进入 Logseq 专家模式。
2. 询问基础：新手可让模型"向初学者解释 Logseq Datascript schema"，快速建立 entity / attribute / value 的心智模型。
3. 属性选型：遇到 book/property/set 选择困难时，提示"对比 Logseq property 类型为 {property_goal} 推荐类型与 cardinality"，获得选型建议。
4. 设计自定义类：让模型"设计一个名为 {class_name} 的 Logseq class，包含以下属性 {properties}"，输出可粘贴到 Logseq 配置文件的模板。
5. 审计 schema：拿到一段 schema 草稿后，让模型"审计此 schema：{schema_description}"，识别 cardinality / namespace / inheritance / validation 等风险。
6. 落地到 Logseq：把审计通过的 schema 段贴回 Logseq 配置文件或查询语法，重启 Logseq 让 schema 生效。

适用场景

• Logseq 插件开发者：在动手写 Datalog 查询 / schema 之前先理清数据模型。
• 个人知识库深度玩家：为自己的研究主题（读书笔记 / 项目管理 / 客户档案）设计高复用度的 schema。
• 教学场景：向新用户解释 Logseq DB 模型与文件式 graph 的本质区别。
• 迁移项目：从 Roam / Obsidian / Notion 迁来时快速建模新 DB 体系。

适用人群

• 想深入 Logseq DB 模式的高级用户与知识工作者
• 正在为 Logseq 开发插件或自动化机器人的开发者
• 借助 Claude / Codex / Claude Code 学习 Logseq 的产品经理 / 工程师
• 任何想把第二大脑"工程化"管理的用户

工作原理

技能以 SKILL.md 文档 + 提示词模板形式提供，模型加载后会自动应用 Malli 校验、entity 标识规范、namespace 划分等约束回答问题。技能本身不连接 Logseq 数据库，所有建议都基于静态 schema 文档与示例，规避了误操作真实图谱的风险。

官方链接

• Skill 详情页：https://skillstore.io/skills/c0ntr0lledcha0s-understanding-db-schema
• Manifest 接口：https://skillstore.io/api/skills/c0ntr0lledcha0s-understanding-db-schema/manifest
• 源码仓库：https://github.com/C0ntr0lledCha0s/claude-code-plugin-automations/tree/main/logseq-expert/skills/understanding-db-schema