Introduces several major improvements

.github/workflows/test.yml

@@ -0,0 +1,116 @@
+name: CI/CD
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths-ignore:
+      - '**.md'
+      - '.gitignore'
+      - '.idea/**'
+  pull_request:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '.gitignore'
+      - '.idea/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # 1. 测试任务
+  test:
+    name: Test & Lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 pytest
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+    - name: Lint with flake8
+      run: |
+        flake8 . --count --select=E9,F63,F7,F82,F401,F403 --show-source --statistics
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+    - name: Run tests
+      run: |
+        export PYTHONPATH=$PYTHONPATH:.
+        pytest -v
+
+  # 2. 构建任务 (仅当测试通过后运行)
+  build:
+    name: Build Plugin
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+      - name: Pack Plugin
+        run: |
+          python -m mcdreforged pack -o ./package
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: SakuraFlow-Build
+          path: package/*.mcdr
+          retention-days: 5
+
+  # 3. 发布任务 (仅当构建成功且是 Tag 推送时运行)
+  release:
+    name: Publish Release
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: SakuraFlow-Build
+          path: package/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: package/*.mcdr
+          generate_release_notes: true

.gitignore

@@ -8,3 +8,14 @@
 /dataSources.local.xml
 /.idea/
 /sakura_flow/__pycache__/
+
+# Python 缓存
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Pytest 缓存
+.pytest_cache/
+
+# MCDR 打包输出
+package/

README.md

@@ -1,89 +1,159 @@
 # Sakura Flow
 
-一款专注于**依赖管理**与**深度交互**的 MCDReforged 待办事项插件。
-Sakura Flow 旨在解决长周期、多线并行的复杂任务管理难题，提供极简的输入体验和类似 IDE 的聊天栏交互界面。
+**Sakura Flow** 是一款基于 MCDReforged 的 Minecraft 服务器**高级待办事项（Todo）管理插件**。
 
-## ✨ 核心特性
+Sakura Flow 旨在解决长周期、多线并行的复杂任务管理难题（如大型机器搭建、自动化流水线设计等）。通过充分利用 Minecraft 聊天栏的富文本功能，插件提供了**悬浮预览**、**点击跳转**与**指令自动填充**等交互特性，实现了高效、直观的任务管理体验。
 
-* **极简输入**: 减少繁琐打字，支持字段别称（如 `t` 代表 `tier`），让指令输入如行云流水。
-* **深度交互**: 充分利用 Minecraft 聊天栏富文本（RText），将聊天栏打造为交互式“控制面板”。支持悬浮预览详情、点击执行指令。
-* **流程管理**: 专为复杂任务链设计，强调任务的**前置依赖（Dependencies）**管理，自动梳理任务执行顺序。
-* **层级可视化**: 内置动态颜色系统，根据任务等级（Tier）显示不同颜色，直观区分任务重要性或阶段。
-* **协作管理**: 支持多玩家协作，记录任务创建者与协作者。
-* **自然排序**: 依赖项 ID 自动按数值排序，协作者和标签按字典序排序。
+## ✨ 核心特性
 
-## 🛠️ 指令系统
+* **游戏内管理**: 直接在聊天栏进行全流程任务管理，无需切换窗口。
+* **富文本交互**: 基于 Minecraft 聊天栏的**富文本（JSON）** 特性，支持点击按钮执行指令（完成、暂停、查看详情），操作便捷。
+* **依赖管理**: 专为复杂工程设计，支持设置任务**前置条件（Dependencies）**，自动梳理任务执行顺序。
+* **高效输入**: 提供智能指令别名系统（如 `t` 代表 `tier`），简化指令输入流程。
+* **层级可视化**: 内置动态颜色系统，根据任务等级（Tier）自动区分显示样式，直观展示任务重要性。
+
+## 🚀 快速上手 (Quick Start)
+
+本节介绍插件的基本工作流：
+
+1. **创建任务**
+    示例：创建一个名为“建造刷铁机”的任务。任务会自动分配一个唯一的ID，后续操作该任务需要使用其ID。
+    `!!todo add 建造刷铁机`
+2. **查看列表**
+    显示当前所有待办任务。
+    `!!todo list`
+    *(提示：鼠标悬浮在 `[#ID]` 上可预览任务摘要)*
+3. **追加记录**
+    为任务添加详细说明或进度笔记。
+    `!!todo note <ID> 需要准备 20 张床` 或者 `!!todo note <ID> 已完成建筑材料的准备`
+    *(提示：点击列表中的 `[✎]` 按钮可自动填充此指令前缀)*
+4. **标记完成**
+    任务完成后，将其标记为 Done 并归档。
+    `!!todo complete <ID>`
+    *(提示：也可直接点击列表中的 `[✔]` 按钮)*
+5. **查看历史任务**
+    `!!todo archive`可查看所有已完成的历史任务
+
+## 📖 指令手册
 
 所有指令前缀为 `!!todo`。
 
-### 任务创建
+### 1. 基础操作
 
-| 指令                   | 别称         | 说明       |
-|:---------------------|:-----------|:---------|
-| `!!todo add <title>` | `!!todo a` | 创建一个新任务。 |
+| 动作     | 指令格式                   | 别称  | 说明                     |
+|:-------|:------------------|:----|:-----------------------|
+| **新建** | `!!todo add <标题>`      | `a` | 创建一个新任务。任务会自动分配一个唯一的ID，后续操作该任务需要使用其ID。   |
+| **列表** | `!!todo list`          | `l` | 显示所有**进行中**的任务（含交互按钮）。**已完成**的任务见后文进阶管理。 |
+| **详情** | `!!todo info <ID>`     | `i` | 查看指定任务的详细信息（依赖、笔记等）。   |
+| **完成** | `!!todo complete <ID>` | -   | 标记任务为完成并移入归档。     |
+| **帮助** | `!!todo help`          | -   | 显示帮助菜单。                |
 
-### 查询与管理
+### 2. 进阶管理
 
-| 指令                 | 别称          | 说明                         |
-|:-------------------|:------------|:---------------------------|
-| `!!todo list`      | `!!todo l`  | 显示当前所有 **未完成** 的任务（含交互按钮）。 |
-| `!!todo archive`   | `!!todo ar` | 显示所有 **已完工** 的历史任务。        |
-| `!!todo info <id>` | `!!todo i`  | 查看任务详情，支持依赖项悬浮预览和跳转。       |
-| `!!todo help`      | -           | 显示帮助菜单。                    |
+| 动作       | 指令格式                    | 别称   | 说明                       |
+|:---------|:------------------------|:-----|:-------------------------|
+| **记笔记**  | `!!todo note <ID> <内容>` | `n`  | 追加一条带有时间戳的进度记录。          |
+| **暂停**   | `!!todo pause <ID>`     | -    | 挂起任务（状态变更为 On Hold）。     |
+| **恢复**   | `!!todo resume <ID>`    | -    | 恢复任务（状态变更为 In Progress）。 |
+| **归档库**  | `!!todo archive`        | `ar` | 查看所有已完成的历史任务。            |
+| **恢复归档** | `!!todo restore <ID>`   | -    | 将已完成的任务恢复至进行中状态。         |
 
-### 快捷操作
+### 3. 属性修改 (Set/Modify)
 
-| 指令                        | 别称         | 说明                          |
-|:--------------------------|:-----------|:----------------------------|
-| `!!todo note <id> <text>` | `!!todo n` | 追加带有时间戳和作者的任务进度记录。          |
-| `!!todo complete <id>`    | -          | 一键标记为 **Done** 并移入归档。       |
-| `!!todo pause <id>`       | -          | 状态切换为 **On Hold**，暂停项目。     |
-| `!!todo resume <id>`      | -          | 状态切换为 **In Progress**，恢复项目。 |
-| `!!todo restore <id>`     | -          | 从归档中恢复任务至 **In Progress**。  |
+用于修改任务的各项属性，如等级、依赖关系等。
 
-### 属性修改
+| 操作类型      | 指令格式                          | 别称   | 说明                                |
+|:----------|:------------------------------|:-----|:----------------------------------|
+| **修改单值**  | `!!todo set <ID> <属性> <值>`    | `s`  | 修改标题、等级、优先级等单值属性。                 |
+| **添加列表项** | `!!todo append <ID> <属性> <值>` | `ap` | 向列表属性（如依赖 `dep`、协作者 `collab`）追加值。 |
+| **移除列表项** | `!!todo remove <ID> <属性> <值>` | `rm` | 从列表属性中移除指定值。                      |
 
-| 指令                                  | 别称          | 说明                                                        |
-|:------------------------------------|:------------|:----------------------------------------------------------|
-| `!!todo set <id> <prop> <value>`    | `!!todo s`  | 修改单值属性（如 title, tier, priority）。<br>Tier 支持数字输入，用于区分任务等级。 |
-| `!!todo append <id> <list> <value>` | `!!todo ap` | 向列表属性（dep, collab, label）追加项。<br>追加依赖时会检查 ID 是否存在。        |
-| `!!todo remove <id> <list> <value>` | `!!todo rm` | 从列表属性中移除特定项。                                              |
+> **说明**:
+>
+> * **Tier (等级)**: 支持 `0-14` 的整数。数值越大，任务在列表中的显示颜色越醒目。
+> * **Dependencies (依赖)**: 使用 `!!todo ap <ID> dep <前置ID>` 添加依赖关系。
 
-## 🖥️ 交互界面
+## 🖱️ 交互界面指南
 
-插件在聊天栏提供丰富的交互元素：
+插件在聊天栏提供以下交互元素：
 
 * **列表视图**:
-    * `[#ID]`: 悬浮显示详情，点击填充查询指令。
-    * `[▶/⏸]`: 点击快捷切换 暂停/进行中 状态。
-    * `[✔]`: 点击一键完成任务。
-    * `[✎]`: 点击快捷填充笔记指令。
+  * `[#ID]`: **悬浮**查看摘要，**点击**自动填充 `info` 指令。
+  * `[▶] / [⏸]`: **点击**切换 暂停/进行中 状态。
+  * `[✔]`: **点击**直接完成任务。
+  * `[✎]`: **点击**自动填充 `note` 指令。
 * **详情视图**:
-    * **等级颜色**: 根据 Tier 等级显示对应颜色，高等级任务会有更醒目的高亮显示。
-    * **依赖链**: 依赖项以 `[#ID]` 展示，支持悬浮预览状态，点击跳转。
+  * **依赖链**: 点击依赖任务的 ID 可跳转查看该前置任务的详情。
 
 ## 📦 安装说明
 
-1. 确保已安装 [MCDReforged](https://github.com/MCDReforged/MCDReforged)。
-2. 将本插件文件夹放入 `plugins` 目录。
-3. 在 MCDR 中重载插件。
-
-## 📝 字段说明
-
-### 单值属性 (Set)
-
-| 属性名           | 别称          | 说明   | 合法值示例                                      |
-|:--------------|:------------|:-----|:-------------------------------------------|
-| `title`       | `title`     | 任务名称 | 任意文本                                       |
-| `description` | `desc`      | 详细描述 | 任意文本                                       |
-| `status`      | `stat`, `s` | 任务状态 | `In Progress`, `On Hold`, `Done`           |
-| `tier`        | `t`         | 任务等级 | `0`-`14` (数字越大颜色越醒目)                       |
-| `priority`    | `prio`, `p` | 优先级  | `0`-`4` 或 `Very High`, `High`, `Medium`... |
-
-### 列表属性 (Append/Remove)
-
-| 属性名             | 别称            | 说明                  |
-|:----------------|:--------------|:--------------------|
-| `collaborators` | `collab`, `c` | 协作者列表               |
-| `dependencies`  | `dep`, `d`    | 前置任务 ID 列表 (自动数值排序) |
-| `labels`        | `label`, `l`  | 标签列表                |
+1. 确保服务端已安装 [MCDReforged](https://github.com/MCDReforged/MCDReforged)。
+2. 下载本插件，将文件夹放入 `plugins` 目录。
+3. 在控制台或游戏内输入 `!!MCDR plugin reload` 重载插件。
+
+## 📝 附录：属性字段速查
+
+在执行 `set`, `append`, `remove` 时可用的属性名及其简写：
+
+| 属性全名            | 简写            | 类型    | 说明                    |
+|:----------------|:--------------|:------|:----------------------|
+| `title`         | -             | 文本    | 任务标题                  |
+| `description`   | `desc`        | 文本    | 详细描述                  |
+| `tier`          | `t`           | 数字    | 任务等级 (0-14)           |
+| `priority`      | `p`, `prio`   | 文本/数字 | 优先级 (High, Medium...) |
+| `dependencies`  | `d`, `dep`    | 列表    | **前置任务 ID**           |
+| `collaborators` | `c`, `collab` | 列表    | 协作者玩家名               |
+| `labels`        | `l`, `label`  | 列表    | 自定义标签                 |
+
+## 🛠️ 示例：建造刷铁机
+
+以下是从零开始管理一个“刷铁机建造工程”的完整指令流：
+
+### 1. 创建与基础设置
+* **创建主任务**：
+  `!!todo add 建造高效刷铁机` (假设分配 ID 为 `1`)
+* **设置任务等级**：
+  `!!todo set 1 tier 5` (将等级设为 5，使其在列表中以更醒目的颜色显示)
+* **设置任务优先级**：
+  `!!todo set 1 priority High` (标记为高优先级)
+* **添加详细描述**：
+  `!!todo set 1 desc 位于主城坐标 100, 64, 200 的 32 堆叠刷铁机`
+
+### 2. 细化任务与依赖管理
+* **创建前置子任务**：
+  `!!todo add 收集 20 张床` (假设分配 ID 为 `2`)
+  `!!todo add 运输 3 名村民` (假设分配 ID 为 `3`)
+* **建立依赖关系**：
+  `!!todo append 1 dep 2` (主任务 `1` 现在依赖于 `2`)
+  `!!todo append 1 dep 3` (主任务 `1` 现在依赖于 `3`)
+
+### 3. 协作与进度记录
+* **添加协作者**：
+  `!!todo append 1 collab Steve` (邀请 Steve 一起参与)
+* **记录进度笔记**：
+  `!!todo note 2 已在沙漠村庄收集到 12 张床，还差 8 张`
+* **添加标签**：
+  `!!todo append 1 label 工业`
+
+### 4. 状态流转
+* **查看当前进度**：
+  `!!todo list` (查看所有任务状态)
+* **查看任务 1 的详细依赖链**：
+  `!!todo info 1`
+* **暂时挂起**：
+  `!!todo pause 1` (因材料不足暂时停工)
+* **恢复施工**：
+  `!!todo resume 1`
+* **完成前置任务**：
+  `!!todo complete 2`
+  `!!todo complete 3`
+* **最终归档**：
+  `!!todo complete 1`
+
+### 5. 维护与回顾
+* **查看已完成的任务**：
+  `!!todo archive`
+* **移除不再需要的标签**：
+  `!!todo remove 1 label 工业`
+* **若发现漏掉细节需要重做**：
+  `!!todo restore 1`