283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# .NET开发技能插件
|
||
|
||
`dotnet` `Claude Code` `插件` `C#` `Akka.NET`
|
||
|
||
# Claude Code 的 .NET 技能插件
|
||
|
||
一个功能全面的 Claude Code 插件，包含 **30 个技能** 和 **5 个专业智能体**，专为专业 .NET 开发而设计。涵盖 C#、Akka.NET、Aspire、EF Core、测试和性能优化等领域，均为来自生产系统的经过实战验证的模式。
|
||
|
||
## 安装
|
||
|
||
本插件支持多种支持技能/智能体功能的 AI 编程助手。
|
||
|
||
### Claude Code（CLI）
|
||
|
||
[官方文档](https://code.claude.com/docs/en/discover-plugins)
|
||
|
||
在 Claude Code CLI（终端应用，非 VSCode 扩展）中运行以下命令：
|
||
|
||
```
|
||
/plugin marketplace add Aaronontheweb/dotnet-skills
|
||
/plugin install dotnet-skills
|
||
```
|
||
|
||
更新方式：
|
||
```
|
||
/plugin marketplace update
|
||
```
|
||
|
||
### GitHub Copilot
|
||
|
||
[官方文档](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
|
||
|
||
将技能克隆或复制到项目或全局配置中：
|
||
|
||
**项目级别**（推荐）：
|
||
```bash
|
||
# 克隆到项目的 .github/skills/ 目录
|
||
git clone https://github.com/Aaronontheweb/dotnet-skills.git /tmp/dotnet-skills
|
||
cp -r /tmp/dotnet-skills/skills/* .github/skills/
|
||
```
|
||
|
||
**全局**（适用所有项目）：
|
||
```bash
|
||
mkdir -p ~/.copilot/skills
|
||
cp -r /tmp/dotnet-skills/skills/* ~/.copilot/skills/
|
||
```
|
||
|
||
### OpenCode
|
||
|
||
[官方文档](https://opencode.ai/docs/skills)
|
||
|
||
```bash
|
||
git clone https://github.com/Aaronontheweb/dotnet-skills.git /tmp/dotnet-skills
|
||
|
||
# 全局安装（目录名必须与 frontmatter 的 'name' 字段匹配）
|
||
mkdir -p ~/.config/opencode/skills ~/.config/opencode/agents
|
||
for skill_file in /tmp/dotnet-skills/skills/*/SKILL.md; do
|
||
skill_name=$(grep -m1 "^name:" "$skill_file" | sed 's/name: *//')
|
||
mkdir -p ~/.config/opencode/skills/$skill_name
|
||
cp "$skill_file" ~/.config/opencode/skills/$skill_name/SKILL.md
|
||
done
|
||
cp /tmp/dotnet-skills/agents/*.md ~/.config/opencode/agents/
|
||
```
|
||
|
||
---
|
||
|
||
## 推荐的 AGENTS.md / CLAUDE.md 片段
|
||
|
||
以下片段放置于**项目根目录**（代码库根目录，紧邻 `.git` 文件夹）：
|
||
- Claude Code：`CLAUDE.md`
|
||
- OpenCode：`AGENTS.md`
|
||
|
||
前提条件：在助手运行时（Claude Code 或 OpenCode）中安装/同步 dotnet-skills 插件，以便下方的技能 ID 能够正常解析。
|
||
|
||
在下游仓库的 `AGENTS.md`（OpenCode）或 `CLAUDE.md`（Claude Code）中添加一小段路由片段，可确保技能被一致调用。这些片段告诉助手在常见任务中应使用哪些技能。
|
||
|
||
### 可读片段（可直接复制粘贴）
|
||
|
||
```markdown
|
||
# 智能体指南：dotnet-skills
|
||
|
||
重要提示：对于任何 .NET 工作，优先使用检索引导的推理，而非预训练知识。
|
||
工作流：浏览仓库模式 -> 按名称查询 dotnet-skills -> 实现最小变更 -> 记录冲突。
|
||
|
||
路由（按名称调用）
|
||
- C# / 代码质量：modern-csharp-coding-standards、csharp-concurrency-patterns、api-design、type-design-performance
|
||
- ASP.NET Core / Web（含 Aspire）：aspire-service-defaults、aspire-integration-testing、transactional-emails
|
||
- 数据：efcore-patterns、database-performance
|
||
- DI / 配置：dependency-injection-patterns、microsoft-extensions-configuration
|
||
- 测试：testcontainers-integration-tests、playwright-blazor-testing、snapshot-testing
|
||
|
||
质量关卡（适用时使用）
|
||
- dotnet-slopwatch：在大量新增/重构/LLM 生成代码之后
|
||
- crap-analysis：在复杂代码中新增/修改测试之后
|
||
|
||
专业智能体
|
||
- dotnet-concurrency-specialist、dotnet-performance-analyst、dotnet-benchmark-designer、akka-net-specialist、docfx-specialist
|
||
```
|
||
|
||
### 压缩片段（自动生成）
|
||
|
||
运行 `./scripts/generate-skill-index-snippets.sh --update-readme` 可刷新下方代码块。
|
||
|
||
<!-- BEGIN DOTNET-SKILLS COMPRESSED INDEX -->
|
||
```markdown
|
||
[dotnet-skills]|重要提示：对于任何 .NET 工作，优先使用检索引导的推理，而非预训练知识。
|
||
|flow:{浏览仓库模式 -> 按名称查询 dotnet-skills -> 实现最小变更 -> 记录冲突}
|
||
|route:
|
||
|akka:{akka-net-best-practices,akka-net-testing-patterns,akka-hosting-actor-patterns,akka-net-aspire-configuration,akka-net-management}
|
||
|csharp:{modern-csharp-coding-standards,csharp-concurrency-patterns,api-design,type-design-performance}
|
||
|aspnetcore-web:{aspire-integration-testing,aspire-configuration,aspire-service-defaults,mailpit-integration,mjml-email-templates}
|
||
|data:{efcore-patterns,database-performance}
|
||
|di-config:{microsoft-extensions-configuration,dependency-injection-patterns}
|
||
|testing:{testcontainers-integration-tests,playwright-blazor-testing,snapshot-testing,verify-email-snapshots,playwright-ci-caching}
|
||
|dotnet:{dotnet-project-structure,dotnet-local-tools,package-management,serialization,dotnet-devcert-trust}
|
||
|quality-gates:{dotnet-slopwatch,crap-analysis}
|
||
|meta:{marketplace-publishing,skills-index-snippets}
|
||
|agents:{akka-net-specialist,docfx-specialist,dotnet-benchmark-designer,dotnet-concurrency-specialist,dotnet-performance-analyst,roslyn-incremental-generator-specialist}
|
||
```
|
||
<!-- END DOTNET-SKILLS COMPRESSED INDEX -->
|
||
|
||
## 专业智能体
|
||
|
||
智能体是具有深度领域专长的 AI 角色，当 Claude Code 检测到相关任务时会自动调用。
|
||
|
||
| 智能体 | 专业领域 |
|
||
| --- | --- |
|
||
| **akka-net-specialist** | Actor 系统、集群、持久化、Akka.Streams、消息模式 |
|
||
| **dotnet-concurrency-specialist** | 线程、async/await、竞态条件、死锁分析 |
|
||
| **dotnet-benchmark-designer** | BenchmarkDotNet 设置、自定义基准测试、测量策略 |
|
||
| **dotnet-performance-analyst** | 性能分析器分析、基准测试结果解读、回归检测 |
|
||
| **docfx-specialist** | DocFX 构建、API 文档、Markdown 检查 |
|
||
|
||
---
|
||
|
||
## 技能库
|
||
|
||
### Akka.NET
|
||
|
||
使用 Akka.NET 构建分布式系统的生产级模式。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **best-practices** | EventStream vs DistributedPubSub、监督策略、Actor 层次结构 |
|
||
| **testing-patterns** | Akka.Hosting.TestKit、异步断言、TestProbe 模式 |
|
||
| **hosting-actor-patterns** | Props 工厂、`IRequiredActor<T>`、Actor 中的 DI 作用域管理 |
|
||
| **aspire-configuration** | Akka.NET + .NET Aspire 集成、HOCON 与 IConfiguration |
|
||
| **management** | Akka.Management、健康检查、集群引导 |
|
||
|
||
### C# 语言
|
||
|
||
适用于简洁、高性能代码的现代 C# 模式。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **coding-standards** | Records、模式匹配、可空类型、值对象、禁用 AutoMapper |
|
||
| **concurrency-patterns** | 何时使用 Task vs Channel vs lock vs actors |
|
||
| **api-design** | 仅扩展设计、API/线路兼容性、版本控制策略 |
|
||
| **type-design-performance** | 密封类、只读结构体、静态纯函数、Span<T> |
|
||
|
||
### 数据访问
|
||
|
||
可扩展的数据库模式。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **efcore-patterns** | 实体配置、迁移、查询优化 |
|
||
| **database-performance** | 读写分离、防止 N+1 问题、AsNoTracking、行数限制 |
|
||
|
||
### .NET Aspire
|
||
|
||
云原生应用编排。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **integration-testing** | DistributedApplicationTestingBuilder、Aspire.Hosting.Testing |
|
||
| **service-defaults** | OpenTelemetry、健康检查、弹性、服务发现 |
|
||
| **mailpit-integration** | 使用 Mailpit 容器进行邮件测试、SMTP 配置、测试断言 |
|
||
|
||
### ASP.NET Core
|
||
|
||
Web 应用程序模式。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **mjml-email-templates** | MJML 语法、响应式布局、模板渲染器、组合器模式 |
|
||
|
||
### .NET 生态系统
|
||
|
||
核心 .NET 开发实践。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **project-structure** | 解决方案布局、Directory.Build.props、分层架构 |
|
||
| **package-management** | 中央包管理（CPM）、共享版本变量、dotnet CLI |
|
||
| **serialization** | Protobuf、MessagePack、System.Text.Json 源生成器、AOT |
|
||
| **local-tools** | dotnet 工具清单、团队共享工具 |
|
||
| **slopwatch** | 检测代码库中 LLM 生成的反模式 |
|
||
|
||
### Microsoft.Extensions
|
||
|
||
依赖注入与配置模式。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **configuration** | IOptions 模式、环境特定配置、密钥管理 |
|
||
| **dependency-injection** | IServiceCollection 扩展、作用域管理、键控服务 |
|
||
|
||
### 测试
|
||
|
||
全面的测试策略。
|
||
|
||
| 技能 | 学习内容 |
|
||
| --- | --- |
|
||
| **testcontainers** | 基于 Docker 的集成测试、PostgreSQL、Redis、RabbitMQ |
|
||
| **playwright-blazor** | Blazor 应用的端到端测试、页面对象、异步断言 |
|
||
| **crap-analysis** | CRAP 分数、覆盖率阈值、ReportGenerator 集成 |
|
||
| **snapshot-testing** | Verify 库、审批测试、API 响应校验 |
|
||
| **verify-email-snapshots** | 对邮件模板进行快照测试，捕获渲染回归 |
|
||
|
||
---
|
||
|
||
## 核心原则
|
||
|
||
这些技能强调在生产环境中有效的模式：
|
||
|
||
- **默认不可变** —— Records、只读结构体、值对象
|
||
- **类型安全** —— 可空引用类型、强类型 ID
|
||
- **组合优于继承** —— 无抽象基类，默认密封
|
||
- **性能意识** —— Span<T>、对象池、延迟枚举
|
||
- **可测试性** —— 处处使用 DI、纯函数、显式依赖
|
||
- **无黑魔法** —— 不用 AutoMapper，不用重反射框架
|
||
|
||
---
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
dotnet-skills/
|
||
├── .claude-plugin/
|
||
│ └── plugin.json # 插件清单
|
||
├── agents/ # 5 个专业智能体
|
||
│ ├── akka-net-specialist.md
|
||
│ ├── docfx-specialist.md
|
||
│ ├── dotnet-benchmark-designer.md
|
||
│ ├── dotnet-concurrency-specialist.md
|
||
│ └── dotnet-performance-analyst.md
|
||
└── skills/ # 扁平结构（30 个技能）
|
||
├── akka-best-practices/SKILL.md
|
||
├── akka-hosting-actor-patterns/SKILL.md
|
||
├── akka-net-aspire-configuration/SKILL.md
|
||
├── aspire-configuration/SKILL.md
|
||
├── aspire-integration-testing/SKILL.md
|
||
├── csharp-concurrency-patterns/SKILL.md
|
||
├── testcontainers-integration-tests/SKILL.md
|
||
└── ... # （按类别添加前缀）
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献指南
|
||
|
||
想要添加技能或智能体？欢迎提交 PR！
|
||
|
||
1. 创建 `skills/<skill-name>/SKILL.md`（使用 `akka-`、`aspire-`、`csharp-` 等前缀标注类别）
|
||
2. 将路径添加到 `.claude-plugin/plugin.json`
|
||
3. 提交 PR
|
||
|
||
技能文档应为包含具体示例和反模式的完整参考文档（10-40KB）。
|
||
|
||
---
|
||
|
||
## 作者
|
||
|
||
由 [Aaron Stannard](https://aaronstannard.com/)（[@Aaronontheweb](https://github.com/Aaronontheweb)）创建
|
||
|
||
模式来源于生产系统，包括 [Akka.NET](https://getakka.net/)、[Petabridge](https://petabridge.com/) 和 [Sdkbin](https://sdkbin.com/)。
|
||
|
||
## 许可证
|
||
|
||
MIT 许可证 - 版权所有 © 2025 Aaron Stannard
|
||
|
||
详情见 [LICENSE](LICENSE) 文件。 |