# 官网与 CLI 统一按目录条目计数

> 官网、扩展列表、可用性摘要和目录刷新结果统一统计全部目录记录。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> **决策日期：** 2026-10-16<br>
> **状态：** Implemented（已实现），纳入 v1.10.0 候选版本，尚未发布。<br>
> **当前参考：** [`pig ext` 目录计数](/zh/ext/#catalog-count)<br>
> **范围：** 目录总数与默认列表成员；包安装和 SQL 启用方式仍由各条目定义。

## 决策 {#decision}

统一用目录记录数表示扩展总数，包括已打包的 SQL 工具与保留的生命周期记录。
CLI 根据实际加载或下载的目录计算总数。

## 背景 {#context}

目录同时服务于软件包发现和 PostgreSQL 扩展发现。已打包的 SQL 工具即使没有控制文件，
不支持 `CREATE EXTENSION`，也仍然有用。将它从默认列表和总数中排除，会让 CLI 与
官网、目录文件的统计不一致，即使按名称搜索仍能找到它。

## 考虑过的方案 {#alternatives}

- **只统计被分类为 PostgreSQL 扩展的记录。** 不采用，因为同一目录会在 CLI 与官网产生不同总数。
- **为每种条目类型新增独立的公开计数。** 当前列表契约不需要这些额外字段。
- **在 CLI 中写死对外公布的总数。** 不采用，因为下载的目录可能与内嵌目录不同。

## 契约 {#contract}

- 无筛选的默认列表包含全部目录记录，包括 SQL 工具和已移除记录。
- 文本行数与 JSON/YAML 的 `data.count` 等于实际返回的记录数。
- 搜索统计匹配条目；`--pkg` 继续统计主导包记录。
- 全局可用性文本摘要使用完整目录总数。
- 目录刷新结果的 `data.extension_count` 和消息使用实际下载的记录数。
- 官网总数跟随内嵌目录；更新后的下载目录可以有不同总数。
- 计入总数不会改变条目的 DDL 要求、生命周期状态或平台可用性。

## 影响 {#impact}

SQL 工具同时出现在默认列表和按名称搜索的结果中。输出字段的名称和类型保持稳定。
调用方应将扩展总数理解为目录覆盖范围；它不表示某个数据库已启用的扩展数，
也不表示某台主机可以安装的扩展数。

## 验证 {#verification}

v1.10.0 已提交修订的固定源码与回归测试证据包括：
[目录条目计数与可用性](https://github.com/pgsty/pig/commit/863a271a924a1634630247643d9d96200a98572d)。这些提交不构成版本发布证据。

此前的分类规则保留在
[v1.9.0 目录源码](https://github.com/pgsty/pig/blob/9eb5488847ea34827a74c9f8bb7b2dd3778f5190/cli/ext/catalog.go)
中。验收检查将解析得到的记录数与默认列表、可用性摘要、目录刷新结果逐一比较，
覆盖已打包的 SQL 工具和已移除记录，并确认搜索和包计数仍对应各自返回的行。

## 状态 {#status}

此决策于 2026-10-16 接受，已实现并包含回归测试。v1.10.0 候选版本内嵌 603 条记录，尚未发布。
计数契约见[当前参考](/zh/ext/#catalog-count)，版本边界见[发布注记](/zh/release/)。