更新 Home

Home.md

@@ -183,4 +183,64 @@ scheduler.update_listen_data("on_config_changed", "dark_mode=true")
 # ... 主程序继续运行 ...
 # 当需要关闭时：
 # scheduler.stop_queue_scheduler()
-```
+```
+
+## 详细使用指南
+
+### 消息优先级的使用
+
+### 设置任务过期时间
+
+### 错误处理与重试机制
+
+### 如何扩张分片数
+
+### 监听器的高级用法
+
+## API 文档
+
+`MessageItem`
+
+- `to_dict() -> Dict`：转化为字典
+- `to_dict_by_core() -> Dict`：转换为核心库所需的格式（字符串化的 JSON）。
+- `classmethod from_dict(data: Dict) -> MessageItem`：从字典创建对象。
+-  `is_expired() -> bool`：检查消息是否过期。
+
+`QueueScheduler`
+
+- `__init__(receive_thread_num=1, task_thread_num=1, shard_num=4)`
+- `start_queue_scheduler()`：启动所有后台线程。
+- `stop_queue_scheduler()`：停止所有后台线程。
+- `send_message(message: MessageItem, callback: Callable)`：发送任务。
+- `update_listen_data(key: str, value: Any)`：更新监听数据。
+- `get_listen_data(key: str) -> Any`：获取监听数据当前值。
+
+### 装饰器
+
+- `@TaskMounter.task(meta: dict = {})`
+- `@ListenMounter.listener()`
+
+## 性能调优
+
+1. **分片 (`shard_num`)**：这是最重要的参数。根据你的工作负载和 CPU 核心数增加分片（例如 8，16），可以显著提高入队/出队的吞吐量。
+2. **线程数**：`task_thread_num` 应根据任务类型（I/O 密集型或 CPU 密集型）进行调整。
+3. **SQLite 优化**：Rust 核心层已经设置了积极的 PRAGMA 选项（WAL，NORMAL sync，大缓存）。除非非常了解，否则不建议修改。
+4. **消息大小**：保持 `MessageItem.content` 尽可能小，大的数据应该存储在其他地方（如 S3、数据库），只在消息中存储引用 ID。
+
+## 常见问题
+
+**Q：任务函数执行失败了怎么办？**
+A：任务状态会被标记为 `FAILED`。根据 `retry_count` 和你的逻辑，你可以选择重新发送该消息
+
+**Q：如何查询队列中当前的任务数量**
+A：使用 `scheduler.queue_operation.get_queue_length()`。
+
+**Q：如何手动触发清理？**
+A：可以调用 `scheduler.cleanup_scheduler.cleanup_expired_message()`，但通常清理调度器会自动处理。
+
+*Q：编译 Rust 扩展时出错？*
+A：确保你的 Rust 工具链是最新的 (`rustup update`)。在 Windows 上，你可能需要安装 Microsoft C++ Build Tools。
+
+*Q：`destination 找不到对应的任务函数`？*
+A：确保任务函数被正确装饰（`@TaskMounter.task`）并且其 `__name__` 与 `destination` 字符串完全一致。确保包含任务函数的模块在运行主程序前已被导入。
+