|
|
# NewLife Copilot 协作指令
|
|
|
|
|
|
适用于新生命团队（NewLife）全部 C#/.NET 仓库。存在本文件则必须遵循。**简体中文回复。**
|
|
|
通用 C# 最佳实践（设计模式、SOLID、健壮性等）AI 已知，此处不赘述，**仅列出组织专属规则与反常规约定**。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 1. 专用指令（前置检查，必须执行）
|
|
|
|
|
|
**开始任何任务前，必须先将用户请求与下表触发信号逐行匹配。命中则立即用 `get_file` 读取 `.github/instructions/{指令文件}`，读取成功后遵循其中全部规则。未命中任何行才跳过。**
|
|
|
|
|
|
| 触发信号（用户请求含以下任意关键词即命中） | 指令文件 |
|
|
|
|---------|---------|
|
|
|
| XCode/实体生成/Model.xml/数据库 CRUD/`NewLife.XCode` 引用/`*.xcode.xml`/项目名含 `.Data`/`XCode.*` 命名空间/用户提及修改任意 `.xml` 文件 | `xcode.instructions.md` |
|
|
|
| Cube/魔方/Web开发/`NewLife.Cube` 引用/`NewLife.Cube.*` 命名空间 | `cube.instructions.md` |
|
|
|
| 性能测试/基准测试/压力测试/压测/BenchmarkDotNet/Benchmark/benchmark/吞吐量评估/性能分析/性能对比/性能报告/速度对比/速度测试/内存分配/perf/性能优化测试/做性能/跑分/测试报告 | `benchmark.instructions.md` |
|
|
|
| NetServer/NetSession/网络服务器/网络客户端/Socket服务/TCP服务/UDP服务/`NewLife.Net` 引用/`NewLife.Net.*` 命名空间/ISocketClient/ISocketRemote/CreateRemote/StandardCodec/LengthFieldCodec/管道编解码/网络编程/Echo服务/网络会话/长连接/粘包拆包 | `net.instructions.md` |
|
|
|
| 新建系统/新建项目/新增模块/需求整理/需求文档/需求分析/架构设计/技术方案/功能清单/功能拆分/任务分解/迭代开发/迭代计划/验收/PRD/用户故事/做一个系统/做一个平台/开发流程/全部搞完/批量开发/自治模式/一次性做完/继续处理/接着做 | `development.instructions.md` |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 核心原则
|
|
|
|
|
|
检索优先、风格一致、兼容友好、**主动优化**。
|
|
|
发现明显缺陷（资源泄漏、空引用、逻辑错误）时主动修复；优化请求时深入分析，不做表面工作。
|
|
|
改动较小直接做并说明；改动较大（涉及公共 API 或大范围重构）先列方案询问确认。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 兼容性约束（极重要）
|
|
|
|
|
|
NewLife 核心库支持 `.NET 4.5` 至最新版本（`net45` → `net10`）。
|
|
|
|
|
|
- **语言版本**：`<LangVersion>latest</LangVersion>`，最大化使用最新 C# 语法糖（switch 表达式、集合表达式 `[]`、`?.`/`??`、模式匹配、目标类型 `new`、record 等）
|
|
|
- **禁止高版本专属 BCL API**：❌ `ArgumentNullException.ThrowIfNull()` → ✅ `if (x == null) throw new ArgumentNullException(nameof(x));`
|
|
|
- **条件编译符号**：`NETFRAMEWORK`、`NETSTANDARD2_0`、`NETCOREAPP`、`NET5_0_OR_GREATER`、`NET6_0_OR_GREATER`、`NET8_0_OR_GREATER`
|
|
|
- 新增 API 需评估各框架兼容性，必要时提供条件编译降级实现
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 编码规范
|
|
|
|
|
|
### 4.1 类型名（关键差异）
|
|
|
|
|
|
**必须**使用 .NET 正式名：`String`/`Int32`/`Boolean`/`Int64`/`Double`/`Object` 等。
|
|
|
❌ **禁止**使用 C# 别名：`string`/`int`/`bool`/`long`/`double`/`object`
|
|
|
|
|
|
### 4.2 命名
|
|
|
|
|
|
| 成员类型 | 规则 | 示例 |
|
|
|
|---------|------|------|
|
|
|
| 类型/公共成员 | PascalCase | `UserService`、`GetName()` |
|
|
|
| 参数/局部变量 | camelCase | `userName`、`count` |
|
|
|
| 私有字段 | `_camelCase` | `_cache`、`_instance` |
|
|
|
| 扩展方法类 | `xxxHelper` 或 `xxxExtensions` | `StringHelper`、`CollectionExtensions` |
|
|
|
|
|
|
### 4.3 代码风格
|
|
|
|
|
|
- **命名空间**：file-scoped namespace
|
|
|
- **单文件**：每文件一个主要公共类型；较大平台差异使用 `partial`
|
|
|
- **集合初始化**：优先使用集合表达式 `[]`，如 `List<String> Tags { get; set; } = [];`
|
|
|
- **Null 条件运算符**：优先使用 `?.`/`??` 简化空值检查
|
|
|
|
|
|
```csharp
|
|
|
// ✅ 单行 if：单语句且整行不过长时同行
|
|
|
if (value == null) return;
|
|
|
if (key == null) throw new ArgumentNullException(nameof(key));
|
|
|
|
|
|
// ✅ 语句较长时另起一行，仍不加花括号
|
|
|
if (value == null)
|
|
|
throw new ArgumentNullException(nameof(value), "Value cannot be null");
|
|
|
|
|
|
// ✅ 多分支单语句：不加花括号
|
|
|
if (count > 0)
|
|
|
DoSomething();
|
|
|
else
|
|
|
DoOther();
|
|
|
|
|
|
// ✅ 循环必须保留花括号（即使单语句）
|
|
|
foreach (var item in list)
|
|
|
{
|
|
|
Process(item);
|
|
|
}
|
|
|
|
|
|
// ✅ using 优先无花括号声明；仅需生命周期（如锁）时用弃元
|
|
|
using var stream = File.OpenRead("file.txt");
|
|
|
using var _ = _lock.AcquireLock();
|
|
|
```
|
|
|
|
|
|
### 4.4 Region 与日志
|
|
|
|
|
|
较长类使用 `#region` 分段，顺序：`属性` → `静态` → `构造` → `方法` → `辅助` → **`日志`**。
|
|
|
含 `ILog Log` 和 `WriteLog` 时：**必须放类末尾**，用名为"日志"的 region 包裹，不放入"辅助"。
|
|
|
关键过程可使用 `Tracer?.NewSpan()` 埋点。
|
|
|
|
|
|
### 4.5 文档注释
|
|
|
|
|
|
- `<summary>` **必须同行闭合**：`/// <summary>获取名称</summary>`
|
|
|
- 每个参数**必须有** `<param>` 标签，无论方法可见性
|
|
|
- 有返回值**必须有** `<returns>`；复杂方法可增加 `<remarks>`
|
|
|
- `public`/`protected` 成员必须注释；`[Obsolete]` 必须包含迁移建议
|
|
|
|
|
|
### 4.6 异步与性能
|
|
|
|
|
|
- 异步方法后缀 `Async`，库内部默认 `ConfigureAwait(false)`
|
|
|
- 热点路径避免反射/复杂 Linq，优先手写循环/`ArrayPool<T>`/`Span`
|
|
|
- 池化资源明确获取/归还，异常分支不遗失归还
|
|
|
|
|
|
### 4.7 错误处理
|
|
|
|
|
|
- 精准异常类型：`ArgumentNullException`/`InvalidOperationException` 等
|
|
|
- TryXxx 模式：不用异常作常规分支
|
|
|
- 类型转换：优先使用 `ToInt()`/`ToBoolean()` 等扩展方法
|
|
|
- 对外异常不暴露内部实现/路径
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. NewLife 内置工具
|
|
|
|
|
|
优先使用项目内置工具而非标准库，**禁止重复造轮子**：
|
|
|
|
|
|
- 字符串构建：`Pool.StringBuilder`（替代 `new StringBuilder()`）
|
|
|
- 时间戳：`Runtime.TickCount64`
|
|
|
- 类型转换：`ToInt()`、`ToBoolean()`、`ToDouble()`、`ToDateTime()` 等扩展方法
|
|
|
- 追踪埋点：`Tracer?.NewSpan()`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 防御性注释（禁止删除）
|
|
|
|
|
|
代码中带有说明文字的被注释代码属于**防御性注释**，记录历史踩坑经验。**禁止删除，禁止"恢复"执行**。可补充更详细说明。
|
|
|
|
|
|
```csharp
|
|
|
// 曾经尝试过同步等待，但会导致线程池饥饿和死锁
|
|
|
// var result = task.Result;
|
|
|
|
|
|
// 不要使用 SendAsync 的无超时重载，否则会造成连接泄漏
|
|
|
// await client.SendAsync(data);
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 工作流
|
|
|
|
|
|
触发检查（第 1 节触发信号表匹配，命中则读取专用指令） → 检索（**优先复用**现有实现） → 评估（公共 API/兼容性/性能） → 方案 → 实施 → 验证 → 说明
|
|
|
|
|
|
- **触发检查**：开始工作前必须完成，遗漏专用指令将导致输出不符合要求
|
|
|
- **实施**：完成主任务；顺带修复明显缺陷；顺带简化重复代码；保留原注释与结构
|
|
|
- **验证**：代码变更必须编译通过；找到相关测试则运行；仅文档变更可跳过
|
|
|
|
|
|
### 主动优化原则
|
|
|
|
|
|
用户要求**分析/优化代码**时：
|
|
|
|
|
|
| 行动 | 说明 |
|
|
|
|------|------|
|
|
|
| **架构梳理** | 重构不清晰的结构，让代码更易懂 |
|
|
|
| **缺陷修复** | 资源泄漏、空引用、并发问题、逻辑错误 → 直接修复 |
|
|
|
| **代码简化** | 提取重复代码、合并冗余判断、应用现代语法 |
|
|
|
| **性能优化** | 缓存重复计算、池化高频对象、避免无用分配 |
|
|
|
| **注释完善** | 补充缺失的 XML 注释和关键逻辑说明 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. 测试
|
|
|
|
|
|
- 框架 xUnit；类名 `{ClassName}Tests`；方法加 `[DisplayName("中文描述意图")]`
|
|
|
- 网络端口用 `0`/随机，IO 用临时目录
|
|
|
- 先搜索 `{ClassName}` 引用定位测试文件，再找 `{ClassName}Tests.cs`；**未找到需说明**，不自动创建测试项目
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. 文档与发布
|
|
|
|
|
|
### Markdown 文档
|
|
|
|
|
|
UTF-8 无 BOM；存放 `Doc/` 目录；文件名优先中文。**已有文件必须先读取再增量修改，禁止覆盖。**
|
|
|
|
|
|
### NuGet 版本
|
|
|
|
|
|
| 类型 | 格式 | 示例 |
|
|
|
|------|------|------|
|
|
|
| 正式版 | `{主}.{子}.{年}.{月日}` | `11.9.2025.0701` |
|
|
|
| 测试版 | `{主}.{子}.{年}.{月日}-beta{时分}` | `11.9.2025.0701-beta0906` |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 10. 重要禁止项
|
|
|
|
|
|
以下是 AI 容易犯但在本项目影响严重的错误：
|
|
|
|
|
|
- 将 `String`/`Int32` 改为 `string`/`int`（本项目反 C# 惯例，**必须用正式名**）
|
|
|
- 删除防御性注释（带说明的注释代码）
|
|
|
- 删除循环体的花括号
|
|
|
- 将 `<summary>` 拆成多行
|
|
|
- 擅自删除 `public`/`protected` 成员
|
|
|
- 擅自新增外部 NuGet 依赖（需说明理由）
|
|
|
- 仅删除空白行/注释制造"格式优化"提交
|
|
|
- 虚构不存在的 API/文件/类型
|
|
|
- 伪造测试结果/性能数据
|
|
|
- 在热点路径添加未缓存反射/复杂 Linq
|
|
|
- 输出敏感凭据/内部地址
|
|
|
- 发现问题却视而不见
|
|
|
- 用户要求优化时仅做注释/测试等表面工作
|
|
|
- **跳过第 1 节触发检查**（命中关键词却未加载专用指令文件，是最严重的遗漏错误）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 11. 变更说明模板
|
|
|
|
|
|
```markdown
|
|
|
## 概述
|
|
|
做了什么 / 为什么
|
|
|
|
|
|
## 影响
|
|
|
- 公共 API：是/否
|
|
|
- 性能影响：无/有（说明）
|
|
|
|
|
|
## 兼容性
|
|
|
降级策略 / 条件编译点
|
|
|
|
|
|
## 风险与后续
|
|
|
潜在回归 / 是否补测试
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
（完）
|