ironweave 1.0.0

package/skills/orchestrator/references/route-d.md

@@ -0,0 +1,75 @@
+# D：重构
+
+## Plan
+
+> **注意**：如果 CLARIFY 阶段已执行架构讨论，Plan 中的 brainstorm 默认**跳过**，除非重构过程中发现新的策略争议。
+
+```mermaid
+graph TB
+    START["D 启动"] --> CTX["project-context<br>读取架构全貌"]
+    CTX --> ASSESS["现状评估<br>问题识别 + 影响范围"]
+
+    ASSESS --> BRAIN_CHK{"L4+ 且<br>CLARIFY 未做?"}
+    BRAIN_CHK -->|"是"| BRAIN["brainstorm<br>评估重构策略"]
+    BRAIN_CHK -->|"否"| PLAN_REF
+    BRAIN --> PLAN_REF["重构方案<br>目标架构 + 迁移路径"]
+
+    PLAN_REF --> ENG{"L3+?"}
+    ENG -->|"是"| ENG_DO["engineering-principles<br>验证方案合规性"]
+    ENG -->|"否"| RISK
+    ENG_DO --> PERF_CHK{"L4+?"}
+    PERF_CHK -->|"是"| PERF["performance-arch-design<br>性能重设计"]
+    PERF_CHK -->|"否"| RISK
+    PERF --> RISK["风险评估<br>回归风险 + 回滚能力"]
+
+    RISK --> DOCS_CHK{"L3+?"}
+    DOCS_CHK -->|"是"| DOCS["docs-output<br>增量同步"]
+    DOCS_CHK -->|"否"| GATE
+    DOCS --> GATE["Plan 卡点"]
+
+    style CTX fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style ASSESS fill:#fff3e0,stroke:#e65100,color:#bf360c
+    style BRAIN fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+    style PLAN_REF fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
+    style ENG_DO fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style PERF fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+    style RISK fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+    style DOCS fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style GATE fill:#fff3e0,stroke:#e65100,color:#bf360c,stroke-width:2px
+```
+
+### 变体差异
+
+| Skill | D-lite | D | D+ |
+|-------|--------|---|-----|
+| project-context | 读取架构 | 读取架构 | 读取架构 |
+| 现状评估 | 快速 | 标准 | 深度 |
+| brainstorm | 跳过 | 跳过 | CLARIFY 未做则必做；CLARIFY 已做则跳过 |
+| 重构方案 | 简要 | 标准 | 详细 + 迁移计划 |
+| engineering-principles | 跳过 | 标准验证 | 深度验证 |
+| performance-arch-design | 跳过 | 跳过 | 性能重设计 |
+| 风险评估 | 跳过 | 标准 | 详细 + 回滚方案 |
+| docs-output | 跳过 | 增量同步 | 增量同步 |
+
+---
+
+## Execute
+
+通用执行流程（任务分解 → TDD 循环 → 审查 → 汇合）→ 读取 `references/execute.md`。Route D 的**特化规则**：
+
+- **无 scaffold** — 重构不新建项目/模块骨架
+- **核心原则**：每个 task 完成后**原有测试必须全部通过**（行为等价）
+- `integration-test-design` **仅在跨层重构时触发**
+- **不允许积累**：不允许多个 task 完成后再统一测试，每个 task 后立即验证等价性
+
+```mermaid
+graph TB
+    E1["Task 1..N: 按重构方案分步编码<br>TDD + 每步行为等价验证"] --> E2{"跨层变更?"}
+    E2 -->|"是"| E3["Task N+1: integration-test-design<br>迁移验证测试"]
+    E2 -->|"否"| E4["汇合: 全量测试<br>确认行为等价"]
+    E3 --> E4
+
+    style E1 fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style E3 fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style E4 fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+```

package/skills/orchestrator/references/scope-sizer.md

@@ -0,0 +1,219 @@
+# 范围切片（Scope Sizer）
+
+在 CLARIFY 之后（或 CLARIFY 跳过后）、路径选择之前执行。评估任务的**广度**而非深度，决定是否将一个大需求拆分为多个可管理的 slice。
+
+## 前置输入
+
+scope-sizer 需要**已澄清的需求信息**作为输入，而非原始模糊的用户输入：
+
+| 来源 | 内容 | 何时可用 |
+|------|------|---------|
+| CLARIFY 产出 | 模块清单、核心功能、架构方向 | CLARIFY 被触发时 |
+| 用户输入本身 | 已经足够具体（如"给 user 模块加修改密码"） | CLARIFY 跳过时 |
+| project-context | 已有项目的模块结构（B/C/D 路径） | 有代码仓库时 |
+
+---
+
+## 为什么需要切片
+
+- **上下文窗口有限**：一次对话无法完成 8 个模块的 Plan + Execute
+- **风险分散**：每个 slice 独立验证，问题早暴露早修复
+- **可中断恢复**：用户可在任意 slice 后暂停，下次会话从 progress 恢复
+- **增量交付**：每完成一个 slice 就有可部署的增量产出
+
+---
+
+## 评估维度
+
+```mermaid
+graph TB
+    INPUT["已澄清的需求信息<br>（来自 CLARIFY 或具体的用户输入）"] --> DIM1["D1: 模块数<br>识别独立业务模块"]
+    INPUT --> DIM2["D2: 功能点数<br>Must 级功能点计数"]
+    INPUT --> DIM3["D3: 跨模块依赖<br>模块间耦合度"]
+    DIM1 --> DECIDE{"切片决策"}
+    DIM2 --> DECIDE
+    DIM3 --> DECIDE
+
+    style INPUT fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style DECIDE fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c,stroke-width:2px
+```
+
+| 维度 | 单 slice 标准 | 需拆分标准 |
+|------|-------------|-----------|
+| **模块数** | <= 2 个独立模块 | > 2 个独立模块 |
+| **功能点数** | <= 3 个 Must 功能 | > 3 个 Must 功能 |
+| **跨模块依赖** | 无依赖或线性依赖 | 存在循环依赖或复杂编织 |
+
+**触发条件**：任意一个维度达到"需拆分标准"即触发切片。
+
+用户可覆盖："不拆，一次做完" → 跳过切片，但需在 Plan 中标注风险。
+
+---
+
+## 切片策略
+
+切片策略因路径不同而异。核心思想相同：**按风险和依赖排序，每个 slice 可独立验证**。
+
+### Route A（新项目）— 按依赖层分组
+
+```mermaid
+graph LR
+    MODULES["所有模块"] --> GROUP["按依赖层分组"]
+    GROUP --> L1["Layer 1: 基础设施<br>认证 · 权限 · 通用配置"]
+    GROUP --> L2["Layer 2: 核心域<br>核心业务模块"]
+    GROUP --> L3["Layer 3: 支撑域<br>辅助功能模块"]
+    GROUP --> L4["Layer 4: 集成层<br>跨模块联动 · 聚合页面"]
+
+    style L1 fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style L2 fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
+    style L3 fill:#fff9c4,stroke:#f9a825,color:#e65100
+    style L4 fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+```
+
+1. **基础设施优先**：认证、权限、数据库初始化、项目骨架等放在 Slice 1
+2. **核心域其次**：系统最核心的业务模块（如小说系统的"小说管理 + 阅读"）放在 Slice 2
+3. **支撑域跟随**：锦上添花但非 MVP 核心的模块（如评论、书架、推荐）后续 slice
+4. **集成层最后**：需要多模块协作的聚合功能（如首页仪表盘、搜索聚合）放最后
+
+### 每个 slice 的粒度控制
+
+| 约束 | 目标 |
+|------|------|
+| 最大模块数 | 单个 slice 不超过 2-3 个模块 |
+| 最大功能点 | 单个 slice 不超过 5 个 Must 功能 |
+| 最大预估文件 | 单个 slice 新增/修改不超过 ~30 个文件 |
+| 可独立运行 | 每个 slice 完成后项目应可编译运行 |
+
+### 全局 vs Slice 级 Skill
+
+| Skill | 首个 Slice | 后续 Slice |
+|-------|-----------|-----------|
+| requirement-qa | 全局 + Slice 1 细节 | 仅 Slice N 细节 |
+| brainstorm | 全局架构方案 | **默认跳过**（CLARIFY 已做）；仅新架构争议时触发 |
+| spec-writing | 全局概览 + Slice 1 六段式 | 仅 Slice N 六段式 |
+| tech-stack | **完整输出**（全局性） | **跳过**（复用 Slice 1 产出） |
+| engineering-principles | **完整匹配**（全局性） | **跳过**（复用） |
+| api-contract-design | Slice 1 涉及的端点 | Slice N 增量端点 |
+| error-handling-strategy | **完整设计**（全局性） | **跳过**（复用） |
+| code-scaffold | **完整骨架**（仅 Slice 1） | **跳过**（骨架已存在） |
+| docs-output | 初始化 + Slice 1 同步 | **Slice N 增量同步** |
+| project-context | 初始化 + Slice 1 回写 | **Slice N 增量回写** |
+
+### Route B（新功能）— 按实现阶段分组
+
+已有项目上添加新功能时，切片维度从"模块数"转变为"实现阶段"和"影响范围"：
+
+| 维度 | 单 slice 标准 | 需拆分标准 |
+|------|-------------|-----------|
+| **影响模块数** | 仅 1 个模块内部 | 跨 2+ 模块 |
+| **实现层次** | 单层（仅后端 / 仅前端） | 前后端 + 数据迁移 |
+| **数据变更** | 无 schema 变更 | 需要数据迁移 |
+
+**分组原则**：
+
+1. **数据层优先**：如需 schema 变更或数据迁移，单独一个 slice
+2. **后端 API 其次**：新增/修改后端接口
+3. **前端 UI 跟随**：依赖后端 API 的前端页面/组件
+4. **集成联调最后**：端到端集成测试 + 回归
+
+示例："给小说系统加搜索功能"
+| Slice | 范围 | 内容 |
+|-------|------|------|
+| S1 | 数据层 | ES 索引设计 · 数据同步管道 · schema 迁移 |
+| S2 | 后端 | SearchService · 搜索 API · 分页/排序 |
+| S3 | 前端 + 集成 | 搜索 UI · 联调 · 回归测试 |
+
+### Route C（Bug 修复）— 通常单 slice
+
+Bug 修复天然范围窄，**默认不切片**。仅当以下条件满足时才触发：
+
+| 信号 | 判定 |
+|------|------|
+| 系统性 bug 影响 3+ 模块 | 需按模块逐个修复验证 |
+| 修复需要数据修正 + 代码修复 | 分为"数据修正 slice"+"代码修复 slice" |
+| 其他情况 | **单 slice，跳过切片** |
+
+### Route D（重构）— 按安全边界分步
+
+重构的切片原则是**每步可回滚、行为等价**：
+
+| 维度 | 单 slice 标准 | 需拆分标准 |
+|------|-------------|-----------|
+| **受影响模块** | 仅 1 个模块内部重构 | 跨 2+ 模块或公共层 |
+| **API 变更** | 内部实现变更，API 不变 | API 签名/协议变更 |
+| **数据模型变更** | 无 schema 变更 | 需要数据迁移 |
+
+**分组原则**：
+
+1. **内部重构优先**：不改变外部 API 的模块内部重构（最安全）
+2. **接口重构其次**：API 签名变更 + 调用方适配
+3. **数据迁移最后**：schema 变更 + 数据转换（风险最高）
+
+示例："把认证模块重构为微服务"
+| Slice | 范围 | 内容 |
+|-------|------|------|
+| S1 | 内部抽象 | 提取 AuthService 接口 · 解耦直接调用 |
+| S2 | 服务拆分 | 独立服务部署 · gRPC/HTTP 通信 |
+| S3 | 数据迁移 | 用户表迁移 · 双写过渡 · 旧代码清理 |
+
+---
+
+## 切片清单输出格式
+
+评估完成后，输出切片清单供用户确认：
+
+```markdown
+### Slice 切片计划
+
+**需求**: [需求名称]
+**评估结果**: [模块数] 个模块 · [功能点] 个 Must 功能 → 拆分为 [N] 个 slice
+
+| Slice | 范围 | 包含模块 | 关键功能 | 依赖 |
+|-------|------|---------|---------|------|
+| S1 | 基础设施 + 核心骨架 | auth, common | 项目初始化 · 认证 · 权限 | 无 |
+| S2 | 核心域 | novel, chapter | 小说 CRUD · 章节管理 · 阅读器 | S1 |
+| S3 | 支撑域 | user, bookshelf | 用户档案 · 书架 · 收藏 | S1, S2 |
+| S4 | 集成 | search, dashboard | 全文搜索 · 首页推荐 | S1-S3 |
+
+**预计每个 Slice 独立走完 Plan→Execute→Validate→Deliver。**
+**每个 Slice 完成后同步 docs/ 和 .cache/context.db。**
+
+确认此切片计划？（可调整顺序、合并或拆分 slice）
+```
+
+---
+
+## Slice 迭代器行为
+
+```mermaid
+graph TB
+    START["Slice 清单已确认"] --> READ["读取当前 Slice 定义"]
+    READ --> CTX_CHECK["检查前置 Slice 产出<br>docs/ + .cache/context.db"]
+    CTX_CHECK --> ROUTE["路径选择<br>（通常仍为 A）"]
+    ROUTE --> PLAN["Plan<br>（仅 Slice 级 Skill）"]
+    PLAN --> GATE_P{"Plan 卡点"}
+    GATE_P -->|"通过"| EXEC["Execute"]
+    GATE_P -->|"不通过"| PLAN
+    EXEC --> GATE_V{"Validate 卡点"}
+    GATE_V -->|"通过"| DELIVER["Deliver<br>docs-output + project-context"]
+    GATE_V -->|"代码/设计/需求级"| REFLOW["回流"]
+    DELIVER --> NEXT{"还有 Slice?"}
+    NEXT -->|"是"| PAUSE{"用户选择"}
+    NEXT -->|"否"| DONE["全部完成<br>输出最终交付摘要"]
+    PAUSE -->|"继续"| READ
+    PAUSE -->|"暂停"| SAVE["保存进度<br>下次从此恢复"]
+
+    style START fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style DELIVER fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20,stroke-width:2px
+    style PAUSE fill:#fff3e0,stroke:#e65100,color:#bf360c,stroke-width:2px
+    style DONE fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20,stroke-width:2px
+    style SAVE fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+```
+
+### 暂停与恢复
+
+- 每个 Slice 的 Deliver 阶段强制同步 docs/ 和 .cache/context.db
+- 如果用户暂停（或会话中断），下次启动 Orchestrator 时：
+  1. project-context 读取 .cache/context.db → 发现项目已有代码和文档
+  2. 读取 docs/progress/ → 发现上次完成到 Slice N
+  3. 自动从 Slice N+1 继续，无需重新评估全局上下文

package/skills/performance-arch-design/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: performance-arch-design
+description: >-
+  性能前置设计——在编码前从架构层面识别性能瓶颈并设计缓存分层、异步处理、数据库索引、限流和分区策略。将性能思维融入系统架构设计阶段，避免事后优化的高成本。
+  务必在以下场景使用本 skill：用户提到性能优化、缓存设计、缓存策略、Redis、异步处理、消息队列、数据库索引、索引设计、限流、熔断、分库分表、分区、N+1 查询、慢查询、高并发、性能瓶颈、QPS、TPS、响应时间、吞吐量、性能基线、压测目标、热点数据、读写分离，或涉及 steps/06 系统架构中的性能相关决策。
+---
+
+# 性能前置设计
+
+在编码前从架构层面识别性能瓶颈，设计缓存分层、异步处理、索引策略和限流方案。
+
+---
+
+## 设计流程
+
+```mermaid
+graph TB
+    INPUT["系统架构 + 业务场景"] --> BASELINE["性能基线<br>目标 QPS / 响应时间"]
+    BASELINE --> HOTSPOT["热点识别<br>高频读 / 高频写 / 大数据量"]
+    HOTSPOT --> CACHE["缓存分层<br>本地 / 分布式 / CDN"]
+    HOTSPOT --> ASYNC["异步处理<br>消息队列 / 事件驱动"]
+    HOTSPOT --> INDEX["索引策略<br>数据库索引 / 全文检索"]
+    CACHE --> PROTECT["保护机制<br>限流 / 熔断 / 降级"]
+    ASYNC --> PROTECT
+    INDEX --> PROTECT
+    PROTECT --> OUTPUT["输出性能方案"]
+
+    style INPUT fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style BASELINE fill:#fff3e0,stroke:#e65100,color:#bf360c
+    style HOTSPOT fill:#ffcdd2,stroke:#c62828,color:#b71c1c
+    style CACHE fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style ASYNC fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style INDEX fill:#e8eaf6,stroke:#283593,color:#1a237e
+    style PROTECT fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+    style OUTPUT fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
+```
+
+---
+
+## 1. 性能基线定义
+
+### 目标模板
+
+| 指标 | 目标 | 测量方式 |
+|--|--|--|
+| P99 响应时间 | < 200ms (读) / < 500ms (写) | APM 工具 |
+| QPS | 根据业务估算 | 压测工具 |
+| 错误率 | < 0.1% | 监控告警 |
+| 数据库查询 | < 50ms (单表) / < 200ms (联表) | 慢查询日志 |
+
+### 估算公式
+
+```
+预估 QPS = 日活用户 × 人均请求数 / 有效时长(秒)
+峰值 QPS = 预估 QPS × 3（峰值系数）
+```
+
+---
+
+## 2. 热点识别
+
+### 读热点
+
+| 特征 | 示例 | 优化策略 |
+|--|--|--|
+| 同一数据被大量请求 | 商品详情、配置信息 | 缓存 |
+| 列表查询频繁 | 首页数据、排行榜 | 预计算 + 缓存 |
+| 大数据量全表扫描 | 搜索、报表 | 索引 / 全文检索 / 物化视图 |
+
+### 写热点
+
+| 特征 | 示例 | 优化策略 |
+|--|--|--|
+| 高并发写同一行 | 库存扣减、计数器 | 乐观锁 / 分桶计数 |
+| 批量数据写入 | 日志写入、数据导入 | 异步 + 批量 |
+| 大事务 | 多表级联操作 | 拆分事务 / Saga |
+
+---
+
+## 3. 缓存分层
+
+```mermaid
+graph LR
+    REQ["请求"] --> L1["L1: 本地缓存<br>Caffeine / LRU<br>< 1ms"]
+    L1 -->|"未命中"| L2["L2: 分布式缓存<br>Redis<br>1-5ms"]
+    L2 -->|"未命中"| DB["数据库<br>10-100ms"]
+    DB -->|"回填"| L2
+    L2 -->|"回填"| L1
+
+    style REQ fill:#f5f5f5,stroke:#616161,color:#212121
+    style L1 fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
+    style L2 fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style DB fill:#ffe0b2,stroke:#e65100,color:#bf360c
+```
+
+### 缓存策略选择
+
+| 场景 | 策略 | TTL | 说明 |
+|--|--|--|--|
+| 基本不变的数据 | Cache-Aside | 24h | 配置、字典表 |
+| 频繁读少量写 | Cache-Aside + 写失效 | 1h | 用户信息、商品详情 |
+| 读写均衡 | Write-Through | 30min | 会话数据 |
+| 写多读少 | Write-Behind | N/A | 日志、统计 |
+| 排行榜/计数 | Redis 原生结构 | 持久化 | SortedSet / HyperLogLog |
+
+### 缓存问题防护
+
+| 问题 | 原因 | 解决方案 |
+|--|--|--|
+| 缓存穿透 | 查询不存在的数据 | 布隆过滤器 / 缓存空值(短 TTL) |
+| 缓存击穿 | 热点 Key 过期 | 互斥锁加载 / 永不过期+异步刷新 |
+| 缓存雪崩 | 大量 Key 同时过期 | TTL 加随机偏移 / 多级缓存 |
+
+---
+
+## 4. 异步处理
+
+### 适用场景判定
+
+```mermaid
+graph TB
+    DECIDE{"该操作是否?"} -->|"用户需要即时结果"| SYNC["同步处理"]
+    DECIDE -->|"耗时 > 2s"| ASYNC_YES["异步 + 轮询/推送"]
+    DECIDE -->|"不影响主流程"| ASYNC_FIRE["异步 Fire-and-Forget"]
+    DECIDE -->|"需要多步编排"| SAGA["Saga / 工作流"]
+
+    style SYNC fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
+    style ASYNC_YES fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
+    style ASYNC_FIRE fill:#fff9c4,stroke:#f9a825,color:#e65100
+    style SAGA fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
+```
+
+### 消息队列选型
+
+| 队列 | 适用 | 特点 |
+|--|--|--|
+| Redis Stream | 轻量级、单机 | 简单、不持久化 |
+| RabbitMQ | 中小型、需要路由 | 灵活路由、可靠投递 |
+| Kafka | 大数据量、日志流 | 高吞吐、持久化、分区 |
+
+---
+
+## 5. 数据库索引策略
+
+### 索引设计原则
+
+| 原则 | 说明 |
+|--|--|
+| 高选择性字段优先 | 唯一值多的列效果好 |
+| 查询条件即索引 | WHERE / ORDER BY / JOIN 的列 |
+| 复合索引最左前缀 | 遵循查询模式排列列顺序 |
+| 覆盖索引 | 索引包含查询所有列，避免回表 |
+| 避免过度索引 | 每增加一个索引，写入性能下降 |
+
+### N+1 查询防护
+
+| 场景 | ORM 解法 | SQL 解法 |
+|--|--|--|
+| 关联查询 | Eager Loading / Join Fetch | LEFT JOIN |
+| 批量查询 | `findAllById(ids)` | `WHERE id IN (...)` |
+| 分页+关联 | 先查 ID 再批量加载 | 子查询分页 |
+
+### 慢查询预防清单
+- [ ] 所有 WHERE 条件都有索引覆盖
+- [ ] 无全表 COUNT(*)（用近似计数或缓存）
+- [ ] 无 `SELECT *`（只查需要的列）
+- [ ] 分页用游标/Keyset 而非 OFFSET
+- [ ] 大 IN 列表拆分为批次（< 1000 条）
+
+---
+
+## 6. 限流策略
+
+| 算法 | 适用 | 特点 |
+|--|--|--|
+| 固定窗口 | 简单限流 | 有边界突刺问题 |
+| 滑动窗口 | 一般 API | 平滑、内存稍多 |
+| 令牌桶 | 允许突发 | 可积累令牌应对突发 |
+| 漏桶 | 严格匀速 | 流量平滑 |
+
+### 限流维度
+
+| 维度 | 示例 |
+|--|--|
+| 用户级 | 每用户 100 次/分 |
+| IP 级 | 每 IP 200 次/分 |
+| API 级 | 某接口全局 1000 次/秒 |
+| 服务级 | 上游调用方配额 |
+
+---
+
+## 7. 输出清单
+
+| 制品 | 说明 |
+|--|--|
+| 性能基线文档 | 目标 QPS、响应时间、错误率 |
+| 热点分析表 | 读热点 + 写热点 + 优化策略 |
+| 缓存设计方案 | 分层策略、TTL、防护措施 |
+| 异步处理方案 | 场景列表 + 队列选型 |
+| 索引设计清单 | 每张表的索引定义 |
+| 限流配置 | 维度 + 算法 + 阈值 |
+
+---
+
+## 参考
+
+详细规则参见 `references/` 目录：
+- `performance-rules.md` — 性能设计详细规则与反模式

package/skills/performance-arch-design/references/performance-rules.md

@@ -0,0 +1,95 @@
+# 性能设计规则与反模式
+
+## 性能反模式
+
+| 反模式 | 问题 | 解决方案 |
+|--|--|--|
+| N+1 查询 | 循环中逐条查询 | 批量查询 / JOIN |
+| SELECT * | 返回不需要的列 | 显式列出字段 |
+| 大事务 | 长时间持锁 | 拆分事务、减小范围 |
+| OFFSET 分页 | 深分页性能差 | Keyset 游标分页 |
+| 无索引全表扫描 | 查询 O(n) | 添加合适索引 |
+| 缓存 key 无 TTL | 内存持续增长 | 所有 key 设置 TTL |
+| 同步调用链过长 | 延迟累加 | 异步化非关键路径 |
+| 数据库当队列用 | 轮询开销大 | 使用消息队列 |
+| 日志中序列化大对象 | 影响吞吐 | 只记关键字段 |
+| 无连接池 | 连接创建开销 | 配置连接池(HikariCP) |
+
+## 缓存 Key 设计规范
+
+### 命名格式
+```
+{app}:{module}:{entity}:{id}[:suffix]
+```
+
+示例：
+- `myapp:user:profile:12345`
+- `myapp:order:list:user:12345:page:1`
+- `myapp:config:system:global`
+
+### 规则
+- Key 长度 < 128 字节
+- 不包含空格和特殊字符
+- 使用 `:` 分隔层级
+- 批量操作用 `{hash_tag}` 保证同槽
+
+## Redis 数据结构选型
+
+| 场景 | 数据结构 | 示例 |
+|--|--|--|
+| 对象缓存 | String (JSON) | 用户信息 |
+| 计数器 | String (INCR) | API 调用次数 |
+| 集合去重 | Set | 用户在线列表 |
+| 排行榜 | Sorted Set | 积分排行 |
+| 近似计数 | HyperLogLog | UV 统计 |
+| 布隆过滤 | Bloom Filter (module) | 缓存穿透防护 |
+| 限流 | String + Lua 脚本 | 滑动窗口计数 |
+| 分布式锁 | String + NX + PX | Redisson |
+
+## 连接池配置参考
+
+### HikariCP (Java)
+
+| 参数 | 推荐值 | 说明 |
+|--|--|--|
+| maximumPoolSize | CPU 核心数 * 2 + 1 | 数据库连接上限 |
+| minimumIdle | 与 maximumPoolSize 相同 | 固定连接数性能最优 |
+| connectionTimeout | 30000ms | 获取连接超时 |
+| idleTimeout | 600000ms (10min) | 空闲连接存活时间 |
+| maxLifetime | 1800000ms (30min) | 连接最大存活时间 |
+
+## Keyset 分页 vs OFFSET 分页
+
+### OFFSET 分页（不推荐深分页）
+```sql
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 10000;
+-- 数据库需要扫描 10020 行再丢弃前 10000 行
+```
+
+### Keyset 分页（推荐）
+```sql
+SELECT * FROM orders WHERE id > :lastId ORDER BY id LIMIT 20;
+-- 直接从索引定位，性能恒定
+```
+
+### 前端配合
+```json
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTAyMH0=",
+    "hasMore": true
+  }
+}
+```
+
+## 压测检查清单
+
+- [ ] 已确定目标 QPS 和 P99 响应时间
+- [ ] 压测数据量与生产一致（或同量级）
+- [ ] 压测覆盖热点接口（读 + 写）
+- [ ] 观察数据库连接池使用率
+- [ ] 观察 CPU / 内存 / 网络 IO
+- [ ] 观察慢查询和慢日志
+- [ ] 压测期间无 OOM 或连接泄漏
+- [ ] 压测后数据一致性验证