Skip to content

Latest commit

 

History

History
150 lines (120 loc) · 6.97 KB

copilot-instructions.md

File metadata and controls

150 lines (120 loc) · 6.97 KB

GitHub Copilot 指导文档

DotNetCampus Terminal 项目的 AI 协作开发指南。

项目概述

基于 .NET 9.0 和 Consolonia 的远程设备连接管理工具，采用多AI协同开发模式。

🤖 AI角色自动认领机制：如果用户在提示词中指定了AI的角色（如"你是文档维护员"、"你是UI界面设计师"等），AI应该：

  1. 立即查看 .github/AI任务分工.md 文件认领对应职位
  2. 阅读该角色的必读文档（角色经验总结文档）
  3. 按照职位要求和经验总结执行后续行动
  4. 遵循该角色的技术规范和工作流程

技术栈：.NET 9.0, Consolonia, SSH.NET, System.Text.Json, DotNetCampus.Logger

核心编码规范

命名约定

  • 类名/方法名/属性名：PascalCase
  • 私有字段：camelCase + 下划线前缀 _fieldName
  • 接口：以I开头

代码风格

  • 启用 nullable 引用类型
  • 异步方法以 Async 结尾
  • 使用依赖注入
  • 添加 XML 文档注释

常见错误提醒 ⚠️

以下是AI同事经常犯的错误，必须避免：

  1. 日志命名空间：使用 DotNetCampus.Logging 而不是 DotNetCampus.Logger（前者是命名空间，后者是库名称）
  2. 日志方法名：使用 Log.Warn 而不是 Log.Warning
  3. 编译文件占用：dotnet build 提示文件被占用时，这是正常现象（VS Code的bug），不要报错
  4. SSH.NET引用：确保添加 using Renci.SshNet;

兼容性原则

重要：本项目不需要考虑兼容性问题

  • 不使用 [Obsolete] 标记
  • 不保留旧方法或接口
  • 不添加"兼容旧版本"等注释说明
  • 直接重构和替换，无需向后兼容
  • 项目处于开发阶段，API可以自由变更

代码重构原则

  • 400行规则：代码超过400行时，需要酌情考虑重构
  • 600行硬限制：代码超过600行时，必须考虑重构
  • 例外情况：超过600行但非常单一易懂的代码（如大型枚举）可以保留
  • 重构方式：拆分类、提取方法、分离职责

Consolonia 关键要点

核心概念

  • 像素 = 字符：每个像素对应一个控制台字符
  • 文件扩展名：使用 .axaml 而不是 .xaml
  • 命名空间：xmlns:console="https://github.com/jinek/consolonia"
  • 主题：推荐使用 TurboVisionDarkTheme

重要差异

  • 使用 AvaloniaList<T> 替代 ObservableCollection<T>
  • 使用 console:LineBrush 配置边框样式
  • 按钮禁用阴影：console:ButtonExtensions.Shadow="False"
  • 异步UI更新：Dispatcher.UIThread.InvokeAsync

性能优化

  • 使用 VirtualizingStackPanel 处理大数据集
  • 选择合适的绑定模式（OneTime/OneWay/TwoWay）
  • 使用 x:DataType 实现强类型绑定

日志规范

使用 DotNetCampus.Logger：

  • 使用静态 Log 类，无需依赖注入
  • 日志格式：Log.Info("[标签] 消息内容")
  • 标签约定：[FileSync] [SSH] [UI] [Config] [Network] [System]
  • 常用方法：Log.Info(), Log.Warn(), Log.Error()

协作要点

开发流程

  1. 🔥 首要步骤：查看 .github/AI任务分工.md 确定自己的角色
  2. 📖 必读文档：阅读对应角色的经验总结文档（详见下方技术文档索引）
  3. 📚 技术查阅：查看 .github/knowledge/ 相关技术文档
  4. 接口设计优先，确保模块依赖清晰
  5. 及时测试，避免积累错误
  6. 知识更新到知识库和经验总结，便于复用

求助时机

以下情况建议寻求人类帮助：

  • 多个命名空间冲突
  • API版本兼容性问题
  • 复杂的泛型推断失败
  • 平台特定显示问题
  • 反复犯错：如果发现自己在重复犯同样的错误

注意：dotnet build 文件占用问题是VS Code的已知bug，属于正常现象，无需求助。

技术文档索引

详细的技术资料已整理到 .github/knowledge/ 目录：

角色经验总结（首要阅读）

  • UI界面设计师-核心经验总结.md - UI设计师核心经验
  • 文件同步工程师-核心经验总结.md - 文件同步工程师核心经验
  • 配置管理专家-核心经验总结.md - 配置管理专家核心经验
  • SSH连接专家-核心经验总结.md - SSH连接专家核心经验
  • 文档维护员-核心经验总结.md - 文档维护员核心经验

技术参考文档

详细的技术资料已按照以下结构组织，AI可根据具体技术需求选择相应文档：

依赖库使用指南

  • 依赖库文档/Consolonia/01-快速参考指南.md - Consolonia快速参考
  • 依赖库文档/Consolonia/02-架构核心要点.md - 架构设计要点
  • 依赖库文档/Consolonia/03-UI框架使用.md - UI框架详细使用
  • 依赖库文档/Consolonia/04-UI设计模式最佳实践.md - UI设计模式
  • 依赖库文档/DotNetCampus.Logger/01-日志框架使用指南.md - 日志使用指南
  • 依赖库文档/SSH.NET/01-基础使用指南.md - SSH.NET基础使用
  • 依赖库文档/SSH.NET/02-文件同步实现.md - 文件同步指南
  • 依赖库文档/System.Text.Json/01-JSON配置系统使用指南.md - JSON配置系统使用
  • 依赖库文档/DotNet9/01-新特性在项目中的应用.md - .NET 9新特性

技术设计文档

  • 技术设计文档/界面设计/01-Terminal界面开发指南.md - Terminal界面开发
  • 技术设计文档/界面设计/02-SSH设备信息视图设计.md - SSH设备视图设计
  • 技术设计文档/界面设计/03-进度显示和数据绑定.md - 进度显示设计
  • 技术设计文档/界面设计/04-ViewModel重构最佳实践.md - ViewModel重构
  • 技术设计文档/界面设计/05-TUI与Shell集成解决方案.md - Shell集成方案
  • 技术设计文档/界面设计/06-交互式命令模式设计.md - 交互式命令设计
  • 技术设计文档/配置管理/01-JSON配置系统架构设计.md - 配置架构设计
  • 技术设计文档/配置管理/02-配置保存功能实现.md - 配置保存实现
  • 技术设计文档/配置管理/03-配置数据源迁移方案.md - 配置迁移方案
  • 技术设计文档/配置管理/04-设备唯一标识符设计.md - 设备ID设计
  • 技术设计文档/文件同步/01-远程到本地同步架构.md - 同步架构设计
  • 技术设计文档/文件同步/02-增量同步性能优化.md - 同步性能优化
  • 技术设计文档/文件同步/03-同步错误处理机制.md - 错误处理机制
  • 技术设计文档/SSH连接管理/01-SSH密钥认证配置方案.md - SSH密钥配置
  • 技术设计文档/SSH连接管理/02-多设备连接安全分析.md - 连接安全分析

问题排查指南

  • 问题排查/开发问题快速解答手册.md - 问题解决方案

AI协作经验

  • AI协作经验/实现经验总结/设备唯一ID实现技术总结.md - 设备ID实现经验
  • AI协作经验/AI多角色协作开发经验.md - 多角色协作经验

重要提醒：

  1. 🔥 开始任务前，必须先阅读对应角色的经验总结文档
  2. 📚 遇到技术问题先查阅知识库，避免重复踩坑
  3. 💡 将新的踩坑经验及时更新到经验总结文档中