| name | db-foundation-course |
| description | 编写"数据库筑基课"文章的专用 Skill，面向数据库架构师、DBA 和业务开发者。输入一个筑基课文章标题及相关参考资料（技术文档、产品手册、开源项目地址、deepwiki、论文等），输出图文并茂、结构完整的 Markdown 筑基课文章，保存至项目 markdown/ 目录。适用主题覆盖：表存储结构（heap/parquet/arrow/zedstore/LSM-Tree/HStore等）、索引结构（btree/gin/brin/hnsw/ivfflat/bloom等）、数据类型与操作符（vector/jsonb/tsvector/range/array等）、优化器扫描算法（seq scan/index scan/bitmap scan/join/agg/并行等）、场景化实践（时序/GIS/RAG/全文检索/图数据/数据湖等）以及事务/锁/并发/安全等周边主题。只要用户提及"筑基课"、"数据库原理"、"数据库内核"写作，或给出了数据库存储/索引/扫描相关的技术文档让你写成教程，都应使用此 Skill。 |
数据库筑基课 Skill
核心目标：让数据库架构师、DBA、业务开发者学完每篇筑基课后，能将知识直接用于工作实践，打下坚实基础。
一、工作流程总览
输入: 文章标题 + 参考资料(URL / 文档 / 论文 / 代码仓库)
│
├─ Step 1: 读取参考资料
├─ Step 2: 按"标准文章结构"起草提纲
├─ Step 3: 逐节撰写内容（含图表、代码、示例）
├─ Step 4: 自检（逻辑 / 代码 / 事实）
└─ Step 5: 输出 Markdown 文件 → markdown/<slug>.md
二、标准文章结构（模板）
每篇筑基课文章必须包含以下 12 个章节，可根据主题适当增减子节：
# 数据库筑基课 - <标题>
> 所属系列: [数据库筑基课大纲](链接)
> 难度: ★☆☆ / ★★☆ / ★★★
> 适合角色: 架构师 / DBA / 业务开发者
---
## 0. 导读（Why Read This）
## 1. 背景与痛点（Background & Pain Points）
## 2. 核心原理（Core Principles）
## 3. 数据结构 / 存储格式 / 算法详解（Deep Dive）
## 4. 优势与适合场景（Strengths & Use Cases）
## 5. 劣势与不适合场景（Weaknesses & Anti-Patterns）
## 6. 竞品 / 横向技术对比（Comparison）
## 7. 实操与最佳实践（Hands-on & Best Practices）
## 8. 性能调优（Performance Tuning）
## 9. 思考与边界（Thinking & Boundaries）
## 10. 常见问题（FAQ）
## 11. 扩展阅读（Further Reading）
三、各章节撰写指南
§ 0 导读
- 一句话点明本文解决什么问题
- 给出"读完本文你能做到什么"的 3 条 bullet
§ 1 背景与痛点
- 说明技术/功能出现前的痛苦场景（具体，有数字）
- 用对比图或叙事说明"没有它时有多难"
- 可画 mermaid 时序图 / 流程图表达痛点
§ 2 核心原理
- 先用一张总览图（mermaid / SVG / text diagram）展示整体架构
- 然后逐层展开
- 原理说明时配合类比（例如 heap 的 fsm 就像"停车场空位管理牌"）
§ 3 深度解析
根据主题选择合适的子节，参考如下分类：
存储结构类（heap/parquet/arrow/zedstore/LSM等）
- file layout（文件级结构）→ block/page layout（块级结构）→ tuple/record layout（行级结构）
- 写入流程 / 读取流程 / 更新流程 / 删除流程
- 垃圾回收 / 压缩 / Compaction
- 索引与存储的协同
索引结构类（btree/gin/brin/hnsw/bloom等）
- 索引构建算法
- 索引 page/node 的内部结构
- 搜索算法（贪婪/二分/图遍历等）
- 索引维护（插入/删除/分裂/合并）
扫描与计算类（seq scan/index scan/join/agg/并行等）
- 算法伪代码 or 流程图
- 代价模型（cost model）简介
- 执行计划解读（EXPLAIN 输出示例）
数据类型类（vector/jsonb/tsvector等）
§ 4 优势与适合场景
§ 5 劣势与不适合场景
- 明确说明边界：什么情况会变慢 / 出问题 / 不应使用
- 给出替代方案
§ 6 竞品/横向对比
- 至少对比 2～3 个同类技术，使用 Markdown 表格
- 维度：性能 / 压缩比 / 写入/读取模式 / 事务支持 / 生态 / 适用场景
§ 7 实操与最佳实践
- 给出可运行的 SQL 或代码示例
- 至少 1 个完整的场景化 Demo（建表→写入→查询→分析）
- 列出 DBA 常用的监控/诊断 SQL
- 标注关键 GUC 参数及推荐值
§ 8 性能调优
- 调优思路：从 EXPLAIN → 瓶颈定位 → 参数/DDL 调整
- 列出 TOP 5 调优手段
§ 9 思考与边界
- 给出 2～3 个"扩展问题"（类似原文的"扩展问题"章节）
- 每个问题都给出分析过程，不只给答案
- 点明该技术的本质取舍（trade-off）
§ 10 FAQ
§ 11 扩展阅读
- 分类列出：官方文档 / 论文 / 源码路径 / 博客 / 相关筑基课章节
四、图表规范
4.1 优先使用 mermaid（流程 / 关系 / 时序）
graph TD
A[Client] --> B[Buffer Pool]
B --> C{命中?}
C -- Yes --> D[直接返回]
C -- No --> E[从磁盘读取 Block]
4.2 存储结构用 text diagram（清晰表达 layout）
File Layout:
┌─────────────────────────────────┐
│ Block 0 │ Block 1 │ ... │
│ (8KB) │ (8KB) │ │
└─────────────────────────────────┘
Block Layout:
┌──────────────┬────────────────────────┐
│ Page Header │ Line Pointers (lp[]) │
├──────────────┴────────────────────────┤
│ Free Space │
├───────────────────────────────────────┤
│ Tuple N │ ... │ Tuple 2 │ Tuple 1 │
└───────────────────────────────────────┘
4.3 对比用 Markdown 表格
| 特性 | heap(行存) | parquet(列存) | zedstore(行列混存) |
|---|
| OLTP 写入 | ★★★★★ | ★★☆☆☆ | ★★★★☆ |
| OLAP 扫描 | ★★☆☆☆ | ★★★★★ | ★★★★☆ |
| ... | ... | ... | ... |
4.4 SVG（复杂的多层结构，如 HNSW 图）
在确实需要 SVG 时，使用简洁的 <svg> 内联图，宽度限制在 700px 以内。
五、代码示例规范
CREATE TABLE tbl_demo (
id BIGSERIAL PRIMARY KEY,
name TEXT,
score FLOAT
) WITH (fillfactor = 80);
INSERT INTO tbl_demo (name, score)
SELECT 'user_' || g, random() * 100
FROM generate_series(1, 100000) g;
SELECT pg_relation_filepath('tbl_demo');
SELECT * FROM heap_page_items(get_raw_page('tbl_demo', 0)) LIMIT 5;
- 代码块必须标注语言（
sql / bash / python / json）
- 关键行加注释
- 示例数据量适中（不超过百万行，能快速运行）
六、自检清单（输出前必须核对）
在生成最终文件前，逐项检查：
□ 文章结构是否覆盖了 12 个标准章节（允许合并，不允许缺失关键章节）
□ 每个技术概念是否有对应的图示（layout/流程图/对比表）
□ 所有 SQL / 代码示例是否语法正确（逐行检查关键字、括号、引号）
□ 核心原理是否有"类比"帮助理解
□ 对比章节是否客观（不只夸自己，要说出竞品优势）
□ 边界/不适合场景是否明确
□ 扩展阅读的链接格式是否正确
□ 文件名格式是否符合 <YYYYMMDD>_<slug>.md
□ 文章开头是否有"所属系列"链接 和 "难度/角色"标注
七、文件命名与保存
markdown/20240919_heap-storage.md
markdown/20241015_parquet-columnar.md
markdown/20250624_hnsw-vector-index.md
保存完毕后，输出：
- 文件的绝对路径
- 文章的章节目录（TOC）
- 3 条"读完本文你将掌握"的收益说明
八、主题速查表（常用参考）
| 主题类别 | 典型技术点 | 关联大纲章节 |
|---|
| 行存 | heap, HOT-update, vacuum, FSM, VM | 一、表组织结构 |
| 列存(磁盘) | parquet, orc, lance, vortex | 一、表组织结构 |
| 列存(内存) | arrow, monetdb in-memory, DuckDB | 一、表组织结构 |
| 行列混存 | zedstore, vops | 一、表组织结构 |
| 追加写优化 | LSM-Tree, HStore/HBase | 一、表组织结构 |
| 有序存储 | cluster table, 索引组织表 | 一、表组织结构 |
| 冷热分层 | Iceberg, Delta Lake, Hudi | 一、表组织结构 |
| 传统索引 | btree, hash, bitmap, brin, bloom, gin | 二、索引组织结构 |
| 全文索引 | gin+tsvector, BM25, zombodb | 二、索引组织结构 |
| 向量索引 | hnsw, ivfflat, pgvectorscale, vectorchord | 二、索引组织结构 |
| 特殊索引 | partial/expression/include/global index | 二、索引组织结构 |
| 数据类型 | vector, jsonb, tsvector, range, array | 三、数据类型和操作符 |
| 扫描算法 | seq/index/bitmap/index-only scan | 四、扫描&计算 |
| Join 算法 | nested loop, hash join, merge join | 四、扫描&计算 |
| 并行计算 | parallel scan, EPQ, JIT, 向量化 | 四、扫描&计算 |
| 场景实践 | 时序/GIS/RAG/全文/图/数据湖 | 五、应用实践 |
| 周边能力 | 事务/锁/连接池/安全/存储过程 | 六、其他 |
九、参考资料获取策略
当用户提供的参考资料为 URL 时：
- 使用
web_fetch 获取完整内容
- 如果是 GitHub/DeepWiki 地址，重点关注 README、核心源码注释、设计文档
- 如果是论文，重点提炼：摘要 → 核心贡献 → 关键算法 → 实验结论
- 整理成内部知识后按标准结构输出
十、示例输出片段（heap 文章节选）
## 1. 背景与痛点
数据库最基础的问题：**一条记录写到哪里？怎么找回来？**
在 heap 之前，如果要自己实现存储，可能会想到顺序存文件——但这样读一条记录需要扫全表。
heap 的设计解决了三个核心问题：
| 问题 | heap 的解法 |
|--------------|----------------------|
| 写到哪里？ | FSM 快速找空闲 block |
| 怎么定位一行？ | ctid = (blockNum, lp) |
| 怎么回收空间？ | vacuum + autovacuum |
## 2. 核心原理
### 整体架构
```
Table Files:
main: tbl.1, tbl.2, ... ← 数据文件（每个最大 1GB）
fsm: tbl_fsm ← 空闲空间图（Free Space Map）
vm: tbl_vm ← 可见性图（Visibility Map）
```
### Block 内部结构
```
┌─────────────────────────────────────────┐ ← Block（默认 8KB）
│ PageHeaderData (24B) │
│ lp[1] lp[2] lp[3] ... lp[N] │ ← Line Pointers（4B each）
│ │
│ ← Free Space → │
│ │
│ Tuple 3 Tuple 2 Tuple 1 │ ← 从尾部向前增长
└─────────────────────────────────────────┘
ctid = (BlockNum, lp_index)
例：ctid=(0,1) 表示第0块，第1条记录
```
以上即为"数据库筑基课"Skill 的完整指南。
每次生成文章后，务必运行自检清单，确认内容逻辑正确、代码可运行，再保存文件。
