skill

mathmodel-studio

A local-first desktop agent for mathematical modeling contests: human-in-the-loop model selection, explanations, quality gates and scoring, plus figures, LaTeX/Word papers and de-AI checks. Electron +

Escap1ng/mathmodel-studiocommunitylistedunreviewed

Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/Escap1ng/mathmodel-studio itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 31, 2026

设计原则：能自动校验的交给门禁，需要判断的留给人，判断点做成界面。

桌面程序内置一组技能（出版级图表、排版规范、AI 痕迹检查、结构自检与评分）。模型由使用者接入，数据不出本机。

概览

MathModel Studio 面向正在推进建模工作、准备交付的参赛者与研究者。它不替使用者做建模判断，但把阶段推进、选模、图表返工、论文排版和交付检查放在同一个工作台里，每一步都有记录。

本地优先：桌面端和 Python 运行时都在本机运行，模型 Key 用系统安全存储加密。
人在环：关键节点会停下来等确认；重启后仍停在原来的决策点。
契约驱动：技能由注册表、JSON Schema 和 CLI 退出码约束，界面按注册表生成，不写死技能清单。
证据可复核：每条门禁都有读数，并配反向用例。

界面

截图来自实际界面（1.5 倍像素密度）：首图是最大化窗口，其余裁自 1440×900 窗口。会话内容来自离线演示，没有真实赛题和密钥。

评分与扣分定位	论文排版与 PDF 预览

五维得分、扣分明细和正文定位	xelatex → pandoc → 三道门禁与页级预览

当前状态

0.6.1（2026-11-01）。这一版让阶段四真的跑起来：选模确认后定位工作区里的 CSV、生成并执行基线脚本，把 PNG/PDF/SVG 登记成图表版本；工作区没有数据时回落到内置示例并说明。长会话按上下文预算自动压缩较早轮次，对话流里插入压缩分隔线；失败的问答可以直接重试。附件支持读取 xlsx 全部工作表；文件页的工作区文件可以拖进中栏或右键加入，移除附件不会删掉原文件。上一版的底色不变：多会话管理、五类模型入口（DeepSeek、通义千问、Kimi、智谱 GLM、OpenAI 格式端点）、200k / 400k / 1m 上下文预算、中 / 高 / 最大思维深度，以及可收起的右侧工作台。

论文页完成整条排版链路：xelatex 两遍 → pandoc 转 DOCX → Word 版式后处理 → 去 AI 措辞、结构指标和章节结构三道门禁；PDF 用 pdf.js 逐页预览。当前编译的是仓库自带的演示稿，构建成功也不会自动把阶段五标记为通过。

M6 打包已配置完成：electron-builder 把便携 Python 和 pandoc 一起装进安装包，NSIS x64 安装包已在本机构建，尚未在干净机器上安装验证。

里程碑见 PLAN.md §7；已验证结论与未证事项见 docs/HANDOFF.md。

快速开始

# 安装依赖。大陆网络环境请先阅读 docs/env-setup.md：npm 直连与 github.com 均不稳定
npm install
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 启动桌面端。无 Key 时可加 MMS_FAKE_PROVIDER=1 使用离线演示
MMS_FAKE_PROVIDER=1 npm run dev

# 不接入模型也可验证运行时：列出 25 个模板并渲染一张图（PNG/PDF/SVG）
npm run mms -- templates
npm run mms -- invoke figure paired-raincloud

# 运行全部本地门禁：注册表、技能规范、反向覆盖、类型检查、构建、产物冒烟、契约、CLI、通道、工作台与论文
npm run gate

npm run gate 全部通过，表示本地门禁没有问题，且不依赖网络和显示器。论文自检需要本机安装 xelatex 和 pandoc（见「依赖」）。

核心能力

阶段编排与决策点

阶段零到阶段六（环境预检、赛题分析、工作目录、算法选择、代码实现、论文输出、评分优化）排成一条状态轨道，当前卡在哪一步可以直接看到。关键节点用决策卡暂停：

K2 赛题与附件确认：拆出子问题，标明附件用途，逐问对应数据。
K3 选模卡：2–3 条候选路线，列出核心思路、创新度、可解释性、实现难度、预计耗时和精度预期，可换一批。
K4 就地解释：打开解释抽屉，待选状态不丢。
K5 图表返工：换模板、换主题、重渲和回滚；重渲后只显示当前图，旧版本进入历史。
K6 评分与优化轮次：五维评分、扣分定位、三轮熔断和一票否决。

会话与上下文

左栏是会话列表：建模会话存在 SQLite，问答会话存在本地；可以新建、切换、单条删除和清空。切换时恢复消息、附件、阶段和待决卡。中栏顶部显示当前会话和上下文用量，按 200k / 400k / 1m 预算从最新消息往回装载。

模型接入

设置页按服务商列出五类入口，模型名可选预设或手动填写。Key 只经主进程 safeStorage 加密保存；未配置 Key 时可用离线演示。详见 docs/providers.md。

图表与论文

图表工作台调用真实渲染器输出 PNG/PDF/SVG，同时保留可复现的命令和运行日志。论文页完成 xelatex、pandoc、Word 版式后处理和三道交付门禁，PDF 用 pdf.js 逐页预览。

文件与工作区

「文件」页列出工作区内容，可以切换目录；工作区默认在桌面「赛题」，首次启动时创建。附件可以直接拖入中栏或粘贴，主进程负责抽取正文（PDF 用 pdfjs，文本和 CSV 直接读取并报告行列，xlsx 按工作表读成表格并识别日期，旧版 .xls 仍需另存）。

架构

桌面端和 Python 运行时通过本地回环通道（HTTP + SSE）通信，模型 Key 只由主进程加密保存。阶段在 K2–K6 决策点暂停，状态、待决卡和消息历史写入 SQLite，重启后可以恢复。

技能矩阵

技能清单以 skills/manifest.json 为准；下表行数和徽章计数由 CI 校验，必须一致。

技能	职责	状态
`mathmodel-core`	阶段零至阶段六编排与路由	内置
`mathmodel-methods`	建模方法库与选型：问题族索引、选型依据、验证方式	内置
`mathmodel-paper`	论文写作与排版：写作规范、LaTeX 骨架、Word 输出、参考文献	内置
`mathmodel-figure`	数据图表：matplotlib 模板库与 Nature 出图标准	内置
`mathmodel-diagram`	学术示意图：JSON 驱动版式模板与高保真复刻	内置
`mathmodel-deai`	降 AI 与交付核查：词表级、结构级、字符级三道门禁	内置
`mathmodel-score`	结构自检与评分：章节门槛与百分制五维评分卡	内置

七个技能以源码随仓库分发（Apache-2.0），版本和引入记录见 skills/VENDOR.md。运行时只通过 subprocess 调用技能脚本、按退出码判定，因此每个技能也能被 Claude Code 等宿主单独加载。

质量门禁与证据

每条门禁都配了反向用例：只会报通过的检查器不算证据。

门禁	判据	反向覆盖
G1 注册表一致	注册表、技能目录、契约词表与两份 README 的技能表及徽章计数一致	8 种破坏逐项注入，必须变红（`npm run check:registry:negative`）
G8 技能规范	每个技能的 `SKILL.md` 为合法 Agent Skills 入口：frontmatter 可解析、名称与目录一致、描述非空且在 1024 字内、无仓库私有字段	6 种基于真实文件的破坏必须变红（`npm run check:skills:negative`）
G2 契约校验	注册表按 JSON Schema Draft 2020-12 校验；`jsonschema` 缺席时降级并说明	两份非法注册表必须被拒
G2b 版本同源	`VERSION`、`package.json`、`pyproject.toml`、`mms/__init__.py` 四处一致	任一缺项或取值不同即失败
G3 CLI 契约	退出码 0/1/2 均可达；实际调用渲染器并核验 PNG/PDF/SVG 三件产物	词表外取值、非法 JSON、空 `MMS_HOME`、未知子命令/模板与渲染器假成功均被拦截（`runtime/selfcheck.py`）
G4 事件流	握手、Bearer token、回环 Host/Origin 白名单、九类 SSE 事件、续传与取消；覆盖 K2/K3 暂停恢复与进程重启后恢复；0.6.0 增加思维深度、关闭开关和上下文裁剪（52 条）	10 种坏事件必须被拒；无 token、错误 Host、无待决恢复均被拒（`python runtime/selfcheck_channel.py --selftest`）
G5 provider 离线契约	本地假端点覆盖 429 退避、`reasoning_content` 分离、分片 `tool_calls` 拼装、历史消息剥离和 Key 传递边界	Key 哨兵不得进入事件流与 stderr；未开启离线模式时假 provider 被拒
G6 桌面骨架	类型检查、构建，并校验产物包含本项目中文文案与设计令牌	断言失败即退出 1（`scripts/smoke-dist.mjs`）
G9 工作台	真实渲染两版图、版本历史与回滚，未知模板、主题或版本不会写入历史；三轮评分、扣分定位、章节样例和一票否决（13 条）	未知模板/主题/版本均为反向控制（`runtime/selfcheck_workbench.py`）
G10 论文排版	xelatex 两遍 → pandoc → Word 后处理：PDF/DOCX 文件头与体积、六个步骤、三道门禁、状态写入磁盘（10 条）	缺件、坏稿、坏 TeX、缺稿件四条反向；`MMS_PAPER_SKIP=1` 才允许跳过并打印未验证
G11 编排状态机	起题、K2 确认、K3 换一批与选模，选模后阶段四真跑：定位工作区 CSV、生成并执行基线脚本、PNG/PDF/SVG 登记成图表版本；工作区无数据时回落到内置示例并说明（13 条）	默认方法族写成单元素元组、关键词族被清空两种破坏必须变红（`python runtime/selfcheck_orchestrator.py --selftest`）
G12 长会话 harness	预算核算、工具结果先裁剪再结构化摘要、摘要本身有长度上限、二次压缩并入旧摘要、锚点每轮替换、溢出识别、单条超预算时从最早处丢；50 轮压到预算内且最近 6 条原文保留（14 条）	拆掉压缩、关掉工具裁剪两种破坏必须变红（`python runtime/selfcheck_harness.py --selftest`）
G13 附件 xlsx	解压工作簿读出全部工作表：共享字符串与富文本、稀疏列、布尔/错误值、公式缓存值、日期与时间格式（含 1904 日期系统）；单表最多 300 行 × 60 列（10 条）	非 ZIP 与缺工作簿两种坏文件必须报错；301 行的表必须截到 300 行（`npm run check:xlsx`）
G7 真启动冒烟	以生产入口起窗，验证构建产物、1440×900、非白像素、IPC、中文真字形与 Key 不回显；覆盖 K2→K3→解释→选择、阶段四真跑与自动出图、图表重渲与回滚、评分、论文构建与预览、附件与 xlsx、工作区文件拖入与右键、多会话、五家预设、上下文与思维深度、右栏收起（100 条）	空白截图、自建窗口、缺字（方框字形）和删除关键断言都会被拦截（`tests/window-smoke.cjs`）
G6b 结果核验	读取冒烟 JSON 并复算读数：内容尺寸、非白像素、断言下限、关键断言与自述计数	`--selftest` 用 12 份合成结果证明假通过会被拒（`scripts/check-window-smoke.mjs`）

验证状态

0.6.1 在本机验证了类型检查、构建、完整 npm run gate（G4 52/52、G11 13/13、G12 14/14、G13 10/10、G9 13/13、G10 10/10）与 G7 100/100，G6b 独立复算一致（内容尺寸 1440×900、非白像素 3.83%）。CI run 41289813731 的三个任务全部通过：ubuntu 真启动 100/100、内容尺寸 1440×900、非白像素 4.43%，G6b 复算一致；ubuntu 与 windows 门禁均通过，Windows 上的 G10 显式跳过并标注未验证。

M6 的 NSIS x64 安装包已在本机构建（mathmodel-studio-0.6.1-setup.exe，约 265 MB，自签名证书，未受信任的根，SmartScreen 会提示未知发布者），尚未在干净机器上安装验证。

未覆盖范围：五家服务商的真实联网对话（本仓库不包含 Key）、CI 的 Windows 真起窗、CSP 违规场景的主动探测、安装包在干净机器上的安装与运行。历史 CI run 与读数见 CHANGELOG.md。

依赖

用途	依赖	说明
桌面壳	Electron、electron-vite、React、TypeScript	见 `package.json`
运行时	Python 3.12+	通道服务器、SSE 与 provider 客户端仅用标准库；`jsonschema>=4.20` 可选，缺席时契约校验降级
模型接入	DeepSeek、通义千问、Kimi、智谱 GLM 与任意 OpenAI 格式端点	见 docs/providers.md；Key 经主进程 `safeStorage` 加密
排版	xelatex、pandoc、python-docx	xelatex 需本机安装（TeX Live 或 MiKTeX）；pandoc 可随包提供，也可放进 PATH、设置 `MMS_PANDOC`，或安装到 `%LOCALAPPDATA%\mms-tools\pandoc.exe`
出图	matplotlib、numpy、seaborn	版本下限见 `requirements.txt`，安装使用镜像
论文预览	pdfjs-dist	随 `npm install` 安装，worker 由 Vite 打包，运行时无需网络

打包与分发

打包已配置：内置便携 Python 运行时（python-build-standalone，放在 vendor/python，不入库），pandoc 以 vendor/pandoc/pandoc.exe 随包放进 resources/pandoc；xelatex 仍需本机安装，TeX 没有内置。NSIS x64 配置见 electron-builder.yml，随包工具链由 scripts/prepare-vendor.mjs 准备。应用、安装器与向导页头/侧栏图共用 build/icon.svg 生成的图标；安装包用自签名证书，证书根不受信任，SmartScreen 会提示未知发布者。

参与贡献

欢迎提交 Issue 与 Pull Request。报告问题请写清版本号、Windows 版本、复现步骤与相关日志；改代码或文档前建议先开 Issue 说明意图，避免重复劳动。提交前请在本机跑通 npm run typecheck、npm run build 与上文「质量门禁与证据」中对应的门禁，并在 PR 描述里写明改动动机与验证方式。本仓库以 AGPL-3.0-only 发布，提交 PR 即表示同意你的贡献按同一许可分发。

合规声明

本工具用于排版、出图、交付前自检和方法选型讨论，不代替建模判断，也不保证获奖。内置评分与结构自检默认采用国赛口径（对齐 2026 格式规范），美赛口径可通过参数切换；AI 痕迹检查仅清理模板腔与不可见字符，不将未完成的工作表述为已完成。伪造结果、编造文献与数据属于硬性红线。请遵守所在赛事对生成式工具的规定。