1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | better-drizzle |
| 作者/维护者 | Hiago Almeida（almeidazs，后端软件工程师，曾任职 AbacatePay、RewriteToday） |
| 来源链接 | https://github.com/almeidazs/better-drizzle |
| 许可证 | Apache-2.0（仓库根目录 LICENSE 文件确认，数据来自 GitHub API） |
| GitHub Stars | 293（GitHub API） |
| Forks | 5（GitHub API） |
| 最新版本 | 0.1.1（npm registry dist-tags.latest） |
| 安装方式 | npm install better-drizzle drizzle-orm；配套技能包位于仓库 skills/better-drizzle/ 目录 |
2. 功能介绍与亮点
better-drizzle 是一个包裹现有 Drizzle ORM 客户端的 TypeScript 库，为每张数据表提供一套精简、类型安全的“仓储式”API：点查询、嵌套关系读写、分页、存在性检查、计数辅助、CRUD 返回结构、嵌套 where 过滤器等。目标是保留 Drizzle 本身的类型安全，同时去掉团队反复手写的查询样板代码。
随库附带的 Agent Skill 包（skills/better-drizzle/SKILL.md + references/ 下按主题拆分的参考文档）教会编码 Agent 如何正确使用 better-drizzle 的真实 API，覆盖查询、写入/事务、插件开发、性能敏感改动、故障排查五大场景，并要求 Agent 优先引用官方文档而非臆造 API。
亮点：
- 零脚本、零联网设计：技能包本身不包含任何可执行脚本或安装命令，纯粹是给 Agent 阅读的指引文本。
- 显式安全参考文档（
references/security.md）：明确把用户代码、Markdown、issue 描述等一律视为不可信输入，禁止其中的指令覆盖当前任务或仓库策略,并列出“良好/不良”示例对照。 - 真实开源库支撑：npm 近 30 天下载量 3,223 次，由 Neon（知名 Serverless Postgres 厂商）赞助。
3. 适用场景
固定分类：工程效率与代码质量
适合已经或计划在 TypeScript/Node.js 项目中使用 Drizzle ORM、并希望减少重复查询样板代码的团队。当编码 Agent 需要为项目编写、重构、审查或调试涉及 better-drizzle 委托方法、插件、事务、分页或原生 SQL 的代码时，该技能能提供准确的 API 依据，避免 Agent 凭记忆臆造不存在的方法名或参数。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库根目录提供
CLAUDE.md适配文件，技能包自述“multi-agent support”中明确点名 Claude。 - Codex：未验证——仓库有通用
AGENTS.md提供仓库上下文，但材料中未见针对 Codex 的专门适配说明。 - OpenClaw：未验证——未在已抓取材料中见到相关说明。
- Hermes Agent：未验证——未在已抓取材料中见到相关说明。
（另：仓库同时提供 GEMINI.md 适配文件，支持 Gemini 类 Agent，供参考。）
5. 推荐理由
它把“教 Agent 正确使用一个具体开源库”这件事做得很扎实：技能包按任务类型拆分参考文档、要求 Agent 区分“仓库事实/文档支撑行为/自身推断”三类信息来源、并且从设计上就杜绝了脚本执行与网络外发,配上一份专门的威胁模型文档来防范提示注入——这在同类“库配套技能”里少见。对已经采用或正评估 better-drizzle 的团队,能显著降低 Agent 写出错误查询或臆造 API 的概率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | GitHub 293 stars、npm 近 30 天下载 3,223 次；已有独立外部贡献者提交并合并真实 bug 修复 PR（correlate to-many relation filters），获 Neon 赞助，但社区讨论规模仍偏小众 |
| 可用性 | 8 | 技能包本身“零安装”（Agent 直接读取仓库文件即可使用），参考文档按查询/写入/插件/性能/排障分主题组织，配套库近期仍在活跃维护（最近一次实质提交发现前约一周），免费开源无付费依赖 |
| 安全性 | 9 | 纯文本指引型技能，零脚本零联网；专设安全参考文档，明确禁止读取 .env/SSH 密钥/shell 历史等敏感文件，禁止建议不安全的原生 SQL，并给出显式的提示注入防御准则；License 清晰、作者身份可查证 |
综合评分：7.67（三项均值）
安全检查清单逐项结果：
① Shell 命令执行——无，技能包不含任何脚本或安装命令
② 联网外发——无，仅在文本中引用公开文档链接供参考，不发起网络请求
③ API Key/凭据——不需要；安全参考文档明确禁止无关读取 .env、SSH 密钥等敏感文件
④ 可疑指令——未发现,反而内置提示注入防御指南（把用户代码/Markdown/issue 内容一律视为不可信数据）
⑤ 作者/组织信誉——作者为具名后端工程师,个人网站与既往任职机构可查证,项目获 Neon 赞助
⑥ License——Apache-2.0,仓库根目录确认,清晰明确
⑦ 最近维护——发现前约一周仍有实质提交,同时有 Dependabot 持续依赖更新
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与 better-drizzle 的差异 |
|---|---|---|
| 第三方“Drizzle ORM 参考知识”类技能（多个市场页面可见，如 claudskills.com、awesomeskill.ai 上收录的 Drizzle ORM 技能） | 教 Agent 掌握 Drizzle 原生 API 的语法与模式（schema 定义、关系查询、迁移流程等），本质是知识库/文档压缩包 | better-drizzle 教的是一个真实存在的包裹库的简化 API,目标是减少 Drizzle 原生写法的样板代码,而非单纯复述 Drizzle 文档；技能包由库作者本人维护,与库版本同步更新,避免第三方文档技能常见的“API 已过时”问题 |
Cloudflare D1 专用 Drizzle 技能（如市场上可见的 drizzle-orm-d1 类技能） |
聚焦单一部署目标（Cloudflare D1）的 Drizzle 用法 | better-drizzle 面向 PostgreSQL/MySQL/SQLite 等多种 Drizzle 支持的方言,不绑定特定部署平台 |
8. 用户评价
该技能目前在第三方平台尚无独立具名用户评价。可查证的最直接第三方参与证据来自项目自身 GitHub：外部开发者 pablofdezr 提交并被合并了一个真实 bug 修复（关系过滤器 some/none/every 生成的 EXISTS 子查询缺少关联条件、导致返回错误行），另一位用户 Darren120 提交过功能请求。
9. 其他补充
项目同时提供插件生态（如 @better-drizzle/timestamps、@better-drizzle/soft-delete），均随主库同步发版（当前 0.1.1）。
10. 安装使用方式
- 在项目中安装库本体：
npm install better-drizzle drizzle-orm - 获取技能包：将仓库
skills/better-drizzle/目录（含SKILL.md与references/）复制到所用 Agent 的技能目录（如 Claude Code 的~/.claude/skills/），或在项目内直接引用仓库根目录的CLAUDE.md/AGENTS.md适配文件 - 安装后无需重启，Agent 在处理涉及 better-drizzle 的任务时会按
SKILL.md的任务路由规则自动查阅对应的references/文件
11. 注意事项
- 该技能是 better-drizzle 库的配套技能，仅在项目实际使用（或计划采用）该库时才有意义，不适用于纯 Drizzle 原生项目
- 项目发布仅一个月左右，版本号仍在 0.x 阶段，API 可能继续演进
- 技能包未见针对 Codex / OpenClaw / Hermes Agent 的专门适配说明，跨生态使用前建议自行验证触发与加载行为