卡片文档编写规范

目标：让新用户能够从“我手上有什么结构”一路走到“我应该选哪张卡、怎么设参数、怎么判断结果是否合理”。

语言规范

正文使用中文，必要术语可保留英文。
字段名、serialized key、class 名保持与代码一致。
参数建议尽量写成“场景 + 量级 + 风险”，不要只写抽象形容词。

必备章节

每张卡片页必须按以下顺序组织：

功能说明
操作示例
适用场景与不适用场景
输入前提
参数说明（完整）
推荐预设（可直接复制 JSON）
推荐组合
常见问题与排查
输出标签 / 元数据变更
可复现性说明

操作示例模板

## 操作示例 是强制章节，必须至少包含以下 6 个标签：

场景
输入
目标
参数设置
输出
怎么验证结果合理

推荐写法：

## 操作示例

### 场景：为 Si 小胞补充室温附近扰动样本

**输入：** 已弛豫的 8 原子 Si 单胞

**目标：** 生成 50 个轻微扰动构型，用于近平衡训练

**参数设置：**
- `scaling_condition = [0.05]`
- `num_condition = [50]`
- `engine_type = 0`

**输出：** 50 个带扰动标签的结构；主拓扑保持不变

**怎么验证结果合理：**
- 抽查最短键长没有明显缩到非物理区间
- 角度和体积变化没有超出本轮训练目标
- 若输出为空或重复度过高，先回调主控参数

额外输入模板

如果一张卡除了控件参数外，还依赖输入结构里额外携带的数组、标签或元数据，文档里不能只写“需要提前准备好输入”，必须补一个可复制的输入模板。

建议放在 ## 输入前提 下，用 ### 额外输入模板（...） 小节写清楚：

这些额外信息实际存在哪里，例如 atoms.arrays['group']、EXTXYZ 附加列、结构标签或其他 metadata。
代码实际接受哪些字段名或别名，不要只写概念词。
一个最小可复制示例，优先给 .xyz/.extxyz 的 EXTXYZ 风格模板；如果普通三列 XYZ 不支持，也要明确写出来。
单位说明和联动关系，例如“min_frequency 直接按输入频率单位筛选，不做自动换算”。
缺失或格式错误时程序的真实行为，例如返回空结果、返回原结构或发 warning。

参数说明写法

继续沿用“每个参数一个 ### block”的写法，不改成大表格。

每个参数 block 至少保留以下字段：

UI Label
字段映射 (Field mapping)
控件标签 (Caption)
控件解释 (Widget)
类型/范围 (Type/Range)
默认值 (Default)
含义 (Meaning)
对输出规模/物理性的影响

然后按参数类型补充：

数值或枚举参数：必须有 物理直觉 / 典型值
有条件生效、互斥或覆盖关系的参数：必须有 参数联动 / 生效条件
布尔或字符串参数：必须有 怎么判断该开还是该关

建议原则：

数值参数写清量级感，例如“0.02 表示约 2%”“10-15 Å 常用于隔离 slab 镜像”。
模式参数写清楚“谁和谁互斥”“谁开启后谁失效”“谁只是下游辅助字段”。
不要只写“保守 / 平衡 / 探索”，要补上用户可判断的物理或工程信号。

常见问题与排查

常见问题与排查 至少覆盖以下 3 类问题：

输出为空时最常见的原因
输出结构不合理时如何判断与回调
参数越界、模式冲突或条件不满足时程序的实际行为

描述程序行为时，只能写代码当前真实行为：

UI 限制
运行时回退
返回原结构
返回空结果
发送 warning / message

不要臆造不存在的自动修复逻辑。

入口页与 Recipes

index.md 必须提供“按目标选卡”决策表和“易混卡片对比”。
recipes.md 必须提供完整 step-by-step workflow，而不是只列卡片名。
recipes 第一版采用纯文本 + 可复制 JSON + 每步预期输出，不要求截图。

关键校验

Default 必须与运行时代码默认值一致。
空值必须写 "" 或 null。
禁止 (empty) 占位写法。
字符串枚举与数字必须严格区分。
source_file、文档文件名和在线文档 URL 映射必须保持稳定。

禁止内容

只说“先保守再放大”的空泛快速上手句式。
与卡片无关的统一 Physics caution 模板句。
没有具体对象的泛化推荐组合。
没有输入、目标和验证条件的“伪示例”。

维护命令

python tools/docs/audit_card_docs.py
python -m sphinx -W -b html docs/source docs/build/html