810 lines
38 KiB
Markdown
810 lines
38 KiB
Markdown
---
|
||
name: initialize-new-project
|
||
description: >-
|
||
在基于模板创建新项目后,通过现状检查 + 两轮交互(技术栈 + 业务材料)收集需求,
|
||
最终生成一份支持分模块多轮执行的项目初始化计划(Plan)。
|
||
本 skill 只生成 plan,不执行任何代码或配置变更;用户确认后再由后续对话分模块逐步实现。
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
# 初始化新项目(生成 Plan)
|
||
|
||
本 skill 用于在基于模板创建新项目后,通过两轮交互收集需求,最终输出一份完整、可执行的项目初始化计划(plan)。
|
||
|
||
## 核心原则
|
||
|
||
**本 skill 只生成 plan,绝不执行任何代码、配置或文件变更。**
|
||
- 不写文件、不改 csproj、不加 NuGet 包
|
||
- 不修改 App.xaml、Startup.cs 等代码
|
||
- 不创建 rules / skills / 文档
|
||
- 最终交付物是一份结构化的 plan(写入 `.cursor/plans/initialize-plan.md`)
|
||
|
||
执行阶段由用户确认 plan 后,在后续对话中单独进行(可使用 Cursor 的 Plan 模式或 Agent 模式)。
|
||
|
||
## 最终目标
|
||
|
||
**本 skill 的最终目标是产出一份可执行的项目初始化计划(Plan),该计划经过后续多轮对话逐一实现后,应能得到一个完整可用、与原型图高度一致的 WPF 软件。**
|
||
|
||
这意味着 Plan 必须:
|
||
|
||
- **以原型图为唯一真相源**:Plan 中的所有 UI 描述、模块拆分、页面清单必须直接来自用户提供的设计原型,而不是猜测。
|
||
- **可迭代执行**:Plan 不是"一次性把所有代码写完"的指令,而是按模块、按页面拆分为多个独立可执行的任务块,每块可由后续对话单独实现并验证。
|
||
- **充分暴露不确定性**:原型图中不清晰的部分、技术决策中未决的部分,必须在 Plan 中明确标注「待确认」,让用户参与决策——而不是 AI 自己编造。
|
||
|
||
## 整体流程
|
||
|
||
1. **Step 0 — 项目现状检查**(检查项目已有的配置、模块、模板代码)
|
||
2. **Step 1 — 第一轮:收集技术栈需求**(AskQuestion,10 个问题)
|
||
3. **Step 2 — 生成初步计划(Plan v1)**(仅基于技术栈 + 现状检查结果)
|
||
4. **Step 3 — 第二轮:索要业务材料与设计原型**(AskQuestion + 自由对话)
|
||
5. **Step 4 — 生成完整计划(Plan v2)**(最终交付,写入文件)
|
||
|
||
---
|
||
|
||
## Step 0 — 项目现状检查
|
||
|
||
在收集用户需求之前,必须先了解项目模板的当前状态:**哪些已经配置好了、哪些可以直接用**。这个检查应在 Step 1 之前完成,检查结果会影响后续的技术栈询问策略(例如,已配置好的选项可以自动跳过或在问题中标注「已默认配置」)。
|
||
|
||
### 0.1 检查内容
|
||
|
||
| 检查项 | 检查方法 | 作用 |
|
||
|--------|---------|------|
|
||
| **解决方案结构** | 读取 `.slnx` 文件,列出所有已存在的项目 | 了解当前项目列表,后续新增模块时知道要往哪个 slnx 添加 |
|
||
| **Framework 项目** | 检查 `Source/PipeReviewReport.Framework/` 下的 csproj,列出已有 NuGet 包 | 了解已配置的基础设施(FreeSql、MAX、NLog 等),避免重复添加 |
|
||
| **主项目** | 检查 `Source/PipeReviewReport/PipeReviewReport.csproj` 已有 NuGet 包 | 了解主项目已引用的 UI 库 |
|
||
| **Resources 项目** | 检查 `Source/PipeReviewReport.Resources/` | 了解已有的资源结构(图标、字体、样式) |
|
||
| **Strings 项目** | 检查 `Source/PipeReviewReport.Strings/` | 了解多语言机制的现状 |
|
||
| **现有模块** | 检查 `Source/Modules/` 下是否已有模块 | 了解模块化架构的已有实现 |
|
||
| **App.xaml** | 检查 `Source/PipeReviewReport/App.xaml` | 了解已注册的资源字典 |
|
||
| **Startup / DI 配置** | 检查 `Source/PipeReviewReport.Framework/` 下的依赖注入配置 | 了解已注册的服务 |
|
||
| **现有 rules** | 检查 `.agents/rules/` 下的文件 | 了解已有规范,生成 plan 时知道哪些需要更新 |
|
||
| **现有 skills** | 检查 `.cursor/skills/` 下的文件 | 了解已有技能 |
|
||
|
||
### 0.2 将检查结果融入 Plan
|
||
|
||
在后续 Step 2 和 Step 4 生成 Plan 时:
|
||
|
||
- **标注「已有」**:所有已存在的包、配置、代码在 Plan 中明确标注为「已有」,不要出现在「需新增」清单中。
|
||
- **标注「需移除」**:如果用户选择了与已有配置冲突的选项(如选择 DevExpress 完整版时需移除 DevExpressMvvm 包),在 Plan 中列出。
|
||
- **复用已有模块**:如果 `Source/Modules/` 下已有相关模块,Plan 中应优先建议扩展而非重复创建。
|
||
|
||
---
|
||
|
||
## Step 1 — 第一轮:收集技术栈需求
|
||
|
||
使用 `AskQuestion` 工具询问用户以下问题。**必须先收集完所有回答再进入 Step 2**。
|
||
|
||
可以在一次 `AskQuestion` 调用中提交多个问题(推荐分组提交,避免一次问太多)。
|
||
|
||
### 问题 1:UI 样式库选择
|
||
|
||
- prompt: "这个项目需要使用哪种 UI 样式库?"
|
||
- options:
|
||
- `no-ui-lib`: "不需要额外的 UI 样式库(使用默认样式)"
|
||
- `devexpress-full`: "DevExpress WPF(完整版)- 企业级 UI 控件库"
|
||
- `handycontrol`: "MAX.HandyControl - 现代化 WPF 控件库(内部 fork,禁止官方 HandyControl)"
|
||
- `material-design`: "MaterialDesignInXaml - Material Design 风格"
|
||
- `panuon`: "Panuon.UI.Silver - 现代化 UI 库"
|
||
- `other-ui`: "其他 UI 样式库"
|
||
|
||
### 问题 2:图标库配置
|
||
|
||
- prompt: "项目已内置阿里云 iconfont 图标系统。是否需要额外配置图标?"
|
||
- options:
|
||
- `default-icons`: "使用内置图标系统(推荐)"
|
||
- `fontawesome-add`: "额外添加 FontAwesome 图标库"
|
||
- `material-icons-add`: "额外添加 Material Icons 图标库"
|
||
- `other-icons`: "其他图标库"
|
||
|
||
### 问题 3:图表库选择
|
||
|
||
- prompt: "需要使用图表库吗?(默认:ScottPlot5)"
|
||
- options:
|
||
- `default-charts`: "使用默认图表库(ScottPlot5)"
|
||
- `devexpress-charts`: "DevExpress Charts(如果已选择 DevExpress WPF)"
|
||
- `livecharts`: "LiveCharts - 简单易用的图表库"
|
||
- `oxyplot`: "OxyPlot - 跨平台图表库"
|
||
- `no-charts`: "不需要"
|
||
- `other-charts`: "其他图表库"
|
||
|
||
### 问题 4:数据库选择
|
||
|
||
- prompt: "项目需要使用数据库吗?(默认:FreeSql + SQLite)"
|
||
- options:
|
||
- `default-db`: "使用默认数据库(FreeSql + SQLite)"
|
||
- `sqlite-only`: "SQLite - 仅 SQLite,不使用 FreeSql"
|
||
- `sql-server`: "SQL Server - 企业级数据库"
|
||
- `postgresql`: "PostgreSQL - 开源关系数据库"
|
||
- `mysql`: "MySQL - 流行关系数据库"
|
||
- `redis-only`: "仅需要 Redis 缓存"
|
||
- `other-db`: "其他数据库"
|
||
|
||
### 问题 5:ORM 选择(条件触发)
|
||
|
||
仅当问题 4 选择了数据库(除 `default-db` 和 `redis-only` 外)才询问:
|
||
|
||
- prompt: "需要使用 ORM 框架吗?(FreeSql 已作为默认)"
|
||
- options:
|
||
- `default-orm`: "使用默认的 FreeSql"
|
||
- `ef-core`: "Entity Framework Core - 微软官方 ORM"
|
||
- `dapper`: "Dapper - 轻量级 ORM"
|
||
- `no-orm`: "不需要 ORM,使用原生 SQL"
|
||
- `other-orm`: "其他 ORM"
|
||
|
||
### 问题 6:缓存方案
|
||
|
||
- prompt: "是否需要缓存方案?"
|
||
- options:
|
||
- `no-cache`: "不需要"
|
||
- `memory-cache`: "内存缓存(Microsoft.Extensions.Caching.Memory)"
|
||
- `redis`: "Redis 分布式缓存"
|
||
- `sqlite-cache`: "SQLite 缓存"
|
||
- `other-cache`: "其他缓存方案"
|
||
|
||
### 问题 7:日志框架
|
||
|
||
- prompt: "日志框架使用什么?(默认已有 NLog)"
|
||
- options:
|
||
- `default-nlog`: "使用默认的 NLog"
|
||
- `serilog`: "切换到 Serilog"
|
||
- `log4net`: "切换到 log4net"
|
||
- `multiple-loggers`: "使用多个日志框架"
|
||
|
||
### 问题 8:网络/通信需求
|
||
|
||
- prompt: "项目需要网络通信功能吗?"
|
||
- options:
|
||
- `no-network`: "不需要"
|
||
- `restsharp`: "HTTP 客户端(推荐 RestSharp)"
|
||
- `websocket`: "WebSocket 实时通信"
|
||
- `grpc-client`: "gRPC 客户端"
|
||
- `signalr-client`: "SignalR 客户端"
|
||
- `other-network`: "其他通信方案"
|
||
|
||
### 问题 9:其他依赖库
|
||
|
||
- prompt: "还需要其他特定的第三方库吗?(可多选)"
|
||
- allow_multiple: true
|
||
- options:
|
||
- `no-other`: "没有其他需求"
|
||
- `automapper`: "AutoMapper - 对象映射"
|
||
- `newtonsoft-json`: "Newtonsoft.Json - JSON 序列化(已有)"
|
||
- `system-text-json`: "System.Text.Json - JSON 序列化"
|
||
- `quartz`: "Quartz.NET - 任务调度"
|
||
- `fluentvalidation`: "FluentValidation - 数据校验"
|
||
- `other-lib`: "其他库(手动输入)"
|
||
|
||
### 问题 10:模块化架构
|
||
|
||
- prompt: "是否使用模块化架构?"
|
||
- options:
|
||
- `yes-modules`: "是,使用模块化架构"
|
||
- `no-modules`: "否,单一应用程序架构"
|
||
|
||
---
|
||
|
||
## Step 2 — 生成初步计划(Plan v1)
|
||
|
||
基于 Step 1 的回答,**仅输出**(不执行)一份「技术栈初始化计划(v1)」。内容包含:
|
||
|
||
1. **技术栈总览**:本次选定的所有技术(UI / 图标 / 图表 / 数据库 / ORM / 缓存 / 日志 / 网络 / 模块化)
|
||
2. **NuGet 包清单**:按项目分组(主项目 / Framework / Resources 等),注明包名、版本、用途
|
||
3. **配置文件变更清单**:csproj 修改、App.xaml 资源字典、Directory.Build.props、NLog.config 等
|
||
4. **代码文件变更清单**:Startup.cs 注册、MessageBoxServiceEx.cs 重写等
|
||
5. **rules / skills 变更清单**:需要更新或新增的规则与技能
|
||
6. **文档清单**:README.md、架构文档等
|
||
|
||
### 参考材料:常用 NuGet 包映射表
|
||
|
||
| 用户选择 | NuGet 包名 | 适用项目 | 说明 |
|
||
|---------|----------|---------|------|
|
||
| **DevExpress WPF(完整版)** | DevExpress.Wpf.Core | 主项目 | 核心 MVVM 框架(含 DevExpress.Mvvm) |
|
||
| | DevExpress.Wpf.Themes.Win11Light | 主项目 | Win11 浅色主题 |
|
||
| | DevExpress.Wpf.Grid | 主项目 | DataGrid/TreeList |
|
||
| | DevExpress.Wpf.LayoutControl | 主项目 | 布局控件 |
|
||
| | DevExpress.Wpf.Docking | 主项目 | 可停靠面板 |
|
||
| | DevExpress.Wpf.Ribbon | 主项目 | Ribbon 工具栏 |
|
||
| MAX.HandyControl | MAX.HandyControl | 主项目 | 内部 fork;**禁止**官方 `HandyControl`;程序集/命名空间仍为 HandyControl,需配置 App.xaml |
|
||
| MaterialDesignInXaml | MaterialDesignThemes | 主项目 | Material Design 风格 |
|
||
| Panuon.UI.Silver | Panuon.UI.Silver | 主项目 | |
|
||
| FontAwesome | FontAwesome.WPF | 主项目 | 额外添加(项目已有 iconfont) |
|
||
| Material Icons | MaterialDesignThemes.Mdix | 主项目 | 额外添加(项目已有 iconfont) |
|
||
| **默认图表库** | MAX.Common.Plot5 | Framework | ScottPlot5(已包含) |
|
||
| LiveCharts | LiveCharts.Wpf | 主项目 | |
|
||
| OxyPlot | OxyPlot.Wpf | 主项目 | |
|
||
| **默认数据库** | FreeSql (v3.5.309) | Framework | 已包含,核心库 |
|
||
| | FreeSql.Extensions.JsonMap (v3.5.309) | Framework | 已包含,JSON 映射 |
|
||
| | FreeSql.Provider.Sqlite (v3.5.309) | Framework | 已包含,SQLite 驱动 |
|
||
| | FreeSql.Repository (v3.5.309) | Framework | 已包含,Repository 模式 |
|
||
| SQL Server | Microsoft.Data.SqlClient | Framework | |
|
||
| PostgreSQL | Npgsql | Framework | |
|
||
| MySQL | MySql.Data | Framework | |
|
||
| Redis | StackExchange.Redis | Framework | |
|
||
| EF Core | Microsoft.EntityFrameworkCore.Sqlite | Framework | |
|
||
| Dapper | Dapper | Framework | 轻量级 ORM |
|
||
| RestSharp | RestSharp | Framework | |
|
||
| AutoMapper | AutoMapper | Framework | 对象映射(项目默认已用 Mapster) |
|
||
| Quartz.NET | Quartz | Framework | 任务调度 |
|
||
| FluentValidation | FluentValidation | Framework | 数据校验 |
|
||
|
||
### 参考材料:DevExpress WPF(完整版)配置要点
|
||
|
||
如果用户选择 DevExpress WPF(完整版),生成 plan 时需包含以下要点:
|
||
|
||
1. **添加 DevExpress NuGet 包到主项目**(`Source/PipeReviewReport/PipeReviewReport.csproj`):
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<!-- 核心 MVVM 框架(包含 DevExpress.Mvvm) -->
|
||
<PackageReference Include="DevExpress.Wpf.Core" Version="22.2.11" />
|
||
|
||
<!-- 主题(Win11 浅色主题,可根据需要选择其他主题) -->
|
||
<PackageReference Include="DevExpress.Wpf.Themes.Win11Light" Version="22.2.11" />
|
||
|
||
<!-- 常用控件 -->
|
||
<PackageReference Include="DevExpress.Wpf.Grid" Version="22.2.11" />
|
||
<PackageReference Include="DevExpress.Wpf.LayoutControl" Version="22.2.11" />
|
||
<PackageReference Include="DevExpress.Wpf.Docking" Version="22.2.11" />
|
||
<PackageReference Include="DevExpress.Wpf.Ribbon" Version="22.2.11" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
**可选的 DevExpress 包**(在 plan 中根据 UI 原型决定是否启用):
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<!-- 图表相关 -->
|
||
<PackageReference Include="DevExpress.Wpf.Charts" Version="22.2.11" />
|
||
|
||
<!-- RichEdit 文档编辑 -->
|
||
<PackageReference Include="DevExpress.Wpf.RichEdit" Version="22.2.11" />
|
||
<PackageReference Include="DevExpress.RichEdit.Export" Version="22.2.11" />
|
||
|
||
<!-- PDF 查看器 -->
|
||
<PackageReference Include="DevExpress.Wpf.PdfViewer" Version="22.2.11" />
|
||
|
||
<!-- 打印功能 -->
|
||
<PackageReference Include="DevExpress.Wpf.Printing" Version="22.2.11" />
|
||
|
||
<!-- 其他可选控件 -->
|
||
<PackageReference Include="DevExpress.Wpf.NavBar" Version="22.2.11" />
|
||
<PackageReference Include="DevExpress.Wpf.Gauges" Version="22.2.11" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
2. **移除 DevExpressMvvm 引用**(因为 DevExpress.Wpf.Core 已包含):
|
||
|
||
从 `Source/PipeReviewReport.Framework/PipeReviewReport.Framework.csproj` 中移除:
|
||
|
||
```xml
|
||
<PackageReference Include="DevExpressMvvm" Version="24.1.6" />
|
||
```
|
||
|
||
3. **App.xaml 无需修改**:DevExpress 主题通过 NuGet 包自动加载,无需在 App.xaml 中手动添加资源字典。
|
||
|
||
4. **DevExpress 常用控件**:
|
||
|
||
| 控件 | NuGet 包 | 用途 |
|
||
|------|---------|------|
|
||
| DataGrid | DevExpress.Wpf.Grid | 数据表格,支持分组、过滤、排序、虚拟化 |
|
||
| TreeList | DevExpress.Wpf.Grid | 树形列表(与 DataGrid 同一包) |
|
||
| LayoutControl | DevExpress.Wpf.LayoutControl | 布局容器,自动排列子元素 |
|
||
| DockLayoutManager | DevExpress.Wpf.Docking | 可停靠面板,类似 VS 的窗口布局 |
|
||
| RibbonControl | DevExpress.Wpf.Ribbon | 功能区工具栏,类似 Office 的 Ribbon |
|
||
| ChartControl | DevExpress.Wpf.Charts | 图表控件 |
|
||
| RichEditControl | DevExpress.Wpf.RichEdit | 富文本编辑器 |
|
||
|
||
5. **DevExpress 主题选择**:
|
||
|
||
可用主题包(选择一个即可):
|
||
- `DevExpress.Wpf.Themes.Win11Light` - Win11 浅色主题
|
||
- `DevExpress.Wpf.Themes.Win11Dark` - Win11 深色主题
|
||
- `DevExpress.Wpf.Themes.Office2019White` - Office 2019 白色主题
|
||
- `DevExpress.Wpf.Themes.Office2019Colorful` - Office 2019 彩色主题
|
||
- `DevExpress.Wpf.Themes.VS2019Blue` - Visual Studio 2019 蓝色主题
|
||
- `DevExpress.Wpf.Themes.VS2019Dark` - Visual Studio 2019 深色主题
|
||
|
||
主题切换代码:
|
||
|
||
```csharp
|
||
using DevExpress.Xpf.Core;
|
||
|
||
// 在应用启动时设置主题
|
||
ApplicationThemeHelper.UpdateApplicationThemeName("Win11.Light");
|
||
```
|
||
|
||
6. **plan 中应包含的 rules 更新**:
|
||
- 创建 `.agents/rules/devexpress-wpf.md`
|
||
- 说明常用控件的使用方法(DataGrid、TreeList、LayoutControl、Docking、Ribbon 等)
|
||
- 说明主题选择方式
|
||
- 更新 `.agents/rules/architecture.md`,在"核心技术组件"部分添加 DevExpress WPF 说明
|
||
|
||
### 参考材料:MAX.HandyControl 配置要点
|
||
|
||
如果用户选择 MAX.HandyControl(内部 fork),生成 plan 时需包含以下要点:
|
||
|
||
> **强制遵守:** 使用 NuGet 包 `MAX.HandyControl`,**禁止**引用官方包 `HandyControl`。程序集名与代码命名空间仍为 `HandyControl`,因此 pack URI / `using` 写法与官方兼容。本地源码:`{LIBS_ROOT}HandyControl\`(路径变量见 `max-libraries-reference.md`)。
|
||
|
||
1. **添加 MAX.HandyControl NuGet 包**(`Source/PipeReviewReport/PipeReviewReport.csproj`):
|
||
|
||
```xml
|
||
<ItemGroup>
|
||
<PackageReference Include="MAX.HandyControl" />
|
||
</ItemGroup>
|
||
```
|
||
|
||
2. **在 App.xaml 中添加 HandyControl 资源字典**(`Source/PipeReviewReport/App.xaml`):
|
||
|
||
```xml
|
||
<Application.Resources>
|
||
<ResourceDictionary>
|
||
<ResourceDictionary.MergedDictionaries>
|
||
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/SkinDefault.xaml"/>
|
||
<ResourceDictionary Source="pack://application:,,,/HandyControl;component/Themes/Theme.xaml"/>
|
||
</ResourceDictionary.MergedDictionaries>
|
||
</ResourceDictionary>
|
||
</Application.Resources>
|
||
```
|
||
|
||
3. **在需要使用 HandyControl 控件的 XAML 文件中添加命名空间**:
|
||
|
||
```xml
|
||
xmlns:hc="https://handyorg.github.io/handycontrol"
|
||
```
|
||
|
||
4. **HandyControl 常用控件示例**:
|
||
|
||
| 控件 | XAML 标签 | 说明 |
|
||
|------|----------|------|
|
||
| Button | `<hc:Button>` | 带动画效果的按钮 |
|
||
| TextBox | `<hc:TextBox>` | 带水印效果的文本框;**必须** `MaxLength="{x:Static shared:InputLimits.Text}"`(路径片段用 `Path`) |
|
||
| NumericUpDown | `<hc:NumericUpDown>` | 数值输入框 |
|
||
| PasswordBox | `<hc:PasswordBox>` | 密码输入框;**必须**显式 `MaxLength` |
|
||
| ComboBox | `<hc:ComboBox>` | 下拉选择框;不要用可编辑 ComboBox 收自由文本,改用 TextBox |
|
||
| CheckBox | `<hc:CheckBox>` | 复选框 |
|
||
| RadioButton | `<hc:RadioButton>` | 单选按钮 |
|
||
| DatePicker | `<hc:DatePicker>` | 日期选择器 |
|
||
| TimePicker | `<hc:TimePicker>` | 时间选择器 |
|
||
| DateTimePicker | `<hc:DateTimePicker>` | 日期时间选择器 |
|
||
| ToggleSwitch | `<hc:ToggleSwitch>` | 开关控件 |
|
||
| ProgressBar | `<hc:ProgressBar>` | 进度条 |
|
||
| Slider | `<hc:Slider>` | 滑块 |
|
||
| ToggleButton | `<hc:ToggleButton>` | 切换按钮 |
|
||
| ProgressButton | `<hc:ProgressButton>` | 带进度按钮 |
|
||
| GroupBox | `<hc:GroupBox>` | 分组框 |
|
||
| Card | `<hc:Card>` | 卡片容器 |
|
||
| Divider | `<hc:Divider>` | 分隔线 |
|
||
| ScrollViewer | `<hc:ScrollViewer>` | 滚动视图 |
|
||
| MessageBox | `HandyControl.Controls.MessageBox` | 消息对话框 |
|
||
|
||
5. **HandyControl 消息框集成**(重写 `MessageBoxServiceEx`):
|
||
|
||
修改 `Source/PipeReviewReport.Framework/ViewModelServices/MessageBoxServiceEx.cs`,把内部的系统默认 MessageBox 替换为 HandyControl 的实现:
|
||
|
||
```csharp
|
||
using HandyControl.Controls;
|
||
|
||
internal class MessageBoxServiceEx : IMessageBoxService
|
||
{
|
||
public void ShowInfo(string message)
|
||
{
|
||
MessageBox.Show(message, "信息", MessageBoxButton.OK, MessageBoxImage.Information);
|
||
}
|
||
|
||
public bool ShowYesNoQuestion(string message)
|
||
{
|
||
var result = MessageBox.Show(message, "确认", MessageBoxButton.YesNo, MessageBoxImage.Question);
|
||
return result == MessageBoxResult.Yes;
|
||
}
|
||
|
||
// 其他方法实现...
|
||
}
|
||
```
|
||
|
||
**在 View 中注册**(如果引用了 UserControlStyle 或 DialogStyle.Base 则不需要再额外定义):
|
||
|
||
```xml
|
||
<dxmvvm:Interaction.Behaviors>
|
||
<f:MessageBoxServiceEx/>
|
||
</dxmvvm:Interaction.Behaviors>
|
||
```
|
||
|
||
**在 ViewModel 中使用**:
|
||
|
||
```csharp
|
||
public IMessageBoxServiceEx MessageBoxService => GetService<IMessageBoxServiceEx>();
|
||
```
|
||
|
||
6. **HandyControl 主题切换**:
|
||
|
||
HandyControl 支持多种主题,通过 App.xaml 中的资源字典控制:
|
||
- `SkinDefault.xaml` + `Theme.xaml`:默认主题
|
||
- `SkinViolet.xaml` + `Theme.xaml`:紫色主题
|
||
- `SkinDark.xaml` + `Theme.xaml`:深色主题
|
||
|
||
代码切换主题:
|
||
|
||
```csharp
|
||
using HandyControl.Tools;
|
||
|
||
// 切换主题
|
||
HandyControl.Tools.ControlHelper.SetTheme(App.Current, "主题名称");
|
||
```
|
||
|
||
7. **plan 中应包含的 rules 更新**:
|
||
- 创建 `.agents/rules/handycontrol-usage.md`(写明包名为 `MAX.HandyControl`,禁止官方包)
|
||
- 说明常用控件的使用方法
|
||
- 说明主题切换方式
|
||
- 提供常见场景的代码示例
|
||
- 更新 `.agents/rules/architecture.md`,在"核心技术组件"部分添加 MAX.HandyControl 说明
|
||
- 确认 `max-libraries-reference.md` 已包含 MAX.HandyControl 源码路径
|
||
|
||
### 参考材料:默认数据库 / 图表说明
|
||
|
||
- **FreeSql + SQLite**:项目默认已配置,支持 Code First、自动同步表结构、Repository 模式。详见 `.agents/rules/architecture.md`。
|
||
- **ScottPlot5**:通过 `MAX.Common.Plot5` 封装,适合波形图、数据可视化、实时数据。已引用在 Framework 项目中。
|
||
|
||
---
|
||
|
||
## Step 3 — 第二轮:索要业务材料与设计原型
|
||
|
||
向用户说明:**仅凭技术栈选择无法生成贴合业务的完整计划**,需要进一步资料才能产出可执行的最终 plan。
|
||
|
||
### 3.1 通过 AskQuestion 收集结构化信息
|
||
|
||
- prompt: "为了生成贴合业务的完整计划,请提供以下信息(可多选你需要提供的材料类型)"
|
||
- allow_multiple: true
|
||
- options:
|
||
- `ui-mockups`: "我会提供 UI 设计原型图 / 效果图(Figma、Axure、PNG 等)"
|
||
- `requirements-doc`: "我会提供业务需求文档 / 功能清单"
|
||
- `data-model`: "我会提供数据模型 / 数据库设计"
|
||
- `flow-diagrams`: "我会提供业务流程图 / 状态机图"
|
||
- `hardware-interaction`: "涉及硬件读写操作(传感器、PLC、串口、GPIB、USB 设备等)"
|
||
- `reference-products`: "我有参考产品 / 竞品链接"
|
||
- `none-now`: "暂无额外材料,按通用方案生成"
|
||
|
||
### 3.2 通过自由对话收集详细材料
|
||
|
||
向用户**明确请求**以下材料(根据用户在 3.1 的选择,引导用户提供):
|
||
|
||
1. **UI 设计原型图**:
|
||
- 直接粘贴图片到对话,或提供图片路径
|
||
- 说明:主窗口布局、导航结构、关键页面、配色风格、控件偏好
|
||
- 如果使用 DevExpress/HandyControl,原型图能帮助确定具体用哪些控件
|
||
|
||
2. **业务需求文档**:
|
||
- 核心功能列表(用一句话描述每个功能)
|
||
- 用户角色与权限(如果有)
|
||
- 关键业务流程(从用户操作角度描述)
|
||
|
||
3. **数据模型**:
|
||
- 主要实体及其关系
|
||
- 已有的数据库表结构(如果有)
|
||
- 数据规模估算(影响选型:SQLite vs SQL Server)
|
||
|
||
4. **参考产品 / 竞品**:
|
||
- 链接或截图
|
||
- 希望借鉴的部分(布局、交互、功能)
|
||
|
||
5. **特殊要求**:
|
||
- 性能要求(实时性、并发、数据量)
|
||
- 安全 / 合规要求(数据加密、审计、合规标准)
|
||
- 部署方式(单机、ClickOnce、内网分发)
|
||
- 多语言需求(项目已内置 Strings 多语言机制)
|
||
|
||
6. **硬件读写需求**(如果用户在 Step 3.1 选择了 `hardware-interaction`):
|
||
- 涉及的硬件类型与型号(传感器、PLC、串口设备、GPIB 仪器、USB 设备等)
|
||
- 通信协议(Modbus、TCP/IP、RS-232/485、GPIB、自定义协议等)
|
||
- 数据采集频率与实时性要求(毫秒级、秒级、分钟级)
|
||
- 硬件数量、并发连接要求
|
||
- 是否有已有的硬件 SDK / DLL / 驱动
|
||
- **关键决策:初期是否使用 Mock 虚拟设备开发**(详见下文)
|
||
|
||
### 硬件 Mock 策略(必须询问用户)
|
||
|
||
当用户提供了涉及硬件读写的原型图、需求书等材料后,**必须在生成 Plan 之前向用户确认**:
|
||
|
||
> "你提供的材料中涉及 [XX 硬件] 的读写操作。在项目初期构建阶段,建议先使用 **Mock 虚拟设备** 代替真实硬件进行开发和调试——这样可以脱离硬件环境独立开发、快速验证 UI 和业务流程。后续再替换为真实设备的实现。
|
||
>
|
||
> 这套方案通过 **接口 + 实现类** 的架构设计:所有业务代码只依赖接口,Mock 实现和真实硬件实现各自实现同一接口。后续替换时**只需替换实现类**,引用接口的地方完全不用动。"
|
||
|
||
然后使用 `AskQuestion` 让用户确认:
|
||
|
||
- prompt: "硬件读写策略:初期是否使用 Mock 虚拟设备?"
|
||
- options:
|
||
- `mock-first`: "是,先用 Mock 虚拟设备开发,后续替换为真实硬件(推荐)"
|
||
- `real-hardware`: "直接使用真实硬件开发"
|
||
|
||
无论用户选择哪种策略,Plan 中都必须包含:
|
||
|
||
- **硬件接口定义**:为每种硬件类型定义清晰的 C# 接口(`IHardwareXxx`),包含所有读写操作方法
|
||
- **接口与实现分离**:接口放在共享层(Framework 或 Shared 项目),实现类放在独立项目或模块中
|
||
- **DI 注册**:通过 Autofac 注册接口与实现类的绑定,替换时只需改 DI 注册,无需改业务代码
|
||
- **如果选择 mock-first**:Plan 中包含 Mock 实现类的创建任务(模拟数据返回、模拟设备状态、模拟异常场景)
|
||
- **如果选择 real-hardware**:Plan 中包含真实硬件 SDK 集成、驱动安装、连接测试等任务
|
||
|
||
### 硬件相关 rules / skills 生成
|
||
|
||
Plan 中必须包含根据实际硬件需求生成对应的 **skill** 或 **rule** 的任务:
|
||
|
||
- 如果硬件有专用的通信协议(如 Modbus),在 Plan 的「rules 与 skills 更新」章节中增加创建对应 skill 的任务
|
||
- 如果涉及通用串口通信,创建 `reference-serial-port` skill
|
||
- 如果涉及 GPIB 仪器控制,创建 `reference-gpib` skill
|
||
- 如果硬件有官方 SDK,创建该 SDK 的使用规范 rule
|
||
|
||
Plan 应明确列出需要创建哪些 skill/rule,并在「任务执行顺序」中安排对应的轮次。
|
||
|
||
**重要:等待用户提供实际材料后再进入 Step 4。** 如果用户选择 `none-now`,可以直接进入 Step 4 基于通用方案生成 plan,但要在 plan 中明确标注「待补充业务材料」的部分。
|
||
|
||
---
|
||
|
||
## Step 4 — 生成完整计划(Plan v2 - 最终交付)
|
||
|
||
综合 Step 1 技术栈 + Step 3 业务材料,生成最终的、可执行的完整项目初始化计划。
|
||
|
||
### 4.1 Plan 必须包含的章节
|
||
|
||
最终的 plan 文件应包含以下结构(写入 `.cursor/plans/initialize-plan.md`):
|
||
|
||
```markdown
|
||
# 项目初始化计划
|
||
|
||
## 1. 项目概述
|
||
- 项目名称、目标、核心业务(基于 Step 3 业务材料总结)
|
||
- 技术栈总览表
|
||
|
||
## 2. 环境与依赖(NuGet 包)
|
||
- 按项目分组列出所有需要添加的包(包名、版本、用途)
|
||
- 标注哪些是「已包含」、哪些是「需新增」、哪些是「需移除」
|
||
|
||
## 3. 配置文件变更
|
||
- csproj 修改清单
|
||
- App.xaml 资源字典(如适用)
|
||
- Directory.Build.props
|
||
- NLog.config / 其他配置
|
||
|
||
## 4. 项目结构与模块划分
|
||
- 基于业务需求建议的模块划分(Modules)
|
||
- 每个模块的职责
|
||
- 主要 View / ViewModel 清单(基于 UI 原型图)
|
||
|
||
## 5. 基础设施层
|
||
- 数据库初始化(FreeSql 配置、连接串、Code First 同步策略)
|
||
- 日志配置
|
||
- 缓存方案
|
||
- DI 容器注册(Autofac + MAX.Core 约定)
|
||
|
||
## 6. 框架层
|
||
- 需要新增/修改的容器服务(ISingletonDependency)
|
||
- 需要新增/修改的 ViewModel 服务(ServiceBase)
|
||
- 通用基础设施(消息框、对话框、加载指示器)
|
||
|
||
## 7. 硬件抽象层(如涉及硬件读写)
|
||
|
||
> **重要**:如果项目涉及硬件读写,必须先在 Step 3.2 向用户确认 Mock 策略后再填充本章节。
|
||
|
||
### 7.1 硬件接口定义
|
||
|
||
为每种硬件类型定义 C# 接口,所有业务代码通过接口访问硬件,不直接依赖具体实现类:
|
||
|
||
| 接口 | 对应硬件 | 核心方法 | 放置位置 |
|
||
|------|---------|---------|---------|
|
||
| `ISensorReader` | 温度传感器 | `ReadValueAsync()`, `CalibrateAsync()` | Framework/Interfaces/ |
|
||
| `IPlcController` | PLC 控制器 | `ConnectAsync()`, `SendCommandAsync()` | Framework/Interfaces/ |
|
||
| `ISerialPortDevice` | 串口设备 | `OpenAsync()`, `SendAsync()`, `ReceiveAsync()` | Framework/Interfaces/ |
|
||
|
||
**接口设计原则**:
|
||
- 接口只暴露硬件能力,不暴露通信细节(波特率、串口号等配置参数通过构造函数或初始化方法传入)
|
||
- 所有 I/O 操作使用 `async Task<T>`,支持取消(`CancellationToken`)
|
||
- 包含 `ConnectAsync()` / `DisconnectAsync()` 生命周期方法
|
||
- 包含健康检查方法(`IsConnected` 属性或 `PingAsync()`)
|
||
- 接口放在 Framework 或 Shared 项目中,便于所有模块引用
|
||
|
||
### 7.2 Mock 实现类(初期开发用)
|
||
|
||
如果用户选择 `mock-first` 策略:
|
||
|
||
| Mock 类 | 实现接口 | 模拟策略 |
|
||
|---------|---------|---------|
|
||
| `MockSensorReader` | `ISensorReader` | 返回预设的模拟数据,可配置波动范围和异常概率 |
|
||
| `MockPlcController` | `IPlcController` | 内存状态机模拟,可预设响应序列 |
|
||
| `MockSerialPortDevice` | `ISerialPortDevice` | 内存队列模拟收发,支持注入测试数据 |
|
||
|
||
Mock 实现类放在 `Source/PipeReviewReport.Framework/Mocks/` 目录下。
|
||
|
||
### 7.3 真实硬件实现类(后续替换)
|
||
|
||
| 实现类 | 实现接口 | 依赖 |
|
||
|--------|---------|------|
|
||
| `RealSensorReader` | `ISensorReader` | 硬件 SDK/DLL |
|
||
| `RealPlcController` | `IPlcController` | PLC SDK |
|
||
| `RealSerialPortDevice` | `ISerialPortDevice` | `System.IO.Ports` |
|
||
|
||
真实实现类放在 `Source/PipeReviewReport.Framework/Hardware/` 或独立项目中。
|
||
|
||
### 7.4 DI 注册策略
|
||
|
||
通过 Autofac 的条件注册,替换时只需改一处:
|
||
|
||
```csharp
|
||
// 开发阶段:注册 Mock 实现
|
||
builder.RegisterType<MockSensorReader>().As<ISensorReader>().SingleInstance();
|
||
|
||
// 生产阶段:替换为真实实现(只需改这一行,其余代码不动)
|
||
// builder.RegisterType<RealSensorReader>().As<ISensorReader>().SingleInstance();
|
||
```
|
||
|
||
推荐使用配置文件或编译条件(`#if DEBUG`)控制注册,避免手动改代码。
|
||
|
||
### 7.5 替换保障
|
||
|
||
- **业务代码只引用接口**:所有 ViewModel、Service 中只声明 `ISensorReader`,不引用任何 `MockXxx` 或 `RealXxx`
|
||
- **替换清单**:Plan 中明确列出替换时需修改的文件(通常只有 DI 注册文件 1 个)
|
||
- **测试覆盖**:Mock 类和真实实现类共用同一套接口测试,确保行为一致
|
||
|
||
## 8. UI 层(基于设计原型)
|
||
- 主窗口布局方案
|
||
- 导航结构
|
||
- 关键页面拆分(对照原型图逐页说明)
|
||
- 主题/样式策略
|
||
|
||
## 9. 数据模型与实体
|
||
- 主要实体类设计
|
||
- 实体关系
|
||
- FreeSql 映射约定
|
||
|
||
## 10. 业务流程实现路径
|
||
- 按业务流程列出实现步骤
|
||
- 每个步骤涉及的 View / ViewModel / Service
|
||
|
||
## 11. rules 与 skills 更新
|
||
- 需要更新的现有 rules(architecture.md、wpf-core.md、wpf-xaml.md 等)
|
||
- 需要新增的 rules(如 devexpress-wpf.md、handycontrol-usage.md、硬件相关 skill/rule)
|
||
- 需要新增的 skills
|
||
|
||
## 12. 文档
|
||
- README.md 更新内容
|
||
- 架构文档
|
||
- 开发指南
|
||
|
||
## 13. 任务执行顺序(分模块、多轮执行)
|
||
|
||
**核心原则:Plan 是给多轮对话逐步执行的,不允许一次性写完所有代码。** 任务拆分必须满足:
|
||
|
||
- **按模块拆分**:每个功能模块(或页面)是一个独立的执行单元,一轮对话只负责一个模块。
|
||
- **按层级拆分**:基础设施层 → 框架层 → 业务模块层,先完成底层再建上层。
|
||
- **每轮有明确的验收标准**:每轮结束必须能编译通过并对应当前阶段的功能。
|
||
|
||
### 推荐的分轮执行方案
|
||
|
||
| 轮次 | 范围 | 说明 |
|
||
|------|------|------|
|
||
| **Round 1** | 基础设施配置 | NuGet 包安装、slnx 更新、App.xaml 资源字典、DI 注册基建设置 |
|
||
| **Round 2** | 框架层完善 | Model/Entity 实体类、FreeSql CodeFirst 配置、通用服务(消息框等) |
|
||
| **Round 3-N** | 功能模块逐一实现 | 每个模块包含:Views + ViewModels + Services,一模块一轮 |
|
||
| **Round N+1** | 主窗口整合 | 组装各模块到主窗口(Shell),配置导航、菜单结构 |
|
||
| **Round 最后** | 验收与修复 | 完整编译 + 启动验证 + 原型图对比修复 |
|
||
|
||
### 任务标注格式
|
||
|
||
每个任务标注:
|
||
- 优先级(P0 必须 / P1 重要 / P2 可选)
|
||
- 所属轮次(Round X)
|
||
- 依赖关系(任务 B 依赖任务 A)
|
||
- 预计工作量(小 / 中 / 大)
|
||
- 验证标准(每个任务如何确认完成)
|
||
|
||
### 示例
|
||
|
||
```markdown
|
||
### Round 1: 基础设施配置
|
||
|
||
- [P0] 安装 NuGet 包 → 验证:dotnet restore 无报错
|
||
- [P0] 更新 slnx 添加新模块项目 → 验证:dotnet build 无报错
|
||
- [P1] 配置 App.xaml 资源字典 → 验证:启动后主题生效
|
||
|
||
### Round 3: 报警日志模块
|
||
|
||
- [P0] 创建 AlarmLogMainView.xaml + AlarmLogMainViewModel → 验证:页面可导航到
|
||
- [P0] 实现报警数据查询 Service → 验证:Service 返回测试数据
|
||
- [P1] 集成图表库显示报警趋势 → 验证:图表正确渲染
|
||
```
|
||
|
||
## 14. 验收标准
|
||
- 编译通过:dotnet build 无错误
|
||
- 启动正常:应用可正常启动并显示主窗口
|
||
- 基础流程跑通:(根据业务材料定义的最小可用流程)
|
||
|
||
## 15. 待补充 / 待确认事项
|
||
- 列出所有未确定的决策点(用户在 Step 3 未提供的部分)
|
||
- 列出需要用户进一步澄清的问题
|
||
|
||
## 16. 执行阶段代码质量准则
|
||
|
||
以下准则应作为 Plan 的一部分写入,指导后续执行对话中 AI 生成代码的质量。这些不是 Plan 生成阶段需要执行的,而是 Plan 中为执行阶段预设的约束。
|
||
|
||
### 16.1 csproj 与 slnx 管理
|
||
|
||
- 每新建一个 `.csproj` 项目,必须同时将其添加到解决方案文件(`.slnx`)中。
|
||
- Plan 中应明确列出每个新建项目对应的 slnx 节位置。
|
||
|
||
### 16.2 XAML 命名空间规范
|
||
|
||
AI 生成 View.xaml 时常见的错误是使用错误的命名空间前缀(如 `local:XXXViewModel`)。Plan 中应规定正确的 XAML 命名空间用法:
|
||
|
||
- **不要在 XAML 中使用 `d:DataContext` 或错误的 `local:` 前缀指定 ViewModel 类型。**
|
||
- 正确做法是使用模块专用的命名空间前缀 + `core:DISource`:
|
||
|
||
```xml
|
||
<!-- 正确示例:使用 vms 命名空间 + DI Source -->
|
||
<UserControl xmlns:vms="clr-namespace:CFBG_HostSoftware.AlarmLog.ViewModels"
|
||
DataContext="{core:DISource Type=vms:AlarmLogMainViewModel}">
|
||
```
|
||
|
||
- Plan 中应明确每个模块 View 对应的 ViewModel 命名空间和类型,作为执行阶段的参照。
|
||
|
||
### 16.3 自定义 Window 的默认行为
|
||
|
||
- 优先使用库自带或 WPF 自带的 `Window` 作为窗口基类。
|
||
- 如果确实需要自定义 `Window` 样式,必须保留标准 Windows 窗口行为:标题栏拖拽移动、双击最大化/还原、系统菜单(右键标题栏)、窗口边框调整大小等。
|
||
- 推荐:直接使用 WPF 原生 `Window` + 样式模板,而非完全重写窗口行为。
|
||
|
||
### 16.4 图表控件(ScottPlot / MAX.Common.Plot5)
|
||
|
||
- `MAX.Common.Plot5` 暴露的不是 ScottPlot 原生的 `WpfPlot`,而是封装的 `PlotControl`。
|
||
- 如果 Plan 中涉及使用图表,应在 Framework 项目中新建一个子类继承 `PlotControl`:
|
||
|
||
```csharp
|
||
// Source/PipeReviewReport.Framework/Controls/PlotControlEx.cs
|
||
using MAX.Common.Plot5;
|
||
|
||
namespace PipeReviewReport.Framework.Controls;
|
||
|
||
public class PlotControlEx : PlotControl
|
||
{
|
||
// 可扩展自定义绘图逻辑
|
||
}
|
||
```
|
||
|
||
- 所有业务模块中的图表使用 `PlotControlEx` 而非直接使用 `PlotControl` 或 `WpfPlot`。
|
||
```
|
||
|
||
### 4.2 生成 Plan 的注意事项
|
||
|
||
1. **基于实际材料**:UI 部分、模块划分、数据模型必须基于 Step 3 收到的材料,不要凭空编造业务细节。
|
||
2. **基于现状检查**:利用 Step 0 的检查结果,标注已有项、避免重复添加、优先复用已有模块和配置。
|
||
3. **标注不确定性**:对于材料不足的部分,在「待补充事项」中明确列出,不要假装知道。
|
||
4. **保持可执行性**:每个任务都要具体到「改哪个文件 / 加什么代码」,让用户(或后续 AI 对话)可以直接照做。
|
||
5. **遵循项目约定**:所有方案必须符合 `.agents/rules/` 下的现有规范(MVVM 模式、DI 约定、命名空间约定等)。
|
||
6. **分模块可迭代**:任务拆分必须支持多轮对话逐步执行(详见「16. 执行阶段代码质量准则」),不允许设计为一次性的全量代码生成。
|
||
7. **写文件**:最终 plan 写入 `.cursor/plans/initialize-plan.md`(如果目录不存在,在 plan 中说明需要先创建)。
|
||
8. **输出摘要**:在对话中输出 plan 的摘要 + 文件路径,提醒用户确认后再执行。
|
||
|
||
---
|
||
|
||
## 检查清单
|
||
|
||
- [ ] Step 0:已完成项目现状检查(slnx、csproj、现有模块、App.xaml、rules、skills 等)
|
||
- [ ] Step 0:检查结果已整理,作为 Plan 中「已有」标注的依据
|
||
- [ ] Step 1:已通过 AskQuestion 收集完所有技术栈问题(10 个问题)
|
||
- [ ] Step 2:已生成并展示 Plan v1(技术栈 + 现状检查结果)
|
||
- [ ] Step 3:已通过 AskQuestion 询问材料类型,并请求用户实际提供
|
||
- [ ] Step 3:如涉及硬件读写(`hardware-interaction`),已向用户确认 Mock 策略(mock-first / real-hardware)
|
||
- [ ] Step 3:已等待用户材料(或用户明确选择「暂无」)
|
||
- [ ] Step 4:已综合所有材料生成完整 plan
|
||
- [ ] Step 4:plan 包含「分模块多轮执行」方案,任务按模块拆分、可逐轮执行
|
||
- [ ] Step 4:plan 包含「执行阶段代码质量准则」(XAML 命名空间、Window 行为、PlotControl 使用、slnx 更新)
|
||
- [ ] Step 4:如涉及硬件,plan 包含硬件抽象层(接口定义、Mock/真实实现、DI 注册策略、替换保障)及硬件相关 skill/rule 创建任务
|
||
- [ ] Step 4:plan 已写入 `.cursor/plans/initialize-plan.md`
|
||
- [ ] Step 4:已在对话中输出摘要并提醒用户确认
|
||
- [ ] 全程未执行任何实际代码 / 配置 / 文件变更
|
||
|
||
## 重要约束
|
||
|
||
1. **本 skill 是 Plan 生成器,不是执行器**:在整个过程中,禁止修改任何源码、配置、csproj、rules、skills。
|
||
2. **三步流程缺一不可**:Step 0 现状检查 → Step 1-2 技术栈 → Step 3-4 业务材料,不能跳过任何步骤。
|
||
3. **Plan 必须支持分模块多轮执行**:不允许生成"一次性全量代码写入"式的 plan。任务必须按模块/页面拆分,每轮可独立验证。
|
||
4. **不要替用户做业务决策**:如果材料不足,明确列出「待补充事项」,不要编造业务流程或数据模型。
|
||
5. **保持中立**:推荐技术方案时给出理由和备选,不要绝对化。
|
||
6. **最终交付物只有一份 plan 文件**:除了 `.cursor/plans/initialize-plan.md` 外,不应创建任何其他文件。
|