smart-commit-copilot-cli 0.1.5 → 0.1.6

package/src/code-review-skills/c-code-review/references/build-and-tooling.md

@@ -0,0 +1,16 @@
+# 构建与工具链检查清单
+
+## 标准与编译选项
+
+- `-std=c11`/`c17`、`C_STANDARD`、警告等级和优化选项是否与新增代码用法一致。
+- 是否关闭关键警告或弱化 `-Wall`/`-Wextra`/`-Werror` 等质量门槛而没有说明。
+
+## Sanitizer 与分析工具
+
+- ASan、UBSan、静态分析或格式检查配置是否被明显禁用、降级或误配。
+- 头文件搜索路径、宏定义和目标链接是否让新文件无法被正确编译或分析。
+
+## 构建脚本边界
+
+- Make/Meson/CMake 规则是否遗漏新源文件、公共头文件或平台分支。
+- 仅在 diff 涉及构建或工具配置时启用本清单；不推断 CI 或未展示脚本行为。

package/src/code-review-skills/c-code-review/references/concurrency-and-signals.md

@@ -0,0 +1,16 @@
+# 并发与信号检查清单
+
+## 线程与共享状态
+
+- `pthread` 共享状态是否在所有读写路径上保持一致的锁或原子保护。
+- 锁顺序、条件变量配对和错误路径解锁是否完整，避免死锁或泄漏锁。
+
+## 原子与可见性
+
+- 原子读写是否和非原子访问混用到同一共享对象上。
+- 自旋、标志位和停止信号是否存在可证的竞态或忙等退化。
+
+## 信号处理
+
+- 信号处理函数中是否调用了非 async-signal-safe 接口。
+- 主流程与信号处理之间共享的标志位是否使用适当类型和同步方式。

package/src/code-review-skills/c-code-review/references/error-handling-and-cleanup.md

@@ -0,0 +1,16 @@
+# 错误处理与清理路径检查清单
+
+## 返回码与 `errno`
+
+- 系统调用、库函数和内部 helper 的返回值是否被检查，并在失败时中止后续依赖操作。
+- 读取 `errno` 前是否确认前一个调用确实失败，且没有被后续调用覆盖。
+
+## 清理路径
+
+- `goto cleanup`、`break`、`return` 等退出路径是否统一释放已申请资源。
+- 部分初始化失败时，是否只清理已成功初始化的对象，避免重复释放或遗漏回滚。
+
+## 错误传播
+
+- 错误码是否保留足够信息供上层区分重试、用户错误和内部故障。
+- 记录错误或包装错误时，是否丢失原始失败条件、长度信息或上下文。

package/src/code-review-skills/c-code-review/references/macros-headers-and-build-boundaries.md

@@ -0,0 +1,16 @@
+# 宏、头文件与构建边界检查清单
+
+## 宏与条件编译
+
+- 函数式宏是否有副作用重复求值、缺少括号或与类型不匹配的问题。
+- `#ifdef`/`#ifndef` 分支是否让不同平台下的行为、布局或导出接口出现不一致风险。
+
+## 头文件契约
+
+- 头文件是否暴露不必要的内部实现、可变全局状态或缺少 include guard / `#pragma once`。
+- 声明与定义、`extern`、`static inline`、结构体前置声明是否与新增调用方式一致。
+
+## 模块边界
+
+- 新增公共头或导出符号时，是否破坏已有调用约定、初始化顺序或错误处理契约。
+- 仅凭 diff 可见信息判断问题，不假设未展示模块的包含顺序和链接方式。

package/src/code-review-skills/c-code-review/references/performance-and-data-movement.md

@@ -0,0 +1,16 @@
+# 性能与数据移动检查清单
+
+## 热路径分配与拷贝
+
+- 热路径上是否引入频繁 `malloc`/`free`、重复清零或可避免的缓冲区重分配。
+- 结构体或大缓冲区是否被不必要复制，而不是复用、传指针或按长度窗口处理。
+
+## 扫描与复杂度
+
+- 是否把单次扫描改成重复 `strlen`、重复查找或嵌套遍历，导致明显复杂度退化。
+- 字符串和二进制数据处理是否出现多余的 `memcpy`/`memmove` 链式搬运。
+
+## 系统调用与 I/O
+
+- 高频路径是否引入过细粒度的系统调用、刷新、日志或同步操作。
+- 仅在 diff 可见的热路径和长度行为上报告问题，不臆测真实负载。

package/src/code-review-skills/c-code-review/references/pointers-memory-and-resource-lifecycle.md

@@ -0,0 +1,18 @@
+# 指针、内存与资源生命周期检查清单
+
+## 所有权与释放
+
+- `malloc`/`calloc`/`realloc` 的返回值是否在可见路径上检查失败分支。
+- 新增分配后是否在所有早返回、错误路径和成功路径上保持成对释放，避免泄漏或双重释放。
+- `realloc` 是否直接覆盖原指针，导致失败时丢失原地址。
+
+## 指针与边界
+
+- 指针算术、数组下标和长度参数是否在 diff 中显示可能越界或差一错误。
+- `memcpy`/`memmove`/`strncpy`/`snprintf` 的目标长度是否与实际缓冲区大小一致。
+- 返回局部变量地址、悬空指针、释放后继续使用是否在 diff 中可证。
+
+## 资源清理
+
+- 文件描述符、`FILE *`、锁、映射区或库句柄是否在失败路径上遗漏释放。
+- 初始化一半失败时，是否按已完成的步骤逆序清理。

package/src/code-review-skills/c-code-review/references/scoring-guide.md

@@ -0,0 +1,40 @@
+# 评分指南
+
+评分由**最严重的已确认问题**决定基准区间，再在区间内微调。
+
+## 第一步：确定基准区间
+
+| 最严重问题 | 分值区间 |
+|-----------|---------|
+| 无问题 | 9.0-10.0 |
+| 仅 P2/P3 | 7.5-9.0 |
+| P1 | 4.0-7.0 |
+| P0（内存损坏、数据竞争、明显 UB） | 2.0-3.5 |
+| P0（安全漏洞、命令执行、凭证泄露） | 1.0-2.5 |
+
+## 第二步：在区间内调整
+
+- **影响广度**：影响全局状态、热路径或所有调用方取下限；仅局部边界触发取上限，差距约 0.5-1.0 分
+- **问题数量**：每多一个独立同级别问题，向下移约 0.3-0.5 分
+- **可逆性**：可快速定位、低风险修复的问题可上浮 0.3-0.5 分
+
+> 多个问题时取区间下限附近；单个问题且影响有限时取区间上限附近。
+
+## C 语境硬上限
+
+- 有任意 P0 -> 评分上限 3.5
+- 可证的缓冲区越界、释放后使用、双重释放或格式化字符串漏洞 -> 评分上限 2.5
+- 可证的数据竞争或未同步共享状态访问 -> 评分上限 2.5
+- 明显遗漏错误处理导致资源泄漏、状态损坏或失败后继续执行 -> 评分上限 3.0
+- 硬编码真实凭证或 secret 泄露 -> 评分上限 2.0
+- 纯文件删除（无逻辑变更）-> 评分记为 N/A
+- 测试、bench、示例中的问题 -> 最高计为 P2，不纳入 P0/P1 计数
+
+## 评分语义
+
+| 分值 | 提交建议 | 含义 |
+|------|---------|------|
+| 9.0-10.0 | ✅ 可以提交 | 无明显问题 |
+| 7.5-9.0 | ✅ 可以提交，跟进修复 | 有轻微问题，不影响提交 |
+| 4.0-7.0 | 🔧 修复后提交 | 存在 P1 问题，影响广取下限，影响窄取上限 |
+| 1.0-3.5 | 🚫 禁止提交 | 存在 P0 问题，必须修复 |

package/src/code-review-skills/c-code-review/references/undefined-behavior-and-safety.md

@@ -0,0 +1,17 @@
+# 未定义行为与安全检查清单
+
+## 越界与未初始化
+
+- 数组、缓冲区和字符串操作是否可能读写越界，或把终止符空间算漏。
+- 局部变量、结构体字段或输出缓冲区是否在读取前完成初始化。
+
+## 整数与格式化
+
+- 长度、容量、偏移和乘法是否存在可证的溢出、截断或符号转换问题。
+- `printf`/`snprintf`/日志格式串是否与参数类型一致，且格式串不来自未校验输入。
+
+## 别名与危险接口
+
+- 类型转换、强制转指针、对齐假设和 `void *` 回转是否依赖未证实前提。
+- `gets`、不受限的 `strcpy`/`sprintf`、未校验的 `scanf` 等危险接口是否被引入。
+- 仅在 diff 可证时报告 UB，不推断编译器优化或平台专有行为。

package/src/code-review-skills/code-review/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: code-reviewer
+description: "本地代码自审技能，用于开发者 commit 前对自己的改动进行预审。当用户请求 'review 代码'、'审查这次改动'、'找 diff 里的问题'、'review staged changes' 或 'code review this diff' 时使用。重点识别真实缺陷、安全漏洞、性能回退和设计问题，给出可执行的修复建议。默认只输出审查结论，不直接修改代码。"
+---
+
+# 代码审查
+
+## 问题门槛
+
+每条问题必须满足以下三点，否则不输出：
+
+1. **可定位**：能指向具体文件和新增行号
+2. **可自证**：仅凭当前 diff 和可见上下文即可成立，不依赖 diff 之外的假设
+3. **可修复**：给出具体修复方案，而非泛泛建议
+
+同一根因的多处表现合并为一条，不重复列举。
+
+## 严重级别
+
+| 等级 | 含义 | 处理 |
+|------|------|------|
+| **P0** | 安全漏洞、数据损坏、必现 crash | 必须修复后才能提交 |
+| **P1** | 逻辑错误、功能异常、明显性能/可靠性回退 | 提交前修复 |
+| **P2** | 可维护性问题、测试不足、非阻塞设计问题 | 当前批次修复或登记后续任务 |
+| **P3** | 次要改进 | 可选 |
+
+## 工作流
+
+### 1) 确认审查范围
+
+先用 `git status -sb` 判断当前状态，再决定审查哪部分：
+
+```bash
+git status -sb
+git --no-pager diff --stat          # unstaged 改动
+git --no-pager diff --cached --stat # staged 改动
+```
+
+- 有 unstaged 改动 → 审查 `git --no-pager diff`
+- 只有 staged 改动 → 审查 `git --no-pager diff --cached`
+- 两者都有 → 优先审查 staged `git --no-pager diff --cached`，并提示可再单独审查 unstaged（`git --no-pager diff`）
+
+diff 较大时写入文件再读取：
+
+```bash
+git --no-pager diff > code-review.patch
+```
+
+**边界情况：**
+- **用户直接提供 diff 文本**：跳过 git 命令，直接审查提供的内容。
+- **没有任何变更**：说明当前没有可审查内容，提示用户指定 commit 范围（如 `git diff main...HEAD`）。
+- **diff 较大**：先用 `--stat` 列出改动文件，按文件逐个审查，不要一次性处理全部 diff。
+
+### 2) 代码分析
+
+#### a) 安全与可靠性
+
+加载 `references/security-checklist.md`，说明问题的触发路径和影响范围。只在有明确代码路径支撑时才输出安全问题。
+
+#### b) 代码质量
+
+加载 `references/code-quality-checklist.md`，优先报告会导致错误结果或失败不可见的问题。
+
+#### c) 架构与设计
+
+加载 `references/solid-checklist.md`，检查本次改动是否引入新的设计问题。有重构建议时给出分步方案，不建议整体重写。
+
+#### d) 冗余与删除（diff 中没有代码删除时跳过）
+
+加载 `references/removal-plan.md`，确认被删代码无残留引用，相关测试和配置已同步清理。
+
+### 3) 整理问题列表
+
+确认每条问题满足门槛（可定位、可自证、可修复）。同一根因的多处表现合并为一条。不为凑数量降低标准。
+
+### 4) 评分
+
+加载 `references/scoring-guide.md`，**每次审查必须根据该指南给出具体评分**：先按最严重问题确定基准区间，再按影响广度、问题数量、可逆性在区间内微调，最终输出一个具体分值（如 8.5、7.0），不得只写区间或省略评分；纯文件删除时记为 N/A。
+
+### 5) 输出格式
+
+按以下格式输出：
+
+```markdown
+## 审查摘要
+
+**审查范围**：X 个文件，Y 行新增
+
+**评分**：X / 10（必须为具体分值，如 8.5；仅纯删除时为 N/A）
+
+**提交建议**：✅ 可以提交 / ✅ 可以提交，跟进修复 / 🔧 修复后提交 / 🚫 禁止提交
+
+**问题统计**：P0 × 个 / P1 × 个 / P2 × 个 / P3 × 个
+
+---
+
+## 各维度结果
+
+| # | 维度 | 结论 |
+|---|------|------|
+| 1 | 安全与可靠性 | ✅ 无问题 / ⚠️ 存在问题（简述） |
+| 2 | 代码质量 | ✅ 无问题 / ⚠️ 存在问题（简述） |
+| 3 | 架构与设计 | ✅ 无问题 / ⚠️ 存在问题（简述） / 不适用 |
+
+<!-- 纯文件删除时：前三行均填"不适用（纯删除，未引入新代码）"，并在末尾追加一行：
+| 4 | 冗余与删除 | ✅ 删除安全 / ⚠️ 存在问题（简述） | -->
+
+---
+
+## 问题列表
+
+### P0 🔴 严重
+无
+
+### P1 🟠 高
+1. **[文件:行号] 问题标题**
+   - **问题**：一句话说明是什么问题
+   - **影响**：一句话说明会导致什么后果
+   - **修复**：具体方案
+
+### P2 🟡 中
+无
+
+### P3 🟢 低
+无
+
+---
+
+## 总体评价
+
+2–3 句话说明是否建议提交，以及还需要哪些修复或跟进。
+```
+
+**输出规则：**
+- 每次审查必须在「审查摘要」中给出根据 `references/scoring-guide.md` 计算的具体评分（X / 10），不得省略。
+- 直接给问题，不写前言铺垫。
+- 每条问题写清楚：位置、问题是什么、影响是什么、如何修复。
+- 纯文件删除时，明确写"评分不适用"。
+- 禁止在模板之外添加"亮点"、"优点"、"表扬"等额外章节。
+- `## 总体评价` 只写 2–3 句连续段落，不用列表或子标题。
+
+## 参考文件
+
+| 文件 | 用途 |
+|------|------|
+| `security-checklist.md` | 安全与可靠性检查项 |
+| `code-quality-checklist.md` | 错误处理、性能、边界条件、并发检查项 |
+| `solid-checklist.md` | 架构与设计问题检查项 |
+| `removal-plan.md` | 冗余代码识别与删除计划模板 |
+| `scoring-guide.md` | 评分模型、区间规则和提交建议 |

package/src/code-review-skills/code-review/references/code-quality-checklist.md

@@ -0,0 +1,53 @@
+code# 代码质量检查项
+
+## 错误处理
+
+- 异常被 catch 后直接丢弃，没有重新抛出也没有实质处理
+- 捕获异常后只打 log，调用方无法感知失败，流程继续执行
+- async 函数没有 await，或 Promise 没有 catch，失败静默丢失
+- 降级逻辑掩盖了真实错误，让问题更难排查
+
+## 性能与缓存
+
+- 循环内部触发 N+1 query 或重复 I/O（每次迭代都查一次数据库）
+- 热路径上有高开销操作（序列化、反射、大对象创建）
+- cache key 缺少关键维度，导致不同请求拿到相同缓存数据
+- 集合或缓冲区无界增长，随时间或并发量线性膨胀
+
+## 边界条件
+
+- 访问 null/nil/undefined 前没有 guard check
+- 对空集合直接取第一个元素，或对空字符串做字符串操作
+- 存在除零风险（分母来自外部输入或计算结果）
+- off-by-one 错误：边界用 `<` 还是 `<=`，索引从 0 还是 1 开始
+- `0`、`false`、`""` 这类合法值被 falsy 判断误判为"无值"
+- 对整数范围的假设未校验（例如假设数值一定为正）
+
+## 资源管理
+
+- 连接、文件句柄、锁、数据库 session 没有在所有路径上释放（包括异常路径）
+- try-finally 或 with/defer 只覆盖了正常路径，异常路径漏掉了
+- 对象从容器中移除后，底层资源（连接池、文件描述符）仍然存活
+
+## 并发
+
+- 多线程/协程场景下读写共享可变状态，没有加锁或使用 atomic 操作
+- lazy initialization 没有考虑并发，可能被多次初始化
+- 回调或事件处理函数修改外部共享状态，没有同步保证
+
+## 测试
+
+- 测试只覆盖 happy path，没有覆盖异常、边界、空值场景
+- 断言过于宽泛，无法证明核心行为正确（例如只断言返回了某个类型）
+- 测试 setup 本身存在脆弱点（依赖外部状态、时序、全局变量）
+- 关键业务逻辑变更后，没有对应新增或更新测试
+
+## 排查思路
+
+审查时依次问自己：
+
+- 这里失败了，调用方能感知吗？错误会在哪里暴露？
+- 输入为空、为零、为空集合、超出范围或重复提交时，会发生什么？
+- 哪些逻辑在循环、重试或热路径中执行，是否引入了重复计算或额外 I/O？
+- 即使抛异常，哪些资源仍然必须被释放？
+- 如果某个疑点没有具体代码路径支撑，不作为正式问题输出。

package/src/code-review-skills/code-review/references/removal-plan.md

@@ -0,0 +1,45 @@
+# 冗余代码识别与删除计划
+
+## 可以立即删除
+
+适用条件：代码确认无用，且已通过引用搜索确认没有调用方。
+
+| 字段 | 内容 |
+|------|------|
+| **位置** | `path/to/file:line` |
+| **删除原因** | 无用代码 / 冗余分支 / 已被替代 |
+| **证据** | 无引用 / 路径失效 / 接口已过时 |
+| **影响范围** | 无 / 极低 |
+| **需要同步清理** | 相关测试、配置、文档 |
+| **删除后验证** | 跑哪些测试、检查哪些日志或监控指标 |
+
+## 暂不删除，制定计划
+
+适用条件：代码看起来可以删，但存在不确定因素（仍有调用方、需要迁移、归属不明确）。
+
+| 字段 | 内容 |
+|------|------|
+| **位置** | `path/to/file:line` |
+| **现在不能删的原因** | 仍有调用方 / 需要迁移 / 归属不清 |
+| **前置条件** | 删除前必须先完成什么 |
+| **迁移计划** | 安全的执行顺序（如：先新增替代实现 → 迁移调用方 → 删旧代码） |
+| **验证方式** | 用 `rg` 确认无引用 / 观察相关日志 / 检查监控指标 |
+| **回滚方案** | 出问题如何恢复 |
+
+## 删除前检查表
+
+- 用 `rg` 或等价工具搜索全部直接引用
+- 排查动态引用（反射、字符串拼接、配置文件中的类名/方法名）
+- 确认外部调用方（其他服务、脚本、CI/CD pipeline）不再依赖
+- 更新或删除相关测试
+- 更新相关文档和配置
+- 如果是对外接口，确认已完成 deprecation 通知和迁移窗口
+
+## 排查思路
+
+判断是否可以删除时，依次问自己：
+
+- 这段代码是真的无用，还是引用关系暂时没有找到（动态加载、反射、外部服务调用）？
+- 删除后，哪些运行路径、配置项、脚本或外部调用方会受影响？
+- 现在直接删，还是先补迁移计划？哪种风险更低？
+- 如果证据还不完整，不下"可以立即删除"的结论，改为制定计划。

package/src/code-review-skills/code-review/references/scoring-guide.md

@@ -0,0 +1,38 @@
+# 评分指南
+
+评分由**最严重的已确认问题**决定基准区间，再在区间内微调。
+
+## 第一步：确定基准区间
+
+| 最严重问题 | 分值区间 |
+|-----------|---------|
+| 无问题 | 9.0–10.0 |
+| 仅 P2/P3 | 7.5–9.0 |
+| P1 | 4.0–7.0 |
+| P0（crash、数据损坏） | 2.0–3.5 |
+| P0（安全漏洞、认证绕过） | 1.0–2.5 |
+
+## 第二步：在区间内调整
+
+- **影响广度**：影响所有用户取下限，仅边界场景触发取上限，差距约 0.5–1.0 分
+- **问题数量**：每多一个独立同级别问题，向下移约 0.3–0.5 分
+- **可逆性**：出问题后可以快速定位修复，可在区间内上浮 0.3–0.5 分
+
+> 多个问题时取区间下限附近；单个问题且影响有限时取区间上限附近。
+
+## 硬上限
+
+- 有任意 P0 → 评分上限 3.5
+- 核心功能完全失效 → 评分上限 2.5
+- 硬编码真实 credentials 或 secret 泄露 → 评分上限 2.0
+- 纯文件删除（无逻辑变更）→ 评分记为 N/A
+- 测试文件的问题 → 最高计为 P2，不纳入 P0/P1 计数
+
+## 评分语义
+
+| 分值 | 提交建议 | 含义 |
+|------|---------|------|
+| 9.0–10.0 | ✅ 可以提交 | 无明显问题 |
+| 7.5–9.0 | ✅ 可以提交，跟进修复 | 有轻微问题，不影响提交 |
+| 4.0–7.0 | 🔧 修复后提交 | 存在 P1 问题，影响广取下限，影响窄取上限 |
+| 1.0–3.5 | 🚫 禁止提交 | 存在 P0 问题，必须修复 |

package/src/code-review-skills/code-review/references/security-checklist.md

@@ -0,0 +1,53 @@
+# 安全与可靠性检查项
+
+## 输入输出安全
+
+- **Injection**：用户输入通过字符串拼接直接进入 SQL、NoSQL query、shell 命令或模板引擎，没有使用 parameterized query 或安全 API
+- **XSS**：未经 escape 的用户数据直接输出到 HTML，或通过 `innerHTML`/`dangerouslySetInnerHTML` 插入页面
+- **SSRF**：用户可控的 URL 被服务端直接发起请求，没有校验目标地址是否合法
+- **Path traversal**：用户输入拼接到文件路径，没有 canonicalize 和白名单校验
+- **ReDoS**：用户输入进入带有回溯风险的正则表达式，可能导致 CPU 占用飙升
+
+## 认证与授权
+
+- 新增的 API endpoint 或 route 没有经过认证中间件
+- 操作资源前没有校验资源归属当前用户（水平越权）
+- 接口直接信任客户端传来的 user_id、role、tenant_id 等身份字段，没有服务端验证
+- 存在 tenant 隔离缺失：A 租户的请求能查到 B 租户的数据
+
+## Credentials 与敏感数据
+
+- token、API key、密码、private key 硬编码在代码或配置文件中
+- log 中输出了完整请求/响应体，包含 credentials 或 PII
+- 敏感字段没有在序列化或日志输出时被 mask 或过滤
+
+## 运行时可靠性
+
+- 外部服务调用没有 timeout，可能导致请求一直挂起
+- 没有 retry 限制或 circuit breaker，外部故障会造成雪崩
+- 无界循环或递归，可能导致 CPU 耗尽或 stack overflow
+- 在请求主路径上执行阻塞 I/O（如同步读大文件），影响并发处理能力
+- 大批量数据一次性加载进内存，存在 OOM 风险
+
+## Race condition 与数据一致性
+
+- **check-then-act**：先判断条件再执行操作，中间没有加锁或原子操作保护，存在 TOCTOU 问题
+- 共享可变状态在多线程/多协程场景下没有同步控制
+- **read-modify-write**：先读取再修改再写回，没有事务或乐观锁保护，并发时会有数据覆盖
+- 重试机制可能导致操作重复执行，没有 idempotency 保证
+
+## 加密与序列化
+
+- 安全场景使用弱算法（MD5/SHA1 做密码 hash，ECB 模式加密）
+- IV 或 salt 硬编码或重复使用，破坏加密随机性
+- 直接 deserialize 不可信来源的数据（pickle、Java serialization、YAML.load），存在 RCE 风险
+- 加密数据没有 MAC/HMAC 做完整性校验，可能被篡改
+
+## 排查思路
+
+审查时依次问自己：
+
+- 这条数据从入口到落库或输出，中间有没有绕过校验、鉴权或过滤的路径？
+- 这次改动是否新开了 API 入口、新增了信任边界，或扩大了已有权限范围？
+- 如果输入异常、权限失效或外部系统不可用，系统会安全失败，还是会直接暴露风险？
+- 如果没有明确代码路径支撑，停止延伸，不作为正式问题输出。

package/src/code-review-skills/code-review/references/solid-checklist.md

@@ -0,0 +1,55 @@
+# 架构与设计检查项
+
+## SOLID 原则
+
+### SRP（单一职责）
+
+- 一个模块/类同时承担多个独立的变化原因（例如同时处理数据获取、业务规则和格式化输出）
+- 单个函数同时做校验、业务计算、持久化和通知，职责杂糅
+
+### OCP（开闭原则）
+
+- 新增一种场景需要修改核心逻辑，而不是通过新增实现或配置完成
+- 本应用 strategy/plugin 模式的地方，只能靠堆 if-else / switch 扩展
+
+### LSP（里氏替换）
+
+- 子类覆盖父类方法时，收紧了前置条件或放宽了后置条件，破坏了调用方的期望
+- 调用方需要用 `instanceof` 或类型判断来规避某个具体子类的异常行为
+
+### ISP（接口隔离）
+
+- 接口定义了超出调用方实际需要的方法，调用方被迫实现或依赖不需要的部分
+- 一个接口同时服务多个差异很大的使用场景，导致任何一方改动都影响所有人
+
+### DIP（依赖倒置）
+
+- 高层业务逻辑直接 `import` 或 `new` 底层实现（数据库、文件系统、第三方 SDK）
+- 存储层、网络层或框架细节渗透到核心业务逻辑中，替换底层时必须修改业务代码
+
+## 常见设计坏味道
+
+- **超长函数**：函数超过 50–80 行，或嵌套超过 3 层，很可能承担了太多职责
+- **数据泥团（Data Clump）**：多个参数总是一起出现，应该封装成一个对象
+- **依恋情结（Feature Envy）**：函数大量使用另一个类的字段，逻辑应该移过去
+- **基本类型偏执（Primitive Obsession）**：用 string/int 表示有明确业务含义的概念（如 userId、currency、status），应该引入明确类型
+- **散弹式修改（Shotgun Surgery）**：一个需求变化需要修改多处不相关的文件
+- **魔法值**：裸数字或字符串字面量，没有命名常量说明含义
+- **过度预设计**：为假想的未来需求引入抽象层，当前没有任何实际使用场景
+
+## 重构建议原则
+
+- 优先给出改动最小、风险可控的拆分方案
+- 说明调整后的边界为何更清晰，以及对现有调用方的影响
+- 改动较大时，给出分步方案（先拆接口 → 再迁移实现 → 再删旧代码）
+- 不建议整体重写，除非现有结构无法安全演进
+
+## 排查思路
+
+审查时依次问自己：
+
+- 这些职责为什么会落在同一个模块或函数里？是历史积累还是设计失误？
+- 如果再新增一种场景，现有结构是更容易扩展，还是更容易失控？
+- 调用方是否已经为了适配当前设计，写了额外的 workaround 逻辑？
+- 这次改动暴露的是局部实现问题，还是更上层的边界划分问题？
+- 如果判断不能落到具体调用关系、边界混乱点或新增改动带来的实际影响上，不作为正式问题输出。