@mison/ag-kit-cn 2.0.1

package/.agent/skills/database-design/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: database-design
+description: 数据库设计原则与决策（Database design）。包含模式设计、索引策略、ORM 选择与 Serverless 数据库。
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# 数据库设计
+
+> **学习如何思考（THINK）**，而非机械复制 SQL 模式。
+
+## 🎯 选择性阅读规则
+
+**仅阅读与请求相关的文档！** 查阅内容地图，找到所需信息。
+
+| 文件 | 描述 | 阅读时机 |
+| ---- | ---- | -------- |
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | 选择数据库时 |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | 选择 ORM 时 |
+| `schema-design.md` | 范式化、主键、关系设计 | 设计模式时 |
+| `indexing.md` | 索引类型、复合索引 | 性能调优时 |
+| `optimization.md` | N+1 问题、EXPLAIN ANALYZE | 查询优化时 |
+| `migrations.md` | 安全迁移、Serverless 数据库 | 模式变更时 |
+
+---
+
+## ⚠️ 核心原则
+
+- 需求不明确时，主动询问数据库偏好。
+- 根据实际上下文选择数据库与 ORM。
+- 不要任何场景都默认使用 PostgreSQL。
+
+---
+
+## 决策检查清单
+
+在设计模式（Schema）之前：
+
+- [ ] **是否已询问数据库偏好？**
+- [ ] **是否为当前上下文选择了合适的数据库？**
+- [ ] **是否考虑了部署环境？**
+- [ ] **是否规划了索引策略？**
+- [ ] **是否定义了关系类型？**
+
+---
+
+## 反模式
+
+❌ 为简单应用默认使用 PostgreSQL（SQLite 可能已足够）  
+❌ 忽略索引设计  
+❌ 在生产环境中使用 `SELECT *`  
+❌ 在结构化数据更优时强行存储 JSON  
+❌ 忽略 N+1 查询问题
+
+---

package/.agent/skills/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# 数据库选择（2025）
+
+> 根据上下文选择数据库，不要只用默认选项。
+
+## 决策树
+
+```
+您的需求是什么？
+│
+├── 需要完整的关系型功能
+│   ├── 自托管（Self-hosted） → PostgreSQL
+│   └── 无服务器（Serverless） → Neon, Supabase
+│
+├── 边缘部署（edge）/ 超低延迟
+│   └── Turso（边缘级 SQLite）
+│
+├── AI / 向量搜索（vector search）
+│   └── PostgreSQL + pgvector
+│
+├── 简单 / 嵌入式 / 本地存储
+│   └── SQLite
+│
+└── 全球分布式挂载
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## 各数据库对比
+
+| 数据库 | 最佳适用 | 权衡 |
+| ------ | -------- | ------------------ |
+| **PostgreSQL** | 全功能，复杂查询 | 需要托管 |
+| **Neon** | Serverless PG（无服务器 PostgreSQL），分支功能 | PG 自身的复杂度 |
+| **Turso** | 边缘环境，低延迟 | SQLite 的局限性 |
+| **SQLite** | 简单、嵌入式、本地 | 单个写入者（single-writer）限制 |
+| **PlanetScale** | MySQL，全球量级扩展 | 无外键约束支持 |
+
+## 需要问的问题
+
+1. 部署环境是什么？（Serverless（无服务器）、容器、虚拟机等）
+2. 查询有多复杂？（是否涉及深度嵌套、地理空间等）
+3. Edge（边缘）/Serverless（无服务器）特性是否重要？
+4. 是否需要向量搜索功能？
+5. 是否需要全球分布支持？

package/.agent/skills/database-design/indexing.md

@@ -0,0 +1,39 @@
+# 索引原则
+
+> 选对时机和方式，高效创建索引。
+
+## 何时创建索引
+
+```
+应该建立索引的情况：
+├── WHERE 子句中使用的列
+├── JOIN 连接条件中使用的列
+├── ORDER BY 中使用的列
+├── 外键（foreign key）列
+└── 唯一性约束（unique constraints）列
+
+避免过度索引的情况：
+├── 写操作频繁的表（会降低插入速度）
+├── 区分度低（low-cardinality）的列
+├── 很少被查询的列
+```
+
+## 索引类型选择
+
+| 类型 | 用途 |
+| ---- | ---- |
+| **B-tree** | 通用目的，等值和范围查询 |
+| **Hash** | 仅等值查询，速度更快 |
+| **GIN** | JSONB、数组、全文搜索 |
+| **GiST** | 几何、物理范围类型 |
+| **HNSW/IVFFlat** | 向量相似度（pgvector） |
+
+## 复合索引原则
+
+```
+复合索引的列顺序至关重要：
+├── 等值过滤列在前（equality）
+├── 范围过滤列在后（range）
+├── 区分度高（指重复率低）的列在前
+└── 必须匹配查询模式中的列序
+```

package/.agent/skills/database-design/migrations.md

@@ -0,0 +1,50 @@
+# 迁移原则
+
+> 面向零停机变更的安全迁移策略。
+
+## 安全迁移策略
+
+```
+零停机变更建议：
+│
+├── 新增列（adding column）
+│   └── 先设为 nullable（可为空） → 回填数据 → 再加 NOT NULL
+│
+├── 删除列（removing column）
+│   └── 先停止使用 → 部署过渡版本 → 再删除列
+│
+├── 新增索引（adding index）
+│   └── `CREATE INDEX CONCURRENTLY`（非阻塞）
+│
+└── 重命名列（renaming column）
+    └── 新增新列 → 迁移数据 → 部署 → 删除旧列
+```
+
+## 迁移哲学
+
+- 不要一步到位做破坏性变更
+- 先在数据副本上验证迁移
+- 预先准备回滚方案
+- 在可行场景下使用事务包裹
+
+## Serverless 数据库
+
+### Neon（Serverless PostgreSQL）
+
+| 特性 | 价值 |
+| -------------- | -------------- |
+| Scale to zero（零实例） | 节省成本 |
+| Instant branching（即时分支） | 开发/预览环境方便 |
+| Full PostgreSQL（完整 PostgreSQL） | 兼容生态成熟 |
+| Autoscaling（自动伸缩） | 自动应对流量波动 |
+
+### Turso（Edge SQLite）
+
+| 特性 | 价值 |
+| -------------- | -------------- |
+| Edge locations（边缘节点） | 超低延迟 |
+| SQLite compatible（兼容 SQLite） | 使用简单 |
+| Generous free tier（较大免费额度） | 成本友好 |
+| Global distribution（全球分布） | 全球访问性能更好 |
+
+<!-- /preview -->

package/.agent/skills/database-design/optimization.md

@@ -0,0 +1,36 @@
+# 查询优化
+
+> 解决 N+1 问题、使用 EXPLAIN ANALYZE（执行计划分析）、以及优化优先级。
+
+## N+1 问题
+
+```
+什么是 N+1？
+├── 用 1 条查询获取父记录（parent records）
+├── 用 N 条查询分别获取每条父记录的关联记录
+└── 结果：极其缓慢！
+
+解决方案：
+├── JOIN → 一个查询获取所有数据
+├── 预加载（eager loading） → 让 ORM 处理 JOIN
+├── DataLoader → 批量处理并缓存（多用于 GraphQL）
+└── 子查询（subquery） → 在一个查询中批量获取关联数据
+```
+
+## 查询分析思维
+
+```
+在开始优化前：
+├── 对查询执行 EXPLAIN ANALYZE
+├── 寻找 Seq Scan（全表扫描）
+├── 检查 实际行数（actual） vs 预估行数（estimated）
+└── 识别缺失的索引
+```
+
+## 优化优先级
+
+1. **添加缺失的索引**（这是最常见的问题）
+2. **仅选择需要的列**（严禁使用 `SELECT *`）
+3. **使用正确的 JOIN**（尽可能避免不必要的子查询）
+4. **尽早限制结果集**（在数据库层面执行分页 `LIMIT`）
+5. **引入缓存**（在合适的应用场景下）

package/.agent/skills/database-design/orm-selection.md

@@ -0,0 +1,30 @@
+# ORM 选择（2025）
+
+> 根据部署需求和开发体验（DX）选择 ORM。
+
+## 决策树
+
+```
+开发背景是什么？
+│
+├── 边缘部署（edge）/ 关注包体积
+│   └── Drizzle（体积最小，贴近 SQL 语法）
+│
+├── 最佳开发体验（DX）/ schema（模式）优先
+│   └── Prisma（自带迁移工具和可视化 Studio（控制台））
+│
+├── 追求最大控制权
+│   └── 原始 SQL 配合查询构造器（query builder）
+│
+└── Python 生态
+    └── SQLAlchemy 2.0（支持异步）
+```
+
+## 各 ORM 对比
+
+| ORM | 最佳适用 | 权衡 |
+| --- | -------- | ------------------ |
+| **Drizzle** | 边缘端环境，TypeScript | 相对较新，生态示例较少 |
+| **Prisma** | 开发体验，Schema 管理 | 运行较重，边缘端支持不佳 |
+| **Kysely** | 类型安全的 SQL 构造器 | 需要手动管理迁移 |
+| **Raw SQL（原始 SQL）** | 复杂查询，极致控制权 | 需要手动维护类型安全 |

package/.agent/skills/database-design/schema-design.md

@@ -0,0 +1,56 @@
+# Schema（模式）设计原则
+
+> 范式化、主键选择、时间戳策略以及关系建模。
+
+## 范式化决策
+
+```
+何时进行范式化（normalization，拆分表）：
+├── 数据在多行之间重复出现
+├── 更新操作需要修改多个地方
+├── 实体间关系清晰明确
+├── 查询模式能从拆分中获益（如减少冗余扫描）
+
+何时进行反范式化（denormalization，嵌入/重复数据）：
+├── 读性能至关重要（减少 JOIN）
+├── 数据极少发生变更
+├── 相关数据总是被一起获取
+├── 需要极简的查询语句
+```
+
+## 主键选择
+
+| 类型 | 使用场景 |
+| ---- | -------- |
+| **UUID** | 分布式系统，安全性考虑（不泄露数据量） |
+| **ULID** | 具备 UUID 性质 + 可按时间排序 |
+| **自增（auto-increment）** | 简单应用，单一数据库环境 |
+| **自然主键（natural key）** | 极少使用（具有业务含义的列） |
+
+## 时间戳策略
+
+```
+建议为每一张表添加：
+├── created_at → 创建时间
+├── updated_at → 最后修改时间
+└── deleted_at → 软删除时间（如果需要）
+
+务必使用 TIMESTAMPTZ（带时区）而非原生 TIMESTAMP
+```
+
+## 关系类型
+
+| 类型 | 场景 | 实现方式 |
+| ---- | ---- | -------- |
+| **一对一（One-to-One）** | 扩展数据 | 独立表并通过外键关联 |
+| **一对多（One-to-Many）** | 父子、归属关系 | 在子表上建立外键 |
+| **多对多（Many-to-Many）** | 双方均有复数关联 | 建立关联表（Junction table） |
+
+## 外键删除策略
+
+```
+├── CASCADE → 随父记录一起级联删除子记录
+├── SET NULL → 父记录删除后，子记录关联字段设为 NULL（变孤儿）
+├── RESTRICT → 如果存在子记录，则阻止删除父记录
+└── SET DEFAULT → 父记录删除后，子记录设为默认值
+```

package/.agent/skills/database-design/scripts/schema_validator.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Schema Validator - Database schema validation
+Validates Prisma schemas and checks for common issues.
+
+Usage:
+    python schema_validator.py <project_path>
+
+Checks:
+    - Prisma schema syntax
+    - Missing relations
+    - Index recommendations
+    - Naming conventions
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def find_schema_files(project_path: Path) -> list:
+    """Find database schema files."""
+    schemas = []
+    
+    # Prisma schema
+    prisma_files = list(project_path.glob('**/prisma/schema.prisma'))
+    schemas.extend([('prisma', f) for f in prisma_files])
+    
+    # Drizzle schema files
+    drizzle_files = list(project_path.glob('**/drizzle/*.ts'))
+    drizzle_files.extend(project_path.glob('**/schema/*.ts'))
+    for f in drizzle_files:
+        if 'schema' in f.name.lower() or 'table' in f.name.lower():
+            schemas.append(('drizzle', f))
+    
+    return schemas[:10]  # Limit
+
+
+def validate_prisma_schema(file_path: Path) -> list:
+    """Validate Prisma schema file."""
+    issues = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8', errors='ignore')
+        
+        # Find all models
+        models = re.findall(r'model\s+(\w+)\s*{([^}]+)}', content, re.DOTALL)
+        
+        for model_name, model_body in models:
+            # Check naming convention (PascalCase)
+            if not model_name[0].isupper():
+                issues.append(f"Model '{model_name}' should be PascalCase")
+            
+            # Check for id field
+            if '@id' not in model_body and 'id' not in model_body.lower():
+                issues.append(f"Model '{model_name}' might be missing @id field")
+            
+            # Check for createdAt/updatedAt
+            if 'createdAt' not in model_body and 'created_at' not in model_body:
+                issues.append(f"Model '{model_name}' missing createdAt field (recommended)")
+            
+            # Check for @relation without fields
+            relations = re.findall(r'@relation\([^)]*\)', model_body)
+            for rel in relations:
+                if 'fields:' not in rel and 'references:' not in rel:
+                    pass  # Implicit relation, ok
+            
+            # Check for @@index suggestions
+            foreign_keys = re.findall(r'(\w+Id)\s+\w+', model_body)
+            for fk in foreign_keys:
+                if f'@@index([{fk}])' not in content and f'@@index(["{fk}"])' not in content:
+                    issues.append(f"Consider adding @@index([{fk}]) for better query performance in {model_name}")
+        
+        # Check for enum definitions
+        enums = re.findall(r'enum\s+(\w+)\s*{', content)
+        for enum_name in enums:
+            if not enum_name[0].isupper():
+                issues.append(f"Enum '{enum_name}' should be PascalCase")
+        
+    except Exception as e:
+        issues.append(f"Error reading schema: {str(e)[:50]}")
+    
+    return issues
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[SCHEMA VALIDATOR] Database Schema Validation")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    # Find schema files
+    schemas = find_schema_files(project_path)
+    print(f"Found {len(schemas)} schema files")
+    
+    if not schemas:
+        output = {
+            "script": "schema_validator",
+            "project": str(project_path),
+            "schemas_checked": 0,
+            "issues_found": 0,
+            "passed": True,
+            "message": "No schema files found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Validate each schema
+    all_issues = []
+    
+    for schema_type, file_path in schemas:
+        print(f"\nValidating: {file_path.name} ({schema_type})")
+        
+        if schema_type == 'prisma':
+            issues = validate_prisma_schema(file_path)
+        else:
+            issues = []  # Drizzle validation could be added
+        
+        if issues:
+            all_issues.append({
+                "file": str(file_path.name),
+                "type": schema_type,
+                "issues": issues
+            })
+    
+    # Summary
+    print("\n" + "="*60)
+    print("SCHEMA ISSUES")
+    print("="*60)
+    
+    if all_issues:
+        for item in all_issues:
+            print(f"\n{item['file']} ({item['type']}):")
+            for issue in item["issues"][:5]:  # Limit per file
+                print(f"  - {issue}")
+            if len(item["issues"]) > 5:
+                print(f"  ... and {len(item['issues']) - 5} more issues")
+    else:
+        print("No schema issues found!")
+    
+    total_issues = sum(len(item["issues"]) for item in all_issues)
+    # Schema issues are warnings, not failures
+    passed = True
+    
+    output = {
+        "script": "schema_validator",
+        "project": str(project_path),
+        "schemas_checked": len(schemas),
+        "issues_found": total_issues,
+        "passed": passed,
+        "issues": all_issues
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()