Serendipity/QRGen
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新全部 markdown — CLI 子命令语法 + 新功能

Browse Source 
- README: 所有 CLI 示例改为 qrgen encode/decode 子命令
- CHANGELOG: 新增 0.3.0 CLI 重构条目（子命令/stdin/退出码/进度条）
- CLAUDE.md: 更新 CLI 构建命令 + 架构描述
- CLI_USAGE.md: 完全重写完整参数列表 + stdin/补全/退出码章节
This commit is contained in:
刘航宇
2026-06-20 17:52:21 +08:00
parent e6a7efc760
commit 8298cd4c9c
4 changed files with 111 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+13
View File
@@ -1,5 +1,18 @@
# Changelog # Changelog
## 0.3.0 (2026-06-20)
### Changed
- **CLI 重构** — 子命令结构 `qrgen encode` / `qrgen decode`
- 符合 Rust 生态惯例（ripgrep/fd/cargo 风格）
- Shell 补全支持（`--generate-completions bash/zsh/fish/pwsh/elvish`）
- stdin 管道支持（`echo "text" | qrgen encode -`）
- 退出码规范化（0=成功, 1=输入错误, 2=系统错误）
- `-v` → `-V`（version），`-l` 保持不变
- 批量模式进度条（`indicatif` crate）
- 新增依赖：`clap_complete`、`indicatif`、`image`
## 0.3.0 (2026-06-19) ## 0.3.0 (2026-06-19)
### Added ### Added
CLAUDE.md
+7 -6
View File
@@ -22,13 +22,13 @@ cargo build -p qr-core
# CLI 构建 # CLI 构建
cargo build --release -p qrgen cargo build --release -p qrgen
cargo run -p qrgen -- "Hello World" cargo run -p qrgen -- encode "Hello World"
# Web 服务 # Web 服务
cargo run -p qrgen-web # → http://localhost:3000 cargo run -p qrgen-web # → http://localhost:3000
# CLI 解码 # CLI 解码
cargo run -p qrgen -- --decode test.png cargo run -p qrgen -- decode test.png
# GUI 开发模式 # GUI 开发模式
cd gui/src-frontend && pnpm dev # 终端1: Vite 热更新 cd gui/src-frontend && pnpm dev # 终端1: Vite 热更新
@@ -98,12 +98,13 @@ QRGen/
│ │ ├── placement.rs # 蛇形数据排列 │ │ ├── placement.rs # 蛇形数据排列
│ │ └── mask.rs # 8 种掩码 + 四规则惩罚评分 │ │ └── mask.rs # 8 种掩码 + 四规则惩罚评分
│ └── render/ │ └── render/
│ ├── png.rs # PNG 输出 (image crate, 直接边界检测 margin) │ ├── image.rs # 图像输出 (PNG/BMP/JPEG/WebP, image crate)
│ │ # OutputFormat 枚举，支持 Logo 叠加
│ ├── svg.rs # SVG 输出 (预分配容量) │ ├── svg.rs # SVG 输出 (预分配容量)
│ └── ascii.rs # 终端 ASCII (██/ ) │ └── ascii.rs # 终端 ASCII (██/ )
├── cli/ # CLI 命令行 (依赖 core + clap + anyhow) ├── cli/ # CLI 命令行 (依赖 core + clap + clap_complete + indicatif)
│ └── src/main.rs # Args { content, -o, -l, -v, -s, -m, --invert } │ └── src/main.rs # 子命令: encode/decode, stdin 管道, 批量进度条
│ # 含路径遍历防护（拒绝 .. 组件） │ # 含路径遍历防护 + 退出码 + Shell 补全
├── gui/ # Tauri 桌面应用 (依赖 core + tauri-plugin-*) ├── gui/ # Tauri 桌面应用 (依赖 core + tauri-plugin-*)
│ ├── capabilities/default.json # ACL 权限 (store/dialog/clipboard/fs) │ ├── capabilities/default.json # ACL 权限 (store/dialog/clipboard/fs)
│ ├── src/ │ ├── src/
README.md
+5 -5
View File
@@ -128,16 +128,16 @@ sequenceDiagram
```bash ```bash
# 终端 ASCII 预览 # 终端 ASCII 预览
qrgen "Hello World" qrgen encode "Hello World"
# 生成 PNG # 生成 PNG
qrgen "https://example.com" -o qr.png -s 8 qrgen encode "https://example.com" -o qr.png -s 8
# 生成 SVG（高纠错） # 生成 SVG（高纠错）
qrgen "重要数据" -o qr.svg -l H qrgen encode "重要数据" -o qr.svg -l H
# 解码 QR 码图片 # 解码 QR 码图片
qrgen --decode qr.png qrgen decode qr.png
``` ```
### GUI 桌面应用 ### GUI 桌面应用
@@ -201,7 +201,7 @@ cd gui/src-frontend && pnpm dev # 终端1: 前端
cargo run -p qrgen-gui # 终端2: Rust 后端 cargo run -p qrgen-gui # 终端2: Rust 后端
# CLI 开发 # CLI 开发
cargo run -p qrgen -- "Hello World" cargo run -p qrgen -- encode "Hello World"
# Web 开发 # Web 开发
cargo run -p qrgen-web # → http://localhost:3000 cargo run -p qrgen-web # → http://localhost:3000
docs/CLI_USAGE.md
+86 -64
View File
@@ -6,16 +6,16 @@
```bash ```bash
# 终端预览 QR 码 # 终端预览 QR 码
qrgen "Hello World" qrgen encode "Hello World"
# 生成 PNG # 生成 PNG
qrgen "https://example.com" -o qr.png qrgen encode "https://example.com" -o qr.png
# 生成 SVG # 生成 SVG
qrgen "重要数据" -o qr.svg -l H qrgen encode "重要数据" -o qr.svg -l H
# 解码 QR 图片 # 解码 QR 图片
qrgen --decode qr.png qrgen decode qr.png
``` ```
--- ---
@@ -25,7 +25,8 @@ qrgen --decode qr.png
### 语法 ### 语法
```bash ```bash
qrgen [内容] [选项] qrgen encode [OPTIONS] [CONTENT]
qrgen decode [FILE]
``` ```
### 选项 ### 选项
@@ -47,25 +48,25 @@ qrgen [内容] [选项]
```bash ```bash
# 基础生成 # 基础生成
qrgen "Hello World" -o hello.png qrgen encode "Hello World" -o hello.png
# 高纠错 + 大尺寸 # 高纠错 + 大尺寸
qrgen "重要合同编号: ABC-12345678" -o contract.png -l H -s 8 -m 6 qrgen encode "重要合同编号: ABC-12345678" -o contract.png -l H -s 8 -m 6
# 彩色 QR 码 # 彩色 QR 码
qrgen "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7" qrgen encode "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7"
# 带 Logo # 带 Logo
qrgen "https://mycompany.com" -o logo.png -l H --logo avatar.png qrgen encode "https://mycompany.com" -o logo.png -l H --logo avatar.png
# JPEG 输出 # JPEG 输出
qrgen "JPEG test" -o qr.jpg -f jpeg qrgen encode "JPEG test" -o qr.jpg -f jpeg
# WebP 输出 # WebP 输出
qrgen "WebP test" -o qr.webp -f webp qrgen encode "WebP test" -o qr.webp -f webp
# 指定版本（强制版本 5） # 指定版本（强制版本 5）
qrgen "Fixed version" -o fixed.png -v 5 qrgen encode "Fixed version" -o fixed.png -v 5
``` ```
--- ---
@@ -77,31 +78,31 @@ qrgen "Fixed version" -o fixed.png -v 5
### 文本模式（默认） ### 文本模式（默认）
```bash ```bash
qrgen "任意文本内容" -o text.png qrgen encode "任意文本内容" -o text.png
``` ```
等同于： 等同于：
```bash ```bash
qrgen --mode text "任意文本内容" -o text.png qrgen encode --mode text "任意文本内容" -o text.png
``` ```
### URL 模式 ### URL 模式
```bash ```bash
qrgen --mode url --url "https://github.com/LHY0125/QRGen" -o url.png qrgen encode --mode url --url "https://github.com/LHY0125/QRGen" -o url.png
``` ```
### WiFi 模式 ### WiFi 模式
```bash ```bash
# 基础 WiFi # 基础 WiFi
qrgen --mode wifi --ssid MyWiFi --password pass123 -o wifi.png qrgen encode --mode wifi --ssid MyWiFi --password pass123 -o wifi.png
# 无密码 WiFi # 无密码 WiFi
qrgen --mode wifi --ssid FreeWiFi --encryption nopass -o free-wifi.png qrgen encode --mode wifi --ssid FreeWiFi --encryption nopass -o free-wifi.png
# 隐藏网络 + WPA2 # 隐藏网络 + WPA2
qrgen --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden -o hidden.png qrgen encode --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden -o hidden.png
``` ```
生成的 QR 内容格式：`WIFI:T:WPA;S:MyWiFi;P:pass123;;` 生成的 QR 内容格式：`WIFI:T:WPA;S:MyWiFi;P:pass123;;`
@@ -117,14 +118,14 @@ qrgen --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden
```bash ```bash
# 基础名片 # 基础名片
qrgen --mode vcard \ qrgen encode --mode vcard \
--name "张三" \ --name "张三" \
--phone "13800138000" \ --phone "13800138000" \
--email "zhangsan@example.com" \ --email "zhangsan@example.com" \
-o card.png -o card.png
# 完整名片（10 字段） # 完整名片（10 字段）
qrgen --mode vcard \ qrgen encode --mode vcard \
--name "张三" \ --name "张三" \
--phone "13800138000" \ --phone "13800138000" \
--email "zhangsan@example.com" \ --email "zhangsan@example.com" \
@@ -154,7 +155,7 @@ qrgen --mode vcard \
### Email 模式 ### Email 模式
```bash ```bash
qrgen --mode email \ qrgen encode --mode email \
--to "hello@example.com" \ --to "hello@example.com" \
--subject "合作洽谈" \ --subject "合作洽谈" \
--body "您好，我对贵公司的产品很感兴趣。" \ --body "您好，我对贵公司的产品很感兴趣。" \
@@ -166,7 +167,7 @@ qrgen --mode email \
### 电话模式 ### 电话模式
```bash ```bash
qrgen --mode phone --number "13800138000" -o phone.png qrgen encode --mode phone --number "13800138000" -o phone.png
``` ```
扫描后直接拨号。 扫描后直接拨号。
@@ -174,7 +175,7 @@ qrgen --mode phone --number "13800138000" -o phone.png
### 短信模式 ### 短信模式
```bash ```bash
qrgen --mode sms \ qrgen encode --mode sms \
--number "13800138000" \ --number "13800138000" \
--message "你好，方便电话吗？" \ --message "你好，方便电话吗？" \
-o sms.png -o sms.png
@@ -197,7 +198,7 @@ qrgen --mode sms \
``` ```
```bash ```bash
qrgen --batch items.json --output-dir ./qr_output/ qrgen encode --batch items.json --output-dir ./qr_output/
# 输出: qr_output/qr_0001.png, qr_output/qr_0002.png, ... # 输出: qr_output/qr_0001.png, qr_output/qr_0002.png, ...
``` ```
@@ -211,7 +212,7 @@ content,level
``` ```
```bash ```bash
qrgen --batch items.csv --output-dir ./qr_output/ -s 8 qrgen encode --batch items.csv --output-dir ./qr_output/ -s 8
``` ```
### 批量 WiFi 名片 ### 批量 WiFi 名片
@@ -235,7 +236,7 @@ JSON 中可以用模式专用字段：
从图片文件解码 QR 码内容。 从图片文件解码 QR 码内容。
```bash ```bash
qrgen --decode qr.png qrgen decode qr.png
qrgen -d qr.jpg qrgen -d qr.jpg
``` ```
@@ -284,62 +285,83 @@ qrgen -d qr.jpg
## 完整参数列表 ## 完整参数列表
``` ```
Usage: qrgen [OPTIONS] [CONTENT] Usage: qrgen <COMMAND>
qrgen --decode <FILE>
基础选项: Commands:
encode 编码：文本 → QR 码
decode 解码：QR 码图片 → 文本
通用选项:
--generate-completions <SHELL> 生成 Shell 补全脚本 (bash/zsh/fish/powershell/elvish)
-h, --help 显示帮助
-V, --version 显示版本
编码子命令 — qrgen encode [OPTIONS] [CONTENT]
-o, --output <FILE> 输出文件 (.png/.bmp/.jpg/.webp/.svg) -o, --output <FILE> 输出文件 (.png/.bmp/.jpg/.webp/.svg)
-l, --level <L/M/Q/H> 纠错级别 [default: M] -l, --level <L/M/Q/H> 纠错级别 [default: M]
-v, --version <1-40> 手动指定版本 [default: auto] -V, --version <1-40> 手动指定版本 [default: auto]
-s, --size <PIXELS> 模块像素大小 [default: 4] -s, --size <PIXELS> 模块像素大小 [default: 4]
-m, --margin <MODULES> 白边模块数 [default: 4] -m, --margin <MODULES> 白边模块数 [default: 4]
-f, --format <FORMAT> 图像格式: png/bmp/jpeg/webp [default: 由扩展名推断] -f, --format <FORMAT> 图像格式: png/bmp/jpeg/webp [default: png]
--fg <#RRGGBB> 前景色 [default: #000] --fg <#RRGGBB> 前景色 [default: #000]
--bg <#RRGGBB> 背景色 [default: #FFF] --bg <#RRGGBB> 背景色 [default: #FFF]
--logo <FILE> Logo 图片文件 --logo <FILE> Logo 图片文件
--invert 终端反色
模式选项:
--mode <MODE> 编码模式: text/url/wifi/vcard/email/phone/sms/batch --mode <MODE> 编码模式: text/url/wifi/vcard/email/phone/sms/batch
WiFi 选项:
--ssid <NAME> WiFi 名称 --ssid <NAME> WiFi 名称
--password <PWD> WiFi 密码 --password <PWD> WiFi 密码
--encryption <TYPE> 加密方式: WPA/WPA2/WEP/nopass [default: WPA] --encryption <TYPE> 加密方式: WPA/WPA2/WEP/nopass [default: WPA]
--hidden 隐藏网络 --hidden 隐藏网络
--name <NAME> 姓名 (vCard)
vCard 选项: --phone <NUMBER> 电话 (vCard)
--name <NAME> 姓名 --email <ADDR> 邮箱 (vCard)
--phone <NUMBER> 电话 --company <NAME> 公司 (vCard)
--email <ADDR> 邮箱 --title <TITLE> 职位 (vCard)
--company <NAME> 公司 --address <ADDR> 地址 (vCard)
--title <TITLE> 职位 --vcard-url <URL> 个人网址 (vCard)
--address <ADDR> 地址 --birthday <DATE> 生日 YYYY-MM-DD (vCard)
--vcard-url <URL> 个人网址 --note <TEXT> 备注 (vCard)
--birthday <DATE> 生日 (YYYY-MM-DD) --photo <URL> 照片 URL (vCard)
--note <TEXT> 备注 --to <ADDR> 收件人 (Email)
--photo <URL> 照片 URL --subject <TEXT> 主题 (Email)
--body <TEXT> 正文 (Email)
Email 选项: --number <NUMBER> 电话号码 (Phone/SMS)
--to <ADDR> 收件人 --message <TEXT> 短信内容 (SMS)
--subject <TEXT> 主题
--body <TEXT> 正文
电话/短信选项:
--number <NUMBER> 电话号码
--message <TEXT> 短信内容
URL 选项:
--url <URL> URL 链接 --url <URL> URL 链接
批量选项:
--batch <FILE> 批量输入文件 (JSON/CSV) --batch <FILE> 批量输入文件 (JSON/CSV)
--output-dir <DIR> 批量输出目录 --output-dir <DIR> 批量输出目录
解码选项: 解码子命令 — qrgen decode [FILE]
-d, --decode <FILE> 解码 QR 图片 [FILE] 图片文件路径（传 - 从 stdin 读取）
``` ```
### stdin 管道
```bash
# 编码：从管道读入
echo "Hello" | qrgen encode - -o qr.png
cat long_text.txt | qrgen encode - -o qr.png
# 解码：从管道读入
curl -s https://api.example.com/qr.png | qrgen decode -
```
### Shell 补全
```bash
# 生成补全脚本
qrgen --generate-completions bash > /usr/share/bash-completion/completions/qrgen
qrgen --generate-completions zsh > /usr/share/zsh/site-functions/_qrgen
qrgen --generate-completions fish > ~/.config/fish/completions/qrgen.fish
```
### 退出码
| 码 | 含义 |
|----|------|
| 0 | 成功 |
| 1 | 输入错误（内容为空、模式不匹配、解码失败） |
| 2 | 系统错误（文件不存在、IO 错误） |
--- ---
## 常见问题 ## 常见问题
@@ -356,7 +378,7 @@ URL 选项:
降低纠错级别（L 级容量最大），或让系统自动选择版本： 降低纠错级别（L 级容量最大），或让系统自动选择版本：
```bash ```bash
qrgen "很长的文本..." -o big.png -l L qrgen encode "很长的文本..." -o big.png -l L
``` ```
### Q: Logo 叠加后扫不出来？ ### Q: Logo 叠加后扫不出来？