Skip to content

三层架构与维护原则.md

Latest commit

 

History

History
158 lines (107 loc) · 6.55 KB

三层架构与维护原则.md

File metadata and controls

158 lines (107 loc) · 6.55 KB
Raw

三层架构与维护原则

本文记录 NewLife.Skills 仓库当前实际采用的资产组织方案，以及维护原则，是资产治理的落地依据。

1. 三层架构

层级 载体 内容 维护成本 触发方式
Tier 1 NuGet 包的 XML 注释 类与成员的「如何使用」、示例代码 跟代码一起维护 AI 自动跳转/查看
Tier 2 全局 copilot-instructions.md + 少量专用 instructions/ NewLife 反常规约定（硬约束） 集中维护 全局生效 / 关键词触发
Tier 3 skills/ + agents/ 流程类、架构决策类、跨组件取舍 仅必要项 skill 按需加载 / agent 用户 @ 调用

1.1 Tier 1 是最高杠杆

用户原话：AI 通过 NuGet 包的 XML 注释就知道怎么用 CsvFile，根本不需要 skill。

XML 注释相对 skill 的优势：

  • 跟版本走：随 NuGet 包发布，不会过期
  • 跨项目自动可用：任何引用方都能读，无需额外安装
  • AI 自动发现：跳转定义即得，无需关键词触发
  • 对人类同样有效：IntelliSense 直接展示

因此 NewLife 核心库必须把"用法"沉淀到 XML 注释里，包括：

  • 每个 public 类型：<summary> 一句话定位 + <remarks> 段落（适用/不适用场景）
  • 主入口/常用类：至少一个 <example> 代码块
  • 易混淆 API：<seealso> 互相指引（如 Pool.StringBuilder ↔ StringBuilder）
  • 反常规设计：<remarks> 解释「为什么这样」

1.2 Tier 2 只放硬约束

只放 AI 看代码也猜不到 的 NewLife 反常规约定：

  • 必须用 String 不用 string
  • 私有字段必须 _camelCase
  • 防御性注释禁止删除
  • 优先 Pool.StringBuilder / Runtime.TickCount64 / SpanReader
  • <summary> 必须同行闭合

不放：API 用法说明、组件功能索引、技能/智能体清单（容易过期）。

1.3 Tier 3 只保留流程/架构类

只保留满足以下任一条件的 skill：

  • 多步骤流程（如月度发版准备）
  • 架构决策（如分库分表选型、两层/三层架构选择）
  • 跨多个组件的取舍（如序列化方案对比，但本仓库已剔除——可由 XML + 通用知识承担）
  • NewLife 专属、AI 必然不知道的非平凡用法（如 Model.xml 设计约定）

2. 搬运型禁止原则

判定标准：如果不读这个 skill，AI 也能给出大体相同的回答（即内容来自通用知识或 XML 注释），这个 skill 就是「搬运型」，没有存在价值，应当删除。

典型反面案例（已删除）：

  • frontend-* 12 个：通用前端最佳实践，AI 训练数据覆盖充分
  • caching / serialization / security / type-conversion 等：把 NewLife 类的 XML 注释抄了一遍
  • *-architecture 中与 *-usage 重复的部分

3. 加载标注（可验证性）

全局 instructions 强制要求：每次回答开头第一行必须输出

> 📋 **生效**: instructions=[xxx,yyy] | skills=[xxx] | agent=xxx

这是解决"不知道有没有生效"的最简单机制。用户肉眼即可验证：

  • 命中关键词却没加载 → 回到 instructions 第 1 节补关键词
  • 屡次补关键词仍不准 → 说明 skill 本身没必要

4. 30 天淘汰制

周期 动作
每天 关注「生效」标注，发现该加载未加载的资产
每周 检查近 7 天加载频次，零触发资产打标
每 30 天 连续 30 天零触发的 skill / instructions 删除或合并
每次发版 检查公共 API XML 注释完整性（Tier 1 巩固）

5. 资产维护流程

新需求出现
    │
    ├─► 能加 XML 注释解决？  ──► 改核心库源码（Tier 1，首选）
    │
    ├─► 是 NewLife 反常规约定？──► 改 copilot-instructions.md（Tier 2）
    │
    ├─► 是关键词强相关的深度规范？──► 加专用 instructions（Tier 2 补充）
    │
    ├─► 是多步流程或架构决策？──► 加 skill（Tier 3）
    │
    └─► 是固定的多步工作？      ──► 加 agent（Tier 3）

反向流程（清理）：

某 skill 30 天未触发
    │
    ├─► 内容能由 XML 注释承担？──► 回迁到核心库注释，删除 skill
    │
    ├─► 内容能由全局 instructions 承担？──► 合并到全局，删除 skill
    │
    └─► 都不能？──► 改进触发关键词，再观察 30 天

6. 当前资产清单

完整资产清单（全局指令 / 专用指令 / skills / agents / prompts）以仓库 README.md 为唯一事实源，本文件不再重复维护，避免多处清单漂移。新增或删除资产后，运行 scripts/verify-assets.ps1 校验 README 与磁盘一致。

7. 演进历史

阶段 资产规模 问题
单一 instructions 时代 1 全局 + 几个子级 简单可控，是 baseline
大爆发期 71 skill + 9 instructions + 7 agent 触发不透明、搬运重复、难维护
当前 8 skill + 3 instructions + 8 agent + 1 prompt 三层职责清晰、可验证、可淘汰

下一步聚焦 Tier 1：在 NewLife 核心库（NewLife.Core / NewLife.XCode / NewLife.Cube / NewLife.Redis / NewLife.Net 等）补全 XML 注释质量基线。

8. 资产创建与校验

8.1 创建或修改资产

  • 定制文件语法（frontmatter、applyTo、tools、description 发现机制）参考 VS Code 内置 agent-customization 技能或官方文档 https://code.visualstudio.com/docs/copilot/customization/overview，本文不复述通用语法。
  • 该不该新增：先用第 1 节三层架构与第 2 节搬运型禁止判定。能由 XML 注释或全局 instructions 承担的，不新增 skill。
  • 专用指令必须含 description（关键词丰富，供 on-demand 自动发现）；与对应 skill 内容单一归属，避免重复维护——如 Model.xml 属性表只放 xcode-data-modeling skill，xcode.instructions.md 仅保留触发入口、运行时约定与一个范例。

8.2 校验一致性

新增、删除或重命名任何资产后，运行：

powershell -File scripts\verify-assets.ps1

脚本校验：①每个资产 frontmatter 合规（skill 的 name 必须等于目录名）；②README 资产清单与磁盘双向一致（漏登记、列了不存在的都会报错）。发现问题以非零退出码结束，可纳入 CI。README.md 是人类可读的唯一事实源，verify 脚本是防漂移的机器保障。