@studyllm/resume-preview 0.0.0-stage → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +318 -0
- package/README.md +313 -2
- package/build/constants.js +217 -0
- package/build/diagram-service.js +143 -0
- package/build/file-utils.js +350 -0
- package/build/handlers.js +172 -0
- package/build/html-utils.js +20 -0
- package/build/i18n.js +198 -0
- package/build/index.js +171 -0
- package/build/live-server.js +488 -0
- package/build/logger.js +92 -0
- package/build/mermaid-cli.js +48 -0
- package/build/page-renderer.js +152 -0
- package/build/preview/favicon.svg +23 -0
- package/build/preview/gallery.css +217 -0
- package/build/preview/gallery.html +59 -0
- package/build/preview/gallery.js +259 -0
- package/build/preview/i18n/en.json +57 -0
- package/build/preview/i18n/zh-CN.json +57 -0
- package/build/preview/i18n.js +125 -0
- package/build/preview/resume-template.html +13 -0
- package/build/preview/resume.css +214 -0
- package/build/preview/resume.js +393 -0
- package/build/preview/shared.css +529 -0
- package/build/resume-renderer.js +486 -0
- package/build/resume-service.js +117 -0
- package/build/routes.js +335 -0
- package/build/serve.js +46 -0
- package/build/types.js +5 -0
- package/package.json +63 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 studyllm
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
# Resume Preview MCP Server
|
|
2
|
+
|
|
3
|
+
[简体中文](README.md) | **English**
|
|
4
|
+
|
|
5
|
+
MCP server that turns structured resume content into a live A4 page in your browser — refine the wording while the page keeps up, no export-and-restart cycle.
|
|
6
|
+
|
|
7
|
+
MIT licensed, works with any MCP client.
|
|
8
|
+
|
|
9
|
+
## ✨ Features
|
|
10
|
+
|
|
11
|
+
- 🔄 **Live Reload** - The open tab refreshes by itself every time the content changes
|
|
12
|
+
- 📐 **A4 Layout** - The resume is rendered as a real A4 page, in the browser and in the PDF
|
|
13
|
+
- 📤 **Two Export Formats** - Export to PDF or to a standalone HTML document
|
|
14
|
+
- 🧩 **Structured Content Model** - Sections you leave out are simply omitted from the page
|
|
15
|
+
- 🔤 **Plain Text, Always** - Content is escaped; HTML tags and scripts in it are never interpreted
|
|
16
|
+
- 🗂️ **Multiple Resumes** - One `resume_id` per resume, each with its own tab and its own slug
|
|
17
|
+
- 💾 **Persistent Working Files** - Resumes are stored under `~/.config/resume-preview/resumes`
|
|
18
|
+
- 🖥️ **Standalone Gallery** - `resume-preview --serve` opens a browser gallery of every stored resume, with search and delete
|
|
19
|
+
- 🌍 **Two Independent Languages** - The page chrome follows the browser's language; the resume's own language is set per resume and decides the section headings and the exported document
|
|
20
|
+
- 🔎 **Review Tools** - Zoom, pan and export straight from the preview page, with a live connection indicator and a "last updated" stamp
|
|
21
|
+
- 🤖 **Built-in Skill** - The plugin ships a `resume` skill with the content model and wording guidance
|
|
22
|
+
|
|
23
|
+
## Architecture
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
Both chains share the same code paths:
|
|
28
|
+
|
|
29
|
+
- **Preview** — `resume_preview` → layer by layer → the rendered result lands in `resumes/` → `live-server.ts` notices the change and pushes `reload` over the WebSocket
|
|
30
|
+
- **Export** — `resume_export` → the same rendering → written to `save_path`
|
|
31
|
+
|
|
32
|
+
The module and interface inventory lives in [`docs/api-list.md`](docs/api-list.md).
|
|
33
|
+
|
|
34
|
+
## 🚀 Quick Start
|
|
35
|
+
|
|
36
|
+
> **Release status**: the npm package `@studyllm/resume-preview` is **not published yet**
|
|
37
|
+
> (`npm view @studyllm/resume-preview` returns 404), so neither `npm install -g @studyllm/resume-preview` nor the
|
|
38
|
+
> plugin's `npx` launcher works at the moment. The GitHub repository
|
|
39
|
+
> `studyllm/resume-preview` does exist — clone it, run `npm install && npm run build`, and wire it
|
|
40
|
+
> up with the `.mcp.json` below.
|
|
41
|
+
|
|
42
|
+
**Plugin install (recommended)**
|
|
43
|
+
|
|
44
|
+
> **Type in Claude Code** — the two lines below are slash commands, not shell commands.
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
/plugin marketplace add studyllm/resume-preview
|
|
48
|
+
/plugin install resume-preview@resume-preview
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Then restart Claude Code to activate the plugin.
|
|
52
|
+
|
|
53
|
+
**Install from source**
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
git clone https://github.com/studyllm/resume-preview.git
|
|
57
|
+
cd resume-preview
|
|
58
|
+
npm install && npm run build && npm install -g .
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
After a local checkout, connect it with a `.mcp.json` like this:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"resume-preview": {
|
|
67
|
+
"command": "node",
|
|
68
|
+
"args": ["build/index.js"]
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**Verify the installation**
|
|
75
|
+
|
|
76
|
+
Plugin install: the MCP server is configured automatically — just run `/mcp` in Claude Code and check that `resume-preview` shows up in the server list.
|
|
77
|
+
|
|
78
|
+
Install from source: register it manually and check:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
claude mcp add --scope user resume-preview resume-preview
|
|
82
|
+
claude mcp list
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
You should see `resume-preview: resume-preview - ✓ Connected`
|
|
86
|
+
|
|
87
|
+
## 💡 Usage
|
|
88
|
+
|
|
89
|
+
Just ask for a resume. When installed as a plugin, the built-in `resume` skill gives your AI client the content model, the preview-iterate-export workflow, and the pitfalls worth avoiding.
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
"Write a backend engineer resume and preview it" // the A4 page opens
|
|
93
|
+
"Make the summary shorter and more concrete" // the same tab refreshes
|
|
94
|
+
"Export the resume as PDF to ./docs/resume.pdf" // the other exit of the same resume
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Every revision of the same resume reuses the **same** `resume_id`: the open tab is refreshed instead of a second one being opened. Use a different `resume_id` for a different resume — one per job you are applying to, for example.
|
|
98
|
+
|
|
99
|
+
### Content Model
|
|
100
|
+
|
|
101
|
+
A resume is a JSON object. Only `basics.name` is required — every section you leave out is simply omitted from the page:
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"basics": {
|
|
106
|
+
"name": "Alex Morgan",
|
|
107
|
+
"title": "Senior Backend Engineer",
|
|
108
|
+
"email": "alex@example.com",
|
|
109
|
+
"phone": "+1 555-0100",
|
|
110
|
+
"location": "Shanghai",
|
|
111
|
+
"links": [{ "label": "GitHub", "url": "https://github.com/example" }]
|
|
112
|
+
},
|
|
113
|
+
"summary": "Six years of backend experience, focused on high-traffic services and data pipelines.",
|
|
114
|
+
"experience": [
|
|
115
|
+
{
|
|
116
|
+
"company": "Northwind Systems",
|
|
117
|
+
"title": "Senior Backend Engineer",
|
|
118
|
+
"start": "2023.07",
|
|
119
|
+
"end": "Present",
|
|
120
|
+
"location": "Shanghai",
|
|
121
|
+
"highlights": [
|
|
122
|
+
"Rebuilt the order system, cutting p99 latency from 800ms to 180ms",
|
|
123
|
+
"Introduced a cell-based release process, shortening rollback from 20 minutes to 2"
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
],
|
|
127
|
+
"projects": [
|
|
128
|
+
{
|
|
129
|
+
"name": "Realtime Data Platform",
|
|
130
|
+
"role": "Tech Lead",
|
|
131
|
+
"period": "2024.01 - 2024.09",
|
|
132
|
+
"highlights": ["Designed a streaming ETL pipeline handling 2B events per day"]
|
|
133
|
+
}
|
|
134
|
+
],
|
|
135
|
+
"education": [
|
|
136
|
+
{
|
|
137
|
+
"school": "Northwind University",
|
|
138
|
+
"degree": "BSc Computer Science",
|
|
139
|
+
"period": "2016.09 - 2020.06",
|
|
140
|
+
"highlights": ["GPA 3.7 / 4.0"]
|
|
141
|
+
}
|
|
142
|
+
],
|
|
143
|
+
"skills": [
|
|
144
|
+
{ "category": "Backend", "items": ["Go", "Java", "PostgreSQL", "Kafka"] },
|
|
145
|
+
{ "category": "Infrastructure", "items": ["Kubernetes", "Terraform"] }
|
|
146
|
+
],
|
|
147
|
+
"extras": [{ "label": "Certificates", "items": ["PMP"] }]
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
The `content` parameter accepts this object directly or as a JSON string holding the same object.
|
|
152
|
+
`start` and `end` are free-form strings (`"2023.07"`, `"Present"`); the page joins them with a short dash.
|
|
153
|
+
|
|
154
|
+
### Section Order and Headings
|
|
155
|
+
|
|
156
|
+
The order of the sections is fixed:
|
|
157
|
+
|
|
158
|
+
> Summary → Experience → Projects → Education → Skills → Extras
|
|
159
|
+
|
|
160
|
+
A section that is missing from the content is left out of the page — it is never rendered empty.
|
|
161
|
+
|
|
162
|
+
The headings follow the resume's own `locale`, not the browser's: `en` gives the headings above, `zh-CN` gives 自我评价 / 工作经历 / 项目经历 / 教育经历 / 专业技能 / 其他. The exported document always comes out in the language you set, no matter who opens it.
|
|
163
|
+
|
|
164
|
+
## 🔌 Other MCP Client Configurations
|
|
165
|
+
|
|
166
|
+
This server is optimized for Claude Code, but it works with any MCP-compatible client.
|
|
167
|
+
|
|
168
|
+
The configuration is the same for every client — add this to the client's MCP configuration file:
|
|
169
|
+
|
|
170
|
+
> **Your client's MCP configuration**
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
{
|
|
174
|
+
"mcpServers": {
|
|
175
|
+
"resume-preview": {
|
|
176
|
+
"command": "resume-preview"
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
<details>
|
|
183
|
+
<summary><strong>Where each client keeps its configuration</strong></summary>
|
|
184
|
+
|
|
185
|
+
- **Codex** — `~/.codex/mcp_settings.json`
|
|
186
|
+
- **Cursor** — `.cursor/mcp.json`, or Settings (Cmd/Ctrl + ,) → MCP Servers
|
|
187
|
+
- **VSCode with [Cline extension](https://github.com/cline/cline)** — Settings (Cmd/Ctrl + ,) → search for "Cline MCP" → MCP Settings JSON
|
|
188
|
+
- **Windsurf** — macOS `~/Library/Application Support/Windsurf/mcp.json`; Linux `~/.config/windsurf/mcp.json`; Windows `%APPDATA%\Windsurf\mcp.json`
|
|
189
|
+
- **Gemini CLI** — `~/.gemini/mcp.json`
|
|
190
|
+
|
|
191
|
+
Every other MCP-compatible client uses the same configuration.
|
|
192
|
+
|
|
193
|
+
</details>
|
|
194
|
+
|
|
195
|
+
Two clients can also be configured from the command line:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
codex mcp add resume-preview resume-preview
|
|
199
|
+
gemini config mcp add resume-preview --command resume-preview
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The command `resume-preview` should be available in your PATH after installation.
|
|
203
|
+
|
|
204
|
+
**Note:** Some clients may require the full path to the executable:
|
|
205
|
+
|
|
206
|
+
- Find the path: `which resume-preview` (Unix/macOS) or `where resume-preview` (Windows)
|
|
207
|
+
- Use absolute path in config: `"command": "/path/to/resume-preview"`
|
|
208
|
+
|
|
209
|
+
## 🎯 Live Reload
|
|
210
|
+
|
|
211
|
+
1. **First render:** the resume opens in the browser at `http://localhost:3737/resume/<slug>`
|
|
212
|
+
2. **Make changes:** the AI client updates the content and calls `resume_preview` with the same `resume_id`
|
|
213
|
+
3. **Auto-refresh:** the browser notices the change over the WebSocket and reloads
|
|
214
|
+
4. **Status indicator:** green dot = connected, red dot = reconnecting
|
|
215
|
+
|
|
216
|
+
The live server uses ports 3737-3747 and picks an available one automatically. The page toolbar also offers zoom, pan, and a button to download the PDF or HTML directly.
|
|
217
|
+
|
|
218
|
+
> The server binds to `127.0.0.1` only and has **no authentication**. A resume holds personal data, so never expose the port to your LAN or the internet.
|
|
219
|
+
|
|
220
|
+
## 🖥️ Standalone Server
|
|
221
|
+
|
|
222
|
+
With the `--serve` flag you can start the preview server without an AI agent:
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
resume-preview --serve
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
It opens the resume gallery in your browser with every resume rendered so far. The gallery shows each resume's last-updated time and file size, lets you **search by id**, and lets you **delete** the ones you no longer need.
|
|
229
|
+
|
|
230
|
+
## 🛠️ Development
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
# Install dependencies
|
|
234
|
+
npm install
|
|
235
|
+
|
|
236
|
+
# Build the project
|
|
237
|
+
npm run build
|
|
238
|
+
|
|
239
|
+
# Run the tests
|
|
240
|
+
npm test
|
|
241
|
+
|
|
242
|
+
# Watch mode for development
|
|
243
|
+
npm run dev
|
|
244
|
+
|
|
245
|
+
# Start the MCP server directly
|
|
246
|
+
npm start
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
## ❓ FAQ
|
|
250
|
+
|
|
251
|
+
**Where are resumes stored?** Under `~/.config/resume-preview/resumes/<slug>/` — the directory name is a slug derived from the `resume_id`, so a Chinese id such as `小王的简历` becomes something like `r-3f9a2b`.
|
|
252
|
+
|
|
253
|
+
**Which languages are supported?** Two, and they are independent of each other. The **page chrome** — the gallery, the toolbar, the dialogs — follows the request: `?lang=en` wins, then the browser's `Accept-Language`, then `zh-CN`. The **resume itself** — the section headings and the exported document — follows the `locale` you pass to `resume_preview`, which is stored with the resume and defaults to `zh-CN`. The export language never depends on the browser, so the same resume always exports the same way.
|
|
254
|
+
|
|
255
|
+
**Can the content contain HTML?** No, and deliberately so. Every value is escaped and printed as text, so markup shows up literally instead of being interpreted. Write plain text — this is the largest XSS surface of the product and it stays closed.
|
|
256
|
+
|
|
257
|
+
**Are there more templates or themes?** Not yet — `default` is the only template and the only theme implemented today. Both are whitelists in `src/constants.ts` (`RESUME_TEMPLATES` / `RESUME_THEMES`), so adding one is a matter of extending those lists and adding the matching resource.
|
|
258
|
+
|
|
259
|
+
## 📝 Troubleshooting
|
|
260
|
+
|
|
261
|
+
**The server is not connecting:**
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
# Check if the server is installed
|
|
265
|
+
resume-preview -v
|
|
266
|
+
|
|
267
|
+
# Reinstall if needed
|
|
268
|
+
npm install -g @studyllm/resume-preview
|
|
269
|
+
|
|
270
|
+
# Verify the MCP configuration
|
|
271
|
+
claude mcp list
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
**Permission denied error:**
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
# Make sure the binary is executable
|
|
278
|
+
chmod +x $(which resume-preview)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
**Port already in use:**
|
|
282
|
+
|
|
283
|
+
The server uses ports 3737-3747 and picks an available one automatically. Check whether something else is holding them:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
lsof -i :3737-3747
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
**The resume does not render, or live reload does not work:**
|
|
290
|
+
|
|
291
|
+
The server logs to `~/.config/resume-preview/logs/` — `mcp.log` records tool calls and resume rendering, `web.log` records HTTP/WebSocket connections and live reload.
|
|
292
|
+
|
|
293
|
+
The log level is read from the `CLAUDE_MERMAID_LOG_LEVEL` environment variable — `DEBUG`, `INFO` (default), `WARN`, `ERROR`, `OFF`. The name is a historical leftover and is kept unchanged. Set it to `DEBUG` for more detail:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
tail -f ~/.config/resume-preview/logs/mcp.log
|
|
297
|
+
tail -f ~/.config/resume-preview/logs/web.log
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
**`Cannot find package 'puppeteer'`:** Chromium most likely did not come along with the install. Run `npm install -g @studyllm/resume-preview` again, or download the browser once with `npx puppeteer browsers install chrome`.
|
|
301
|
+
|
|
302
|
+
## 🤝 Contributing
|
|
303
|
+
|
|
304
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
305
|
+
|
|
306
|
+
## 🔗 Links
|
|
307
|
+
|
|
308
|
+
- [GitHub Repository](https://github.com/studyllm/resume-preview)
|
|
309
|
+
- [npm Package](https://www.npmjs.com/package/@studyllm/resume-preview)
|
|
310
|
+
- [Claude Code Documentation](https://docs.claude.com/claude-code)
|
|
311
|
+
- [MIT License](LICENSE)
|
|
312
|
+
|
|
313
|
+
## Upstream Project
|
|
314
|
+
|
|
315
|
+
This repository was renamed from `claude-mermaid` to `resume-preview` and now focuses on resumes
|
|
316
|
+
only. The upstream project (`claude-mermaid`) has a hosted deployment on
|
|
317
|
+
[Fronteir AI](https://fronteir.ai/mcp/veelenga-claude-mermaid). This repository is a renamed
|
|
318
|
+
fork and is not covered by it.
|
package/README.md
CHANGED
|
@@ -1,3 +1,314 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Resume Preview MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**简体中文** | [English](README.en.md)
|
|
4
|
+
|
|
5
|
+
MCP server,把结构化的简历内容渲染到浏览器里的实时 A4 页面 —— 你反复打磨措辞的同时,页面跟着刷新,不用导出再重来。
|
|
6
|
+
|
|
7
|
+
MIT 许可证,兼容任何 MCP 客户端。
|
|
8
|
+
|
|
9
|
+
## ✨ 功能特性
|
|
10
|
+
|
|
11
|
+
- 🔄 **实时刷新** - 内容一改,已打开的标签页就自己刷新
|
|
12
|
+
- 📐 **A4 版式** - 简历在浏览器和 PDF 里都是真实的 A4 页面
|
|
13
|
+
- 📤 **两种导出格式** - 导出 PDF,或导出成独立 HTML 文档
|
|
14
|
+
- 🧩 **结构化内容模型** - 你没写的板块会直接从页面上消失
|
|
15
|
+
- 🔤 **始终是纯文本** - 内容被转义,里面的 HTML 标签和脚本永远不会被解释
|
|
16
|
+
- 🗂️ **多份简历** - 每份简历一个 `resume_id`,各有各的标签页和 slug
|
|
17
|
+
- 💾 **持久化的工作文件** - 简历存放在 `~/.config/resume-preview/resumes`
|
|
18
|
+
- 🖥️ **独立画廊** - `resume-preview --serve` 打开浏览器画廊,列出所有已存简历,支持搜索和删除
|
|
19
|
+
- 🌍 **两套彼此独立的语言** - 页面框架跟随浏览器语言;简历自身的语言按份设置,决定分节标题和导出的文档
|
|
20
|
+
- 🔎 **审阅工具** - 在预览页里缩放、平移、导出,附带连接状态指示和"最后更新"时间戳
|
|
21
|
+
- 🤖 **内置技能** - 插件自带 `resume` 技能,包含内容模型和措辞建议
|
|
22
|
+
|
|
23
|
+
## 架构
|
|
24
|
+
|
|
25
|
+

|
|
26
|
+
|
|
27
|
+
两条链路共用同一套代码路径:
|
|
28
|
+
|
|
29
|
+
- **预览** — `resume_preview` → 逐层处理 → 渲染结果落进 `resumes/` → `live-server.ts` 监听到变化,用 WebSocket 推 `reload`
|
|
30
|
+
- **导出** — `resume_export` → 走同一套渲染 → 落盘到 `save_path`
|
|
31
|
+
|
|
32
|
+
模块与接口清单见 [`docs/api-list.md`](docs/api-list.md)。
|
|
33
|
+
|
|
34
|
+
## 🚀 快速开始
|
|
35
|
+
|
|
36
|
+
> **发布状态**:npm 包 `@studyllm/resume-preview` **尚未发布**(`npm view @studyllm/resume-preview` 返回 404),
|
|
37
|
+
> 因此 `npm install -g @studyllm/resume-preview` 与插件的 `npx` 启动方式暂时都不可用。GitHub 仓库
|
|
38
|
+
> `studyllm/resume-preview` 已创建,请克隆源码后执行 `npm install && npm run build`,
|
|
39
|
+
> 再按下面的 `.mcp.json` 接入 MCP 客户端。
|
|
40
|
+
|
|
41
|
+
**插件安装(推荐)**
|
|
42
|
+
|
|
43
|
+
> **在 Claude Code 中输入** —— 下面两条是斜杠命令,不是 shell 命令。
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
/plugin marketplace add studyllm/resume-preview
|
|
47
|
+
/plugin install resume-preview@resume-preview
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
然后重启 Claude Code 以激活插件。
|
|
51
|
+
|
|
52
|
+
**从源码安装**
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
git clone https://github.com/studyllm/resume-preview.git
|
|
56
|
+
cd resume-preview
|
|
57
|
+
npm install && npm run build && npm install -g .
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
本地检出后,用这样一份 `.mcp.json` 接入 MCP 客户端:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"resume-preview": {
|
|
66
|
+
"command": "node",
|
|
67
|
+
"args": ["build/index.js"]
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**验证安装**
|
|
74
|
+
|
|
75
|
+
插件安装:MCP 服务会自动配置好,只需在 Claude Code 中运行 `/mcp`,确认服务列表里出现 `resume-preview`。
|
|
76
|
+
|
|
77
|
+
从源码安装:需要手动注册并核对:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
claude mcp add --scope user resume-preview resume-preview
|
|
81
|
+
claude mcp list
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
你应当看到 `resume-preview: resume-preview - ✓ Connected`
|
|
85
|
+
|
|
86
|
+
## 💡 使用
|
|
87
|
+
|
|
88
|
+
直接开口要简历就行。装成插件后,内置的 `resume` 技能会把内容模型、"预览—迭代—导出"的工作流,以及该避开的坑都告诉 AI 客户端。
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
"帮我写一份后端工程师的简历并预览" // 浏览器打开 A4 页面
|
|
92
|
+
"把自我评价写得更短、更具体一些" // 同一个标签页原地刷新
|
|
93
|
+
"把简历导出成 PDF 到 ./docs/resume.pdf" // 同一份简历的另一条出口
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
同一份简历的每次修改都复用**同一个** `resume_id`:已打开的标签页会被刷新,而不是新开一个。不同简历用不同的 `resume_id`(比如每个目标岗位一份)。
|
|
97
|
+
|
|
98
|
+
### 内容模型
|
|
99
|
+
|
|
100
|
+
简历是一个 JSON 对象。只有 `basics.name` 是必填的 —— 其余板块你没写就直接从页面上省略:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"basics": {
|
|
105
|
+
"name": "张小明",
|
|
106
|
+
"title": "高级后端工程师",
|
|
107
|
+
"email": "zhang@example.com",
|
|
108
|
+
"phone": "138-0000-0000",
|
|
109
|
+
"location": "上海",
|
|
110
|
+
"links": [{ "label": "GitHub", "url": "https://github.com/example" }]
|
|
111
|
+
},
|
|
112
|
+
"summary": "六年后端经验,专注于高并发服务与数据管道建设。",
|
|
113
|
+
"experience": [
|
|
114
|
+
{
|
|
115
|
+
"company": "某某科技有限公司",
|
|
116
|
+
"title": "高级后端工程师",
|
|
117
|
+
"start": "2023.07",
|
|
118
|
+
"end": "至今",
|
|
119
|
+
"location": "上海",
|
|
120
|
+
"highlights": [
|
|
121
|
+
"主导订单系统重构,接口 P99 延迟从 800ms 降到 180ms",
|
|
122
|
+
"搭建单元化发布流程,回滚时间从 20 分钟缩短到 2 分钟"
|
|
123
|
+
]
|
|
124
|
+
}
|
|
125
|
+
],
|
|
126
|
+
"projects": [
|
|
127
|
+
{
|
|
128
|
+
"name": "实时数据平台",
|
|
129
|
+
"role": "技术负责人",
|
|
130
|
+
"period": "2024.01 - 2024.09",
|
|
131
|
+
"highlights": ["设计流式 ETL 链路,支撑日均 20 亿条事件"]
|
|
132
|
+
}
|
|
133
|
+
],
|
|
134
|
+
"education": [
|
|
135
|
+
{
|
|
136
|
+
"school": "某某大学",
|
|
137
|
+
"degree": "计算机科学与技术 学士",
|
|
138
|
+
"period": "2016.09 - 2020.06",
|
|
139
|
+
"highlights": ["GPA 3.7 / 4.0"]
|
|
140
|
+
}
|
|
141
|
+
],
|
|
142
|
+
"skills": [
|
|
143
|
+
{ "category": "后端", "items": ["Go", "Java", "PostgreSQL", "Kafka"] },
|
|
144
|
+
{ "category": "基础设施", "items": ["Kubernetes", "Terraform"] }
|
|
145
|
+
],
|
|
146
|
+
"extras": [{ "label": "证书", "items": ["PMP"] }]
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`content` 参数既可以直接接受这个对象,也可以接受装着同样对象的 JSON 字符串。
|
|
151
|
+
`start` 和 `end` 是自由格式的字符串(`"2023.07"`、`"至今"`),页面用一个短横线把它们连起来。
|
|
152
|
+
|
|
153
|
+
### 分节顺序与标题
|
|
154
|
+
|
|
155
|
+
分节的顺序是固定的:
|
|
156
|
+
|
|
157
|
+
> 自我评价 → 工作经历 → 项目经历 → 教育经历 → 专业技能 → 其他
|
|
158
|
+
|
|
159
|
+
内容里没有的板块会从页面上省略 —— 绝不会渲染出一个空板块。
|
|
160
|
+
|
|
161
|
+
标题跟随简历自身的 `locale`,而不是浏览器的:`zh-CN` 就是上面这些标题,`en` 则是 Summary → Experience → Projects → Education → Skills → Extras。导出的文档始终是你设定的那个语言,与谁打开它无关。
|
|
162
|
+
|
|
163
|
+
## 🔌 其他 MCP 客户端配置
|
|
164
|
+
|
|
165
|
+
这个服务是为 Claude Code 优化的,但任何兼容 MCP 的客户端都能用。
|
|
166
|
+
|
|
167
|
+
配置内容对所有客户端都是一样的 —— 把下面这段加进客户端的 MCP 配置文件:
|
|
168
|
+
|
|
169
|
+
> **客户端的 MCP 配置**
|
|
170
|
+
|
|
171
|
+
```json
|
|
172
|
+
{
|
|
173
|
+
"mcpServers": {
|
|
174
|
+
"resume-preview": {
|
|
175
|
+
"command": "resume-preview"
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
<details>
|
|
182
|
+
<summary><strong>各客户端的配置文件位置</strong></summary>
|
|
183
|
+
|
|
184
|
+
- **Codex** — `~/.codex/mcp_settings.json`
|
|
185
|
+
- **Cursor** — `.cursor/mcp.json`,或设置界面(Cmd/Ctrl + ,)→ MCP Servers
|
|
186
|
+
- **VSCode + [Cline 插件](https://github.com/cline/cline)** — 设置(Cmd/Ctrl + ,)→ 搜索 "Cline MCP" → MCP Settings JSON
|
|
187
|
+
- **Windsurf** — macOS `~/Library/Application Support/Windsurf/mcp.json`;Linux `~/.config/windsurf/mcp.json`;Windows `%APPDATA%\Windsurf\mcp.json`
|
|
188
|
+
- **Gemini CLI** — `~/.gemini/mcp.json`
|
|
189
|
+
|
|
190
|
+
其余兼容 MCP 的客户端也用上面那份标准配置。
|
|
191
|
+
|
|
192
|
+
</details>
|
|
193
|
+
|
|
194
|
+
有两个客户端可以直接用命令行配置:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
codex mcp add resume-preview resume-preview
|
|
198
|
+
gemini config mcp add resume-preview --command resume-preview
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
安装之后,`resume-preview` 命令应当已经在你的 PATH 里。
|
|
202
|
+
|
|
203
|
+
**注意:** 有些客户端要的是可执行文件的完整路径:
|
|
204
|
+
|
|
205
|
+
- 查路径:`which resume-preview`(Unix/macOS)或 `where resume-preview`(Windows)
|
|
206
|
+
- 在配置里用绝对路径:`"command": "/path/to/resume-preview"`
|
|
207
|
+
|
|
208
|
+
## 🎯 实时刷新
|
|
209
|
+
|
|
210
|
+
1. **首次渲染:** 在浏览器打开 `http://localhost:3737/resume/<slug>`
|
|
211
|
+
2. **做出修改:** AI 客户端更新内容,并用同一个 `resume_id` 调用 `resume_preview`
|
|
212
|
+
3. **自动刷新:** 浏览器通过 WebSocket 感知变化并重新加载
|
|
213
|
+
4. **状态指示:** 绿点 = 已连接,红点 = 正在重连
|
|
214
|
+
|
|
215
|
+
实时服务使用 3737-3747 端口,并自动挑一个可用端口。页面工具栏上还提供缩放、平移,以及直接下载 PDF / HTML 的按钮。
|
|
216
|
+
|
|
217
|
+
> 服务只绑定 `127.0.0.1`,且**没有任何鉴权**。简历含个人信息,绝不要把端口暴露到局域网或公网。
|
|
218
|
+
|
|
219
|
+
## 🖥️ 独立服务模式
|
|
220
|
+
|
|
221
|
+
用 `--serve` 参数可以不起 AI agent,只启动预览服务:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
resume-preview --serve
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
它会在浏览器里打开简历画廊,列出此前渲染过的所有简历。画廊会显示每份简历的最后更新时间和文件大小,可以**按 ID 搜索**,也能**删除**不再需要的。
|
|
228
|
+
|
|
229
|
+
## 🛠️ 开发
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
# 安装依赖
|
|
233
|
+
npm install
|
|
234
|
+
|
|
235
|
+
# 构建项目
|
|
236
|
+
npm run build
|
|
237
|
+
|
|
238
|
+
# 运行测试
|
|
239
|
+
npm test
|
|
240
|
+
|
|
241
|
+
# 开发监听模式
|
|
242
|
+
npm run dev
|
|
243
|
+
|
|
244
|
+
# 直接启动 MCP 服务
|
|
245
|
+
npm start
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## ❓ 常见问题
|
|
249
|
+
|
|
250
|
+
**简历存放在哪里?** 在 `~/.config/resume-preview/resumes/<slug>/` 下 —— 目录名是由 `resume_id` 推导出的 slug,所以像 `小王的简历` 这样的中文 ID 会变成类似 `r-3f9a2b` 的东西。
|
|
251
|
+
|
|
252
|
+
**支持哪些语言?** 两种,而且彼此独立。**页面框架** —— 画廊、工具栏、对话框 —— 跟随请求:`?lang=en` 优先,其次浏览器的 `Accept-Language`,最后 `zh-CN`。**简历本身** —— 分节标题和导出的文档 —— 跟随你传给 `resume_preview` 的 `locale`,它与简历一起存储,默认 `zh-CN`。导出语言永远不依赖浏览器,所以同一份简历每次导出都一样。
|
|
253
|
+
|
|
254
|
+
**内容支持 HTML 吗?** 不支持,而且是刻意的。每个值都会被转义后按文本打印。写纯文本就好;内容里的标记会原样显示 —— 这是本产品最大的 XSS 面,它会一直关着。
|
|
255
|
+
|
|
256
|
+
**还有别的模板或主题吗?** 目前没有 —— `default` 是唯一实现的模板,也是唯一实现的主题。两者都是 `src/constants.ts` 里的白名单(`RESUME_TEMPLATES` / `RESUME_THEMES`),所以新增一个只需要扩展这两个列表并加上对应的资源文件。
|
|
257
|
+
|
|
258
|
+
## 📝 故障排查
|
|
259
|
+
|
|
260
|
+
**服务连不上:**
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
# 确认服务已安装
|
|
264
|
+
resume-preview -v
|
|
265
|
+
|
|
266
|
+
# 需要的话重装
|
|
267
|
+
npm install -g @studyllm/resume-preview
|
|
268
|
+
|
|
269
|
+
# 核对 MCP 配置
|
|
270
|
+
claude mcp list
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
**权限不足报错:**
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
# 确保可执行文件有执行权限
|
|
277
|
+
chmod +x $(which resume-preview)
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
**端口被占用:**
|
|
281
|
+
|
|
282
|
+
服务使用 3737-3747 端口,会自动找一个可用端口。看看是不是别的进程占着:
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
lsof -i :3737-3747
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
**简历没渲染出来,或实时刷新不工作:**
|
|
289
|
+
|
|
290
|
+
服务日志在 `~/.config/resume-preview/logs/` —— `mcp.log` 记录工具调用与简历渲染,`web.log` 记录 HTTP/WebSocket 连接与实时刷新。
|
|
291
|
+
|
|
292
|
+
日志级别由环境变量 `CLAUDE_MERMAID_LOG_LEVEL` 控制,可选 `DEBUG`、`INFO`(默认)、`WARN`、`ERROR`、`OFF` —— 变量名是历史遗留,保持不变。设成 `DEBUG` 可以看更细的日志:
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
tail -f ~/.config/resume-preview/logs/mcp.log
|
|
296
|
+
tail -f ~/.config/resume-preview/logs/web.log
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
**报 `Cannot find package 'puppeteer'`:** 多半是安装时没带上 Chromium。重新 `npm install -g @studyllm/resume-preview`,或先在本机跑一次 `npx puppeteer browsers install chrome` 把浏览器下载下来。
|
|
300
|
+
|
|
301
|
+
## 🤝 参与贡献
|
|
302
|
+
|
|
303
|
+
欢迎贡献!请尽管提交 Pull Request。
|
|
304
|
+
|
|
305
|
+
## 🔗 相关链接
|
|
306
|
+
|
|
307
|
+
- [GitHub 仓库](https://github.com/studyllm/resume-preview)
|
|
308
|
+
- [npm 包](https://www.npmjs.com/package/@studyllm/resume-preview)
|
|
309
|
+
- [Claude Code 文档](https://docs.claude.com/claude-code)
|
|
310
|
+
- [MIT 许可证](LICENSE)
|
|
311
|
+
|
|
312
|
+
## 上游项目
|
|
313
|
+
|
|
314
|
+
本仓库从 `claude-mermaid` 改名而来,现在只专注简历。上游项目(`claude-mermaid`)在 [Fronteir AI](https://fronteir.ai/mcp/veelenga-claude-mermaid) 上有托管部署。本仓库是改名后的 fork,不在它的服务范围内。
|