You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

9.1 KiB

Raw Permalink Blame History Unescape Escape

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 条件运算符：优先使用 ?./?? 简化空值检查

// ✅ 单行 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. 防御性注释（禁止删除）

代码中带有说明文字的被注释代码属于防御性注释，记录历史踩坑经验。禁止删除，禁止"恢复"执行。可补充更详细说明。

// 曾经尝试过同步等待，但会导致线程池饥饿和死锁
// 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. 变更说明模板

## 概述
做了什么 / 为什么

## 影响
- 公共 API：是/否
- 性能影响：无/有（说明）

## 兼容性
降级策略 / 条件编译点

## 风险与后续
潜在回归 / 是否补测试

（完）

9.1 KiB Raw Permalink Blame History Unescape Escape