mc-minder 0.6.0

# AGENTS.md


> 项目上下文文件 - 供 AI 助手参考的开发指南

## 项目概览


**项目名称**: mc-minder  
**描述**: 为 Termux/Android 上的 Minecraft Fabric 服务器设计的智能管理套件  
**语言**: Rust (Edition 2021)  
**版本**: 0.6.0-alpha.11 <!-- ⚠️ 每次发布新版本时请同步更新此处版本号 -->
**仓库**: https://github.com/SharkMI-0x7E/mc-minder

## 核心功能


- 日志监控：使用 notify 库实时监控服务器日志，事件驱动，低 CPU 占用
- 服务器状态查询：基于 wiki.vg 协议的 MC Ping，实时显示玩家数/版本/延迟
- RCON 通信：持久连接池，自动重连，响应返回
- HTTP API：RESTful API (/status + /command)，MC 状态集成
- Java 管理：自动检测、一键安装、交互式切换
- TUI 管理界面：原生 Rust 终端 UI
- 一键安装：交互式初始化配置
- 自动更新：内置 self-update 命令
- 多平台：Linux x64/ARM64、Termux/Android、Windows x64

## 国际化文档同步


**重要**: 本项目维护中英双语文档，更新时必须同步：

| 中文文档 | 英文文档 |
|----------|----------|
| README.md | README_en.md |

**规则**：
- 每次更新 README.md 时，必须同步更新 README_en.md
- 保持两份文档的结构、功能描述、命令示例一致
- 英文文档不需要逐字翻译，但必须包含相同的信息

## 构建配置


### Release Profile (Cargo.toml)

```toml
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"
strip = true
```

### 依赖项注意事项 (重要!)

- **reqwest**: 使用 `rustls-tls` feature + `default-features = false`（避免 OpenSSL 交叉编译问题）
- **reqwest 版本**: 使用 `0.12` 版本（默认使用 `aws-lc-rs` 后端，纯 Rust 实现）
- tokio: 完整异步运行时，包含 signal 和 process 功能
- notify: 文件系统事件监控
- dialoguer: 交互式 CLI 提示
- colored: 终端彩色输出
- warp: HTTP 服务器

### Cargo.toml 关键配置

```toml
# 正确的 reqwest 配置（用于交叉编译）

reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
```

## CI/CD 工作流 (GitHub Actions)


### 工作流文件

`.github/workflows/release.yml` 和 `Cross.toml`

### 触发条件

- Push tags 匹配 `v*` 模式
- 手动触发 (`workflow_dispatch`)

### 构建矩阵


#### 1. Linux x86_64 构建 (`build-linux-x86_64`)

- **Runner**: `ubuntu-latest`
- **工具链**: `dtolnay/rust-toolchain@stable`
- **构建命令**: `cargo build --release`
- **输出文件**: `mc-minder-x86_64-linux`
- **缓存**: 使用 `actions/cache@v3` 缓存 cargo registry 和 target 目录

#### 2. Termux ARM64 构建 (`build-termux-aarch64`) - 最终成功方案!

- **Runner**: `ubuntu-latest`
- **工具链**: `dtolnay/rust-toolchain@stable` + `aarch64-linux-android` target
- **安装 cross**: 使用 `cargo-binstall -y cross` 快速安装预编译版本
- **Cross 配置文件**: `Cross.toml`
  ```toml
  [build.env]
  passthrough = [
      "RUSTFLAGS",
  ]

  [target.aarch64-linux-android]
  image = "ghcr.io/cross-rs/aarch64-linux-android:main"
  ```
- **构建命令**: `cross build --target aarch64-linux-android --release`
- **输出文件**: `mc-minder-termux-aarch64`
- **缓存**: 使用 `actions/cache@v3` 缓存 cargo registry 和 target 目录

#### 3. Linux ARM64 构建 (`build-linux-aarch64`)

- **Runner**: `ubuntu-latest`
- **工具链**: `dtolnay/rust-toolchain@stable` + `aarch64-unknown-linux-gnu` target
- **安装 cross**: 使用 `cargo-binstall -y cross` 快速安装预编译版本
- **Cross 配置文件**: `Cross.toml`
  ```toml
  [target.aarch64-unknown-linux-gnu]
  image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:main"
  ```
- **构建命令**: `cross build --target aarch64-unknown-linux-gnu --release`
- **输出文件**: `mc-minder-aarch64-linux`
- **缓存**: 使用 `actions/cache@v3` 缓存 cargo registry 和 target 目录

#### 4. Windows x86_64 构建 (`build-windows-x86_64`)

- **Runner**: `ubuntu-latest`
- **工具链**: `dtolnay/rust-toolchain@stable` + `x86_64-pc-windows-gnu` target
- **安装 cross**: 使用 `cargo-binstall -y cross` 快速安装预编译版本
- **构建命令**: `cross build --target x86_64-pc-windows-gnu --release`
- **输出文件**: `mc-minder-x86_64-windows.exe`
- **缓存**: 使用 `actions/cache@v3` 缓存 cargo registry 和 target 目录

#### 5. Release 发布 (`release`)

- **依赖**: `needs: [build-linux-x86_64, build-termux-aarch64, build-linux-aarch64, build-windows-x86_64]`
- **发布工具**: `softprops/action-gh-release@v1`
- **附件文件**:
  - `binaries/mc-minder-x86_64-linux/mc-minder-x86_64-linux`
  - `binaries/mc-minder-termux-aarch64/mc-minder-termux-aarch64`
  - `binaries/mc-minder-aarch64-linux/mc-minder-aarch64-linux`
  - `binaries/mc-minder-x86_64-windows/mc-minder-x86_64-windows.exe`
  - `install.sh`

### CI/CD 坑点总结 (血泪史!)


#### 问题 1: OpenSSL 交叉编译失败

- **错误信息**: `Could not find openssl via pkg-config`
- **原因**: `reqwest` 默认依赖系统 OpenSSL，交叉编译需要目标平台的 OpenSSL
- **解决方案**: 使用 `rustls-tls` feature 替代默认的 `native-tls`

#### 问题 2: ring crate 需要 libunwind

- **错误信息**: `cannot find -lunwind`
- **原因**: `ring` 是 rustls 的加密后端，包含平台相关汇编代码
- **解决方案**: 升级 reqwest 到 0.12，使用 `aws-lc-rs` 后端（纯 Rust 实现）

#### 问题 3: cross-rs/cross action 不存在

- **错误信息**: `Can't find 'action.yml' for action 'cross-rs/cross@main'`
- **原因**: cross 没有官方 GitHub Action
- **解决方案**: 使用 `cargo-binstall` 安装预编译的 cross 二进制文件

#### 问题 4: 目标架构错误

- **错误目标**: `aarch64-unknown-linux-musl` (musl libc)
- **正确目标**: `aarch64-linux-android` (Bionic libc)
- **原因**: Termux 运行在 Android 上，使用 Bionic libc

#### 问题 5: NDK 手动配置复杂

- **问题**: 使用 `nttld/setup-ndk` + 手动配置链接器容易出错
- **解决方案**: 使用 `cross` 工具自动处理 Docker 环境和 NDK 配置

### 最终成功配置要点

1. **reqwest 0.12** + **rustls-tls** feature（避免原生依赖）
2. **cross** 通过 **cargo-binstall** 安装（快速）
3. **Cross.toml** 使用官方 Docker 镜像（自动处理 NDK）
4. **target**: `aarch64-linux-android`（正确的 Android 目标）

### 版本管理

- 版本号定义在 `Cargo.toml` 的 `[package].version` 字段
- Git tag 格式: `v{version}` (如 `v0.3.2`)
- 发布 Release 时，tag 会触发 CI/CD 工作流

## 开发注意事项


### Windows 开发环境

- Python 命令使用 `py` 而不是 `python`（环境变量问题）
- PowerShell 中使用 `;` 分隔命令，而不是 `&&`

### 代码风格

- 代码中**不**使用 emoji
- 终端输出保持简洁，不要大量使用 `=` 等分隔符
- 回复用户时可以使用 emoji，但代码保持专业

### 测试与验证

- 交叉编译的二进制文件需要在实际 Termux 环境中测试
- GitHub Actions 构建失败时，检查 job 日志获取详细错误信息

## 文件结构


### 核心源代码结构

```
mc-minder/
├── src/
│   ├── main.rs              # 入口点 - 薄层分发器
│   ├── cli.rs               # 命令行参数解析
│   ├── config.rs            # 配置加载和管理
│   ├── banner.rs            # 横幅打印和日志初始化
│   ├── init.rs              # 交互式初始化配置
│   ├── self_update.rs       # 自动更新功能
│   ├── server_run.rs        # 服务器运行主循环
│   ├── command_sender.rs     # 命令发送（RCON/Stdin连接池）
│   ├── foreground_process.rs # 前台进程管理（Java进程stdio管道）
│   │
│   ├── mc-status-probe/     # MC 服务器状态查询库（wiki.vg 协议实现）
│   │
│   ├── tui/                 # TUI 模块（替代 Shell 脚本）
│   │   ├── mod.rs           # TUI 入口 + 终端管理 + 前台进程spawn
│   │   └── app.rs           # 应用状态 + UI 渲染 + 事件处理
│   │
│   ├── monitor/             # 日志监控 + 聊天捕获模块
│   │   └── mod.rs           # LogMonitor + ChatCapture trait + 实现
│   ├── ai/                  # AI 聊天机器人
│   │   └── mod.rs           # OpenAI/Ollama 客户端、限流
│   ├── rcon.rs              # RCON 通信协议
│   ├── context.rs           # 对话上下文管理
│   ├── api/                 # HTTP API 服务器
│   │   └── mod.rs           # warp HTTP 服务器、端点路由
│   ├── notification.rs      # 通知服务（Telegram 等）
│   └── update_engine.rs     # 更新引擎（异步下载+安装）
├── scripts/                 # Shell 脚本
│   ├── start-tui.sh         # TUI 启动脚本（极简启动器）
│   └── backup.sh            # 备份脚本
├── .github/
│   └── workflows/
│       └── release.yml      # CI/CD 发布工作流
├── Cargo.toml               # 项目配置和依赖
├── Cross.toml               # Cross 交叉编译配置
├── install.sh               # 一键安装脚本
├── AGENTS.md                # 本文件 - AI 上下文
├── README.md                # 中文说明文档
└── README_en.md             # 英文说明文档
```

### 模块职责


| 模块 | 职责 | 关键功能 |
|------|------|----------|
| `main.rs` | 入口点 | 参数解析、模块分发 |
| `cli.rs` | CLI | clap 参数定义、命令处理 |
| `config.rs` | 配置 | toml 加载、配置验证 |
| `banner.rs` | 横幅/日志 | 打印版本、env_logger 初始化 |
| `init.rs` | 初始化 | 交互式配置生成、脚本生成 |
| `self_update.rs` | 更新 | GitHub Release 检查、二进制替换 |
| `server_run.rs` | 运行 | 事件循环、AI聊天处理、组件协调 |
| `command_sender.rs` | 命令发送 | PooledRconSender(持久连接+自动重连)、StdinCommandSender、MultiCommandSender |
| `foreground_process.rs` | 前台进程 | Java进程spawn、stdin/stdout/stderr管道、chat解析 |
| `tui/` | TUI | 原生终端UI + RunningForeground状态(进程内前台运行) |
| `monitor/` | 监控 | LogMonitor(notify文件监控)、ChatCapture trait、Tmux/File/Process实现 |
| `ai/` | AI | OpenAI/Ollama 双后端、请求限流 |
| `rcon.rs` | RCON | 异步 RCON 协议、底层包处理 |
| `context.rs` | 上下文 | 按玩家对话历史、过期清理 |
| `api/` | API | warp HTTP 服务器、命令执行(返回RCON响应) |
| `notification.rs` | 通知 | Telegram Bot API |
```

### 脚本部署方式


脚本支持多种部署方式：

**方式 1：自动部署（推荐）**
```bash
# 通过安装脚本自动部署

curl -fsSL https://github.com/SharkMI-0x7E/mc-minder/releases/latest/download/install.sh | bash

# 安装后目录结构

mc-server/
├── mc-minder              # Rust 二进制（包含 TUI）
├── start-tui.sh           # TUI 启动脚本（极简启动器）
├── backup.sh              # 备份脚本
└── ...
```

**方式 2：手动部署**
```bash
# 只需要 mc-minder 二进制

mc-server/
├── mc-minder              # Rust 二进制
├── start-tui.sh           # 可选：TUI 启动脚本
└── ...
```

**方式 3：直接运行**
```bash
# 无需脚本，直接运行

./mc-minder tui
```

**方式 4：环境变量配置**
```bash
# 设置 mc-minder 二进制位置

export MC_MINDER_BIN=/usr/local/bin/mc-minder
```

TUI 启动脚本会自动检测 mc-minder 二进制位置：
1. MC_MINDER_BIN 环境变量
2. 脚本所在目录
3. 当前目录
4. PATH 中查找

## 常用命令


### 本地构建 (Linux x86_64)

```bash
cargo build --release
```

### 交叉编译 (Termux ARM64)

```bash
cross build --target aarch64-linux-android --release
```

### 创建 Release

```bash
git tag v{version}
git push origin v{version}
```

## Release 内容规范（重要！）


为了确保用户能快速了解每次更新的内容，**Release 页面必须遵循以下格式**：

### 自动生成规则


CI/CD 会根据 commit message 自动生成 Release 内容，**commit message 必须遵循以下格式**：

```
<type>(<scope>): <subject>

<body (可选)>
```

### 分类和类型


Release 页面会自动按以下分类显示更新内容：

| type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(scripts): add smart path detection` |
| `fix` | 问题修复 | `fix(rcon): resolve connection timeout` |
| `perf` | 性能优化 | `perf(monitor): reduce file I/O operations` |
| `refactor` | 代码重构 | `refactor(config): simplify loading logic` |
| `docs` | 文档更新 | `docs(readme): update installation guide` |
| `test` | 测试相关 | `test(rcon): add unit tests` |
| `chore` | 其他改动 | `chore: update dependencies` |

### 最终 Release 页面示例


```markdown
## MC-Minder v0.5.2


### 新功能

- Add intelligent path detection in start-tui.sh
- Enhance binary detection in common.sh

### 问题修复

- Fix path resolution issues in different deployment scenarios

### 性能优化

- Improve script loading with cached path detection

### 文档更新

- Add comprehensive deployment guide
- Document 4 deployment methods

### 其他改动

- Update dependencies to latest versions

---

### 下载

| 平台 | 文件 | 说明 |
|------|------|------|
| Linux x64 | `mc-minder-x86_64-linux` | 适用于桌面 Linux / WSL |
| Linux ARM64 | `mc-minder-aarch64-linux` | 适用于树莓派 / ARM 服务器 |
| Termux/Android ARM64 | `mc-minder-termux-aarch64` | 适用于手机 Termux 环境 |

### 安装

```bash
curl -fsSL https://raw.githubusercontent.com/SharkMI-0x7E/mc-minder/main/install.sh | bash
```
```

### 为什么需要这个规范？


1. **用户体验**：用户打开 Release 页面就能立即看到更新了什么
2. **清晰分类**：按功能、修复、性能等分类，一目了然
3. **自动归档**：每次发布都自动生成结构化的更新日志
4. **专业形象**：让项目看起来更专业、更易维护

### Commit 提交检查清单


提交前请确认：
- [ ] commit message 符合 Conventional Commits 格式
- [ ] type 正确反映了变更性质（feat/fix/docs/refactor/perf/test/chore）
- [ ] scope 准确标识了影响范围
- [ ] subject 简洁明了地描述了变更内容
- [ ] 不要写太长的 commit message，保持在 50 字符以内

## 更新日志

- 2026-04-27: **v0.6.0-alpha.1 发布!** 新增 mc-status-probe 原创库（wiki.vg MC Ping 协议实现）、HTTP API 增强（/status 含 MC 状态、/command RCON 预检）、Windows x86_64 CI/CD 支持、discover_minecraft_port 自动端口发现
- 2026-04-26: **v0.5.6 发布!** 恢复前台模式为终端 exec
- 2026-04-26: **v0.5.5 发布!** Java 交互式版本切换
- 2026-04-26: **v0.5.2 发布!** 添加 Linux ARM64 交叉编译支持（aarch64-unknown-linux-gnu），修复 install.sh 的各种问题（ARM64 检测、脚本库下载、dialog 过期警告）
- 2026-04-26: **v0.5.1 发布!** 消除所有 dead_code 警告，删除未使用的 rcon 模块，更新 README
- 2026-04-26: **v0.5.0 发布!** 彻底移除 LLM/AI 功能，完善初始化配置（Java 自动检测、JDK 路径配置），增强 TUI Java 菜单（版本检测、安装指引）
- 2026-04-25: **v0.4.9 发布!** AI 聊天机器人重大重写：ChatCapture trait 统一捕获、PooledRconSender 持久连接、ForegroundProcess TUI 内前台运行、[Not Secure] regex 修复、[AI] 日志前缀标准化
- 2026-04-21: **v0.3.14 发布!** 修复编译错误、clippy 警告、代码质量优化
- 2026-04-21: **v0.3.13 发布!** 修复 AI 聊天无响应问题、改进日志解析、增强 debug 日志
- 2026-04-21: **v0.3.12 发布!** 改进配置读取、添加前台运行、修复符号链接权限
- 2026-04-21: **v0.3.11 发布!** 修复函数顺序、grep兼容性、PID写入等问题
- 2026-04-21: **v0.3.10 发布!** 修复二进制检测、配置读取等重大BUG
- 2026-04-21: **v0.3.9 发布!** 修复二进制文件命名和SHA256校验问题
- 2026-04-21: **v0.3.8 发布!** 修复PID文件错误、改进macOS支持
- 2026-04-21: **v0.3.7 发布!** TUI启动脚本、JVM配置、Telegram通知
- 2026-04-21: **v0.3.6 发布!** CI/CD 自动生成 Changelog 功能
- 2026-04-21: **v0.3.5 发布!** 修复所有编译警告，零警告构建
- 2026-04-21: **v0.3.4 发布!** 新增 TUI 启动脚本、JVM 配置支持、Telegram 通知功能
- 2026-04-20: **v0.3.3 发布!** 版本统一、依赖升级、代码优化、单元测试
- 2026-04-20: **CI/CD 终于成功!** 使用 reqwest 0.12 + rustls + cross + Cross.toml 方案
- 2026-04-20: 升级 reqwest 到 0.12 解决 libunwind 链接问题
- 2026-04-20: 添加 Cross.toml 配置 Android 交叉编译环境
- 2026-04-20: 切换到 rustls-tls 避免 OpenSSL 交叉编译问题
- 2024-04-20: 初始添加 Termux ARM64 交叉编译支持

---

## 分支模型与版本管理（必读）


### 分支策略（GitHub Flow）


```
main ────────────────────→ 始终可部署，永远稳定
  │         │         │
  feat/a    fix/b     feat/c  → 功能分支（做完就删，合并后自动清理）
```

| 分支 | 作用 | 谁提交 | Tag |
|------|------|--------|-----|
| `main` | 稳定版，始终可部署 | 通过 PR merge | `v0.6.0` 正式版 |
| `feat/*` / `fix/*` | 单功能/修复 | 自由提交 | ❌ 不打 tag |

**没有 develop 分支**。GitHub Flow 是小团队的最佳选择 — 少一层 merge，少一份混乱。

### 版本号规则


| 场景 | 改版本号？ | 谁做 |
|------|----------|------|
| 日常开发 | **不改** | 开发者 |
| 准备正式发布 | **手动改** `Cargo.toml` → PR 到 main → `git tag v0.6.0` | 人工 |

### 工作流


```bash
# 1. 从 main 拉分支

git checkout main && git pull
git checkout -b feat/my-feature

# 2. 写代码 + 提交（一个功能一个 commit）

git commit -m "feat(tui): add TPS history chart"

# 3. 推分支，开 PR

git push origin feat/my-feature
# GitHub 上 Create Pull Request → merge 到 main

# 合并后自动删除分支


# 4. 准备正式发布时

# 改 Cargo.toml version → PR 到 main → git tag v0.6.0

```

### 分支自动清理


GitHub 仓库设置中启用 "Automatically delete head branches"：
- Settings → General → Pull Requests → ✅ Automatically delete head branches
- 每次 PR merge 后，GitHub 自动删掉 feature 分支
- 本地用 `git remote prune origin` 清理本地跟踪

---

## Release Changelog（发布时用 git-cliff 生成）


### 工具配置


项目根目录有 `cliff.toml`，定义了 changelog 格式。发布时运行：

```bash
# 安装（一次性）

cargo install git-cliff

# 生成 changelog

git cliff -o CHANGELOG.md
```

CI/CD 在 release 时自动调用 git-cliff 生成 Release 描述。

### Changelog 怎么生成的


1. 从上一次 tag 到当前 tag，读取所有 commit
2. 按 Conventional Commits 规范分类（feat→新功能，fix→修复）
3. 每个 commit subject 作为一行描述
4. 附带 commit 链接

**所以**：commit subject 写得好 = changelog 自动漂亮。一个 commit 一件事。

### 必须遵循 Conventional Commits


```
<type>(<scope>): <subject>

<body (可选)>
```

#### type（必选，小写英文）


| type | 含义 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(tui): add colored status panel` |
| `fix` | 修 bug | `fix(perf): cache Java detection result` |
| `docs` | 文档 | `docs(readme): update feature list` |
| `refactor` | 重构 | `refactor(config): simplify loader` |
| `perf` | 性能 | `perf(monitor): reduce I/O` |
| `test` | 测试 | `test(rcon): add unit tests` |
| `chore` | 杂项 | `chore: update dependencies` |
| `ci` | CI/CD | `ci: add Windows build target` |

#### scope（可选）


```
tui | api | config | core | msp | monitor | backup | scheduler | ci
```

### 黄金法则


| 规则 | 为什么 |
|------|--------|
| **一个 commit 只做一件事** | Release 页面每行一个 commit subject，commit 多件事=乱 |
| **subject 一句话说完** | `feat(tui): add TPS chart` ✅ |
| **不改版本号**（日常） | 版本号只在发布时改，日常锁住 |
| **一个功能一个分支** | 隔离风险，方便 review |
| **先 PR 再 merge** | 避免直接动 develop |
| **只从 main 打正式 tag** | 预览版由 CI 自动处理 |

### 示例 ✅


```bash
feat(tui): add interactive Java version picker

- Add JavaSwitch state with list navigation
- Enter to confirm selection, updates config.toml
- Esc to cancel and return to menu
```

### 反例 ❌

```bash
feat: add Java switch, fix foreground mode, update README, bump version
# ← 一个 commit 塞了 4 件事，Release 页面乱成一坨
```

---

## Release Changelog 怎么生成的


CI/CD 在发布时执行以下逻辑：

1. 获取上一次 tag 和当前 tag 之间的所有 commit
2. 按 type 分类：`feat` → 新功能，`fix` → 问题修复，`docs` → 文档更新
3. 每个 commit 的 **subject**（冒号后面的部分）作为一条更新描述
4. 同一 commit 的 **body**（多行详细描述）不会出现在 Release 页面

**所以**：

```
你的 commit: feat(tui): add TPS history chart
                          ↑
Release 页面显示: - add TPS history chart

你的 commit: feat: add TPS chart, fix warnings, update docs
                          ↑
Release 页面显示: - add TPS chart, fix warnings, update docs (一坨)
```

**So:**

```
你的 commit: feat(tui): add TPS history chart
                          ↑
Release 页面显示: - add TPS history chart

你的 commit: feat: add TPS chart, fix warnings, update docs
                          ↑
Release 页面显示: - add TPS chart, fix warnings, update docs (一坨)
```

**Release 描述每一行就是一个 commit 的 subject。** 想让 Release 好看，就让每个 commit 只说一件事。

> **关键保障**：即使 AI 完全忘记写 UNRELEASED，`git log` 从上一个 tag 到现在的所有 commit 都会被自动提取到 Release 页面。AI 记忆丢失不会影响 Release 内容。

### 未发布更新记录（辅助 AI 记忆）


> **主方案**：Release 内容由 CI/CD 从 `git log` 自动生成（已实现）。
> **UNRELEASED**：辅助 AI 记住上下文，不是强制要求。有总比没有好。

**发布流程**：
1. AI 读取 `UNRELEASED` + `git log` 对照，确保没遗漏
2. 生成 Release 描述（一份 commit subject 一条）
3. 合并 develop → main
4. 打 tag v0.6.0
5. **清空 UNRELEASED**

**如果 AI 忘了更新 UNRELEASED**：
- `git log` 是最终真相 — Release 不会丢内容
- UNRELEASED 只是辅助人类阅读的摘要

---

## UNRELEASED


（新功能完成时在此添加，发布时清空）

- feat(tui): add colored menu categories (green/cyan/yellow/magenta)
- feat(tui): add TPS history ASCII chart in status view
- feat(core): add Fabric/Paper/Vanilla server auto-download wizard
- feat(mod): add Modrinth mod search and hot mod downloader
- feat(schedule): add cron-style scheduler (backup/broadcast/restart)
- feat(lazy): add LazyStart TCP listener for on-demand server wake
- feat(backup): add world backup system with retention policies
- feat(api): add MC server ping status (/status with players/version/latency/TPS)
- feat(config): add multi-server [[servers]] array support
- feat(java): add Java version auto-detection and one-click install
- feat(tui): add language selection on first launch
- feat(ci): add Windows x86_64 cross-compile build target

## 外部依赖


### mc-status-probe


MC 服务器状态查询功能依赖 `mc-status-probe` 库（`https://crates.io/crates/mc-status-probe`）。
该库已在 crates.io 发布，**不需要**将其源代码放在 mc-minder 项目目录中。

**Cargo.toml 配置**：
```toml
mc-status-probe = "0.1.0-alpha.3"
```

如果本地开发需要同时修改 msp，可以临时改为 path 依赖：
```toml
mc-status-probe = { version = "0.1.0-alpha.2", path = "mc-status-probe" }
```

msp 独立仓库：`https://github.com/SharkMI-0x7E/mc-status-probe`

---

## 测试指南


### 本地开发测试


```bash
# 编译检查（不生成二进制，速度快）

cargo check

# 运行所有单元测试

cargo test --lib

# 运行指定模块的测试

cargo test --lib monitor

# 运行所有测试（含集成测试）

cargo test

# 编译并运行 TUI（功能测试）

cargo run -- tui

# 编译 release 版本

cargo build --release
```

### 测试清单（提交前必做）


- [ ] `cargo check` 零错误零警告
- [ ] `cargo test --lib` 全部通过
- [ ] `cargo build --release` 成功
- [ ] 如果改了 TUI：`cargo run -- tui` 启动确认界面正常

### 关于 release


**不要手动 `cargo publish`**。发布由 CI/CD 在打 tag 时自动完成。
只需推送 tag：`git tag v0.x.x && git push origin v0.x.x`

### Release Changelog 生成规则


CI/CD 根据 commit message 自动生成 Release 描述。为了让每个改动都清晰可见：

1. **一个 commit 只做一件事** — 不要把多个不相关的功能写在一个 commit 里
2. **subject 一行写完** — 核心描述写在一行内，不要换行
3. **body 写详细说明** — 需要详细解释的内容写在 subject 后面的空行里

正例 ✅：
```
feat(tui): add interactive Java version picker

- Add JavaSwitch state with list navigation
- Enter to confirm selection, updates config.toml
- Esc to cancel and return to menu
```

反例 ❌：
```
feat: add Java switch, fix foreground mode, update README, bump version
```

**每组 commit 的 subject 只描述一件事**。Release 页面每行对应一个 commit 的 subject，commit link 可以相同（同一个 commit 的多行 body 不会出现在 Release 描述中）。

---

### 用户个人要求
我是windows10系统，然后python不知道为什么没有上环境变量，所以你要执行python命令的时候不要使用 "python xxx.py" 要使用 "py xxx.py"

回复保持幽默，回复带emoji。但是生成的代码要保持专业，比如，终端打印的内容不要一大堆"="

但是，在实际项目编写中，代码里尽量不出现过多或不出现emoji

说中文
 
### oh-my-opencode 安装脚本
- 项目内新增一个简化安装的脚本：`scripts/install_oh_my_opencode.sh`。
- 作用：按文档要求，自动拼装安装命令并执行，支持非交互模式和简单参数切换。
- 使用方式（示例）：
  - 运行前请确保已安装 Bun（bunx）并可执行 `bunx`。
  - 运行脚本以开始安装：
    ```bash
    bash scripts/install_oh_my_opencode.sh --no-tui --claude=yes --openai=yes --gemini=no --copilot=no --opencode-zen=yes
    ```
- 安装完成后建议执行健康检查：`bunx oh-my-opencode doctor`。
- 如需更多自定义参数，请查看脚本内帮助信息。 

---

## Windows 开发注意事项


### Python 命令

- Python 命令使用 `py` 而不是 `python`（环境变量问题）
- PowerShell 中使用 `;` 分隔命令，而不是 `&&`

### Windows TUI 按键处理（重要！）


Windows 终端（cmd / PowerShell / Windows Terminal）与 Linux 终端在按键事件上有以下区别：

1. **Press/Release 双事件**：Windows 终端每次按键会发送 `KeyEventKind::Press` 和 `KeyEventKind::Release` 两个事件。代码中已在 `tui/mod.rs` 过滤掉 Release 事件，避免状态被重复处理。

2. **小键盘按键**：当 NumLock 开启时，小键盘方向键发送 `KeyCode::Char('8')`（上）、`Char('2')`（下）、`Char('4')`（左）、`Char('6')`（右），而非 `KeyCode::Up/Down/Left/Right`。代码中已在 `app.rs` 的 `normalize_key()` 中做了映射。

3. **新增按键处理时**：必须在 `normalize_key()` 中处理 Windows 特有的按键映射。

### Windows 后台启动不可用


`start_server_background()` 依赖 `tmux` 和 `nohup`，这些是 Unix 专有命令。在 Windows 上后台启动会静默失败。
未来可考虑使用 Windows 的 `start /B` 或 `CreateProcess` 作为替代方案。

### 代码风格

- 代码中**不**使用 emoji
- 终端输出保持简洁，不要大量使用 `=` 等分隔符
- 回复用户时可以使用 emoji，但代码保持专业

### mc-status-probe (msp) 依赖管理


msp 是独立的 Rust 库，有独立仓库 `https://github.com/SharkMI-0x7E/mc-status-probe` 和 crates.io 版本。

**关键规则**：
- msp 更新版本后，mc-minder 的 `Cargo.toml` 中 `mc-status-probe` 版本号**必须同步更新**
- msp 的源代码**不需要**放在 mc-minder 仓库中（已在 .gitignore 排除）
- 本地开发如需同时修改 msp，使用双源依赖：`mc-status-probe = { version = "0.1.0-alpha.3", path = "mc-status-probe" }`
- 发布 mc-minder 前，确保 msp 已发布到 crates.io