# MC-Minder 开发路线图

> 本文档由蓝图拆解而来，每个任务独立可交付。
> 标记：✅ 已完成 | 🔧 进行中 | 📋 待开始 | 💤 远期

---

## 🟢 Phase 0 — 核心基础 (已完成)

### ✅ P0-1: 彻底移除 LLM/AI 功能
- 删除 `src/ai/` 和 `src/context/` 模块
- 移除 `server_run.rs` 中 AI 处理逻辑
- 清理 API `/history` 端点
- 更新 `config.rs` 移除 `AiConfig` / `OllamaConfig`
- 版本: v0.5.0

### ✅ P0-2: Java 管理增强
- `init.rs`: 自动检测 Java 安装，平台专属安装指引
- TUI Java 菜单: 版本检测、一键安装、交互式切换
- `switch_java_version`: 多版本列表，选中后写 `config.toml`
- 版本: v0.5.5

### ✅ P0-3: 语言选择
- 首次启动 TUI 时英文提示选择语言
- `load_language()` / `save_language()` 持久化到 `lang.conf` + `config.toml`
- 版本: v0.5.4

### ✅ P0-4: mc-status-probe 原创库
- 独立 Rust 库，纯 wiki.vg 协议实现 MC Ping
- VarInt 编解码、Handshake、Status Request/Response
- MOTD ChatComponent JSON 提取
- 12/12 单元+集成测试
- 发布到 crates.io: `mc-status-probe = "0.1.0-alpha.4"`
- 版本: msp v0.1.0-alpha.4

### ✅ P0-5: MC 状态集成
- `config.rs`: `[mc_status]` 配置段 + `discover_minecraft_port()`
- `api/mod.rs`: `/status` 返回 MC 状态 (online/players/version/latency/motd)
- `/command` 端点 RCON 可用性预检
- 后台 `tokio::spawn` 周期性 ping，`PingGuard` 防死锁
- TUI `draw_status_view` 显示 MC 状态
- 版本: v0.6.0-alpha.2

### ✅ P0-6: 多平台 CI/CD
- Linux x86_64 + ARM64 (aarch64-unknown-linux-gnu)
- Termux/Android ARM64 (aarch64-linux-android)
- Windows x86_64 (x86_64-pc-windows-gnu)
- 版本: v0.5.2 + v0.6.0-alpha.1

### ✅ P0-7: Windows TUI 按键修复
- 过滤 `KeyEventKind::Release` 避免双事件
- 小键盘 2/8 映射为 Down/Up
- 动态菜单长度 `items().len()`
- 版本: v0.6.0-alpha.1.1

---

## 🟡 Phase 1 — TUI 交互体验升级

### 📋 P1-1: 状态栏定时刷新
- 后台定时器驱动界面刷新（当前是按键驱动）
- 每 2 秒自动刷新状态面板的 MC 状态、进程状态
- 不阻塞用户输入
- 依赖: P0-5
- **状态: ✅ 已完成** — MC 状态每 200ms 自动刷新，F5 手动刷新快捷键 + `refresh_status()` 方法已添加

### ✅ P1-2: 弹窗式交互系统
- 封装 `ModalDialog` 通用组件
- 支持: 确认对话框 / 输入框 / 选择列表
- 所有辅助操作用弹窗替代当前的消息提示
- 携带标题、操作按钮、`Esc` 关闭
- **状态: ✅ 已完成** — `ConfirmAction::Modal` 变体已添加，`show_modal()` 方法可用，支持自定义标题和消息

### ✅ P1-3: 全局快捷键
- 绑定常用功能: `F5` 刷新, `F7` 备份, `c` 控制台
- 状态栏显示当前可用快捷键
- `Ctrl+C` 保持为退出
- **状态: ✅ 已完成** — `F5`/`F7`/`c` 全局快捷键，Busy 状态下阻断其他输入

### ✅ P1-4: 分栏布局
- 左右分栏: 服务器列表(左) + 详情/操作(右)
- 顶部标题栏或标签页
- 控制台视图独立全屏
- **状态: ✅ 已完成** — 主菜单右侧显示 MC 状态 (在线/版本/玩家/延迟/MOTD) + 进程状态 + 快捷键提示

### ✅ P1-5: 操作反馈与进度条
- 耗时操作 (启动/备份/更新) 显示进度遮罩
- 防止重复操作
- 完成自动刷新界面
- **状态: ✅ 已完成** — `AppState::Busy(String)` + `set_busy()`/`clear_busy()` + 居中 spinner 遮罩

### 📋 P1-4: 分栏布局
- 左右分栏: 服务器列表(左) + 详情/操作(右)
- 顶部标题栏或标签页
- 控制台视图独立全屏
- 依赖: P1-1

### 📋 P1-5: 操作反馈与进度条
- 耗时操作 (启动/备份/更新) 显示进度遮罩
- 防止重复操作
- 完成自动刷新界面

---

## 🟠 Phase 2 — 多服务器管理

### 📋 P2-1: 服务器自动发现
- 扫描根目录子文件夹，识别 `fabric-server.jar` / `server.properties`
- 自动构建服务器实例列表
- "拖入即用"体验保留
- **状态: ✅ 已完成** — `discover_servers()` 扫描子目录检测 jar + server.properties，`DiscoveredServer` 结构体

### 📋 P2-2: 多服务器数据结构
- `config.toml` 支持 `[[servers]]` 数组
- 每个实例独立配置 (内存/端口/RCON/JDK)
- 向后兼容单服务器配置
- **状态: ✅ 已完成** — `ServerInstance` + `Config::get_servers()`，`[[servers]]` 数组，遗留格式自动转换

### 📋 P2-3: TUI 服务器列表侧边栏
- 左侧可滚动列表，上下键切换选中
- 显示每个服务器名 + 在线状态小图标
- 操作按钮跟随当前选中服务器
- **状态: 🔧 部分完成** — TUI 右侧面板显示已发现的服务器列表，选中指示器已实现

### 📋 P2-4: 独立配置文件管理
- TUI 内编辑各实例的 `server.properties`
- 支持保存，部分配置需重启生效
- 一键复制配置模板到新实例

### 📋 P2-5: 实例隔离与并发
- 每个服务器在独立 tokio task 中管理
- 崩溃不影响其他实例
- 并发启动/停止/重启

---

## 🟠 Phase 3 — 核心与 Mod 管理

### 📋 P3-1: FabricMC 核心自动下载
- API: `https://meta.fabricmc.net/v2/versions/loader/{ver}/0.17.2/1.1.0/server/jar`
- TUI "新建服务器"向导选择 MC 版本 + Loader 版本
- 自动下载 + 安装 + 生成启动配置
- 来源: FabricMC Meta API v2

### 📋 P3-2: PaperMC 核心自动下载
- API: `https://api.papermc.io/v2/projects/paper/versions/{ver}/builds/{build}/downloads/{name}`
- 自动获取最新 build
- 来源: PaperMC API v2

### 📋 P3-3: 多核心类型选择
- 向导支持: Fabric / Paper / Purpur / Vanilla / Forge
- 每种核心有自己的 API 端点
- 显示版本列表供选择

### 📋 P3-4: Mod 平台集成 (Modrinth)
- API: `https://api.modrinth.com/v2/search?query={keyword}`
- 搜索 Mod/插件/资源包
- 显示搜索结果列表: 名称/下载量/兼容版本
- 一键下载到 `mods/` 文件夹
- 来源: Modrinth API v2

### 📋 P3-5: Mod 更新检测
- API: `GET /v2/project/{id}/version` 获取最新版本
- 列出已安装 Mod，对比在线版本
- 高亮可更新的 Mod
- 批量更新

### 📋 P3-6: 拖入即用保留
- 手动放入的 jar 文件自动识别
- 向导式安装可选，不强制

---

## 🔵 Phase 4 — 自动化与进程管理

### 📋 P4-1: 看门狗增强
- "假死"检测: 长时间 TPS=0 自动重启
- 自定义重试策略: 最大次数/冷却时间
- 崩溃日志自动收集

### 📋 P4-2: 懒启动 (Lazy Start)
- 配置项启用轻量 TCP 监听器
- 收到连接请求 → 唤醒服务器
- 启动期间客户端收到等待提示
- 无玩家在线 N 分钟后自动停服
- 省资源模式

### 📋 P4-3: 计划任务调度器
- 配置 `[[schedules]]` 数组
- 支持: 定时备份 / 广播消息 / 重启 / 执行命令
- Cron 式时间表达式
- TUI 内可视化编辑

---

## 🔵 Phase 5 — 备份管理

### 📋 P5-1: 自动化备份策略
- 触发方式: 定时 / 关服前 / 玩家全退 / 手动
- 调用 `save-all` 确保数据一致性
- 压缩归档

### 📋 P5-2: 备份保留与清理
- 最大备份数 / 最大天数
- 自动清理旧备份
- 保留策略可在 TUI 中配置

### 📋 P5-3: 备份列表与恢复
- TUI 备份列表: 文件名/时间/大小
- 选中一键恢复，弹出确认
- 恢复后自动重启

---

## 🟢 Phase 6 — 高级状态监控

### 📋 P6-1: 实时性能指标 (TPS)
- 通过 RCON 执行 `/tps` 或 `/mspt`
- 在状态面板显示 TPS/内存/CPU
- 颜色编码: 绿色>18, 黄色>10, 红色<10

### 📋 P6-2: 历史趋势图
- 保留最近 N 分钟 TPS 数据
- TUI 中 ASCII 柱状图/折线图
- 帮助诊断性能瓶颈

### 📋 P6-3: 告警机制
- 触发条件: 离线 / TPS过低 / 内存超阈值
- TUI 高亮提示
- 可选: 桌面通知 / Discord Webhook

### 📋 P6-4: 玩家行为日志
- 增强日志监控: 进出时间戳/死亡/成就
- TUI 查询: 玩家在线时长/最后登录
- 依赖: 现有 `monitor/` 模块

---

## 🟣 Phase 7 — 实用工具箱

### 📋 P7-1: 快捷指令面板
- TUI 中显示自定义按钮:
  - "切换到和平" → `/difficulty peaceful`
  - "查看TPS" → 跳转监控面板
  - "全部传送" → 快捷指令列表
- 用户可在配置中自定义按钮

### 📋 P7-2: 崩溃报告查看器
- 扫描 `crash-reports/` 文件夹
- 按时间排序列表
- 点击查看: 高亮关键堆栈行
- 辅助排查崩溃原因

### 📋 P7-3: 游戏内公告
- TUI 直接向在线玩家广播
- 支持动态倒计时: "服务器5分钟后重启"

---

## 🌐 Phase 8 — 架构扩展

### 💤 P8-1: Web 管理面板
- 基于现有 HTTP API 扩展
- 前后端分离: Rust 后端 + 轻量前端框架
- 实时 WebSocket 推送状态

### 💤 P8-2: 插件系统
- 允许第三方 Rust crate 扩展功能
- 定义 Plugin trait
- 动态加载 (abi_stable / wasm)

### 💤 P8-3: 移动端专用优化
- Termux 通知集成 (`termux-notification`)
- 电池优化: 降低轮询频率
- 小屏适配 TUI 布局

---

## 📊 进度总览

| Phase | 任务数 | 已完成 | 状态 |
|-------|--------|--------|------|
| P0 核心基础 | 7 | 7 | ✅ 100% |
| P1 TUI 体验 | 5 | 5 | ✅ 100% |
| P2 多服务器 | 5 | 3 | 🔧 60% (P2-4/5 待完成) |
| P3 核心/Mod | 6 | 0 | 📋 0% |
| P4 自动化 | 3 | 0 | 📋 0% |
| P5 备份 | 3 | 0 | 📋 0% |
| P6 监控 | 4 | 0 | 📋 0% |
| P7 工具箱 | 3 | 0 | 📋 0% |
| P8 架构 | 3 | 0 | 💤 远期 |

---

## 🔗 API 速查

| 平台/功能 | API 端点 | 备注 |
|-----------|---------|------|
| FabricMC 服务端 | `https://meta.fabricmc.net/v2/versions/loader/{ver}/{loader}/1.1.0/server/jar` | 无鉴权 |
| PaperMC 版本列表 | `https://api.papermc.io/v2/projects/paper` | 无鉴权 |
| PaperMC build | `https://api.papermc.io/v2/projects/paper/versions/{ver}/builds/{build}` | 需先查 builds |
| PaperMC 下载 | `{build_url}/downloads/{name}` | name 从 builds 响应获取 |
| Modrinth 搜索 | `https://api.modrinth.com/v2/search?query={q}` | 无鉴权 |
| Modrinth 项目版本 | `https://api.modrinth.com/v2/project/{id}/version` | 无鉴权 |
| Modrinth 下载 | `https://cdn.modrinth.com/data/{id}/versions/{ver}/{file}` | 直链 |
| wiki.vg 协议版本 | `https://wiki.vg/Protocol_version_numbers` | MC Ping 版本号 |
| Minecraft 命令参考 | `https://minecraft.wiki/w/Commands` | 官方 Wiki |















## 原计划
# MC-Minder 全方位改进蓝图 (思路版)

## 0. 核心原则

- **保留并强化现有优势**：MC-Minder 当前的拖入即用（jar 文件放入目录即可管理）、极轻量化、多平台支持、RCON 集成、HTTP API、TUI 界面等核心特色保持不变，所有改进均在此基础上叠加。
- **增量迭代，不推倒重来**：现有代码架构良好，改进以模块化方式逐步推进，确保每次改动都稳定可用。
- **原创性第一**：所有设计思路均来自项目自身需求分析和公开的交互模式，禁止复制任何第三方项目代码，只借鉴产品设计理念。
- **降低用户门槛**：保持“把 server.jar 和 Mods 拖入文件夹，MC-Minder 就能自动识别并管理”的极简体验，新增功能不能破坏这一流程。

## 1. 多服务器管理能力升级

目前 MC-Minder 假设只管理一个服务器实例，是时候支持多个了。但务必保留“拖入即用”的快捷方式。

- **快速入口**：用户将一个含有 `fabric-server.jar`(或其他服务器核心) 的文件夹放入 MC-Minder 的根目录下，MC-Minder 启动时自动扫描子文件夹，识别出所有服务器实例，并列出在 TUI 的主面板上。
- **数据结构改造**：内部配置不再只有单一服务器，而是维护一个服务器列表，每个服务器有自己的独立配置（内存、端口、RCON 密码等），这些配置默认从 `server.properties` 自动读取，也允许用户手动覆盖。
- **TUI 侧边栏**：主界面的左侧显示一个可滚动的服务器列表，可以按上下键快速切换。右侧实时显示当前选中服务器的详细状态（玩家数、版本、TPS、内存占用等），操作按钮（启动/停止/重启/控制台）跟随切换。
- **配置文件管理**：每个服务器实例可以在 TUI 内单独编辑其 `server.properties`、`config.toml` 等配置，支持保存和即时生效（部分需要重启）。也允许一键复制配置模板。

## 2. TUI 交互与视觉体验升级

借鉴 Serverman 的 TUI 设计思路，但不照搬代码，用 ratatui 打造专业且流畅的终端体验。

- **状态栏实时刷新**：整个界面不再静态等待按键，而是由后台定时器驱动。状态栏自动更新服务器在线情况、玩家数、TPS、Ping 延迟等，按钮标签根据服务器状态动态变化（“启动”/“重启”）。
- **弹窗式交互**：所有辅助操作（确认停止、输入命令、修改配置项）都使用居中的模态弹窗，带有清晰的标题、操作按钮和 `Esc` 关闭功能，避免菜单层级过深。
- **全局快捷键**：为常用功能绑定快捷键，例如 `F5` 刷新服务器列表，`F7` 执行备份，`r` 重启选中的服务器，`Del` 删除服务器并弹出确认，`c` 打开控制台等。在状态栏显示快捷键提示。
- **分栏布局**：主界面采用经典的左右分栏（服务器列表 + 详细状态），顶部可以有一个简洁的标题栏或标签页。控制台视图则独立全屏，提供沉浸式日志浏览体验。
- **操作反馈**：任何耗时操作（启动服务器、备份、更新核心）触发时，立即显示一个半透明的“处理中”遮罩或进度条，防止用户重复操作，操作完成后自动刷新界面并给出结果提示。

## 3. 自动化/进程管理与“懒启动”

在现有的看门狗和自动重启基础上，实现更智能的进程生命周期管理。

- **看门狗增强**：不仅是崩溃重启，还支持“假死”检测（例如长时间 TPS 为 0 自动重启），并且可以自定义重启策略（最大重试次数、冷却时间等）。
- **懒启动（Lazy Start）**：在 MC-Minder 中开启一个轻量级 TCP 监听器（默认不开启，可在配置中启用），当收到对 Minecraft 端口的连接请求时，自动唤醒后台服务器。服务器启动期间，客户端会收到等待提示直到可登录。空闲一段时间无玩家在线后，自动安全关闭服务器，实现“有人玩就开，没人玩就关”的省资源模式。
- **计划任务（Cron 式）**：内置一个任务调度器，让用户可以设置定时任务，例如：
  - 每天凌晨 3 点自动备份世界。
  - 每隔 1 小时自动广播一条自定义消息。
  - 每周一早上 6 点重启服务器。
  任务可以在配置文件中定义，也可以在 TUI 内可视化编辑。

## 4. 备份管理提升

将现有的备份脚本功能升级为内置核心模块。

- **自动化备份策略**：支持多种备份触发方式：定时、服务器关闭前、玩家离开后、手动触发。
- **备份保留策略**：设置最大备份数量和天数，自动清理旧备份。
- **备份列表与恢复**：在 TUI 中列出所有备份，显示创建时间和大小，选中一键恢复（会弹出确认并自动重启服务器）。
- **世界快照**：利用 Minecraft 的 `/save-all` 命令配合文件系统快照或简单压缩，确保备份数据一致性。

## 5. 高级状态监控

利用 mc-status-probe 提供的 Ping 数据，构建更完善的状态仪表盘。

- **实时性能指标**：在 TUI 状态面板中显示 TPS、Ping 延迟、内存使用（来自 JMX 或 RCON `/memory`）、CPU 使用等。
- **历史数据图表**：可选保留一段时间内的性能数据，在 TUI 中用简单的柱状图或折线图显示 TPS 趋势，帮助诊断性能瓶颈。
- **告警机制**：当服务器离线、TPS 过低、内存超过阈值时，在 TUI 上高亮提示，并可配置桌面通知或 Discord 等 Webhook 推送。
- **玩家行为日志**：基于日志监控模块，增强玩家行为追踪，比如记录进出时间、死亡掉落等，在 TUI 中可查询。

## 6. 核心与 Mod 管理

参考 Serverman 的多版本安装思路，让 MC-Minder 不仅能管理服务器，还能“组装”服务器。

- **核心自动下载与安装**：在 TUI 的“新建服务器”向导中，提供 Fabric、Forge、NeoForge、Paper 等主流核心的选择，输入版本后自动从官方源或镜像下载安装程序，执行安装，生成启动脚本。整个过程不依赖用户手动准备 `fabric-server.jar`。
- **Mod 平台集成（可选）**：通过调用 Ferium 等命令行工具或封装 Modrinth API，实现 Mod 的搜索、安装、更新功能。可列出已安装 Mod，检查更新，一键升级。
- **自动配置检测**：安装核心后，自动分析并设置 `server.properties` 的基本字段（如端口、游戏模式等），并提示用户同意 EULA。
- **保留拖入即用**：尽管有了向导式安装，但用户依然可以直接把已经配置好的服务器文件夹拖入 MC-Minder 根目录，MC-Minder 会自动识别并纳入管理。

## 7. 更实用的工具箱

- **内置指令快捷面板**：在 TUI 中提供一个可自定义的常用指令按钮面板，如“切换到和平模式”、“传送到某玩家”、“查看TPS”等，点击即可发送。
- **崩溃报告查看器**：主动扫描服务器的崩溃报告文件夹，自动列出时间排序的崩溃报告，点击即可查看详细堆栈信息，高亮关键错误行，辅助排查问题。
- **服务器沟通界面**：可在 TUI 中直接向在线玩家广播消息，支持动态公告（类似“服务器将在5分钟后重启”）。

## 8. 架构与跨平台增强

- **多服务器隔离与并发**：每个服务器实例在独立线程或异步任务中管理，确保一个服务器崩溃不影响其他服务器。
- **Web 界面预备**：考虑未来可能扩展 Web 管理面板，保持前后端分离架构，HTTP API 继续丰富端点，为 Web 客户端铺路。
- **Windows 兼容性优化**：继续完善 Windows 下 TUI 的按键兼容性（如小键盘、NumLock 问题），确保体验与 Linux 一致。
- **保持轻量**：所有新功能保持模块化，按需启用，不增加基础内存占用，确保在 Termux/树莓派等低配环境依然流畅运行。

## 9. 实施指南

- 先重构数据结构以支持多服务器，再逐步添加 TUI 改进，最后实现高级功能（懒启动、计划任务等），每步都保证向后兼容。
- 所有新功能的配置项都加入 `config.toml` 中，提供合理默认值。
- 时刻测试 Termux 环境兼容性，确保移动端体验不打折。
- 代码保持原创，不参考任何竞争项目源码，只借鉴产品功能和交互思路。
