| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 14 | 3 | 6% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 0 | 3 | 0 | 0% |
What each file covers
Sections
1 shared · 14 only in A · 3 only in B- − Copilot instructions
- − General recommendations for working with Aspire
- − Running the application
- − Checking resources
- − Listing integrations
- − Debugging issues
- − Other Aspire MCP tools
- − Playwright MCP server
- − Updating the app host
- − Persistent containers
- − Aspire workload
- − Official documentation
- − BMAD AI 工作流
- − 与 CodeSpirit 规范集成
- + Controller 中使用本地化
- + DTO 验证特性多语言
- + Display 特性
- 获取帮助
Commands
0 shared · 2 only in A · 0 only in B- − dotnet tool install --global dotnet-outdated-tool
- − dotnet-outdated
Section tags
0 shared · 3 only in A · 0 only in B- − code-style
- − agent-behaviour
- − docs
Line diff
xin-lai/CodeSpirit · AGENTS.md
@@ −1 @@
1# Copilot instructions
2
3This repository is set up to use Aspire. Aspire is an orchestrator for the entire application and will take care of configuring dependencies, building, and running the application. The resources that make up the application are defined in `apphost.cs` including application code and external dependencies.
4
5## General recommendations for working with Aspire
61. Before making any changes always run the apphost using `aspire run` and inspect the state of resources to make sure you are building from a known state.
71. Changes to the _apphost.cs_ file will require a restart of the application to take effect.
82. Make changes incrementally and run the aspire application using the `aspire run` command to validate changes.
93. Use the Aspire MCP tools to check the status of resources and debug issues.
10
11## Running the application
12To run the application run the following command:
13
14```
15aspire run
16```
17
18If there is already an instance of the application running it will prompt to stop the existing instance. You only need to restart the application if code in `apphost.cs` is changed, but if you experience problems it can be useful to reset everything to the starting state.
19
20## Checking resources
21To check the status of resources defined in the app model use the _list resources_ tool. This will show you the current state of each resource and if there are any issues. If a resource is not running as expected you can use the _execute resource command_ tool to restart it or perform other actions.
22
23## Listing integrations
24IMPORTANT! When a user asks you to add a resource to the app model you should first use the _list integrations_ tool to get a list of the current versions of all the available integrations. You should try to use the version of the integration which aligns with the version of the Aspire.AppHost.Sdk. Some integration versions may have a preview suffix. Once you have identified the correct integration you should always use the _get integration docs_ tool to fetch the latest documentation for the integration and follow the links to get additional guidance.
25
26## Debugging issues
27IMPORTANT! Aspire is designed to capture rich logs and telemetry for all resources defined in the app model. Use the following diagnostic tools when debugging issues with the application before making changes to make sure you are focusing on the right things.
28
291. _list structured logs_; use this tool to get details about structured logs.
302. _list console logs_; use this tool to get details about console logs.
313. _list traces_; use this tool to get details about traces.
324. _list trace structured logs_; use this tool to get logs related to a trace
33
34## Other Aspire MCP tools
35
361. _select apphost_; use this tool if working with multiple app hosts within a workspace.
372. _list apphosts_; use this tool to get details about active app hosts.
38
39## Playwright MCP server
40
41The playwright MCP server has also been configured in this repository and you should use it to perform functional investigations of the resources defined in the app model as you work on the codebase. To get endpoints that can be used for navigation using the playwright MCP server use the list resources tool.
42
43## Updating the app host
44The user may request that you update the Aspire apphost. You can do this using the `aspire update` command. This will update the apphost to the latest version and some of the Aspire specific packages in referenced projects, however you may need to manually update other packages in the solution to ensure compatibility. You can consider using the `dotnet-outdated` with the users consent. To install the `dotnet-outdated` tool use the following command:
45
46```
47dotnet tool install --global dotnet-outdated-tool
48```
49
50## Persistent containers
51IMPORTANT! Consider avoiding persistent containers early during development to avoid creating state management issues when restarting the app.
52
53## Aspire workload
54IMPORTANT! The aspire workload is obsolete. You should never attempt to install or use the Aspire workload.
55
56## Official documentation
57IMPORTANT! Always prefer official documentation when available. The following sites contain the official documentation for Aspire and related components
58
591. https://aspire.dev
602. https://learn.microsoft.com/dotnet/aspire
613. https://nuget.org (for specific integration package details)
62
63## BMAD AI 工作流
64
65本项目已集成 BMAD (Breakthrough Method of Agile AI-Driven Development) 完整工作流，用于结构化的软件开发生命周期管理。
66
67### 快速开始
68
691. **小型任务/Bug 修复** (Quick Flow):
70 - `/quick-spec` - 创建技术规范
71 - `/quick-dev` - 实现变更
72 - `/code-review` - 代码审查
73
742. **完整功能开发** (Full Flow):
75 - `/product-brief` - 产品需求简报
76 - `/create-prd` - 创建 PRD
77 - `/create-architecture` - 架构设计
78 - `/create-epics-and-stories` - 拆分为 Epic 和 Story
79 - `/sprint-planning` - Sprint 规划
80 - `/dev-story` - 实现 Story
81 - `/code-review` - 代码审查
82 - `/retrospective` - 复盘
83
84### 与 CodeSpirit 规范集成
85
86BMAD 工作流已配置为自动遵循 CodeSpirit 的所有开发规范（位于 `.cursor/rules/`）。在使用 BMAD 时：
87
88- PRD 会自动考虑多租户、多数据库、AI 功能等项目特性
89- 架构设计会遵循依赖注入、缓存策略等规范
90- Story 实现会应用正确的命名约定、DTO 设计、控制器规范等
91- 代码审查会执行 CodeSpirit 特定的审查清单
92
93### 获取帮助
94
95任何时候，输入 `/bmad-help` 可获取上下文相关的指导。
96
97详细使用指南请参考：
98- **[BMAD 使用教程](Docs/bmad/bmad-tutorial.md)** - 完整的综合教程（推荐新手阅读）
99- [BMAD 工作流指南](Docs/bmad/bmad-workflow-guide.md) - 详细的工作流使用指南
100- [BMAD 团队培训指南](Docs/bmad/bmad-team-guide.md) - 团队培训材料
101- [BMAD 集成技能](.cursor/skills/bmad-integration/SKILL.md) - BMAD 与 CodeSpirit 集成
102- [项目上下文文档](project-context.md) - 项目上下文和规范引用
xin-lai/CodeSpirit · .cursor/rules/i18n.mdc
@@ +1 @@
1---
2description: CodeSpirit 多语言国际化规范 - 资源文件、本地化、前后端多语言支持
3globs:
4 - "*Dto.cs"
5 - "**/Dtos/**/*.cs"
6 - "*Enum.cs"
7 - "**/Enums/**/*.cs"
8 - "*Controller.cs"
9 - "**/Controllers/**/*.cs"
10 - "**/Resources/**/*.cs"
11alwaysApply: false
12---
13
14# 多语言国际化规范
15
16## 支持语言
17- **简体中文** (zh-CN) - 默认语言
18- **英文** (en)
19
20## 资源文件命名规范
21
22### 共享资源
23```
24CodeSpirit.Localization/Resources/
25 ├── SharedResources.cs # 资源类
26 ├── Shared.resx # 中文（默认）
27 ├── Shared.en.resx # 英文
28 ├── Display.resx / Display.en.resx # 显示文本资源
29 ├── Validation.resx / Validation.en.resx # 验证消息资源
30```
31
32### 服务特定资源
33```
34CodeSpirit.ExamApi/Resources/
35 ├── ExamDisplayResources.cs # 资源类
36 ├── ExamDisplay.resx # 中文（默认）
37 └── ExamDisplay.en.resx # 英文
38```
39
40## 资源键命名规范
41- **通用**: `Common.{Key}` (如 `Common.Save`, `Common.Delete`)
42- **错误**: `Errors.{Key}` (如 `Errors.NotFound`, `Errors.InvalidInput`)
43- **验证**: `Validation.{Rule}` (如 `Validation.Required`, `Validation.StringLengthMax`)
44- **DTO描述**: `{EntityName}.{PropertyName}.Description` (如 `Question.Content.Description`)
45
46示例资源文件（Display.resx）：
47```xml
48<data name="Common.Save" xml:space="preserve">
49 <value>保存</value>
50</data>
51<data name="Common.Delete" xml:space="preserve">
52 <value>删除</value>
53</data>
54<data name="Question.Content.Description" xml:space="preserve">
55 <value>请输入题目的具体内容</value>
56</data>
57```
58
59## Controller 中使用本地化
60
61```csharp
62using CodeSpirit.Localization.Resources;
63using Microsoft.Extensions.Localization;
64
65public class QuestionsController : ApiControllerBase
66{
67 private readonly IStringLocalizer<SharedResources> _localizer;
68
69 public QuestionsController(IStringLocalizer<SharedResources> localizer)
70 {
71 _localizer = localizer;
72 }
73
74 [HttpPost]
75 public async Task<ActionResult<ApiResponse>> Create(CreateQuestionDto dto)
76 {
77 await _service.CreateAsync(dto);
78 return SuccessResponse(message: _localizer["Common.Save"].Value);
79 }
80}
81```
82
83## DTO 验证特性多语言
84
85### Display 特性
86```csharp
87using CodeSpirit.Localization.Resources;
88
89public class CreateQuestionDto
90{
91 [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
92 [Required(ErrorMessageResourceType = typeof(ValidationResources),
93 ErrorMessageResourceName = "Required")]
94 [StringLength(2000,
95 ErrorMessageResourceType = typeof(ValidationResources),
96 ErrorMessageResourceName = "StringLengthMax")]
97 public string Content { get; set; } = string.Empty;
98
99 [Display(Name = "Score", ResourceType = typeof(DisplayResources))]
100 [Range(0, 100,
101 ErrorMessageResourceType = typeof(ValidationResources),
102 ErrorMessageResourceName = "Range")]
103 public decimal Score { get; set; }
104}
105```
106
107### 描述信息多语言
108```csharp
109using CodeSpirit.Localization.Attributes;
110
111public class CreateQuestionDto
112{
113 [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
114 [LocalizedDescription("Question.Content.Description", typeof(ExamDisplayResources))]
115 public string Content { get; set; } = string.Empty;
116}
117```
118
119## 本地化异常
120
121```csharp
122// 使用资源键
123throw new BusinessException("Errors.InvalidStartTime");
124
125// 带参数（使用占位符 {0}, {1}）
126throw new ValidationException("Errors.NotFound", resourceId);
127```
128
129资源文件定义：
130```xml
131<data name="Errors.NotFound" xml:space="preserve">
132 <value>资源 {0} 未找到</value>
133</data>
134```
135
136## 枚举多语言
137```csharp
138public enum QuestionType
139{
140 [Display(Name = "SingleChoice", ResourceType = typeof(DisplayResources))]
141 SingleChoice = 1,
142
143 [Display(Name = "MultipleChoice", ResourceType = typeof(DisplayResources))]
144 MultipleChoice = 2,
145
146 [Display(Name = "TrueFalse", ResourceType = typeof(DisplayResources))]
147 TrueFalse = 3
148}
149```
150
151资源文件：
152```xml
153<data name="SingleChoice" xml:space="preserve">
154 <value>单选题</value>
155</data>
156<data name="MultipleChoice" xml:space="preserve">
157 <value>多选题</value>
158</data>
159```
160
161## 注意事项
162
163### 强制要求（必须遵守）
164- ✅ 所有面向用户的文本必须支持多语言
165- ✅ 资源文件必须同时提供中文和英文版本
166- ✅ 验证消息、异常消息全部使用本地化
167
168### 最佳实践（推荐遵守）
169- 💡 新开发的 DTO、枚举、控制器应使用多语言写法
170- 💡 逐步迁移现有硬编码文本到资源文件
171- 💡 定期检查资源文件是否有缺失的翻译
172
173### 迁移指南
174对于现有代码，建议采用渐进式迁移：
1751. 新功能必须使用多语言写法
1762. 修改现有功能时，同步迁移为多语言写法
1773. 定期批量迁移高频使用的文本
178
179
@@ −1 +1 @@
1−# Copilot instructions
1+---
2+description: CodeSpirit 多语言国际化规范 - 资源文件、本地化、前后端多语言支持
3+globs:
4+ - "*Dto.cs"
5+ - "**/Dtos/**/*.cs"
6+ - "*Enum.cs"
7+ - "**/Enums/**/*.cs"
8+ - "*Controller.cs"
9+ - "**/Controllers/**/*.cs"
10+ - "**/Resources/**/*.cs"
11+alwaysApply: false
12+---
213
3−This repository is set up to use Aspire. Aspire is an orchestrator for the entire application and will take care of configuring dependencies, building, and running the application. The resources that make up the application are defined in `apphost.cs` including application code and external dependencies.
14+# 多语言国际化规范
415
5−## General recommendations for working with Aspire
6−1. Before making any changes always run the apphost using `aspire run` and inspect the state of resources to make sure you are building from a known state.
7−1. Changes to the _apphost.cs_ file will require a restart of the application to take effect.
8−2. Make changes incrementally and run the aspire application using the `aspire run` command to validate changes.
9−3. Use the Aspire MCP tools to check the status of resources and debug issues.
16+## 支持语言
17+- **简体中文** (zh-CN) - 默认语言
18+- **英文** (en)
1019
11−## Running the application
12−To run the application run the following command:
20+## 资源文件命名规范
1321
22+### 共享资源
1423 ```
15−aspire run
24+CodeSpirit.Localization/Resources/
25+ ├── SharedResources.cs # 资源类
26+ ├── Shared.resx # 中文（默认）
27+ ├── Shared.en.resx # 英文
28+ ├── Display.resx / Display.en.resx # 显示文本资源
29+ ├── Validation.resx / Validation.en.resx # 验证消息资源
1630 ```
1731
18−If there is already an instance of the application running it will prompt to stop the existing instance. You only need to restart the application if code in `apphost.cs` is changed, but if you experience problems it can be useful to reset everything to the starting state.
32+### 服务特定资源
33+```
34+CodeSpirit.ExamApi/Resources/
35+ ├── ExamDisplayResources.cs # 资源类
36+ ├── ExamDisplay.resx # 中文（默认）
37+ └── ExamDisplay.en.resx # 英文
38+```
1939
20−## Checking resources
21−To check the status of resources defined in the app model use the _list resources_ tool. This will show you the current state of each resource and if there are any issues. If a resource is not running as expected you can use the _execute resource command_ tool to restart it or perform other actions.
40+## 资源键命名规范
41+- **通用**: `Common.{Key}` (如 `Common.Save`, `Common.Delete`)
42+- **错误**: `Errors.{Key}` (如 `Errors.NotFound`, `Errors.InvalidInput`)
43+- **验证**: `Validation.{Rule}` (如 `Validation.Required`, `Validation.StringLengthMax`)
44+- **DTO描述**: `{EntityName}.{PropertyName}.Description` (如 `Question.Content.Description`)
2245
23−## Listing integrations
24−IMPORTANT! When a user asks you to add a resource to the app model you should first use the _list integrations_ tool to get a list of the current versions of all the available integrations. You should try to use the version of the integration which aligns with the version of the Aspire.AppHost.Sdk. Some integration versions may have a preview suffix. Once you have identified the correct integration you should always use the _get integration docs_ tool to fetch the latest documentation for the integration and follow the links to get additional guidance.
46+示例资源文件（Display.resx）：
47+```xml
48+<data name="Common.Save" xml:space="preserve">
49+ <value>保存</value>
50+</data>
51+<data name="Common.Delete" xml:space="preserve">
52+ <value>删除</value>
53+</data>
54+<data name="Question.Content.Description" xml:space="preserve">
55+ <value>请输入题目的具体内容</value>
56+</data>
57+```
2558
26−## Debugging issues
27−IMPORTANT! Aspire is designed to capture rich logs and telemetry for all resources defined in the app model. Use the following diagnostic tools when debugging issues with the application before making changes to make sure you are focusing on the right things.
59+## Controller 中使用本地化
2860
29−1. _list structured logs_; use this tool to get details about structured logs.
30−2. _list console logs_; use this tool to get details about console logs.
31−3. _list traces_; use this tool to get details about traces.
32−4. _list trace structured logs_; use this tool to get logs related to a trace
61+```csharp
62+using CodeSpirit.Localization.Resources;
63+using Microsoft.Extensions.Localization;
3364
34−## Other Aspire MCP tools
65+public class QuestionsController : ApiControllerBase
66+{
67+ private readonly IStringLocalizer<SharedResources> _localizer;
68+
69+ public QuestionsController(IStringLocalizer<SharedResources> localizer)
70+ {
71+ _localizer = localizer;
72+ }
73+
74+ [HttpPost]
75+ public async Task<ActionResult<ApiResponse>> Create(CreateQuestionDto dto)
76+ {
77+ await _service.CreateAsync(dto);
78+ return SuccessResponse(message: _localizer["Common.Save"].Value);
79+ }
80+}
81+```
3582
36−1. _select apphost_; use this tool if working with multiple app hosts within a workspace.
37−2. _list apphosts_; use this tool to get details about active app hosts.
83+## DTO 验证特性多语言
3884
39−## Playwright MCP server
85+### Display 特性
86+```csharp
87+using CodeSpirit.Localization.Resources;
4088
41−The playwright MCP server has also been configured in this repository and you should use it to perform functional investigations of the resources defined in the app model as you work on the codebase. To get endpoints that can be used for navigation using the playwright MCP server use the list resources tool.
89+public class CreateQuestionDto
90+{
91+ [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
92+ [Required(ErrorMessageResourceType = typeof(ValidationResources),
93+ ErrorMessageResourceName = "Required")]
94+ [StringLength(2000,
95+ ErrorMessageResourceType = typeof(ValidationResources),
96+ ErrorMessageResourceName = "StringLengthMax")]
97+ public string Content { get; set; } = string.Empty;
98+
99+ [Display(Name = "Score", ResourceType = typeof(DisplayResources))]
100+ [Range(0, 100,
101+ ErrorMessageResourceType = typeof(ValidationResources),
102+ ErrorMessageResourceName = "Range")]
103+ public decimal Score { get; set; }
104+}
105+```
42106
43−## Updating the app host
44−The user may request that you update the Aspire apphost. You can do this using the `aspire update` command. This will update the apphost to the latest version and some of the Aspire specific packages in referenced projects, however you may need to manually update other packages in the solution to ensure compatibility. You can consider using the `dotnet-outdated` with the users consent. To install the `dotnet-outdated` tool use the following command:
107+### 描述信息多语言
108+```csharp
109+using CodeSpirit.Localization.Attributes;
45110
111+public class CreateQuestionDto
112+{
113+ [Display(Name = "Content", ResourceType = typeof(DisplayResources))]
114+ [LocalizedDescription("Question.Content.Description", typeof(ExamDisplayResources))]
115+ public string Content { get; set; } = string.Empty;
116+}
46117 ```
47−dotnet tool install --global dotnet-outdated-tool
48−```
49118
50−## Persistent containers
51−IMPORTANT! Consider avoiding persistent containers early during development to avoid creating state management issues when restarting the app.
119+## 本地化异常
52120
53−## Aspire workload
54−IMPORTANT! The aspire workload is obsolete. You should never attempt to install or use the Aspire workload.
121+```csharp
122+// 使用资源键
123+throw new BusinessException("Errors.InvalidStartTime");
55124
56−## Official documentation
57−IMPORTANT! Always prefer official documentation when available. The following sites contain the official documentation for Aspire and related components
125+// 带参数（使用占位符 {0}, {1}）
126+throw new ValidationException("Errors.NotFound", resourceId);
127+```
58128
59−1. https://aspire.dev
60−2. https://learn.microsoft.com/dotnet/aspire
61−3. https://nuget.org (for specific integration package details)
129+资源文件定义：
130+```xml
131+<data name="Errors.NotFound" xml:space="preserve">
132+ <value>资源 {0} 未找到</value>
133+</data>
134+```
62135
63−## BMAD AI 工作流
136+## 枚举多语言
137+```csharp
138+public enum QuestionType
139+{
140+ [Display(Name = "SingleChoice", ResourceType = typeof(DisplayResources))]
141+ SingleChoice = 1,
142+
143+ [Display(Name = "MultipleChoice", ResourceType = typeof(DisplayResources))]
144+ MultipleChoice = 2,
145+
146+ [Display(Name = "TrueFalse", ResourceType = typeof(DisplayResources))]
147+ TrueFalse = 3
148+}
149+```
64150
65−本项目已集成 BMAD (Breakthrough Method of Agile AI-Driven Development) 完整工作流，用于结构化的软件开发生命周期管理。
151+资源文件：
152+```xml
153+<data name="SingleChoice" xml:space="preserve">
154+ <value>单选题</value>
155+</data>
156+<data name="MultipleChoice" xml:space="preserve">
157+ <value>多选题</value>
158+</data>
159+```
66160
67−### 快速开始
161+## 注意事项
68162
69−1. **小型任务/Bug 修复** (Quick Flow):
70− - `/quick-spec` - 创建技术规范
71− - `/quick-dev` - 实现变更
72− - `/code-review` - 代码审查
163+### 强制要求（必须遵守）
164+- ✅ 所有面向用户的文本必须支持多语言
165+- ✅ 资源文件必须同时提供中文和英文版本
166+- ✅ 验证消息、异常消息全部使用本地化
73167
74−2. **完整功能开发** (Full Flow):
75− - `/product-brief` - 产品需求简报
76− - `/create-prd` - 创建 PRD
77− - `/create-architecture` - 架构设计
78− - `/create-epics-and-stories` - 拆分为 Epic 和 Story
79− - `/sprint-planning` - Sprint 规划
80− - `/dev-story` - 实现 Story
81− - `/code-review` - 代码审查
82− - `/retrospective` - 复盘
168+### 最佳实践（推荐遵守）
169+- 💡 新开发的 DTO、枚举、控制器应使用多语言写法
170+- 💡 逐步迁移现有硬编码文本到资源文件
171+- 💡 定期检查资源文件是否有缺失的翻译
83172
84−### 与 CodeSpirit 规范集成
173+### 迁移指南
174+对于现有代码，建议采用渐进式迁移：
175+1. 新功能必须使用多语言写法
176+2. 修改现有功能时，同步迁移为多语言写法
177+3. 定期批量迁移高频使用的文本
85178
86−BMAD 工作流已配置为自动遵循 CodeSpirit 的所有开发规范（位于 `.cursor/rules/`）。在使用 BMAD 时：
87179
88−- PRD 会自动考虑多租户、多数据库、AI 功能等项目特性
89−- 架构设计会遵循依赖注入、缓存策略等规范
90−- Story 实现会应用正确的命名约定、DTO 设计、控制器规范等
91−- 代码审查会执行 CodeSpirit 特定的审查清单
92−
93−### 获取帮助
94−
95−任何时候，输入 `/bmad-help` 可获取上下文相关的指导。
96−
97−详细使用指南请参考：
98−- **[BMAD 使用教程](Docs/bmad/bmad-tutorial.md)** - 完整的综合教程（推荐新手阅读）
99−- [BMAD 工作流指南](Docs/bmad/bmad-workflow-guide.md) - 详细的工作流使用指南
100−- [BMAD 团队培训指南](Docs/bmad/bmad-team-guide.md) - 团队培训材料
101−- [BMAD 集成技能](.cursor/skills/bmad-integration/SKILL.md) - BMAD 与 CodeSpirit 集成
102−- [项目上下文文档](project-context.md) - 项目上下文和规范引用
