diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8e54b6a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+# VoiceInput
+
+macOS 菜单栏语音输入应用 —— 按住 Fn 键录音，松开自动注入文本。
+
+## 功能
+
+- 🎤 **按住 Fn 说话**：全局监听 Fn/Globe 键，按下录音，松开注入
+- 📝 **流式识别**：Apple Speech Recognition 实时转录，默认简体中文
+- 🌐 **多语言**：简中 / 繁中 / English / 日本語 / 한국어
+- 🎚 **实时波形**：5 条 RMS 驱动的球形波动画，说话时随音量跳动
+- 🪟 **胶囊浮动窗**：屏幕底部居中，无边框，入场弹簧动画
+- 📋 **智能注入**：剪贴板 + Cmd+V，自动检测并切换 CJK 输入法
+- 🤖 **LLM 纠错**：DeepSeek 优化识别结果，修正同音字 / 拼写 / 术语
+
+## 系统要求
+
+- macOS 14+
+- 辅助功能权限（监听 Fn 键）
+- 麦克风权限
+- 语音识别权限
+
+## 快速开始
+
+```bash
+make build   # 编译 + 生成 .app
+make run     # 构建并启动
+```
+
+首次运行需在 **系统设置 → 隐私与安全性 → 辅助功能** 中授权 `VoiceInput.app`。
+
+## 使用
+
+1. 点击任意文本输入框
+2. 按住键盘左下角 **Fn / 🌐 键**
+3. 说话，胶囊窗口显示实时转录
+4. 松开 Fn → 文本自动粘贴到光标位置
+
+点击菜单栏 🎤 图标可切换语言或配置 LLM。
+
+## 构建
+
+```bash
+make build      # Debug 构建
+make release    # Release 构建
+make install    # 安装到 /Applications
+make clean      # 清理
+```
+
+## LLM 纠错
+
+LLM 默认使用 DeepSeek，在菜单栏 **LLM Refinement → Enable** 开启。
+
+| 配置项 | 默认值 |
+|--------|--------|
+| API Base URL | `https://api.deepseek.com` |
+| Model | `deepseek-v4-flash` |
+
+设置窗口可修改 API Key 等配置，点击 **Test** 验证连通性。
+
+## 项目结构
+
+```
+Sources/
+├── App/          # AppDelegate + 菜单栏控制器
+├── Core/         # 按键监听、语音识别、音频电平、文本注入、输入法、LLM
+├── UI/           # 浮动窗口、波形动画、设置窗口
+└── Utils/        # 配置持久化
+```
+
+## 许可
+
+MIT