sqlite-skill

name	sqlite-skill
description	用于平台中立的 SQLite 数据层设计与审查，包括 schema、SQL、migration、事务、索引、PRAGMA/WAL/FTS/JSON、同步持久化、备份恢复、limits 和安全。当用户明确提到 SQLite/sqlite，或需要判断本地关系型数据库是否适合 SQLite 时使用；不要用于未指定 SQLite 的 IndexedDB、localStorage、key-value storage 或服务端数据库任务。

SQLite Skill

意图

帮助 Agent 独立处理 SQLite 相关的数据层问题：数据库设计、SQL 编写、迁移、事务、索引、同步、性能、安全和可靠性。

本 skill 只负责 SQLite 与离线数据工程本身。如果业务项目还涉及具体框架、端平台、插件封装或 UI 工程，由用户主动指定或另行调用对应能力；本 skill 不主动耦合其他 skill。

如果用户明确指定要做 uni-app / UTS 的三端 SQLite 插件，可另行使用 sqlite-uniapp-uts 处理插件工程与平台 Adapter；本 skill 只提供 SQLite 数据层规则。

触发场景

• SQLite 建表、查询、索引、事务、迁移、PRAGMA、EXPLAIN QUERY PLAN。
• 本地数据库、离线缓存、offline-first、同步队列、软删除、冲突处理。
• SQLite 性能、安全、SQL 注入、敏感数据、数据库文件、备份恢复、多账号隔离。
• 需要设计 DAO、Repository、LocalDatabase adapter、QueryBuilder、sync engine、migration runner、health check。
• 需要判断 SQLite 与 IndexedDB、WebSQL、localStorage、文件存储或服务端数据库的边界。

非目标

• 不负责具体业务框架的页面、组件、路由、构建、插件封装或平台 API 细节。
• 不默认任何运行端支持 SQLite；只给 SQLite 数据层方案与能力核查清单。
• 不把浏览器、移动端、桌面端、后端脚本、嵌入式设备混为同一运行环境。
• 不写完整 SQLite 教程；细节按需读取 references。

维护与复用约定

本 skill 遵循仓库 README 的通用规范：中文优先、自包含、渐进式披露、验证再交付。修改或分发本 skill 时读取 references/repository-usage.md；只复制/打包整个 skills/sqlite-skill/ 目录，不只复制 SKILL.md。

核心原则

1. 先确认运行环境：SQLite CLI、Node、移动端 wrapper、桌面端、浏览器 WASM、后端脚本或其他宿主。
2. 先确认 SQLite 版本、编译选项、wrapper 暴露能力、文件系统限制和测试环境。
3. 先确认数据规模、读写频率、同步方式、账号/租户隔离、隐私等级和冲突策略。
4. SQL 示例必须使用 SQLite 兼容语法；不确定宿主 API 时只给通用 SQL 与架构，并说明以具体 wrapper 文档为准。
5. 外部输入必须参数化；动态表名、列名、排序字段必须白名单化。
6. 离线功能必须同时考虑初始化、迁移、事务、同步队列、软删除、重试、冲突和状态恢复。
7. SQLite 不是加密存储；敏感数据默认不明文落库。
8. PRAGMA foreign_keys = ON 需每个连接启用并查询确认；PRAGMA 拼错可能被静默忽略。
9. 不把 INSERT OR REPLACE / REPLACE INTO 当安全 upsert；优先考虑 ON CONFLICT DO UPDATE 并确认 SQLite 版本。
10. 不滥用 AUTOINCREMENT；先理解 INTEGER PRIMARY KEY、rowid、NULL、布尔值和类型亲和性。
11. WAL、FTS5、JSON1/JSONB、SQLCipher、STRICT table、RETURNING、backup API 不承诺在所有运行环境可用，必须检测版本/编译选项/wrapper 能力。
12. 对跨宿主项目，只定义平台中立 Adapter 契约；具体平台 API、插件封装和条件编译由用户另行指定。

工作流

1. 运行环境与能力核查

读取 references/overview.md、references/runtime-boundaries.md、references/pragmas-and-diagnostics.md。

1. 确认宿主环境、SQLite 版本、扩展支持和 wrapper API。
2. 区分 SQLite、IndexedDB、WebSQL、key-value storage、文件存储、服务端 RDBMS。
3. 确认数据库文件路径、沙盒/权限、备份、升级、低磁盘空间和崩溃恢复限制。
4. 执行或规划能力探测：SQLite 版本、编译选项、关键 PRAGMA、扩展模块和 wrapper 限制。

2. Schema / 建表设计

读取 references/schema-design.md、references/data-types-and-affinity.md、references/constraints-and-indexes.md。

1. 明确实体、字段、主键、唯一约束、外键、时间格式和生命周期。
2. 离线同步场景区分本地 id、服务端 id、客户端幂等 key。
3. 设计 sync_status、deleted_at、version、created_at、updated_at 等字段。
4. 为高频 WHERE、JOIN、ORDER BY 字段添加索引。
5. 输出 CREATE TABLE、CREATE INDEX 和迁移说明。

3. Adapter / DAO / SQL 编写与优化

读取 references/adapters-and-api-contracts.md、references/querybuilder-and-dao.md、references/sql-basics.md、references/performance.md。涉及全文搜索、JSON 或批处理时再读取 references/fts5-and-search.md、references/json-and-generated-columns.md、references/limits-and-batching.md。

1. 判断 SQL 类型：DDL、DML、查询、事务或诊断。
2. 需要跨宿主时，先给最小 LocalDatabase 契约，再实现 DAO / Repository。
3. 使用参数绑定占位符，不拼接用户输入。
4. 动态排序、列名和表名必须白名单化；QueryBuilder 只生成受控 SQL 片段。
5. 对复杂查询说明索引、分页和查询计划。
6. 批量写入必须放在事务中。
7. 警惕 LIKE '%xxx%'、大偏移 OFFSET、未分页全表读。

4. 数据迁移

读取 references/migrations.md。

1. 用 PRAGMA user_version 或 schema_migrations 管理版本。
2. 从旧版本顺序升级到最新版，迁移放事务中。
3. 复杂表结构变更使用建新表、复制、删旧表、重命名、重建索引模式。
4. 覆盖新装建库、旧库升级、重复启动、迁移失败恢复。

5. 离线同步

读取 references/sync-patterns.md、references/common-recipes.md。

1. 明确同步方向、同步粒度、幂等 key、软删除和冲突策略。
2. 本地业务写入和 outbox/sync queue 状态更新放在同一事务。
3. 网络恢复后先处理待上传，再拉取远端增量，避免覆盖本地未同步数据。
4. 设计失败重试、重复提交、部分成功、崩溃恢复和用户可见状态。

6. 安全与可靠性

读取 references/security.md、references/transactions-and-concurrency.md、references/backup-and-restore.md、references/pitfalls.md。

1. 参数化查询、防注入、动态标识符白名单、日志脱敏。
2. 多用户/多租户数据隔离，退出登录和切换账号时清理敏感缓存。
3. 需要加密时调研 SQLCipher、系统安全存储或宿主平台安全能力。
4. 关注 SQLite 单写多读、WAL、锁等待、崩溃恢复和备份一致性。

References

场景	读取
SQLite 总览	references/overview.md
运行环境边界	references/runtime-boundaries.md
Adapter 与 API 契约	references/adapters-and-api-contracts.md
连接生命周期	references/connection-lifecycle.md
Statement 与参数绑定	references/statement-and-binding.md
结果集映射	references/result-set-mapping.md
统一错误模型	references/error-model.md
DAO / QueryBuilder	references/querybuilder-and-dao.md
PRAGMA 与诊断	references/pragmas-and-diagnostics.md
SQL 基础	references/sql-basics.md
表结构设计	references/schema-design.md
数据类型	references/data-types-and-affinity.md
约束与索引	references/constraints-and-indexes.md
事务与并发	references/transactions-and-concurrency.md
备份与恢复	references/backup-and-restore.md
数据库迁移	references/migrations.md
性能优化	references/performance.md
FTS5 与搜索	references/fts5-and-search.md
JSON 与生成列	references/json-and-generated-columns.md
Limits 与批处理	references/limits-and-batching.md
同步模式与冲突	references/sync-patterns.md
安全	references/security.md
常用模板	references/common-recipes.md
避坑	references/pitfalls.md
官方文档索引	references/official-docs-map.md
能力检测	references/capability-detection.md
C API 与 wrapper 映射	references/c-api-and-wrappers.md
sqlite3 CLI	references/cli.md
错误码与诊断	references/errors-and-diagnostics.md
功能版本矩阵	references/feature-matrix.md
测试检查清单	references/testing.md
仓库复用与维护	references/repository-usage.md

交付检查清单

• 已确认宿主环境、SQLite wrapper/API、版本、编译选项和扩展支持。
• 跨宿主项目已隔离平台中立 Adapter 契约与具体平台实现。
• 已区分 SQLite、IndexedDB、WebSQL、key-value storage、文件存储、服务端数据库。
• 已覆盖新装建库、旧库升级、重复启动、迁移失败恢复。
• 已验证事务回滚、同步重复提交、软删除、冲突和网络失败重试。
• 已评估数据库文件路径、权限、备份、卸载/清理、升级、低磁盘空间。
• 已确认 SQL 参数绑定、动态标识符白名单、DAO 事务边界和日志脱敏。
• 已规划健康检查：integrity_check / quick_check、数据库大小、关键 PRAGMA、慢查询和最近同步错误。
• 已评估备份恢复、WAL/checkpoint、limits/批处理、FTS5/JSON 等能力是否被宿主支持。
• 已规划目标宿主的真实环境验证，不用模拟环境替代关键端侧验证。