mat — Documentation

Agent-first materials CLI. 把构造、扰动、解释 2D 材料和催化界面的全部原子级操作压缩到 1–4 个 token 的命令里，并自动产出 PNG + summary.md 让多模态 agent 直接看图自检。

导览

	文档	谁应该看
1	Overview — 为什么是 agent-first	第一次接触、想理解设计哲学
2	Quickstart — 5 分钟跑完一个完整流程	直接想试
3	Implicit context — 一次设定全程跟随	写 agent 自动化
4	Build — 8 种 builder + 9 种 material 别名	要造结构
5	Motifs — 配位环境抽象 + connectivity graph	要看 / 验证局部环境
6	Lattice ops — strain / vacuum / recenter	要改晶格
7	Perturb — 缺陷、掺杂、错位、层间	要造缺陷 / 改界面
8	Resource layer — RESTful 路径覆盖长尾	找不到对应 command 时
9	Auto-artifacts — PNG + summary.md 机制	想知道每步产物是什么
10	Agent recipes — 给 agent 的可复用调用模式	给自己的 agent 写 prompt
11	VASP inputs & paper recipes — 上游连接 DFT	要往 DFT 算或复现论文
12	Reference — 全部命令、资源、flag 速查	当词典查
13	Complex gallery — 10 个复杂界面/表面/缺陷案例	真实项目里的复杂场景

---

一图看全 CLI 的两层结构

┌─────────────────────────────────────────────────────────────┐
│  COMMAND 层（高层意图，无 / 前缀）                          │
│                                                             │
│   mat init      mat build      mat get      mat list        │
│   mat motifs    mat sites      mat strain   mat vacuum      │
│   mat perturb   mat verify     mat explain  mat reproduce   │
│                                                             │
│   → 给人和 agent 读最方便                                   │
└─────────────────────────────────────────────────────────────┘
                          ↓ 内部 delegate
┌─────────────────────────────────────────────────────────────┐
│  RESOURCE 层（RESTful 路径，有 / 前缀）                     │
│                                                             │
│   mat /structures  list|get|create|update|delete  ...       │
│   mat /motifs      list|get                       ...       │
│   mat /lattice     get|update                     ...       │
│   mat /sites       get|update|create              ...       │
│   mat /defects     create                         ...       │
│   mat /bilayers    update                         ...       │
│   mat /adsorbates  create                         ...       │
│   mat /vasp-inputs create                         ...       │
│   mat /runs        list|get|create|delete         ...       │
│   mat /recipes     list|get|run                   ...       │
│   mat /mp          list                           ...       │
│                                                             │
│   → 5 个动词覆盖所有长尾，学一个就会全部                    │
└─────────────────────────────────────────────────────────────┘
                          ↓
              所有 verb 都支持以下 flag：
              --json   --jq EXPR   -o PATH   -q

一图看全 auto-artifact

┌──────────────────┐    write    ┌──────────┐
│ mat build mos2   │ ──────────► │ mos2.vasp│
└──────────────────┘             └──────────┘
         │
         │ context.set_current()
         ▼
┌────────────────────────────────────────────┐
│ artifacts.emit_for(path)                   │
│   ├─ render PNG (matplotlib + motif poly)  │
│   └─ write summary.md (formula/lat/motifs) │
└────────────────────────────────────────────┘
         │
         ▼
┌────────────────┐  ┌────────────────────┐
│ mos2.png       │  │ mos2.summary.md    │
└────────────────┘  └────────────────────┘
   多模态 agent 看      文本 agent 看