SenSu/docs/SenSu 框架基本架构.md

一、项目架构与设计思路

1.1 核心设计理念

SenSu框架采用了服务化、插件化、事件驱动的设计理念：

• 模块化服务架构：每个功能都是一个独立服务（Service），通过ServiceManager统一管理
• 异步优先：全面采用asyncio，支持高并发处理
• 插件隔离：插件有独立的命名空间和权限控制
• 桥接通信：通过消息桥接实现模块间解耦通信

1.2 框架启动流程

main.py → SenSuFramework.initialize() → 依次初始化15+个核心服务

启动顺序：

1. InitService（配置加载）
2. LogService（日志系统）
3. CoreBridge（核心消息桥接）
4. CommandService（命令系统）
5. AuthService（认证系统）
6. PluginBridge（插件桥接）
7. ShutdownService（优雅关闭）
8. TuiService（终端界面）
9. PermissionService（权限管理）
10. InternetService（网络服务）
11. PluginService（插件管理）
12. APIService（API服务）

二、目录结构详细分析

2.1 核心目录说明

SenSu-Alpha0.2/
├── main.py                    # 框架主入口，定义CatFramework类
├── service_manager.py         # 服务管理器（全局服务注册表）
├── requirements.txt           # Python依赖包
├── README.md                  # 项目文档
│
├── bridges/                   # 消息桥接系统
│   ├── __init__.py
│   ├── core_bridge.py         # 核心模块间通信（发布-订阅模式）
│   ├── plugin_bridge.py       # 插件间通信
│   └── plugin_network_bridge.py # 插件网络桥接
│
├── services/                  # 核心服务模块（核心业务逻辑）
│   ├── init_service.py       # 框架初始化
│   ├── log_service.py        # 日志服务（多输出、文件切割）
│   ├── tui_service.py        # TUI终端界面（基于Textual）
│   ├── command_service.py    # 命令处理系统
│   ├── auth_service.py       # 认证系统
│   ├── internet_service.py   # 网络服务（HTTP+WebSocket）
│   ├── plugin_service.py     # 插件管理器
│   ├── permission_service.py # 权限验证器
│   ├── api_service.py        # API端点管理
│   └── shutdown_service.py   # 优雅关闭
│
├── core/                   # 框架功能集（工具函数）
│   └── plugin_command_decorator.py # 插件命令装饰器
│
├── utils/                     # 通用工具类
│   ├── file_utils.py         # 文件操作
│   ├── config_utils.py       # 配置管理
│   ├── validation_utils.py   # 数据验证
│   ├── network_utils.py      # 网络工具
│   └── plugin_utils.py       # 插件工具
│
├── config/                    # 运行时配置文件
│   ├── framework/            # 框架核心配置
│   ├── plugins/              # 插件配置
│   ├── services/             # 服务配置
│   └── permissions/          # 权限配置
│
├── plugins/                   # 插件目录
│   └── example_plugin/       # 示例插件
│
└── gui/                      # GUI接口（预留）
    └── api.py                # Web API接口

2.3 配置管理系统

框架使用两级配置：

1. Base Config (config/framework/base_config.yaml): 框架基础配置
2. Runtime Config: 运行时动态生成的配置（保存在config目录）

三、核心模块深度解析

3.1 服务管理器（ServiceManager）

作用：全局服务注册表，实现依赖注入

# 注册服务
service_manager.register_service("log", log_service)

# 获取服务
log_service = service_manager.get_service("log")

3.2 桥接系统（Bridges）

核心设计：

• CoreBridge: 模块间通信，支持MessageType枚举
• PluginBridge: 插件间通信，支持PluginMessageType枚举
• 消息格式：topic + data + timestamp

消息类型：

class MessageType(Enum):
    EVENT = "event"      # 事件通知
    COMMAND = "command"  # 命令执行
    DATA = "data"        # 数据传输
    STATUS = "status"    # 状态更新
    ERROR = "error"      # 错误报告

3.3 日志系统（LogService）

特性：

• 支持控制台和文件双输出
• 按级别分离（runtime/debug）
• 自动文件切割和清理
• 日志消费者模式（TUI实时显示）
• 彩色日志输出

配置示例：

logging:
  level: DEBUG
  debug_level_file: true
  max_file_size: 10MB
  max_log_files: 20

3.4 TUI界面（TuiService）

基于Textual框架的三栏布局：

1. 日志区域（4fr）: 显示所有日志输出
2. 消息区域（5fr）: 显示系统消息和命令结果
3. 输入区域（1fr）: 命令输入框

特性：

• 实时日志捕获和显示
• 命令自动补全（预留）
• 滚动控制（自动/手动）
• 彩色消息显示

3.5 网络服务（InternetService）

功能：

• HTTP服务器（aiohttp）
• WebSocket服务器
• 插件路由自动注册
• 反向代理支持（预留）

端口配置：

internet:
  websocket:
    port: 8765
  http:
    port: 8000

3.6 插件系统（PluginService）

关键特性：

• 热加载/卸载
• 权限隔离
• 命令自动注册
• 错误隔离（插件崩溃不影响框架）
• 网络路由自动注册

四、插件开发详解

4.1 插件目录结构

plugins/
└── example_plugin/
    ├── __init__.py          # 插件主类（必须包含Plugin类）
    ├── config.yaml          # 插件配置
    └── permissions.yaml     # 权限申请

4.2 插件主类模板

class Plugin:
    def __init__(self, plugin_name: str, config: Dict, bridge):
        self.plugin_name = plugin_name
        self.config = config
        self.bridge = bridge        # PluginBridge实例
        self.network_bridge = None  # PluginNetworkBridge实例
    
    async def initialize(self):
        """插件初始化"""
        # 1. 创建网络桥接
        self.network_bridge = PluginNetworkBridge(...)
        
        # 2. 注册网络路由
        await self.network_bridge.register_http_route(...)
        await self.network_bridge.register_websocket(...)
        
        # 3. 注册事件处理器
        self.bridge.subscribe_plugin(...)
    
    # 使用装饰器注册命令
    @plugin_command(name="mycmd", description="我的命令")
    async def my_command(self, *args):
        return "命令执行结果"
    
    async def shutdown(self):
        """插件关闭"""
        # 清理资源

4.3 权限申请文件（permissions.yaml）

plugin_name: "example_plugin"
permissions:
  - "plugin.example.read"
  - "plugin.example.write"
  - "plugin.example.execute"
  - "framework.event.subscribe"
  - "framework.command.execute"

4.4 插件配置文件（config.yaml）

name: "ExamplePlugin"
version: "1.0.0"
description: "插件描述"
author: "作者名"

settings:
  enabled: true
  auto_start: true
  log_level: "INFO"

features:
  # 插件特有配置

4.5 插件命令装饰器

框架提供了@plugin_command装饰器：

from core.plugin_command_decorator import plugin_command

@plugin_command(name="echo", description="回显消息")
async def cmd_echo(self, *args):
    return " ".join(args)

# 简化版
@plugin_command()
async def hello(self, *args):
    '''打招呼命令'''
    return "Hello World!"

4.6 插件网络功能

HTTP路由注册：

await self.network_bridge.register_http_route(
    "/api/info", 
    self._handle_api_info,
    methods=["GET"],
    require_auth=False
)

WebSocket注册：

await self.network_bridge.register_websocket(
    "/chat",
    self._handle_websocket_chat
)

五、命令系统详解

5.1 内置命令

框架提供丰富的内置命令：

• help - 显示帮助
• status - 框架状态
• history - 命令历史
• testlog - 测试日志生成
• netdiag - 网络诊断
• permissions - 权限管理
• scroll - 滚动控制
• autoscroll - 自动滚动开关

5.2 权限管理命令

框架提供完整的权限管理命令集（pm前缀）：

• pmallow - 同意权限请求
• pmdeny - 拒绝权限请求
• pmignore - 忽略权限请求
• permissions - 显示权限状态
• pmpending - 查看待授权请求
• pmhelp - 权限命令帮助

5.3 命令注册机制

插件命令注册流程：

1. PluginService扫描插件方法
2. 识别@plugin_command装饰器
3. 注册到CommandService
4. 命令格式：命令名 [参数...]

六、开发建议与最佳实践

6.1 插件开发建议

1. 错误处理：插件内应妥善处理异常，避免影响框架
2. 资源管理：在shutdown方法中清理所有资源
3. 异步安全：确保异步方法正确处理取消和超时
4. 权限最小化：只申请必要的权限

6.2 性能优化

1. 异步IO：所有网络和文件操作使用异步版本
2. 连接池：数据库/网络连接使用连接池
3. 缓存机制：频繁读取的数据适当缓存
4. 懒加载：大型资源按需加载

6.3 安全性考虑

1. 输入验证：所有外部输入都应验证
2. 权限验证：敏感操作前检查权限
3. 日志脱敏：避免在日志中记录敏感信息
4. API限流：防止API被滥用

七、框架优势与特点

7.1 优势

1. 完整的生态：日志、网络、UI、插件系统一应俱全
2. 良好的扩展性：插件系统设计完善
3. 生产级质量：完善的错误处理和日志记录
4. 开发者友好：详细的文档和示例插件

7.2 适用场景

1. 后台管理工具：需要终端界面的管理工具
2. API网关：插件化路由和认证
3. 自动化平台：可扩展的任务调度和执行
4. 监控系统：实时数据展示和告警

7.3 技术栈亮点

• 异步架构：asyncio全面应用
• 现代化UI：基于Textual的TUI
• 微服务理念：服务化模块设计
• 企业级特性：权限、认证、日志一应俱全

八、后续发展建议

8.1 功能增强

1. 数据库支持：添加ORM或数据库连接池
2. 任务队列：集成Celery或类似系统
3. 监控指标：集成Prometheus指标导出
4. 配置文件热重载：支持运行时配置更新

8.2 易用性改进

1. 插件市场：在线插件安装和管理
2. 配置生成器：图形化配置界面
3. 调试工具：集成调试和性能分析
4. 文档生成：自动生成API文档

8.3 生态建设

1. 插件模板：快速创建插件的脚手架
2. 测试框架：插件测试工具
3. CI/CD集成：自动化测试和部署
4. 社区建设：建立插件开发者社区

总结

SenSu框架是一个设计精良、功能完整的Python后端框架，具有以下核心价值：

1. 工程化设计：服务化架构、完善的错误处理、详细的日志
2. 强大的插件系统：支持热加载、权限隔离、网络路由自动注册
3. 现代化的用户体验：基于Textual的TUI界面，美观实用
4. 企业级特性：完整的权限管理、认证系统、网络服务

框架代码结构清晰，文档详细，适合作为：

• 企业级后台系统的基础框架
• 插件化应用的核心引擎
• 学习和研究现代Python框架设计的优秀案例

对于想要基于此框架进行开发的开发者，建议从example_plugin入手，逐步理解框架的各个组件，然后根据业务需求开发定制插件。

九、v0.2.1 新增：插件系统增强

9.1 PluginStatus 枚举 (core/plugin_status.py)

统一的插件生命周期状态：

• UNLOADED → LOADING → LOADED → INITIALIZING → RUNNING
• 异常路径: ERROR, STOPPING, STOPPED, UNLOADING

9.2 PluginError 异常层级 (core/plugin_error.py)

PluginError (基础)
├── PluginLoadError       (加载失败)
├── PluginConfigError     (配置错误)
├── PluginPermissionError (权限不足)
├── PluginCommandError    (命令执行错误)
└── PluginNetworkError    (网络操作错误)

9.3 PluginBridge 新方法

• subscribe_plugin(topic, handler, plugin_name) — 便捷订阅，同时注册到 CoreBridge 和插件订阅表

9.4 PluginNetworkBridge 新方法

• setup_data_transfer(event_type, handler) — 跨插件数据传输通道
• send_data(target_plugin, event_type, data) — 向其他插件发送数据

9.5 PluginService 增强

• 配置验证：加载时检查 name、version 必需字段
• 状态追踪：plugin_status 字典跟踪每个插件的 PluginStatus

十、v0.6.0 新增：WebUI 重构 + 文件管理器

10.1 Web 面板路由 (services/web_panel/)

v0.6.0 将 Web 面板重构为模块化路由架构：

services/web_panel/
├── manager.py          # WebPanelManager — 路由注册 + 静态挂载
├── routes/
│   ├── auth.py         # 认证 API (login/logout/status)
│   ├── status.py       # 框架/系统状态 + WS 实时推送
│   ├── plugins.py      # 插件管理 API
│   ├── commands.py     # 命令执行 API
│   ├── logs.py         # 日志 WS 广播
│   ├── projects.py     # 项目引擎 API (run/stop/logs/stdin)
│   ├── proxy.py        # 反向代理 API
│   ├── plugin_web.py   # 插件 Web 页面动态路由
│   └── files.py        # 文件管理器 API (11 个端点) ← NEW
└── utils/
    ├── auth.py         # panel_auth 装饰器
    └── system_info.py  # 跨平台系统信息采集

10.2 文件管理器 (v0.6.0)

• 后端: services/web_panel/routes/files.py — 11 个 REST 端点
  • 列表/新建/删除/重命名/上传/下载/读写/文件信息
  • 全文件系统访问，os.path.normpath 防路径穿越
  • 跨平台: Windows 盘符枚举 + Linux / 根
  • 符号链接: stat() 跟踪 → lstat() fallback 处理损坏
• 前端: pages/files.html + pages/files.js
  • 面包屑导航 (每层级可点击) + 可编辑路径跳转
  • 双层面包屑 (逻辑路径 + 物理路径，符号链接目录)
  • 右键菜单 (下载/重命名/编辑/删除)
  • 文本编辑器 (全屏覆盖层)
  • 文件上传 (多文件, ≤50MB)
  • .. 行返回上级
• 插件接口: Picker API (/api/files/picker)
  • 插件通过 window.open + postMessage 唤出选择器
  • 权限: filemanager.picker / filemanager.access / filemanager.write

10.3 WebSocket 实时推送

• /api/system/ws — 每 2s 推送系统 + 框架数据 (替代 HTTP 轮询)
• /api/logs/ws — 日志广播，前端批量渲染 + 500 行上限防卡死
• 仪表盘: DualLineChart 双线图 (下载实线/上传虚线)，Y 轴零点偏移

10.4 MD3 主题系统

• CSS 变量完整 MD3 color tokens (Dark + Light 双主题)
• data-theme 属性切换，localStorage 持久化
• 按钮组合模式: btn + btn-tonal/btn-outlined/btn-filled + btn-sm
• SVG 全局 fill: currentColor 自适应主题色
• 动画: 波纹/卡片悬浮/页面淡入/状态脉冲/骨架屏