luban_ui_internal/.github/instructions/prompt.instructions.md

applyTo

applyTo
**

• 说中文
• 这是一个基于Avalonia的项目管理工程，目标是让非程序员也能轻松使用luban管理配置表。
• 命令行是PowerShell使用分号作为命令分隔符

架构说明

🏗️ LubanHub.Core 核心能力库

LubanHub.Core 提供了项目的底层核心能力，优先使用这些服务来实现功能，避免重复造轮子：

📥 下载服务 (ICoreDownloadService)

• 默认下载目录: 系统用户数据目录的LubanHub子目录 (%AppData%\LubanHub\Downloads)
• 目录管理: 获取/设置下载目录
• 进度追踪: 实时下载进度、速度、文件名显示
• 取消支持: 支持CancellationToken取消下载
• 使用场景: Luban版本下载、模板下载、资源文件下载

📁 文件管理服务 (ICoreFileService)

• 文件操作: 创建、删除、复制、移动文件
• 目录操作: 创建、删除、遍历目录
• 异步读写: ReadAllTextAsync/WriteAllTextAsync
• 信息获取: FileInfo/DirectoryInfo
• 使用场景: 配置文件操作、项目文件管理、模板文件处理

⚙️ 进程调用服务 (ICoreProcessService)

• 同步执行: 等待进程完成并获取输出
• 异步执行: 实时获取stdout/stderr输出
• 后台进程: 启动但不等待的进程
• 进程管理: 检查进程状态、杀死进程
• 使用场景: 调用Luban命令行、Git操作、外部工具集成

🗜️ 解压缩服务 (ICoreCompressionService)

• ZIP支持: 完整的ZIP解压缩功能
• 进度追踪: 解压进度回调
• 格式检测: 自动识别压缩格式
• 扩展支持: 预留RAR/7Z接口（需第三方库）
• 使用场景: Luban安装包解压、模板包解压、资源包处理

🔧 依赖注入集成

// 在App.axaml.cs中已配置
services.AddCoreServices(); // 自动注册所有Core服务

⚠️ 扩展原则

• 优先使用: 实现新功能时，首先检查Core是否已提供相关服务
• 必要扩展: 只有在Core无法满足需求时，才考虑扩展Core
• 接口设计: 新增Core功能需要定义接口，保持架构一致性
• 日志集成: 所有Core服务已集成Microsoft.Extensions.Logging

UI设计规范

🎨 主题兼容性

• 深色模式支持: 所有UI元素必须在深色主题下清晰可见，具有足够的对比度
• 浅色模式支持: 所有UI元素必须在浅色主题下保持良好的可读性和视觉效果
• 动态主题切换: 使用DynamicResource绑定，支持运行时主题切换
• 颜色资源化: 避免硬编码颜色值，统一使用主题资源字典中的颜色定义

🎯 交互状态设计

• 主要操作按钮: 使用主题蓝色系，在两种模式下都要突出显示
• 成功/确认状态: 使用绿色系，表示积极操作
• 警告状态: 使用黄色系，提醒用户注意
• 错误/删除状态: 使用红色系，表示危险操作
• 悬停和按下状态: 提供清晰的视觉反馈，确保在两种主题下都有足够的对比度

📝 文字层级

• 主要文字: 使用主题的主要文字颜色，确保最佳可读性
• 次要文字: 使用稍浅的颜色，但仍保持良好的可读性
• 占位符文字: 使用更浅的颜色，明确区分占位符和实际内容
• 禁用文字: 使用最浅的颜色，明确表示不可用状态

🔘 圆角规范

• 按钮圆角: 4px
• 输入框圆角: 4px
• 卡片圆角: 5px
• 列表项圆角: 3px

📏 间距规范

• 小间距: 5px
• 标准间距: 10px
• 中等间距: 15px
• 大间距: 20px
• 页面边距: 20px
• 按钮内边距: 水平15px 垂直8px
• 导航按钮内边距: 水平20px 垂直15px

🎭 动画规范

• 过渡时间: 0.2s (200ms)
• 缓动函数: ease-out
• 支持的过渡: 背景色、前景色、透明度

📱 组件规范

• 导航栏宽度: 200px
• 最小窗口尺寸: 宽度1000px 高度600px
• 设计尺寸: 宽度1200px 高度800px
• 按钮最小高度: 36px
• 输入框最小高度: 32px

🎪 图标使用

• 使用Emoji作为图标: 📚📁📦📱⚙️🎮📊🔧🤖➕🔄📂🌐等
• 图标大小: 导航按钮中正常大小，卡片中40px

🖱️ 交互反馈

• 所有可点击元素必须有悬停状态
• 按钮支持按下状态反馈
• 输入框支持焦点状态
• 列表项支持选中和悬停状态
• 过渡动画让交互更流畅

开发指导

📋 功能实现流程

1. 需求分析: 明确功能需求和用户场景
2. Core检查: 检查LubanHub.Core是否已提供相关服务
3. 服务利用: 优先使用Core服务实现功能逻辑
4. UI设计: 按照设计规范创建用户界面
5. 进度显示: 长时间操作使用底部进度条显示状态
6. 错误处理: 合理的异常处理和用户提示

🎯 常见场景示例

• 文件下载: 使用ICoreDownloadService，进度显示在底部
• Luban调用: 使用ICoreProcessService执行命令行
• 配置管理: 使用ICoreFileService读写配置文件
• 安装包处理: 使用ICoreCompressionService解压
• 目录选择: 集成系统文件对话框（需要时扩展Core）

🔄 服务扩展指南

当需要新功能且Core无法满足时：

1. 在LubanHub.Core/Interfaces添加接口定义
2. 在LubanHub.Core/Services添加实现类
3. 在ServiceCollectionExtensions中注册服务
4. 更新本文档说明新增能力
5. 在App层通过依赖注入使用新服务

📊 UI状态管理

• ViewModelBase: 所有ViewModel继承此基类
• 属性绑定: 使用SetProperty方法通知UI更新
• 命令模式: 使用RelayCommand处理用户交互
• 进度显示: 使用DownloadProgressViewModel显示长时间操作

🎨 主题和样式

• 主题切换: 使用ThemeManager管理深色/浅色主题
• 资源绑定: 所有颜色使用DynamicResource绑定
• 样式复用: 在Styles.axaml中定义通用样式
• 响应式: 支持运行时主题切换