# Technical Documentation: JOYCEQL/magic-resume

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/JOYCEQL/magic-resume)

### Overview (README.md)

<div align="center">

# ✨ Magic Resume ✨

[](https://opensource.org/licenses/Apache-2.0)



<a href="https://trendshift.io/repositories/13077" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13077" alt="Magic Resume | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

[简体中文](./README.zh-CN.md) | English

</div>

Magic Resume is a modern online resume editor that makes creating professional resumes simple and enjoyable. Built with TanStack Start and Framer Motion, it supports real-time preview and custom themes.

## 📸 Screenshots

<img width="1920" height="1440" alt="336_1x_shots_so" src="https://github.com/user-attachments/assets/18969a17-06f8-4a4b-94eb-284ba8442620" />


## ✨ Features

- 🚀 Built with TanStack Start
- 💫 Smooth animations (Framer Motion)
- 🎨 Custom theme support
- 📱 Responsive design
- 🌙 Dark mode
- 📤 Export to PDF
- 🔄 Real-time preview
- 💾 Auto-save
- 🔒 Local storage

## 🛠️ Tech Stack

- TanStack Start
- TypeScript
- Motion
- Tiptap
- Tailwind CSS
- Zustand
- Shadcn/ui
- Lucide Icons

## 🚀 Quick Start

1. Clone the project

```bash
git clone git@github.com:JOYCEQL/magic-resume.git
cd magic-resume
```

2. Install dependencies

```bash
pnpm install
```

3. Start development server

```bash
pnpm dev
```

4. Open browser and visit `http://localhost:3000`

## 📦 Build and Deploy

```bash
pnpm build
```

### AI provider networking

Cloudflare Workers use the platform's native `fetch` and do not need an application-level proxy. For Node.js or Docker deployments in regions that cannot directly reach OpenAI, Gemini, or Anthropic, set `AI_PROXY_URL`. `HTTPS_PROXY` and `HTTP_PROXY` are also supported as fallbacks.

```bash
AI_PROXY_URL=http://127.0.0.1:7890
```

DeepSeek, Qwen, and Doubao continue to use a direct connection.


## 🐳 Docker Deployment

### Docker Compose

1. Ensure you have Docker and Docker Compose installed

2. Run the following command in the project root directory:

```bash
docker compose up -d
```

This will:

- Automatically build the application image
- Start the container in the background


## 📝 License and Usage Restrictions

The source code of this project is released under the **Apache 2.0** license with an additional **non-commercial use restriction**:

- **Free for Personal Use**: Free to use purely for personal, non-commercial purposes (e.g., personal learning, creating your own resume).
- **Commercial Use Prohibited**: The project may not be used for any commercial purpose, including providing it as a paid or profit-generating service (such as SaaS/PaaS), enterprise commercial operations, resale, or secondary commercial development, **regardless of whether the source code has been modified**.

Please see the [LICENSE](LICENSE) file for detailed terms.

## 🗺️ Roadmap

- [x] AI-assisted writing
- [x] Multi-language support
- [ ] Support for more resume templates
- [x] Support for more export formats
- [x] Import PDF, Markdown, etc.
- [x] Custom model
- [x] Auto one page
- [ ] Online resume hosting

## 📈 Star History

<a href="https://star-history.com/#JOYCEQL/magic-resume&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JOYCEQL/magic-resume&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JOYCEQL/magic-resume&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JOYCEQL/magic-resume&type=Date" />
 </picture>
</a>

## 📞 Contact

You can follow the latest updates via:

- Author: Siyue
- X: @GuangzhouY81070
- Discord: Join our community https://discord.gg/9mWgZrW3VN
- Email: 18806723365@163.com


- Project Homepage: https://github.com/JOYCEQL/magic-resume

## 🌟 Support

If you find this project helpful, please give it a star ⭐️

## ❤️ Sponsors

<div align="center">
  <h3>Sponsors</h3>
  <p>If you sponsored this project but are not listed here, please contact me.</p>
  <p>
    <a href="https://github.com/yj147">
      <img src="https://github.com/yj147.png?size=40" width="40" height="40" alt="@yj147" />
    </a>
    <a href="https://github.com/someone1128">
      <img src="https://github.com/someone1128.png?size=40" width="40" height="40" alt="@someone1128" />
    </a>
    
  </p>
</div>

---

### Pdf Import (`docs/pdf-import.md`)

# PDF 解析模型配置

在「AI 服务商」页面选择厂商并填写一次 API Key。文字助手与 PDF 解析直接复用这份凭证，无需填写模型 ID 或手动设置图片能力。

每个厂商下展示维护好的内置模型。模型卡会标明 `文字`、`PDF` 能力；填入 Key 后，这些模型会出现在页面顶部对应的选择框中。连接检测按模型执行，PDF 模型会使用测试图片验证视觉输入。

当前内置模型：

| 服务商   | 内置模型                                                |
| -------- | ------------------------------------------------------- |
| OpenAI   | GPT-5.6 Sol、GPT-5.6 Terra、GPT-5.6 Luna                |
| 千问     | Qwen 3.8 Max、Qwen 3.7 Plus、Qwen 3.8 Flash             |
| Gemini   | Gemini 3.8 Flash、Gemini 3.1 Pro、Gemini 3.1 Flash-Lite |
| Claude   | Claude Sonnet 5、Claude Opus 5、Claude Haiku 4.5        |
| DeepSeek | DeepSeek V4 Pro、V4 Flash、V4 Vision                    |
| 豆包     | Doubao Seed 2.1 Pro、Seed 2.0 Lite、Seed 1.6 Vision     |

填完配置后点击「检测连接」。连接正常后，在顶部为文字助手和 PDF 解析分别选择模型，再到「我的简历 → 导入简历 → 导入 PDF」使用。

## 导入范围

- PDF 在浏览器中渲染为页面图片，再发送给所选模型提取结构化简历。
- 最多 10 页，原文件最多 20 MB，请求体最多 16 MB；超过限制会直接提示。
- 不支持加密或损坏的 PDF。
- 创建前会显示识别预览；原 PDF 的版式和照片不会保留。
- 认证失败、限流、模型不支持图片、空结果、非法 JSON 和输出截断都有对应错误提示。

## 验证

使用 Node.js 20.19+ 或 22.12+：

```sh
pnpm test:ai
pnpm build
```

自动测试使用模拟响应，不会调用真实模型。实际识别效果需要配置自己的 Key 后测试。

---

--- METRICS ---
- Files Extracted: 2
- Estimated Token Budget: ~1380 tokens
- Canonical Reference: https://codewiki.google/github.com/JOYCEQL/magic-resume