2. Quickstart — 5 分钟跑完一个完整流程

完成本页后，你会：建出一个 MoS2 单层 → 看它的配位 motif → 施 2% 应变 → 抠一个硫空位 → 出 VASP 输入。

0. 安装

git clone <repo> vasp-cli
cd vasp-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
mat --help

1. 起一个 run 目录

mat init -q

输出：

runs/001-run

-q 是 quiet，只输出主路径。这步同时把 runs/001-run 记进 ./.mat-context.json 作为"当前 run dir"——后面所有命令自动把产物写进去。

2. 造一个 MoS2 单层（3 token）

mat build mos2 -q

输出：

  artifacts: render=mos2.png  summary=mos2.summary.md
runs/001-run/mos2.vasp

stderr 上的 artifacts: 一行告诉你自动产出了什么。看看 run dir：

runs/001-run/
├── mos2.vasp           ← POSCAR
├── mos2.png            ← 自动渲染
└── mos2.summary.md     ← 文本摘要

打开 mos2.png：

紫色八面体清楚显示了 1 个 Mo 被 6 个 S 包围。

3. 看配位 motif（2 token）

mat motifs

输出：

✓ 1 motif(s)
  mos6_octahedral_0001     MoS6_octahedral        Mo[0]  cn=6  octahedral

这里没有传文件——mat motifs 自动用上一步建出来的 mos2.vasp（隐式 context）。

4. 施 2% 双轴应变（3 token）

mat strain 2% -q

输出：

  artifacts: render=mos2.strain2pct.png  summary=mos2.strain2pct.summary.md
runs/001-run/mos2.strain2pct.vasp

CLI 自动生成了带语义的文件名 mos2.strain2pct.vasp，新的"当前结构"也自动切到它。

5. 抠一个硫空位（3 token）

mat perturb vacancy=S:1 -q

输出：

  artifacts: render=mos2.strain2pct.S-vac.png  summary=...
runs/001-run/mos2.strain2pct.S-vac.vasp

可以看到八面体被打破了：Mo 现在只配位 5 个 S（之前 6 个）。再跑一次 mat motifs 验证：

mat motifs

motif label 会从 MoS6_octahedral 变成别的（例如 MoS5_square_pyramidal），这是 motif 抽象的强大之处——结构变了，标签自动变。

6. 出 VASP 输入（2 token）

mat /vasp-inputs create profile=mp-relax-pbe

会生成 INCAR / KPOINTS / POSCAR / POTCAR.spec 一套。

7. 看现在在哪（0 token）

mat

输出：

mat — motif-native materials CLI

  current: /.../runs/001-run/mos2.strain2pct.S-vac.vasp
  run dir: runs/001-run

common actions on current:
  mat motifs                              # list coordination motifs
  mat sites                               # list sites (cart + frac)
  mat /lattice get                        # lattice + vacuum + slab
  mat strain 2%                           # apply 2% biaxial strain
  mat vacuum 20                           # set vacuum to 20 Å
  mat perturb shift=top:0.1,0             # composite edits

mat（0 参数）等价于 git status：告诉你当前 context + 下一步可以做什么。

总结：6 条命令，全程不传文件路径

mat init -q
mat build mos2 -q
mat motifs
mat strain 2% -q
mat perturb vacancy=S:1 -q
mat /vasp-inputs create profile=mp-relax-pbe

run dir 里有完整的文本 + 视觉日志，任何人（或 agent）打开 runs/001-run/ 就能复原全过程。

---

下一步： Implicit context → 一次设定全程跟随