
Saturday Materials
io.github.toki0413由 GitHub 帳號 toki0413 發布v0.3.14更新於 Oct 24, 2026
Materials computing tools for AI agents: structures, engines, phonons, EOS, NEB, sampling, lineage.
概覽
為助理提供材料計算工具:結構載入、弛豫、摻雜篩選、聲子、狀態方程式、NEB 與取樣。
- 可以做什麼
- Saturday 是一個以外掛形式暴露材料計算能力的執行環境。README 列出的能力包括 material.load(化學式轉結構)、structure.fromSmiles(SMILES 轉三維構形)、potential.relax(週期與分子系統弛豫)、workflow.screen(批次摻雜篩選並依能量排序),以及 analysis.phonon、analysis.eos、analysis.neb、analysis.elasticity、sampler.* 與 workflow.* 等工具。README 稱透過 stdio 暴露 56 個工具,未設定 MP_API_KEY 時縮減為 55 個。
- 適用情境
- 適合讓助理真正執行材料計算而非只做討論:弛豫結構、對摻雜變體排序、計算聲子、狀態方程式、遷移能障或彈性張量,以及取樣候選結構供後續回算驗證。
- 執行需求
- 透過 npx @toki0413/mcp-server 以 stdio 在本機執行,需要 Node >= 22。安裝 Python >= 3.10 與 ASE >= 3.22 可解鎖 EMT 真實物理;否則使用零相依的 LJ 引擎。選用的 MP_API_KEY 用於 Materials Project 結構解析。README 另描述選用的 streamable-http 模式與 Docker 映像。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Saturday Materials,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
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 等)——在客户端配置里加:
存盘重启客户端,对它说一句“把 Cu 弛豫一下并给出每原子能量”,它会调 potential.relax 返回
energyPerAtom(eV);material.load / workflow.screen(掺杂筛选)/ analysis.phonon(声子)
等 56 个工具都在。想要真实 EMT/LAMMPS 物理,再装 Python≥3.10 + ASE(见下“环境矩阵”),
引擎按能力自动升级,插件面契约与单位/指纹门禁不变。
路径 B:本地跑起来看全链
想知道“我该调哪个工具”→ 见 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 携带结构化错误码。
宿主配置(Claude Desktop / Cursor / Cherry Studio 等通用 mcpServers 格式):
环境档位声明:纯 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)
运行
挂载到 dsh(完整运行时)
demo:agent 展示 Agent 会话的完整编排能力:裸 cordis 进程内组装全部真实 dsh 服务 +
脚本化 mock 模型,覆盖材料加载、真实弛豫、采样联合排序、锚点持久化与恢复、血缘审计、
修复验收与回填十个阶段,全部以自然语言驱动。
设计原则
- 契约即宪法:
@toki0413/contract-tests提供 structure-resolver / potential-provider / workflow / sampler / derivation 五条 seam 的标准断言集,新插件npm test即过宪法; 兼容性由测试而非文档承诺 - 防腐层(依赖卫生):领域代码不 import cordis,上游变更的影响面收敛到适配层一个文件; dsh 为唯一官方宿主,裸 cordis 作为开发/CI 模式
- 单位与能力指纹入契约:引擎注册即校验单位三元组与能力指纹;换算只能由调用方显式发起;
异源/异单位能量进入比较路径前显式拒绝;实测版本可回读盖章(
demo:cross-engine/demo:availability展示全链) - 热力学诚实:能量零点显式声明——严格形成焓 + 凸包判据需要显式参考态, 不可得时降级并明说;自由能零点(锚点)同理
- 采样语义:逆解是对相容分布的采样而非求逆;似然可求值性显式声明; 候选必须可回算验证,引擎是唯一 oracle
- 谱系即活性:导出量登记推导来源,失效沿推导图传播;落盘载荷携带可追溯声明, 跨会话可撤回
- 摘要可再生:
npm run summary从测试输出与契约实证表机械汇编SUMMARY.md, 不手写、不人工维护
引用
Saturday 的架构范式基于以下工作:
许可
MIT
來源:README.md,提交 bee0960
工具
0版本歷史
8- v0.3.14最新Sep 21, 2026
- v0.3.13Sep 21, 2026
- v0.3.12Sep 21, 2026
- v0.3.11Sep 21, 2026
- v0.3.10Sep 20, 2026
- v0.3.9Sep 19, 2026
- v0.3.8Sep 19, 2026
- v0.3.7Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分