entari-plugin-webui 1.0.0__tar.gz

entari_plugin_webui-1.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.1
+Name: entari-plugin-webui
+Version: 1.0.0
+Summary: WebUI Plugin for Entari
+Author-Email: RF-Tar-Railt <rf_tar_railt@qq.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: arclet-entari[dotenv,yaml]>=0.18.0
+Requires-Dist: entari-plugin-server>=0.7.1
+Requires-Dist: entari-plugin-database>=0.3.2
+Requires-Dist: fastapi>=0.135.1
+Requires-Dist: ansi2html>=1.9.2
+Description-Content-Type: text/markdown
+
+# entari-plugin-webui
+
+基于 Vite + Vue 3 + Element Plus 的 [Entari](https://github.com/ArcletProject/arclet-entari) 可视化管理面板。
+
+## 功能特性
+
+- **仪表盘** — 消息统计、运行状态一览（ECharts）
+- **配置管理** — 可视化编辑所有插件配置，支持 YAML 源码与表单双模式
+- **插件管理** — 查看/启用/停用/重载插件
+- **插件市场** — 浏览、安装、卸载社区插件
+- **实时日志** — WebSocket 流式日志查看，支持 ANSI 转义渲染
+- **在线聊天** — 基于 Satori 协议的浏览器内聊天界面
+- **扩展机制** — 其他插件可通过 `webui_extend` 注册菜单、页面、路由、国际化、权限
+- **主题切换** — 明暗主题一键切换
+- **会话管理** — 基于 Cookie 的登录会话，自动过期
+- **登录限流** — 防暴力破解
+
+## 安装
+
+### pip
+
+```bash
+pip install entari-plugin-webui
+```
+
+### pdm
+
+```bash
+pdm add entari-plugin-webui
+```
+
+## 配置示例
+
+在 `entari.yml` 中启用插件：
+
+```yaml
+plugins:
+  server:
+    port: 8765              # WebUI 服务端口
+    path: "satori"
+    direct_adapter: true
+  database:
+    name: .entari/database.db   # 统计数据用 SQLite
+  webui: {}                     # 启动 WebUI 面板
+```
+
+完整字段说明：
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `password` | `""` | 登录密码（远程部署必填，本地可省略） |
+| `registry_url` | `""` | 插件市场地址 |
+| `package_manager` | `""` | 包管理器（自动探测 pip/pdm/uv/poetry/rye/pipenv） |
+| `session_ttl` | `43200` | 会话过期时间（秒，默认 12 小时） |
+| `log_buffer_lines` | `5000` | 日志缓冲区行数 |
+| `login_rate_limit` | `5/60s` | 登录频率限制 |
+
+## 认证说明
+
+- **本地部署**（`host=127.0.0.1/localhost/::1`）：自动免认证，无需密码即可登录
+- **远程部署**：首次启动时自动生成随机 16 位密码并输出到控制台日志
+
+## 故障恢复
+
+忘记密码时，删除配置中的 `plugins.webui.password` 字段（或置空），重启后即重新生成新密码：
+
+```yaml
+plugins:
+  webui: {}
+  # password 字段可删除或留空
+```
+
+## 扩展开发
+
+其他 Entari 插件可通过 `webui_extend` 注册前端扩展，无需修改本插件源码。
+
+```python
+from entari_plugin_webui.core.extension import webui_extend
+
+ext = webui_extend("my_plugin")
+
+# 注册侧栏菜单
+ext.add_menu("my_plugin.name", "mdi:account", "/extension/my_plugin")
+
+# 注册 iframe 页面
+ext.add_page("my_plugin", "my_plugin.name", "mdi:account",
+             "http://127.0.0.1:3000/", permission="my_plugin.access")
+
+# 注册后端 API 路由
+ext.add_route("/api/my-plugin/hello", ["GET"], my_handler, permission="my_plugin.access")
+
+# 注册国际化文案
+ext.add_i18n("zh-CN", "my_plugin.name", "我的插件")
+ext.add_i18n("en-US", "my_plugin.name", "My Plugin")
+
+# 注册权限项
+ext.add_permission("my_plugin.access", "my_plugin.permission.access")
+```
+
+`WebUIExtension` 方法总览：
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `add_menu` | `label_key, icon, path, order, badge_key, children` | 添加侧栏菜单项 |
+| `add_page` | `key, label_key, icon, component_url, permission` | 添加 iframe 页面 |
+| `add_route` | `path, methods, handler, permission` | 添加后端 HTTP 路由 |
+| `add_websocket_route` | `path, handler, permission` | 添加后端 WebSocket 路由 |
+| `add_i18n` | `locale, key, value` | 添加国际化翻译 |
+| `add_permission` | `key, label_key` | 添加权限定义 |
+
+## 风险须知
+
+> [!WARNING]
+> - 扩展页面以 **iframe 沙箱** 加载，与主面板隔离运行
+> - 扩展来源 **仅限本机已安装的插件**，不支持加载外部站点
+> - 各扩展通过 `postMessage` 与主面板通信，无法直接操作 DOM 或获取全局状态
+> - 安装插件市场中的第三方插件前，请自行评估其安全性

entari_plugin_webui-1.0.0/README.md

@@ -0,0 +1,117 @@
+# entari-plugin-webui
+
+基于 Vite + Vue 3 + Element Plus 的 [Entari](https://github.com/ArcletProject/arclet-entari) 可视化管理面板。
+
+## 功能特性
+
+- **仪表盘** — 消息统计、运行状态一览（ECharts）
+- **配置管理** — 可视化编辑所有插件配置，支持 YAML 源码与表单双模式
+- **插件管理** — 查看/启用/停用/重载插件
+- **插件市场** — 浏览、安装、卸载社区插件
+- **实时日志** — WebSocket 流式日志查看，支持 ANSI 转义渲染
+- **在线聊天** — 基于 Satori 协议的浏览器内聊天界面
+- **扩展机制** — 其他插件可通过 `webui_extend` 注册菜单、页面、路由、国际化、权限
+- **主题切换** — 明暗主题一键切换
+- **会话管理** — 基于 Cookie 的登录会话，自动过期
+- **登录限流** — 防暴力破解
+
+## 安装
+
+### pip
+
+```bash
+pip install entari-plugin-webui
+```
+
+### pdm
+
+```bash
+pdm add entari-plugin-webui
+```
+
+## 配置示例
+
+在 `entari.yml` 中启用插件：
+
+```yaml
+plugins:
+  server:
+    port: 8765              # WebUI 服务端口
+    path: "satori"
+    direct_adapter: true
+  database:
+    name: .entari/database.db   # 统计数据用 SQLite
+  webui: {}                     # 启动 WebUI 面板
+```
+
+完整字段说明：
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `password` | `""` | 登录密码（远程部署必填，本地可省略） |
+| `registry_url` | `""` | 插件市场地址 |
+| `package_manager` | `""` | 包管理器（自动探测 pip/pdm/uv/poetry/rye/pipenv） |
+| `session_ttl` | `43200` | 会话过期时间（秒，默认 12 小时） |
+| `log_buffer_lines` | `5000` | 日志缓冲区行数 |
+| `login_rate_limit` | `5/60s` | 登录频率限制 |
+
+## 认证说明
+
+- **本地部署**（`host=127.0.0.1/localhost/::1`）：自动免认证，无需密码即可登录
+- **远程部署**：首次启动时自动生成随机 16 位密码并输出到控制台日志
+
+## 故障恢复
+
+忘记密码时，删除配置中的 `plugins.webui.password` 字段（或置空），重启后即重新生成新密码：
+
+```yaml
+plugins:
+  webui: {}
+  # password 字段可删除或留空
+```
+
+## 扩展开发
+
+其他 Entari 插件可通过 `webui_extend` 注册前端扩展，无需修改本插件源码。
+
+```python
+from entari_plugin_webui.core.extension import webui_extend
+
+ext = webui_extend("my_plugin")
+
+# 注册侧栏菜单
+ext.add_menu("my_plugin.name", "mdi:account", "/extension/my_plugin")
+
+# 注册 iframe 页面
+ext.add_page("my_plugin", "my_plugin.name", "mdi:account",
+             "http://127.0.0.1:3000/", permission="my_plugin.access")
+
+# 注册后端 API 路由
+ext.add_route("/api/my-plugin/hello", ["GET"], my_handler, permission="my_plugin.access")
+
+# 注册国际化文案
+ext.add_i18n("zh-CN", "my_plugin.name", "我的插件")
+ext.add_i18n("en-US", "my_plugin.name", "My Plugin")
+
+# 注册权限项
+ext.add_permission("my_plugin.access", "my_plugin.permission.access")
+```
+
+`WebUIExtension` 方法总览：
+
+| 方法 | 参数 | 说明 |
+|------|------|------|
+| `add_menu` | `label_key, icon, path, order, badge_key, children` | 添加侧栏菜单项 |
+| `add_page` | `key, label_key, icon, component_url, permission` | 添加 iframe 页面 |
+| `add_route` | `path, methods, handler, permission` | 添加后端 HTTP 路由 |
+| `add_websocket_route` | `path, handler, permission` | 添加后端 WebSocket 路由 |
+| `add_i18n` | `locale, key, value` | 添加国际化翻译 |
+| `add_permission` | `key, label_key` | 添加权限定义 |
+
+## 风险须知
+
+> [!WARNING]
+> - 扩展页面以 **iframe 沙箱** 加载，与主面板隔离运行
+> - 扩展来源 **仅限本机已安装的插件**，不支持加载外部站点
+> - 各扩展通过 `postMessage` 与主面板通信，无法直接操作 DOM 或获取全局状态
+> - 安装插件市场中的第三方插件前，请自行评估其安全性

entari_plugin_webui-1.0.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "entari-plugin-webui"
+version = "1.0.0"
+description = "WebUI Plugin for Entari"
+authors = [
+    { name = "RF-Tar-Railt", email = "rf_tar_railt@qq.com" },
+]
+dependencies = [
+    "arclet-entari[dotenv,yaml]>=0.18.0",
+    "entari-plugin-server>=0.7.1",
+    "entari-plugin-database>=0.3.2",
+    "fastapi>=0.135.1",
+    "ansi2html>=1.9.2",
+]
+requires-python = ">=3.10"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[dependency-groups]
+dev = [
+    "arclet-entari[reload]>=0.18.0",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.15",
+    "pyright>=1.1",
+    "anyio>=4",
+    "httpx>=0.28.1",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.build]
+includes = [
+    "src/entari_plugin_webui",
+]
+
+[tool.pdm.scripts]
+build-frontend = "npm --prefix frontend run build"
+dev = "cd frontend && npm run dev"
+format = "ruff format src/ tests/"
+lint = "ruff check src/ tests/ --fix"
+typecheck = "pyright src/entari_plugin_webui"
+test = "pytest -v -s -W ignore"
+
+[tool.pdm.scripts.build-all]
+composite = [
+    "build-frontend",
+    "pdm build",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+include = [
+    "src/**.py",
+    "tests/**.py",
+]
+respect-gitignore = true
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "W",
+    "C",
+    "T",
+    "PYI",
+    "PT",
+    "Q",
+]
+ignore = [
+    "C901",
+    "T201",
+    "E731",
+    "E402",
+    "PYI055",
+    "B008",
+]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = false
+extra-standard-library = [
+    "typing_extensions",
+]
+
+[tool.pyright]
+pythonVersion = "3.10"
+pythonPlatform = "All"
+typeCheckingMode = "basic"
+venvPath = "."
+venv = ".venv"
+reportMissingImports = true

entari_plugin_webui-1.0.0/src/entari_plugin_webui/__init__.py

@@ -0,0 +1,131 @@
+"""Entari Plugin: WebUI 服务（重设计版）"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from arclet.entari import plugin
+from arclet.entari.event.lifespan import Startup
+from arclet.entari.event.send import SendResponse
+from arclet.entari.plugin import PluginRole, plugin_config
+from entari_plugin_server import add_route, add_websocket_route, replace_asgi, server
+from fastapi import Request
+from fastapi.staticfiles import StaticFiles
+from starlette.responses import FileResponse, Response
+
+from .config import Config
+from .core.extension import MenuItem as MenuItem
+from .core.extension import WebUIExtension as WebUIExtension
+from .core.extension import get_all_extension_routes
+from .core.extension import webui_extend as webui_extend
+from .core.security import (
+    LoginThrottle,
+    generate_random_password,
+    hash_password,
+    is_local_deployment,
+    parse_rate_limit,
+    set_local_mode,
+)
+from .core.session import SessionStore
+from .utils import logger
+
+__version__ = "1.0.0"
+_STATIC_DIR = Path(__file__).parent / "static"
+_FRONTEND_DIR = _STATIC_DIR / "frontend"
+
+webui_config = plugin_config(Config, bind=True)
+
+from .adapter import WebUIAdapter
+from .api import create_app as _create_app  # noqa: E402
+from .api import logs  # noqa: F401
+from .models.stats import MessageStat  # noqa: F401
+from .services.stats_service import increment  # noqa: PLC0415
+
+_session_store: SessionStore = SessionStore(ttl=webui_config.session_ttl)
+_login_throttle = LoginThrottle(*parse_rate_limit(webui_config.login_rate_limit))
+
+if not server.path:
+    logger.warning("未检测到 Server 插件的 path 配置，WebUI 可能无法正常工作")
+    logger.warning("已自动设置 Server 插件的 path 为 /satori")
+    server.path = "/satori"
+
+server.apply(WebUIAdapter())
+
+
+plugin.metadata(
+    "WebUI 服务",
+    PluginRole.UTILITY,
+    [{"name": "RF-Tar-Railt", "email": "rf_tar_railt@qq.com"}],
+    __version__,
+    description="基于 Vite + Vue 3 + Element Plus 的可视化管理面板",
+    urls={"homepage": "https://github.com/ArcletProject/entari-plugin-webui"},
+    config=Config,
+)
+
+
+# ---------- SPA fallback handlers ----------
+async def _root(request: Request) -> Response:
+    if not _FRONTEND_DIR.exists():
+        return Response(
+            content="Frontend not built. Run 'pdm run build-frontend'.",
+            status_code=503,
+        )
+    path = request.url.path.lstrip("/")
+    file = _FRONTEND_DIR / (path or "index.html")
+    if file.exists():
+        return FileResponse(file)
+    return Response(status_code=404)
+
+
+replace_asgi(app := _create_app())
+
+if _FRONTEND_DIR.exists() and (_FRONTEND_DIR / "assets").exists():
+    app.mount("/assets", StaticFiles(directory=_FRONTEND_DIR / "assets", html=True))
+
+add_route("/", methods=["GET"], include_in_schema=False)(_root)
+add_route("/favicon.ico", methods=["GET"], include_in_schema=False)(_root)
+add_route("/favicon.svg", methods=["GET"], include_in_schema=False)(_root)
+
+
+# ---------- SendResponse listener (message counting) ----------
+@plugin.listen(SendResponse)
+async def _on_message_sent(event: SendResponse) -> None:
+    platform = event.account.platform
+    try:
+        await increment(platform)
+    except Exception:  # noqa: BLE001
+        logger.debug("消息计数失败")
+
+
+# ---------- Startup listener ----------
+@plugin.listen(Startup, priority=100)
+async def _on_startup() -> None:
+    is_local = is_local_deployment(server.host)
+    set_local_mode(is_local)
+    if is_local:
+        logger.info("本地部署模式，无需认证")
+    else:
+        logger.info("远程部署模式，需要认证")
+        if not webui_config.password:
+            raw = generate_random_password(16)
+            webui_config.password = hash_password(raw)
+            logger.warning("已生成管理员密码：" + raw)
+
+    import arclet.entari.logger as entari_log
+    from loguru import logger as loguru_logger
+
+    from .core.log_stream import LogWriter, get_log_buffer
+
+    log_buffer = get_log_buffer()
+    loguru_logger.add(
+        LogWriter(log_buffer), level=0, diagnose=True, backtrace=True, colorize=True, filter=entari_log.default_filter
+    )  # type: ignore[call-overload]
+
+    routes, ws_routes = get_all_extension_routes()
+    for r in routes:
+        add_route(r.path, methods=r.methods)(r.handler)
+    for w in ws_routes:
+        add_websocket_route(w.path)(w.handler)
+
+    host = server.host or "127.0.0.1"
+    logger.info(f"管理面板已启动: http://{host}:{server.port}/")