# NebulaShell AI 开发文档

> **架构决策**：`nebula cli` 采用前后端分离设计，TUI 前端直连后端 JSON API，
> 不使用 HTML→ANSI 转换引擎。详见下文 [TUI 架构决策](#tui-架构决策)。

## 项目介绍

NebulaShell 是一个企业级插件化运行时框架 (v1.2.0)，核心理念是「一切皆为插件」。它提供了一个最小化的核心系统，仅负责加载 `plugin-loader` 插件，其余 26+ 个官方插件均由该加载器管理。

### 核心特性

- **插件化架构**：所有功能均通过插件实现，支持热插拔
- **隐藏成就系统**：通过 `!!` 前缀访问的游戏化彩蛋（78+ 个验证规则）
- **智能依赖管理**：支持 6 大包管理器自动安装依赖
- **安全特性**：进程级隔离、PL 注入机制、签名验证、动态防火墙
- **双模界面**：同时支持 WebUI (浏览器) 和 TUI (终端) 双启动

### 技术栈

- Python 3.10+
- Click (命令行框架)
- PyYAML (配置解析)
- websockets (实时通信)
- Rich (TUI 渲染引擎)
- 纯静态 WebUI (HTML/CSS/JS)

---

## TUI 架构决策

### 废弃方案：HTML→ANSI 动态转换层（v1.3）

**已废弃。** 早期方案通过 `oss/tui/converter.py`（1430 行）在运行时将 WebUI 的 HTML 页面解析为终端元素，存在以下问题：

| 问题 | 说明 |
|------|------|
| **布局失真** | CSS Flex/Grid 布局模型无法映射到终端字符网格 |
| **交互断层** | JavaScript 事件系统只能在终端模拟，与真实浏览器行为不一致 |
| **维护成本高** | 1430 行转换引擎 + 每个 WebUI 页面需维护 TUI 兼容标记 |
| **渲染性能差** | 每次导航需对整个 HTML 进行 DOM 解析和布局计算 |
| **调试困难** | 终端渲染错误难以定位是 HTML 问题还是转换器 Bug |

### 当前方案：前后端分离，原生 ANSI 渲染

```
nebula serve  ─── JSON API ───→  nebula cli (TUI 前端)
   (后端)                          (原生 ANSI 终端渲染)
```

**后端职责**（`nebula serve`）：
- 提供 RESTful JSON API（如 `/api/dashboard/stats`）
- WebSocket 实时推送
- 不感知 TUI 存在

**前端职责**（`nebula cli`）：
- 通过 HTTP/WebSocket 消费后端 JSON 数据
- 使用 ANSI 转义码直接在终端绘制界面
- 不依赖任何 HTML/CSS 解析

#### 技术要点

```
终端控制:
  raw mode  ───  tty.setraw()，单字节读取
  ONLCR     ───  重新开启 \n→\r\n 映射，避免阶梯乱码
  SGR 鼠标  ───  \x1b[?1000h\x1b[?1006h，解析 \x1b[<button;x;y;M
  SIGWINCH  ───  捕获终端 resize，全屏重绘

ANSI 绘制:
  24-bit 真彩色  ───  \x1b[38;2;R;G;Bm / \x1b[48;2;R;G;Bm
  字符图形        ───  █ ░ ▓ 等 Unicode 块字符作进度条
  光标定位        ───  \x1b[{row};{col}H

页面导航:
  热点区域映射    ───  预计算每行点击区域 (y → page_id)
  键盘备选       ───  数字键 1-5 作为鼠标候补
```

### 开放代码（opencode）TUI 架构分析

[opencode](https://opencode.ai) 是目前最成熟的终端 AI 编程助手，其 TUI 架构可参考：

| 特性 | opencode 实现 |
|------|-------------|
| **渲染引擎** | 原生终端渲染，无 HTML 中间层。直接操作终端缓冲区 |
| **组件系统** | 类似 React 的组件化方案，但所有组件直接输出 ANSI 字符串 |
| **输入处理** | raw mode + SGR 鼠标 + 组合键解析，支持 `Tab` 切换模式 |
| **布局** | 弹性布局引擎，组件根据终端宽度自动折行/折叠 |
| **状态管理** | 全局状态树，每次状态变更触发受控重绘（非全屏重绘）|
| **会话管理** | 多会话并行，每个会话独立维护上下文和渲染状态 |
| **主题系统** | 完整的配色方案，支持暗色/亮色主题切换 |

**关键差异**：opencode 不使用任何 Web 技术栈做 TUI，其所有界面元素（输入框、按钮、列表、状态栏、侧边栏）都是直接通过 ANSI 转义码在终端绘制的。每个组件是一个纯 Python/TypeScript 类，`render()` 方法返回 ANSI 字符串。

**对我们的启发**：
1. 放弃 HTML 转换层是正确的方向
2. 直接 ANSI 渲染的架构更可控、性能更好
3. 需要设计自己的组件化终端渲染库（参考 opencode 的组件系统）
4. `nebula cli` 命令已预留，后续在此框架上构建原生 TUI

---

## 插件开发指南

### 插件基础结构

所有插件必须继承自 `oss.plugin.types.Plugin` 基类，并实现三个核心方法：

```python
from oss.plugin.types import Plugin
from oss.plugin.decorators import plugin

@plugin(name="my-plugin", version="1.0.0", description="我的插件")
class MyPlugin(Plugin):
    """插件类"""
    
    def init(self) -> None:
        """初始化阶段：加载配置、注册路由等"""
        self.logger.info("插件初始化")
        
    def start(self) -> None:
        """启动阶段：启动服务、连接数据库等"""
        self.logger.info("插件启动")
        
    def stop(self) -> None:
        """停止阶段：清理资源、断开连接等"""
        self.logger.info("插件停止")
```

### 插件目录结构

```
plugins/
└── my-plugin/
    ├── __init__.py          # 插件入口
    ├── plugin.py            # 主插件类
    ├── config.yaml          # 配置文件
    ├── routes/              # HTTP 路由
    │   ├── __init__.py
    │   └── api.py
    ├── tui/                 # TUI 专用页面
    │   ├── index.html
    │   ├── styles.css
    │   └── interaction.js
    ├── webui/               # WebUI 页面
    │   ├── index.html
    │   ├── styles.css
    │   └── app.js
    └── utils/               # 工具函数
        └── helpers.py
```

### 插件装饰器参数

```python
@plugin(
    name="unique-name",           # 唯一插件名 (必填)
    version="1.0.0",              # 版本号 (必填)
    description="插件描述",         # 描述 (必填)
    author="作者名",               # 作者 (可选)
    dependencies=["plugin-a"],    # 依赖插件列表 (可选)
    optional_dependencies=["plugin-b"],  # 可选依赖 (可选)
    min_core_version="1.0.0",     # 最低核心版本要求 (可选)
    tags=["category", "type"],    # 标签分类 (可选)
    enabled=True                  # 默认是否启用 (可选)
)
```

### 注册 HTTP 路由

```python
from flask import Blueprint, jsonify

# 创建路由蓝图
bp = Blueprint('my_plugin', __name__, url_prefix='/api/my-plugin')

@bp.route('/health', methods=['GET'])
def health_check():
    """健康检查接口"""
    return jsonify({"status": "ok", "plugin": "my-plugin"})

@bp.route('/data', methods=['POST'])
def receive_data():
    """接收数据接口"""
    data = request.json
    # 处理逻辑
    return jsonify({"success": True})

# 在插件的 init 方法中注册路由
def init(self) -> None:
    self.app.register_blueprint(bp)
```

### 创建 TUI/WebUI 页面

#### WebUI 页面 (webui/index.html)

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>我的插件</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <div class="container">
        <h1>欢迎使用我的插件</h1>
        <button id="action-btn">执行操作</button>
        <div id="result"></div>
    </div>
    <script src="app.js"></script>
</body>
</html>
```

#### TUI 页面 (tui/index.html)

```html
<!-- TUI 专用页面，包含 data-tui 标记 -->
<div data-tui-type="panel" data-tui-title="我的插件" data-tui-border="rounded">
    <h1 data-tui-type="heading" data-tui-level="1" data-tui-align="center">
        欢迎使用我的插件
    </h1>
    
    <button 
        data-tui-type="button" 
        data-tui-label="执行操作"
        data-tui-id="action-btn"
        data-tui-style="primary">
    </button>
    
    <div 
        data-tui-type="text" 
        data-tui-id="result"
        data-tui-color="gray">
        等待操作...
    </div>
</div>
```

#### TUI 专用样式 (tui/styles.css)

```css
/* 仅包含终端支持的样式 */
.container {
    padding: 2;
    margin: 1;
}

h1 {
    font-size: large;
    font-weight: bold;
    text-align: center;
    color: #00ff00;
}

button {
    background-color: #0066cc;
    color: #ffffff;
    border: 2 solid #004499;
    border-style: rounded;
    padding: 1 2;
}

#result {
    color: #888888;
    font-style: italic;
}
```

#### TUI 交互逻辑 (tui/interaction.js)

```javascript
// 仅支持基础交互
document.getElementById('action-btn').addEventListener('click', function() {
    // 发送请求到后端
    fetch('/api/my-plugin/action', {method: 'POST'})
        .then(res => res.json())
        .then(data => {
            document.getElementById('result').textContent = data.message;
        });
});

// 键盘快捷键
document.addEventListener('keydown', function(e) {
    if (e.key === 'r') {
        // 刷新操作
        location.reload();
    }
});
```

### 插件配置

在 `config.yaml` 中定义插件配置：

```yaml
# plugins/my-plugin/config.yaml
plugin_name: my-plugin
enabled: true
settings:
  api_key: ""
  timeout: 30
  max_retries: 3
  debug: false
  
routes:
  prefix: /api/my-plugin
  auth_required: true

tui:
  enabled: true
  theme: default
  refresh_rate: 1000  # 毫秒

webui:
  enabled: true
  port: 8080
```

在插件中读取配置：

```python
def init(self) -> None:
    config = self.get_config()
    self.api_key = config.get('settings', {}).get('api_key', '')
    self.timeout = config.get('settings', {}).get('timeout', 30)
    self.logger.info(f"插件配置加载完成: timeout={self.timeout}")
```

### 插件间通信

```python
# 调用其他插件的方法
other_plugin = self.get_plugin('other-plugin')
if other_plugin:
    result = other_plugin.some_method(arg1, arg2)

# 发布事件
self.emit_event('my-event', {'data': 'value'})

# 订阅事件
@self.on_event('other-event')
def handle_event(event_data):
    self.logger.info(f"收到事件: {event_data}")
```

### 插件生命周期

```
1. 发现阶段：扫描 plugins 目录，识别插件
2. 排序阶段：根据依赖关系确定加载顺序
3. 初始化阶段：调用每个插件的 init() 方法
4. 启动阶段：调用每个插件的 start() 方法
5. 运行阶段：插件正常提供服务
6. 停止阶段：调用每个插件的 stop() 方法 (按依赖逆序)
```

### 调试插件

```bash
# 启用调试模式
export NEBULA_DEBUG=1
python main.py

# 查看特定插件日志
tail -f logs/nebula.log | grep my-plugin

# 热重载插件 (开发模式)
python main.py --dev --reload-plugins
```

### 打包插件

```bash
# 创建插件包
cd plugins/my-plugin
zip -r my-plugin-1.0.0.zip . 

# 安装插件
nebula plugin install my-plugin-1.0.0.zip

# 发布到插件市场
nebula plugin publish my-plugin-1.0.0.zip
```

---

## 最佳实践

### 1. 代码规范

- 遵循 PEP 8 编码规范
- 使用类型注解
- 编写单元测试 (覆盖率 > 80%)
- 添加详细的文档字符串

### 2. 错误处理

```python
try:
    result = risky_operation()
except SpecificError as e:
    self.logger.error(f"操作失败: {e}")
    raise PluginError("操作执行失败", original_error=e)
finally:
    cleanup_resources()
```

### 3. 日志记录

```python
# 不同级别的日志
self.logger.debug("调试信息")
self.logger.info("一般信息")
self.logger.warning("警告信息")
self.logger.error("错误信息")
self.logger.critical("严重错误")

# 带上下文的日志
self.logger.info(
    "用户操作",
    extra={"user_id": user_id, "action": "create"}
)
```

### 4. 性能优化

- 使用异步操作处理 I/O 密集型任务
- 实现缓存机制减少重复计算
- 批量处理数据库操作
- 监控资源使用情况

### 5. 安全考虑

- 验证所有用户输入
- 使用参数化查询防止 SQL 注入
- 实施速率限制
- 定期更新依赖
- 敏感信息使用环境变量

---

## 常见问题

### Q: 如何禁用 TUI 只使用 WebUI？

```bash
# 设置环境变量
export NEBULA_TUI_ENABLED=false
python main.py

# 或在配置文件中
# config.yaml
tui:
  enabled: false
```

### Q: TUI 显示乱码怎么办？

确保终端支持 UTF-8 和真彩色：

```bash
# 检查终端支持
echo $TERM  # 应该类似 xterm-256color

# 启用真彩色
export COLORTERM=truecolor
```

### Q: 如何自定义 TUI 主题？

在插件的 `tui/styles.css` 中定义主题变量：

```css
:root {
    --primary-color: #0066cc;
    --secondary-color: #6c757d;
    --success-color: #28a745;
    --danger-color: #dc3545;
    --bg-color: #1a1a2e;
    --text-color: #eeeeee;
}
```

### Q: 插件加载失败如何排查？

```bash
# 查看详细日志
python main.py --verbose

# 检查插件依赖
nebula plugin check my-plugin

# 验证插件结构
nebula plugin validate my-plugin/
```

---

## 贡献指南

1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发环境设置

```bash
# 克隆仓库
git clone https://github.com/nebulashell/nebulashell.git
cd nebulashell

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/

# 代码格式化
black .
isort .
flake8 .
```

---

## 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

## 联系方式

- 官网：https://nebulashell.io
- 文档：https://docs.nebulashell.io
- 社区：https://community.nebulashell.io
- GitHub: https://github.com/nebulashell/nebulashell