Metadata-Version: 2.4
Name: cvbuilder-cli
Version: 0.1.1
Summary: Generate PDF resumes from Markdown with customizable styles, headers/footers, and LLM auto-formatting
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer<1.0,>=0.9
Requires-Dist: markdown<4.0,>=3.5
Requires-Dist: playwright<2.0,>=1.40
Requires-Dist: pypdf<5.0,>=3.0
Requires-Dist: llmdog
Requires-Dist: larkfunc
Requires-Dist: rich<14.0,>=13.0

# cvbuilder-cli

专业的 PDF 简历生成工具 - 将 Markdown 简历快速转换为精美 PDF 文件，支持多种样式、自定义页眉页脚、LLM 智能格式化。

## 功能特性

- 📝 **Markdown 转 PDF** - 一键生成专业简历
- 🎨 **4 种内置样式** - default / modern / classic / elegant，满足不同场景需求
- 🌐 **中英文支持** - 自动检测语言或手动指定
- 🤖 **LLM 智能格式化** - 原始文本自动转为标准简历格式
- 📋 **自定义页眉页脚** - 支持文字和图片
- ⚡ **CLI 命令行工具** - 简洁高效的工作流
- 🎯 **左对齐/右对齐布局** - 教育背景和经历的时间段自动右对齐

## 安装和环境配置

### 1. 安装 cvbuilder-cli

```bash
pip install cvbuilder-cli
```

### 2. 安装 Playwright 浏览器

cvbuilder 使用 Playwright 进行 PDF 渲染，需要安装 Chromium 浏览器：

```bash
playwright install chromium
```

### 3. （可选）配置 LLM

如果需要使用 LLM 自动格式化功能，需要配置 llmdog。详细教程请查看下方的 [LLM 配置完整教程](#llm-配置完整教程)。

## 使用示例和代码片段

### 快速开始（新手指南）

#### 第一步：初始化模板

```bash
# 创建项目目录
mkdir my-resume && cd my-resume

# 获取所有模板文件（中英文模板 + 4 种样式）
cvbuilder init
```

执行后会生成以下文件：
- `resume_zh.md` - 中文简历模板
- `resume_en.md` - 英文简历模板
- `default.css` - 默认样式
- `modern.css` - 现代样式
- `classic.css` - 经典样式
- `elegant.css` - 优雅样式

#### 第二步：编辑简历内容

用任意文本编辑器打开 `resume_zh.md`，填入你的真实信息。

**重要：教育背景和工作经历的时间段布局**

使用以下格式实现左对齐（学校/公司）+ 右对齐（时间段）：

```markdown
### <div class="edu-row"><strong>北京大学 - 计算机硕士</strong> <span>2020.09 - 2023.06</span></div>

- GPA: 3.8/4.0
- 主修课程：机器学习、分布式系统
```

渲染效果：
```
北京大学 - 计算机硕士              2020.09 - 2023.06
```

#### 第三步：生成 PDF

```bash
# 使用默认样式生成
cvbuilder build --md resume_zh.md

# 指定输出文件名
cvbuilder build --md resume_zh.md --output 张三简历.pdf

# 使用其他样式
cvbuilder build --md resume_zh.md --css elegant --output 张三简历_优雅版.pdf
```

### 进阶用法

#### 添加页眉页脚

```bash
# 文字页眉页脚
cvbuilder build --md resume_zh.md \
  --header "张三 | 电话: 138-0000-0000" \
  --footer "机密文档 - 请勿外传"

# 图片页眉
cvbuilder build --md resume_zh.md --header-image logo.png
```

#### LLM 自动格式化

如果你有原始简历文本（非 Markdown 格式），可以让 LLM 自动格式化：

```bash
# 从文本文件生成 PDF
cvbuilder format --input raw_resume.txt --output resume.pdf

# 指定语言
cvbuilder format --input raw_resume.txt --lang zh --output resume.pdf
```

#### 查看可用样式

```bash
cvbuilder styles
```

## 样式详细介绍

cvbuilder 提供 4 种精心设计的样式，每种都有独特的视觉风格：

### 1. default - 默认样式

**特色**：
- 居中标题，专业简洁
- 蓝色左侧强调线（section headers）
- 无衬线字体，通用性强

**适用场景**：
- ✅ 技术岗位简历
- ✅ 互联网行业
- ✅ 通用型简历

**使用方式**：
```bash
cvbuilder build --md resume.md --css default
```

### 2. modern - 现代风格

**特色**：
- 左对齐大标题，简约设计
- 蓝色大写字母章节标题
- 充足留白，现代感十足

**适用场景**：
- ✅ 设计师简历
- ✅ 创意行业
- ✅ 海外求职

**使用方式**：
```bash
cvbuilder build --md resume.md --css modern
```

### 3. classic - 经典风格

**特色**：
- 衬线字体（Georgia/宋体）
- 传统横线分隔
- 保守配色，正式感强

**适用场景**：
- ✅ 金融/银行行业
- ✅ 政府机关
- ✅ 学术岗位
- ✅ 传统企业

**使用方式**：
```bash
cvbuilder build --md resume.md --css classic
```

### 4. elegant - 优雅风格（NEW！）

**特色**：
- 渐变紫色强调色（#6366f1 → #818cf8）
- 渐变标题背景效果
- 卡片式区块设计
- 圆角边框，柔和视觉层次

**适用场景**：
- ✅ 高端岗位
- ✅ 管理岗位
- ✅ 希望脱颖而出的场景
- ✅ 外企/跨国公司

**使用方式**：
```bash
cvbuilder build --md resume.md --css elegant
```

## 样式配置方法

### 方法 1：使用内置样式

```bash
# 查看所有可用样式
cvbuilder styles

# 使用指定样式
cvbuilder build --md resume.md --css <样式名>
```

### 方法 2：自定义 CSS

1. 初始化获取所有样式文件：
```bash
cvbuilder init
```

2. 复制并修改任意样式文件：
```bash
cp default.css my-custom.css
# 编辑 my-custom.css，修改颜色、字体等
```

3. 使用自定义样式：
```bash
cvbuilder build --md resume.md --css my-custom.css
```

### 常用 CSS 修改示例

**修改强调色**：
```css
:root {
    --accent: #ff6b6b;  /* 改为红色 */
}
```

**修改字体**：
```css
html, body {
    font-family: "你的字体", sans-serif;
}
```

**调整页边距**：
```css
@page {
    margin: 15mm 20mm;  /* 上下 15mm，左右 20mm */
}
```

## 文本对齐格式说明

### 教育背景/工作经历布局

使用 `edu-row` 类实现左右对齐布局：

```markdown
### <div class="edu-row"><strong>左侧内容</strong> <span>右侧内容</span></div>
```

**实际效果**：
```
北京大学 - 计算机硕士              2020.09 - 2023.06
高级后端工程师 - 字节跳动           2023.07 - 至今
```

**注意事项**：
- 左侧内容使用 `<strong>` 标签，左对齐
- 右侧内容使用 `<span>` 标签，右对齐且不换行
- 中间自动填充空白
- 适用于教育背景和工作经历的时间段显示

## API 接口说明

### Python API

```python
from cvbuilder import convert

# 基本用法
convert(
    md_path="resume.md",
    css_path="resume.css",
    output="resume.pdf",
    lang="zh"  # zh / en / auto
)

# 完整参数
convert(
    md_path="resume.md",
    css_path="elegant.css",
    output="resume.pdf",
    lang="zh",
    header_text="页眉文字",
    header_image="logo.png",
    footer_text="页脚文字",
    footer_image="footer.png"
)
```

### LLM 格式化 API

```python
from cvbuilder.formatter import format_resume

# 格式化原始文本
md_content = format_resume(
    input_text="你的原始简历文本...",
    lang="zh"  # zh / en / auto
)

# 保存为 Markdown 文件
with open("resume.md", "w") as f:
    f.write(md_content)
```

## 依赖项清单

### 核心依赖

- **typer** (>=0.9, <1.0) - CLI 框架
- **markdown** (>=3.5, <4.0) - Markdown 解析
- **playwright** (>=1.40, <2.0) - 浏览器自动化（PDF 渲染）
- **pypdf** (>=3.0, <5.0) - PDF 处理
- **llmdog** - LLM 调用封装
- **larkfunc** - LLM 响应清理
- **rich** (>=13.0, <14.0) - 终端美化输出

### 系统依赖

- Python >= 3.10
- Playwright Chromium 浏览器（通过 `playwright install chromium` 安装）

## LLM 配置完整教程

本教程将指导你完成 llmdog 的配置，让你能够使用 LLM 智能格式化功能。

### 什么是 llmdog？

llmdog 是一个 LLM 调用封装库，cvbuilder 使用它来调用大语言模型（如 DeepSeek、OpenAI 等），将你的原始简历文本自动格式化为标准的 Markdown 简历格式。

### 配置前准备

在开始配置之前，你需要：

1. **获取 API Key** - 从 LLM 服务提供商获取 API 密钥
   - DeepSeek: https://platform.deepseek.com/
   - OpenAI: https://platform.openai.com/
   - 其他支持 OpenAI 兼容 API 的服务

2. **确认 API 地址** - 不同服务商的 API 地址不同
   - DeepSeek: `https://api.deepseek.com/v1/chat/completions`
   - OpenAI: `https://api.openai.com/v1/chat/completions`

### 第一步：生成配置文件示例

在项目根目录执行以下命令：

```bash
cvbuilder llm-config
```

执行后会生成 `.llmdog.yaml.example` 文件，内容如下：

```yaml
# llmdog 配置文件
# 将此文件复制为 .llmdog.yaml 并填入真实配置
api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
api_url: https://api.deepseek.com/v1/chat/completions
model: deepseek-chat
timeout: 60
verify_ssl: true
```

### 第二步：创建配置文件

复制示例文件为实际配置文件：

```bash
cp .llmdog.yaml.example .llmdog.yaml
```

### 第三步：编辑配置文件

用任意文本编辑器打开 `.llmdog.yaml`，修改为你的真实配置：

```yaml
# .llmdog.yaml - LLM 配置文件

# 【必填】API Key - 从服务商处获取
api_key: sk-your-real-api-key-here

# 【必填】API 地址 - 根据你使用的服务修改
api_url: https://api.deepseek.com/v1/chat/completions

# 【必填】模型名称 - 根据你使用的服务修改
model: deepseek-chat

# 【可选】超时时间（秒）- 默认 60 秒
timeout: 60

# 【可选】是否验证 SSL 证书 - 默认 true
verify_ssl: true
```

### 配置文件参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `api_key` | string | ✅ | 无 | 你的 API 密钥，从 LLM 服务商获取 |
| `api_url` | string | ✅ | 无 | API 请求地址，不同服务商地址不同 |
| `model` | string | ✅ | 无 | 使用的模型名称 |
| `timeout` | int | ❌ | 60 | 请求超时时间（秒） |
| `verify_ssl` | bool | ❌ | true | 是否验证 SSL 证书 |

### 常见服务商配置示例

#### DeepSeek（推荐）

```yaml
api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
api_url: https://api.deepseek.com/v1/chat/completions
model: deepseek-chat
timeout: 60
verify_ssl: true
```

#### OpenAI

```yaml
api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
api_url: https://api.openai.com/v1/chat/completions
model: gpt-4o
timeout: 60
verify_ssl: true
```

#### 其他兼容 OpenAI API 的服务

```yaml
api_key: your-api-key
api_url: https://your-api-domain.com/v1/chat/completions
model: your-model-name
timeout: 60
verify_ssl: true
```

### 配置优先级顺序

cvbuilder 按照以下顺序查找配置文件（优先级从高到低）：

1. **项目根目录** - `./llmdog.yaml`（当前工作目录）
2. **家目录** - `~/.llmdog.yaml`（用户主目录）
3. **环境变量** - 通过 `.env` 文件设置
4. **默认配置** - 使用内置默认值

**示例**：

```bash
# 优先级 1：项目级配置（推荐）
./your-project/.llmdog.yaml

# 优先级 2：全局配置（所有项目共享）
~/.llmdog.yaml  # Linux/macOS: /home/user/.llmdog.yaml
                # Windows: C:\Users\user\.llmdog.yaml

# 优先级 3：环境变量配置
echo "LLMDOG_API_KEY=sk-xxx" >> .env
```

**建议**：
- ✅ 每个项目使用独立的 `.llmdog.yaml`（优先级 1）
- ✅ 多台电脑共享配置可使用家目录配置（优先级 2）
- ❌ 避免在代码中硬编码 API Key

### 安全注意事项 ⚠️

**重要：保护你的 API Key！**

1. **加入 .gitignore**

   绝对不要将 `.llmdog.yaml` 提交到 Git 仓库！

   ```bash
   # 在项目根目录创建或编辑 .gitignore 文件
   echo ".llmdog.yaml" >> .gitignore
   ```

2. **检查是否已忽略**

   ```bash
   # 检查文件是否被 Git 跟踪
   git status

   # 如果显示 .llmdog.yaml，立即移除
   git rm --cached .llmdog.yaml
   ```

3. **权限设置**（Linux/macOS）

   ```bash
   # 设置文件仅所有者可读写
   chmod 600 .llmdog.yaml
   ```

4. **不要分享给他人**

   - API Key 等同于密码
   - 泄露可能导致费用损失
   - 定期更换 API Key

5. **使用环境变量（可选）**

   对于团队协作，可以使用环境变量：

   ```bash
   # 在 .env 文件中设置（也需加入 .gitignore）
   echo "LLMDOG_API_KEY=sk-xxx" >> .env
   echo ".env" >> .gitignore
   ```

### 验证配置

配置完成后，测试是否成功：

```bash
# 方法 1：使用 format 命令测试
cvbuilder format --input test_resume.txt --output test.pdf

# 方法 2：查看配置是否被正确读取
cat .llmdog.yaml
```

如果配置正确，应该能成功生成 PDF。

### 常见问题解答（FAQ）

#### Q1: 提示 "LLM 返回空响应" 怎么办？

**A**: 可能原因：
1. API Key 错误 - 检查是否正确复制
2. API 地址错误 - 确认 URL 格式
3. 网络问题 - 检查网络连接
4. 余额不足 - 确认账户有足够余额

**解决步骤**：
```bash
# 1. 检查配置文件
cat .llmdog.yaml

# 2. 测试 API 连接（使用 curl）
curl -X POST https://api.deepseek.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "Hello"}]}'
```

#### Q2: 可以使用免费的 LLM 吗？

**A**: 可以！以下是一些免费选项：
- DeepSeek: 注册即送免费额度
- OpenAI: 新用户有免费额度
- 本地部署: Ollama、LM Studio 等

#### Q3: 如何切换不同的 LLM 服务商？

**A**: 修改 `.llmdog.yaml` 中的 `api_url` 和 `model`：

```yaml
# 从 DeepSeek 切换到 OpenAI
api_url: https://api.openai.com/v1/chat/completions
model: gpt-4o
```

#### Q4: 多个项目需要不同配置怎么办？

**A**: 每个项目创建独立的 `.llmdog.yaml`：

```bash
# 项目 A
project-a/.llmdog.yaml  # 使用 DeepSeek

# 项目 B
project-b/.llmdog.yaml  # 使用 OpenAI
```

#### Q5: 配置后仍然无法使用？

**A**: 按以下步骤排查：

1. **检查文件位置**
   ```bash
   # 确认配置文件在当前目录
   ls -la .llmdog.yaml
   ```

2. **检查 YAML 格式**
   - 使用空格，不要使用 Tab
   - 键值对用冒号分隔
   - 字符串不需要引号（除非包含特殊字符）

3. **查看错误日志**
   ```bash
   # 使用 verbose 模式运行
   cvbuilder format --input test.txt --output test.pdf -v
   ```

4. **联系支持**
   - 提交 Issue 到 GitHub
   - 附上错误信息（隐藏 API Key）

### 快速配置清单

- [ ] 获取 API Key
- [ ] 运行 `cvbuilder llm-config`
- [ ] 复制 `.llmdog.yaml.example` 为 `.llmdog.yaml`
- [ ] 编辑 `.llmdog.yaml`，填入真实配置
- [ ] 将 `.llmdog.yaml` 加入 `.gitignore`
- [ ] 测试配置是否成功

完成以上步骤后，你就可以使用 `cvbuilder format` 命令享受 LLM 智能格式化功能了！

## 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 开发环境设置

```bash
# 克隆仓库
git clone <repository-url>
cd cvbuilder

# 安装开发依赖
pip install -e .

# 安装 Playwright
playwright install chromium
```

### 提交 Pull Request

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 遵循 PEP 8 编码规范
- 使用 type hints
- 添加必要的注释

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件
