1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | pgvector-semantic-search-timescale-pg-aiguide | — |
| 项目自述名称 | pg-aiguide（skill 本身在 SKILL.md 中命名为 pgvector-semantic-search） |
GitHub |
| 作者/维护者 | Timescale（对外品牌 Tiger Data），官方组织仓库 | GitHub API |
| 来源链接 | https://github.com/timescale/pg-aiguide/tree/main/skills/pgvector-semantic-search | — |
| 许可证 | Apache-2.0 | GitHub API |
| GitHub Stars | 1,791（整个 pg-aiguide 仓库口径；该仓库是包含 10 个 Postgres 相关 skill 的合集，此数字不代表本 skill 自身热度） | GitHub API |
| Forks | 98 | GitHub API |
| 最新版本 | 0.5.1（package.json）；最近一次正式 Release 为 v0.5.0，发布于 2026-04-28 | GitHub API |
| 安装方式 | npx skills add timescale/pg-aiguide --skill pgvector-semantic-search |
官方 README |
2. 功能介绍与亮点
pgvector-semantic-search 是 pg-aiguide 项目里专攻向量检索的参考文档型 skill：agent 触发后即可获得一套针对 PostgreSQL + pgvector 扩展的调优知识库，覆盖索引选型（HNSW 与 IVFFlat 的取舍）、存储类型（halfvec 减半存储与索引体积）、二值量化（超大数据集下配合重排序召回）、过滤检索策略（迭代扫描、局部索引、分区）、批量导入顺序，以及一份“症状→原因→修复”的故障排查表。
主要亮点：
- 纯参考文档型 skill，agent 只读取 Markdown 指导写 SQL，不执行代码、不发起网络请求
- 给出明确的“默认配置”（Golden Path）：
halfvec存储 + HNSW 索引（m=16, ef_construction=64）+ 余弦距离，减少新手在多种索引/距离度量间反复试错 - 覆盖从千级到千万级向量规模的容量估算表与量化决策依据，而不只是给一个笼统的“建索引”建议
- 隶属于 pg-aiguide 项目：该仓库另有表设计、混合检索（BM25+向量）、PostGIS 空间数据、TimescaleDB hypertable 等 9 个细分 skill，可按需单独安装
3. 适用场景
所属分类：工程效率与代码质量
适合用 Claude Code / Codex 等 agent 构建 RAG（检索增强生成）或语义搜索功能、把 PostgreSQL 作为向量数据库使用的开发者；尤其适合不确定该选 HNSW 还是 IVFFlat、不清楚何时该上二值量化、或过滤检索总是召回不足的场景——这些是 pgvector 实践中最容易踩坑、也最难凭记忆写对的细节。
4. 跨 Agent 兼容性
- Claude Code：原生支持——官方 README 明确列出 Claude Code，并提供专门的 Claude Code 插件市场安装路径（
claude plugin marketplace add timescale/pg-aiguide） - Codex：官方 README 将 Codex 列入可通过
npx skills安装的受支持 agent 名单；但仓库内有一条开放中的社区 issue 请求“为 Codex 补充专门的安装脚本”，说明该路径的打磨程度可能不及 Claude Code 成熟 - OpenClaw：未验证——未见相关材料
- Hermes Agent：未验证——未见相关材料
（npx skills 是独立于 pg-aiguide 的第三方跨 agent 安装器，官方称支持 40 余种 agent；仓库另含 .cursor-plugin 目录为 Cursor 做了专门适配，但 Cursor 不在本报告追踪的四个生态之内）
5. 推荐理由
RAG 与语义搜索是当下最常见的 AI 应用需求之一，而 pgvector 的索引参数、存储类型与过滤策略选择很容易被 agent 写错或写得次优，导致召回率差或查询变慢。这份 skill 由深耕 Postgres 生态的官方厂商 Timescale 维护，把索引调优、内存容量估算、过滤检索这些原本需要查阅多份文档、反复试错才能掌握的经验固化成可直接套用的默认配置与故障排查表，且因为纯文档、不执行代码，风险面很小，适合作为构建向量检索功能时的常驻参考。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Timescale（Tiger Data）官方仓库整体 1,791 stars（合集口径，不代表本 skill 自身热度）；该 skill 由外部贡献者提交的 PR 引入，仓库还有多条来自仓库外部用户的真实 issue（如请求补充 Codex 安装脚本、修复文档链接等），显示有持续的真实使用者 |
| 可用性 | 9 | 一条命令 npx skills add timescale/pg-aiguide --skill pgvector-semantic-search 即可安装；SKILL.md 文档详尽，含默认配置、参数对照表、容量估算表与症状-修复对照表；要求 PostgreSQL 15+ 与 pgvector 0.8.0+（均为免费开源组件，无付费依赖）；仓库近 1 个月内有更新 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
- shell 命令执行范围：skill 本身是纯 Markdown 参考文档，agent 只读取不执行，仓库虽含用于生成文档索引的内部脚本，但那是维护者自用工具，安装 skill 不会触发
- 联网外发：skill 本体不发起任何网络请求；正文仅以链接形式引用 pgvector 官方 README 供参考阅读
- API key 存储：不需要任何密钥或凭据，只需用户自备已装好 pgvector 扩展的 PostgreSQL 实例
- 可疑指令：全文抓取阅读未发现面向 AI 助手的可疑指令、混淆代码或数据外发企图
- 作者信誉：Timescale 为知名开源 Postgres 时序数据库厂商，仓库署名与官方域名一致，未见刷星或 SEO 操纵痕迹
- License：Apache-2.0，明确
- 最近维护：仓库整体最近一次提交在 2026-06-26，一个月内
7. 跟同类 Skills 相比的优势
| Skill | 定位 | 与本 skill 的差异 |
|---|---|---|
| rag-architect（Jeffallan/claude-skills 合集内） | 面向整个 RAG 系统的架构设计——文档切块、嵌入模型选择、向量库选型、混合检索与重排序评估 | 定位更宏观、不绑定具体数据库；本 skill 专攻已选定 PostgreSQL+pgvector 场景下的索引类型、参数调优与内存容量估算等落地细节，两者可搭配使用 |
| weaviate-claude-skills（saskinosie） | 连接本地 Weaviate 向量数据库，管理集合、导入数据并做 RAG 查询 | 面向 Weaviate 这一独立向量数据库产品，需要额外部署 Weaviate 服务；本 skill 让开发者复用已有的 PostgreSQL 实例做向量检索，无需引入新的数据库组件 |
8. 用户评价
该技能所在的 pg-aiguide 仓库有真实外部用户通过 GitHub issue 提出改进请求（如请求为 Codex 补充专属安装脚本、修复文档中的失效链接），但截至目前尚未见到专门针对 pgvector-semantic-search 这一具体子技能的具名第三方评价。该技能已被 LobeHub、AgentSkills.so 等第三方 Agent Skill 目录收录展示。
9. 其他补充
仓库同时提供公共 MCP 服务器（mcp.tigerdata.com），可对 PostgreSQL、TimescaleDB、PostGIS 官方文档做版本感知的语义检索，作为本 skill 静态参考文档的补充；仓库还含面向 Cursor、VS Code 等编辑器的一键安装徽章。
10. 安装使用方式
- Agent Skill（推荐）：
npx skills add timescale/pg-aiguide --skill pgvector-semantic-search；若想交互式挑选仓库内其他 9 个细分 skill，去掉--skill参数即可 - Claude Code 插件市场：
claude plugin marketplace add timescale/pg-aiguide，随后安装 pg-aiguide 插件 - MCP 服务器（可选，用于版本感知的语义文档检索）：在 MCP 配置中添加
https://mcp.tigerdata.com/docs - 安装后无需重启，agent 在涉及 pgvector 索引、向量检索性能或 RAG 相关任务时会自动触发加载该参考文档
11. 注意事项
- 使用前需自行在目标 PostgreSQL 实例（15+）上安装并启用 pgvector 扩展（建议 0.8.0+ 以获得
halfvec、二值量化等全部特性），skill 本身不负责扩展安装 - 该 skill 覆盖的是索引与查询层面的调优，不涉及嵌入模型选择或文本切块策略，这两者对检索质量同样关键，需另行规划
- Codex 支持目前依赖通用的
npx skills跨 agent 安装器，仓库内有开放 issue 请求为 Codex 补充专门安装脚本，细节可能仍在完善中