为什么做 Crib

2026-11-06 发布于文章

设计

Crib 项目组

放在手边的手册应该离线、分版本、中英文对得上，还能记下自己的结论。

PostgreSQL 的手册写得好，但查起来常常不顺手。Crib 想解决的是几个反复出现的小麻烦，而不是再做一个文档网站。

版本要对得上

线上跑着 9.6、12、14 的人很多。搜索引擎给的往往是最新版的页面，参数默认值、视图的列、函数的签名都可能已经变了。要查旧版本，就得记住 URL 规则，或者翻到页面角落去切换。

Crib 收录 6.3 到 20devel 共 31 条版本线，每条固定到一个确切的内容版本。搜索时在前面写上 PG96:，结果就只来自 9.6 的手册和 Wiki；同一个概念在多个版本里出现时，结果折叠成一组，展开就能逐版对比。pg18 这样的别名总是解析到一个确切的发布，比如 18.6；目标版本没装，就直接说没装，不拿 18.4 冒充。

中英文要对得上

中文手册降低了阅读门槛，但译文总有拿不准的地方，这时需要看英文原文的同一段。在两个网站之间来回翻目录，十几秒就过去了，思路也断了。

Crib 把每条版本线的中英文手册打成一个双语包，构建时从手册源码里找出两种语言共同的章节标识，只有两边都能唯一确定时才建立对应。阅读时一键切到另一种语言的同一节，或者两栏并排对照。62 套手册之间有 77,580 对这样的章节对应；没有对应的地方，就回到父节并告诉你，不靠标题去猜。

断网也要能用

机房、内网、飞机上，在线文档打不开，下载的 PDF 又没法跨版本搜。Crib 的手册、Wiki 和搜索索引都随应用安装，第一次打开就能断网阅读和搜索，不需要先下载、先建索引。完整离线版随附全部内容；Core 版只带 18.6，其余版本需要时再从签名目录下载，下载、校验和重建索引都在后台完成，验证通过才切换。

符号和中文都要搜得到

->>、@@、\dC、23505 这类写法是 PostgreSQL 用户最常查的东西，也是通用搜索最容易丢掉的东西。中文又没有空格分词，“锁”“索引”这样的短词很难搜准。Crib 先按精确名称查，再搜正文；中文按双字切分，单个汉字走名称索引。细节见另一篇文章。

自己的结论要留得住

排障时查到的结论、发现的译文问题，记在别处很快就和原文脱节了。Crib 的笔记、书签和本地更正挂在具体章节上，存在独立的个人资料库里，官方原文不动。内容更新后，笔记按原来的锚点重新定位，找不到就列出来等你处理；本地更正则暂停显示，列入“待重新定位”。所有个人资料都可以导出成 Markdown 加 JSON。

为什么是原生 macOS 应用

需要的是原生窗口和标签页、系统服务菜单、可靠的输入法处理和键盘操作，以及不依赖本地 HTTP 服务的离线阅读。所以界面用 SwiftUI 和少量 AppKit，正文用 WKWebView 通过受限的内部地址读取资料包，搜索用 SQLite FTS5。构建端用 Go 生产和验证资料包，两边共用同一套格式合同和测试样例。