Crib：放在手边的 PostgreSQL 手册 on Crib

11 月第一周：深度评审与界面重设计

Fri, 06 Nov 2026 00:00:00 +0800

这一周做了三件事。它们都还停留在本地开发构建，没有发布。

深度设计评审的修复

11 月 5 日对整个项目做了一轮深度设计评审，列出了 9 个最高优先级（P0）和 8 个次高优先级（P1）问题。本周修完了其中 8 个 P0 和全部 P1，以及各子系统的大部分中低优先级问题；复核修复本身时又发现二十多处问题，也逐项修复并补了回归测试。源码也是在这一轮第一次进入 Git，按主题分批提交。

为什么做 Crib

Fri, 06 Nov 2026 00:00:00 +0800

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

版本要对得上

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

Crib 是什么

Mon, 01 Jan 0001 00:00:00 +0000

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

安装与首次启动

Mon, 01 Jan 0001 00:00:00 +0000

还没有公开安装包

Crib 仍在开发中，没有公开下载，也没有确定价格和许可证。发布后安装包会放在下载页。本页描述的是当前开发构建的行为。开发构建只有临时签名，没有经过 Apple 公证。

系统要求

项目	现状
部署目标	macOS 14
已测试	只在 Apple 芯片（arm64）的开发机上测试过
未测试	实际运行在 macOS 14 上、Intel Mac
网络	首次启动和日常阅读、搜索都不需要；只有下载其他版本时需要

部署目标是编译设置，不等于已经在 macOS 14 上验证过。正式发布前会单列实测过的系统和机型。

本地 API

Mon, 01 Jan 0001 00:00:00 +0000

本地 API 默认关闭。启用后只监听 127.0.0.1，只读，只能访问当前已启用的资料包。笔记、书签、阅读历史、片段和更正都不对外开放。Crib 自己的搜索和阅读不经过这个接口。

管理资料库

Mon, 01 Jan 0001 00:00:00 +0000

资料库是 Crib 里已安装的全部文档。打开方式：菜单“资料库 → 管理资料库…”、工具栏的资料库按钮，或主页的“资料库”。菜单“资料库 → 获取更多版本…”和主页的“获取版本”直接打开“全部版本”。

用户数据与迁移

Mon, 01 Jan 0001 00:00:00 +0000

用户目录

Crib 的数据在 ~/Library/Application Support/Crib/。下面列出与你有关的部分，有些文件在用到相应功能后才出现：

- user.sqlite # 个人资料：笔记、书签、标签、阅读历史、更正
- preferences.json # 设置
- session.json # 窗口、标签页和阅读位置
- snippets.json # 片段库
- backups/ # 个人资料库升级结构前自动做的备份
- Library/ # 下载或导入的资料包、搜索世代和登记表
 - packs/
 - generations/
 - registry.sqlite
- Distribution/ # 版本目录缓存
- Distribution-partials/ # 中断下载的已下载部分，保留 7 天
- Distribution-rejected/ # 无法再通过校验的旧目录缓存，保留最近 5 份
- api/ # 本地 API 的地址、密钥和锁，启用 API 后出现
- crib-migration.json # 从 PGDash 迁移的记录，迁移过才有

App 内置的资料包和初始搜索索引在 Crib.app/Contents/Resources/Library 里，只读，随 App 一起替换。

从 PGDash 改名为 Crib

Fri, 06 Nov 2026 00:00:00 +0800

Crib 开发前期叫 PGDash。2026 年 10 月 28 日决定正式改名为 Crib，10 月 31 日在本地完成迁移并验证。如果你没用过 PGDash 的开发构建，这篇可以跳过。

改了什么

项目	原来	现在
应用	`PGDash.app`	`Crib.app`
Bundle ID	`com.pgsty.pgdash.*`	`com.pgsty.crib`
用户目录	`~/Library/Application Support/PGDash`	`~/Library/Application Support/Crib`
深链接	`pgdash://`	`crib://`
MCP 程序与配置键	`PGDashMCP`、`pgdash`	`CribMCP`、`crib`
环境变量	`PGDASH_*`	`CRIB_*`
导出文件名	`PGDash-*`	`Crib-*`
签名版本目录	`pgdash-signed-catalog-1`	`crib-signed-catalog-1`（v3）

没有改的

已经签名的内容不能改名，否则签名和哈希就对不上了。下面这些标识保持原样，它们只是格式的名字，不代表产品名：

让符号、中文和版本号一起被搜到

Fri, 06 Nov 2026 00:00:00 +0800

PostgreSQL 用户搜索的东西很杂：参数名 work_mem，运算符 ->>，psql 命令 \dC，错误码 23505，中文词“复制延迟”，还常常带着版本号。通用的全文检索对这些都不友好。这篇说明 Crib 的做法。

MCP

Mon, 01 Jan 0001 00:00:00 +0000

Crib 随 App 附带一个 stdio MCP 程序 Crib.app/Contents/MacOS/CribMCP，不需要安装 Python、uv 或 Node。它通过本地 API 只读地搜索和读取已启用的文档。

版本与别名

Mon, 01 Jan 0001 00:00:00 +0000

收录的版本线

Crib 收录 31 条 PostgreSQL 手册版本线，每条一个中英双语资料包；Wiki 是另一个资料包。默认版本是 PostgreSQL 18（18.6），也是 pg 别名的目标；只内置一个版本的构建内置的就是它。

来源与许可

Mon, 01 Jan 0001 00:00:00 +0000

Crib 自己的代码和它收录的内容是两回事：应用的许可证不会覆盖手册、译文、Wiki、字体和图片各自的权利。本页列出每类内容的来源和目前的许可状态。

再分发许可尚未核对完成

应用代码尚未选定许可证，源码未公开。收录内容的再分发许可正在逐项核对，在核对完成前不会公开分发。本页是来源清单，不是新的授权。

收录内容

Mon, 01 Jan 0001 00:00:00 +0000

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

搜索

Mon, 01 Jan 0001 00:00:00 +0000

搜索 work_mem（2026-11-06 开发构建，深色外观）

按 ⌘ 加 L 聚焦工具栏中的搜索框，⌘ 加 K 是备用快捷键。结果随输入更新。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

现在能下载吗？

还不能。Crib 只有本地开发构建，Developer ID 签名、Apple 公证、内容再分发许可和生产资料包目录都还没完成。见发布状态和下载。

工作原理

Mon, 01 Jan 0001 00:00:00 +0000

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

系统服务与全局快捷键

Mon, 01 Jan 0001 00:00:00 +0000

两个服务

在其他应用中选中文字，从应用菜单或右键菜单的“服务”中选择：

服务	结果	选区上限
在 Crib 中查找	打开一个新的 Crib 窗口，用选中的文字（去掉首尾空白）搜索	256 个字符
在 Crib 中创建片段	打开“设置 → 片段”，新建一个未保存的片段草稿，正文与选区完全一致，缩进和换行都保留	1,000,000 个字符

Crib 只读取系统传给服务的文字，不读取也不改写剪贴板。

下载

Mon, 01 Jan 0001 00:00:00 +0000

暂无安装包

Crib 目前只有本地开发构建，没有公开下载。下面列出计划提供的版本和发布前的剩余工作；正式发布时会在这一页给出下载链接和 SHA-256 校验值，并在开发日志公告。请不要使用其他来源分发的 “Crib” 安装包。

下载、更新与恢复

Mon, 01 Jan 0001 00:00:00 +0000

正式版本目录尚未上线

Crib 默认从 https://repo.pigsty.io/doc/catalog.json 获取版本目录。这个地址是规划中的正式目录，还没有上传，所以现在“刷新目录”拿不到正式目录。下文描述开发构建的行为，在本机测试目录上验证过，没有在公网 HTTPS 和 CDN 上测试。

阅读与双语对照

Mon, 01 Jan 0001 00:00:00 +0000

阅读手册（2026-11-06 开发构建，深色外观）

窗口布局

窗口分三栏：

笔记、书签与本地更正

Mon, 01 Jan 0001 00:00:00 +0000

笔记、书签、标签、阅读历史和更正统称个人资料，保存在 ~/Library/Application Support/Crib/ 中，与资料包分开。卸载或更新文档版本不会删除它们；个人资料出问题时，阅读和搜索照常可用。

发布状态

Mon, 01 Jan 0001 00:00:00 +0000

截至 2026-11-06：尚未发布

Crib 没有公开安装包，也没有公开源码。本页按项目内部的发布计划整理，每个阶段单独标注；一项完成不代表其他项完成。

深链接

Mon, 01 Jan 0001 00:00:00 +0000

Crib 注册了 crib 协议。点击一个 crib:// 链接，Crib 会打开它指向的章节。界面里把这类链接叫“链接”。

复制链接

在搜索结果上点右键，选“复制链接”。折叠起来的多版本结果，复制的是代表项那一条。
阅读时，从正文上方的“更多”菜单（版本、书签按钮右侧）选“复制链接”，复制正在阅读的章节。
本地 API 搜索结果中的 load_url 也是这种链接，见本地 API。

复制得到的链接形如：

资料包格式

Mon, 01 Jan 0001 00:00:00 +0000

现在没有公开的资料包，也没有正式签名密钥。发布目录规划在 https://repo.pigsty.io/doc/，还没有上传。本页描述开发构建和构建工具 crib-pack 实现的格式。

文件

资料包是一个 ZIP 文件（支持 ZIP64，条目为 stored 或 DEFLATE），条目按名称排序，时间戳固定。2026-11-06 起新发布的资料包以 .crib 结尾；之前签发的目录和归档使用 .pgdocpack，这些已签名的路径继续有效。版本目录里的归档路径只接受这两种结尾，.CRIB、.crib.zip 等都会被拒绝。

片段

Mon, 01 Jan 0001 00:00:00 +0000

片段是常用的 SQL、命令或说明文字，保存在片段库中。用的时候填好参数，复制到剪贴板，再粘贴到需要的地方。Crib 不会在其他应用里自动展开片段。

快捷键

Mon, 01 Jan 0001 00:00:00 +0000

下表是开发构建的默认值，均可在“设置 › 快捷键”中修改，见修改快捷键。菜单和工具栏的悬停提示始终显示当前生效的组合。

搜索与查找

命令	默认	菜单
搜索资料库	`⌘` 加 `L`	编辑
搜索资料库（备用）	`⌘` 加 `K`	编辑
页内查找	`⌘` 加 `F`	编辑
查找下一个	`⌘` 加 `G`	编辑
查找上一个	`⇧` 加 `⌘` 加 `G`	编辑
使用所选内容查找	`⌘` 加 `E`	编辑
跳到所选内容	`⌘` 加 `J`	编辑
筛选目录	`⇧` 加 `⌘` 加 `F`	编辑

阅读

命令	默认	菜单
切换语言	`⇧` 加 `⌘` 加 `L`	编辑
双语对照	`⇧` 加 `⌘` 加 `B`	阅读
后退	`⌘` 加 `[`	阅读
前进	`⌘` 加 `]`	阅读
返回主页	`⇧` 加 `⌘` 加 `H`	阅读
放大	`⌘` 加 `+`	阅读
缩小	`⌘` 加 `-`	阅读
实际大小	`⌘` 加 `0`	阅读
在浏览器中打开	`⌥` 加 `⌘` 加 `B`	阅读

书签、历史与笔记

命令	默认	菜单
添加书签	`⌘` 加 `D`	书签
显示书签	`⇧` 加 `⌘` 加 `D`	书签
显示历史	`⇧` 加 `⌘` 加 `Y`	书签
新建笔记	`⇧` 加 `⌘` 加 `N`	文件

标签页

命令	默认	菜单
新建标签页	`⌘` 加 `T`	文件
重新打开关闭的标签页	`⇧` 加 `⌘` 加 `T`	文件
显示上一个标签页	`⇧` 加 `⌘` 加 `[`	窗口
显示下一个标签页	`⇧` 加 `⌘` 加 `]`	窗口

不能修改的按键

位置	按键	作用
全局	`⌘` 加 `,`	设置
全局	`⌘` 加 `W`	关闭标签页或窗口
搜索框与结果	`↑` `↓`	选择结果
搜索框与结果	`↩`	打开
搜索框与结果	`⌘` 加 `↩`	在新标签页打开
搜索框与结果	`Esc`	回到正文
结果列表	`→` / `←`	展开 / 收起多版本结果
目录、书签、历史弹出框	`↑` `↓`、`↩`、`⌘` 加 `↩`、`Esc`	选择、打开、在新标签页打开、关闭
填写片段参数	`⌘` 加 `↩`	复制

片段编辑器的按键见片段。用中文输入法选词时，↩、Esc 和方向键先交给输入法，选词结束后才执行上表中的操作。