# PROJECT M - Matrix Bot

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![Matrix](https://img.shields.io/badge/Protocol-Matrix-green.svg)](https://matrix.org/)
[![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](https://docs.docker.com/compose/)

> Matrix Bot for OpenClaw integration - Auto-join rooms and sync access tokens.

## 功能特點

- 🔐 **自動登錄**：使用配置的帳號密碼登錄 Matrix Server
- 🔄 **Token 同步**：自動更新 `~/.openclaw/openclaw.json` 中的 access token
- 📬 **邀請響應**：自動接受房間邀請並加入
- 👋 **問候消息**：加入房間後自動發送問候信息
- 🐳 **Docker 部署**：支持 Docker Compose 一鍵啟動

## 快速開始

### 1. 配置環境變量

```bash
# 複製環境變量模板
cp .env.example .env

# 編輯配置
nano .env
```

必要配置項：
```env
MATRIX_SERVER=https://your-matrix-server.com
MATRIX_USER_ID=@your-bot:your-matrix-server.com
MATRIX_PASSWORD=your-secure-password
```

### 2. 使用 Docker Compose 啟動

```bash
# 構建並啟動
docker compose up -d

# 查看日誌
docker compose logs -f

# 停止
docker compose down
```

### 3. 本地開發運行

```bash
# 創建虛擬環境
python -m venv .venv
source .venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

# 運行
python -m src.main
```

## 項目結構

```
openclaw-matrix-uplife-bot/
├── src/
│   ├── __init__.py
│   ├── main.py              # 主入口
│   ├── config.py            # 配置管理
│   └── services/
│       ├── __init__.py
│       ├── matrix_service.py  # Matrix 服務
│       └── token_manager.py   # Token 管理器
├── tests/                    # 測試
├── store/                    # E2EE 密鑰存儲
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md
```

## 安全協議

### Token 更新安全

1. **強制備份**：更新前必須創建帶時間戳的備份
2. **驗證機制**：確認備份文件存在後才進行更新
3. **錯誤回滾**：更新失敗時可從備份恢復

### 環境變量

- 敏感信息（密碼）僅通過環境變量傳入
- `.env` 文件已加入 `.gitignore`
- 禁止在代碼中硬編碼密碼

## 測試

```bash
# 運行所有測試
pytest tests/ -v

# 運行特定測試
pytest tests/test_token_manager.py -v
```

## License

MIT License

---

**PROJECT M** - OpenClaw Matrix Integration Bot