---
description: User preferences for communication and workflow
globs:
alwaysApply: true
---

# 用户偏好（必须遵守）

## 语言
- 永远使用中文回复，无论用户用什么语言输入（用户使用语音输入时系统可能自动翻译为英文）

## 沟通方式
- 用户不懂代码，不需要看代码修改过程
- 不要打开代码文件让用户审阅
- 直接完成修改，只展示最终结果
- 用产品语言描述变更（"改好了，刷新看效果"），而非技术语言
- 用户擅长产品思维和创造力，用这个层面和他沟通

## 进度存档机制（防丢上下文，必须遵守）
- **新对话开始时**：第一件事先读 `阶段总结/session_progress.md`，了解之前做到哪了
- **每完成一个阶段性任务后**：主动更新 `阶段总结/session_progress.md`，记录：
  - 这次做了什么
  - 做到哪一步了
  - 下一步要干什么
  - 遇到了什么问题
- **对话即将结束前**（比如用户说"先到这""下次继续"等）：必须更新存档
- **格式要求**：保持简洁，用产品语言，不要贴大段代码

## Flutter 开发流程（必须遵守）

### 端口管理
- 启动 `flutter run -d chrome` 前，**必须**先杀掉旧进程并确认端口已释放
- 流程：Stop-Process → 等3秒 → 确认端口空闲 → 再启动新进程
- 用完浏览器预览后，**必须**在做其他事之前先关闭 Flutter 进程释放端口
- 永远不要直接换端口来绕过占用，要先清理旧的

### 标准编译流程
```
# 1. 停旧进程
Stop-Process -Id $OLD_PID -Force -ErrorAction SilentlyContinue
Start-Sleep -Seconds 3

# 2. 确认端口空闲
netstat -ano | Select-String ":$PORT"

# 3. 用 web-server 模式启动（不会自动弹Chrome窗口！）
flutter run -d web-server --web-port=$PORT --no-pub

# 4. 手动在 Cursor 内置浏览器打开地址
# browser_navigate → http://localhost:$PORT
```

### 浏览器管理（极其重要）
- **禁止**用 `flutter run -d chrome`，它会自动弹出系统 Chrome 窗口
- **必须**用 `flutter run -d web-server`，只启动服务不弹浏览器
- 用 Cursor 内置浏览器 (browser_navigate) 手动打开地址预览
- 关闭时：先把内置浏览器导航到 about:blank，再停 Flutter 进程
- 如果不小心弹了系统 Chrome，也要记得关掉

### 编译优化
- 如果只改了 Dart 代码（没加新依赖/asset），用 `--no-pub` 跳过 pub get
- 如果添加了新 asset 文件，需要完整重新编译（不能 --no-pub）
- Web-server 模式首次编译约 60-90s，后续热重启约 20s
- Android 模拟器编译约 300s，非必要不用，最后验收时再用

### 网络与镜像源（必须遵守）
- 下载任何东西前，**优先使用国内镜像源**
- Flutter/Dart 包：设置环境变量后再执行
  ```
  $env:PUB_HOSTED_URL = "https://pub.flutter-io.cn"
  $env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"
  ```
- npm 包：使用淘宝镜像 `--registry=https://registry.npmmirror.com`
- pip 包：使用清华源 `-i https://pypi.tuna.tsinghua.edu.cn/simple`
- Gradle/Maven：使用阿里云镜像（已在 android/build.gradle.kts 配置）
- 如果镜像也失败，再尝试直连

### 资源/图片
- 新图片放入 assets/ 后必须重新完整编译才能生效
- HTML 原版图片在 assets/www/ 目录，如有问题先对照 HTML 代码里的引用路径
- 优先使用透明背景 PNG，避免白色方块