10. Agent recipes — 给 agent 的可复用调用模式

本页给"用 LLM agent 驱动 mat"的人——把若干高频任务写成可复用 prompt + CLI 模板，agent 直接套。

通用 agent 调用规则（建议放在 system prompt 里）

You are using `mat`, an agent-first materials CLI.

Hard rules:
1. Use `-q` on any step that writes a structure to keep output to one line.
2. After every structure-changing command, the CLI auto-emits:
     <stem>.png        ← read this if you need to verify visually
     <stem>.summary.md ← read this for formula/lattice/motifs/sites
3. Do not re-pass file paths once a structure has been produced; the CLI
   remembers the "current structure" automatically.
4. To trim output for context, prefer `--json --jq EXPR` over default text.
5. To inspect what you've done, use `mat` (zero-arg) for a status line.

Capability map:
- Build a structure              → mat build <alias|kind> [strain= vacuum= out=]
- Look at it                     → mat get  |  mat motifs  |  mat sites
- Modify lattice                 → mat strain <spec>  |  mat vacuum <Å>  |  mat recenter
- Edit atoms                     → mat perturb <ops...>  (vacancy/substitute/displace/shift/rotate/...)
- Long-tail capabilities         → mat /<resource> <verb>
- Generate DFT input             → mat /vasp-inputs create profile=mp-relax-pbe
- Run a paper recipe             → mat reproduce x.recipe.yaml
- Available material shortcuts   → mat materials
- Full help                      → mat --help

Recipe 1：缺陷形成能 ladder（同种缺陷不同位置）

意图："给我 MoS2 supercell 里所有不等价 S 空位的候选结构。"

mat init --label s-vacancies -q
mat build mos2 -q
mat /structures update supercell=3,3,1 out=runs/001-s-vacancies/sc.vasp -q
mat sites element=S --json --jq '.[].index' > runs/001-s-vacancies/s_idx.json
# agent 读 s_idx.json，对每个 index 跑：
for i in $(cat runs/001-s-vacancies/s_idx.json | python -c 'import sys,json;[print(i) for i in json.load(sys.stdin)]'); do
  mat perturb vacancy=index:$i runs/001-s-vacancies/sc.vasp out=runs/001-s-vacancies/vac-$i.vasp -q
done
ls runs/001-s-vacancies/vac-*.png        # 每个候选自带渲染

agent 直接看 PNG 选出"对称等价"的那几组只保留代表。

Recipe 2：strain–motif relation 扫描

意图："看应力对 MoS2 八面体 Mo–S 键长的影响。"

mat init --label strain-scan -q
for p in -3 -1 0 1 2 3 5 7; do
  mat build mos2 strain=${p}% out=runs/001-strain-scan/mos2-s${p}.vasp -q
  mat /motifs list runs/001-strain-scan/mos2-s${p}.vasp --json \
      --jq '{strain:'"${p}"', motif:.[0].label, cn:.[0].cn, bonds:.[0].bond_lengths}' \
      >> runs/001-strain-scan/sweep.jsonl
done
cat runs/001-strain-scan/sweep.jsonl

输出是 JSONL，每行一组 (strain, motif, bond)。agent 直接拼图。

Recipe 3：bilayer 错位扫描（moiré 起点）

意图："看双层 MoS2 横移 0.1 Å 步长下层间距、motif 怎么变。"

mat init --label bilayer-shift -q
mat build mos2 -q
cp runs/001-bilayer-shift/mos2.vasp runs/001-bilayer-shift/a.vasp
cp runs/001-bilayer-shift/mos2.vasp runs/001-bilayer-shift/b.vasp
mat build bilayer runs/001-bilayer-shift/a.vasp runs/001-bilayer-shift/b.vasp interlayer=6.5 \
    out=runs/001-bilayer-shift/bi.vasp -q
for dx in 0 0.1 0.2 0.3 0.5 1.0; do
  mat perturb shift=top:${dx},0 runs/001-bilayer-shift/bi.vasp \
      out=runs/001-bilayer-shift/shift-${dx}.vasp -q
done
ls runs/001-bilayer-shift/shift-*.png    # 全部错位 PNG

Recipe 4：异质双层适配（不同晶格匹配）

mat init --label hetero -q
mat build mos2 -q                                          # MoS2: a=3.16
mat build hbn -q                                           # hBN:  a=2.504
mat strain a:5%,b:5% runs/001-hetero/hbn.vasp \
    out=runs/001-hetero/hbn-stretched.vasp -q              # 把 hBN 拉到匹配
mat build bilayer runs/001-hetero/mos2.vasp \
    runs/001-hetero/hbn-stretched.vasp interlayer=3.4 \
    out=runs/001-hetero/mos2-hbn.vasp -q

Recipe 5：DFT-ready 流水线（造结构 → 校验 → 出 VASP 输入）

mat init --label dft-pipeline -q
mat build mos2 strain=2% vacuum=22 recenter=z -q
mat verify <structure.vasp>  --rules rules/2d-mos2.yaml  # ✓ pass / ✗ fail
mat motifs --json --jq '.[].label' > runs/001-dft-pipeline/motifs.json
mat /vasp-inputs create profile=mp-relax-pbe \
    out=runs/001-dft-pipeline/vasp-inputs/
ls runs/001-dft-pipeline/vasp-inputs/                  # INCAR KPOINTS POSCAR POTCAR.spec

Agent 应对错误的标准动作

当 mat 报错，stderr 是结构化的：

error: 2D safety violation: vacuum 5.2 Å < 8 Å minimum
  hint: pass force=1 to bypass (not recommended for production)

Agent 的策略：

1. 读错误信息和 hint
2. 如果是物理约束 → 调整参数（如这里改 vacuum=20 而不是 force=1）
3. 如果是路径/参数错误 → 跑 mat <command> --help 看 usage
4. 如果是 motif 检测失败 → 跑 mat motifs --json 看 raw 数据决定

Agent 应对模糊任务的标准动作

用户说 "做一个有缺陷的 MoS2 异质结"——任务模糊。agent 应：

1. 先 mat 看 context 知道当前在哪
2. 询问 / 假设关键自由度：哪一层有缺陷？什么缺陷？supercell 大小？
3. 跑最小版本 给用户看 PNG 确认走向
4. 基于反馈 跑全规模

Token 预算参考

操作	输出 token（默认）	输出 token（-q）	JSON
mat build mos2	~50	~5	~100
mat motifs	~80	—	取决于 motif 数
mat /lattice get	~80	—	~120
mat sites (3 atom)	~60	—	~200
mat sites (300 atom)	~50 (截 20 行)	—	巨大 → 用 --jq 裁

经验法则：默认输出适合人类 + agent 直接读；--json --jq 用于 agent 之间串联。

---

下一步： VASP inputs & paper recipes → 上游连接 DFT