diff --git a/.gitignore b/.gitignore
index 0f91d8e..ec51237 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,20 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# ---- 大文件素材（可从手机重新获取/重新生成，不入库）----
 samples/
 *.ppl
 *.psd
-__pycache__/
+*.png
+*.img
+*.jpg
+*.jpeg
+
+# ---- 临时文件 ----
+*.tmp
+*.log
+.DS_Store
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1741dcd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# pplCpsd — Photo Editor (.ppl) ↔ Photoshop (.psd) 转换工具
+
+将安卓「照片编辑器」(Photo Editor, dev.macgyver) 的多图层项目文件 `.ppl`
+与 Adobe Photoshop 的 `.psd` 双向转换。
+
+`.ppl` 本质是 ZIP 包：内含 `layers.ini`（图层描述）+ 若干 `*.img`（图层 PNG）。
+
+---
+
+## 功能
+
+### ppl2psd.py — PPL → PSD
+
+| 特性 | 说明 |
+|---|---|
+| 默认（栅格化） | 所有层（位图/形状/文字）转成像素图层，视觉与 App 一致 |
+| `--type-layer` | 文字层转成**可编辑的 TypeLayer**（PS 里可改字/字号/颜色） |
+| 图层组映射 | ppl 的 `[group]` + 图层 `groupId` → PSD 图层组（含嵌套），无需参数 |
+| 加粗映射 | `textFontStyle=1`（伪加粗）→ TypeLayer 的 FauxBold / 栅格化 stroke 加粗 |
+| 进度条 | tqdm 显示渲染/编码进度 |
+
+### psd2ppl.py — PSD → PPL
+
+- 像素层 → `[bitmap]` 层（导出 PNG + 位置/透明度/可见性）
+- 文字层（TypeLayer）→ `[text]` 层（内容/字号/颜色，字体映射到手机字体）
+- 图层位置、不透明度、可见性保留
+
+---
+
+## 安装
+
+```bash
+pip install pillow numpy tqdm psd-tools fonttools
+```
+
+> 字体 PostScript 名提取（TypeLayer 用）需要 fonttools，其他为必需依赖。
+
+---
+
+## 用法
+
+```bash
+# PPL → PSD（栅格化，默认）
+python3 ppl2psd.py input.ppl -o out.psd --preview out.png
+
+# PPL → PSD（文字转可编辑 TypeLayer）
+python3 ppl2psd.py input.ppl -o out.psd --type-layer
+
+# PSD → PPL（反向）
+python3 psd2ppl.py input.psd -o out.ppl
+```
+
+参数：
+- `-o` / `--output`：输出路径（默认与输入同名）
+- `--preview`：同时输出合成预览 PNG
+- `-j` / `--workers`：并行编码线程数（默认 4）
+- `--type-layer`：文字转 TypeLayer
+
+---
+
+## 目录结构
+
+```
+pplCpsd/
+├── ppl2psd.py              # PPL → PSD
+├── psd2ppl.py              # PSD → PPL
+├── tools_tysh_template.bin # TypeLayer 引擎数据模板（取自 PS 生成文件）
+└── samples/                # 测试素材（ppl/psd/预览图）
+```
+
+---
+
+## 已知限制
+
+- **栅格化模式**（默认）下文字/渐变/圆角都是像素，PS 里不可编辑（可移动/缩放/调透明度）
+- **TypeLayer 模式**：PS 里文字可编辑，但需要电脑安装对应字体（`/storage/emulated/0/Fonts/` 下的
+  汉仪花冠、思源宋体/黑体、行楷等），否则 PS 会用替换字体显示
+- 形状渐变/圆角在两种模式下均栅格化（不可编辑渐变参数）
+- PSD → PPL 反向转换后，原 ppl 的文字/形状矢量信息无法恢复（已栅格化）
+
+---
+
+## 校准说明
+
+ppl 的文字渲染与 PS 有系统性差异，本项目针对 App 导出图做了逐项校准：
+
+- **字号系数**：App 实际字号 = `textSize × k`（按字体族配置，思源宋体 0.8、黑体 1.0 等）
+- **字符宽度**：PIL 的 CFF 字体 advance 与 App 不同，按全角/半角/标点/空格分系数修正
+- **对齐**：居中基准按字体族区分（advance 居中 vs 内容居中）
+- **blending ranges**：PS 要求图层合成范围为全范围 (0..65535)，否则图层不参与合成（画布空白）
+
+修改 `ppl2psd.py` 顶部的 `FONT_PROFILES` 可调整各字体渲染参数。