用途:以通俗语言解释数据库 schema、模型或单条审计发现,并生成与数据库范式匹配的 Mermaid 图。只读,绝不编辑或迁移数据。
用法:/claude-db:explain $ARGUMENTS,参数为 <path|table|finding-id> [flags]。目标可以是 schema/ORM/迁移文件路径、单个表或集合名,或此前审计产生的 finding id。
主要能力:先检测范式与引擎(scripts/detect-stack.mjs),再解析模型(scripts/parse-schema.mjs / parse-orm-python.py)。开头用无术语的通俗语言说明各实体存什么、归属关系与连接方式。随后生成范式感知图:node scripts/gen-diagram.mjs --file <schema> [--paradigm relational|document|key-value|wide-column|graph]。关系型用 erDiagram 展示表、主外键与基数;文档型展示嵌套与引用树;键值型展示分区键与排序键设计;宽列型展示按查询建表与分区键布局;向量型展示集合、度量/维度与元数据过滤字段;时序型展示 hypertable/measurement、标签与保留策略;图型展示节点边与关系类型。可在通俗描述下提供可展开的技术层,含精确列类型、索引定义、约束名与删除行为。若目标是 finding id,则说明其检查内容、影响的评分轴(design | performance | both)、重要性及复现方式(verification.reproduce)。
查询与 EXPLAIN 计划模式:--query "<SQL>" 可对原始 SQL 做静态推理,指出为何慢并给出修复建议(如 SELECT *、结构性 N+1、OFFSET 深分页、非 SARGable 谓词),推荐具体索引、keyset 改写或谓词调整;粘贴 EXPLAIN/EXPLAIN ANALYZE 计划时,读取计划节点(顺序扫描、排序/哈希溢出、行数估算与实际、嵌套循环膨胀),说明哪一步是瓶颈及如何消除。若用户要求对数据库实际运行 EXPLAIN,则标记为 needs_api / Tier-2,不编造计划数字,改为静态解释或请其粘贴计划。
限制:只描述模型中实际存在的内容,不虚构列、关系、行数或延迟;若关系是隐含而非强制的(如无约束的逻辑外键),会明确说明。默认用用户语言(EN/ES)回复,--lang 可覆盖。