| name | catgo-campaign |
| description | Run a CatGo file-first md-orchestration "campaign" — a multi-step / high-throughput computational-materials study (e.g. SAA HER screening) driven from a human-readable folder + markdown tree, not the DB workflow engine. Use when the user says "跑一个 campaign", "md 模式跑", "high-throughput screening", or wants an agent-in-the-loop study with stages/funnel/analysis/report. Requires `catgo` on PATH. |
catgo-campaign — run a file-first computational campaign
A "campaign" = a coordinated multi-step study (many calculations → analysis → report)
toward one research goal. This skill drives it via the portable catgo campaign CLI,
which dispatches to CatGo's campaign reference scripts.
Launcher (works from any directory)
Run via the catgo CLI:
catgo campaign <action> ...
With an editable install (pip install -e <repo>/server) the CLI reflects the LIVE repo
source, so edits to the campaign scripts/SKILL take effect immediately, no reinstall.
If catgo is not on PATH (env not activated), use the entry point inside its python
env directly: <env-prefix>/bin/catgo campaign ....
In the steps below, catgo campaign means that launcher.
Before anything: confirm the environment (NEVER guess)
Ask the user and record in cluster.md: which cluster + SSH host/account +
partition/walltime/ntasks, the compute binary + load method (module/conda/full path +
run command), the POTCAR/pseudopotential root, the python env, and the remote base dir.
The user may give a reference job script (local or a path on the cluster — pull it with
catgo campaign fetch-ref). catgo campaign submit REFUSES until cluster.md is
complete. A wrong path fails every job — if unsure, STOP and ask.
Steps
-
Scaffold at the user's chosen location:
catgo campaign new /path/to/Project --name "<name>" --template saa_her|blank
-
Plan — ASK the user: brainstorm the plan together (literature-grounded, one
question at a time, propose approaches) OR use the template / generate directly.
-
Reference script (optional): catgo campaign fetch-ref --project <dir> --ssh <alias> --remote_path <.sb>
-
Per calc: build inputs into the LOCAL calc folder, then the input-file gate (below),
then catgo campaign submit --project <dir> --calc calc/<stage>/<candidate> --ssh <alias>
(skip the gate only on explicit YOLO opt-in).
⛔ INPUT-FILE GATE (hard rule — catgo-campaign + autochem). Before ANY submit (and after a
calc converges, before building the NEXT step's inputs): sync the CONTCAR and the INCAR to
the LOCAL campaign folder, and tell the user the exact LOCAL file paths of the INCAR +
CONTCAR. The user reviews / edits / confirms the files THEMSELVES on disk. Submit ONLY after the
user explicitly confirms. Do NOT push structures to the CatGO viewer as a substitute for
local-file review of inputs, and NEVER auto-submit. (Waived only by explicit YOLO.)
-
Loop (~10 min, user-triggered): catgo campaign poll --project <dir> --ssh <alias>
marks DONE/FAILED via squeue→sacct. A scheduler DONE != converged — open the
work_dir outputs to confirm, write numbers into the calc's result.md, log gotchas
in LESSONS.md.
-
At a stage / decision point: catgo campaign aggregate --project <dir> --plot
(ranking / volcano / funnel), then checkpoint with the user.
-
Report: catgo campaign report --project <dir> --occasion groupmeeting
-
Literature: catgo campaign ingest --project <dir> --pdf <p.pdf> (MinerU) or
--repo <url> --purpose "…".
-
Archive (clean the tree, never auto-decide): catgo campaign archive --project <dir> --list
proposes FAILED calcs (funnel rejects are kept as data); move one only on the user's
explicit OK: catgo campaign archive --project <dir> --calc calc/<stage>/<name> --reason "…".
Notes
- Default to a review gate (user-in-the-loop); only auto-advance on explicit opt-in.
- Full conventions live in the in-repo skill
server/catgo/workflow/skills/campaign/SKILL.md
(read it for the folder layout, progressive-md rules, two-level plan, gate details).
