面向数学建模竞赛的本地桌面 Agent · 关键判断留给你
从赛题到论文，需要判断的地方都会停下来等你确认：
选模理由、方案解释、门禁结论和扣分明细都在界面上，可以追问，也可以回滚。
简体中文 · English
通用模式：欢迎页与通用快捷提问，右侧只剩文件页图标
设计原则：能自动校验的交给门禁，需要判断的留给人，判断点做成界面。
桌面程序内置一组技能（出版级图表、排版规范、AI 痕迹检查、结构自检与评分）。模型由使用者接入，数据不出本机。
MathModel Studio 面向正在推进建模工作、准备交付的参赛者与研究者。它不替使用者做建模判断，但把阶段推进、选模、图表返工、论文排版和交付检查放在同一个工作台里，每一步都有记录。
- 本地优先：桌面端和 Python 运行时都在本机运行，模型 Key 用系统安全存储加密。
- 人在环：关键节点会停下来等确认；重启后仍停在原来的决策点。
- 契约驱动：技能由注册表、JSON Schema 和 CLI 退出码约束，界面按注册表生成，不写死技能清单。
- 证据可复核：每条门禁都有读数，并配反向用例。
截图来自实际界面（1.5 倍像素密度）：整行大图来自 1440×900 窗口，面板图裁自 1500×900 窗口。会话内容来自离线演示，没有真实赛题和密钥。
K3 选模：三条候选附五维雷达（创新、解释、精度、速度、易做），越靠外越好，难度与耗时已反向
| 过程总览与产物芯片 | 五维评分与扣分定位 |
|---|---|
 |
 |
| 七阶段管线按状态着色，点芯片直达对应页 | 五维得分、扣分明细和正文定位 |
论文：xelatex → pandoc → 三道交付门禁，pdf.js 页级预览
对话：流式回复、折叠思考与工具卡在同一条时间线上
0.2.0（2026-11-15）。数模模块真正跑通：配 Key 后七阶段全链由 LLM 驱动——K2 拆题面与核对数据角色、K3 按本题出选模候选（五维雷达对比，难度与耗时反向归一）、阶段四按题面与所选方法生成求解代码并经「代码确认卡」点运行才执行（失败回喂修复 ≤2 轮）、阶段五按真实结果写论文并过三道门禁、阶段六按 rubric 真实评分（总分 <85 回喂修复 ≤3 轮熔断，一票否决直接淘汰）。没有 Key 或模型不可用时回退确定性路径与演示样例，并在对话里明确标注兜底。默认进入通用对话，底部「通用 | 数模」分段切换；单 Python 内核（DSH 双内核已移除）。基础能力：多会话管理、五类模型入口（DeepSeek、通义千问、Kimi、智谱 GLM、OpenAI 格式端点）、200k / 400k / 1m 上下文预算、中 / 高 / 最大思维深度、附件读取与可收起的右侧工作台。
论文页完成整条排版链路：xelatex 两遍 → pandoc 转 DOCX → Word 版式后处理 → 去 AI 措辞、结构指标和章节结构三道门禁；PDF 用 pdf.js 逐页预览。论文与评分按会话隔离，构建成功自动推进阶段五。
打包已配置完成：electron-builder 把便携 Python 和 pandoc 一起装进安装包；0.2.0 的 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 gatenpm run gate 全部通过，表示本地门禁没有问题，且不依赖网络和显示器。论文自检需要本机安装 xelatex 和 pandoc（见「依赖」）。
阶段零到阶段六（环境预检、赛题分析、工作目录、算法选择、代码实现、论文输出、评分优化）排成一条状态轨道，当前卡在哪一步可以直接看到。关键节点用决策卡暂停：
- K2 赛题与附件确认：拆出子问题，标明附件用途，逐问对应数据。
- K3 选模卡：2–3 条候选路线，列出核心思路、创新度、可解释性、实现难度、预计耗时和精度预期，附五维雷达对比，可换一批。
- K4 就地解释：打开解释抽屉，待选状态不丢。
- K5 图表返工：换模板、换主题、重渲和回滚；重渲后只显示当前图，旧版本进入历史。
- K6 评分与优化轮次：五维评分、扣分定位、三轮熔断和一票否决。
数模模式的右侧工作台默认打开「过程总览」：七阶段管线按状态着色，每个阶段挂一条产物芯片（题面与附件、已选模型、图表版本、论文 PDF/DOCX、评分轮次），点芯片直达对应页；每次切入数模都回到这一页。
左栏是会话列表：建模会话存在 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/tests/selfcheck.py） |
| G4 事件流 | 握手、Bearer token、回环 Host/Origin 白名单、九类 SSE 事件、续传与取消；覆盖 K2/K3 暂停恢复与进程重启后恢复、思维深度与上下文裁剪、代码确认卡与全链（论文+评分）事件契约（64 条） | 12 种坏事件必须被拒；无 token、错误 Host、无待决恢复均被拒（python runtime/tests/selfcheck_channel.py --selftest） |
| G5 provider 离线契约 | 本地假端点覆盖 429 退避、reasoning_content 分离、分片 tool_calls 拼装、历史消息剥离和 Key 传递边界 |
Key 哨兵不得进入事件流与 stderr；未开启离线模式时假 provider 被拒 |
| G6 桌面骨架 | 类型检查、构建，并校验产物包含本项目中文文案与设计令牌 | 断言失败即退出 1（scripts/smoke-dist.mjs） |
| G9 工作台 | 真实渲染两版图、版本历史与回滚，未知模板、主题或版本不会写入历史；三轮评分、扣分定位、章节样例和一票否决（19 条） | 未知模板/主题/版本均为反向控制（runtime/tests/selfcheck_workbench.py） |
| G10 论文排版 | xelatex 两遍 → pandoc → Word 后处理：PDF/DOCX 文件头与体积、六个步骤、三道门禁、状态写入磁盘（12 条） | 缺件、坏稿、坏 TeX、缺稿件四条反向；MMS_PAPER_SKIP=1 才允许跳过并打印未验证 |
| G11 编排状态机 | 起题、K2 确认、K3 换一批与选模、代码确认卡（未确认不执行、失败回喂）、阶段四五六全链（求解→论文 PDF/DOCX+三门禁→真实评分达标/否决）；LLM 注入的坏 JSON 回喂与回退、选模落盘（34 条） | 默认方法族写成单元素元组、关键词族被清空两种破坏必须变红（python runtime/tests/selfcheck_orchestrator.py --selftest） |
| G12 长会话 harness | 预算核算、工具结果先裁剪再结构化摘要、摘要本身有长度上限、二次压缩并入旧摘要、锚点每轮替换、溢出识别、单条超预算时从最早处丢；50 轮压到预算内且最近 6 条原文保留（14 条） | 拆掉压缩、关掉工具裁剪两种破坏必须变红（python runtime/tests/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、工作区文件拖入与右键、多会话、五家预设、上下文与思维深度、通用/数模分段切换与按模式记住收合偏好、过程总览默认页与五维雷达（115 条） | 空白截图、自建窗口、缺字（方框字形）和删除关键断言都会被拦截（tests/window-smoke.cjs） |
| G6b 结果核验 | 读取冒烟 JSON 并复算读数：内容尺寸、非白像素、断言下限、关键断言与自述计数 | --selftest 用 12 份合成结果证明假通过会被拒（scripts/check-window-smoke.mjs） |
0.2.0 在本机（Windows）验证了类型检查、构建与完整 npm run gate（G4 64/64、G11 34/34、G12 14/14、G13 10/10、G9 19/19、G10 12/12）：离线全链（fake provider）从题面 → 选模 → 代码确认 → 运行 → 论文 PDF/DOCX + 三门禁 → 评分达标，阶段 0–6 全 passed。G7 真启动本轮被本机环境阻塞（重启后 Electron 渲染进程挂起，疑似终端安全软件拦截），待环境恢复后复跑。
0.2.0 的 NSIS x64 安装包尚未构建；打包配置已把便携 Python 与 pandoc 接入。
未覆盖范围：五家服务商的真实联网端到端（本仓库不包含 Key，需用户配 Key 后自跑）、G7 真启动（环境阻塞）、CI 的 Windows 真起窗、CSP 违规场景的主动探测、安装包在干净机器上的安装与运行。发布记录见 CHANGELOG.md，发布格式见 docs/release.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 痕迹检查仅清理模板腔与不可见字符，不将未完成的工作表述为已完成。伪造结果、编造文献与数据属于硬性红线。请遵守所在赛事对生成式工具的规定。
AGPL-3.0-only。本仓库整体以 AGPL-3.0-only 发布；分发本软件或其修改版时，需按该许可提供对应源码。skills/ 中的 Apache-2.0 文件保留原许可与版权声明，版本与出处记录见 skills/VENDOR.md。