create-vibe-workflow 0.1.0 → 0.2.0

package/templates/skills/database/postgres-patterns/SKILL.md.ejs

@@ -0,0 +1,235 @@
+# PostgreSQL Patterns — PostgreSQL 数据库模式
+
+> 使用此 skill 时：设计表结构、编写查询、优化数据库性能时。
+
+## 索引策略
+
+### 索引类型选择
+
+```text
+B-Tree（默认）：
+  适用：等值查询、范围查询、排序
+  不适用：全文搜索、数组包含
+
+Hash：
+  适用：等值查询（性能略高于 B-Tree）
+  不适用：范围查询、排序
+  注意：不记录大小，重建时需 REINDEX
+
+GiST：
+  适用：全文搜索、地理空间、范围重叠
+  示例：tsvector、geometry、timerange
+
+GIN：
+  适用：包含查询（数组、JSONB、全文搜索）
+  示例：JSONB 的 @> 操作符、数组的 @> 操作符
+
+BRIN：
+  适用：与物理存储顺序相关的大表（如时间序列）
+  优点：索引体积极小
+  注意：数据插入顺序须与索引列顺序接近
+```
+
+### 索引设计检查清单
+
+```text
+是否真正需要？
+  [ ] 这个查询是频繁执行的吗？
+  [ ] 表大到不用索引会慢吗？（<1000 行不需要）
+  [ ] 这个查询会随着数据增长变慢吗？
+
+索引列选择：
+  [ ] WHERE 子句中的列优先
+  [ ] JOIN 的关联列必须索引
+  [ ] ORDER BY 的列考虑包含在索引中
+  [ ] 高选择性的列优先（唯一值多）
+
+避免过度索引：
+  [ ] 不要为低频查询建索引
+  [ ] 不要重复索引（复合索引的前缀列不需要单独索引）
+  [ ] 写密集的表索引尽量少（每个索引增加写入开销）
+  [ ] 定期用 pg_stat_user_indexes 检查未使用索引
+
+复合索引：
+  [ ] = 条件的列放前面
+  [ ] 范围条件的列放后面
+  [ ] 查询条件中有多个 = 列时，任意顺序均可
+  [ ] 考虑 INCLUDE 列（覆盖索引）
+```
+
+## 数据类型选择
+
+```text
+【数值型】
+  整数：
+    smallint (2B, ±32K) → 枚举/状态码
+    integer   (4B, ±2B)  → 默认选择
+    bigint    (8B)       → 自增 ID 超 2B 时
+
+  小数：
+    numeric(p,s)  → 精确计算（金额）
+    double precision → 科学计算（允许小误差）
+
+【文本型】
+  text          → 没有长度限制，性能与 varchar 相同
+  varchar(n)    → 有长度约束时（如邮箱限制 254 字符）
+  citext        → 不区分大小写的文本（扩展）
+
+  选择规则：默认用 text，需要约束长度时用 varchar(n)
+
+【时间型】
+  timestamptz   → 首选（带时区，存储为 UTC）
+  timestamp     → 不需要时区时
+  date          → 只需要日期时
+  time          → 只需要时间时
+  interval      → 时间间隔
+
+【JSON vs JSONB】
+  json          → 只存不查（保留原格式、键顺序）
+  jsonb         → 需要查询/索引（二进制格式，去重键）
+
+  总结：90% 场景用 jsonb，只有日志归档等只存不查场景用 json
+
+【数组】
+  适用：标签、分类等有限集合
+  注意：数组查询不能利用普通 B-Tree 索引（需 GIN）
+```
+
+## 查询优化
+
+### N+1 查询检测
+
+```text
+症状：一次查询后循环内执行 N 次查询
+
+识别：
+  - 日志中出现大量相似查询
+  - 翻页/列表接口慢
+
+// ❌ N+1
+for each user {
+    query("SELECT * FROM orders WHERE user_id = ?", user.id)
+}
+
+// ✅ 批量查询
+userIds = users.map(u => u.id)
+orders = query("SELECT * FROM orders WHERE user_id = ANY(?)", [userIds])
+// 在应用层关联
+```
+
+### JOIN vs 子查询
+
+```text
+【优先 JOIN】
+  适用：
+    - 需要返回父表和子表的列
+    - 关联表行数不多
+
+  注意：
+    - JOIN 的表都应有索引
+    - 避免大表的 CROSS JOIN
+
+【子查询（EXISTS）】
+  适用：
+    - 只需要检查是否存在
+    - 关联条件是聚合结果
+
+  注意：
+    - EXISTS 找到第一条即停止，比 IN 快
+    - NOT EXISTS 比 NOT IN 安全（NOT IN 遇到 NULL 行为异常）
+
+总结：
+  90% 的关联查询用 JOIN
+  存在性检查用 EXISTS
+  聚合子查询用 CTE 或 LATERAL JOIN
+```
+
+### 分页策略
+
+```text
+【OFFSET/LIMIT】— 简单但大偏移量慢
+  适用：小数据集、前几页
+  问题：OFFSET 越大越慢（需要扫描并丢弃前面的行）
+
+  优化：用复合索引 + 覆盖索引减轻
+
+【游标分页（Keyset Pagination）】— 大数据集推荐
+  适用：无限滚动、实时数据
+  原理：用 WHERE 条件代替 OFFSET
+
+  SELECT * FROM users
+  WHERE createdAt < :lastCreatedAt OR (createdAt = :lastCreatedAt AND id < :lastId)
+  ORDER BY createdAt DESC, id DESC
+  LIMIT 20
+
+  优点：无论翻到第几页，性能恒定
+  缺点：不能直接跳转到特定页
+```
+
+### EXPLAIN 分析
+
+```text
+EXPLAIN ANALYZE {query};
+
+关键指标：
+  - seq scan → 考虑加索引
+  - rows 估算偏差大 → 更新统计信息（ANALYZE）
+  - actual time 大 → 确认瓶颈
+
+常见问题：
+  - 类型不匹配导致隐式转换 → 索引失效
+  - OR 条件 → 考虑 UNION ALL
+  - IN 子句大量值 → 考虑临时表或 ANY
+```
+
+## 约束与数据完整性
+
+```text
+NOT NULL — 默认用，除非真有理由允许 NULL
+UNIQUE — 保证业务唯一性（用户名、邮箱）
+CHECK — 业务规则（age > 0, status IN ('a','b','c')）
+FOREIGN KEY — 引用完整性（注意：会加锁）
+EXCLUDE — 排他约束（时间范围不重叠）
+
+注意：
+  - 外键约束创建和维护有开销
+  - 批量导入时可先禁用约束，导入后重建验证
+  - CHECK 约束比应用层验证更可靠
+```
+
+## Row-Level Security（RLS）
+
+```text
+适用：多租户隔离（每个用户只能看到自己的数据）
+
+实现：
+  1. 启用行级安全：ALTER TABLE {table} ENABLE ROW LEVEL SECURITY
+  2. 创建策略：允许/禁止特定操作
+
+示例：多租户隔离
+  CREATE POLICY tenant_isolation ON orders
+    USING (tenant_id = current_setting('app.tenant_id')::int)
+
+规则：
+  - RLS 应用层不可绕过
+  - 性能影响很小（查询只加一次过滤）
+  - 管理员应有一个绕过 RLS 的角色
+```
+
+## 连接池
+
+```text
+为什么需要连接池？
+  - 建立连接开销大（TCP + TLS + 认证）
+  - 数据库并发连接数有限
+
+配置要点：
+  - 池大小 = 2 × CPU 核心数 + 磁盘数（经验公式）
+  - 不是越大越好（过多连接→上下文切换→性能下降）
+  - 设置超时：连接超时、查询超时、闲置超时
+
+连接耗尽处理：
+  - 优先保证关键路径的连接
+  - 非关键操作降级（缓存结果 / 返回降级响应）
+  - 监控连接池使用率
+```

package/templates/skills/devops/deployment-patterns/SKILL.md.ejs

@@ -0,0 +1,228 @@
+# Deployment Patterns — 部署模式
+
+> 使用此 skill 时：设计部署流水线、选择部署策略、配置健康检查、管理回滚。
+
+## CI/CD 流水线
+
+### 标准流水线结构
+
+```text
+┌─ Code Push ─→ CI（构建+测试） ─→ CD（部署） ─→ 验证 ─→ 完成
+
+【CI 阶段（提交触发）】
+  1. Lint + 类型检查
+  2. 单元测试 + 集成测试
+  3. 构建（编译、打包）
+  4. 构建镜像（Docker build）
+  5. 镜像扫描（安全漏洞）
+  6. 推送镜像到仓库
+
+【CD 阶段（手动/自动触发）】
+  1. 从镜像仓库拉取指定版本
+  2. 部署到目标环境
+  3. 运行健康检查
+  4. 运行 Smoke Test
+  5. 切换流量（如有负载均衡）
+  6. 通知团队
+```
+
+### 环境管理
+
+```text
+开发（Development）：
+  - 开发者自行部署
+  - 自动从 feature 分支部署
+  - 不稳定，用于快速迭代
+
+测试（Staging / QA）：
+  - 合并到 main 后自动部署
+  - 运行全量测试套件
+  - 模拟生产环境配置
+
+生产（Production）：
+  - 从 Staging 提升（promotion）
+  - 需要审批流程
+  - 蓝绿/灰度发布
+
+环境差异性管理：
+  build once, deploy many
+  同一构建产物部署到所有环境
+  通过环境变量区分配置
+```
+
+## 部署策略
+
+### 策略对比
+
+| 策略 | 零停机 | 回滚速度 | 成本 | 适用场景 |
+|------|--------|---------|------|---------|
+| Rolling | 是 | 慢 | 低 | 标准 Web 服务 |
+| Blue-Green | 是 | 极快 | 高（双倍资源） | 关键服务 |
+| Canary | 是 | 中 | 中 | 高风险变更 |
+| Recreate | 否 | N/A | 低 | 内部工具/定时任务 |
+
+### Rolling Update（滚动更新）
+
+```text
+过程：
+  1. 启动新版本实例（逐台替换）
+  2. 旧实例下线前完成请求处理
+  3. 新实例通过健康检查后开始接收流量
+
+配置要点：
+  maxSurge: 1           # 最多超出目标实例数 1 个
+  maxUnavailable: 0     # 始终保持 100% 可用
+  minReadySeconds: 30   # 新实例就绪后等待 30 秒再继续
+
+适用场景：
+  - 无状态服务
+  - 多实例（≥3）
+  - 可以接受慢回滚
+```
+
+### Blue-Green Deployment（蓝绿部署）
+
+```text
+过程：
+  1. Blue（当前生产环境）
+  2. Green（新版本环境，独立部署）
+  3. Green 验证通过后，切换负载均衡指向 Green
+  4. Blue 保留以备回滚
+
+回滚：
+  - 负载均衡切回 Blue（秒级回滚）
+  - Blue 实例保持运行直到确认稳定
+
+资源要求：
+  - 双倍基础设施
+  - 数据库需前后兼容（两个版本同时读写）
+
+适用场景：
+  - 关键业务服务
+  - 需要即时回滚
+  - 可以承担双倍资源成本
+```
+
+### Canary Release（金丝雀发布）
+
+```text
+过程：
+  1. 部署新版本到少量实例（如 5% 流量）
+  2. 监控错误率、延迟、业务指标
+  3. 稳定后逐步增加流量（10% → 25% → 50% → 100%）
+  4. 异常时自动回滚
+
+流量路由方式：
+  - 负载均衡权重
+  - 基于用户群体（内部用户先使用）
+  - 基于地域
+
+适用场景：
+  - 高风险大版本更新
+  - 需要真实流量验证
+  - 有完善的监控体系
+```
+
+## 健康检查端点
+
+### 三级检查体系
+
+```text
+【就绪检查（Readiness）】
+  端点：GET /health/ready
+  目的：服务是否准备好接收流量
+  检查：依赖服务可用（DB、缓存、队列连接正常）
+  失败：从负载均衡移除，不停止容器
+
+【存活检查（Liveness）】
+  端点：GET /health/live
+  目的：服务是否正常运行
+  检查：进程响应、无死锁
+  失败：重启容器
+
+【启动检查（Startup）】
+  端点：GET /health/startup
+  目的：服务是否完成初始化
+  检查：预热完成、数据加载完成
+  失败：延长等待，不杀死进程
+
+实现建议：
+  /health 端点应：
+    - 返回 200 表示健康
+    - 返回 5xx 表示不健康
+    - 不包含敏感信息
+    - 快速响应（< 100ms）
+    - 不进行复杂计算
+```
+
+## 回滚策略
+
+```text
+【触发回滚的条件】
+  - 健康检查连续失败
+  - 错误率超过阈值（如 5xx > 1%）
+  - 延迟超过基准线 2 倍
+  - 业务指标异常（如转化率下降）
+  - 手动触发（线上事故）
+
+【回滚方式】
+  快速回滚（秒级）：
+    - 负载均衡切回旧版本（蓝绿部署）
+    - DNS 切换
+
+  标准回滚（分级）：
+    - 恢复到上一个稳定版本
+    - 数据库迁移需回滚
+
+  重建回滚（分钟级）：
+    - 从头部署旧版本
+    - 适用：非容器化部署
+
+【回滚后操作】
+  1. 确认服务恢复
+  2. 通知团队
+  3. 分析事故原因
+  4. 更新测试防止重现
+```
+
+## 环境变量与配置管理
+
+```text
+【配置分层】
+  代码级           → 不随环境变化（默认值、常量）
+  构建级           → 构建时注入（构建时间、Git commit）
+  部署级（环境变量） → 环境差异（DB URL、API Key）
+  运行时级          → 运行时获取（配置中心、Secrets Manager）
+
+【敏感配置】
+  不使用环境变量（日志可能泄露）
+  使用密钥管理服务（Vault、AWS Secrets Manager、GCP Secret Manager）
+  或加密后提交，部署时解密
+
+【配置验证】
+  启动时验证所有必需配置存在
+  缺失时快速失败（fail fast）
+  打印缺失的配置名（但不打印值）
+```
+
+## 监控与告警
+
+```text
+【必须监控的指标】
+  可用性  — 健康检查成功率
+  性能    — 请求延迟（P50/P95/P99）
+  容量    — CPU/内存/磁盘/网络
+  错误    — 错误率（4xx/5xx）
+  业务    — 关键业务指标（注册数、订单数）
+
+【告警规则】
+  P0（紧急）：服务不可用、数据丢失 → 即时通知
+  P1（高）：延迟飙升、错误率突增 → 5 分钟内通知
+  P2（中）：容量接近上限 → 24 小时内处理
+  P3（低）：非关键警告 → 下一迭代处理
+
+【告警原则】
+  - 告警可行动（收到告警能采取具体操作）
+  - 避免告警疲劳（太少 ≠ 太多）
+  - 告警包含上下文（什么服务、什么指标、多久了）
+```

package/templates/skills/devops/docker-patterns/SKILL.md.ejs

@@ -0,0 +1,215 @@
+# Docker Patterns — Docker 容器化模式
+
+> 使用此 skill 时：编写 Dockerfile、配置 Compose、优化镜像、排查容器问题。
+
+## 开发环境配置
+
+### Docker Compose 结构
+
+```text
+compose.yaml
+├── services:
+│   ├── app          # 应用服务
+│   ├── db           # 数据库
+│   ├── cache        # 缓存（Redis / Memcached）
+│   ├── queue        # 消息队列
+│   └── proxy        # 反向代理（开发用）
+├── volumes:         # 持久化数据
+└── networks:        # 网络隔离
+```
+
+### 开发环境要点
+
+```text
+【热重载】
+  - 挂载源码目录到容器内（volumes）
+  - 应用进程支持文件变化自动重启
+
+【环境变量】
+  - 用 .env 文件管理（不提交到 git）
+  - compose.yaml 引用 ${VARIABLE:-default}
+
+【端口映射】
+  - 只暴露需要的端口
+  - 避免端口冲突（映射到随机主机端口）
+
+示例卷挂载：
+  volumes:
+    - ./src:/app/src           # 源码热重载
+    - /app/node_modules        # 匿名卷（覆盖，防止覆盖容器内依赖）
+```
+
+## 多阶段构建
+
+### 通用模式
+
+```text
+【第一阶段：构建（Builder）】
+  FROM base AS builder
+  WORKDIR /app
+  COPY package.json ./
+  RUN install dependencies
+  COPY . .
+  RUN build
+
+【第二阶段：运行（Runtime）】
+  FROM runtime-base
+  WORKDIR /app
+  COPY --from=builder /app/dist ./dist
+  COPY --from=builder /app/node_modules ./node_modules
+  EXPOSE 3000
+  CMD ["run"]
+```
+
+### 优化技巧
+
+```text
+缓存利用：
+  1. 先复制依赖配置文件（package.json / requirements.txt）
+  2. 安装依赖（这一层会缓存，源码不变时不重跑）
+  3. 再复制源码
+  4. 最后构建
+
+  # 好 — 利用缓存
+  COPY package.json .
+  RUN npm install
+  COPY src/ .
+  RUN npm run build
+
+  # 坏 — 每次重装依赖
+  COPY . .
+  RUN npm install && npm run build
+
+减少层数：
+  - 合并 RUN 命令（&& 连接）
+  - 清理缓存文件（apt-get clean、npm cache clean --force）
+  - 多阶段构建只复制产物
+
+基础镜像选择：
+  alpine       → 最小体积（但 musl libc 可能不兼容）
+  slim         → Debian 精简版（推荐）
+  distroless   → 最小攻击面（但调试困难）
+  结论：首选 slim，需要最小体积用 distroless
+```
+
+## 安全最佳实践
+
+```text
+【不使用 root 用户运行】
+  RUN groupadd -r appuser && useradd -r -g appuser appuser
+  USER appuser
+
+【最小基础镜像】
+  - 越小的镜像 = 越小的攻击面
+  - 避免包含编译器、调试工具、包管理器
+
+【镜像漏洞扫描】
+  定期扫描：trivy / docker scan / snyk
+  CI 中集成：漏洞阻断（CRITICAL/HIGH）
+
+【其他安全措施】
+  - 不将敏感信息写入镜像（构建参数 vs 环境变量）
+  - 使用 secrets 挂载（BuildKit: --secret）
+  - READ_ONLY 根文件系统（read_only: true）
+  - 限制容器能力（cap_drop: ALL）
+  - 不暴露 Docker socket（除非绝对必要）
+```
+
+## 日志管理
+
+```text
+【原则】
+  应用 → stdout/stderr → Docker 收集 → 日志驱动 → 集中管理
+
+12-Factor App：
+  应用将日志写入 stdout/stderr
+  Docker 负责收集和路由
+
+生产环境日志驱动（compose.yaml）：
+  logging:
+    driver: "json-file"
+    options:
+      max-size: "10m"
+      max-file: "3"
+
+集中日志方案：
+  - 文件日志驱动 + Filebeat → Elasticsearch
+  - syslog 驱动 → 集中日志服务器
+  - awslogs / gcp 驱动 → 云平台日志服务
+```
+
+## 常见服务模板
+
+### PostgreSQL
+
+```text
+db:
+  image: postgres:16-alpine
+  environment:
+    POSTGRES_DB: ${DB_NAME}
+    POSTGRES_USER: ${DB_USER}
+    POSTGRES_PASSWORD: ${DB_PASSWORD}
+  volumes:
+    - pgdata:/var/lib/postgresql/data
+    - ./init-db:/docker-entrypoint-initdb.d  # 初始化脚本
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
+    interval: 5s
+    timeout: 5s
+    retries: 5
+```
+
+### Redis
+
+```text
+cache:
+  image: redis:7-alpine
+  command: redis-server --requirepass ${REDIS_PASSWORD}
+  volumes:
+    - redis-data:/data
+  healthcheck:
+    test: ["CMD", "redis-cli", "ping"]
+    interval: 5s
+    timeout: 3s
+    retries: 5
+```
+
+### Nginx（反向代理）
+
+```text
+proxy:
+  image: nginx:alpine
+  volumes:
+    - ./nginx.conf:/etc/nginx/nginx.conf:ro
+    - ./public:/var/www/public:ro
+  ports:
+    - "80:80"
+    - "443:443"
+  depends_on:
+    - app
+```
+
+## Docker 排查命令
+
+```text
+查看日志：
+  docker logs {container}                    # 标准日志
+  docker logs -f {container}                 # 实时追踪
+  docker logs --tail 100 {container}         # 只看最后 100 行
+
+检查进程：
+  docker exec {container} ps aux             # 运行了什么进程
+  docker top {container}                     # Docker 封装的 top
+
+进入容器调试：
+  docker exec -it {container} sh             # 进入容器（alpine）
+  docker exec -it {container} bash           # 进入容器（debian）
+
+资源监控：
+  docker stats {container}                   # CPU/内存/网络
+  docker inspect {container} | jq '.[0].State'  # 容器状态
+
+构建调试：
+  docker build --no-cache .                  # 无缓存构建
+  docker build --progress=plain .            # 详细构建输出
+```