Skip to content

Commit 38bef69

Browse files
wanshuiyinclaude
wanshuiyin
and
claude
committed
feat(homepage-generator): scaffold v1 — fact-checked academic homepage from CV
v1 lands the skill contract, theory-minimal template, orchestrator skeleton, and .gitignore. Section builders + extraction pipeline + audit-report writer are stubbed for the next iteration. Design locked via two rounds of cross-model review (Codex GPT-5.5 xhigh + Gemini auto-gemini-3): - Scope: academic only; theory-minimal default persona; active-researcher v1.1 - Input: magic-then-editable (init --from-cv → profile.yml + .bib + .md) - Pitch: "the only personal-site generator that fact-checks your CV" - Fact-check: DBLP/arXiv direct API; per-paper override with expires field - Template: Python builds HTML chunks; template is shell with placeholders Files: - skills/homepage-generator/SKILL.md (contract, 286 lines) - tools/templates/homepage-theory-minimal.html (shell + Zhxie/Avicenna CSS) - tools/aris_homepage.py (init/render/check/doctor commands, builders stubbed) - .gitignore (Python __pycache__, .DS_Store, .aris-homepage/ intermediates) Doctor pass: pyyaml ✓ textutil ✓ pdftotext ✓ DBLP ✓ (bibtexparser one-line install). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent b1ebb6f commit 38bef69

4 files changed

Lines changed: 1101 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Python
2+
__pycache__/
3+
*.pyc
4+
*.pyo
5+
*.pyd
6+
.Python
7+
*.egg-info/
8+
9+
# OS
10+
.DS_Store
11+
Thumbs.db
12+
13+
# Editors
14+
.idea/
15+
.vscode/
16+
*.swp
17+
*.swo
18+
19+
# ARIS homepage generator intermediates
20+
.aris-homepage/
21+
*.bak-*

‎skills/homepage-generator/SKILL.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
---
2+
name: homepage-generator
3+
description: "Generate a fact-checked academic personal homepage from a CV. Extracts a .docx/.pdf/.txt CV into editable structured files (profile.yml + publications.bib + bio.md + news.md), runs cross-model factual review against DBLP / arXiv (hard-fail on wrong venue/year/author, soft-warn on unverifiable), then renders to single-file HTML in one of two academic personas (theory-minimal | active-researcher). Output: index.html + audit-report.md. Use when the user says '做个学术主页', '从CV生成主页', 'aris-homepage', 'generate academic homepage from CV', 'PhD homepage', or wants a fact-checked personal academic site."
4+
argument-hint: init --from-cv <cv.docx|cv.pdf|cv.txt> [--out <dir>] [--force|--merge] | render --persona theory-minimal|active-researcher [--out index.html] [--override-all] [--offline] | check [--strict] | doctor
5+
allowed-tools: Bash(*), Read, Write, Edit, mcp__codex__codex
6+
---
7+
8+
# /homepage-generator — fact-checked academic homepage from CV
9+
10+
> **The only personal-site generator that fact-checks your CV before publishing.**
11+
> Built on ARIS's cross-model adversarial-review invariant: the LLM that drafts your homepage never grades it — a fresh Codex (GPT-5.5 xhigh) thread audits every claim against DBLP / arXiv / Semantic Scholar before the HTML is signed off.
12+
13+
## When to use
14+
15+
Generate a single-file HTML academic homepage from a CV. v1 supports **academic personas only** (theorist / active researcher); Builder-Engineer and PM are deferred to v2. Optimized for PhD candidates, postdocs, and early-career researchers — not for tenured faculty with student/teaching pages (use [academicpages](https://academicpages.github.io/) for that scope).
16+
17+
**Use when the user says**: `做个学术主页` · `from CV generate homepage` · `aris-homepage` · `PhD personal site` · `theory page` · `dogfood my homepage`
18+
19+
**Do NOT use for**: portfolio sites needing image galleries (Designer-Visual is out of scope); newsletter-funnel sites needing audience metrics; pure blog sites (use Jekyll/Hugo).
20+
21+
## Pitch & invariants
22+
23+
1. **Fact-check is the north star.** Every claim (paper venue, year, author role, employment dates, award) is verified against DBLP / arXiv / Semantic Scholar before render is signed off. Failures block ship unless explicit `--override-all` or per-paper `audit.overrides.<bibkey>` is set (with optional `expires:` date for self-honesty).
24+
2. **Magic-then-editable input.** `init --from-cv` does the heavy lifting via LLM extraction into structured files. User edits in their IDE. Never a hosted black box.
25+
3. **Single-file HTML output.** Drop on GitHub Pages, S3, university `~user/public_html/`, email attachment. Zero build server at hosting time.
26+
4. **Zero-knob templates.** Two academic personas — pick one, get a good default. No CSS feature-flag bloat.
27+
5. **Graceful degradation.** Empty fields → section disappears. Never an LLM filling "publications" with hallucinated entries to satisfy a template loop.
28+
29+
## Commands
30+
31+
```bash
32+
# 1. Bootstrap workspace from a CV
33+
aris-homepage init --from-cv cv.docx
34+
# → writes profile.yml, publications.bib, bio.md, news.md, EXTRACTION_REVIEW.md
35+
# → bails if profile.yml exists; use --force (backup .bak) or --merge (fill-only)
36+
37+
# 2. Render to HTML (runs fact-check at the same time)
38+
aris-homepage render --persona theory-minimal
39+
# → writes index.html + audit-report.md
40+
# → blocks on hard-fail unless --override-all
41+
42+
# 3. Run fact-check without rendering
43+
aris-homepage check [--strict]
44+
# → updates audit-report.md only; --strict treats soft-warn as fail
45+
46+
# 4. Environment diagnostic
47+
aris-homepage doctor
48+
# → checks Python, pyyaml, bibtexparser, textutil/python-docx availability,
49+
# write permissions, DBLP reachability
50+
```
51+
52+
**Default persona** (when `--persona` omitted): `theory-minimal`. Anchored on the assumption that users opening this skill are typically theorists / PhD-candidates whose papers don't have visual demos.
53+
54+
## Input files (after `init`)
55+
56+
| File | Role | Required | Canonical for |
57+
|---|---|---|---|
58+
| `profile.yml` | Structured facts (identity, affiliations, education, research, awards, talks, publications-meta) | ✓ | Everything except paper bibliographies and prose |
59+
| `publications.bib` | BibTeX entries — paper truth source | ✓ if you list publications | Author, title, venue, year |
60+
| `bio.md` | 1-3 paragraph self-introduction prose | optional | Free-text bio (overrides `research.summary` in profile.yml) |
61+
| `news.md` | Reverse-chronological news bullets | optional | News ticker (capped to last 10) |
62+
| `assets/` | Photo, optional paper thumbnails | optional | Visual assets (base64-embedded if <2MB total) |
63+
| `EXTRACTION_REVIEW.md` | LLM extraction confidence flags | generated by init | Audit trail for the bootstrap step |
64+
65+
## `profile.yml` schema (v1)
66+
67+
Full reference in `skills/homepage-generator/PROFILE_SCHEMA.md` (generated next). Excerpt:
68+
69+
```yaml
70+
schema_version: 1
71+
72+
identity:
73+
name: "Ruofeng Yang" # required
74+
name_native: "杨若峰" # optional, bilingual rendering
75+
title: "Ph.D. Candidate" # optional
76+
photo: "assets/photo.jpg" # optional, ≤500KB; base64-embedded
77+
email: "wanshuiyin@sjtu.edu.cn"
78+
79+
affiliations:
80+
current:
81+
- institution: "Shanghai Jiao Tong University"
82+
department: "John Hopcroft Center"
83+
role: "Ph.D. Candidate"
84+
start: "2022-09"
85+
end: null # null = present
86+
87+
education:
88+
- degree: "Ph.D. in Computer Science"
89+
institution: "SJTU"
90+
advisor: ["Prof. Shuai Li (李帅)"]
91+
start: "2022-09"
92+
end: "present"
93+
94+
research:
95+
summary: "Diffusion models and reinforcement learning theory." # overridden by bio.md if present
96+
interests: ["diffusion models", "reinforcement learning theory", "long-horizon agents"]
97+
98+
links:
99+
google_scholar: "https://scholar.google.com/..."
100+
github: "https://github.com/wanshuiyin"
101+
dblp: "https://dblp.org/pid/..."
102+
103+
awards:
104+
- title: "National Scholarship (Ph.D.)"
105+
issuer: "Ministry of Education, China"
106+
year: 2025
107+
url: null # null = not externally verifiable
108+
109+
talks:
110+
- title: "ARIS: 跨模型持久化对抗式多智能体自主科研系统"
111+
venue: "VALSE 2026"
112+
date: "2026-XX-XX"
113+
url: null
114+
115+
publications_meta: # KEYED BY BIBKEY (must exist in publications.bib)
116+
yang2026moe:
117+
spotlight: true # render at top of selected list
118+
award: null
119+
co_first: ["Ruofeng Yang", "Yongcan Li"]
120+
thumbnail: null # active-researcher only
121+
links:
122+
arxiv: "https://arxiv.org/abs/..."
123+
code: null
124+
project: null
125+
126+
selected_publications: # ordered list of bibkeys to show on homepage
127+
- yang2026moe
128+
- yang2024fewshot
129+
- yang2025consistency
130+
# ...
131+
132+
audit:
133+
overrides: # per-paper, per-field bypass with expiration
134+
yang2024fewshot:
135+
venue: true
136+
reason: "DBLP indexes only main conference; CV uses workshop attribution from TongAI 2025 best-paper award."
137+
expires: "2026-12-31" # auto-expire to force re-verification
138+
139+
ship:
140+
persona: theory-minimal # default render persona
141+
accent_color: "#1a4a8c" # one knob: subtle accent override
142+
lang: en # en | zh | bilingual
143+
```
144+
145+
## Persona templates (v1)
146+
147+
### `theory-minimal` (default)
148+
149+
Anchored on Zhxie / Avicenna aesthetic. **Text-only papers, no thumbnails, no badges**. Selected-works-with-Scholar-deflection. Bilingual name header. Monochrome + one subtle accent. Single-column scroll, ~720px max-width, generous line-height. **Hand-rolled vibe.** Ships zero animation.
150+
151+
Optimized for: theorists, PhD candidates with 5-15 papers, anyone whose research is mathematically interesting but visually plain.
152+
153+
Section order: Header (photo + name + affiliation + social) → Bio → Research Interests → Education → Selected Publications (text-only with `[abs][code][pdf][project]` quadruple) → News → Awards → footer (audit link + generation timestamp).
154+
155+
### `active-researcher`
156+
157+
Anchored on al-folio / Mayue Ma aesthetic. **Per-paper thumbnails, news ticker, logo-grid affiliations**. For empirical researchers with visual demos (vision, NLP, RL with environments).
158+
159+
Same content schema as `theory-minimal` — uses `publications_meta.<key>.thumbnail` to upgrade text rows to cards. If thumbnails are missing, gracefully degrades to text rows.
160+
161+
## Fact-check protocol
162+
163+
Runs automatically during every `render` (unless `--no-audit`). Three outcomes per claim:
164+
165+
| Outcome | Trigger | Effect |
166+
|---|---|---|
167+
| **PASS (silent)** | Title fuzzy-matched on DBLP; venue + year + author set agree | No mention in audit-report |
168+
| **WARN (soft)** | DBLP returns 0 hits OR ≥2 ambiguous hits; OR arXiv-only paper; OR award has no external URL | Render proceeds; logged in audit-report |
169+
| **FAIL (hard)** | DBLP venue ≠ profile venue; year mismatch; author list missing user; or fabricated award badge | Render produces HTML but audit verdict = `BLOCKED`; user must `--override-all` to ship |
170+
171+
**Hard-fail enumeration** (Codex round-2 list):
172+
1. BibTeX key in `selected_publications` / `publications_meta.spotlight` / `publications_meta.thumbnails` not present in `publications.bib`.
173+
2. Title fuzzy-matched on DBLP but venue or year differs from profile claim.
174+
3. Author set / order differs from DBLP, unless `audit.overrides.<bibkey>.authors: true`.
175+
4. Award badge claims `Best Paper` / `Oral` / `Spotlight` but no verifiable note / URL.
176+
5. Selected publication date in the future without `forthcoming: true` marker.
177+
6. Affiliation / degree / year in homepage contradicts profile.yml fields.
178+
179+
**Soft-warn enumeration**:
180+
1. DBLP has no result but arXiv URL is verifiable.
181+
2. DBLP returns ≥2 results that fuzzy-match the title (cannot uniquely disambiguate).
182+
3. Workshop / preprint venue not indexed by DBLP at all.
183+
4. Award / talk / teaching has no external URL — only self-attested.
184+
5. `active-researcher` thumbnail path missing → degrade to text card.
185+
186+
**DBLP query**: direct call to `https://dblp.org/search/publ/api?q=<title>&format=json&h=5`. No third-party library required.
187+
188+
**Override mechanism** (two-layer, per Codex):
189+
- Per-paper, per-field: `audit.overrides.<bibkey>.<field>: true` in profile.yml, with required `reason:` and optional `expires: YYYY-MM-DD` for self-honesty.
190+
- CLI emergency: `aris-homepage render --override-all` skips blocking but every override is loudly logged in audit-report.
191+
192+
**Audit report format** (`audit-report.md`, generated next to `index.html`):
193+
194+
```markdown
195+
# ARIS Homepage Audit Report
196+
Generated: 2026-05-22 10:14 UTC
197+
Persona: theory-minimal
198+
Verdict: ✅ PASS | ⚠️ WARN | ❌ BLOCKED
199+
200+
## Summary
201+
PASS 9 · WARN 2 · FAIL 1 · OVERRIDDEN 1
202+
203+
## Publications
204+
- PASS `yang2026moe`: title/year/authors verified by DBLP (conf/iclr/YangLJC26).
205+
- PASS `yang2024fewshot`: title verified by DBLP; venue overridden (TongAI 2025 best-paper, expires 2026-12-31).
206+
- WARN `yang2025preprint`: no DBLP hit; arXiv URL ✓.
207+
- FAIL `yang2022award`: badge `Best Paper` has no verifiable URL.
208+
209+
## Profile
210+
- PASS identity.affiliation: SJTU JHC matches profile.yml.
211+
- WARN awards[1]: issuer + year present, no verification URL.
212+
213+
## Overrides applied
214+
- `yang2024fewshot.venue` — expires 2026-12-31 — reason: workshop attribution.
215+
```
216+
217+
## Pipeline (internal flow)
218+
219+
```
220+
┌───────────────────────────┐
221+
cv.docx ──────► │ Step 1: textutil → cv.txt │
222+
└───────────┬───────────────┘
223+
▼
224+
┌───────────────────────────────────────────┐
225+
│ Step 2: LLM extract → JSON (schema bound) │
226+
│ ↳ EXTRACTION_REVIEW.md (confidence log) │
227+
└───────────┬───────────────────────────────┘
228+
▼
229+
┌────────────────────────────────────┐
230+
│ Step 3: persist → profile.yml + │
231+
│ publications.bib + bio.md + news │
232+
└───────────┬────────────────────────┘
233+
│
234+
✋ USER EDITS IN IDE ✋
235+
│
236+
▼
237+
┌────────────────────────────────────────────┐
238+
│ Step 4: render (also runs fact-check) │
239+
│ ↳ Codex MCP fresh thread audits claims │
240+
│ ↳ Python builds per-section HTML chunks │
241+
│ ↳ inject into homepage-<persona>.html │
242+
└───────────┬────────────────────────────────┘
243+
▼
244+
┌────────────────────────────────────┐
245+
│ index.html + audit-report.md │
246+
└────────────────────────────────────┘
247+
```
248+
249+
## Tool / dependency layout
250+
251+
- `skills/homepage-generator/SKILL.md` — this contract
252+
- `tools/aris_homepage.py` — orchestrator (init / render / check / doctor)
253+
- `tools/render_html.py` — reused for Markdown→HTML primitives + sanitization (already exists)
254+
- `tools/templates/homepage-theory-minimal.html` — Theory-Minimal template (shell + placeholders)
255+
- `tools/templates/homepage-active-researcher.html` — Active-Researcher template (TBD in v1.1)
256+
257+
**Python deps**: `pyyaml`, `bibtexparser` (one-line `pip install`). The stdlib-only constraint of `render_html.py` does not extend here — homepage is more complex than cheat sheets and one `pip install` is acceptable. `doctor` command checks dependencies on first run.
258+
259+
## Output ownership (privacy + drift detection)
260+
261+
- Every generated HTML embeds `<meta name="aris:source-sha256">` of `profile.yml` + `publications.bib` for drift detection (same pattern as cheat sheets).
262+
- Footer carries a small **"Generated by ARIS-Homepage · fact-checked"** mark — counterpart to Karpathy's "hand-rolled" badge.
263+
- The `audit-report.md` is the user's evidence trail; commit it alongside the HTML.
264+
- **Personal-info banlist**: no `/Users/`, no system paths, no API keys, no tokens. Same sanitization as cheat sheets.
265+
266+
## Acceptance criteria (definition of v1 done)
267+
268+
1. `aris-homepage init --from-cv` produces editable scaffolding from a real CV (Ruofeng Yang's `RuofengYang_CV_bytedance.docx` is the dogfood case).
269+
2. `aris-homepage render --persona theory-minimal` produces a single HTML file ≤500KB (no images) or ≤2MB (with photo+thumbnails).
270+
3. Fact-check correctly hard-fails on a manually corrupted profile.yml (e.g., venue swap NeurIPS↔ICML) and passes when corrected.
271+
4. Side-by-side visual comparison vs Ruofeng's manual `wanshuiyin.github.io` shows the generated version is *not embarrassing* — restraint matches, content is accurate, layout is readable on mobile.
272+
5. README.md + README_CN.md flip the 🚧 ARIS-Homepage TODO to ✅ Live, with bilingual usage examples.
273+
274+
## What's deferred (v1.1+)
275+
276+
- `active-researcher` template (v1 default ships theory-minimal only; active-researcher placeholder in tools/templates/ is a stub)
277+
- Builder-Engineer / PM personas (v2)
278+
- Multi-page output (sidebar nav for sites with 50+ pubs)
279+
- Custom domain bindings, GitHub Actions deploy
280+
- Bilingual (`lang: bilingual`) — both EN and ZH versions side-by-side in one HTML
281+
282+
## Related
283+
284+
- `skills/interview-cheatsheet/SKILL.md` — sister skill for cheat sheets (shared cross-model review pattern)
285+
- `skills/render-html/SKILL.md` — Markdown→HTML primitive (reused)
286+
- `tools/render_html.py` — implementation of the primitive

0 commit comments

Comments
 (0)