explain-patterns

name	explain-patterns
description	Visual pattern library for explanation-type artifacts. Provides decision rules for choosing between annotated code blocks, call-flow diagrams, concept accordions, comparison tables, and insight cards.

Explain Patterns

解释型内容的视觉化模式库。

视觉化决策规则

何时用注释代码块

内容包含代码，且代码逻辑非线性（不能从命名直接理解）。

• 适用：状态机、并发逻辑、协议解析、巧妙优化
• 不适用：业务 CRUD、纯接口签名

何时用调用流程图

涉及多个函数/组件的调用链，顺序是理解关键。

• 适用：MQTT 上下行、数据同步、跨服务调用
• 节点 ≥3 个时优于纯文字描述

何时用概念分解手风琴

有 3+ 个并列子概念，读者不一定都需要全读。

• 用 <details>/<summary> 实现，默认折叠
• 每个子项独立标题 + 1-2 段说明

何时用对比表格

涉及两种或以上方案/技术的比较。

• 列头为对比项（性能/复杂度/成本/扩展性）
• 行头为方案名称
• 单元格用 ✓ / ✗ / "—" 或具体数值

何时用关键洞察卡片

有反直觉的结论、隐藏的约束、或高价值的最佳实践。

• 不写"显而易见"的内容
• 每条用一句话标题 + 一段说明
• 3 列卡片网格布局

模板套用顺序

定义 → 关键洞察预告（可选） → 概念分解 → 流程图/代码 → 对比 → 完整洞察 → 实施建议

内容量原则

• 详尽优于精简。所有列表项数按 complexity 分级，下限不上限
• 关键概念应充分展开：背景、机制、示例、注意事项都要谈到，不要因为字数自我设限
• 唯一的写作约束是「单条信息密度合理」（一个段落聚焦一个观点），而不是"必须 X 条以内"