写作与格式规范
本仓库所有 Markdown 内容（README、docs/、blogs/）遵循本规范。提交前运行 python scripts/lint_md.py 检查格式问题。
文档应放在哪里、是否需要新增目录，以及模型收录和维护流程，统一见 贡献规范。本文件只维护写作与格式细则。
一、文风
目标是让读者觉得这是一位研究者写的笔记，而不是营销文案。
1. 用事实和数字说话
- 用具体数字代替形容词。写“HR MAE 3.9 bpm”，不写“高保真心率估计”；写“编码器 0.31M 参数”，不写“极致轻量”。
- 论文结论要标明来源：“作者报告……”“论文在 PTB-XL 上得到……”。论文的说法和自己的判断分开写，后者放在“评注”里。
- 只写能在论文、官方代码仓或数据集页面查到的信息。查不到的字段留空；“未公开”须有作者声明等依据，不用它代替未知。
2. 禁用和慎用的词
| 类别 | 词语 | 处理方式 |
|---|---|---|
| 禁用 | 神级、巨座、颠覆、革命性、降维打击、解毒、完美、极致、终局、天花板 | 删除，改为具体描述 |
| 禁用 | 旗舰、黄金（标准/底座）、标杆、里程碑、重磅 | 删除；“金标准”仅用于医学上的 gold standard |
| 慎用 | 首个、首创、首次 | 仅在论文本身如此声称时使用，写作“作者称其为首个……” |
| 慎用 | 全面超越、显著提升、彻底解决 | 换成具体指标和对比对象 |
| 慎用 | 核心、深度、全景、前沿 | 一段内最多出现一次，标题中尽量不用 |
3. 句子和段落
- 一个段落讲一件事。列表不超过 6 项，超过就拆分或改成表格。
- 不堆砌定语。写“MC-MED（Stanford 急诊监护数据，约 11.8 万次就诊）”，不写“千万级真实急诊多模态重症高精数据库”。
- 机构写正式名称即可，不加头衔和评价（如“某某开创者”“顶级团队”）。
- 术语首次出现写“中文（English, 缩写）”，之后用缩写。
- 默认不用 emoji，包括标题、表格、列表和状态标记。唯一例外是 README 的“打开交互式网页版”入口，可在链接文字前加一个
🌐，突出交互阅读入口；其他位置保持克制。 - 不加“已核实”“经验证”一类标记。正确是默认要求，不需要声明。
4. 面向读者写结论
首页帮助读者理解研究、找到资料；维护流程写在贡献规范中。
- 删除“不能据此判断……”等泛化免责句。影响理解的限定写成具体事实，例如“摘要报告 1,596 万实例，正文为 1,580 万”；保留评测条件、数据划分、许可与访问限制。
- 不向读者解释生成或维护机制，例如“日期优先采用
updated，否则采用added”。这类说明放在CONTRIBUTING.md、脚本或 HTML 注释里。 - 公开正文不写对话、检索过程或任务进度，例如“本轮检索”“沿用并修正”“未取得全文”“后续决定是否收录”。工作记录放在本地
internal_strategy/；相关研究保留来源和研究内容，影响复现的证据缺口写成具体的协议或资源限制。 - 站内专题不添加“欢迎交流与共建”等回流卡片；共建入口由网页统一导航提供。此类卡片只用于面向站外平台的文章。
- 首页参数量、代码、权重缺失时省略对应项，不反复填“未报告”“未列”，也不用“紧凑级”“轻量级”“工业级”代替数字。专题可说明有研究价值的证据缺口。
- 表格单元格不写“见专题”“统计口径见专题”。每行已链接专题，差异在专题正文中说明。
- 同一概念全仓只用一个说法。资源状态的固定写法见“五、收录信息”。
二、Markdown 格式
GitHub 使用 CommonMark/GFM 渲染。中文排版有几类常见的渲染失败，下面逐条说明。
1. 加粗：首尾不放标点
CommonMark 判断 ** 能否闭合时会看两侧字符。加粗内容以标点开头或结尾、而外侧紧挨着汉字或字母时，加粗会失效，页面上直接露出 **。
| 错误写法 | 正确写法 |
|---|---|
模型提出了**“分辨率假说”**并验证 |
模型提出了“**分辨率假说**”并验证 |
首创**解耦预测跨度（DHF）**与时间注意力 |
提出**解耦预测跨度**（DHF）与时间注意力 |
参数量为**0.72M。**下游 |
参数量为 **0.72M**。下游 |
规则：加粗内容的第一个和最后一个字符不能是标点（括号、引号、冒号、句号、百分号等）。把标点移到 ** 外面即可。
加粗用于关键数字或术语，每段最多一处，不加粗整句，标题内不加粗。
2. 波浪号、美元符号和公式
- 范围用短横线或全角波浪号：
3-4 mmHg、10～15 min。不要用半角~，GitHub 会把成对的~渲染成删除线。 - 近似值写“约”：
约 1.5M，不写~1.5M或\~1.5M。 - 简单符号用 Unicode：
→、≤、≥、×、±。不写$\to$、$\le$。 - 只有真正的公式才用 LaTeX。行内公式用
$...$；独立公式的$$各占一行，前后空行。 - 正文中的美元符号写成
\$。
3. 标题
- 标题里不放 emoji、加粗和句末标点；README 网页入口的单个图标例外见上文。
- 模型小节的标题只写模型名，例如
### PaPaGei。机构、年份、链接放在标题下的信息行里。这样锚点稳定（#papagei），改描述也不会弄断别处的链接。 - 不用“——”接一长串副标题。
4. 列表、表格和提示框
- 列表、表格、代码块、标题前后都留一个空行。
- 嵌套列表统一缩进 2 个空格。
- 表格单元格里的竖线写成
\|，换行用<br>。表格不超过 8 列，过宽就拆成两张。 - GitHub 提示框（
> [!NOTE]等）只能放在顶层，放进列表里不会渲染。整篇最多用 2-3 个。
5. 链接
- 仓库内的文件一律用相对路径，例如
`[睡眠专题](docs/models/sleep_models.md#sleepfm)`。不要写file:///或本机绝对路径。 - 汇总、选型和比较表中，用作行标识或比较列标题的模型、论文、基准与数据集名称统一写成
[**名称**](#小节锚点)，跨专题使用相对文件路径加锚点。同一格有多个不同条目时分别链接，机构、年份与评测设置留在链接外；正文说明中的名称不必重复加链。 - 链接指向已有的对应介绍；本页没有详细介绍时，链接主要维护专题的小节。没有对应小节的条目保留文字或已有论文入口，不为补链接新建空小节，也不链接到无关模型。
- 论文优先链接 arXiv abs 页或 DOI，不直接链接 PDF。
- 锚点按 GitHub 规则生成：小写，去掉标点，空格变
-。scripts/lint_md.py会检查仓库内的锚点是否存在。
6. 中英文混排
- 中文与英文、数字之间加一个空格：
使用 PPG 信号、共 57,000 小时。 - 数字与单位之间加空格：
100 Hz、5 min。百分号和度数除外：42%、37°C。 - 中文句子里用全角标点（，。：；“”（））。括号内全是英文时可以用半角括号。
三、图片
1. 数量
- 每个模型小节尽量放一张图，首选论文里的总览图或架构图。
- 有必要时可以再放一张关键结果图。整个小节不超过 3 张。
- 图要跟正文对得上，不放装饰性图片。论文内容不使用 AI 生成的示意图。
2. 来源和署名
- 来源优先级：论文原图（arXiv 版本）> 官方项目页或 GitHub README > 自绘。
- 图下一行写来源，格式为：
图源：PaPaGei 论文 Fig. 1（arXiv:xxxx.xxxxx）。 - 自绘的流程图或架构图用 Mermaid 编写并渲染成 PNG，源码和图片一起提交。
首页地图采用白底、中性灰和单一低饱和强调色。研究路线用卡片分区，卡片内用小模块区分模态与模型；辅助主题各占一块，不合并成长条文字。层级首先由留白、对齐、字号和边框表达，颜色用于少量强调。在约 900 px 的首页阅读宽度下检查正文，避免靠缩小字体容纳更多模型。
Mermaid 节点内的 HTML 样式使用 rgb(...) 指定颜色，避免十六进制颜色与分号被解析为实体；classDef 的颜色仍可用十六进制。
3. 文件
- 论文图片放在
docs/figures/<model-id>/，<model-id>与data/models.yaml中的id一致。README 用的图放在assets/。 - 文件名用小写字母和短横线，例如
overview.png、architecture.png、results-ptbxl.png。 - 论文裁图宽度不超过 1600 px，单张不超过 500 KB。首页地图按 1200 px 逻辑宽度导出 2x PNG，保留 SVG。线条图用 PNG，照片用 JPG。
- 用
python scripts/figures.py crop ...从论文 PDF 裁图，脚本会自动缩放和压缩。论文 PDF 放在本地papers/目录，不提交。
四、模型小节模板
### PaPaGei
Nokia Bell Labs · ICLR 2025 · [论文](https://arxiv.org/abs/xxxx.xxxxx) · [代码](https://github.com/xxx) · [权重](https://zenodo.org/xxx)
图源：PaPaGei 论文 Fig. 1（arXiv:xxxx.xxxxx）
一两句话说明模型是什么、解决什么问题。
**方法**
- 要点一
- 要点二
**结果**
- 作者报告的关键指标，注明数据集和对比对象
**评注**
自己的判断：适用场景、局限、和其他模型的关系。没有就不写。
“方法”“结果”“评注”这些小标签可以按内容增减，不强求三段齐全。
五、收录信息
模型和数据集的元数据统一维护在 data/models.yaml 和 data/datasets.yaml，README 中的索引表由 python scripts/build_tables.py 生成，不要手动编辑 README 里标记为自动生成的区块。
资源栏只使用以下写法，由 build_tables.py 根据字段生成：
| 情况 | 字段 | 显示 |
|---|---|---|
| 有公开链接 | paper、code、dataset、weights |
论文、代码、数据、权重 |
| 权重有许可限制 | weights + weights_label |
学术用途权重、非商用权重 |
| 权重需申请 | access: gated |
权重需申请（有入口则链接） |
| 作者已声明将发布 | access: planned |
权重待发布；无代码时为代码与权重待发布 |
| 无权重入口 | weights 留空且非待发布或申请状态 |
省略权重项 |
参数量或数据规模查不到时字段留空，表格中不显示该行。
新增一个模型的步骤：
- 在
data/models.yaml末尾添加条目，added填当天日期。 - 在对应专题文档中添加模型小节，按需放图。
- 运行
python scripts/build_tables.py和python scripts/lint_md.py。