diff --git a/CHANGELOG.md b/CHANGELOG.md
index 651b551..c371de9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,18 @@
 # 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)
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index c815b86..53aabf4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,13 +22,13 @@ cargo build -p qr-core
 
 # CLI 构建
 cargo build --release -p qrgen
-cargo run -p qrgen -- "Hello World"
+cargo run -p qrgen -- encode "Hello World"
 
 # Web 服务
 cargo run -p qrgen-web               # → http://localhost:3000
 
 # CLI 解码
-cargo run -p qrgen -- --decode test.png
+cargo run -p qrgen -- decode test.png
 
 # GUI 开发模式
 cd gui/src-frontend && pnpm dev     # 终端1: Vite 热更新
@@ -98,12 +98,13 @@ QRGen/
 │       │   ├── placement.rs      # 蛇形数据排列
 │       │   └── mask.rs           # 8 种掩码 + 四规则惩罚评分
 │       └── render/
-│           ├── png.rs            # PNG 输出 (image crate, 直接边界检测 margin)
+│           ├── image.rs          # 图像输出 (PNG/BMP/JPEG/WebP, image crate)
+│           │                     # OutputFormat 枚举，支持 Logo 叠加
 │           ├── svg.rs            # SVG 输出 (预分配容量)
 │           └── ascii.rs          # 终端 ASCII (██/  )
-├── cli/                          # CLI 命令行 (依赖 core + clap + anyhow)
-│   └── src/main.rs               # Args { content, -o, -l, -v, -s, -m, --invert }
-│                                 # 含路径遍历防护（拒绝 .. 组件）
+├── cli/                          # CLI 命令行 (依赖 core + clap + clap_complete + indicatif)
+│   └── src/main.rs               # 子命令: encode/decode, stdin 管道, 批量进度条
+│                                 # 含路径遍历防护 + 退出码 + Shell 补全
 ├── gui/                          # Tauri 桌面应用 (依赖 core + tauri-plugin-*)
 │   ├── capabilities/default.json # ACL 权限 (store/dialog/clipboard/fs)
 │   ├── src/
diff --git a/README.md b/README.md
index 4d73237..6a4c834 100644
--- a/README.md
+++ b/README.md
@@ -128,16 +128,16 @@ sequenceDiagram
 
 ```bash
 # 终端 ASCII 预览
-qrgen "Hello World"
+qrgen encode "Hello World"
 
 # 生成 PNG
-qrgen "https://example.com" -o qr.png -s 8
+qrgen encode "https://example.com" -o qr.png -s 8
 
 # 生成 SVG（高纠错）
-qrgen "重要数据" -o qr.svg -l H
+qrgen encode "重要数据" -o qr.svg -l H
 
 # 解码 QR 码图片
-qrgen --decode qr.png
+qrgen decode qr.png
 ```
 
 ### GUI 桌面应用
@@ -201,7 +201,7 @@ cd gui/src-frontend && pnpm dev    # 终端1: 前端
 cargo run -p qrgen-gui             # 终端2: Rust 后端
 
 # CLI 开发
-cargo run -p qrgen -- "Hello World"
+cargo run -p qrgen -- encode "Hello World"
 
 # Web 开发
 cargo run -p qrgen-web              # → http://localhost:3000
diff --git a/docs/CLI_USAGE.md b/docs/CLI_USAGE.md
index 0c0d470..90e0077 100644
--- a/docs/CLI_USAGE.md
+++ b/docs/CLI_USAGE.md
@@ -6,16 +6,16 @@
 
 ```bash
 # 终端预览 QR 码
-qrgen "Hello World"
+qrgen encode "Hello World"
 
 # 生成 PNG
-qrgen "https://example.com" -o qr.png
+qrgen encode "https://example.com" -o qr.png
 
 # 生成 SVG
-qrgen "重要数据" -o qr.svg -l H
+qrgen encode "重要数据" -o qr.svg -l H
 
 # 解码 QR 图片
-qrgen --decode qr.png
+qrgen decode qr.png
 ```
 
 ---
@@ -25,7 +25,8 @@ qrgen --decode qr.png
 ### 语法
 
 ```bash
-qrgen [内容] [选项]
+qrgen encode [OPTIONS] [CONTENT]
+qrgen decode [FILE]
 ```
 
 ### 选项
@@ -47,25 +48,25 @@ qrgen [内容] [选项]
 
 ```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 码
-qrgen "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7"
+qrgen encode "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7"
 
 # 带 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 输出
-qrgen "JPEG test" -o qr.jpg -f jpeg
+qrgen encode "JPEG test" -o qr.jpg -f jpeg
 
 # WebP 输出
-qrgen "WebP test" -o qr.webp -f webp
+qrgen encode "WebP test" -o qr.webp -f webp
 
 # 指定版本（强制版本 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
-qrgen "任意文本内容" -o text.png
+qrgen encode "任意文本内容" -o text.png
 ```
 
 等同于：
 ```bash
-qrgen --mode text "任意文本内容" -o text.png
+qrgen encode --mode text "任意文本内容" -o text.png
 ```
 
 ### URL 模式
 
 ```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 模式
 
 ```bash
 # 基础 WiFi
-qrgen --mode wifi --ssid MyWiFi --password pass123 -o wifi.png
+qrgen encode --mode wifi --ssid MyWiFi --password pass123 -o wifi.png
 
 # 无密码 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
-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;;`
@@ -117,14 +118,14 @@ qrgen --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden
 
 ```bash
 # 基础名片
-qrgen --mode vcard \
+qrgen encode --mode vcard \
   --name "张三" \
   --phone "13800138000" \
   --email "zhangsan@example.com" \
   -o card.png
 
 # 完整名片（10 字段）
-qrgen --mode vcard \
+qrgen encode --mode vcard \
   --name "张三" \
   --phone "13800138000" \
   --email "zhangsan@example.com" \
@@ -154,7 +155,7 @@ qrgen --mode vcard \
 ### Email 模式
 
 ```bash
-qrgen --mode email \
+qrgen encode --mode email \
   --to "hello@example.com" \
   --subject "合作洽谈" \
   --body "您好，我对贵公司的产品很感兴趣。" \
@@ -166,7 +167,7 @@ qrgen --mode email \
 ### 电话模式
 
 ```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
-qrgen --mode sms \
+qrgen encode --mode sms \
   --number "13800138000" \
   --message "你好，方便电话吗？" \
   -o sms.png
@@ -197,7 +198,7 @@ qrgen --mode sms \
 ```
 
 ```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, ...
 ```
 
@@ -211,7 +212,7 @@ content,level
 ```
 
 ```bash
-qrgen --batch items.csv --output-dir ./qr_output/ -s 8
+qrgen encode --batch items.csv --output-dir ./qr_output/ -s 8
 ```
 
 ### 批量 WiFi 名片
@@ -235,7 +236,7 @@ JSON 中可以用模式专用字段：
 从图片文件解码 QR 码内容。
 
 ```bash
-qrgen --decode qr.png
+qrgen decode qr.png
 qrgen -d qr.jpg
 ```
 
@@ -284,62 +285,83 @@ qrgen -d qr.jpg
 ## 完整参数列表
 
 ```
-Usage: qrgen [OPTIONS] [CONTENT]
-       qrgen --decode <FILE>
+Usage: qrgen <COMMAND>
 
-基础选项:
+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)
   -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]
   -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]
   --bg <#RRGGBB>          背景色 [default: #FFF]
   --logo <FILE>           Logo 图片文件
-  --invert                终端反色
-
-模式选项:
   --mode <MODE>           编码模式: text/url/wifi/vcard/email/phone/sms/batch
-
-WiFi 选项:
   --ssid <NAME>           WiFi 名称
   --password <PWD>        WiFi 密码
   --encryption <TYPE>     加密方式: WPA/WPA2/WEP/nopass [default: WPA]
   --hidden                隐藏网络
-
-vCard 选项:
-  --name <NAME>           姓名
-  --phone <NUMBER>        电话
-  --email <ADDR>          邮箱
-  --company <NAME>        公司
-  --title <TITLE>         职位
-  --address <ADDR>        地址
-  --vcard-url <URL>       个人网址
-  --birthday <DATE>       生日 (YYYY-MM-DD)
-  --note <TEXT>           备注
-  --photo <URL>           照片 URL
-
-Email 选项:
-  --to <ADDR>             收件人
-  --subject <TEXT>        主题
-  --body <TEXT>           正文
-
-电话/短信选项:
-  --number <NUMBER>       电话号码
-  --message <TEXT>        短信内容
-
-URL 选项:
+  --name <NAME>           姓名 (vCard)
+  --phone <NUMBER>        电话 (vCard)
+  --email <ADDR>          邮箱 (vCard)
+  --company <NAME>        公司 (vCard)
+  --title <TITLE>         职位 (vCard)
+  --address <ADDR>        地址 (vCard)
+  --vcard-url <URL>       个人网址 (vCard)
+  --birthday <DATE>       生日 YYYY-MM-DD (vCard)
+  --note <TEXT>           备注 (vCard)
+  --photo <URL>           照片 URL (vCard)
+  --to <ADDR>             收件人 (Email)
+  --subject <TEXT>        主题 (Email)
+  --body <TEXT>           正文 (Email)
+  --number <NUMBER>       电话号码 (Phone/SMS)
+  --message <TEXT>        短信内容 (SMS)
   --url <URL>             URL 链接
-
-批量选项:
   --batch <FILE>          批量输入文件 (JSON/CSV)
   --output-dir <DIR>      批量输出目录
 
-解码选项:
-  -d, --decode <FILE>     解码 QR 图片
+解码子命令 — qrgen decode [FILE]
+  [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 级容量最大），或让系统自动选择版本：
 
 ```bash
-qrgen "很长的文本..." -o big.png -l L
+qrgen encode "很长的文本..." -o big.png -l L
 ```
 
 ### Q: Logo 叠加后扫不出来？