14. Skill for AI agents — 让 agent 像师兄一样跟你交互

这一章把 vasp-materials-thinking skill 整理成给人看的版本。

核心理念：让 agent 不是默默跑命令的脚本，而是会问、会确认、会给选项、会回滚的师兄。 研究员永远在驾驶座。

⚠️ 这个 skill 现在有独立仓库：https://github.com/AidenNovak/vasp-materials-thinking 本仓库 .opencode/skill/vasp-materials-thinking/ 是上游的 mirror，OpenCode 用户开箱即用。 修 bug / 加 feature 请去上游提 PR；其他 agent (Claude Code, Cursor) 也可独立装。

---

整体框架：5 步 + 4 个交互 checkpoint

用户开题
  │
  ▼
[A] 课题归类  ─► 🟢 CP-1 意图确认（≤3 个具体问题 + 默认配置）
  │
  ▼
[B] 结构选型  ─► 🟢 CP-2 结构预览（完整命令链 + 预计产出，等 ✓ 才跑）
  │
  ▼
[C] mat 命令链   ─► CP-2.5 实时进度（失败立即停）
  │
  ▼
[D] 三项自验
  │
  ▼
[E] 5 段式报告  ─► 🟢 CP-3 结果解读（含 PNG 里看到什么）
  │
  ▼
              🟢 CP-4 下一步菜单（2-5 选项 + 推荐 + 「我自己想想」出口）

4 个 checkpoint 的本质

CP	防止什么	给用户什么权力
🟢 CP-1	跑错方向（30 分钟白搭）	修正意图、给约束
🟢 CP-2	做错结构（cell、缺陷、终端选错）	看命令链 + 拦 / 改
🟢 CP-3	"完成了"信息密度太低	看到具体数字 + 图里看到啥
🟢 CP-4	"你自己想下一步" 甩手	看常走方向 + 自由出口

---

CP-1 实操：意图确认

Agent 输出格式：

🤔 帮我确认一下你的需求：

**我理解的是**：你想算 [复述原话]，对应 **[question type]** / **[2D|3D|slab]**。

**这几点我不确定**：
1. [Q1]?
   - 「选项 A」→ [后果]
   - 「选项 B」→ [后果]（我建议这个）
   - 不确定 → 走默认
2. [Q2]?（如有）
3. [Q3]?（如有）

**按默认我会做**：
- [decision 1]
- [decision 2]

铁律：≤ 3 个问题 / 每问必给候选 / 永远附默认配置。

---

CP-2 实操：结构预览

Agent 输出格式：

📐 我打算这样做：

| 维度 | 选择 | 理由 |
|------|------|------|
| 基底 | ... | ... |
| Cell | ... | ... |
| 真空 | ... | ... |
| 缺陷 | ... | ... |

我会跑这串命令：

\`\`\`bash
mat init -q
mat build mos2 -q
mat /structures update supercell=3,3,1 out=sc.vasp -q
mat perturb vacancy=S:1 sc.vasp out=def.vasp -q
\`\`\`

**预计产出**：3 个 .vasp + 3 个 .png + 3 个 .summary.md
**预计用时**：~5 秒

**确认这样做？**
- ✅ 「OK」/「跑」→ 我立刻开跑
- ❌ 改 X → 我改完再确认一次
- 🛑 「先别跑」→ 我等你

铁律：完整列出命令链 / 必须等到 ✓ / 用户改要求 → 改完重发 CP-2。

---

Step C 实操：命令链 + 实时进度

6 条铁律

1. 任何写结构的命令一律加 -q
2. 第一个命令永远是  mat init -q
3. 后续命令尽量不写 input 路径——CLI 自动用 current
4. 塞 LLM context 用 --json --jq 抽字段
5. 中间路径明确时：out=runs/NNN-XXX/<stem>.vasp
6. 长尾用 resource：mat /structures get、mat /vasp-inputs create

实时进度显示

⚙️ 跑命令中...

[1/4] mat init --label svac-mos2 -q     ✓ runs/001-svac-mos2
[2/4] mat build mos2 -q                  ✓ mos2.vasp + mos2.png
[3/4] mat /structures update supercell... ✓ sc.vasp + sc.png  
[4/4] mat perturb vacancy=S:1 ...        ✓ def.vasp + def.png

✓ 全部完成（用时 ~4 秒）

任一步失败 → 立即停下 → 报错 + 建议修复方案 → 等用户确认。

7 类 question type 对应命令链

defect

mat init -q
mat build mos2 -q
mat /structures update supercell=3,3,1 out=sc.vasp -q
mat perturb vacancy=S:1 sc.vasp out=def.vasp -q

adsorption

mat init -q
mat build slab=Pt(111) layers=4 vacuum=15 out=pt.vasp -q
mat /adsorbates create molecule=CO site=ontop:Pt:1 target=pt.vasp -q

interface

mat init -q
mat build bilayer layer1=mos2 layer2=hbn match=hex stack=AB -q

surface_slab

mat init -q
mat build slab=Pt(111) layers=4 vacuum=15 -q
mat /sites update freeze=layer:bottom:2 -q

strain

mat init -q
mat build mos2 -q
mat strain a:3%,b:-1% -q

bulk_ground

mat init -q
mat get mp-2815 -q
mat /vasp-inputs create profile=mp-relax-pbe

reproduce

mat init -q
mat reproduce <paper.recipe.yaml>

---

CP-3 实操：5 段式报告

## 📋 你的需求 → 我的理解
（1-2 句复述）

## 🧱 我构建的结构
| 项目 | 值 |
|------|-----|
| 化学式 | Mo₉S₁₇ |
| Cell | 3×3×1 supercell, 26 atoms |
| Lattice | a=b=9.49 Å, c=20.00 Å |
| 缺陷 | 1 个 S 空位 @ index 13 |
| 文件 | `runs/001-svac/def.vasp` |

## 🔢 关键数字
- 缺陷浓度: 5.6%
- 受影响 Mo: 3 个（配位 6→5）
- d(Mo-S): 2.39-2.41 Å

## 🖼️ 可视化
![def](runs/001-svac/def.png)

俯视图中央偏左有 1 个 S 原子缺失（图中较暗位置）；
侧视图：缺陷在上层 S 平面，下层完整。

## 🎯 关键发现 / 注意点
- 缺陷局部对称性 D₃ₕ → C₃ᵥ，预期带隙内态
- POSCAR 排序 Mo (9) + S (17) ✓
- 未弛豫，下一步必须先 relax

段 4 铁律：agent 已经看过图，写"图里看到 X"，不要"请查看 PNG"。 段 5 铁律：物理 insight，不是 generic 警告。

---

CP-4 实操：下一步菜单

## 🎯 下一步你想做什么？

**[1] 跑结构弛豫**（推荐）
   \`\`\`bash
   mat /vasp-inputs create profile=mp-relax-pbe target=def.vasp
   \`\`\`
   收敛标准：力 < 0.01 eV/Å。

**[2] 准备对照组**（完美 supercell）

**[3] 扫描不等价 S site**

**[4] 换参数重做**

**[5] 我想自己想想，先停在这里**

你选 **[?]** ？或用自然语言告诉我也行。

铁律：2-5 选项 / 第 1 个推荐 / 必须有「我自己想想」/ 接受自然语言。

---

完整多轮对话示例

3 个真实场景，含用户中途改要求 / agent 主动给方法学预警：

• Example 1 — 缺陷：MoS₂ S 空位（用户改 cell 5→3 回滚）
• Example 2 — 吸附：CO 在 Pt(111) 多位扫描（批量任务）
• Example 3 — 异质结：MoS₂/hBN moiré（vdW 预警）

---

怎么给 agent 装这个 skill

OpenCode（原生支持，最简单）

clone nku-vasp-cli 仓库时 skill 已经在 .opencode/skill/vasp-materials-thinking/，启动 OpenCode 自动加载。

或独立安装：

curl -fsSL https://raw.githubusercontent.com/AidenNovak/vasp-materials-thinking/main/install.sh | bash

Claude Code

INSTALL_DIR=~/.claude/skills \
  curl -fsSL https://raw.githubusercontent.com/AidenNovak/vasp-materials-thinking/main/install.sh | bash

Cursor / 其他 agent

把这段贴进 system prompt：

你装有 nku-vasp-cli（命令叫 mat）。
处理任何 VASP / DFT / 材料任务，按 vasp-materials-thinking skill 的 5 步 + 4 checkpoint：

[A] 内部判定 question type（7 类）+ 2D/3D
🟢 CP-1 输出意图确认（≤3 问 + 选项 + 默认配置），等用户回
[B] 内部选 cell / 真空 / 缺陷 grammar
🟢 CP-2 输出结构预览（含完整命令链 + 预计产出），等 ✓
[C] 跑 mat 命令链（每步 -q，第一步 mat init -q），实时报进度
[D] 自验 3 项（文件存在 / summary 读得通 / motif 配位一致）
🟢 CP-3 输出 5 段式报告（意图 / 结构表 / 数字 / 图+解读 / 注意点）
🟢 CP-4 输出下一步菜单（2-5 选项 + 推荐第 1 个 + 「我自己想想」出口）

铁律：
- 任何 CP 没 ✓ 不要往下走
- 跑命令一律 -q
- PNG 必须自己看，写"图里看到 X"，不要"请查看 PNG"
- 任何错误立即停，问研究员

完整说明：https://github.com/AidenNovak/vasp-materials-thinking

---

反例：什么算"做得不好"

❌ Bad	✅ Good
跳过 CP-1 直接 mat build mos2	先问"缺陷还是带隙？"
CP-2 藏命令	完整列出整条命令链
不等 ✓ 直接跑	等到用户说"OK 跑"
失败 silent fail	立刻停下，问"要改还是回滚"
CP-3 写"请查看 PNG"	"图里中央偏左缺一个 S 原子"
CP-4 只写"完成了"	给 2-5 个常走方向 + 推荐

---

仓库 + 协议

项目	URL
Skill 独立仓库	https://github.com/AidenNovak/vasp-materials-thinking
本仓库 mirror	.opencode/skill/vasp-materials-thinking/
同步脚本	scripts/sync-skill.sh
License	AGPL-3.0-or-later（跟 nku-vasp-cli 同协议）
商业授权	COMMERCIAL.md

欢迎 PR：新 question type / 新领域 example / 更细话术 / 翻译。