内容
# 量身定制 — AI 简历和求职信生成器
量身定制是一款本地网页应用，能够将职位发布的 URL 转化为定制化、结构良好的简历和求职信。你可以维护一个 **主配置文件** — 你所有的经历，以 JSON 结构保存 — 量身定制会为每个职位 *选择、重新排序和强调* 相关内容。它绝不会捏造任何信息（参见 [真实性](#真实性)）。
## 亮点
- **在数据层强制执行真实性，而不是在提示中。** 大多数 AI 简历工具都会礼貌地要求模型不要夸大。量身定制会拒绝任何生成的简历，其中包含的雇主、职称、日期、学位或认证不在你的主配置文件中 — 这是在写入路径上的结构性检查，因此保证无论哪个 AI 生成的文本都有效。
- **两种提供智能的方式，一份合同。** 使用内置的Anthropic API 管道（粘贴一批职位 URL 然后离开），或者通过 MCP 连接你自己的代理 — 一个从头开始的 MCP 服务器（10 个工具），允许 Claude Code、Codex 或任何支持 MCP 的客户端在自己的订阅上工作，无需 API 密钥，并且可以读取登录墙后投稿的浏览器可以访问的页面。相同的真实性保证适用于两者。
- **你的代码库成为简历证据。** 一个投资组合扫描提示加上一个 MCP 编写工具，允许代理读取你工作区中的仓库，并直接在你的配置文件中编写有证据支持、技能标记的项目条目（仅添加、验证，绝不破坏）。
- **为非工程师打造。** 双击启动器（Windows `.bat` + Unix `.sh`）在第一次运行自安装，完全离线演示模式不需要 API 密钥，四个打印调优模板导出 PDF / HTML / ATS 纯文本，暗色模式，以及一个前端构建提交，因此克隆只需要 Python。
- **它跟踪求职过程，而不仅仅是生成。** 从保存到 Offer 的阶段，一个有日期的时间线用于回调、面试和笔记，存档和永久删除，以及你可以免费停放的已保存工作岗位，可以稍后生成。
- **工程化，而不是凭感觉编码。** 规格 → 实现计划 → 测试驱动开发，每个任务独立审查。244 个自动化测试（192 个后端包括真正的无头 Chromium PDF 渲染，52 个前端），并针对实时 Anthropic API 进行端到端验证 — 通过这种方式发现并修复了两个仅 API 的错误。
职位 URL 可以排队等待立即生成，也可以作为已保存的工作岗位免费停放，以后无需额外成本即可生成。对于你选择的每个职位 URL，它都会运行一个四阶段的流程：
1. **获取** — 下载帖子并提取文本（用于登录墙站点的粘贴后备）。
2. **研究** — 解析帖子；可选地研究公司（每个工作岗位的深度可调，见下文）。
3. **定制** — Claude (`claude-opus-4-8`) 选择并强调你的主配置文件中最相关的部分，并撰写一封匹配的求职信。
4. **渲染** — 四个打印调优模板（Meridian、Slate、Terminal、Signal）→ PDF、独立 HTML 和 ATS 安全纯文本。
在应用内 **模板** 页面上以并排方式比较所有四个模板，并提供实时预览。用户界面还会自动跟随系统的浅色/深色偏好，并在导航栏或设置中提供一键式覆盖。
拥有自己的代码仓库吗？使用 [投资组合扫描提示](docs/portfolio-scan-prompt.md) 与 Claude Code（或任何有能力的编码代理）将你的实际代码库转化为有证据支持的项目材料添加到你的主配置文件中。
所有操作都在你的机器上运行。唯一的网络流量是获取帖子和调用 Anthropic API。所有状态都存放在 `data/` 文件夹中 — 备份只需复制一个文件夹。
## 快速入门（Windows）
1. 从 [python.org](https://www.python.org/downloads/) 安装 **Python 3.11+** — 在第一个安装屏幕上，**勾选 "Add python.exe to PATH"**。
2. 克隆或下载此仓库，然后在项目文件夹中双击 **`Tailored.bat`**。
第一次启动会为你完成设置 — 创建虚拟环境、安装依赖项、下载用于 PDF 导出的 Chromium 浏览器 — 需要几分钟。之后的每次启动只需几秒钟。
如果你还没有 [Anthropic API 密钥](https://console.anthropic.com/)，启动器会提供一个 **演示模式**，使用样本数据 — 无需密钥或网络访问。
## 快速入门（macOS / Linux）
你需要 **Python 3.11+** （使用 `python3 --version` 检查，或通过包管理器 / [python.org](https://www.python.org/downloads/) 安装）。
```bash
git clone <此仓库的URL> tailored
cd tailored
bash start_tailored.sh
```
与 Windows 类似：第一次运行会设置所有内容（几分钟），后续运行立即完成，如果你还没有 API 密钥，脚本会提供一个不需要密钥的 **演示模式**。
## 手动设置（开发者）
这是 `Tailored.bat` / `start_tailored.sh` 自动执行的内容。适用于开发、使用不支持的操作系统或需要完全手动控制的情况。
你需要 **Python 3.11+** 和 [Anthropic API 密钥](https://console.anthropic.com/)。 Node.js **不需要** — 内置的前端已经提交。
```bash
git clone <此仓库的URL> tailored
cd tailored
python -m venv .venv
.venv\Scripts\activate # Windows （macOS/Linux: source .venv/bin/activate）
pip install -r requirements.txt
playwright install chromium
copy .env.example .env # macOS/Linux: cp .env.example .env
```
编辑 `.env` 并设置你的密钥：
```
ANTHROPIC_API_KEY=sk-ant-...
```
然后启动：
```
python run.py
```
服务器启动在 http://127.0.0.1:8547，浏览器会自动打开。
### 使用你自己的 AI 代理代替 API（MCP 模式）
量身定制附带了一个 MCP 服务器（`backend/mcp_server.py`），允许任何支持 MCP 的代理 — Claude Code、Codex CLI 和其他 — 代替内置的 Anthropic API 管道作为智能。你编码代理的订阅会进行思考，因此 **无需 API 密钥**，并且由于代理使用自己的浏览器/工具获取帖子，因此它可以读取登录墙帖子，而应用程序的获取器无法读取。
使用一行命令在 Claude Code 中注册它（用克隆的绝对路径替换两个路径 — 任何支持 MCP 的代理都可以注册相同的命令）：
```bash
claude mcp add tailored -- "<绝对路径>\.venv\Scripts\python.exe" "<绝对路径>\backend\mcp_server.py"
```
然后要求你的代理阅读量身定制的流程指南（`get_workflow_guide` 工具），然后：
> 为我定制 <职位 URL> 的个人简历
代理会读取你的主配置文件，获取并分析帖子，可选地研究公司，并将定制的简历和求职信写回量身定制，后者会渲染与内置管道相同的 PDF/HTML/ATS 导出。 [真实性保证](#真实性) 也适用于代理 — 它在写入路径上在服务器端强制执行，因此连接的代理无法保存捏造的雇主、职称、日期、学位或认证；它会收到违规列表并必须纠正简历。参见 [docs/EXTENDING.md](docs/EXTENDING.md) 以获取完整的工具合同。MCP 驱动的应用程序在代理保存之前停留在 `tailoring` 状态，这会阻止该行的 Web UI 粘贴/重新生成/编辑操作，直到您保存或删除，并且相反，MCP 保存会在内置管道正在处理同一应用程序时被拒绝。
同一个连接的代理也可以将你的工作区项目直接导入到你的主配置文件中：运行 [投资组合扫描提示](docs/portfolio-scan-prompt.md)，代理会通过 `add_profile_evidence` 工具将验证后的发现写回（仅添加，不会覆盖你已经拥有的内容）。
## 演示模式（无 API 密钥，完全离线）
`Tailored.bat` / `start_tailored.sh` 在找不到密钥时自动提供此功能。要手动设置（例如上面的手动设置）：设置 `TAILORED_FAKE=1`：
```bash
# Windows PowerShell
$env:TAILORED_FAKE = "1"; python run.py
# macOS / Linux
TAILORED_FAKE=1 python run.py
```
演示模式会植入一个样本配置文件和一个已完成的应用程序，并从离线固定装置中回答每个 AI 调用。每个屏幕都是可点击的，从头到尾。
## 研究深度 = 成本调节
研究深度在添加每个工作岗位时选择。每个应用程序的大致成本（Claude Opus 4.8；实际令牌使用量和成本按应用程序记录并在每个应用程序的页面上显示）：
| 深度 | 它执行的操作 | 大约成本 |
|------------|---------------------------------------------------------------------|--------------|
| `quick` | 仅解析帖子 | $0.15-0.30 |
| `standard` | + 获取公司自己的网站（使命、产品、价值观） | $0.30-0.60 |
| `deep` | + 网络搜索：最近的新闻、产品、技术栈和文化信号 | $1-3 |
## 真实性
量身定制是一个 *选择和强调* 问题，而不是发明。生成器可能会重新排序、重新加权和重新措辞你的项目符号，以匹配帖子的词汇 — 但前提是你的主配置文件中有事实支持。它绝不会捏造雇主、职称、日期、学位、认证、工具或指标。这在两个方面得到强制执行：在提示词条中，在每次生成后在结构上 — 生成的简历上的每个雇主、职称、日期范围、学位和认证都必须与你的主配置文件完全匹配，否则应用程序会进入错误状态而不是发送伪造内容。重新生成是版本控制的，因此早期输出永远不会丢失。
## 开发
### 前端（仅开发需要 Node）
```bash
cd frontend
npm install
npm run dev # Vite 开发服务器；代理 /api 到 http://127.0.0.1:8547
```
在 `npm run dev` 的同时运行后端（`python run.py`）。 **提交 UI 更改前，请重建捆绑包** — `frontend/dist/` 已提交，因此最终用户不需要 Node：
```bash
npm run build
```
### 测试
```bash
pytest -m "not pdf" # 快速套件（无 Chromium）
pytest # 完整套件，包括 Playwright PDF 测试
cd frontend; npm test # 前端测试
```
测试从不调用真正的 Anthropic API — Claude 包装器有一个固定装置支持的假模（与演示模式使用的相同）。
## 项目布局
```
tailored/
├── Tailored.bat # 双击启动器（Windows）
├── start_tailored.sh # 启动脚本（macOS/Linux：bash start_tailored.sh）
├── run.py # 一键启动器（服务器 + 浏览器）
├── requirements.txt
├── .env.example
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI 应用；提供 API + 内置前端
│ │ ├── config.py # 环境 / 设置
│ │ ├── db.py # SQLite 引擎 + 会话
│ │ ├── models.py # SQLModel 实体
│ │ ├── schemas.py # Pydantic 模式（简历 JSON 合同）
│ │ ├── services/ # claude, intake, fetcher, research, tailor, render, pipeline
│ │ ├── api/ # REST 路由
│ │ └── fixtures/ # 离线固定装置（测试 + 演示模式）
│ └── templates/ # meridian/ slate/ terminal/ signal/ + 求职信
├── frontend/ # React + Vite + TypeScript（dist/ 已提交）
├── tests/
└── data/ # gitignored: SQLite db, exports/, settings.json
```
## 已知限制
- 仪表板轮询在一次状态获取失败后停止，直到刷新。
- 在简历编辑器打开时重新生成可能会让旧保存覆盖新版本。
- 项目符号在配置文件编辑器中不可编辑（保存时保留）。
- 打印导出的 resume.html 时始终使用 Letter（PDF 导出会遵守页面大小设置）。
- 标准深度研究仅在从帖子中检测到公司域时受限。
- 失败生成的令牌支出不计入显示的成本。
## 故障排除
- **LinkedIn 或其他登录墙帖子** — 阻止机器人的网站会使应用程序进入 **"需要粘贴"** 状态（不是错误）。打开应用程序，将帖子文本粘贴到提示中，管道会恢复正常。
- **Playwright 浏览器丢失** （`Executable doesn't exist` 或类似）— `Tailored.bat` / `start_tailored.sh` 在第一次运行自动安装此项（如果失败则打印警告，但不阻止应用程序的其他部分）。如果你正在进行手动设置，或者自动安装失败，请自己安装一次：`playwright install chromium`。
- **端口已被占用** — 量身定制默认为端口 8547。如果是量身定制本身已经运行，`run.py` 会检测到它并直接打开你的浏览器，而不是报错。否则，在 `.env` 中设置 `TAILORED_PORT` （例如 `TAILORED_PORT=8600`）并重启。
- **缺少 API 密钥** — 应用程序仍然运行；生成操作将提示你。 在 `.env` 中设置 `ANTHROPIC_API_KEY`，或使用演示模式（`TAILORED_FAKE=1`）。
