# 🐱 SenSu

万能 Python TUI 项目管理器 — 插件化架构，任何项目都能挂载运行。

[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()

---

## ✨ 特性

- 🎨 **Textual TUI** — 三栏界面 + 系统监控面板 + CLI 回退
- 🔌 **插件系统** — 热加载、权限隔离、依赖解析、进程隔离
- 🗄️ **项目注册表** — 插件声明 `project.yaml` 申请端口和资源
- 📊 **SQLite 持久化** — 插件状态、权限、审计日志统一存储
- 🌐 **Web 管理面板** — aiohttp + WebSocket，:4200 实时仪表盘
- 🔐 **安全认证** — PBKDF2-SHA256、环境变量密码、Token 管理
- 🐳 **Docker 部署** — Alpine 镜像 <100MB，systemd 服务文件
- 🧪 **23 个回归测试** — pytest，零失败

## 🚀 快速开始

```bash
# 安装依赖
pip install -r requirements.txt

# 启动 (TUI 模式)
python main.py

# 启动 (headless，适合 SSH/systemd/Docker)
python main.py --headless

# 运行测试
python -m pytest tests/ -v
```

## 🏗️ 架构

```
main.py → SenSuFramework
  ├─ ServiceManager (15 服务)
  ├─ CoreBridge ⇄ PluginBridge ⇄ NetworkBridge
  ├─ PluginService (热加载 + 依赖解析)
  ├─ ProjectService (项目注册表 + 端口分配)
  ├─ SenSuDB (SQLite 5 表)
  ├─ TuiService (Textual + 系统监控)
  ├─ InternetService (HTTP :4200 + WS :4240)
  ├─ WebPanel (管理面板 /SenSu)
  └─ PermissionService (4 级权限)
```

## 📁 目录结构

```
SenSu-Alpha/
├── main.py                 # 框架入口
├── service_manager.py      # 服务注册表
├── sdk/                    # 插件开发工具包
│   ├── plugin_command_decorator.py
│   ├── plugin_status.py
│   └── plugin_error.py
├── services/               # 核心服务 (15 个)
│   ├── sensu_db.py         # SQLite 持久化
│   ├── project_service.py  # 项目注册表
│   ├── process_isolated.py # 进程隔离
│   └── sysmon_widget.py    # 系统监控
├── bridges/                # 消息桥接
├── plugins/                # 插件目录
├── deploy/                 # 部署文件
│   ├── sensu.service       # systemd
│   └── Dockerfile          # Docker
├── tests/                  # 23 个测试
└── docs/                   # 开发文档
```

## 🔌 插件开发

```python
# plugins/my_plugin/__init__.py
from sdk.plugin_command_decorator import plugin_command

class Plugin:
    def __init__(self, plugin_name=None, config=None, bridge=None):
        self.plugin_name = plugin_name
        self.bridge = bridge

    async def initialize(self):
        # 注册网络路由
        await self.network_bridge.register_http_route(
            "/api/my/info", self._handler, methods=["GET"])

    @plugin_command(name="hello", description="打招呼")
    async def cmd_hello(self, *args):
        return f"Hello from {self.plugin_name}!"

    async def shutdown(self):
        pass
```

详细文档见 `docs/SenSu 插件开发详细指南.md`

## 🌐 API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| GET | `/SenSu/` | Web 管理面板 |
| POST | `/SenSu/api/login` | 面板登录 |
| GET | `/SenSu/api/system` | 系统状态 |
| GET | `/SenSu/api/plugins` | 插件列表 |
| POST | `/SenSu/api/command` | 执行命令 |
| GET | `/api/example/info` | 示例插件 |

## 🔧 环境变量

| 变量 | 默认值 | 说明 |
|------|------|------|
| `SENSU_ADMIN_PASSWORD` | `admin123` | 管理员密码 |
| `SENSU_API_PASSWORD` | `api123` | API 密码 |
| `SENSU_PANEL_USER` | `admin` | 面板用户名 |
| `SENSU_PANEL_PASS` | `admin` | 面板密码 |

## 📄 许可证

Apache License 2.0 · Copyright 2026 AskaEth