refactor(permission): 重构权限管理系统，合并管理员管理功能

- 将 admin_manager 功能整合到 permission_manager 中，统一管理
- 采用文件为主、Redis 为辅的架构，确保数据一致性
- 实现原子操作机制，防止数据损坏
- 更新文档说明新的权限管理机制
- 调整相关模块引用和编译配置

docs/core-concepts/redis-atomic-operations.md

@@ -0,0 +1,135 @@
+# Redis 原子操作与数据一致性
+
+## 概述
+
+NEO Bot 的权限管理系统采用了文件为主、Redis 为辅的架构设计，确保数据可靠性和高性能访问的平衡。为了保证数据一致性，系统在所有写操作中都实现了原子操作机制。
+
+## 设计理念
+
+### 以文件为权威数据源
+
+- **主数据源**: `core/data/permissions.json` 作为权限数据的权威来源
+- **缓存层**: Redis 作为高速缓存，提供快速访问能力
+- **一致性保障**: 所有写操作都以文件为准，再同步到 Redis
+
+### 原子操作实现
+
+所有权限管理的写操作都遵循以下原子操作模式：
+
+1. **读取当前状态**: 从 `permissions.json` 读取当前数据
+2. **内存中修改**: 在内存中完成数据修改
+3. **原子写入**: 使用临时文件 + 原子重命名的方式写入磁盘
+4. **缓存同步**: 将修改同步到 Redis 缓存
+
+## 核心实现细节
+
+### 原子文件写入
+
+```python
+# 原子写入操作示例
+temp_file = self.data_file + ".tmp"
+with open(temp_file, "w", encoding="utf-8") as f:
+    f.write(json.dumps(data, indent=2, ensure_ascii=False))
+os.replace(temp_file, self.data_file)  # 原子操作
+```
+
+- 使用临时文件避免写入过程中数据损坏
+- `os.replace()` 确保操作的原子性
+- 即使在写入过程中断电，也不会破坏原文件
+
+### Redis 同步机制
+
+```python
+# 同步文件内容到 Redis
+async def _sync_file_to_redis(self):
+    # 清空 Redis 中的现有数据
+    await redis_manager.redis.delete(self._REDIS_KEY)
+    await redis_manager.redis.delete(self._REDIS_ADMINS_KEY)
+    
+    # 从文件加载数据并同步到 Redis
+    # ...
+```
+
+- 使用 Redis 管道操作提高批量写入效率
+- 确保 Redis 与文件数据的一致性
+
+## 支持的操作
+
+### 权限管理操作
+
+- `set_user_permission()`: 设置用户权限
+- `remove_user()`: 移除用户权限
+- `add_admin()`: 添加管理员
+- `remove_admin()`: 移除管理员
+- `clear_all()`: 清空所有权限
+
+### 数据隔离
+
+- 普通权限存储在 Redis Hash (`neobot:permissions`) 中
+- 管理员列表存储在 Redis Set (`neobot:admins`) 中
+- 避免数据冲突，提高查询效率
+
+## 性能优化
+
+### 读取优化
+
+- 读取操作直接从 Redis 缓存获取，毫秒级响应
+- 减少磁盘 I/O，提升系统性能
+
+### 批量操作
+
+- 使用 Redis 管道进行批量操作
+- 减少网络往返次数，提高吞吐量
+
+## 错误处理
+
+### 异常恢复
+
+- 文件写入失败时，保留原数据不丢失
+- Redis 操作失败时，不影响文件数据
+- 提供详细的错误日志便于排查
+
+### 数据校验
+
+- 写入前校验数据格式
+- 防止非法数据进入系统
+
+## 最佳实践
+
+### 插件开发建议
+
+```python
+# 在插件中使用权限管理器
+from core.managers import permission_manager
+from core.permission import Permission
+
+# 查询权限
+user_perm = await permission_manager.get_user_permission(user_id)
+
+# 检查权限
+if await permission_manager.check_permission(user_id, Permission.ADMIN):
+    # 执行管理员操作
+    pass
+```
+
+### 高并发场景
+
+- 系统设计支持高并发读取
+- 写操作频率较低，适合权限管理场景
+- Redis 缓存有效缓解数据库压力
+
+## 故障恢复
+
+### Redis 故障
+
+- Redis 不可用时，系统仍可通过文件数据提供服务
+- Redis 恢复后，自动从文件同步最新数据
+
+### 文件损坏
+
+- 系统定期备份权限数据
+- 可从历史备份中恢复数据
+
+## 总结
+
+通过以文件为权威数据源、Redis 为缓存层的设计，结合原子操作机制，NEO Bot 的权限管理系统在保证数据可靠性的同时，提供了高性能的访问能力。这种设计既满足了数据一致性的要求，又兼顾了系统性能的需求。

docs/core-concepts/singleton-managers.md

@@ -30,14 +30,9 @@
 *   **管啥**:
     *   **划分三六九等**: `ADMIN`, `OP`, `USER` 这些等级都是它定的。
     *   **管理权限**: 谁有啥权限，都记在 `core/data/permissions.json` 里。
-    *   **会自动变通**: 查权限的时候，它会把 `AdminManager` 里的超管也当成 `ADMIN`。
-
-### 3. `AdminManager` (`admin_manager`)
-
-*   **怎么找**: `from core.managers.admin_manager import admin_manager`
-*   **管啥**:
-    *   **钦差大臣**: 专门管机器人的超级管理员，增删改查都在这。
-    *   **三级缓存**: 内存 -> Redis -> 文件
+    *   **管理员管理**: 超级管理员的增删改查也在这里，统一管理。
+    *   **双重存储**: 普通权限存储在 Redis Hash 中，管理员列表存储在 Redis Set 中。
+    *   **原子操作**: 所有写操作都采用原子操作，确保数据一致性。详见 [Redis 原子操作与数据一致性](./redis-atomic-operations.md)
 
 ### 4. `PluginManager`
 

docs/index.md

@@ -17,6 +17,7 @@
 *   [性能优化](./core-concepts/performance.md): 页面池、JIT、Mypyc... 
 *   [消息流](./core-concepts/event-flow.md): 看看一条消息从被接收到被回复是如何运行的
 *   [核心](./core-concepts/singleton-managers.md): `matcher`, `browser_manager`... 认识这些核心模块。
+*   [Redis 原子操作与数据一致性](./core-concepts/redis-atomic-operations.md): 权限管理系统的原子操作实现，确保数据一致性
 *   [错误处理](./core-concepts/error-handling.md): 了解系统的错误处理机制和错误码定义。
 
 ### 3. API 参考