简介

• 1: Crib 是什么
• 2: 收录内容
• 3: 工作原理
• 4: 发布状态

1 - Crib 是什么

Crib 是一款 macOS 应用，把 PostgreSQL 6.3 到 20devel 共 31 条版本线的中英文手册、一份结构化的 PostgreSQL Wiki，以及你自己的笔记和更正放在同一个本地资料库里。它不需要账号，不依赖网络，也不需要连接 PostgreSQL 服务器。

它解决什么问题

查 PostgreSQL 文档时常见的几个麻烦：

• 版本对不上。 生产库还在 9.6 或 12，网上搜到的却是最新版手册。Crib 收录每条版本线，搜索时可以直接写 PG96: vacuum。
• 符号搜不到。 ->>、@@、\dC 这类写法在通用搜索引擎里会被当成标点丢掉。Crib 先按精确名称匹配，再搜正文。
• 中英文来回找。 读中文手册遇到拿不准的句子，想看英文原文，往往要重新翻目录。Crib 一键切到另一种语言的同一节，也可以两栏对照。
• 断网或内网环境。 机房、飞机、隔离网络里打不开在线文档。Crib 首次启动就能离线阅读和搜索。
• 笔记散落各处。 排障时记下的结论和手册原文分开放，过一阵就找不到出处。Crib 的笔记、书签和更正挂在具体章节上，内容更新后会重新核对位置，找不到的单独列出。

适合谁

和其他方式的区别

Crib 借鉴了 Dash 的片段库、系统服务和本地 API 等用法。区别在于内容格式：Crib 的 .crib 资料包自带双语章节对应、版本信息和签名，不使用也不兼容 Dash docset。

它不做什么

• 不连接数据库，不执行 SQL。
• 不翻译。中文内容只来自已有的中文译本；某一节没有译文时，明确显示缺失，不拿英文冒充。
• 不改写官方原文。你的更正存在个人资料库里，与原文并列显示。
• 没有云同步。个人资料可以导出、导入和备份，但不会自动上传到任何地方。

现在的状态

Crib 还在开发中，没有公开安装包。本站文档描述的是当前开发构建的行为。已经完成和尚未完成的部分见发布状态。

接下来读什么

• 收录内容 — 31 条版本线和 30 个 Wiki 集合的明细。
• 工作原理 — 资料包、搜索索引和个人资料怎样分开存放。
• 安装与首次启动 — 两个版本的区别，首次启动做了什么。

2 - 收录内容

Crib 的内容分两类：PostgreSQL 手册，每条版本线一个中英双语资料包；Wiki，一个独立的双语资料包。所有内容都来自固定版本的输入，构建时记录每个文件的来源和哈希，并用 Ed25519 签名。

手册

31 条版本线，每条一套英文、一套中文，共 62 套完整手册。每条线固定到一个确切的内容版本，不跟随上游自动更新；新的小版本发布后，以新的资料包修订号加入版本目录，旧版本保留。

来源

• 英文手册：PostgreSQL 全球开发组发布的官方文档，按上表版本从固定的源码归档构建。19 和 20 缺少现成的 HTML 构建，从固定的源码输入补建。
• 中文手册：pgdoc 收录的各版本简体中文译本。每套手册保留原有的译者署名和版权声明，例如 18.6 中文版署名“翻译：冯若航，Pigsty 项目组”。
• 历史资源：6.3、6.4 等早期中文版缺失的 CSS 和图片，只从同一版本的另一语言版本或核实过的同版材料补齐，并逐个记录来源。

规模

中英文章节对应只在两侧手册源码里都能找到唯一的章节声明、且 HTML 中有唯一的物理锚点时才建立；标题相同或自动生成的 ID 不算数。没有对应的章节，切换语言时回到最近的已对应父节，并明确提示。

已知缺口

• 原始手册中有 80 处历史失效链接和 235 处重复锚点，Crib 保留原样并在资料包审计中列出，不臆造目标。
• 本地 SVG 插图（PG 12–20 中的 GIN、页面布局、GEQO 等图）以静态图片显示，脚本与远程资源一律去除。

Wiki

Wiki 来自 pg.center 2026-10-24 的冻结快照，打成一个独立的双语资料包。它把散落在手册各处的对象整理成条目：一个配置参数、一个函数、一个等待事件各是一条，带类型、默认值、出现版本和来源。导航分六组共 30 个集合：

前五组是 29 种实体集合；“版本”是组合视图，把版本发布、CVE 与能力矩阵放在一起看。

Wiki 的边界

• 不是每个集合在每个版本、每种语言都有覆盖。部分扩展集合只覆盖 PG 10–20，表访问方法从 PG 12 开始。
• “未观测到”和“已移除”是两回事。只有来源明确写出时才标记某项被移除，覆盖缺口不会被当成删除。
• 每条事实显示来源、版本和观测时间；某种语言没有正文时显示缺失，不用另一种语言填充。
• Wiki 中引用的外部网页和插图不随包下载。

你自己的资料

笔记、书签、标签、阅读历史、本地更正和片段不属于任何资料包，单独存放在用户目录里。卸载或更新文档版本不会删除它们。见笔记、书签与本地更正和用户数据与迁移。

3 - 工作原理

Crib 由两部分组成：构建端用 Go 把手册和 Wiki 做成签名的资料包和预建索引；macOS 应用用 SwiftUI、少量AppKit、WKWebView 和 SQLite FTS5 读取它们。应用运行时不需要网络服务，也不启动本地 HTTP 服务器（本地 API 是可选功能，默认关闭）。

flowchart LR
  P["手册源码与 HTML<br>Wiki 冻结快照"] --> G["Go 构建工具<br>crib-pack"]
  G --> B["签名资料包<br>.crib"]
  G --> S["出厂搜索索引<br>seed"]
  B --> V["应用：验签与安全解包"]
  V --> W["后台构建新的搜索世代"]
  S --> A["当前世代"]
  W --> A
  A --> Q["搜索"]
  A --> R["阅读器 WKWebView"]
  U["个人资料<br>user.sqlite"] --> R
  U --> Q

三类数据分开存放

资料包导入器不能写个人资料库，个人资料也不建立指向资料包的级联删除。所以卸载一个版本不会删掉挂在上面的笔记，只会让它们暂时显示为目标不可用。

资料包

每条 PostgreSQL 版本线是一个双语原子包，Wiki 是另一个。包里有 manifest.json、签名、来源清单、章节数据库、两种语言的文档和许可文件。同一个版本、同一个修订号的文件字节永远不变；内容有变化就发新的修订号。格式细节见资料包格式。

应用只接受签名有效的包：检查清单签名、文件长度和哈希、ZIP 边界和资源清单，拒绝绝对路径和路径穿越。

搜索世代

搜索时只查一个聚合的 SQLite 数据库，不同时挂接多个包的数据库。这样所有版本的正文用同一套统计排序，结果可以直接比较。

这个聚合数据库叫一个“世代”。它由当前启用的资料包组合唯一决定：

• 完整离线版和 Core 版都随附一个出厂世代，首次启动直接使用，不需要建索引。
• 导入、更新、启用或停用资料包时，应用在后台从各包流式读取章节，写一个新的世代。
• 新世代验证通过后才原子切换。构建期间旧世代照常服务，已经打开的阅读窗口继续停在原来的世代上。
• 构建失败、被取消或磁盘不足时，保留原来的世代，不会出现一半新一半旧的状态。

只移动版本别名（例如 pg18 从 18.6 指向 18.7）不需要重建世代；只有实际更换资料包才重建。

搜索

查询先解析成结构化条件：版本前缀和 lang:、kind: 等过滤器来自白名单，其余是文本。用户输入不会直接拼进 SQL。排序分层进行：

1. 当前范围内的精确名称和别名（work_mem、->>、\dC、SQLSTATE 代码）。
2. 名称前缀。
3. 标题和章节名。
4. 正文。

中文按连续汉字的重叠双字切分：“事务隔离”切成“事务、务隔、隔离”。单个汉字（例如“锁”）走标题和名称的字符索引，在有限范围内查，不扫描全库正文。构建端和应用使用同一个切分规则（analyzer），并用同一组测试样例核对。具体写法见搜索。

阅读器

正文是资料包里的 HTML，由 WKWebView 通过一个受限的内部地址读取：地址里带有资料包清单的摘要，只能访问该包内的文件，不能加载远程脚本或资源。切换语言时，按两种语言之间已验证的章节对应跳转，没有对应就回到父节并提示。

个人资料

user.sqlite 使用 WAL 和完整同步写入，每次保存在一个事务里比较修订号：两个编辑器同时改同一条笔记时，后保存的一方得到冲突提示，不会覆盖对方。迁移或备份使用 SQLite 在线备份，而不是复制正在使用的数据库文件。个人资料库打不开时，只停用个人功能，阅读和搜索照常工作。见笔记、书签与本地更正。

4 - 发布状态

已完成

这些是源码层面的里程碑，在本地开发构建上验证过：

• 31 条版本线、62 套手册和 Wiki 全部构建、签名并通过完整性审计；完整离线版的出厂搜索索引可以直接使用。
• 搜索、阅读、双语切换与对照、笔记、书签、本地更正、片段、资料包管理、本地 API、MCP 和系统服务均已实现。
• 由 PGDash 改名为 Crib：产品、应用、用户目录和输出名称已统一；旧用户资料按一次性迁移复制，旧格式继续兼容。见用户数据与迁移。
• 签名版本目录 v3：每个版本带生命周期（默认、常规、历史、开发、不再提供），别名、搜索、资料库和阅读器共用同一个版本模型。
• Core 版加按需下载：内置 18.6 和启动索引，其余版本从签名目录下载，可断点续传。
• 2026-11-06 完成界面与文案重设计，资料包扩展名改为 .crib（旧的 .pgdocpack 继续有效）。

尚未完成

“发布就绪”和“已发布”是两个独立的状态，目前都为否。

本站文档的适用范围

• 文档描述的是 2026-11-06 前后的开发构建。正式发布前，界面文字、默认快捷键和部分细节仍可能调整。
• 标注“尚未实测”“待验收”的行为，不要当作已经保证。
• 截图来自开发构建的离屏快照，与正式版可能略有差异。

进展更新发在开发日志。