Files

qwen.ai[bot] 9f7ca46f96 Update TUI to v1.3 with enhanced conversion layer and dual UI architecture

- ai.md: Added comprehensive documentation for TUI v1.3 conversion layer with 64+ supported components, CSS styling, and JavaScript interaction capabilities
- oss/tui/: Created complete TUI module with converter.py implementing HTML/CSS/JS to terminal conversion engine, supporting 40+ component types and advanced styling
- oss/tui/plugin.py: Implemented TUI plugin with dual startup architecture accessing WebUI's /tui interface for HTML conversion and terminal rendering
- store/@{NebulaShell}/webui/tui/: Added TUI package with converter, configuration files, and index.html for terminal interface
- store/@{NebulaShell}/webui/core/server.py: Enhanced WebUI server with TUI interface endpoints (/tui/*) for providing special-marked HTML to conversion layer
- store/@{NebulaShell}/webui/main.py: Updated WebUI plugin to support TUI dual launch with automatic homepage redirection and navigation integration
- .gitignore: Updated ignore patterns for better project cleanliness

The update provides a sophisticated terminal interface that automatically converts WebUI content through a powerful transformation layer, enabling seamless dual-mode operation.

2026-05-02 12:04:27 +08:00

4.6 KiB

Raw Blame History

NebulaShell TUI - 终端用户界面

概述

TUI（Terminal User Interface）插件为 NebulaShell 提供终端界面，与 WebUI 双启动运行。

核心特性

1. 转换层架构

TUI 本身只有一个转换层，它只会访问 WebUI 所开放的 /tui 接口：

/tui/index.html - TUI 入口页面
/tui/page - 获取任意页面的 TUI 版本
/tui/css - 终端兼容的 CSS
/tui/interact - 处理交互事件

2. HTML 标记规范

WebUI 开放的 .html 文件中不含有任何给用户看的内容，但包含 TUI 可解析的特殊标记：

<!-- TUI 页面标记 -->
<html class="tui-page">
<body class="tui-body">

<!-- TUI 容器 -->
<div class="tui-container" data-tui-layout="vertical">

<!-- 键盘快捷键标记 -->
<a href="/" data-tui-key="1" data-tui-action="navigate">[1] 首页</a>

<!-- TUI 配置脚本 -->
<script type="application/x-tui-config">
{
    "keyboard": {
        "1": {"action": "navigate", "target": "/"},
        "q": {"action": "quit"}
    }
}
</script>

<!-- TUI CSS (仅终端支持的样式) -->
<style type="text/x-tui-css">
.tui-header { font-weight: bold; }
</style>

3. 支持的 CSS 属性

TUI 只支持终端能够渲染的样式：

CSS 属性	TUI 转换	说明
`font-weight: bold`	ANSI 加粗	`\x1b[1m`
`font-style: italic`	ANSI 斜体	`\x1b[3m`
`text-decoration: underline`	ANSI 下划线	`\x1b[4m`
`background-color`	ANSI 背景色	仅支持基础 8 色
`color`	ANSI 前景色	仅支持基础 8 色
`text-align`	文本对齐	left/center/right

4. 支持的 JS 交互

TUI 只支持基础的终端交互：

鼠标位置 - 通过 ANSI 鼠标协议获取
点击事件 - 转换为选择操作
按键输入 - 完整的键盘支持

// TUI 配置中的键盘映射
{
    "keyboard": {
        "1": {"action": "navigate", "target": "/"},
        "ArrowUp": {"action": "navigate_up"},
        "Enter": {"action": "select"},
        "q": {"action": "quit"}
    }
}

文件结构

webui/tui/
├── __init__.py          # 包初始化
├── main.py              # TUI 插件主程序
├── converter.py         # HTML 到 TUI 转换层
├── index.html           # TUI 入口页面（含特殊标记）
├── manifest.json        # 插件清单
└── README.md            # 本文档

使用方式

启动 NebulaShell

# 正常启动，WebUI 和 TUI 会同时运行
python main.py serve

# 或通过 CLI
python -m oss.cli serve

TUI 快捷键

按键	功能
`1`	首页
`2`	仪表盘
`3`	日志
`4`	终端
`5`	插件
`6`	设置
`r`	刷新
`h`	帮助
`↑/↓`	上下导航
`Enter`	确认
`q`	退出 TUI

开发指南

创建 TUI 兼容页面

在 WebUI 插件中创建页面时，添加 TUI 标记
使用 data-tui-* 属性定义交互行为
在 <script type="application/x-tui-config"> 中定义键盘映射
在 <style type="text/x-tui-css"> 中定义终端样式

示例

# 在 WebUI 插件中注册 TUI 兼容页面
def register_tui_page(webui):
    webui.register_page(
        path='/mypage',
        content_provider=lambda: '''
        <!DOCTYPE html>
        <html class="tui-page">
        <head><title>我的页面</title></head>
        <body class="tui-body">
            <div class="tui-container">
                <h1 data-tui-style="bold">欢迎</h1>
                <a href="/action" data-tui-key="a" data-tui-action="click">执行操作</a>
            </div>
            <script type="application/x-tui-config">
            {"keyboard": {"a": {"action": "click", "target": "/api/action"}}}
            </script>
        </body>
        </html>
        ''',
        nav_item={'icon': 'ri-star-line', 'text': '我的页面'}
    )

技术细节

转换流程

TUI 插件启动时访问 /tui/index.html
HTMLToTUIConverter 解析 HTML 提取：
- 文本内容
- 按钮和链接
- TUI 配置（键盘映射、样式）
TUIRenderer 将元素渲染为 ANSI 转义序列
TUICanvas 管理终端显示缓冲区
TUIInputHandler 处理键盘/鼠标输入

ANSI 颜色映射

COLOR_MAP = {
    '#000000': '\x1b[30m',  # black
    '#ff0000': '\x1b[31m',  # red
    '#00ff00': '\x1b[32m',  # green
    '#ffff00': '\x1b[33m',  # yellow
    '#0000ff': '\x1b[34m',  # blue
    '#ff00ff': '\x1b[35m',  # magenta
    '#00ffff': '\x1b[36m',  # cyan
    '#ffffff': '\x1b[37m',  # white
}

许可证

MIT License - NebulaShell Project

4.6 KiB Raw Blame History Unescape Escape