Saturday Materials

Saturday —— 材料计算的插件运行时

简体中文 | English

Everything is a plugin。 Saturday 不是又一套材料计算引擎，不替代 DFT / MD / FEM / CFD 的任何求解器； 它是材料计算的组合层：引擎、结构源、工作流、分析工具全部以插件形态挂载到 DeepSeek Harness (dsh) / `@deepseek-ai/cordis` v4 运行时上，由 Agent 在运行时自由挂载、卸载与组合。

插件接口规范见 packages/bridge/docs/plugin-contract-v0.md（中文原本，英文摘要版同目录）。

60 秒上手

不需要 Python、不需要装任何求解器——有 Node ≥ 22 就能让 Agent 拿到真实的材料回算数值 （无 ASE 时自动走零依赖 lj-js 引擎；能量由引擎回算，非玩具占位假数）。

最快一行（连客户端都不配）：npx -y @toki0413/mcp-server --relax Cu 直接打印 Cu 的每原子能量与所用引擎（装了 MACE/ASE 会自动升真物理）。

免装 Node/Python（全保真容器）：docker run --rm ghcr.io/toki0413/saturday --relax Cu 一行拿 EMT 真值，镜像已内含 Node + Python + ASE（构建/推镜像由 GitHub Actions + GHCR 承担，本地不装工具链）。当前状态：镜像构建与容器内冒烟已在 CI 跑通，但 GHCR 推送只在打 v* tag 时发生，因此该命令自 v0.3.14 起可拉；现在就要零安装跑用上面那行 npx。

路径 A：接进任意 MCP 客户端（Claude Desktop / Cursor / Cherry Studio 等）——在客户端配置里加：

{

"mcpServers": { "saturday-materials": { "command": "npx", "args": ["-y", "@toki0413/mcp-server"] } } }

存盘重启客户端，对它说一句“把 Cu 弛豫一下并给出每原子能量”，它会调 potential.relax 返回 energyPerAtom（eV）；material.load / workflow.screen（掺杂筛选）/ analysis.phonon（声子） 等 56 个工具都在。想要真实 EMT/LAMMPS 物理，再装 Python≥3.10 + ASE（见下“环境矩阵”）， 引擎按能力自动升级，插件面契约与单位/指纹门禁不变。

路径 B：本地跑起来看全链

git clone https://github.com/toki0413/dsh-saturday && cd dsh-saturday

npm install && npm test # 全量回归（纯 Node 即可） npm run demo # 一条十阶段端到端：加载→采样→筛选→声子→回算，环境自适应 npm run demo:agent # 一个 prompt 驱动整个发现链（mock LLM，无外部依赖）

想知道“我该调哪个工具”→ 见 docs/recipes.md（按意图找工具与参数）； 5 分钟上手与拒绝伪造证据的演示 → docs/agent-e2e-demo.md。

核心范式

时空可组合性（Spatiotemporal Composability）

理论依据为 Cordis 配套论文：

*A Programming Paradigm for Spatiotemporal Composability*，Yifan Shi, Wei Zhang, Tianyi Cui，

arXiv:2608.25512 [cs.PL]（北京大学 / DeepSeek-AI）。

Saturday 把论文的两个正交维度落到材料计算域：

材料计算 = 双通道事件流

各引擎（DFT/MD/FEM/CFD）的运行时行为投影为两类事件，Saturday 的总线只做路由不改物理：

• 瀑布事件（因果链）：弛豫步、SCF 迭代、MD 步进——传递"当前状态接力棒"，全序、可回放，承载时间维；
• 广播事件（一对多）：收敛达成、能量异常、属性算出——多消费方订阅联动，承载空间维。

事件粒度因引擎而异（迭代级 ↔ 任务级），由能力握手显式声明。

原子化操作（Atomic Operations）

一切研发动作分解为可独立调用、自由组合的原语（relax / calculate / substitute …）， 同一组原语同时暴露给 Agent 工具、DSL 与编程 API。原子性按作用域分级： 软件资源域完全可逆（cordis effect）、计算任务域幂等 + 可取消、物理设备域永不回滚。

活的材料上下文

材料上下文 = 瀑布事件累积器之上的响应式谱系图：每个导出量声明推导来源， 上游变化沿谱系自动传播失效与重算。推导登记簿（@toki0413/plugin-derivation） 是这一形态的运行时载体，已接入真实筛选工作流（势函数热替换沿引擎引用全链失效）。 掺杂操作 Material.substitute 的不可变 fork 语义保证谱系全程可追溯。

能力（v0.3）

MCP server：任意 MCP 宿主接入

上述工具面经 @toki0413/mcp-server 以 Model Context Protocol 全量暴露（56 工具， stdio 传输；工具面随环境如实收缩——无 MP_API_KEY 时 structure.resolve 不注册 = 55 工具， 环境不可用的引擎/结构源挂载即跳过并显式报告，不展示注定失败的能力）： Claude Desktop / Cursor / Cline 等任何 MCP 宿主零代码接入， 参数 schema 由各工具的契约声明直通，工具失败以 MCP isError 携带结构化错误码。

npx @toki0413/mcp-server        # stdio；SATURDAY_DISABLE 可排除插件

npx @toki0413/mcp-server --http # 或 SATURDAY_MCP_TRANSPORT=http：streamable-http 远程端点（默认 127.0.0.1:3000/mcp，/health 探活）

宿主配置（Claude Desktop / Cursor / Cherry Studio 等通用 mcpServers 格式）：

{

"mcpServers": { "saturday-materials": { "command": "npx", "args": ["-y", "@toki0413/mcp-server"], "env": { "MP_API_KEY": "可选：Materials Project 远端结构解析需要" } } } }

环境档位声明：纯 Node 环境下工具面为 lj-js 教学档（零依赖玩具势）；本地安装 Python ≥ 3.10 + ASE ≥ 3.22 后自动解锁 EMT 真物理与全量 31 工具（启动横幅如实呈报，非静默降级）。

宿主适配层边界：MCP server 只依赖 @toki0413/kernel 的无宿主引导 （bootstrapPlugins，cordis 的 import 收敛在 kernel 包内）与插件包， 插件本身对 MCP 无感知——防腐层纪律不变。

引擎插件矩阵（均接入 @toki0413/contract-tests 标准套件）： emt-mock（核心，ASE EMT / LJ）、lj-js（零依赖纯 JS，玩具势教学档，优雅回退数据面）、lammps（批处理，粒度 job）、mace（ML 势，可用性预检）、ase（通用 ASE 计算器，自带 sidecar）。

EMT 能量零点为各元素平衡 fcc 晶体，energyPerAtom 近似形成焓。Cu 掺杂筛选实测： Cu3Pt (-0.10) < Cu3Au (-0.02) < Cu (0) < Cu3Ni (+0.01) < Cu3Ag (+0.02) eV/atom—— 有序化（Cu-Pt / Cu-Au）与相分离（Cu-Ni / Cu-Ag）倾向与实验冶金学一致。

环境矩阵

开箱即用：git clone → npm install 后，纯 Node 环境即可跑全部演示与全量回归（无额外依赖；无 ASE 时走零依赖 lj-js）。 数据面形态随环境自适应，启动横幅如实呈报（非静默降级：回退引擎是显式注册的独立引擎）。

• Node ≥ 22（dsh 硬性要求；裸 cordis 测试可在 Node 20 运行）
• Python 数据面依赖：numpy + scipy（仅升级精度时需要）
• Windows 下默认使用 python 命令，可用 bridge.python 配置覆盖
• pnpm

CI（数据面双档矩阵）

每次推送/PR 自动跑两档（.github/workflows/ci.yml），与上方环境矩阵一一对应：

两档跑同一份测试：套件内环境自适应（HAS_ASE/dataPlane 探测 + 显式 skip，诚实不静默）； 真物理断言（晶格常数、严格形成焓、互转自检）仅在精度档执行，零依赖档如实跳过不伪造。

结构（npm workspaces）

packages/

kernel/ # @toki0413/kernel —— 防腐层：全仓唯一接触 cordis 的文件 src/cordis-adapter.mjs # SaturdayRuntime 接口 + append-only Trajectory core/ # @toki0413/core —— 领域核心（零运行时依赖） src/material.mjs # Material 领域对象（谱系、视图、substitute 掺杂） src/potential.mjs # PotentialRegistry（引擎 seam + 评分路由 + 粒度门禁） src/structure-resolver.mjs# 结构解析 seam（原型库，含多晶型 + 7 种 fcc 金属） src/elements.mjs # 元素表（Z/符号/电负性，化学式合成） python-bridge/ # @toki0413/python-bridge —— 通用 Python sidecar 客户端 src/bridge.mjs # stdio JSON-lines，握手/超时/批量 sidecar.py + adapters/ # 主 sidecar：按元素逐调用路由 ASE EMT / LJ 兜底 contract-tests/ # @toki0413/contract-tests —— 契约测试套件（兼容性由测试承诺） src/index.mjs # structureResolver / potentialProvider / workflow / sampler / derivation bridge/ # @toki0413/bridge —— dsh Bundle（saturday 主插件） src/saturday.plugin.mjs # cordis 插件入口 { name, apply } profiles/cordis.patch.yml # 挂载到 dsh profile 的示例 docs/plugin-contract-v0.md# Plugin Contract v0（插件契约，experimental） plugins/ # 插件生态（新插件必须过 contract-tests 套件） screening/ # @toki0413/plugin-screening —— 工作流：批量掺杂筛选 mp-structure-source/ # @toki0413/plugin-mp —— 结构源：Materials Project lammps/ # @toki0413/plugin-lammps —— 引擎：LAMMPS 批处理，粒度 job mace/ # @toki0413/plugin-mace —— 引擎：MACE ML 势，一次性/常驻 batch 双形态，可用性预检 ase/ # @toki0413/plugin-ase —— 引擎：通用 ASE 计算器，自带 sidecar lennard-jones/ # @toki0413/plugin-lj —— 引擎：零依赖纯 JS LJ（优雅回退数据面，指纹 lj-js） replay/ # @toki0413/plugin-replay —— 分析：Trajectory 回放与索引重建 rss/ # @toki0413/plugin-rss —— 采样：RSS 随机结构搜索（§4.5 非 flow 生成式第二实证） neb/ # @toki0413/plugin-neb —— 分析：NEB 最小能量路径与势垒 eos/ # @toki0413/plugin-eos —— 分析：Birch-Murnaghan 状态方程拟合 phonon/ # @toki0413/plugin-phonon —— 分析：Γ 点声子（虚频与稳定性判定） elasticity/ # @toki0413/plugin-elasticity —— 分析：6×6 弹性张量 + Born 判据 + VRH sampler-perturb/ # @toki0413/plugin-sampler-perturb —— 采样：参考结构微扰 sampler-ou/ # @toki0413/plugin-sampler-ou —— 采样：OU 受控扩散 + 混合提案 + 锚点工具链 sampler-flow/ # @toki0413/plugin-sampler-flow —— 采样：仿射耦合流（可逆输运 + 换元精确似然） explore/ # @toki0413/plugin-explore —— 工作流：采样 → 回算闭环 ergodic/ # @toki0413/plugin-ergodic —— 工作流：遍历对账 free-energy/ # @toki0413/plugin-free-energy —— 工作流：构型自由能曲线（热力学积分） derivation/ # @toki0413/plugin-derivation —— 活性上下文：失效传播与惰性重算

运行

npm install             # workspaces：@deepseek-ai/cordis（peer）+ 全部 @toki0413/* 包软链

npm test # 全部 workspace 测试 npm run summary # 再生项目摘要（实跑全部包测试 + 提取契约实证表 → SUMMARY.md/.json） node scripts/pack-check.mjs # 发布形态核验（逐包 pack 干跑：版本一致 + files 白名单）

端到端演示（均无需 API Key，纯 Node 环境全部可跑：

无 Python 时数据面自动回退零依赖 lj-js 引擎，横幅如实呈报）

npm run demo --workspace @toki0413/bridge # 基础端到端 npm run demo:screening --workspace @toki0413/bridge # 掺杂筛选（环境自适应：EMT 或 lj-js） npm run demo:screening-ternary --workspace @toki0413/bridge # 三元混掺筛选（多组分凸包判据） npm run demo:concentrations --workspace @toki0413/bridge # 多浓度/共掺扫描（非退化凸包包络） npm run demo:freeenergy --workspace @toki0413/bridge # 构型自由能曲线（恒温 Langevin MD + 谐波锚点） npm run demo:cross-engine --workspace @toki0413/bridge # 跨引擎对照（单位/指纹门禁） npm run demo:availability --workspace @toki0413/bridge # 引擎可用性预检 npm run demo:mixture-sampling --workspace @toki0413/bridge # 多锚点混合采样（闭式似然重算 + 回算闭环） npm run demo:anchor-guided --workspace @toki0413/bridge # 锚点引导闭环（入库→检索→提案→回算→排序） npm run demo:anchor-aut