# sms-viewer

**Repository Path**: Cacher/sms-viewer

## Basic Information

- **Project Name**: sms-viewer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SMS Viewer - 手机短信桌面看板

接收手机 [SmsForwarder](https://github.com/pppscn/SmsForwarder) 转发的短信，在电脑桌面实时展示的轻量工具。
单文件 Python 应用，无数据库依赖，消息本地持久化，支持验证码自动识别 + 一键复制。

## 功能特性

- **实时接收** — FastAPI 后台线程接收 SmsForwarder Webhook 转发，GUI 实时刷新，新消息响铃提醒
- **格式兼容** — 同时兼容 JSON 和表单（`x-www-form-urlencoded`）两种 Webhook 格式，字段名自动归一化（`phone/sender/from`、`content/msg/text/body` 都认），时间戳秒/毫秒自动换算
- **验证码识别** — 自动提取短信中的验证码（4-8 位数字），覆盖「验证码/校验码/动态码/动态密码/动态口令/一次性密码/code」等关键词，支持「验证码 123456」和「123456 是您的动态口令」两种语序
- **自动复制** — 新短信到达时，验证码自动写入剪贴板，并弹托盘通知，无需任何操作
- **系统托盘** — 关闭窗口即最小化到托盘，后台继续接收；双击托盘图标恢复窗口
- **消息管理** — 搜索（含验证码数字）、复制、删除、清空、导出 TXT、双击查看全文
- **持久化** — 消息保存到同目录 `messages.json`，重启不丢；重复消息自动去重
- **单文件打包** — PyInstaller 打包为单 exe，双击即用

## 快速开始

### 从源码运行

```bash
# Python 3.10+（需带 tkinter）
pip install -r requirements.txt

python main.py              # 启动 GUI + HTTP 服务（默认 0.0.0.0:9801）
python main.py --port 9000  # 自定义端口
python main.py --no-gui     # 纯服务模式，无界面（适合挂机）
```

### 直接使用打包版

用 PyInstaller 打包成单文件 exe（见下文），双击运行即可。

### 手机端配置（SmsForwarder）

1. 手机安装 [SmsForwarder](https://github.com/pppscn/SmsForwarder)
2. 转发通道 → 新增 Webhook：
   - **地址**：`http://<电脑IP>:9801/sms`（IP 显示在窗口底部状态栏）
   - **格式**：JSON 或表单均可
3. 手机与电脑需在同一局域网
4. Windows 防火墙首次会弹窗，选择「允许」

> 配合微信通知等通道时，SmsForwarder 的`发送地址`备用写法：`POST http://<电脑IP>:9801/` 也接受。

## HTTP 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/sms` | 接收短信（JSON / 表单） |
| GET | `/messages` | 查看已收消息（JSON） |
| DELETE | `/messages` | 清空消息 |
| GET | `/health` | 健康检查 |

POST `/sms` 示例：

```json
{
  "phone": "10086",
  "content": "【某平台】验证码 123456，5分钟内有效。",
  "timestamp": 1755522300000,
  "type": "sms",
  "card": 0
}
```

## 打包为 exe

```bash
pip install pyinstaller

pyinstaller --onefile --noconsole --name SMSViewer --icon app.ico ^
  --collect-all uvicorn --collect-all pystray --hidden-import=PIL ^
  --noconfirm main.py
```

产物：`dist/SMSViewer.exe`（数据文件 `messages.json` 自动保存在 exe 同目录）

> 已知坑：`--noconsole` 模式下 `sys.stdout` 为 `None`，uvicorn 日志会崩，本项目已在入口做兜底重定向，直接用即可。

## 项目结构

```
sms-viewer/
├── main.py           # 全部代码（FastAPI + tkinter + 托盘）
├── requirements.txt  # 依赖
├── app.ico           # 应用图标
└── README.md
```

## 依赖

- Python 3.10+（标准库自带 tkinter）
- fastapi / uvicorn / python-multipart — HTTP 服务
- pystray / Pillow — 系统托盘

## License

[MIT](LICENSE)

## 致谢

- [SmsForwarder](https://github.com/pppscn/SmsForwarder) — 安卓短信转发神器
- [FastAPI](https://github.com/fastapi/fastapi) / [uvicorn](https://github.com/encode/uvicorn) / [pystray](https://github.com/moses-palmer/pystray)