# NewLife Copilot 协作指令 本说明适用于新生命团队（NewLife）及其全部开源 / 衍生项目。本指令用于规范在这些项目中使用 Copilot（及类似智能助手）时的行为，主要面向 C# / .NET 技术栈。 ## 1. 目标 - 提效：减少机械样板劳动，聚焦业务/核心算法。 - 一致：风格、结构、命名、API 行为稳定。 - 可控：限制改动影响面、可审计、兼容友好、不引入隐患。 - 可靠：避免虚构、保持性能、不破坏现有合约。 ## 2. 适用范围 - 含 NewLife 组件或其衍生的全部 C# / .NET 仓库。 - 不含纯前端 / 非 .NET / 市场文案。 - 存在本文件 → 必须遵循；缺失可引入。 ## 3. 角色与职责 - 开发者：提出清晰需求（功能/缺陷/性能/重构/文档）。 - Copilot：先检索再生成；输出必要且影响面受控的改动；不虚构；简体中文回复。 - 审核关键点：公共 API、一致性、性能影响。 ## 4. 工作流 1) 需求分类 → 功能 / 修复 / 性能 / 重构 / 文档 2) 检索 → 相关类型、目录、方法、已有扩展/工具 3) 评估 → 是否公共 API / 是否性能热点 4) 设计 → 列出改动点 + 兼容/降级策略 5) 实施 → 局部编辑，限制改动影响面；保留原注释与结构 6) 验证 → 通过编译；自动运行与本次改动相关的单元测试；若未发现任何相关测试，在结果中明确说明；不得自动新增测试项目 7) 说明 → 变更摘要 / 影响范围 8) 提交 → 统一格式，整理中文提交日志；禁止夹带无关格式化 ## 5. 编码规范 - 语言：`<LangVersion>latest</LangVersion>`，使用最新C#语法特性。 - 命名：类型/公共成员 PascalCase；参数/局部 camelCase；私有字段 `_xxx`（且字段应紧邻其对应的属性之前，见下述“就近规则”）。 - 类型名用 .NET 正式名（`String`/`Int32`），避免别名。 - 单行 if：仅单语句同一行；多分支单语句不加花括号。 - 循环（`for/foreach/while/do`）即使循环体当前只有单一语句，也必须保留 `{}` 花括号（除非原始代码本就无括号），避免未来增量导致隐藏逻辑或合并冲突；禁止为所谓“简洁”而移除。 - 每文件一个主要公共类型；平台差异使用 `partial`。 - 忌全量重排、无差异格式化提交。 - Linq、反射仅用于非高频路径；热点使用手写循环/缓存。 - 使用 file-scoped namespace。 - 禁止擅自删除已有代码注释（含单行 // 与 XML 文档注释），可以修改或追加；禁止单独“清理”一片注释块或仅删除空白行来制造差异。 - 不得仅为对齐或所谓美观批量移除、合并空白行；保留有意的逻辑分隔空行。仅在同一局部有真实代码增删且需要保持统一时才可适度调整。 ### 5.1 可读性优先（就近） - 局部变量就近声明：在首次使用前的最近位置声明，避免集中在方法开头。 - 字段紧邻属性：私有字段命名 `_xxx`，并紧贴使用它的属性之前，减少跨距阅读。 - 按用途放置字段：若某私有字段仅被单一方法使用（如 `TimerX _timer`），优先放在该方法之前；若被多方法共享，则集中放在 `#region 属性` 段的末尾，便于统一浏览与维护。 - 成组排布：相关成员按依赖顺序成组摆放，降低跳转成本。 - 合理例外：如会导致重复声明、闭包捕获或影响性能/生命周期，可权衡位置并加简短注释。 冲突时以“易读易懂”为先。 ### 5.2 现代 C# 语法偏好（优先） - 使用 switch 表达式与模式匹配（含 relational、logical、property/positional patterns）。 - 使用集合表达式与简化初始化（C# 12）：`[]`、`[..spread]`、`"key" => value`。 - 使用目标类型 new、文件作用域命名空间、`init`/`required` 成员、record/record struct。 - 使用插值原始多行字符串与 `using var` 声明减少样板代码。 示例（简洁优先）： ```csharp // 文件作用域命名空间 namespace Demo; public readonly record struct User(string Name, int Age); static string Describe(int code) => code switch { 200 => "OK", >= 400 and < 500 => "ClientError", >= 500 => "ServerError", _ => "Other" }; // 集合表达式（C# 12） var baseList = [1, 2, 3]; List<int> list = [..baseList, 4]; Dictionary<string, int> map = ["a" => 1, "b" => 2]; // 目标类型 new 与 using 声明 using var ms = new MemoryStream(); List<User> users = []; ``` ## 6. 文档注释 - `public` / `protected` 必须具备注释：`<summary>` 单行简洁；详细描述放 `<remarks>`；补充 `<param>` `<returns>`。 - `<summary>` 与 `</summary>` 必须在同一行，示例：`<summary>开始服务</summary>`；除非内容确需多段落，非必要不得使用三行（上下各独立）格式。 - 示例可裁剪；避免泄露密钥、真实内部地址。 - `[Obsolete]` 成员必须含迁移建议。 - 中文优先，必要时补精简英文（同一 `<remarks>`）。 ## 7. 异步与性能 - 异步方法后缀 `Async`；禁止伪异步包装。 - 库内部默认 `ConfigureAwait(false)`。 - 高频路径优先：对象池 / `ArrayPool<T>` / `Span`；避免多余分配与装箱。 - 禁止在热点引入未缓存反射 / 动态 / 复杂 Linq。 - 池化资源：明确获取/归还；异常分支不遗失归还。 ## 8. 日志与追踪 - 支持注入：`ILog Log`，可选 `ITracer Tracer`。 - 关键过程建 Tracer?.NewSpan 埋点；异常标记错误标签。 ## 9. 错误处理 - 精准异常类型；避免未处理直接 `throw;`。 - 参数校验：空 / 越界 / 格式。 - 不用异常作常规分支 → 提供 `TryXxx`。 - 对外异常信息不含内部实现/路径。 - 类型转换优先现有扩展：`ToInt` / `ToBoolean` 等。 ## 10. 测试 - 框架：xUnit；命名 `{ClassName}Tests`。 - `[DisplayName]` 中文描述意图；断言语义清晰。 - IO 用临时目录；端口用 0 / 随机。 - 覆盖：正常 / 边界 / 异常 / 并发竞争（必要时）。 - 性能敏感代码：最小基准验证或引用基线结果（不伪造数据）。 - 选择性执行：默认仅运行与改动相关的测试；优先在当前解决方案中检索 `{ClassName}` 的引用，若引用落入单元测试（测试项目或测试目录）则运行这些测试；若未命中，再在解决方案内查找 `{ClassName}Tests.cs`（如 `SpanReader` ↔ `SpanReaderTests.cs`）。 - 未发现相关测试：在结果中明确说明“未匹配到相关测试”，且不自动创建/引入测试项目。 ## 11. Copilot 使用守则 - 仅回答开发相关；非开发 → “我是编程助手”。 - 输出前检索；禁止重复造轮子。 - 不生成超出需求的大块模板，先列方案再实现。 - 不新增外部依赖（除非说明内置不足并给出权衡）。 - 遇不确定上下文 → 标记“需查看文件”。 - 不伪造：测试结果 / 性能数据 / 外部调用。 - 回答或修改代码时，不得移除已有注释文本，可以修改或追加；不得单独删除整段注释或仅删除空白行制造“格式优化”式提交。 - 进行循环、控制流结构调整时，若原代码含循环花括号（即便单语句体），须保留，不得擅自移除。 - 修改或提交代码后，需自动在本地运行与改动相关的单元测试并确保通过；若无法定位相关测试，再运行最小必要集合或全部；若未找到任何测试，需在结果中明确说明且不自动新增测试项目。 - 生成文档：未特别指明时，默认以 Markdown（.md）格式输出，并使用 UTF-8 编码。 ## 12. 变更与审核说明 提交或答复需包含： - 概述：做了什么 / 为什么 - 影响：公共 API？性能？ - 兼容：降级策略 / 条件编译点 - 风险：潜在回归 / 性能开销 - 后续：是否补测试 / 文档 ## 13. 禁止清单 - 虚构 API / 文件 / 类型 - 未检索即重写或重复实现 - 擅自删除公共 / 受保护成员 - 引入重复第三方功能库 - 伪造测试/性能数据 - 在热点路径添加高分配 LINQ/反射（无缓存） - 输出敏感凭据/内部地址 - 未审计第三方片段直接贴入 - 将非确定性行为直接断言（时间/随机）不隔离 - 强行异步化纯同步逻辑 - 大面积格式化无业务价值 - 擅自删除已有代码注释 - 仅删除或合并空白行以制造“变化” - 删除已有 `for/foreach/while/do` 单行循环体的花括号 ## 14. 术语说明 - 热点路径：经性能分析或高频调用栈确认的关键执行段。 - 基线：变更前的功能/性能参考数据。 --- （完）