deepsmth 1.9.7.dev3
DeepSMTH - Modern SSH BBS client for SMTH with AI-powered features (GUI version)
Requires Python: >=3.13

# DeepSMTH

DeepSMTH 是一款现代化的 Python 图形界面 SSH BBS 客户端，专为访问 SMTH（水木社区）设计。它采用原生桌面应用架构，支持 AI 辅助发帖回帖功能。

## 主要功能

### 🖥️ 图形界面
- **原生桌面应用**：基于 Qt/PySide6 开发，流畅的本地体验
- **动态窗口调整**：实时适应窗口大小变化，自动调整终端尺寸
- **完整显示支持**：完整的 ANSI 颜色和转义序列支持
- **自定义外观**：支持自定义字体、字号和行间距
- **颜色映射**：重新映射 BBS 颜色以优化显示效果（如蓝色标题栏改为青色）
- **优化的渲染**：高性能终端画布，支持光标闪烁、文本选择等

### 🔐 连接与认证
- **SSH 公钥认证**：安全便捷的登录方式，支持 SSH Agent
- **智能重连**：网络断开后自动重连，可配置重连次数和延迟
- **多编码支持**：支持 UTF-8、GBK、GB2312 等多种字符编码
- **灵活的断线处理**：可配置正常退出和网络错误时的处理策略

### ✍️ 编辑与发布
- **BBCode 格式化**：完整的 BBCode 文本格式支持（加粗、斜体、颜色、字号等）
- **图片导出**：将文本内容导出为图片，便于分享
- **图片查看器**：内置图片浏览功能
- **附件模式**：支持附件上传和管理
- **字体缩放**：快捷键调整编辑器字体大小

### ⚡ 效率工具
- **宏自动化**：自动执行重复性按键操作，支持预定义和自定义宏
- **自定义快捷键**：为任意按键绑定命令、宏或插件操作
- **帖子过滤**：按用户黑名单过滤帖子，支持运行时开关
- **会话录制**：记录 BBS 操作过程，兼容 asciinema 格式
- **屏幕状态检测**：自动识别 BBS 当前页面状态

### 🤖 AI 智能助手
- **多模型支持**：集成 GPT-3.5、GPT-4 等大语言模型
- **智能回帖**：AI 辅助生成回帖内容，支持引用和上下文
- **智能发帖**：AI 辅助生成新帖内容
- **多角色系统**：支持预设角色（如版主角色）和自定义角色
- **对话历史**：记录 AI 生成历史，支持查看和复用
- **签名管理**：运行时配置和管理签名
- **可取消生成**：长时间 AI 生成时可中途取消

### 🌍 IP 地理位置
- **自动识别**：自动检测帖子中的 IP 地址
- **在线/本地查询**：支持在线 API（ip-api、ipinfo）和本地数据库（IPIP、GeoIP2）
- **智能缓存**：缓存查询结果，提高性能
- **格式优化**：将 IP 地址替换为地理位置信息（如：北京）

### 🔌 插件系统
- **可扩展架构**：统一的插件 API，易于开发自定义插件
- **内置插件**：
  - IP 地理位置查询
  - 帖子过滤
  - 会话录制
  - LLM 智能助手
- **插件管理**：图形化插件配置界面，支持启用/禁用和参数配置
- **事件驱动**：基于事件的插件交互机制

### 🎨 用户体验
- **设置对话框**：统一的图形化配置界面
- **中文界面**：完整的中文本地化
- **消息提示**：Toast 通知系统，及时反馈操作结果
- **异步操作**：支持异步 UI 操作，避免界面卡顿
- **Markdown 渲染**：内容预览支持 Markdown 格式

## 系统要求

- **Python** 3.13 或更高版本
- **uv**（推荐）或 pip
- macOS 10.15+、Linux 或类 Unix 系统

**注意**：Windows 原生不支持，请使用 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)。

## 安装步骤

### 方法一：使用 uv（推荐）

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

# 安装依赖
uv sync

# 安装应用
uv pip install -e .

# 启动应用
deepsmth
```

### 方法二：使用 pip

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

# 安装依赖
pip install -e .

# 启动应用
deepsmth
```

### 方法三：从源码运行

```bash
# 使用 uv
uv run python mainw.py

# 或直接使用 python
python mainw.py
```

### macOS 用户：打包为 .app

```bash
# 构建 macOS 应用包
./build_macos.sh

# 应用将生成在 dist/DeepSMTH.app
# 并自动复制到 /Applications/ 目录
```

## 配置说明

配置文件存储在 `~/.config/deepsmth/` 目录下，遵循 XDG 基础目录规范。

**注意**：如果您有现有的 `~/.config/bbs/` 目录，首次运行时会自动迁移到 `~/.config/deepsmth/`。

### 快速配置

```bash
# 创建配置目录
mkdir -p ~/.config/deepsmth

# 复制示例配置文件
cp examples/config.yaml ~/.config/deepsmth/
cp examples/macros.yaml ~/.config/deepsmth/
cp examples/plugins.yaml ~/.config/deepsmth/
```

### 配置 BBS 连接

编辑 `~/.config/deepsmth/config.yaml` 文件：

```yaml
connection:
  hostname: bbs.mysmth.net
  username: your_username      # 修改为您的用户名
  identity_file: ~/.ssh/id_rsa  # 您的 SSH 私钥路径
  encoding: gbk                # SMTH 使用 GBK 编码
```

### 配置文件说明

| 文件名 | 说明 |
|--------|------|
| `config.yaml` | 主配置文件（服务器、连接设置、显示设置） |
| `macros.yaml` | 宏自动化定义 |
| `plugins.yaml` | 插件设置 |
| `llm.yaml` | LLM（AI）集成设置（可选） |
| `keybindings.yaml` | 自定义键盘快捷键（可选） |

## 使用指南

### 启动应用

```bash
# 使用默认配置启动
deepsmth

# 指定服务器启动
deepsmth --server smth

# 覆盖特定设置
deepsmth --server smth --user myusername --encoding gbk
```

### 键盘控制

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+]` | 退出 BBS 会话 |
| `Ctrl+L` | 打开宏菜单 |
| `Ctrl+R` | 创建并运行自定义宏 |
| `Ctrl+S` | 停止当前运行的宏 |
| `Ctrl+F` | 打开插件命令菜单 |
| `Alt+?` | 显示快捷键帮助 |
| 方向键 | 光标移动 |
| 功能键 | F1-F12、Home、End、Page Up/Down |

其他按键会直接发送到 BBS 服务器。

### 使用宏功能

宏可以自动执行重复的按键操作，提高使用效率。

#### 方法一：使用预定义宏

1. 按 `Ctrl+L` 打开宏菜单
2. 输入宏编号或名称（如 `delete_confirm`）
3. 输入重复次数（留空表示无限循环）
4. 完成后按 `Ctrl+S` 停止

#### 方法二：创建自定义宏

1. 按 `Ctrl+R` 进入自定义宏模式
2. 输入按键序列（如 `d y enter`）
3. 输入重复次数
4. 输入按键间隔时间（默认 0.5 秒）

查看 `examples/macros.yaml` 了解可用的预定义宏。

### 帖子过滤功能

过滤特定用户的帖子：

1. 在 `~/.config/deepsmth/plugins.yaml` 中启用过滤器插件
2. 按 `Ctrl+F` 打开插件命令菜单
3. 使用以下命令：
   - `filter-add username` - 将用户加入黑名单
   - `filter-remove username` - 从黑名单移除
   - `filter-list` - 显示黑名单用户
   - `filter-toggle` - 开启/关闭过滤功能

### AI 智能助手

使用 AI 辅助生成回帖和发帖内容。

#### 设置

```bash
# 复制 AI 配置文件
cp examples/llm.yaml ~/.config/deepsmth/llm.yaml

# 设置 API Key
export BBS_LLM_API_KEY=sk-your-openai-api-key
```

#### 使用方法

按 `Ctrl+F` 打开插件命令菜单，然后使用：

- `llm-reply` - 为当前帖子生成回复
- `llm-post <标题>` - 生成新帖内容
- `llm-config` - 检查配置状态

### 自定义快捷键

为常用操作创建快捷键：

```bash
# 复制快捷键配置模板
cp examples/keybindings.yaml ~/.config/deepsmth/keybindings.yaml
```

配置示例：

```yaml
keybindings:
  Alt+G:
    type: plugin_command
    command: llm-reply
    description: "生成 AI 回复"

  Alt+F:
    type: plugin_command
    command: filter-list
    description: "查看过滤列表"
```

按 `Alt+?` 查看所有已配置的快捷键。

## SSH 密钥设置

### 生成 SSH 密钥

```bash
ssh-keygen -t rsa -b 4096 -f ~/.ssh/smth_key
```

### 上传公钥到 BBS 服务器

```bash
ssh-copy-id -i ~/.ssh/smth_key.pub user@bbs.mysmth.net
```

### 配置应用使用密钥

在 `~/.config/deepsmth/config.yaml` 中设置：

```yaml
identity_file: ~/.ssh/smth_key
```

## 常见问题

### 应用无法启动

- 确认 Python 版本 >= 3.13：`python --version`
- 检查依赖是否已安装：`uv pip list`
- 查看日志文件：`tail -f ~/.config/deepsmth/logs/bbs_$(date +%Y-%m-%d).log`

### 连接问题

- 确认 SSH 密钥路径和权限（应为 600）
- 确认公钥已在 BBS 服务器注册
- 使用以下命令测试连接：`ssh -i ~/.ssh/your_key user@bbs.mysmth.net`

### 显示问题

- 尝试不同的编码：`--encoding gbk` 或 `--encoding gb2312`
- 确认终端支持 ANSI 转义序列

## 开发者文档

详细的开发文档位于 `docs/` 目录：

- **[配置指南](docs/CONFIGURATION.md)** - 详细的配置选项说明
- **[快捷键配置](docs/KEYBINDINGS.md)** - 自定义键盘快捷键
- **[LLM 集成](docs/LLM_INTEGRATION.md)** - AI 功能集成指南
- **[插件开发](docs/PLUGINS.md)** - 创建自定义插件
- **[帖子过滤](docs/POST_FILTERING.md)** - 过滤插件使用指南
- **[屏幕检测](docs/SCREEN_DETECTION.md)** - 屏幕状态检测系统

## 项目结构

```
bbs/
├── mainw.py              # 图形界面入口
├── main.py               # 命令行入口（旧版）
├── gui/                  # 图形界面实现
├── shared/               # 共享模块（配置、日志、LLM）
├── plugins/              # 插件系统
│   └── builtin/          # 内置插件
├── tests/                # 测试套件
├── examples/             # 配置示例
├── build_macos.sh        # macOS 构建脚本
├── deepsmth-macos.spec   # PyInstaller 配置
└── pyproject.toml        # 项目配置
```

## 贡献指南

我们欢迎各种形式的贡献！

- 报告问题和功能请求
- 提交代码改进
- 完善文档
- 开发插件
- 帮助其他用户

## 许可证

MIT License