与此同时，程序的「最终」版本存放在某人 2023 年桌上的 Word 文件中。Confluence 页面？过期了。Wiki？没人知道密码。

这不是假设性的噩梦。对于数千个仍然将文档视为目的地而非交付物的团队来说，这是家常便饭。

令人不安的事实是：您的文档策略是单一故障点。 而在 2029 年，当 Atlassian 永久关闭 Confluence 本地版时，这个故障将成为强制性的。

但有一条出路。它叫做文档即代码（Document as Code，DaC）。不，这不仅仅是「用 Markdown 写作」。这是团队思考知识方式的根本转变。

1 问题：文档坟墓

让我们点明房间里的大象。

Word 文档墓地

📁 共享硬盘/  📁 Operations/    📄 Runbook_FINAL.docx    📄 Runbook_FINAL_v2.docx    📄 Runbook_FINAL_v2_UPDATED.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL_REALLY.docx

现实情况：

• 没人知道哪个版本是权威的
• 变更需要「追踪修订」和电子邮件往来
• 搜索？祝你好运
• 访问控制？要么每个人都有，要么完全没有

Confluence 陷阱

Confluence 承诺提供有组织、可搜索的知识。但它带来的是：

Wiki 的狂野西部

Wiki 始于「每个人都可以编辑！」，变成了「没人拥有这个。」

🌐 内部 Wiki  ├── 📄 入门指南（最后更新：2021 年）  ├── 📄 架构概览（图片损坏）  ├── 📄 值班程序（密码：？？？）  └── 📄 [404 页面未找到]

模式： 所有这三种方法都共享同一个致命缺陷——文档与工作分离。

2 什么是文档即代码？

文档即代码将文档视为软件：

但 DaC 与「仅使用 Markdown」的不同之处在于：

不仅仅是 Markdown。是 Git。

❌ 「我们使用 Markdown」→ 共享硬盘上的文件✅ 「我们使用文档即代码」→ 基于 Git 的工作流程，具有版本控制

什么是 Git？（给非技术读者）

Git 是一个随时间追踪文件变更的工具。把它想象成文档的时光机。

每次您保存变更时，Git 都会拍摄快照。您以后可以回到任何快照——昨天的版本、上周的，甚至一年前的。没有什么会丢失。

为什么 Git 被建立

问题（Git 之前）：  👤 人员 A：「我正在编辑文件！」  👤 人员 B：「我也是！」  → 两人都保存 → 一个人的变更为丢失 😱解决方案（使用 Git）：  👤 人员 A：「我在自己的副本上编辑」  👤 人员 B：「我也在自己的副本上编辑」  → 两人都完成 → Git 安全地合并变更 ✅

现实类比

Google 文档版本历史 的工作原理类似——每次保存都会记录谁变更了什么。Git 也这样做，但有三个关键差异：

1. 离线运作 — 不需要互联网
2. 电脑上的完整副本 — 每个版本，永远
3. 没有厂商锁定 — 您的数据保持属于您

这对您意味着什么

• 没有互联网？ 没问题。一切都是本地的。
• 服务器宕机？ 您有完整的备份。
• 厂商消失？ 您的数据是您的。
• 犯了错误？ 即时还原到任何时间点。

Git 很难学吗？

对开发者来说，Git 是日常工作——他们已经知道了。

对非技术用户来说，您不需要学习 Git 命令。现代工具（GitHub Web UI、AI 助理）处理复杂性。您只需编辑——Git 在后台运作。

安全超能力：Git 就像文档的区块链

这是强大的部分：Git 使用密码学使历史记录防篡改。

每次变更都会获得一个独特的指纹（称为「哈希」）。这个指纹是根据以下内容计算的：

• 您变更的内容
• 上次变更的指纹
• 谁进行了变更以及何时

这创建了一个指纹链——就像区块链一样。如果有人试图篡改历史记录（比如删除谁批准变更的证据），指纹就不再匹配。篡改行为会立即被检测到。

Confluence 和 Word 无法做到这一点。它们的日志可以由管理员修改。Git 的历史记录无法被静默更改。

提交签署：变更的数字签章

Git 有一个更强大的安全功能：提交签署。

每个人都获得一个个人证书（就像数字身份证）。当您保存变更时，Git 会用您的证书签署它。签名证明：「这个变更来自我，我批准它。」

现实类比：

传统 Git 提交：  👤 「John 批准了此变更」  → 您相信系统正确记录了这个签署的 Git 提交：  👤 「John 批准了此变更」✍️ [数字签署]  → 密码学证明 John 批准了它  → John 的证书验证签名  → 没有 John 的私钥就无法伪造

为什么签署很重要：

• 防止冒充 — 没人能假装是您
• 法律有效性 — 签署的提交在法庭上有效（就像亲笔签名）
• 供应链安全 — 确切知道谁批准了每次变更
• 合规性 — 某些受监管产业需要

实际情况：

✅ 已验证提交 abc123 由 John Doe (john@company.com)⚠️ 未验证提交 def456 由 unknown@example.com

GitHub 和 GitLab 在签署的提交上显示绿色「Verified」徽章。如果有人试图伪造您的提交，签名将不匹配——立即暴露。

Git 的差异

纯 Markdown 文件（没有 Git）：

• 版本历史记录：仅文件时间戳
• 协作：覆盖冲突
• 离线访问：是（本地文件）
• 审核追踪：手动记录
• 回滚：「有人有旧版本吗？」
• 分布式：集中式文件服务器

使用 Git 的文档即代码：

• 版本历史记录：每次变更都被追踪，谁/何时/为什么
• 协作：分支、合并、解决冲突
• 离线访问：是（完整的 repo 克隆）
• 审核追踪：不可变的提交历史记录（密码学保护）
• 回滚：git revert — 即时恢复
• 分布式：每个克隆都是完整的备份

关键洞察

Git 本质上是去中心化的。每个开发者都有文档存储库的完整副本。这意味着：

• 没有单一故障点
• 离线运作（对沙盒/气隙环境至关重要）
• 无需登录即可阅读
• 没有厂商能挟持您的知识

现在我们了解了基础，让我们探讨为什么这种架构在系统故障时很重要。

3 操作手册测试：凌晨三点会发生什么？

让我们用文档即代码重播我们的开场情境。

凌晨三点。生产事故。无法访问互联网（沙盒环境）。

使用传统文档：

工程师：「让我检查操作手册……」  ↓开启浏览器 → Confluence 登录 → 没有网络  ↓致电队友 → 「Wiki 密码是什么？」  ↓队友：「我想在 LastPass 里……」  ↓LastPass → 没有网络 → 无法同步  ↓[事故升级，同时寻找凭证]

解决时间： 45 分钟（包括 38 分钟寻找文档）

使用文档即代码：

工程师：「让我检查操作手册……」  ↓开启终端机 → `cd runbooks` → 已经本地克隆  ↓`grep "database failover" *.md` → 即时搜索  ↓遵循程序 → 系统恢复  ↓提交事故笔记 → `git commit -m "Incident #2026-0329"`

解决时间： 7 分钟（全部用于修复问题）

看到了 DaC 在压力下的表现，让我们检查使其值得采用的实际优势。

4 为什么文档即代码获胜

1. 导出为任何格式

您的利益相关者想要 Word？PDF？Confluence？没问题。

自动化运作方式：

您将变更保存到 Git        ↓自动化检测变更        ↓构建 PDF 版本        ↓构建 Word 版本        ↓更新网站        ↓（可选）同步到 Confluence        ↓完成 — 所有格式自动更新

这取代了什么：

实际自动化配置如下：

# CI/CD 管线构建多种格式on:  push:    branches: [main]jobs:  build-docs:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      # 转换为 PDF      - name: Build PDF        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.pdf      # 转换为 Word（给坚持的利益相关者）      - name: Build Word        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.docx      # 同步到 Confluence（给还没准备好放弃的团队）      - name: Sync to Confluence        uses: docker://confluence-publisher        with:          args: --source ./docs --space OPS

什么是 CI/CD？ 这是每当您的文档变更时执行的自动化。把它想象成机器人助理：您将变更保存到 Git，它会自动构建 PDF、Word 文档和网站——无需手动步骤。

魔法： 写一次（Markdown），发布到各处（PDF、Word、HTML、Confluence）。

2. 可扫描的安全性

传统文档是安全盲点：

🔍 安全团队：「我们可以扫描 Word 文档是否有机密吗？」👤 IT 管理员：「它们在文件服务器上。我们需要……」🔍 安全团队：「那 Confluence 呢？」👤 IT 管理员：「那是 SaaS。您需要 API 访问和……」🔍 安全团队：*叹息*

文档即代码是安全透明的：

范例：扫描意外机密

# 扫描所有文档是否泄漏的密码或 API 密钥$ gitleaks detect --source ./docs --report-path secrets.json# 搜索常见的敏感模式$ grep -r "password\|api_key\|secret" ./docs/*.md# 在保存变更前自动执行检查$ pre-commit run --all-files

这些命令的作用： 第一个命令执行安全性扫描器，寻找密码、API 密钥和令牌。第二个搜索常见的敏感字词。第三个在每次有人尝试保存变更时自动执行——在保存之前封锁任何可疑内容。

会抓到什么：

3. 2029 Confluence 迁移

让我们面对现实：Confluence Data Center 将于 2029 年 3 月 28 日变为只读。

您的选项：

Confluence Cloud 的实际成本：

企业（1000 用户）：  - Confluence Cloud：~$120,000/年  - 必要附加组件：~$30,000/年  - 迁移服务：~$50,000（一次性）  - 培训：~$20,000  第 1 年总计：~$220,000  第 3 年总计：~$410,000

文档即代码成本：

企业（1000 用户）：  - Git 托管（GitHub/GitLab）：~$20,000/年（通常已支付）  - 静态网站生成器：$0（开源）  - CI/CD：$0-$10,000/年（通常包含）  - 培训：~$20,000（一次性）  第 1 年总计：~$50,000  第 3 年总计：~$80,000

3 年节省：~$330,000（而且您拥有您的数据）

财务和战略优势明确后，让我们检查文档即代码面临真正挑战的地方。

5 AI 优势：为什么 DaC 是 AI 助理的完美选择

这是转折：文档即代码是您能选择的最 AI 友好的文件格式。

低成本，高影响

代币经济：

AI 助理按代币收费（大约 1 代币 = 1 个单词）。比较：

为什么 Markdown 获胜：

Markdown：     "# Runbook：Database Failover" → 干净，最少代币Word DOCX：    "<w:document><w:p><w:r><w:t>Runbook...</w:t></w:r></w:p>..." → XML 膨胀Confluence：   "<div class='content'><h1>Runbook</h1><span data-...>..." → HTML 噪声

计算： 使用 AI 更新 100 个文档页面：

• Markdown： API 成本约 $0.10
• Word/Confluence： API 成本约 $0.60-1.00
• 节省： AI 处理成本降低 80-90%

命令行 + AI 代理 = 完美搭配

AI 代理喜欢命令行工具。 原因如下：

🤖 AI 代理：「我将更新 PostgreSQL 16 的操作手册」步骤 1：克隆存储库          → `git clone ...`步骤 2：寻找相关文件        → `grep -r "PostgreSQL" docs/`步骤 3：阅读当前内容        → `cat docs/runbooks/db-failover.md`步骤 4：产生更新的内容      → （AI 写新版本）步骤 5：保存变更            → `git add && git commit`步骤 6：建立拉取请求         → `gh pr create ...`✅ 30 秒内完成

为什么这有效：

与 Confluence 对比：

🤖 AI 代理：「我将更新 Confluence 页面……」步骤 1：透过 OAuth 验证     → 代币交换，API 密钥步骤 2：透过 REST API 取得页面   → HTTP 请求，速率限制步骤 3：解析 HTML 内容        → 移除标签，处理编码步骤 4：产生更新的内容      → （AI 写新版本）步骤 5：转换回 HTML          → 重新新增格式，宏步骤 6：透过 API 发布         → HTTP POST，处理冲突❌ 复杂度增加 10 倍，速度慢 5 倍，API 速率限制

视觉图表：Mermaid 图表

Markdown 现在本机支持图表：

flowchart LR    A[侦测到事故] --> B{严重性？}    B -->|关键| C[呼叫值班人员]    B -->|低| D[记录工单]    C --> E[启动操作手册]    D --> F[监控]

渲染为：

Zmxvd2NoYXJ0IExSCiAgICBBW+S+pua1i+WIsOS6i+aVhV0gLS0+IEJ75Lil6YeN5oCn77yffQogICAgQiAtLT585YWz6ZSufCBDW+WRvOWPq+WAvOePreS6uuWRmF0KICAgIEIgLS0+fOS9jnwgRFvorrDlvZXlt6XljZVdCiAgICBDIC0tPiBFW+WQr+WKqOaTjeS9nOaJi+WGjF0KICAgIEQgLS0+IEZb55uR5o6nXQ==

AI + Mermaid = 即时图表：

👤 用户：「建立我们部署流程的流程图」🤖 AI：*产生 Mermaid 代码*✅ 结果：专业图表，无需设计技能

支持的图表类型：

学习曲线正在变平

当时（2020）：

👤 非技术用户：「什么是 Markdown？」🔧 工程师：「就像是带有符号的纯文字……」👤 非技术用户：「我在哪里编辑？」🔧 工程师：「您需要文字编辑器，或者也许……」😓 摩擦：高

现在（2026）：

👤 非技术用户：「我如何编辑？」选项 1：GitHub Web UI（所见即所得模式）  - 点击编辑 → 看到格式化视图 → 保存选项 2：Notion（导出为 Markdown）  - 视觉化写作 → 导出为 .md选项 3：Google Docs（具有 Markdown 转换器）  - 在 Docs 中写作 → 自动转换为 .md选项 4：Microsoft Word（保存为 Markdown）  - 内建支持😓 摩擦：低且正在减少

趋势： 所见即所得编辑器正在新增 Markdown 支持，而不是取代它。

AI 代理普及 Markdown

现实： 非技术用户不再需要学习 Git 命令。

👤 营销经理：「更新首页文案」2020 工作流程：  - 学习 Git 基础  - 克隆存储库  - 在文字编辑器中编辑文件  - 执行 Git 命令  - 开启拉取请求  - 等待审查2026 工作流程：  - 告诉 AI 代理：「更新首页文案为 X」  - AI 建立分支，编辑文件，开启 PR  - 审查通知到达 Slack  - 点击「批准」→ 完成

弥合差距的 AI 工具：

结论： Markdown + Git 曾经是「开发者技能」。随着 AI 代理，它正在成为通用技能——就像打字一样。

6 残酷的真相：DaC 的挣扎之处

文档即代码并不完美。以下是它真正不足的地方：

挑战 1：非技术协作

问题：

👤 营销经理：「我如何建议编辑？」🔧 工程师：「Fork 存储库，建立分支，提交，开启 PR……」👤 营销经理：*默默地发送 Slack 讯息*

现实检查： Git 有学习曲线。对于没有开发经验的团队，工作流程感觉陌生。

!!! success "✅ AI 的一线希望」
AI 代理正在迅速减少这种摩擦。像Claude Code、GitHub Copilot和Cursor这样的工具现在可以：
- 从自然语言执行 Git 命令（「建立分支并更新操作手册」）
- 用简单的英语解释每个命令的作用
- 自动产生提交讯息和拉取请求描述

差距比预期更快地缩小。 2023 年需要 Git 培训的内容，2026 年可以透过聊天完成。

缓解策略：

挑战 2：没有内嵌评论

问题：

Confluence 和 Google Docs 擅长内嵌评论：

📄 Confluence 页面：  「重新启动数据库服务」  └─ 💬 评论：「哪个服务？postgresql.service 还是 mysqld.service？」  └─ 💬 评论：「这个步骤在 staging 中对我失败了」  └─ 💬 评论：「在 PR #452 中更新了命令」

Markdown 文件没有本机的内嵌评论。

解决方案：

挑战 3：视觉协作

问题：

一些团队在视觉协作中茁壮成长：

🎨 Google Docs：  - 高亮文字 → 新增评论 → 分配给人员  - 看到其他人即时编辑的游标  - 建议模式 → 视觉化接受/拒绝变更

Git 本质上是异步的。即时协作不是它的强项。

什么时候重要：

挑战 4：「我在哪里编辑？」问题

问题：

新贡献者面临摩擦：

👤 新团队成员：「我发现操作手册中有错字。我如何修复它？」传统：  - 点击「编辑」按钮 → 输入 → 保存 → 完成文档即代码：  - 克隆存储库（或导航到网页……）  - 建立分支（或在网页上编辑）  - 进行变更  - 写提交讯息  - 建立拉取请求  - 等待审查  - 合并（或请求合并）

摩擦税： 与 wiki 式编辑相比，每次编辑需要约 5-10 个额外步骤。

缓解：

范例：贡献者的简单指南

# .github/CONTRIBUTING.md## 如何更新文档### 快速修正（错字，小变更）1. 在 GitHub 上导航到文件2. 点击 ✏️ 铅笔图示3. 进行您的变更4. 写简短描述5. 点击「建议变更」6. 完成！我们将审查并合并。### 较大的变更1. Fork 存储库2. 建立分支：`git checkout -b fix/my-change`3. 编辑文件4. 提交：`git commit -m "fix：描述您的变更"`5. 推送：`git push origin fix/my-change`6. 开启拉取请求

明确的指导显著减少摩擦。

承认挑战后，让我们探讨采用文档即代码的团队的实际策略。

7 让 DaC 运作：实用指南

从小处开始，快速获胜

第 1-2 周：试点项目

📁 docs/  └── runbooks/      ├── incident-response.md      ├── database-failover.md      └── deployment-procedure.md

选择一个高价值、技术受众（例如，值班工程师）。获得他们的支持。让他们亲身体验离线优势。

建立桥梁，而不是墙

不要： 「Confluence 现在对我们来说死了。」

要： 「让我们在迁移期间同时执行两者。」

范例：在过渡期间自动同步到 Confluence

# CI/CD 同步 DaC → Confluence（临时）- name: Publish to Confluence  if: github.ref == 'refs/heads/main'  uses: confluence-publisher@v1  with:    space: OPS    parent: "Operations Runbooks"

这的作用： 每当文档更新时，它会自动发布副本到 Confluence。这让团队可以继续使用 Confluence，同时逐渐采用文档即代码——没有突然的中断。

这给利益相关者时间适应，同时证明 DaC 的价值。

投资工具

基本堆叠：

可有可无：

定义工作流程

给工程师：

实际情况：

# 1. 为您的变更建立新分支git checkout -b docs/update-failover-procedure# 2. 开启并编辑文档文件code docs/runbooks/database-failover.md# 3. 在浏览器中预览外观mkdocs serve  # 开启在 http://localhost:8000# 4. 将您的变更保存到版本控制git add docs/runbooks/database-failover.mdgit commit -m "docs：更新 PostgreSQL 16 的故障转移步骤"git push origin docs/update-failover-procedure# 5. 请求团队审查gh pr create --title "docs：更新故障转移步骤" --body "更新 PG16 兼容性"

翻译： 每个命令做一件事——建立工作区、编辑文件、预览、保存它，并请求队友审查。bash 符号如 # 只是解释每个步骤作用的注释。

给非工程师：

1. 在 GitHub/GitLab 上导航到文件2. 点击「编辑」（铅笔图示）3. 进行您的变更4. 写下变更的简短描述5. 点击「建议变更」6. 团队成员将审查并合并

衡量成功

追踪这些指标：

现在我们有了实际实施策略，让我们检查不同类型组织的战略影响。

8 战略视角：谁应该采用 DaC？

完美适合 ✅

需要培训的良好适合 ⚠️

不适合 ❌

总结：文档的十字路口

Zmxvd2NoYXJ0IExSCiAgICBBW+S7iuaXpeaWh+aho10gLS0+IEJ76YCJ5oup5oKo55qE6Lev5b6EfQogICAgQiAtLT4gQ1tDb25mbHVlbmNlIENsb3VkIDIwMjldCiAgICBCIC0tPiBEW+aWh+aho+WNs+S7o+eggV0KICAgIEIgLS0+IEVb546w54q2XQoKICAgIEMgLS0+IEZbU2FhUyDkvp3otZY8YnIvPuaMgee7reaIkOacrDxici8+6ZyA6KaB55m75b2VXQogICAgRCAtLT4gR1vmi6XmnInmgqjnmoTmlbDmja48YnIvPuemu+e6v+iuv+mXrjxici8+5a6J5YWo5omr5o+PXQogICAgRSAtLT4gSFvmioDmnK/lgLrliqE8YnIvPuefpeivhua1geWksTxici8+MjAyOSDljbHmnLpdCgogICAgc3R5bGUgRCBmaWxsOiNlOGY1ZTksc3Ryb2tlOiMzODhlM2MKICAgIHN0eWxlIEMgZmlsbDojZmZmM2UwLHN0cm9rZTojZjU3YzAwCiAgICBzdHlsZSBFIGZpbGw6I2ZmZWJlZSxzdHJva2U6I2M2MjgyOA==

选择：

结论：

文档即代码不是关于 Markdown。是关于所有权。

当您的文档存放在 Git 中：

• 📖 您拥有数据 — 没有厂商能挟持它
• 🔓 离线运作 — 关键时刻网络故障时
• 🔍 可扫描 — 内建安全和合规
• 📦 可导出到任何地方 — PDF、Word、Confluence（如果您必须）
• 📜 有历史记录 — 每次变更被追踪、可还原、可审核
• 🔒 防篡改 — 密码学保护，像区块链
• 🤖 AI 就绪 — 最低代币成本，命令行友好，Mermaid 图表

挑战是真实的——非技术协作、内嵌评论、视觉工作流程。但这些是可解决的问题，不是根本缺陷。

而在 2029 年，当 Confluence 本地版终止，您的合规团队问*「我们的文档在哪里？」*——您会想要一个不涉及恐慌迁移的答案。

从小处开始。选择一个操作手册。克隆一个存储库。亲身体验离线优势。

因为种树最好的时间是 20 年前。第二好的时间是在厂商关闭您的服务器之前。

进一步阅读

• GitHub Docs：Documentation as Code
• Atlassian Confluence End-of-Life Announcement
• gitleaks：Secret Scanning Tool
• Mermaid：Diagrams and Flowcharts in Markdown

與此同時，程序的「最終」版本存放在某人 2023 年桌上的 Word 文件中。Confluence 頁面？過期了。Wiki？沒人知道密碼。

這不是假設性的噩夢。對於數千個仍然將文件視為目的地而非交付物的團隊來說，這是家常便飯。

令人不安的事實是：您的文件策略是單一故障點。 而在 2029 年，當 Atlassian 永久關閉 Confluence 本機版時，這個故障將成為強制性的。

但有一條出路。它叫做文件即程式碼（Document as Code，DaC）。不，這不僅僅是「用 Markdown 寫作」。這是團隊思考知識方式的根本轉變。

1 問題：文件墳墓

讓我們點明房間裡的大象。

Word 文件墓地

📁 共用硬碟/  📁 Operations/    📄 Runbook_FINAL.docx    📄 Runbook_FINAL_v2.docx    📄 Runbook_FINAL_v2_UPDATED.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL_REALLY.docx

現實情況：

• 沒人知道哪個版本是權威的
• 變更需要「追蹤修訂」和電子郵件往來
• 搜尋？祝你好運
• 存取控制？要嘛每個人都有，要嘛完全沒有

Confluence 陷阱

Confluence 承諾提供有組織、可搜尋的知識。但它帶來的是：

Wiki 的狂野西部

Wiki 始於「每個人都可以編輯！」，變成了「沒人擁有這個。」

🌐 內部 Wiki  ├── 📄 入門指南（最後更新：2021 年）  ├── 📄 架構概覽（圖片損壞）  ├── 📄 值班程序（密碼：？？？）  └── 📄 [404 頁面未找到]

模式： 所有這三種方法都共享同一個致命缺陷——文件與工作分離。

2 什麼是文件即程式碼？

文件即程式碼將文件視為軟體：

但 DaC 與「僅使用 Markdown」的不同之處在於：

不僅僅是 Markdown。是 Git。

❌ 「我們使用 Markdown」→ 共用硬碟上的檔案✅ 「我們使用文件即程式碼」→ 基於 Git 的工作流程，具有版本控制

什麼是 Git？（給非技術讀者）

Git 是一個隨時間追蹤檔案變更的工具。把它想像成文件的時光機。

每次您儲存變更時，Git 都會拍攝快照。您以後可以回到任何快照——昨天的版本、上週的，甚至一年前的。沒有什麼會丟失。

為什麼 Git 被建立

問題（Git 之前）：  👤 人員 A：「我正在編輯檔案！」  👤 人員 B：「我也是！」  → 兩人都儲存 → 一個人的變更為遺失 😱解決方案（使用 Git）：  👤 人員 A：「我在自己的副本上編輯」  👤 人員 B：「我也在自己的副本上編輯」  → 兩人都完成 → Git 安全地合併變更 ✅

現實類比

Google 文件版本歷史 的工作原理類似——每次儲存都會記錄誰變更了什麼。Git 也這樣做，但有三個關鍵差異：

1. 離線運作 — 不需要網際網路
2. 電腦上的完整副本 — 每個版本，永遠
3. 沒有廠商鎖定 — 您的資料保持屬於您

這對您意味著什麼

• 沒有網際網路？ 沒問題。一切都是本機的。
• 伺服器當機？ 您有完整的備份。
• 廠商消失？ 您的資料是您的。
• 犯了錯誤？ 即時還原到任何時間點。

Git 很難學嗎？

對開發者來說，Git 是日常工作——他們已經知道了。

對非技術使用者來說，您不需要學習 Git 命令。現代工具（GitHub Web UI、AI 助理）處理複雜性。您只需編輯——Git 在背景運作。

安全超能力：Git 就像文件的區塊鏈

這是強大的部分：Git 使用密碼學使歷史記錄防篡改。

每次變更都會獲得一個獨特的指紋（稱為「雜湊」）。這個指紋是根據以下內容計算的：

• 您變更的內容
• 上次變更的指紋
• 誰進行了變更以及何時

這創建了一個指紋鏈——就像區塊鏈一樣。如果有人試圖篡改歷史記錄（比如刪除誰批准變更的證據），指紋就不再匹配。篡改行為會立即被檢測到。

Confluence 和 Word 無法做到這一點。它們的日誌可以由管理員修改。Git 的歷史記錄無法被靜默更改。

提交簽署：變更的數位簽章

Git 有一個更強大的安全功能：提交簽署。

每個人都獲得一個個人憑證（就像數位身分證）。当您儲存變更時，Git 會用您的憑證簽署它。簽名證明：「這個變更來自我，我批准它。」

現實類比：

傳統 Git 提交：  👤 「John 批准了此變更」  → 您相信系統正確記錄了這個簽署的 Git 提交：  👤 「John 批准了此變更」✍️ [數位簽署]  → 密碼學證明 John 批准了它  → John 的憑證驗證簽名  → 沒有 John 的私鑰就無法偽造

為什麼簽署很重要：

• 防止冒充 — 沒人能假裝是您
• 法律有效性 — 簽署的提交在法庭上有效（就像親筆簽名）
• 供應鏈安全 — 確切知道誰批准了每次變更
• 合規性 — 某些受監管產業需要

實際情況：

✅ 已驗證提交 abc123 由 John Doe (john@company.com)⚠️ 未驗證提交 def456 由 unknown@example.com

GitHub 和 GitLab 在簽署的提交上顯示綠色「Verified」徽章。如果有人試圖偽造您的提交，簽名將不匹配——立即暴露。

Git 的差異

純 Markdown 檔案（沒有 Git）：

• 版本歷史記錄：僅檔案時間戳
• 協作：覆蓋衝突
• 離線存取：是（本機檔案）
• 審核追蹤：手動記錄
• 回滾：「有人有舊版本嗎？」
• 分散式：集中式檔案伺服器

使用 Git 的文件即程式碼：

• 版本歷史記錄：每次變更都被追蹤，誰/何時/為什麼
• 協作：分支、合併、解決衝突
• 離線存取：是（完整的 repo 克隆）
• 審核追蹤：不可變的提交歷史記錄（密碼學保護）
• 回滾：git revert — 即時恢復
• 分散式：每個克隆都是完整的備份

關鍵洞察

Git 本質上是去中心化的。每個開發者都有文件儲存庫的完整副本。這意味著：

• 沒有單一故障點
• 離線運作（對沙盒/氣隙環境至關重要）
• 無需登入即可閱讀
• 沒有廠商能挾持您的知識

現在我們了解了基礎，讓我們探討為什麼這種架構在系統故障時很重要。

3 操作手冊測試：凌晨三點會發生什麼？

讓我們用文件即程式碼重播我們的開場情境。

凌晨三點。生產事故。無法存取網際網路（沙盒環境）。

使用傳統文件：

工程師：「讓我檢查操作手冊……」  ↓開啟瀏覽器 → Confluence 登入 → 沒有網路  ↓致電隊友 → 「Wiki 密碼是什麼？」  ↓隊友：「我想在 LastPass 裡……」  ↓LastPass → 沒有網路 → 無法同步  ↓[事故升級，同時尋找憑證]

解決時間： 45 分鐘（包括 38 分鐘尋找文件）

使用文件即程式碼：

工程師：「讓我檢查操作手冊……」  ↓開啟終端機 → `cd runbooks` → 已經本機克隆  ↓`grep "database failover" *.md` → 即時搜尋  ↓遵循程序 → 系統恢復  ↓提交事故筆記 → `git commit -m "Incident #2026-0329"`

解決時間： 7 分鐘（全部用於修復問題）

看到了 DaC 在壓力下的表現，讓我們檢查使其值得採用的實際優勢。

4 為什麼文件即程式碼獲勝

1. 匯出為任何格式

您的利害關係人想要 Word？PDF？Confluence？沒問題。

自動化運作方式：

您將變更儲存到 Git        ↓自動化檢測變更        ↓建構 PDF 版本        ↓建構 Word 版本        ↓更新網站        ↓（可選）同步到 Confluence        ↓完成 — 所有格式自動更新

這取代了什麼：

實際自動化配置如下：

# CI/CD 管線建構多種格式on:  push:    branches: [main]jobs:  build-docs:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      # 轉換為 PDF      - name: Build PDF        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.pdf      # 轉換為 Word（給堅持的利害關係人）      - name: Build Word        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.docx      # 同步到 Confluence（給還沒準備好放棄的團隊）      - name: Sync to Confluence        uses: docker://confluence-publisher        with:          args: --source ./docs --space OPS

什麼是 CI/CD？ 這是每當您的文件變更時執行的自動化。把它想像成機器人助理：您將變更儲存到 Git，它會自動建構 PDF、Word 文件和網站——無需手動步驟。

魔法： 寫一次（Markdown），發布到各處（PDF、Word、HTML、Confluence）。

2. 可掃描的安全性

傳統文件是安全盲點：

🔍 安全團隊：「我們可以掃描 Word 文件是否有機密嗎？」👤 IT 管理員：「它們在檔案伺服器上。我們需要……」🔍 安全團隊：「那 Confluence 呢？」👤 IT 管理員：「那是 SaaS。您需要 API 存取和……」🔍 安全團隊：*嘆息*

文件即程式碼是安全透明的：

範例：掃描意外機密

# 掃描所有文件是否有洩漏的密碼或 API 金鑰$ gitleaks detect --source ./docs --report-path secrets.json# 搜尋常見的敏感模式$ grep -r "password\|api_key\|secret" ./docs/*.md# 在儲存變更前自動執行檢查$ pre-commit run --all-files

這些命令的作用： 第一個命令執行安全性掃描器，尋找密碼、API 金鑰和權杖。第二個搜尋常見的敏感字詞。第三個在每次有人嘗試儲存變更時自動執行——在儲存之前封鎖任何可疑內容。

會抓到什麼：

3. 2029 Confluence 遷移

讓我們面對現實：Confluence Data Center 將於 2029 年 3 月 28 日變為唯讀。

您的選項：

Confluence Cloud 的實際成本：

企業（1000 使用者）：  - Confluence Cloud：~$120,000/年  - 必要附加元件：~$30,000/年  - 遷移服務：~$50,000（一次性）  - 培訓：~$20,000  第 1 年總計：~$220,000  第 3 年總計：~$410,000

文件即程式碼成本：

企業（1000 使用者）：  - Git 託管（GitHub/GitLab）：~$20,000/年（通常已支付）  - 靜態網站產生器：$0（開源）  - CI/CD：$0-$10,000/年（通常包含）  - 培訓：~$20,000（一次性）  第 1 年總計：~$50,000  第 3 年總計：~$80,000

3 年節省：~$330,000（而且您擁有您的資料）

財務和戰略優勢明確後，讓我們檢查文件即程式碼面臨真正挑戰的地方。

5 AI 優勢：為什麼 DaC 是 AI 助理的完美選擇

這是轉折：文件即程式碼是您能選擇的最 AI 友好的文件格式。

低成本，高影響

代幣經濟：

AI 助理按代幣收費（大約 1 代幣 = 1 個單字）。比較：

為什麼 Markdown 獲勝：

Markdown：     "# Runbook：Database Failover" → 乾淨，最少代幣Word DOCX：    "<w:document><w:p><w:r><w:t>Runbook...</w:t></w:r></w:p>..." → XML 膨脹Confluence：   "<div class='content'><h1>Runbook</h1><span data-...>..." → HTML 雜訊

計算： 使用 AI 更新 100 個文件頁面：

• Markdown： API 成本約 $0.10
• Word/Confluence： API 成本約 $0.60-1.00
• 節省： AI 處理成本降低 80-90%

命令列 + AI 代理 = 完美搭配

AI 代理喜歡命令列工具。 原因如下：

🤖 AI 代理：「我將更新 PostgreSQL 16 的操作手冊」步驟 1：克隆儲存庫          → `git clone ...`步驟 2：尋找相關檔案        → `grep -r "PostgreSQL" docs/`步驟 3：閱讀當前內容        → `cat docs/runbooks/db-failover.md`步驟 4：產生更新的內容      → （AI 寫新版本）步驟 5：儲存變更            → `git add && git commit`步驟 6：建立拉取請求         → `gh pr create ...`✅ 30 秒內完成

為什麼這有效：

與 Confluence 對比：

🤖 AI 代理：「我將更新 Confluence 頁面……」步驟 1：透過 OAuth 驗證     → 代幣交換，API 金鑰步驟 2：透過 REST API 取得頁面   → HTTP 請求，速率限制步驟 3：解析 HTML 內容        → 移除標籤，處理編碼步驟 4：產生更新的內容      → （AI 寫新版本）步驟 5：轉換回 HTML          → 重新新增格式，巨集步驟 6：透過 API 發布         → HTTP POST，處理衝突❌ 複雜度增加 10 倍，速度慢 5 倍，API 速率限制

視覺圖表：Mermaid 圖表

Markdown 現在本機支援圖表：

flowchart LR    A[偵測到事故] --> B{嚴重性？}    B -->|關鍵| C[呼叫值班人員]    B -->|低| D[記錄工單]    C --> E[啟動操作手冊]    D --> F[監控]

渲染為：

Zmxvd2NoYXJ0IExSCiAgICBBW+WBtea4rOWIsOS6i+aVhV0gLS0+IEJ75Zq06YeN5oCn77yffQogICAgQiAtLT586Zec6Y21fCBDW+WRvOWPq+WAvOePreS6uuWToV0KICAgIEIgLS0+fOS9jnwgRFvoqJjpjITlt6Xllq5dCiAgICBDIC0tPiBFW+WVn+WLleaTjeS9nOaJi+WGil0KICAgIEQgLS0+IEZb55uj5o6nXQ==

AI + Mermaid = 即時圖表：

👤 使用者：「建立我們部署流程的流程圖」🤖 AI：*產生 Mermaid 程式碼*✅ 結果：專業圖表，無需設計技能

支援的圖表類型：

學習曲線正在變平

當時（2020）：

👤 非技術使用者：「什麼是 Markdown？」🔧 工程師：「就像是帶有符號的純文字……」👤 非技術使用者：「我在哪裡編輯？」🔧 工程師：「您需要文字編輯器，或者也許……」😓 摩擦：高

現在（2026）：

👤 非技術使用者：「我如何編輯？」選項 1：GitHub Web UI（所見即所得模式）  - 點擊編輯 → 看到格式化視圖 → 儲存選項 2：Notion（匯出為 Markdown）  - 視覺化寫作 → 匯出為 .md選項 3：Google Docs（具有 Markdown 轉換器）  - 在 Docs 中寫作 → 自動轉換為 .md選項 4：Microsoft Word（儲存為 Markdown）  - 內建支援😓 摩擦：低且正在減少

趨勢： 所見即所得編輯器正在新增 Markdown 支援，而不是取代它。

AI 代理普及 Markdown

現實： 非技術使用者不再需要學習 Git 命令。

👤 行銷經理：「更新首頁文案」2020 工作流程：  - 學習 Git 基礎  - 克隆儲存庫  - 在文字編輯器中編輯檔案  - 執行 Git 命令  - 開啟拉取請求  - 等待審查2026 工作流程：  - 告訴 AI 代理：「更新首頁文案為 X」  - AI 建立分支，編輯檔案，開啟 PR  - 審查通知到達 Slack  - 點擊「批准」→ 完成

彌合差距的 AI 工具：

結論： Markdown + Git 曾經是「開發者技能」。隨著 AI 代理，它正在成為通用技能——就像打字一樣。

6 殘酷的真相：DaC 的掙扎之處

文件即程式碼並不完美。以下是它真正不足的地方：

挑戰 1：非技術協作

問題：

👤 行銷經理：「我如何建議編輯？」🔧 工程師：「Fork 儲存庫，建立分支，提交，開啟 PR……」👤 行銷經理：*默默地發送 Slack 訊息*

現實檢查： Git 有學習曲線。對於沒有開發經驗的團隊，工作流程感覺陌生。

!!! success "✅ AI 的一線希望」
AI 代理正在迅速減少這種摩擦。像Claude Code、GitHub Copilot和Cursor這樣的工具現在可以：
- 從自然語言執行 Git 命令（「建立分支並更新操作手冊」）
- 用簡單的英語解釋每個命令的作用
- 自動產生提交訊息和拉取請求描述

差距比預期更快地縮小。 2023 年需要 Git 培訓的內容，2026 年可以透過聊天完成。

緩解策略：

挑戰 2：沒有內嵌評論

問題：

Confluence 和 Google Docs 擅長內嵌評論：

📄 Confluence 頁面：  「重新啟動資料庫服務」  └─ 💬 評論：「哪個服務？postgresql.service 還是 mysqld.service？」  └─ 💬 評論：「這個步驟在 staging 中對我失敗了」  └─ 💬 評論：「在 PR #452 中更新了命令」

Markdown 檔案沒有本機的內嵌評論。

解決方案：

挑戰 3：視覺協作

問題：

一些團隊在視覺協作中茁壯成長：

🎨 Google Docs：  - 高亮文字 → 新增評論 → 分配給人員  - 看到其他人即時編輯的游標  - 建議模式 → 視覺化接受/拒絕變更

Git 本質上是非同步的。即時協作不是它的強項。

什麼時候重要：

挑戰 4：「我在哪裡編輯？」問題

問題：

新貢獻者面臨摩擦：

👤 新團隊成員：「我發現操作手冊中有錯字。我如何修復它？」傳統：  - 點擊「編輯」按鈕 → 輸入 → 儲存 → 完成文件即程式碼：  - 克隆儲存庫（或導航到網頁……）  - 建立分支（或在網頁上編輯）  - 進行變更  - 寫提交訊息  - 建立拉取請求  - 等待審查  - 合併（或請求合併）

摩擦稅： 與 wiki 式編輯相比，每次編輯需要約 5-10 個額外步驟。

緩解：

範例：貢獻者的簡單指南

# .github/CONTRIBUTING.md## 如何更新文件### 快速修正（錯字，小變更）1. 在 GitHub 上導航到檔案2. 點擊 ✏️ 鉛筆圖示3. 進行您的變更4. 寫簡短描述5. 點擊「建議變更」6. 完成！我們將審查並合併。### 較大的變更1. Fork 儲存庫2. 建立分支：`git checkout -b fix/my-change`3. 編輯檔案4. 提交：`git commit -m "fix：描述您的變更"`5. 推送：`git push origin fix/my-change`6. 開啟拉取請求

明確的指導顯著減少摩擦。

承認挑戰後，讓我們探討採用文件即程式碼的團隊的實際策略。

7 讓 DaC 運作：實用指南

從小處開始，快速獲勝

第 1-2 週：試點專案

📁 docs/  └── runbooks/      ├── incident-response.md      ├── database-failover.md      └── deployment-procedure.md

選擇一個高價值、技術受眾（例如，值班工程師）。獲得他們的支持。讓他們親身體驗離線優勢。

建立橋樑，而不是牆

不要： 「Confluence 現在對我們來說死了。」

要： 「讓我們在遷移期間同時執行兩者。」

範例：在過渡期間自動同步到 Confluence

# CI/CD 同步 DaC → Confluence（臨時）- name: Publish to Confluence  if: github.ref == 'refs/heads/main'  uses: confluence-publisher@v1  with:    space: OPS    parent: "Operations Runbooks"

這的作用： 每當文件更新時，它會自動發布副本到 Confluence。這讓團隊可以繼續使用 Confluence，同時逐漸採用文件即程式碼——沒有突然的中斷。

這給利害關係人時間適應，同時證明 DaC 的價值。

投資工具

基本堆疊：

可有可無：

定義工作流程

給工程師：

實際情況：

# 1. 為您的變更建立新分支git checkout -b docs/update-failover-procedure# 2. 開啟並編輯文件檔案code docs/runbooks/database-failover.md# 3. 在瀏覽器中預覽外觀mkdocs serve  # 開啟在 http://localhost:8000# 4. 將您的變更儲存到版本控制git add docs/runbooks/database-failover.mdgit commit -m "docs：更新 PostgreSQL 16 的故障轉移步驟"git push origin docs/update-failover-procedure# 5. 請求團隊審查gh pr create --title "docs：更新故障轉移步驟" --body "更新 PG16 相容性"

翻譯： 每個命令做一件事——建立工作區、編輯檔案、預覽、儲存它，並請求隊友審查。bash 符號如 # 只是解釋每個步驟作用的註釋。

給非工程師：

1. 在 GitHub/GitLab 上導航到檔案2. 點擊「編輯」（鉛筆圖示）3. 進行您的變更4. 寫下變更的簡短描述5. 點擊「建議變更」6. 團隊成員將審查並合併

衡量成功

追蹤這些指標：

現在我們有了實際實施策略，讓我們檢查不同類型組織的戰略影響。

8 戰略視角：誰應該採用 DaC？

完美適合 ✅

需要培訓的良好適合 ⚠️

不適合 ❌

總結：文件的十字路口

Zmxvd2NoYXJ0IExSCiAgICBBW+S7iuaXpeaWh+S7tl0gLS0+IEJ76YG45pOH5oKo55qE6Lev5b6RfQogICAgQiAtLT4gQ1tDb25mbHVlbmNlIENsb3VkIDIwMjldCiAgICBCIC0tPiBEW+aWh+S7tuWNs+eoi+W8j+eivF0KICAgIEIgLS0+IEVb54++54uAXQoKICAgIEMgLS0+IEZbU2FhUyDkvp3os7Q8YnIvPuaMgee6jOaIkOacrDxici8+6ZyA6KaB55m75YWlXQogICAgRCAtLT4gR1vmk4HmnInmgqjnmoTos4fmlpk8YnIvPumboue3muWtmOWPljxici8+5a6J5YWo5o6D5o+PXQogICAgRSAtLT4gSFvmioDooZPlgrXli5k8YnIvPuefpeitmOa1geWksTxici8+MjAyOSDljbHmqZ9dCgogICAgc3R5bGUgRCBmaWxsOiNlOGY1ZTksc3Ryb2tlOiMzODhlM2MKICAgIHN0eWxlIEMgZmlsbDojZmZmM2UwLHN0cm9rZTojZjU3YzAwCiAgICBzdHlsZSBFIGZpbGw6I2ZmZWJlZSxzdHJva2U6I2M2MjgyOA==

選擇：

結論：

文件即程式碼不是關於 Markdown。是關於所有權。

當您的文件存放在 Git 中：

• 📖 您擁有資料 — 沒有廠商能挾持它
• 🔓 離線運作 — 關鍵時刻網路故障時
• 🔍 可掃描 — 內建安全和合規
• 📦 可匯出到任何地方 — PDF、Word、Confluence（如果您必須）
• 📜 有歷史記錄 — 每次變更被追蹤、可還原、可審核
• 🔒 防篡改 — 密碼學保護，像區塊鏈
• 🤖 AI 就緒 — 最低代幣成本，命令列友好，Mermaid 圖表

挑戰是真實的——非技術協作、內嵌評論、視覺工作流程。但這些是可解決的問題，不是根本缺陷。

而在 2029 年，當 Confluence 本機版終止，您的合規團隊問*「我們的文件在哪裡？」*——您會想要一個不涉及恐慌遷移的答案。

從小處開始。選擇一個操作手冊。克隆一個儲存庫。親身體驗離線優勢。

因為種樹最好的時間是 20 年前。第二好的時間是在廠商關閉您的伺服器之前。

進一步閱讀

• GitHub Docs：Documentation as Code
• Atlassian Confluence End-of-Life Announcement
• gitleaks：Secret Scanning Tool
• Mermaid：Diagrams and Flowcharts in Markdown

Meanwhile, the “final” version of the procedure lives in a Word document on someone’s desktop from 2023. The Confluence page? It’s out of date. The wiki? Nobody knows the password.

This isn’t a hypothetical nightmare. It’s Tuesday for thousands of teams still treating documentation like a destination instead of a deliverable.

Here’s the uncomfortable truth: Your documentation strategy is a single point of failure. And in 2029, when Atlassian shuts down Confluence on-premises forever, that failure becomes mandatory.

But there’s a way out. It’s called Document as Code (DaC). And no, it’s not just “writing in Markdown.” It’s a fundamental shift in how teams think about knowledge.

1 The Problem: Documentation Graveyards

Let’s name the elephants in the room.

The Word Document Cemetery

📁 Shared Drive/  📁 Operations/    📄 Runbook_FINAL.docx    📄 Runbook_FINAL_v2.docx    📄 Runbook_FINAL_v2_UPDATED.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL.docx    📄 Runbook_FINAL_v3_ACTUAL_FINAL_REALLY.docx

The Reality:

• Nobody knows which version is authoritative
• Changes require “Track Changes” and email chains
• Search? Good luck with that
• Access control? Either everyone or nobody

The Confluence Trap

Confluence promised organized, searchable knowledge. What it delivered:

The Wiki Wild West

Wikis started as “everyone can edit!” and became “nobody owns this.”

🌐 Internal Wiki  ├── 📄 Getting Started (last updated: 2021)  ├── 📄 Architecture Overview (broken images)  ├── 📄 On-Call Procedures (password: ???)  └── 📄 [404 Page Not Found]

The Pattern: All three approaches share the same fatal flaw—documentation is separate from the work.

2 What Is Document as Code?

Document as Code treats documentation like software:

But here’s what makes DaC different from “just using Markdown”:

It’s Not Just Markdown. It’s Git.

❌ "We use Markdown" → Files on a shared drive✅ "We use Document as Code" → Git-based workflow with version control

What Is Git? (For Non-Technical Readers)

Git is a tool that tracks changes to files over time. Think of it like a time machine for documents.

Every time you save a change, Git takes a snapshot. You can travel back to any snapshot later—yesterday’s version, last week’s, even from a year ago. Nothing is ever lost.

Why Git Was Built

Problem (before Git):  👤 Person A: "I'm editing the file!"  👤 Person B: "Me too!"  → Both save → One person's changes are lost 😱Solution (with Git):  👤 Person A: "I'm editing on my own copy"  👤 Person B: "Me too on my own copy"  → Both finish → Git combines changes safely ✅

Real-World Analogy

Google Docs version history works similarly—every save is recorded with who changed what. Git does this too, but with three key differences:

1. Works offline — No internet needed
2. Full copy on your computer — Every version, ever
3. No vendor lock-in — Your data stays yours

What This Means for You

• No internet? No problem. Everything is local.
• Server goes down? You have a full backup.
• Vendor disappears? Your data is yours.
• Made a mistake? Instant undo to any point in time.

Is Git Hard to Learn?

For developers, Git is daily work—they already know it.

For non-technical users, you don’t need to learn Git commands. Modern tools (GitHub Web UI, AI assistants) handle the complexity. You just edit—Git works in the background.

The Security Superpower: Git Is Like a Blockchain for Documents

Here’s the powerful part: Git uses cryptography to make history tamper-proof.

Every change gets a unique fingerprint (called a “hash”). This fingerprint is calculated from:

• The content you changed
• The fingerprint of the previous change
• Who made the change and when

This creates a chain of fingerprints—just like blockchain. If someone tries to alter history (say, delete evidence of who approved a change), the fingerprints no longer match. The tampering is instantly detectable.

Confluence and Word can’t do this. Their logs can be modified by admins. Git’s history cannot be silently changed.

Commit Signing: Digital Signatures for Changes

Git has an even stronger security feature: commit signing.

Every person gets a personal certificate (like a digital ID card). When you save a change, Git signs it with your certificate. The signature proves: “This change came from me, and I approve it.”

Real-World Analogy:

Traditional Git commit:  👤 "John approved this change"  → You trust the system recorded this correctlySigned Git commit:  👤 "John approved this change" ✍️ [digitally signed]  → Cryptographically proven John approved it  → John's certificate validates the signature  → Cannot be faked without John's private key

Why signing matters:

• Prevents impersonation — Nobody can pretend to be you
• Legal validity — Signed commits hold up in court (like a wet signature)
• Supply chain security — Know exactly who approved each change
• Compliance — Required for some regulated industries

What you see in practice:

✅ Verified commit abc123 by John Doe (john@company.com)⚠️ Unverified commit def456 by unknown@example.com

GitHub and GitLab show a green “Verified” badge on signed commits. If someone tries to fake a commit from you, the signature won’t match—instantly exposed.

The Git Difference

Plain Markdown Files (without Git):

• Version history: File timestamps only
• Collaboration: Overwrite conflicts
• Offline access: Yes (local files)
• Audit trail: Manual logging
• Rollback: “Does anyone have the old version?”
• Distributed: Centralized file server

Document as Code with Git:

• Version history: Every change tracked, who/when/why
• Collaboration: Branches, merge, resolve conflicts
• Offline access: Yes (full repo clone)
• Audit trail: Immutable commit history (cryptographically secured)
• Rollback: git revert — instant recovery
• Distributed: Every clone is a complete backup

The Key Insight

Git is decentralized by design. Every developer has a complete copy of the documentation repository. This means:

• No single point of failure
• Works offline (crucial for sandboxed/air-gapped environments)
• No login required to read
• No vendor can hold your knowledge hostage

Now that we understand the foundation, let’s explore why this architecture matters when systems fail.

3 The Runbook Test: What Happens at 3 AM?

Let’s replay our opening scenario with Document as Code.

3 AM. Production incident. No internet access (sandboxed environment).

With Traditional Documentation:

Engineer: "Let me check the runbook..."  ↓Opens browser → Confluence login → No network  ↓Calls teammate → "What's the wiki password?"  ↓Teammate: "I think it's in LastPass..."  ↓LastPass → No network → Can't sync  ↓[Incident escalates while hunting for credentials]

Time to resolution: 45 minutes (including 38 minutes finding docs)

With Document as Code:

Engineer: "Let me check the runbook..."  ↓Opens terminal → `cd runbooks` → Already cloned locally  ↓`grep "database failover" *.md` → Instant search  ↓Follows procedure → System recovered  ↓Commits incident notes → `git commit -m "Incident #2026-0329"`

Time to resolution: 7 minutes (all of it fixing the problem)

Having seen how DaC performs under pressure, let’s examine the practical advantages that make it worth adopting.

4 Why Document as Code Wins

1. Export to Any Format

Your stakeholders want Word? PDF? Confluence? No problem.

Here’s how the automation works:

You save changes to Git        ↓Automation detects the change        ↓Builds PDF version        ↓Builds Word version        ↓Updates website        ↓(Optionally) Syncs to Confluence        ↓Done — all formats updated automatically

What this replaces:

The actual automation configuration looks like this:

# CI/CD pipeline builds multiple formatson:  push:    branches: [main]jobs:  build-docs:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4            # Convert to PDF      - name: Build PDF        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.pdf            # Convert to Word (for stakeholders who insist)      - name: Build Word        uses: docker://pandoc/core        with:          args: runbook.md -o runbook.docx            # Sync to Confluence (for teams not ready to quit)      - name: Sync to Confluence        uses: docker://confluence-publisher        with:          args: --source ./docs --space OPS

What Is CI/CD? It’s automation that runs whenever your documentation changes. Think of it like a robot assistant: you save your changes to Git, and it automatically builds the PDF, Word document, and website—no manual steps required.

The Magic: Write once (Markdown), publish everywhere (PDF, Word, HTML, Confluence).

2. Security That Scans

Traditional docs are security blind spots:

🔍 Security Team: "Can we scan the Word documents for secrets?"👤 IT Admin: "They're on a file server. We'd need to..."🔍 Security Team: "What about Confluence?"👤 IT Admin: "That's SaaS. You'd need API access and..."🔍 Security Team: *sighs*

Document as Code is security-transparent:

Example: Scanning for accidental secrets

# Scan all documentation for leaked passwords or API keys$ gitleaks detect --source ./docs --report-path secrets.json# Search for common sensitive patterns$ grep -r "password\|api_key\|secret" ./docs/*.md# Run checks automatically before saving changes$ pre-commit run --all-files

What these commands do: The first command runs a security scanner that looks for passwords, API keys, and tokens. The second searches for common sensitive words. The third runs automatically every time someone tries to save changes—blocking anything suspicious before it’s stored.

What Gets Caught:

3. The 2029 Confluence Exodus

Let’s address the elephant: Confluence Data Center becomes read-only on March 28, 2029.

Your Options:

The Real Cost of Confluence Cloud:

Enterprise (1000 users):  - Confluence Cloud: ~$120,000/year  - Required add-ons: ~$30,000/year  - Migration services: ~$50,000 (one-time)  - Training: ~$20,000    Total Year 1: ~$220,000  Total Year 3: ~$410,000

Document as Code Cost:

Enterprise (1000 users):  - Git hosting (GitHub/GitLab): ~$20,000/year (often already paid)  - Static site generator: $0 (open source)  - CI/CD: $0-$10,000/year (often included)  - Training: ~$20,000 (one-time)    Total Year 1: ~$50,000  Total Year 3: ~$80,000

Savings over 3 years: ~$330,000 (and you own your data)

With the financial and strategic advantages clear, let’s examine where Document as Code faces genuine challenges.

5 The AI Advantage: Why DaC Is Perfect for AI Assistants

Here’s the plot twist: Document as Code is the most AI-friendly documentation format you can choose.

Low Cost, High Impact

The Token Economy:

AI assistants charge by the token (roughly 1 token = 1 word). Compare:

Why Markdown Wins:

Markdown:     "# Runbook: Database Failover" → Clean, minimal tokensWord DOCX:    "<w:document><w:p><w:r><w:t>Runbook...</w:t></w:r></w:p>..." → XML bloatConfluence:   "<div class='content'><h1>Runbook</h1><span data-...>..." → HTML noise

The Math: Updating 100 documentation pages with AI:

• Markdown: ~$0.10 in API costs
• Word/Confluence: ~$0.60-1.00 in API costs
• Savings: 80-90% lower AI processing costs

Command Line + AI Agents = Perfect Match

AI agents love command-line tools. Here’s why:

🤖 AI Agent: "I'll update the runbook for PostgreSQL 16"Step 1: Clone repository          → `git clone ...`Step 2: Find relevant files       → `grep -r "PostgreSQL" docs/`Step 3: Read current content      → `cat docs/runbooks/db-failover.md`Step 4: Generate updated content  → (AI writes new version)Step 5: Save changes              → `git add && git commit`Step 6: Create pull request       → `gh pr create ...`✅ Done in 30 seconds

Why This Works:

Contrast with Confluence:

🤖 AI Agent: "I'll update the Confluence page..."Step 1: Authenticate via OAuth    → Token exchange, API keysStep 2: Fetch page via REST API   → HTTP request, rate limitsStep 3: Parse HTML content        → Strip tags, handle encodingStep 4: Generate updated content  → (AI writes new version)Step 5: Convert back to HTML      → Re-add formatting, macrosStep 6: Publish via API           → HTTP POST, handle conflicts❌ 10x more complex, 5x slower, API rate limits

Visual Diagrams: Mermaid Charts

Markdown now supports diagrams natively:

flowchart LR    A[Incident Detected] --> B{Severity?}    B -->|Critical| C[Page On-Call]    B -->|Low| D[Log Ticket]    C --> E[Start Runbook]    D --> F[Monitor]

Renders as:

Zmxvd2NoYXJ0IExSCiAgICBBW0luY2lkZW50IERldGVjdGVkXSAtLT4gQntTZXZlcml0eT99CiAgICBCIC0tPnxDcml0aWNhbHwgQ1tQYWdlIE9uLUNhbGxdCiAgICBCIC0tPnxMb3d8IERbTG9nIFRpY2tldF0KICAgIEMgLS0+IEVbU3RhcnQgUnVuYm9va10KICAgIEQgLS0+IEZbTW9uaXRvcl0=

AI + Mermaid = Instant Diagrams:

👤 User: "Create a flowchart of our deployment process"🤖 AI: *generates Mermaid code*✅ Result: Professional diagram, no design skills needed

Supported Diagram Types:

The Learning Curve Is Flattening

Then (2020):

👤 Non-tech user: "What's Markdown?"🔧 Engineer: "It's like plain text with symbols..."👤 Non-tech user: "Where do I edit?"🔧 Engineer: "You need a text editor, or maybe..."😓 Friction: High

Now (2026):

👤 Non-tech user: "How do I edit?"Option 1: GitHub Web UI (WYSIWYG mode)  - Click edit → See formatted view → SaveOption 2: Notion (exports to Markdown)  - Write visually → Export as .mdOption 3: Google Docs (with Markdown converter)  - Write in Docs → Auto-convert to .mdOption 4: Microsoft Word (Save as Markdown)  - Native support built-in😓 Friction: Low and decreasing

The Trend: WYSIWYG editors are adding Markdown support, not replacing it.

AI Agents Democratize Markdown

The Reality: Non-technical users don’t need to learn Git commands anymore.

👤 Marketing Manager: "Update the homepage copy"2020 Workflow:  - Learn Git basics  - Clone repository  - Edit file in text editor  - Run git commands  - Open pull request  - Wait for review2026 Workflow:  - Tell AI agent: "Update homepage copy to say X"  - AI creates branch, edits file, opens PR  - Review notification arrives in Slack  - Click "Approve" → Done

AI Tools That Bridge the Gap:

The Bottom Line: Markdown + Git was once a “developer skill.” With AI agents, it’s becoming a universal skill—just like typing.

6 The Honest Truth: Where DaC Struggles

Document as Code isn’t perfect. Here’s where it genuinely falls short:

Challenge 1: Non-Technical Collaboration

The Problem:

👤 Marketing Manager: "How do I suggest an edit?"🔧 Engineer: "Fork the repo, create a branch, commit, open a PR..."👤 Marketing Manager: *quietly sends a Slack message instead*

Reality Check: Git has a learning curve. For teams without development experience, the workflow feels foreign.

!!! success “✅ The AI Silver Lining”
AI agents are rapidly reducing this friction. Tools like Claude Code, GitHub Copilot, and Cursor can now:
- Execute Git commands from natural language (“Create a branch and update the runbook”)
- Explain what each command does in plain English
- Auto-generate commit messages and pull request descriptions

The gap is closing faster than expected. What required Git training in 2023 can be done via chat in 2026.

Mitigation Strategies:

Challenge 2: No Inline Comments

The Problem:

Confluence and Google Docs excel at inline commenting:

📄 Confluence Page:  "Restart the database service"  └─ 💬 Comment: "Which service? postgresql.service or mysqld.service?"  └─ 💬 Comment: "This step failed for me in staging"  └─ 💬 Comment: "Updated command in PR #452"

Markdown files don’t have native inline comments.

Workarounds:

Challenge 3: Visual Collaboration

The Problem:

Some teams thrive on visual collaboration:

🎨 Google Docs:  - Highlight text → Add comment → Assign to person  - See cursors of others editing in real-time  - Suggestion mode → Accept/reject changes visually

Git is asynchronous by design. Real-time collaboration isn’t its strength.

When This Matters:

Challenge 4: The “Where Do I Edit?” Problem

The Problem:

New contributors face friction:

👤 New Team Member: "I found a typo in the runbook. How do I fix it?"Traditional:  - Click "Edit" button → Type → Save → DoneDocument as Code:  - Clone repo (or navigate to web UI)  - Create branch (or edit in web)  - Make change  - Write commit message  - Create pull request  - Wait for review  - Merge (or request merge)

The Friction Tax: Each edit requires ~5-10 extra steps compared to wiki-style editing.

Mitigation:

Example: A simple guide for contributors

# .github/CONTRIBUTING.md## How to Update Documentation### Quick Fix (Typo, small change)1. Navigate to the file on GitHub2. Click the ✏️ pencil icon3. Make your change4. Write a brief description5. Click "Propose changes"6. Done! We'll review and merge.### Larger Changes1. Fork the repository2. Create a branch: `git checkout -b fix/my-change`3. Edit the files4. Commit: `git commit -m "fix: describe your change"`5. Push: `git push origin fix/my-change`6. Open a Pull Request

Clear guidance reduces friction significantly.

Having acknowledged the challenges, let’s explore practical strategies for teams adopting Document as Code.

7 Making DaC Work: A Practical Guide

Start Small, Win Fast

Week 1-2: Pilot Project

📁 docs/  └── runbooks/      ├── incident-response.md      ├── database-failover.md      └── deployment-procedure.md

Pick one high-value, technical audience (e.g., on-call engineers). Get their buy-in. Let them experience the offline benefit firsthand.

Build the Bridge, Not the Wall

Don’t: “Confluence is dead to us now.”

Do: “Let’s run both in parallel during migration.”

Example: Automatically sync to Confluence while transitioning

# CI/CD syncs DaC → Confluence (temporary)- name: Publish to Confluence  if: github.ref == 'refs/heads/main'  uses: confluence-publisher@v1  with:    space: OPS    parent: "Operations Runbooks"

What this does: Every time documentation is updated, it automatically publishes a copy to Confluence. This lets teams keep using Confluence while gradually adopting Document as Code—no sudden disruption.

This gives stakeholders time to adapt while proving DaC’s value.

Invest in Tooling

Essential Stack:

Nice to Have:

Define the Workflow

For Engineers:

What this looks like in practice:

# 1. Create a new branch for your changesgit checkout -b docs/update-failover-procedure# 2. Open and edit the documentation filecode docs/runbooks/database-failover.md# 3. Preview how it looks in your browsermkdocs serve  # Opens at http://localhost:8000# 4. Save your changes to version controlgit add docs/runbooks/database-failover.mdgit commit -m "docs: update failover steps for PostgreSQL 16"git push origin docs/update-failover-procedure# 5. Request a review from your teamgh pr create --title "docs: update failover steps" --body "Updated for PG16 compatibility"

Translation: Each command does one thing—create a workspace, edit the file, preview it, save it, and ask teammates to review. The bash symbols like # are just notes explaining what each step does.

For Non-Engineers:

1. Navigate to the file on GitHub/GitLab2. Click "Edit" (pencil icon)3. Make your changes4. Write a brief description of what changed5. Click "Propose changes"6. A team member will review and merge

Measure Success

Track these metrics:

Now that we have practical implementation strategies, let’s examine the strategic implications for different types of organizations.

8 The Strategic View: Who Should Adopt DaC?

Perfect Fit ✅

Good Fit with Training ⚠️

Poor Fit ❌

Summary: The Documentation Crossroads

Zmxvd2NoYXJ0IExSCiAgICBBW0RvY3VtZW50YXRpb24gVG9kYXldIC0tPiBCe0Nob29zZSBZb3VyIFBhdGh9CiAgICBCIC0tPiBDW0NvbmZsdWVuY2UgQ2xvdWQgMjAyOV0KICAgIEIgLS0+IERbRG9jdW1lbnQgYXMgQ29kZV0KICAgIEIgLS0+IEVbU3RhdHVzIFF1b10KICAgIAogICAgQyAtLT4gRltTYWFTIERlcGVuZGVuY3k8YnIvPk9uZ29pbmcgQ29zdHM8YnIvPkxvZ2luIFJlcXVpcmVkXQogICAgRCAtLT4gR1tPd24gWW91ciBEYXRhPGJyLz5PZmZsaW5lIEFjY2Vzczxici8+U2VjdXJpdHkgU2Nhbm5pbmddCiAgICBFIC0tPiBIW1RlY2huaWNhbCBEZWJ0PGJyLz5Lbm93bGVkZ2UgTG9zczxici8+MjAyOSBDcmlzaXNdCiAgICAKICAgIHN0eWxlIEQgZmlsbDojZThmNWU5LHN0cm9rZTojMzg4ZTNjCiAgICBzdHlsZSBDIGZpbGw6I2ZmZjNlMCxzdHJva2U6I2Y1N2MwMAogICAgc3R5bGUgRSBmaWxsOiNmZmViZWUsc3Ryb2tlOiNjNjI4Mjg=

The Choice:

The Bottom Line:

Document as Code isn’t about Markdown. It’s about ownership.

When your documentation lives in Git:

• 📖 You own the data — No vendor can hold it hostage
• 🔓 It works offline — Critical when networks fail
• 🔍 It’s scannable — Security and compliance built-in
• 📦 It exports anywhere — PDF, Word, Confluence (if you must)
• 📜 It has history — Every change tracked, reversible, auditable
• 🔒 It’s tamper-proof — Cryptographically secured like blockchain
• 🤖 It’s AI-ready — Lowest token costs, command-line friendly, Mermaid diagrams

The challenges are real—non-technical collaboration, inline comments, visual workflows. But these are solvable problems, not fundamental flaws.

And in 2029, when Confluence on-premises reaches end-of-life and your compliance team asks “Where is our documentation?”—you’ll want an answer that doesn’t involve a panic migration.

Start small. Pick one runbook. Clone one repo. Experience the offline benefit firsthand.

Because the best time to plant a tree was 20 years ago. The second-best time is before the vendor shuts off your server.

Further Reading

• GitHub Docs: Documentation as Code
• Atlassian Confluence End-of-Life Announcement
• gitleaks: Secret Scanning Tool
• Mermaid: Diagrams and Flowcharts in Markdown

我们的选择性估计是猜测：

// From Part 7 - simplified (wrong!) estimatesfn estimate_selectivity(&self, expr: &Expression) -> f64 {    match expr {        BinaryOperator::Eq => 0.01,   // Always 1%? Wrong!        BinaryOperator::Gt => 0.33,   // Always 33%? Wrong!        _ => 0.5,                      // Always 50%? Very wrong!    }}

真实数据不是均匀的：

User balances in our database:Balance Distribution:$0-100:     ████████████████████████████████████████  80% of users$100-1K:    ████████                                   15% of users$1K-10K:    ██                                          4% of users$10K-100K:  █                                           1% of usersQuery: SELECT * FROM users WHERE balance > 100Our estimate: 33% of rows (using fixed 0.33)Actual: 20% of rows→ Wrong plan chosen! Index scan would be better than seq scan.

解决方案： 捕捉实际数据分布的直方图。

今天：在 Rust 中实现直方图统计以进行准确的选择性估计。

1 为什么直方图很重要

均匀分布谬误

没有直方图，优化器假设均匀分布：

-- Table: users (1,000,000 rows)-- Column: account_type ('free', 'premium', 'enterprise')-- Reality:'free':       950,000 rows (95%)'premium':     45,000 rows (4.5%)'enterprise':   5,000 rows (0.5%)-- Query 1:SELECT * FROM users WHERE account_type = 'enterprise'-- Optimizer estimate (uniform): 1,000,000 / 3 = 333,333 rows-- Actual: 5,000 rows-- Error: 67x overestimate!-- Query 2:SELECT * FROM users WHERE account_type = 'free'-- Optimizer estimate (uniform): 333,333 rows-- Actual: 950,000 rows-- Error: 3x underestimate!

有直方图： 我们知道实际分布。

对连接顺序的影响

SELECT u.name, o.totalFROM users uJOIN orders o ON u.id = o.user_idWHERE u.account_type = 'enterprise'

没有直方图：

Optimizer thinks 'enterprise' = 333,333 rowsPlan: SeqScan(users) → Hash Join → SeqScan(orders)Cost: 5000 (wrong!)

有直方图：

Histogram shows 'enterprise' = 5,000 rowsPlan: IndexScan(users) → Nested Loop → IndexScan(orders)Cost: 100 (correct!)

结果： 查询快 50 倍。

2 直方图类型

等宽直方图

相等的桶范围，不同的行数：

Data: [1, 2, 3, 4, 5, 10, 11, 12, 13, 14]Equi-Width (3 buckets, range 1-14):┌─────────────────────────────────────────────────────────────┐│ Bucket 1: [1-5]     → 5 rows  │████████████████████████████││ Bucket 2: [6-10]    → 1 row   │██████                      ││ Bucket 3: [11-14]   → 4 rows  │██████████████████████      │└─────────────────────────────────────────────────────────────┘

#[derive(Debug, Clone)]pub struct EquiWidthHistogram {    pub min_value: Value,    pub max_value: Value,    pub num_buckets: usize,    pub buckets: Vec<WidthBucket>,}#[derive(Debug, Clone)]pub struct WidthBucket {    pub lower_bound: Value,    pub upper_bound: Value,    pub row_count: u64,    pub distinct_count: u64,    pub null_count: u64,}impl EquiWidthHistogram {    pub fn build(values: &[Value], num_buckets: usize) -> Result<Self, HistogramError> {        if values.is_empty() {            return Err(HistogramError::EmptyData);        }        let (min, max) = Self::find_min_max(values)?;        let bucket_width = max.subtract(&min).divide(num_buckets as f64);        let mut buckets = vec![WidthBucket {            lower_bound: min.clone(),            upper_bound: min.clone(),            row_count: 0,            distinct_count: 0,            null_count: 0,        }; num_buckets];        // Initialize bucket bounds        for i in 0..num_buckets {            buckets[i].lower_bound = min.add(bucket_width.multiply(i as f64));            buckets[i].upper_bound = min.add(bucket_width.multiply((i + 1) as f64));        }        // Count rows in each bucket        for value in values {            if value.is_null() {                buckets[0].null_count += 1;                continue;            }            let bucket_idx = Self::find_bucket_index(value, &min, &bucket_width, num_buckets);            if bucket_idx < num_buckets {                buckets[bucket_idx].row_count += 1;            }        }        Ok(Self {            min_value: min,            max_value: max,            num_buckets,            buckets,        })    }    fn find_bucket_index(value: &Value, min: &Value, width: &Value, num_buckets: usize) -> usize {        let offset = value.subtract(min);        let bucket = offset.divide(width).to_f64().floor() as usize;        bucket.min(num_buckets - 1)    }}

优点： 简单，适合均匀数据。

缺点： 对于偏斜数据效果差（大多数桶为空，一个桶巨大）。

等深直方图（PostgreSQL 风格）

每个桶的行数相等，范围不同：

Data: [1, 2, 3, 4, 5, 10, 11, 12, 13, 14]Equi-Depth (3 buckets, ~3-4 rows each):┌─────────────────────────────────────────────────────────────┐│ Bucket 1: [1-4]     → 4 rows  │████████████████████████████││ Bucket 2: [5-11]    → 3 rows  │████████████████████████████││ Bucket 3: [12-14]   → 3 rows  │████████████████████████████│└─────────────────────────────────────────────────────────────┘

#[derive(Debug, Clone)]pub struct EquiDepthHistogram {    pub num_buckets: usize,    pub total_rows: u64,    pub buckets: Vec<DepthBucket>,}#[derive(Debug, Clone)]pub struct DepthBucket {    pub lower_bound: Value,    pub upper_bound: Value,    pub row_count: u64,    pub distinct_count: u64,    pub cumulative_count: u64,  // Rows <= upper_bound}impl EquiDepthHistogram {    pub fn build(values: &[Value], num_buckets: usize) -> Result<Self, HistogramError> {        if values.is_empty() {            return Err(HistogramError::EmptyData);        }        // Sort values        let mut sorted_values = values.to_vec();        sorted_values.sort();        let total_rows = sorted_values.len() as u64;        let target_bucket_size = (total_rows as f64 / num_buckets as f64).ceil() as usize;        let mut buckets = Vec::new();        let mut cumulative = 0u64;        for i in 0..num_buckets {            let start = i * target_bucket_size;            let end = ((i + 1) * target_bucket_size).min(sorted_values.len());            if start >= sorted_values.len() {                break;            }            let bucket_values = &sorted_values[start..end];            let row_count = bucket_values.len() as u64;            let distinct_count = bucket_values.iter().collect::<std::collections::HashSet<_>>().len() as u64;            cumulative += row_count;            buckets.push(DepthBucket {                lower_bound: bucket_values.first().unwrap().clone(),                upper_bound: bucket_values.last().unwrap().clone(),                row_count,                distinct_count,                cumulative_count: cumulative,            });        }        Ok(Self {            num_buckets,            total_rows,            buckets,        })    }    /// Estimate selectivity for equality predicate    pub fn estimate_eq(&self, value: &Value) -> f64 {        for bucket in &self.buckets {            if value >= &bucket.lower_bound && value <= &bucket.upper_bound {                // Assume uniform distribution within bucket                let bucket_selectivity = 1.0 / bucket.distinct_count.max(1) as f64;                return bucket_selectivity * (bucket.row_count as f64 / self.total_rows as f64);            }        }        0.0  // Value outside histogram range    }    /// Estimate selectivity for range predicate (value > X)    pub fn estimate_gt(&self, value: &Value) -> f64 {        let mut selectivity = 0.0;        for bucket in &self.buckets {            if value < &bucket.lower_bound {                // Entire bucket matches                selectivity += bucket.row_count as f64 / self.total_rows as f64;            } else if value >= &bucket.lower_bound && value < &bucket.upper_bound {                // Partial bucket - assume uniform within bucket                let bucket_range = bucket.upper_bound.subtract(&bucket.lower_bound).to_f64();                let matching_range = bucket.upper_bound.subtract(value).to_f64();                let fraction = (matching_range / bucket_range).clamp(0.0, 1.0);                selectivity += fraction * (bucket.row_count as f64 / self.total_rows as f64);            }            // else: value >= bucket.upper_bound, no match        }        selectivity    }    /// Estimate selectivity for range predicate (value < X)    pub fn estimate_lt(&self, value: &Value) -> f64 {        1.0 - self.estimate_gte(value)    }    /// Estimate selectivity for range predicate (value >= X)    pub fn estimate_gte(&self, value: &Value) -> f64 {        let mut selectivity = 0.0;        for bucket in &self.buckets {            if value <= &bucket.lower_bound {                // Entire bucket matches                selectivity += bucket.row_count as f64 / self.total_rows as f64;            } else if value > &bucket.lower_bound && value <= &bucket.upper_bound {                // Partial bucket                let bucket_range = bucket.upper_bound.subtract(&bucket.lower_bound).to_f64();                let matching_range = bucket.upper_bound.subtract(value).to_f64();                let fraction = (matching_range / bucket_range).clamp(0.0, 1.0);                selectivity += fraction * (bucket.row_count as f64 / self.total_rows as f64);            }        }        selectivity    }}

优点： 对于偏斜数据更好，每个桶有相等的权重。

缺点： 对于有大量重复的数据，桶边界可能是任意的。

压缩直方图（处理重复）

单独处理最常见值（MCV）：

Data: [1, 1, 1, 1, 1, 2, 3, 4, 5, 10, 11, 12, 13, 14]Compressed Histogram:┌─────────────────────────────────────────────────────────────┐│ Most Common Values (MCV):                                   ││   Value 1: frequency = 5/14 = 35.7%                        │├─────────────────────────────────────────────────────────────┤│ Histogram (for remaining values):                           ││   Bucket 1: [2-5]   → 4 rows                                ││   Bucket 2: [6-10]  → 1 row                                 ││   Bucket 3: [11-14] → 4 rows                                │└─────────────────────────────────────────────────────────────┘

#[derive(Debug, Clone)]pub struct CompressedHistogram {    pub mcv_list: MCVList,    pub histogram: EquiDepthHistogram,    pub null_fraction: f64,}#[derive(Debug, Clone)]pub struct MCVList {    pub values: Vec<(Value, f64)>,  // (value, frequency)    pub total_mcv_frequency: f64,}impl CompressedHistogram {    pub fn build(values: &[Value], num_buckets: usize, num_mcv: usize) -> Result<Self, HistogramError> {        // Handle NULLs        let null_count = values.iter().filter(|v| v.is_null()).count();        let null_fraction = null_count as f64 / values.len() as f64;        let non_null_values: Vec<_> = values.iter().filter(|v| !v.is_null()).collect();        // Build MCV list        let mcv_list = Self::build_mcv_list(&non_null_values, num_mcv);        // Build histogram for non-MCV values        let mcv_values: std::collections::HashSet<_> =             mcv_list.values.iter().map(|(v, _)| v).collect();        let non_mcv_values: Vec<_> = non_null_values            .iter()            .filter(|v| !mcv_values.contains(v))            .cloned()            .collect();        let histogram = if non_mcv_values.is_empty() {            // All values are in MCV, create empty histogram            EquiDepthHistogram {                num_buckets: 0,                total_rows: 0,                buckets: Vec::new(),            }        } else {            EquiDepthHistogram::build(&non_mcv_values, num_buckets)?        };        Ok(Self {            mcv_list,            histogram,            null_fraction,        })    }    fn build_mcv_list(values: &[Value], num_mcv: usize) -> MCVList {        let mut value_counts: std::collections::HashMap<&Value, usize> =             std::collections::HashMap::new();        for value in values {            *value_counts.entry(value).or_insert(0) += 1;        }        let mut mcv: Vec<_> = value_counts.into_iter().collect();        mcv.sort_by(|a, b| b.1.cmp(&a.1));  // Sort by count descending        let total_mcv_frequency = mcv.iter().map(|(_, c)| *c as f64).sum::<f64>() / values.len() as f64;        let mcv_values = mcv            .into_iter()            .take(num_mcv)            .map(|(v, c)| (v.clone(), c as f64 / values.len() as f64))            .collect();        MCVList {            values: mcv_values,            total_mcv_frequency,        }    }    /// Estimate selectivity with MCV awareness    pub fn estimate_selectivity(&self, op: &BinaryOperator, value: &Value) -> f64 {        // Check MCV first        for (mcv_val, frequency) in &self.mcv_list.values {            if mcv_val == value {                return match op {                    BinaryOperator::Eq => *frequency,                    BinaryOperator::Neq => 1.0 - frequency,                    _ => {                        // For range ops, MCV exact match doesn't help much                        // Fall through to histogram estimation                        0.0                    }                };            }        }        // Not in MCV, use histogram        let histogram_selectivity = match op {            BinaryOperator::Eq => self.histogram.estimate_eq(value),            BinaryOperator::Gt => self.histogram.estimate_gt(value),            BinaryOperator::Lt => self.histogram.estimate_lt(value),            BinaryOperator::Gte => self.histogram.estimate_gte(value),            BinaryOperator::Lte => 1.0 - self.histogram.estimate_gt(value),            _ => 0.5,        };        // Adjust for non-MCV portion        let non_mcv_fraction = 1.0 - self.mcv_list.total_mcv_frequency;        histogram_selectivity * non_mcv_fraction    }}

优点： 两全其美 - 对于常见值准确，对于其余值有良好的分布。

缺点： 更复杂，需要更多内存。

3 大型表的采样

问题：完整表扫描很昂贵

-- Table: users (100 million rows)-- Building histogram requires sorting all values-- Full scan approach:SELECT balance FROM users ORDER BY balance;-- Time: 30 minutes (!)-- I/O: Read entire table-- Not practical for routine ANALYZE

解决方案：统计采样

// src/optimizer/sampling.rsuse rand::seq::SliceRandom;use rand::thread_rng;pub struct Sampler {    sample_size: usize,    confidence: f64,}impl Sampler {    pub fn new(sample_size: usize, confidence: f64) -> Self {        Self { sample_size, confidence }    }    /// Reservoir sampling for streaming data    pub fn reservoir_sample<T: Clone>(        &self,        stream: impl Iterator<Item = T>,    ) -> Vec<T> {        let mut reservoir = Vec::with_capacity(self.sample_size);        let mut count = 0;        for item in stream {            count += 1;            if reservoir.len() < self.sample_size {                reservoir.push(item);            } else {                // Replace with probability sample_size / count                let j = thread_rng().gen_range(0..count);                if j < self.sample_size {                    reservoir[j] = item;                }            }        }        reservoir    }    /// Simple random sampling for in-memory data    pub fn simple_random_sample<T: Clone>(&self, values: &[T]) -> Vec<T> {        let mut rng = thread_rng();        let mut sample: Vec<T> = values.to_vec();        sample.shuffle(&mut rng);        sample.truncate(self.sample_size);        sample    }    /// Calculate confidence interval for estimate    pub fn confidence_interval(&self, sample_proportion: f64, sample_size: usize) -> (f64, f64) {        // z-score for confidence level (1.96 for 95%)        let z = match self.confidence {            0.99 => 2.576,            0.95 => 1.96,            0.90 => 1.645,            _ => 1.96,        };        let standard_error = (sample_proportion * (1.0 - sample_proportion) / sample_size as f64).sqrt();        let margin = z * standard_error;        (sample_proportion - margin, sample_proportion + margin)    }}// Usage in histogram buildingimpl EquiDepthHistogram {    pub fn build_from_sample(        values: &[Value],        num_buckets: usize,        sample_size: usize,    ) -> Result<Self, HistogramError> {        let sampler = Sampler::new(sample_size, 0.95);        let sample = sampler.simple_random_sample(values);        // Build histogram from sample        let mut histogram = Self::build(&sample, num_buckets)?;        // Scale row counts to match full table        let scale_factor = values.len() as f64 / sample.len() as f64;        for bucket in &mut histogram.buckets {            bucket.row_count = (bucket.row_count as f64 * scale_factor).round() as u64;            bucket.cumulative_count = (bucket.cumulative_count as f64 * scale_factor).round() as u64;        }        histogram.total_rows = values.len() as u64;        Ok(histogram)    }}

采样大小指南

4 多列统计

问题：列相关性

-- Table: users (1,000,000 rows)-- Columns: country, city-- Individual column statistics:-- country: 'US' = 50%, 'UK' = 30%, 'DE' = 20%-- city: 'London' = 5%, 'Berlin' = 10%, 'Munich' = 5%-- Query:SELECT * FROM users WHERE country = 'UK' AND city = 'London'-- Optimizer (assuming independence):-- Selectivity = 0.30 × 0.05 = 0.015 = 1.5%-- Estimated rows: 15,000-- Reality (London only exists in UK):-- Actual selectivity = 5% (all London users are in UK)-- Actual rows: 50,000-- Error: 3.3x underestimate!

多列直方图

#[derive(Debug, Clone)]pub struct MultiColumnHistogram {    pub columns: Vec<String>,    pub num_buckets: usize,    pub total_rows: u64,    pub buckets: Vec<MultiColumnBucket>,}#[derive(Debug, Clone)]pub struct MultiColumnBucket {    pub bounds: Vec<(Value, Value)>,  // (min, max) for each column    pub row_count: u64,    pub distinct_count: u64,}impl MultiColumnHistogram {    pub fn build(        data: &[Vec<Value>],  // Each row is [col1_value, col2_value, ...]        columns: Vec<String>,        num_buckets: usize,    ) -> Result<Self, HistogramError> {        if data.is_empty() {            return Err(HistogramError::EmptyData);        }        // Use k-d tree style partitioning for multi-dimensional buckets        let buckets = Self::build_kd_histogram(data, num_buckets)?;        Ok(Self {            columns,            num_buckets,            total_rows: data.len() as u64,            buckets,        })    }    fn build_kd_histogram(        data: &[Vec<Value>],        num_buckets: usize,    ) -> Result<Vec<MultiColumnBucket>, HistogramError> {        // Simplified: split on dimension with highest variance        let num_dims = data[0].len();        let target_bucket_size = data.len() / num_buckets;        let mut buckets = Vec::new();        Self::partition_data(data, 0, num_buckets, &mut buckets, target_bucket_size)?;        Ok(buckets)    }    fn partition_data(        data: &[Vec<Value>],        depth: usize,        remaining_buckets: usize,        buckets: &mut Vec<MultiColumnBucket>,        target_size: usize,    ) -> Result<(), HistogramError> {        if remaining_buckets == 1 || data.len() <= target_size {            // Create leaf bucket            let bucket = Self::create_bucket(data)?;            buckets.push(bucket);            return Ok(());        }        // Split on dimension with highest range        let dim = depth % data[0].len();        let mut sorted = data.to_vec();        sorted.sort_by(|a, b| a[dim].cmp(&b[dim]));        let mid = sorted.len() / 2;        let (left, right) = sorted.split_at(mid);        Self::partition_data(left, depth + 1, remaining_buckets / 2, buckets, target_size)?;        Self::partition_data(right, depth + 1, remaining_buckets - remaining_buckets / 2, buckets, target_size)?;        Ok(())    }    fn create_bucket(data: &[Vec<Value>]) -> Result<MultiColumnBucket, HistogramError> {        let num_dims = data[0].len();        let mut bounds = Vec::new();        for dim in 0..num_dims {            let mut values: Vec<_> = data.iter().map(|row| &row[dim]).collect();            values.sort();            bounds.push((values.first().unwrap().clone(), values.last().unwrap().clone()));        }        let distinct_count = data.iter().collect::<std::collections::HashSet<_>>().len() as u64;        Ok(MultiColumnBucket {            bounds,            row_count: data.len() as u64,            distinct_count,        })    }    pub fn estimate_selectivity(&self, predicates: &[(usize, BinaryOperator, Value)]) -> f64 {        let mut selectivity = 0.0;        for bucket in &self.buckets {            let bucket_selectivity = self.estimate_bucket_selectivity(bucket, predicates);            selectivity += bucket_selectivity * (bucket.row_count as f64 / self.total_rows as f64);        }        selectivity    }    fn estimate_bucket_selectivity(        &self,        bucket: &MultiColumnBucket,        predicates: &[(usize, BinaryOperator, Value)],    ) -> f64 {        let mut bucket_selectivity = 1.0;        for (col_idx, op, value) in predicates {            if *col_idx >= bucket.bounds.len() {                continue;            }            let (min, max) = &bucket.bounds[*col_idx];            let col_selectivity = match op {                BinaryOperator::Eq => {                    if value >= min && value <= max {                        1.0 / bucket.distinct_count.max(1) as f64                    } else {                        0.0                    }                }                BinaryOperator::Gt => {                    if value < min {                        1.0                    } else if value >= max {                        0.0                    } else {                        let range = max.subtract(min).to_f64();                        let matching = max.subtract(value).to_f64();                        (matching / range).clamp(0.0, 1.0)                    }                }                // ... handle other operators                _ => 0.5,            };            bucket_selectivity *= col_selectivity;        }        bucket_selectivity    }}

何时使用多列统计：

5 在优化器中使用直方图

与成本模型集成

// src/optimizer/histogram_selectivity.rspub struct HistogramSelectivityEstimator {    statistics: Arc<StatisticsCatalog>,}impl HistogramSelectivityEstimator {    pub fn new(statistics: Arc<StatisticsCatalog>) -> Self {        Self { statistics }    }    pub fn estimate(&self, table: &str, column: &str, expr: &Expression) -> f64 {        let table_stats = match self.statistics.get_table(table) {            Some(stats) => stats,            None => return 0.5,  // No stats, use default        };        let col_stats = match table_stats.columns.get(column) {            Some(stats) => stats,            None => return 0.5,        };        match &col_stats.histogram {            Some(Histogram::Compressed(comp)) => {                match expr {                    Expression::BinaryOp { op, right, .. } => {                        comp.estimate_selectivity(op, right)                    }                    Expression::InList { list, .. } => {                        // Sum selectivity for each value                        list.iter()                            .map(|v| comp.estimate_selectivity(&BinaryOperator::Eq, v))                            .sum()                    }                    Expression::Between { low, high, .. } => {                        let low_sel = comp.estimate_selectivity(&BinaryOperator::Gte, low);                        let high_sel = comp.estimate_selectivity(&BinaryOperator::Lte, high);                        (low_sel + high_sel - 1.0).max(0.0)                    }                    _ => 0.5,                }            }            Some(Histogram::EquiDepth(equi)) => {                match expr {                    Expression::BinaryOp { op, right, .. } => {                        match op {                            BinaryOperator::Eq => equi.estimate_eq(right),                            BinaryOperator::Gt => equi.estimate_gt(right),                            BinaryOperator::Lt => equi.estimate_lt(right),                            BinaryOperator::Gte => equi.estimate_gte(right),                            BinaryOperator::Lte => 1.0 - equi.estimate_gt(right),                            _ => 0.5,                        }                    }                    _ => 0.5,                }            }            None => {                // No histogram, fall back to MCV or default                self.estimate_from_mcv(col_stats, expr)            }        }    }    fn estimate_from_mcv(&self, col_stats: &ColumnStatistics, expr: &Expression) -> f64 {        match expr {            Expression::BinaryOp { op: BinaryOperator::Eq, right, .. } => {                // Check if value is in MCV list                for (mcv_val, frequency) in &col_stats.most_common_values {                    if mcv_val == right {                        return *frequency;                    }                }                // Not in MCV, estimate based on distinct count                1.0 / col_stats.distinct_count.max(1) as f64            }            _ => 0.5,  // Default for other operators        }    }}// Updated cost model using histogramsimpl CostModel {    pub fn estimate_selectivity_with_histograms(        &self,        estimator: &HistogramSelectivityEstimator,        table: &str,        expr: &Expression,    ) -> f64 {        match expr {            Expression::BinaryOp { op, left, right, .. } => {                // Find which side is a column reference                if let Expression::Identifier(ident) = left.as_ref() {                    return estimator.estimate(table, &ident.value, &Expression::BinaryOp {                        op: op.clone(),                        left: Box::new(Expression::Identifier(ident.clone())),                        right: right.clone(),                    });                }                // Default estimate                0.5            }            Expression::InList { expr, list, negated } => {                let base_selectivity = list.iter()                    .map(|v| estimator.estimate(table, "column", v))                    .sum::<f64>()                    .min(1.0);                if *negated { 1.0 - base_selectivity } else { base_selectivity }            }            _ => 0.5,        }    }}

示例：真实查询优化

-- Table statistics (from ANALYZE):-- users: 1,000,000 rows-- users.balance: histogram shows 80% have balance < $100-- Query:SELECT * FROM users WHERE balance > 100-- Without histogram:-- Selectivity estimate: 0.33 (fixed guess)-- Estimated rows: 333,333-- Chosen plan: SeqScan (cost: 5000)-- With histogram:-- Selectivity estimate: 0.20 (from histogram)-- Estimated rows: 200,000-- Chosen plan: IndexScan (cost: 2000) ← Better!

6 直方图维护

何时更新统计

// src/optimizer/stats_maintenance.rspub struct StatsMaintenancePolicy {    auto_analyze_threshold: u64,  // Rows modified before auto-analyze    auto_analyze_scale_factor: f64,  // Fraction of table    last_analyze_threshold: chrono::Duration,  // Max time since last analyze}impl Default for StatsMaintenancePolicy {    fn default() -> Self {        Self {            auto_analyze_threshold: 50,  // PostgreSQL default            auto_analyze_scale_factor: 0.2,  // 20% of table            last_analyze_threshold: chrono::Duration::days(7),        }    }}pub struct StatsMaintenanceManager {    catalog: Arc<Catalog>,    policy: StatsMaintenancePolicy,    modification_counts: HashMap<String, u64>,  // table → rows modified}impl StatsMaintenanceManager {    pub fn check_and_analyze(&mut self, table: &str) -> Result<bool, AnalyzerError> {        let table_stats = self.catalog.get_table_statistics(table);        let modified_rows = self.modification_counts.get(table).copied().unwrap_or(0);        let needs_analyze = if let Some(stats) = table_stats {            let threshold = self.policy.auto_analyze_threshold                + (stats.row_count as f64 * self.policy.auto_analyze_scale_factor) as u64;            modified_rows >= threshold        } else {            true  // No stats, need initial analyze        };        if needs_analyze {            self.analyze_table(table)?;            self.modification_counts.insert(table.to_string(), 0);            Ok(true)        } else {            Ok(false)        }    }    pub fn record_modification(&mut self, table: &str, rows_affected: u64) {        let count = self.modification_counts.entry(table.to_string()).or_insert(0);        *count += rows_affected;    }    fn analyze_table(&self, table: &str) -> Result<(), AnalyzerError> {        // Run ANALYZE on the table        let analyzer = StatisticsAnalyzer::new(self.catalog.clone());        let stats = analyzer.analyze_table(table)?;        self.catalog.store_statistics(&stats)?;        Ok(())    }}

增量直方图更新

问题： 对于大型表，完整重建很昂贵。

解决方案： 对于小变更进行增量更新。

impl EquiDepthHistogram {    /// Update histogram with new values (for small changes)    pub fn update(&mut self, new_values: &[Value], deleted_values: &[Value]) {        // Update total row count        self.total_rows += new_values.len() as u64;        self.total_rows -= deleted_values.len() as u64;        // For each new value, find its bucket and increment count        for value in new_values {            for bucket in &mut self.buckets {                if value >= &bucket.lower_bound && value <= &bucket.upper_bound {                    bucket.row_count += 1;                    bucket.cumulative_count += 1;                    break;                }            }        }        // For deleted values, decrement counts        for value in deleted_values {            for bucket in &mut self.buckets {                if value >= &bucket.lower_bound && value <= &bucket.upper_bound {                    bucket.row_count = bucket.row_count.saturating_sub(1);                    bucket.cumulative_count = bucket.cumulative_count.saturating_sub(1);                    break;                }            }        }        // If too many changes, trigger full rebuild        let total_changes = new_values.len() + deleted_values.len();        if total_changes as f64 / self.total_rows as f64 > 0.1 {            // Mark for full rebuild            self.needs_rebuild = true;        }    }}

7 用 Rust 构建的挑战

挑战 1：值比较

问题： SQL 值可以是不同类型（int、float、string、date）。

// ❌ Doesn't work - can't compare different typespub enum Value {    Integer(i64),    Float(f64),    String(String),    Date(chrono::NaiveDate),}impl Ord for Value {    fn cmp(&self, other: &Self) -> Ordering {        // Can't compare Integer with String!    }}

解决方案：类型感知比较

// ✅ Works - handle type mismatchesimpl Value {    pub fn compare(&self, other: &Self) -> Result<Ordering, ValueError> {        match (self, other) {            (Value::Integer(a), Value::Integer(b)) => Ok(a.cmp(b)),            (Value::Float(a), Value::Float(b)) => a.partial_cmp(b).ok_or(ValueError::NaN),            (Value::String(a), Value::String(b)) => Ok(a.cmp(b)),            (Value::Integer(a), Value::Float(b)) => (*a as f64).partial_cmp(b).ok_or(ValueError::NaN),            (Value::Float(a), Value::Integer(b)) => a.partial_cmp(&(*b as f64)).ok_or(ValueError::NaN),            _ => Err(ValueError::TypeMismatch),        }    }}

挑战 2：内存使用

问题： 许多列的直方图可能使用大量内存。

// ❌ Memory explosion// 1000 tables × 20 columns × 100 buckets × 32 bytes = 64 MB

解决方案：压缩桶边界

// ✅ Compressed representationpub struct CompressedBucket {    pub lower_bound_idx: u32,  // Index into shared value pool    pub upper_bound_idx: u32,    pub row_count: u32,}pub struct CompressedHistogram {    shared_values: Vec<Value>,  // Deduplicated values    buckets: Vec<CompressedBucket>,}

挑战 3：线程安全统计

问题： 统计需要在 ANALYZE 更新期间在查询计划期间读取。

// ❌ Race conditionpub struct StatisticsCatalog {    tables: HashMap<String, TableStatistics>,}

解决方案：Arc<RwLock<>> 用于并发访问

// ✅ Thread-safepub struct StatisticsCatalog {    tables: Arc<RwLock<HashMap<String, Arc<TableStatistics>>>>,}impl StatisticsCatalog {    pub fn get_table(&self, name: &str) -> Option<Arc<TableStatistics>> {        let tables = self.tables.read().unwrap();        tables.get(name).cloned()    }    pub fn update_table(&self, stats: TableStatistics) {        let mut tables = self.tables.write().unwrap();        tables.insert(stats.table_name.clone(), Arc::new(stats));    }}

8 AI 如何加速这项工作

AI 做对了什么

AI 做错了什么

模式： AI 处理教科书案例良好。边界情况（边界、NULL、增量）需要手动精炼。

示例：调试选择性

我问 AI 的问题：

“直方图显示 20% 的行有 balance > 100，但优化器估计 5%。为什么？”

我学到的：

1. MCV 列表没有被首先检查
2. 缺少非 MCV 分数调整
3. 桶内范围估计颠倒了

结果： 修复选择性估计：

pub fn estimate_selectivity(&self, op: &BinaryOperator, value: &Value) -> f64 {    // Check MCV first    for (mcv_val, frequency) in &self.mcv_list.values {        if mcv_val == value {            return match op {                BinaryOperator::Eq => *frequency,                BinaryOperator::Neq => 1.0 - frequency,                _ => 0.0  // Fall through for range ops            };        }    }    // Use histogram for non-MCV values    let histogram_sel = self.histogram.estimate_gt(value);    let non_mcv_fraction = 1.0 - self.mcv_list.total_mcv_frequency;    histogram_sel * non_mcv_fraction  // ← Was missing this!}

总结：直方图统计一张图

Zmxvd2NoYXJ0IFRECiAgICBzdWJncmFwaCAiRGF0YSBDb2xsZWN0aW9uIgogICAgICAgIEFbVGFibGUgRGF0YV0gLS0+IEJ7U2FtcGxlIG9yIEZ1bGw/fQogICAgICAgIEIgLS0+fFNtYWxsIHRhYmxlfCBDW0Z1bGwgU2Nhbl0KICAgICAgICBCIC0tPnxMYXJnZSB0YWJsZXwgRFtSZXNlcnZvaXIgU2FtcGxpbmddCiAgICBlbmQKICAgIAogICAgc3ViZ3JhcGggIkhpc3RvZ3JhbSBCdWlsZGluZyIKICAgICAgICBDIC0tPiBFW1NvcnQgVmFsdWVzXQogICAgICAgIEQgLS0+IEUKICAgICAgICBFIC0tPiBGe0J1aWxkIFR5cGU/fQogICAgICAgIEYgLS0+fFVuaWZvcm0gZGF0YXwgR1tFcXVpLVdpZHRoXQogICAgICAgIEYgLS0+fFNrZXdlZCBkYXRhfCBIW0VxdWktRGVwdGhdCiAgICAgICAgRiAtLT58V2l0aCBkdXBsaWNhdGVzfCBJW0NvbXByZXNzZWQgKyBNQ1ZdCiAgICBlbmQKICAgIAogICAgc3ViZ3JhcGggIk11bHRpLUNvbHVtbiIKICAgICAgICBKW0NvcnJlbGF0ZWQgQ29sdW1uc10gLS0+IEtbTXVsdGktRGltZW5zaW9uYWwgQnVja2V0c10KICAgIGVuZAogICAgCiAgICBzdWJncmFwaCAiVXNhZ2UgaW4gT3B0aW1pemVyIgogICAgICAgIEggLS0+IExbU2VsZWN0aXZpdHkgRXN0aW1hdGlvbl0KICAgICAgICBJIC0tPiBMCiAgICAgICAgSyAtLT4gTAogICAgICAgIEwgLS0+IE1bQ29zdCBDYWxjdWxhdGlvbl0KICAgICAgICBNIC0tPiBOW1BsYW4gU2VsZWN0aW9uXQogICAgZW5kCiAgICAKICAgIHN1YmdyYXBoICJNYWludGVuYW5jZSIKICAgICAgICBPW0lOU0VSVC9VUERBVEUvREVMRVRFXSAtLT4gUFtUcmFjayBNb2RpZmljYXRpb25zXQogICAgICAgIFAgLS0+IFF7VGhyZXNob2xkIFJlYWNoZWQ/fQogICAgICAgIFEgLS0+fFllc3wgUltBdXRvLUFOQUxZWkVdCiAgICAgICAgUSAtLT58Tm98IFNbSW5jcmVtZW50YWwgVXBkYXRlXQogICAgICAgIFIgLS0+IEUKICAgIGVuZAogICAgCiAgICBzdHlsZSBBIGZpbGw6I2UzZjJmZCxzdHJva2U6IzE5NzZkMgogICAgc3R5bGUgTiBmaWxsOiNlOGY1ZTksc3Ryb2tlOiMzODhlM2MKICAgIHN0eWxlIEwgZmlsbDojZmZmM2UwLHN0cm9rZTojZjU3YzAw

关键要点：

进一步阅读：

• PostgreSQL Source: src/backend/commands/analyze.c
• “Random Sampling for Histogram Construction” by Vitter et al.
• “Selectivity Estimation for Range Queries” by Ioannidis et al.
• PostgreSQL Documentation: “Statistics Used by the Planner”
• Vaultgres Repository: github.com/neoalienson/Vaultgres

Our selectivity estimates are guesses:

// From Part 7 - simplified (wrong!) estimatesfn estimate_selectivity(&self, expr: &Expression) -> f64 {    match expr {        BinaryOperator::Eq => 0.01,   // Always 1%? Wrong!        BinaryOperator::Gt => 0.33,   // Always 33%? Wrong!        _ => 0.5,                      // Always 50%? Very wrong!    }}

Real data isn’t uniform: