/.github/copilot-instructions.md

GitHub Copilot Code Review 指导

基础规则

1. Code Review 评论内容请使用中文
2. 专注于提供有价值、可操作的建议，避免指出显而易见的问题

CR 优先级框架

🔴 高优先级（必须评论）

• 安全问题：输入验证、SQL 注入、XSS、权限控制等
• 性能问题：算法复杂度过高、内存泄漏、不必要的循环等
• 关键逻辑错误：业务逻辑缺陷、边界条件处理不当
• 架构一致性：违反项目架构模式、模块职责不清
• TypeScript 类型安全：类型滥用、any 类型的不当使用

🟡 中优先级（建议评论）

• API 设计：接口一致性、参数设计、返回值结构
• 错误处理：异常处理不完整、错误信息不清晰
• 代码可读性：复杂的业务逻辑需要更好的注释或重构
• 测试质量：测试覆盖率不足、测试用例设计不合理

🟢 低优先级（避免评论）

• 格式问题：缩进、空格、换行等（应由自动化工具处理）
• 命名风格：除非严重影响理解
• 个人编码偏好：不影响功能实现的习惯性写法

项目特定指导

MCP 协议实现

• 关注 MCP 消息处理的正确性和完整性
• 检查传输适配器的错误处理和重连机制
• 验证工具调用和资源管理的生命周期

TypeScript 最佳实践

• 优先使用具体的类型而非 any
• 鼓励使用类型推导和泛型
• 检查接口设计的一致性和向后兼容性

模块化架构

• 验证模块间的依赖关系是否合理
• 检查单一职责原则的遵循
• 确保依赖注入容器的正确使用

测试策略

• 重点检查集成测试和端到端测试
• 验证异步代码的正确测试
• 关注测试的可维护性和可读性

评论质量标准

✅ 好的评论应该

1. 解释原因：说明为什么需要这个改动
2. 提供方案：给出具体的修改建议
3. 考虑影响：说明改动可能对其他部分的影响
4. 示例代码：在需要时提供代码示例

❌ 避免的评论类型

1. 仅指出问题："这里有问题"、"这样不好"
2. 模糊建议："建议重构"、"优化一下"
3. 过度建议：针对边缘案例的过度设计
4. 风格偏好：个人习惯相关的评论

评审结论指引

✅ 评审通过

如果代码没有明显问题，符合项目要求，在 PR 中显著地用中文评论：

## ✅ 代码评审通过，允许合并

代码改动符合项目要求，可以合并。

评审通过的标准

• 代码功能正确，无明显 bug
• 符合项目的代码风格和质量要求
• 无高优先级或中优先级的安全问题
• 错误处理完善
• 测试覆盖合理

技术债务关注点

可维护性

• 代码重复
• 过长的函数或类
• 深层嵌套的复杂逻辑

可扩展性

• 硬编码的配置和常量
• 缺乏抽象的重复代码
• 紧耦合的组件设计

可测试性

• 难以测试的代码结构
• 过多的外部依赖
• 缺乏依赖注入

具体示例

好的评论示例

🔴 **安全问题**：这个函数直接使用用户输入构建 SQL 查询，存在 SQL 注入风险。

建议：使用参数化查询或 ORM 的查询构建器来避免 SQL 注入。

```typescript
// 当前代码（不安全）
const query = `SELECT * FROM users WHERE name = '${userName}'`;

// 建议改为
const query = 'SELECT * FROM users WHERE name = ?';
db.query(query, [userName]);

### 应该避免的评论

❌ "这个函数太长了"（没有具体建议） ❌ "变量名应该用 camelCase"（自动化工具应处理） ❌ "建议用 async/await"（没有说明具体收益）

## 上下文理解

1. **理解改动目的**：在评论前先理解这个 PR 的目标
2. **考虑整体影响**：不要只关注局部代码片段
3. **平衡建议**：在完美主义和实用性之间找到平衡
4. **尊重设计决策**：除非有明确问题，否则尊重现有的架构选择

## CR 范围控制

### 聚焦 PR 本身改动

- **专注于 PR 改动范围**：只分析本次 PR 修改的代码，不要扩大审查范围到未改动的代码
- **只分析改动本身**：评估改动代码本身是否有需要改进的地方
- **关注必要的潜在问题**：识别真正影响功能和安全的问题，避免过度延伸
- **不审查历史代码**：不要借机审查 PR 范围之外的代码，即使发现问题也只提醒不强制要求修复

### 范围控制原则

- 如果发现 PR 之外的代码有问题，可以简单提及但不应作为评审重点
- 不要求 PR 作者在当前改动中解决所有历史技术债务
- 保持评审焦点在本次改动的质量和正确性上

## 务实开发原则

### 核心原则

- **如无必要勿增实体**：需要什么功能就实现什么功能
- **功能驱动**：优先解决实际问题，不过度设计
- **优雅实现**：代码清晰、可维护、结构合理
- **避免过度设计**：
  - 不要为了"未来可能需要"而增加复杂度
  - 不要为了理论完美而过度抽象
  - 不要在没有性能问题时优化性能
  - 不要为了使用设计模式而使用

### 何时考虑复杂设计

- 实际遇到问题时
- 功能明确需要时
- 代码确实难以维护时
- 团队协作需要统一接口时

### CR 中的务实原则

- 评估代码是否增加了不必要的复杂性
- 验证功能实现是否符合"如无必要勿增实体"
- 确保代码优雅但不过度设计
- 验证架构合理性但不冗余
- 避免要求添加"未来可能用到"的功能

通过遵循这些指导，Copilot 将提供更有价值、更符合人类标准的 Code Review。