面向数学建模竞赛的本地桌面 Agent · 关键判断留给你
从赛题到论文，需要判断的地方都会停下来等你确认：
选模理由、方案解释、门禁结论和扣分明细都在界面上，可以追问，也可以回滚。
简体中文 · English
工作台：左侧会话与阶段轨道，中间三条候选的 K3 选模卡
设计原则：能自动校验的交给门禁，需要判断的留给人，判断点做成界面。
桌面程序内置一组技能（出版级图表、排版规范、AI 痕迹检查、结构自检与评分）。模型由使用者接入，数据不出本机。
MathModel Studio 面向正在推进建模工作、准备交付的参赛者与研究者。它不替使用者做建模判断，但把阶段推进、选模、图表返工、论文排版和交付检查放在同一个工作台里，每一步都有记录。
- 本地优先：桌面端和 Python 运行时都在本机运行，模型 Key 用系统安全存储加密。
- 人在环：关键节点会停下来等确认；重启后仍停在原来的决策点。
- 契约驱动：技能由注册表、JSON Schema 和 CLI 退出码约束，界面按注册表生成，不写死技能清单。
- 证据可复核：每条门禁都有读数，并配反向用例。
截图来自实际界面（1.5 倍像素密度）：首图是最大化窗口，其余裁自 1440×900 窗口。会话内容来自离线演示，没有真实赛题和密钥。
K3 选模：三条候选路线逐项对比，可直接选，也可先看解释
| 评分与扣分定位 | 论文排版与 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 gatenpm 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 痕迹检查仅清理模板腔与不可见字符，不将未完成的工作表述为已完成。伪造结果、编造文献与数据属于硬性红线。请遵守所在赛事对生成式工具的规定。
AGPL-3.0-only。本仓库整体以 AGPL-3.0-only 发布；分发本软件或其修改版时，需按该许可提供对应源码。skills/ 中的 Apache-2.0 文件保留原许可与版权声明，版本与出处记录见 skills/VENDOR.md。