<div align="center">
  <img src="assets/logo.svg" width="200" height="200" alt="Beam Logo">
  
  # Beam
  
  **跨设备剪贴板.**
  
  [![PyPI version](https://badge.fury.io/py/beam-clipboard.svg)](https://pypi.org/project/beam-clipboard/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  
  [English](README.md)
  
  通过云端 API 实现快速跨设备文本共享的命令行工具。
  
  **只需两个命令: `bm c` (复制) 和 `bm p` (粘贴)**
</div>

## 快速开始

```bash
# 安装 (基础版)
pip install beam-clipboard

# 安装带剪贴板支持 (推荐)
pip install beam-clipboard[clipboard]

# 首次使用: 设置个人 key
bm c "hello world"
# 提示: No key configured. Please enter your personal key:
# 输入你的 key (建议 20+ 字符)

# 日常使用
bm c "复制这个"    # 复制到云端
bm p              # 从云端粘贴
```

## 特性

- ✨ **极简** - 只需 `bm c` 和 `bm p` 两个命令
- 🚀 **零配置** - 首次使用自动设置
- 🔄 **跨设备** - Mac, Linux, Windows, iPhone 浏览器
- 📦 **纯 Python** - 无额外依赖
- 🔐 **加密** - 上传前加密内容
- 🗜️ **压缩** - 减少传输大小 (代码可压缩约 60%)
- 🔓 **开源** - MIT License

## 使用方法

### 复制和粘贴

```bash
# 直接复制文本
bm c "hello world"

# 从 stdin 复制 (所有平台)
echo "hello" | bm c
cat file.txt | bm c

# 从系统剪贴板复制 (需要安装 pyperclip)
bm c

# 平台特定的剪贴板命令 (不安装 pyperclip 的替代方案)
pbpaste | bm c           # macOS
xclip -o | bm c          # Linux X11
wl-paste | bm c          # Linux Wayland
Get-Clipboard | bm c     # Windows PowerShell

# 明文模式 (用于移动设备浏览器查看)
bm c --plain "hello world"

# 粘贴文本
bm p
```

### 修改 Key 和密码

```bash
# 交互式修改 (server + key + 密码)
bm e

# 直接设置新 key
bm e mynewkey

# 设置自定义服务器 URL
bm e -s https://your-domain.com

# 设置加密密码
bm e -p mypassword
```

### 其他使用方式

```bash
python -m beam c "hello world"
python -m beam p
```

## 使用场景

### 💻 电脑间同步

```bash
# 电脑 A
bm c "some data"

# 电脑 B
bm p
```

### 📱 电脑与移动设备互传

**电脑到手机 (浏览器查看)**

```bash
# 在电脑上
bm c --plain "hello world"

# 在手机浏览器访问
# https://textdb.online/你的key
```

**手机到电脑 (浏览器输入)**

```bash
# 在手机浏览器访问
# https://textdb.online/你的key
# 直接输入文本

# 在电脑上
bm p
```

## API 说明

基于 [TextDB.online](https://textdb.online/) 免费服务:

- **创建/更新**: `https://api.textdb.online/update/?key={key}&value={text}`
- **读取**: `https://textdb.online/{key}`
- **删除**: `https://api.textdb.online/update/?key={key}&value=`

Key 要求:
- 长度: 6-60 字符
- 不能包含斜杠 (/)
- 建议 20+ 字符以保证安全性

### 服务限制说明

TextDB.online 是一个免费公共服务, 具有以下特点:

- ✅ **免费使用** - 无需注册
- ✅ **读取无限制** - 获取数据无次数限制
- ⚠️ **写入限制 500次/天/IP** - 包含创建、更新、删除操作总和
- ⚠️ **建议测试使用** - 不保证生产环境稳定性
- ⚠️ **1年自动删除** - 数据1年未更新会自动删除
- ⚠️ **无密码保护** - 建议使用长 key (20+ 字符) 避免碰撞

**重要提示**: 本工具设计用于个人设备间便捷的文本共享, 不适合存储关键或高度敏感数据。加密提供基本隐私保护, 但不应依赖于保密性要求高的信息。

### 私有部署

如需用于生产环境或追求更高可靠性, 可以部署自己的 TextDB 服务器:

1. **获取离线版本**: TextDB.online 提供 [私有部署版本](https://demo.textdb.online/)
2. **配置 Beam 使用你的服务器**:
   ```bash
   bm e -s https://your-domain.com
   ```
3. **私有部署的优势**:
   - 更高的稳定性和性能
   - 无速率限制
   - 完全的数据控制权
   - 更好的安全性

如果你自行实现 API 服务器, 需确保遵循 TextDB API 格式:
- 写入端点: `{api_base}/update/?key={key}&value={text}`
- 读取端点: `{read_base}/{key}`

## 配置文件

配置保存在: `~/.config/beam/config.json`

```json
{
  "api_base": "https://api.textdb.online",
  "read_base": "https://textdb.online",
  "key": "your_personal_key",
  "password": "your_encryption_password"
}
```

- `api_base`: API 服务器 URL, 用于写入操作 (默认: `https://api.textdb.online`)
- `read_base`: 服务器 URL, 用于读取操作 (默认: `https://textdb.online`)
- `key`: 你在 TextDB API 使用的个人 key
- `password`: 加密密码 (默认: `123456`)

### 使用私有部署

如果你部署了自己的 TextDB 服务器, 可以这样配置:

```bash
bm e -s https://your-domain.com
```

或直接编辑配置文件设置 `api_base` 和 `read_base`。

## 安全性

所有内容在上传前都会先**压缩** (zlib) 再**加密** (XOR + SHA256):

```
你的文本 → 压缩 → 加密 → Base64 → 上传
```

服务器只能看到类似 `BM2:xxxxx...` 的加密数据, 无法读取你的内容。

使用 `--plain` 选项可以跳过压缩和加密, 适用于需要在移动设备浏览器中查看的非敏感内容。

> ⚠️ 这是为便利性设计的轻量级加密, 不适用于高度敏感数据。

## 依赖

- Python 3.6+
- pyperclip (可选, 用于剪贴板支持)

安装带剪贴板支持的版本:

```bash
pip install beam-clipboard[clipboard]
```

## 贡献

欢迎贡献! 你可以:
- 🐛 报告 bug
- 💡 提出新功能建议
- 🔧 提交 pull request

## 许可证

MIT License

## 作者

[vw2x](https://github.com/vwww-droid)

---

**如果觉得有用, 请给个 Star ⭐**
