Metadata-Version: 2.4
Name: resume-story
Version: 0.1.0
Summary: Convert traditional resumes into narrative career stories with beautiful visualizations
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: cli,narrative,resume,story,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.0
Requires-Dist: llmdog>=0.0.3
Requires-Dist: markdown>=3.5
Requires-Dist: pdfplumber>=0.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Resume Story

> 把你的简历变成一段有温度的职业故事，一键生成精美的可视化网页。

[![PyPI version](https://img.shields.io/pypi/v/resume-story)](https://pypi.org/project/resume-story/)
[![Python](https://img.shields.io/pypi/pyversions/resume-story)](https://pypi.org/project/resume-story/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

你是否厌倦了千篇一律的简历模板？**Resume Story** 把你的职业经历转化为一场有叙事感的旅程——它不只是罗列经历和数据，而是用"讲故事"的方式，让阅读者感受到你的成长脉络和技术深度。

只需一条命令，你的简历就能变成一个可独立打开的 HTML 页面，支持六种风格迥异的视觉主题，可自由分享给任何人。

---

## 功能亮点

**多格式解析** — 支持 YAML、JSON、PDF、Markdown、纯文本五种简历格式，无需手动转换。

**智能叙事生成** — 接入 LLM 大语言模型，将干巴巴的工作经历编织成具有主题和内在逻辑的职业故事；也可完全离线使用内置的 fallback 引擎。

**六种视觉主题** — 从暗色宇宙叙事到复古 CRT 终端，从极简作品集到 3D 赛博朋克工作室，满足不同岗位和审美偏好。

**零依赖分享** — 生成的 HTML 是完整的独立文件（CSS/JS 全部内联），可直接通过浏览器打开、邮件发送或部署到任意静态网站。

**跨平台命令行** — 基于 Typer + Rich 构建的终端界面，Windows / macOS / Linux 均可使用，对新手非常友好。

---

## 模板风格一览

### story — 叙事时间线

深邃宇宙背景搭配金色字体，用时间轴串联你的职业旅程，适合技术岗位展示深度。

![story 模板效果](docs/images/screenshot_story.png)

### dashboard — 数据仪表盘

以图表和指标卡片呈现职业数据，专业且信息密度高，适合业务/职能岗位。

![dashboard 模板效果](docs/images/screenshot_dashboard.png)

### immersive3d — 3D 虚拟工作室

基于 Three.js 的赛博朋克风格，粒子特效与玻璃拟态卡片打造沉浸式体验，适合创意/技术岗位。

![immersive3d 模板效果](docs/images/screenshot_immersive3d.png)

### minimal — 极简作品集

Apple/MUJI 风格的明亮留白设计，排版克制优雅，适合设计师和通用场景。

![minimal 模板效果](docs/images/screenshot_minimal.png)

### bento — Bento Grid 卡片

现代化的暗色 Bento 网格布局，用不同尺寸的卡片承载信息，适合产品和全栈工程师。

![bento 模板效果](docs/images/screenshot_bento.png)

### retro — 复古终端

CRT 显示器质感，磷光绿字体配合扫描线动画，极客和运维同学的最爱。

![retro 模板效果](docs/images/screenshot_retro.png)

---

## 快速开始

### 第一步：安装

推荐直接从 PyPI 安装：

```bash
pip install resume-story
```

如果你希望参与开发或查看最新代码：

```bash
git clone https://github.com/your-username/resume-story.git
cd resume-story
pip install -e ".[dev]"
```

安装完成后，在终端输入以下命令验证是否成功：

```bash
resume-story version
```

如果看到类似 `Resume Story v0.1.0` 的输出，说明安装成功了。

### 第二步：初始化简历模板

用 `init` 命令在当前目录生成一份示例简历文件：

```bash
resume-story init
```

执行后会在当前目录创建 `resume.yaml`，里面包含了一份完整的示例简历（张明远，高级全栈工程师）。你可以用任何文本编辑器打开它，替换成自己的信息：

```bash
# macOS / Linux
open resume.yaml       # 或用 vim, nano, code 等编辑器

# Windows
notepad resume.yaml
```

你也可以指定输出文件名：

```bash
resume-story init -o my_resume.yaml
```

如果文件已存在，程序会拒绝覆盖以保护你的数据。加 `--force` 可以强制覆盖。

> **提示：** 除了 YAML，你也可以用 JSON（`.json`）、Markdown（`.md`）、纯文本（`.txt`）或 PDF（`.pdf`）格式的简历，手动创建即可。

### 第三步：生成故事

这是最核心的一步！在终端中运行：

```bash
# 离线模式（不需要任何 API Key，适合快速体验）
resume-story story resume.yaml --no-llm --open
```

这条命令会解析你的简历，生成叙事内容，渲染成 HTML 页面，并自动在浏览器中打开。

如果你想使用 LLM 获得更好的叙事效果，可以先设置 API Key：

```bash
# macOS / Linux
export LLM_API_KEY="your-api-key"

# Windows PowerShell
$env:LLM_API_KEY="your-api-key"

# 然后运行（默认启用 LLM）
resume-story story resume.yaml --open
```

### 第四步：尝试不同风格

用 `--style` 参数切换模板风格：

```bash
resume-story story resume.yaml --style dashboard --open
resume-story story resume.yaml --style minimal --open
resume-story story resume.yaml --style retro --open
resume-story story resume.yaml --style bento --open
resume-story story resume.yaml --style immersive3d --open
```

可选的风格值：`story`（默认）、`dashboard`、`immersive3d`、`minimal`、`bento`、`retro`。

---

## 完整命令参考

### `init` — 初始化简历模板

在当前目录创建一份示例简历 YAML 文件，方便你在此基础上修改。

```bash
resume-story init
resume-story init -o my_resume.yaml
resume-story init --force
```

参数说明：

| 参数 | 说明 |
|------|------|
| `-o, --output` | 输出文件路径（默认为 `resume.yaml`） |
| `-f, --force` | 如果文件已存在，强制覆盖 |

### `parse` — 解析简历

仅解析简历文件并在终端中展示结构化数据，不生成 HTML。

```bash
resume-story parse my_resume.yaml
resume-story parse my_resume.pdf --llm --api-key "your-key"
resume-story parse my_resume.md -o parsed.json
```

参数说明：

| 参数 | 说明 |
|------|------|
| `file` | 简历文件路径 |
| `-o, --output` | 将解析结果保存为 JSON 文件 |
| `--llm` | 使用 LLM 辅助规范化非结构化格式的简历 |
| `-m, --model` | 指定 LLM 模型名称 |
| `--api-key` | LLM API Key（也可通过环境变量 `LLM_API_KEY` 设置） |
| `--api-url` | LLM API URL（也可通过环境变量 `LLM_API_URL` 设置） |
| `-v, --verbose` | 显示详细日志 |

### `story` — 生成故事

完整流程：解析简历 → 生成叙事 → 渲染 HTML。

```bash
resume-story story my_resume.yaml
resume-story story my_resume.yaml --style bento --open
resume-story story my_resume.pdf --llm --model gpt-4o
resume-story story my_resume.yaml --no-llm -o output.html
```

参数说明：

| 参数 | 说明 |
|------|------|
| `file` | 简历文件路径 |
| `-o, --output` | 输出 HTML 文件路径（默认为 `简历名_story.html`） |
| `-s, --style` | 模板风格（story / dashboard / immersive3d / minimal / bento / retro） |
| `--no-llm` | 完全离线模式，不调用任何 LLM |
| `--normalize` | 仅用 LLM 规范化简历数据，故事生成使用离线引擎 |
| `-O, --open` | 生成后自动在浏览器中打开 |
| `-m, --model` | 指定 LLM 模型名称 |
| `--api-key` | LLM API Key |
| `--api-url` | LLM API URL |
| `-v, --verbose` | 显示详细日志 |

### `version` — 查看版本

```bash
resume-story version
```

---

## 支持的简历格式

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| YAML | `.yaml` / `.yml` | 推荐格式，结构清晰易编辑 |
| JSON | `.json` | 适合程序化生成 |
| PDF | `.pdf` | 直接从已有简历 PDF 解析 |
| Markdown | `.md` | 适合技术人员的写作习惯 |
| 纯文本 | `.txt` | 最基础的格式 |

对于 PDF、Markdown 和纯文本等非结构化格式，开启 `--llm` 选项可以获得更精准的解析结果。

---

## LLM 配置（可选）

Resume Story 使用 [llmdog](https://github.com/narumiruna/llmdog) 作为 LLM 调用层，兼容任何 OpenAI API 格式的服务。

通过环境变量配置（推荐）：

```bash
export LLM_API_KEY="sk-your-api-key"
export LLM_API_URL="https://api.openai.com/v1"    # 或其他兼容端点
```

也可以通过命令行参数传入：

```bash
resume-story story my_resume.yaml --api-key "sk-xxx" --api-url "https://your-api.com/v1"
```

如果不想使用 LLM，加上 `--no-llm` 即可，程序会使用内置的 fallback 引擎生成叙事内容。

---

## 从源码开发

```bash
# 克隆仓库
git clone https://github.com/your-username/resume-story.git
cd resume-story

# 安装开发依赖
pip install -e ".[dev]"

# 运行全部测试
pytest

# 代码风格检查
ruff check src/ tests/
```

项目结构：

```
resume-story/
├── src/resume_story/
│   ├── __init__.py          # 版本号
│   ├── cli.py               # 命令行入口
│   ├── resume_parser.py     # 简历解析引擎
│   ├── story_generator.py   # 叙事故事生成
│   ├── visualizer.py        # HTML 渲染
│   └── templates/           # Jinja2 模板（6 种风格）
├── tests/                   # 单元测试
├── examples/                # 示例简历文件
└── docs/                    # 文档与截图
```

---

## 常见问题

**Q：不装 Python 可以用吗？**
目前需要 Python 3.10 及以上版本。如果你还没安装 Python，推荐从 [python.org](https://www.python.org/downloads/) 下载最新版。

**Q：生成的 HTML 需要联网才能看吗？**
不需要。生成的 HTML 文件是完全独立的，所有样式和脚本都已内联。但部分模板使用了 Google Fonts 和 CDN 资源（Tailwind CSS、Three.js、ECharts），首次打开时如果有网络会加载更完整的字体效果。

**Q：`--no-llm` 和默认模式有什么区别？**
默认模式下，程序会尝试调用 LLM 生成更有叙事感的故事内容。`--no-llm` 模式完全离线，使用模板引擎和规则生成叙事，效果略逊但无需任何 API 配置。

**Q：怎么分享给别人？**
直接把生成的 `.html` 文件发给对方即可，也可以部署到 GitHub Pages、Vercel 等静态托管服务上。

---

## 许可证

MIT License
