怎么贡献一篇经验帖

这个站希望一直有不同届、不同院系的人来写。流程刻意做得不需要你会写代码——会写微信长文就够了。

你需要准备什么

• 一个 GitHub 账号（提 PR 用）。
• 一篇写好的稿子，Markdown 或纯文本都行。

提示

完全不想碰 Git 也没关系：把你的稿子发到 GitHub Issues，标题写「投稿：xxx」，有人会帮你排版进去。

用站内后台改（最省事，推荐）

不需要装任何东西、不需要会 Git，日常改内容全程在校园网里就能做：

1. 打开站内后台（地址：thu.whizzzest.com/admin/）。

2. 点 Sign in with GitHub → 在 GitHub 页面点授权，就回到后台了。

   这一步要能打开 GitHub（授权页在 github.com 上）：校园网里先挂代理或用手机流量。 授权后拿到的是长效登录，之后改内容、传图、提交都不再需要代理。

3. 左边选分类（新生入学 / 学业 / 科研与深造 / 校园生活 / 心态与避坑 / 技能入门……）→ 点开要改的文章 → 直接改。

   • 每个字段上面都有中文说明，不用记 frontmatter 的写法；
   • 正文默认是「原文模式」（不会把排版改乱）。想加粗、加链接可以切到富文本模式，但 ::: 提示块和视频语法只在原文模式里写；
   • 排序数字（sidebar.order）同目录内不要重复，提示里写了。

4. 点保存。它不会直接推上线：会自动开一个 PR，机器人把预览链接评论到 PR 上，维护者看过、CI 全绿才合并。

登录相关的两个细节

• 代理只在登录这一步要：授权页在 github.com 上（国内时通时不通）；后台读写走 api.github.com，不用代理。
• 登录不了怎么办：登录页上有 Sign In Using Access Token 备用入口（自己生成一个 GitHub 令牌粘贴进去）， 生成令牌那一步同样在 github.com 上。平时用不到，OAuth 出问题时才用。

登录等于你的仓库写权限

不要把自己的登录令牌复制给别人，也不要在机房公共电脑上登录；用完记得在后台右上角退出。

插图与视频

图片

在后台编辑器里直接把图片拖进去（或点插入图片 → 从媒体库上传）就行，不需要记路径：

• 上传前浏览器会自动把它转成 WebP、长边缩到 2048、剥掉 EXIF（手机照片里的定位信息就在 EXIF 里，自动去掉）；
• 图片存在 Cloudflare R2 上，不进 Git 仓库，所以仓库不会因为插图越来越重；
• 插入到正文里是一行标准 Markdown：![图片说明](https://thu.whizzzest.com/media/uploads/……)。

三条硬规矩：

1. 图片说明（方括号里那段）必须写，而且要写清是什么图——读者用屏幕阅读器、或者图加载失败时，靠它理解内容。
2. 不要贴微信/QQ/飞书的临时图片链接：那些链接会过期，一过期历史文章里的图就全变空。自动检查会直接报错。
3. 截图前先想清楚：涉及内部系统、成绩单、教务页面的截图一律不许上传（见下面的内容红线）。要传就先打码：学号、姓名、成绩、人脸都遮掉。

视频

一句话就够，单独占一行：

::bilibili[BV1xx411c7mD]

• 直接写 B 站视频的 BV 号，或者把整条 https://www.bilibili.com/video/BV... 链接粘进方括号里；
• 想加图注，用竖线隔开：::bilibili[BV1xx411c7mD | 演示：怎么用这个工具]；
• 短的自录视频（无声操作演示）可以先在后台媒体库里上传，再写 ::video[https://thu.whizzzest.com/media/uploads/xxx.mp4 | 说明]；
• 长视频、有声音的视频一律放 B 站再嵌入：境内能看、不占站点的带宽，也不用担心文件太大。
• 别把 mp4 直接提交进仓库（会让仓库永久变大），也别嵌 YouTube（校园网打不开）。

为什么视频优先放 B 站

B 站播放器是 iframe 嵌入：零带宽成本、零仓库体积，而且境内访问稳定。 站上只保存一行语法糖，构建时才会把它变成 16:9 的响应式播放器。

直接改文件（开发者 / 批量改动）

每篇页面底部都有「编辑此页」，点它会直接在 GitHub 上打开对应的 Markdown 文件，改完提交会自动生成 PR （github.com 国内时通时不通，这条路可能要代理；批量改、调排版建议用下面的本地方式）。

如果要在本地预览效果：

git clone https://github.com/pan-nie/TsinghuaSurvive.git
cd tsinghua-guide
npm install
npm run dev      # 打开 http://localhost:4321

改完 Markdown，浏览器会热更新，所见即所得。

新增一篇文章

1. 在 src/content/docs/ 下选一个目录，新建 .md 文件：

   • freshman/ 新生入学
   • academics/ 学业
   • research/ 科研与深造
   • campus/ 校园生活
   • mindset/ 心态与避坑
   • skills/ 技能入门
   • publicity/ 宣传与传播

2. 文件名用英文小写加连字符，正文标题写中文。文件名会变成网址，中文网址在微信里转发出去会变成一长串 %E5%AD%A6...，很难看。

   • ✅ academics/course-selection.md → /academics/course-selection/
   • ❌ academics/选课攻略.md

3. 复制下面的模板填好 frontmatter。

4. 本地 npm run dev 看一眼，然后提 PR。

Frontmatter 模板

---
title: 选课怎么排才不踩坑          # 页面标题
description: 一句话摘要，会出现在搜索结果和分享卡片里
stage: ['本科低年级']              # 本科新生/本科低年级/本科高年级/研究生/全阶段，可多选
tags: ['选课', '培养方案']
authors: ['你的昵称（xx 院系 xx 级）']
status: stable                    # draft 草稿 / stable 已定稿 / outdated 已过期
reviewedAt: 2026-09-30            # 你亲自逐条核对过文中事实的日期（见下）
summary: 卡片上显示的一句话
sidebar:
  order: 10                       # 目录里的排序，小的在前
---

正文从这里开始……

stage、tags、status 这些字段写错了构建会直接失败并告诉你是哪个文件，所以不用怕写错，改对就行。

加粗别贴着全角标点写

这条很容易踩，而且页面照常打开，只是文字上多几个星号：

场合	怎么写	为什么
正文	点「同步」	写成 **「同步」** 时，** 紧贴 「 会让 Markdown 认定它不是加粗标记，星号原样印出来
正文（结尾是标点）	结论。后面	写成 **结论。**后面 同理
banner.content	<strong>重点</strong>	banner 只认 HTML，不认 Markdown，写 ** 会原样显示
title / description / summary	不加任何标记	这些字段是纯文本，标记不会被解析

记住一句话：全角标点放在 ** 外面。 提交前跑 npm run check:markup（或 npm run verify）会自动扫出来——它数的是渲染后的页面文字，所以正文、banner、卡片文案三种情况都能兜住。

这几个字段会被用来做什么

填了不会白填，站上有对应的功能在读它们：

字段	用在哪
stage	「按阶段浏览」页面的分组，以及文章底部的阶段链接
tags	「按标签浏览」页面的聚合，以及文章底部的主题链接
summary	卡片和列表里的一句话简介（没填就退回用 description）
authors	文章底部署名；也用于搜索卡片
status: draft	卡片上会显示「待核对」标签
status: outdated	页面顶部出现红色过期警告
reviewedAt	看门狗：超过 6 个月没重新核对，页面顶部自动出现橙色「可能已过期」提醒

关于 reviewedAt，请认真对待

这是本站最重要的一个机制，因为它决定了读者能不能信任这里的内容。

• 填了它 = 你亲自逐条核对过文中提到的事实（规则、时间、流程），现在是对的。
• 不填 = 页面底部显示「尚未标注」，读者知道这篇没经过人工核对。
• 不要为了“看起来完整”而随便填。填了之后 6 个月内它是你的承诺。

写经验、讲方法、说心态的文章，可以填。制度性内容如果没查证过，就不要填，同时把 status 设成 draft，并在正文里用提示块写明哪一段需要确认——就像现在站上那几篇的做法。

提交前跑一遍自动检查

npm run check:all          # 类型检查 + 内容检查 + 后台配置检查 + 媒体检查
npm run check:content      # 只跑内容检查
npm run verify             # 内容检查 + 构建 + 全套产物检查 ← 提 PR 前最稳的一条

内容检查会抓这些构建本身抓不到的问题：

• 站内链接指向不存在的页面（改名或移动文章后最容易漏，会直接报出文件和行号）
• 文件名不是英文 slug（中文文件名在微信里转发会变成一长串 %E5%AD%A6...）
• reviewedAt 写在未来
• 同一目录下 sidebar.order 冲突（目录顺序会不确定）
• links.ts / resources.ts 里的占位符和过期的核对日期
• 视频语法糖写错（写在句子中间、BV 号不对、::: 没闭合）
• 图片用了会失效的来源（微信/微博/飞书的临时链接、http:// 图片）
• 后台配置漏字段（不报错，但作者在后台保存一次就会把那个字段丢掉）
• 产物和源码对不上（有一类错误构建会「成功」但页面少一块，靠这条兜底）

真错误会让 CI 阻断部署；占位符之类的债务只提示不拦。想连债务一起清掉，跑 npm run check:content:strict。 用后台写的话这些检查一样会跑：保存会开 PR，PR 上跑的就是同一套检查。

PR 会自动生成预览

提 PR 之后，机器人会把一个预览链接评论到 PR 上，不需要你自己部署就能看到最终效果。

两个限制

1. 来自 fork 的 PR 没有预览。这是有意的安全取舍：给 fork PR 开凭证等于把 Cloudflare 账号交给陌生代码。如果你是从 fork 提的，请本地 npm run dev 看效果。
2. 预览地址是公开的。所以别在 PR 里放未脱敏的内容——内容红线在预览环境一样适用。

写作上的几个约定

1. 先给结论，再讲原因。读者是在手机上找答案，不是在看论文。
2. 写你亲历的。“我大二找导师时发过 7 封邮件只回了 2 封”比“联系导师要有耐心”有用得多。
3. 区分事实和建议。规则类内容写明“以官方为准”，建议类内容允许有个人色彩。
4. 别写绝对化的判断。“这门课给分很好”最好改成“我那年这门课的成绩分布大概是这样”。
5. 有具体时间点的内容要标年份，因为规则会变。

选题池：现在最缺什么

这个站缺的不是又一篇「要好好学习」，而是有人真的走过某条路的记录。下面这些是明确缺的，不用先问我——你写的就是这里列的东西，直接开工就行。

缺什么	谁能写	大概要写多少
五篇骨架的亲历者填空	真走过那条路的人：保研（推研）、出国申请、考研、本科生科研项目怎么报、读文献与写第一篇论文	五篇里各自有一节「需要核实的事实清单」，一条一条填；填完把 status 改成 stable，并注明适用年份
你跟不上的那门课，具体是怎么补回来的	有过「上课跟不上 → 后来追回来」完整经历的人	从高中到大学：学习方式要怎么换 只写了通用方法；某门具体课（高数、线代、程序设计……）的先修、断点在哪、用什么资源补、花了多久，只有亲历者能写。不要写成老师评价
选课经验（有了新去处）	上过这门课、并且愿意署名的人	一篇书信体：第一人称、写给学弟学妹、20–40 行，按你自己的年级和方向署名
校内系统的实际使用体验	长期用过校内 GitLab、校内 Overleaf、云盘、镜像站的人	容量、权限、常见报错各写一段就够；写法是注明适用年份 + 哪些以官方为准
某门课的学习路径	修过这门课的人	先修是什么、难点在哪、推荐的学习顺序；明确不要写成老师评价
院系差异	转过专业、辅修/双学位，或对比过不同院系培养方案的人	培养方案、转专业、辅修/双学位在不同院系的差别；注明年份与院系
实测与纠错	任何人	哪怕只是「这条链接死了」「这个门禁规定改了」，也算贡献，一两句话就行
进实验室的过程	在组里待过一段时间的人	怎么找到这个组、第一封邮件怎么发、进组后前两个月做什么——见怎么进实验室做科研
校园生活的具体点位	在校内生活的人	食堂、自习空间、运动场馆「什么时候去、什么体验」——名称与开放时间以当年官方为准
你所在院系的奖学金评定细则	手上有本院系当年细则（或公示件）的人	对象、名额、申请时间、兼得规则各摘一段就够；注明院系与适用学年——站上现在只有未央书院与工程物理系两个实例，见荣誉与奖学金怎么评
实践与志愿：一趟怎么走	当过实践支队长，或长期做志愿服务的人	从立项到报销、从报名到工时认定，各写一段流程与踩过的坑；金额与认定规则以当年官方为准
社工岗位「真实的一天」	在某个岗位上干满一年的人	写具体的事（这一年办了哪些活动、卡在哪、怎么解决的），不写对人或组织的评价——见社工体系
宣传岗「真实的一天」	干过一年以上宣传岗的人	这一年出了多少条推送、办过哪些活动、排版改了几版、踩过什么坑——见宣传与传播
本院系的宣传规范与素材	手上有本院系宣传规范、模板或素材库的人	字号配色规范、审批流程、素材来源各写一段；注明院系与适用年份，不要贴内部系统截图与未署名的他人作品
海外研修的当年细节	真走过当年流程的人	时间节点、签证材料与耗时、导师匹配节奏、课程冲突怎么解决——见海外科研实习 末尾的待填清单；注明适用年份

关于选课经验为什么单独列一条：/academics/course-decision/ 的「这一页还需要补什么」和这一节指向的是同一件事。选课建议本质上是主观而且有争议的，我们不打算把它压成一个「客观」结论——几篇彼此矛盾的署名经验放在一起，比一个匿名「编者按」有用。所以请写书信体，让读者对着你的处境去校准，而不是对着一个匿名的编者。

不确定怎么写就先看骨架页

那五篇骨架的正文里已经写好了「这一段该回答什么」，你只需要把答案填进去。填不出的条目就继续留空，不要猜。

投稿条件

• 匿名、署名都可以。真名、昵称、匿名学长 都行，署名只是方便读者判断可信度。
• 可以有个人观点和情绪。「我那年焦虑了三个月」比「要保持良好心态」有用。但制度性事实必须注明适用年份，并给出核实渠道（哪个官方页面、哪份通知）。
• 下面这些会被退回：涉及他人隐私、内部系统截图、对具体老师的指名评价的内容。完整清单见下一节。
• 可以很短。几段话、只写一件事都可以，不需要凑成一篇完整攻略。
• 「我不确定」是允许的——只要标出来。「这条我记不清是哪个学期了」比编一个看起来合理的数字好得多。

以上缺口的完整地图（含本站的各项债务清单和写作原则）在仓库根目录的 OUTLINE.md。想先看全貌再决定写哪一块，就从那里挑。

内容红线

投稿前请自查，以下内容会被直接退回：

• 内部系统的数据、截图、账号，或绕过权限的方法；
• 对具体老师的指名评价；
• 他人隐私（学号、成绩、联系方式、名单）；
• 违反校规的做法；
• 付费内容导流。

完整说明见免责声明与内容边界。

审稿约定

• 每篇至少 1 人 review 后才能合并。
• 涉及制度性事实（学分、截止日期、政策）的改动，reviewer 需要自己去官方渠道核实一遍，或者把相关内容标注成「待核对」。
• 内容过期时，优先更新并保留历史说明，而不是直接删除。

关于署名

你可以用真名、昵称，或者干脆匿名（authors: ['匿名学长']）。署名只是方便读者判断可信度，不是义务。