8. Resource layer — RESTful 路径覆盖长尾

为什么有 resource 层

如果每个能力都做成一个 command，CLI 一年就有 60+ 子命令。gh api repos/{owner}/{repo}/issues/{n} 用 RESTful 路径解决这个问题——mat 学这个思路。

通用语法

mat /<path>/<id>?/<sub-path>?  <verb>  [key=value ...]  [--flag ...]

• /<path> 资源名（以 / 开头明确表示路径，不是 command）
• <id> 可选，定位单个实例（如 /mp/mp-2815）
• 动词收敛到 5 个：list / get / create / update / delete（/recipes 多一个 run）
• key=value 资源参数
• --flag CLI 行为（--json --jq --quiet --output）

全部资源

路径	缩写	动词	用途
/structures	/s	get / create / update / delete	读结构 + 通用 transform (supercell, substitute)
/motifs	/m	list / get	列 / 取 motif
/motifs/graph	—	get	motif 间 corner/edge/face-sharing
/lattice	/l	get / update	晶格 + 2D vacuum/slab，update 接 strain= vacuum= recenter=
/sites	/si	get / update / create	原子级编辑（绝对坐标）
/bilayers	/b	update	层操作 (shift / rotate / interlayer)
/defects	/d	create	缺陷 (vacancy / substitute / displace)
/adsorbates/sites	—	list	列吸附位 (ontop / bridge / hollow)
/adsorbates	/a	create	加吸附物
/vasp-inputs	/v	create	出 INCAR/KPOINTS/POSCAR/POTCAR.spec
/runs	/r	list / create / get / delete	run 目录管理
/runs/<id>	—	get / delete	单个 run 的 provenance
/recipes	/rec	list / get / run	论文复现 recipe
/mp	—	list	Materials Project 筛选
/mp/<id>	—	get	取单个 MP entry

5 个动词的语义

verb	语义	例子
list	列多个	mat /motifs list center=Mo
get	取一个详情	mat /lattice get
create	创建新东西	mat /defects create vacancy=S:1
update	改一个东西	mat /lattice update strain=2%
delete	删除	mat /runs/001-demo delete

学会一个资源，就基本会全部——这是 RESTful 最大的好处。

全部 IO flag（所有 verb 都支持）

flag	作用
--json	输出 JSON 而不是人类可读文本
--jq EXPR	用 jq 表达式裁剪 JSON（裁剪发生在 stdout 之前，节省 token）
-o PATH	写文件而不是 stdout
-q	quiet 单行（只输出主标识符）

6 个典型 resource 调用

1. 列结构里所有八面体

mat /motifs list geometry=octahedral --json --jq '.[].center_index'

2. 看晶格的真空层（只要这一个字段）

mat /lattice get --json --jq '.vacuum'

3. 把 0 号原子 z 坐标设为 7.5

mat /sites update set=0=z:7.5

4. 加一个 O 原子在某位置

mat /sites create species=O pos=2.5,1.4,9.0

5. 拿 MP-2815 的结构

mat /mp/mp-2815 get -o mp2815.vasp

6. 列所有 motif 间的 corner-sharing 边

mat /motifs/graph get --json --jq '.[]|select(.mode=="corner")'

缩写一览

/m     = /motifs
/s     = /structures
/l     = /lattice
/r     = /runs
/a     = /adsorbates
/d     = /defects
/b     = /bilayers
/si    = /sites
/v     = /vasp-inputs
/rec   = /recipes

只缩写资源，不缩写 command（学 gh 的做法，避免 gh r c 这种猜不出来的形式）。

command 与 resource 的关系

简单 mapping：

Command（高频，短）	等价 Resource（长尾，明确）
mat get foo.vasp	mat /structures get foo.vasp
mat motifs	mat /motifs list <current>
mat sites	mat /sites get <current>
mat strain 2%	mat /lattice update strain=2%
mat vacuum 20	mat /lattice update vacuum=20
mat perturb vacancy=S:1	mat /defects create vacancy=S:1
mat reproduce x.recipe.yaml	mat /recipes run path=x.recipe.yaml

写交互用 command（短），写脚本/recipe 用 resource（明确不歧义）。

如何发现资源

mat --help                                # 列全部 command + 全部 resource
mat /                                     # 仅列 resource
mat /<path> --help                        # 单个资源的帮助

资源以表格输出，扫一眼就知道每个支持什么 verb。

---

下一步： Auto-artifacts → PNG + summary.md 机制