explain

/claude-db:explain

以通俗易懂的语言描述架构（或某项发现），并提供一张适配范式的图示。只读——仅作说明，不会编辑或迁移。

$ARGUMENTS = <path|table|finding-id> [flags]。目标可以是架构、ORM 或迁移文件的路径、单个表／集合名称，或先前审计结果中的发现 id。

要执行的操作

1. 检测范式／引擎（scripts/detect-stack.mjs），并解析模型（scripts/parse-schema.mjs / parse-orm-python.py）。
2. 先用通俗语言描述——开篇不要使用行话：说明每个实体存储什么、归属关系如何，以及各部分如何连接。按照用户的表达方式说明（“一个用户有多个订单；每个订单恰好属于一个用户”）。
3. 使用 node scripts/gen-diagram.mjs --file <schema> [--paradigm relational|document|key-value|wide-column|graph] 绘制适配范式的图示（Mermaid）：关系型用 ERD，文档型用访问模式图，DynamoDB／KV 用键和 GSI 示意图，图数据库用节点／边图：
   • 关系型 → 使用 erDiagram，显示表、PK／FK 和基数。
   • 文档型 → 绘制嵌入／引用树，展示哪些内容是嵌套的、哪些是引用的。
   • 键值型 → 绘制访问模式／键设计示意图（分区键 + 排序键）。
   • 宽列型 → 绘制按查询划分的表／分区键布局。
   • 向量型 → 显示集合 + 度量／维度 + 元数据过滤字段。
   • 时序型 → 显示超表／度量值 + 标签 + 保留策略。
   • 图数据库 → 绘制节点和边示意图，并标注关系类型。
4. 在通俗描述下方提供可展开的技术细节：精确列类型、索引定义、约束名称、删除时的行为，供需要精确 DDL 的读者查看。
5. 如果目标是某个发现 id，说明检查内容、影响的评分／维度（设计 | 性能 | 两者）、其重要性，以及如何复现（verification.reproduce）。

查询／EXPLAIN 计划模式

两个额外输入，均复用 db-query-patterns (M13) 的分析方法：

• --query "<SQL>" —— 输入原始 SQL 语句，用通俗语言解释它为什么会慢以及如何修复：检测 M13 模式（SELECT *、结构性 N+1、深度 OFFSET 分页、非 SARGable 谓词），然后建议可供索引使用的具体索引、键集分页改写或谓词变更。此项只对查询文本进行静态分析——无需连接实际数据库。
• 粘贴 EXPLAIN 计划 —— 输入粘贴的 EXPLAIN／EXPLAIN ANALYZE 计划，解读计划节点（顺序扫描、排序／哈希溢出、估算行数与实际行数的差异、嵌套循环暴增），并说明哪一步开销最大，以及如何通过索引／改写消除该开销，同样采用 M13 分析方法。
• 如果用户希望现场生成计划（对其数据库运行 EXPLAIN），而不是粘贴计划，请将请求标记为 needs_api / Tier-2，不要捏造计划数字——改为根据查询文本进行静态分析，或请用户粘贴计划。

诚实原则

• 仅描述模型中实际存在的内容。绝不臆造列、关系、行数或延迟。如果某种关系只是隐含存在、并未强制执行（例如没有约束的逻辑 FK），请明确说明。
• 使用用户的语言回复（EN／ES）；--lang 可覆盖此设置。