GrimNej/portfolio-design

作品集设计（Portfolio Design）

本技能为任何人重新构建一套特定的作品集设计。设计是固定的且已经过调优。你的工作是收集用户的素材，以其语气撰写文案，生成网站，证明其正常工作，并在用户同意后发布。

所有内容都位于此技能文件夹内：

路径	说明
template/assets/	网站的 CSS、JavaScript 模块、字体和第三方库（GSAP、Lenis）。请勿针对个人编辑：构建时会复制并应用主题。
scripts/build.mjs	将 portfolio.json 转换为完整的静态网站。Node 18+，无外部依赖。
scripts/prepare_photos.py	裁剪肖像（去背景）并将关于照片调整为正方形。
scripts/discover_github.mjs	列出 GitHub 用户的公开仓库，附带 README 标语和横幅图片，用于挑选项目。
scripts/snapshot_github.mjs	保存存档所依赖的公开仓库列表快照。
scripts/render_images.py	渲染分享卡片（og.jpg）和触摸图标。
scripts/serve.py	构建后网站的本地预览服务器。
scripts/qa/run_all.py	浏览器质量门控。构建未通过检查即视为未完成。
examples/portfolio.example.json	一个虚构人物的完整配置，包含占位图片。
reference/	配置模式、采访脚本、设计系统、文案规则、质量门控、部署指南。

在以下命令中，scripts/... 指此技能文件夹（运行时请使用绝对路径），portfolio/... 是用户工作目录中的项目文件夹。

在编写配置前请阅读 reference/config-schema.md，在编写任何文案前请阅读 reference/copywriting.md。

基本规则

• 未经明确同意，不得公开任何内容。 在用户明确批准该步骤之前，不要执行 git push、部署或创建仓库。本地构建和预览是允许的。
• 隐私。 仅使用公开的 GitHub 数据（两个 GitHub 脚本故意调用未认证的 API）。在存档上线前，展示将要显示的公开仓库列表，并询问用户希望隐藏哪些。除非用户要求，否则绝不在页面上放置电话号码、街道地址或私有仓库。
• 用户的照片归用户所有。 只在项目文件夹内处理副本。除用户批准的网站外，不得将其上传至任何地方。
• 设计即产品。 不要因为用户提出模糊要求而增加章节、更换字体或重新设计组件。只调整内容、主题预设、吉祥物和文案。如果用户提出结构性修改，请先告知其成本并获得确认。
• 文案是写出来的，而不是填进去的。 用户提供的笔记是原始素材。以用户的语气起草每一行内容，遵守字数限制，并在构建最终版本前展示给用户。

工作流程

1. 检查工具链

node --version          # 18 或更高版本
python --version        # 3.10 或更高版本
python -m pip install playwright pillow numpy
python -m playwright install chromium

肖像背景去除需要 python -m pip install "rembg[cpu]"（首次运行会下载约 1 GB 的模型）。如果无法实现，请要求一张已去除背景的肖像，并使用 --no-cutout 参数。

与用户商定项目文件夹（默认：当前目录下的 ./portfolio/）。目录结构如下：

portfolio/
  portfolio.json      # 你编写的配置
  photos/             # 用户的原始照片（切勿原样发布）
  work/               # 项目横幅和截图
  site/               # 构建输出：该文件夹将被部署

2. 采访

遵循 reference/interview.md。采访分为十个简短轮次，对于有合理选项的每个选择（主题、吉祥物、展示哪些仓库、在英雄区放哪些链接），使用 AskUserQuestion。自由格式的素材（个人简介、项目描述）以纯文本形式询问。一次只问一轮，对于用户不想撰写的内容，主动提供草稿。

顺序依次为：

1. 身份：全名、别名或常用账号、简短头衔、邮箱、城市和国家（用于实时时钟时区）、语言。
2. 照片：一张头像半身肖像（用于英雄区裁剪）和一张可选用于“关于”部分的照片。
3. 链接：用户希望列出的所有个人资料；从中挑选两到四个放在英雄区行中。
4. 英雄区与关于：用一句话说明用户做什么，然后用两段简短文字介绍其工作方式。
5. 作品分类：四种作品类型，每个用一个词表示，附带一行描述和一个悬停动画（如 agents、automation、context、launch、code、data、design）。
6. 项目：最多六个精选项目和最多三个支线项目。先运行 discover_github.mjs 并推荐候选项目。
7. 存档：是否显示所有公开仓库，以及要隐藏哪些。
8. 技术栈：分组的工具列表，以及 12 到 24 个用作物理球池球体的工具。
9. 流程、联系、滚动条：三个流程步骤、联系行、两条滚动磁带条。
10. 外观与附加：主题预设、吉祥物（名称、语气或关闭）、网站 URL 及托管位置。

3. 收集项目素材

node scripts/discover_github.mjs --user <github-user> --out portfolio/discovery.json
node scripts/discover_github.mjs --user <github-user> --out portfolio/discovery.json --download portfolio/work --repos RepoA,RepoB

第一次运行列出公开仓库及其 README 标语、图片和在线链接。第二次运行将每个选定仓库的第一张 README 图片保存到本地。每个精选项目至少需要一张预览图片。合适的来源依次为：README 横幅、在线应用的截图（使用 Playwright 以 1600x900 尺寸截取）、仿照 examples/assets/*.svg 风格生成的横幅。检查每张图片：截图中不能包含机密信息，不能模糊，应为宽屏格式（16:9 或接近）。

4. 准备照片

python scripts/prepare_photos.py --portrait portfolio/photos/portrait.jpg \
  --about portfolio/photos/about.jpg --about-gray --out portfolio/photos/out

打开结果并检查。裁剪后的肖像必须边缘干净、无透明破洞，头部靠近顶部。如果关于照片中脸部裁剪不当，请使用 --about-focus x,y（图像宽高的 0 到 1 分数）重新运行。将配置中 person.photos.portrait 和 .about 指向 out/ 中的文件。

5. 编写配置并构建

编写 portfolio/portfolio.json（模式见 reference/config-schema.md；工作示例见 examples/portfolio.example.json）。其中的路径是相对于配置文件本身的。然后执行：

node scripts/build.mjs --config portfolio/portfolio.json --out portfolio/site
node scripts/snapshot_github.mjs --user <github-user> --site portfolio/site   # 仅当启用存档时运行
python scripts/render_images.py --site portfolio/site

当缺少必填字段时，构建会给出明确提示并停止。有关未知图标的警告意味着该球体将以文本形式显示其名称；请从 data/simple-icons.json 中选择一个 slug，或者保持不变。

6. 预览

在后台启动网站预览服务器，并将 URL 提供给用户：

python scripts/serve.py --site portfolio/site --port 4321

请使用此服务器而非 python -m http.server：后者在页面同时请求大量文件时会断开连接，导致随机性的 QA 失败。此服务器还会发送无缓存头（重新构建后刷新即可看到更新），并对未知路径（如 GitHub Pages 中那样）返回 404.html。

7. 质量门控

python scripts/qa/run_all.py --url http://127.0.0.1:4321/ --out portfolio/qa

所有检查必须通过（reference/quality-gates.md 解释了每项检查及其常见故障的修复方法）。然后亲自查看 portfolio/qa/shots/ 中的截图，逐部分检查桌面端和手机端。自动化检查能捕获碰撞和溢出；你的眼睛能发现别扭的断行、模糊的图片和读起来不通顺的文案。修复、重新构建、重新运行。在部署前至少运行一次 --full。

8. 与用户一起审核

带领用户浏览预览：英雄区、关于、行、项目、存档、球池、流程、联系、吉祥物聊天。收集修改意见，将其应用到配置中（而不是构建后的文件），重新构建并重新运行质量检测。

9. 部署（仅在其明确同意后）

遵循 reference/deploy.md：GitHub Pages（用户站点或项目站点）、自定义域名以及重要的 Cloudflare 设置。部署后，运行在线检查：

python scripts/qa/run_all.py --url https://their-domain/ --only smoke,live --out portfolio/qa-live

如果“邮箱未被重写”检查失败，说明 Cloudflare 的邮箱地址混淆功能已启用，破坏了“联系我们”环；修复方法在 reference/deploy.md 中。

后续修改

编辑 portfolio.json，重新构建，重新运行质量检测，重新部署。每次构建都会在每个资源上添加新的 ?v= 版本字符串，因此浏览器和 CDN 无需手动清除缓存即可获取更新。