MCM Plugin

版本：1.0.0

面向数学建模竞赛的可审计工作流插件，适用于 Codex、OpenCode 与 Claude Code。它以结构化 Skill、职责受限的 Agent、不可变输入快照、模型决策证据、正式验证和论文交付门禁，组织从题面处理到提交前验收的全过程。

本仓库仅包含插件源码，不包含赛题输入、审批后的原始快照、实验结果、用户对话或工作区生成的 .mcm/ 记录。

能力

• 提取并复核题面、表格、图片、公式和源码型附件。
• 在模型使用数据前建立类型化数据契约。
• 采用三名互盲算法专家、唯一汇总 owner 和有限候选实现，不默认进行 registry 全量筛选。
• 在论文引用结果前冻结模型规格和数值证据。
• 验证代码、图件、证据绑定、文献、编译产物和最终提交物。
• 每个论文阶段均要求人工复核。

论文流程

paper-config-lock -> 人工审核
paper-plan-evidence -> 人工审核
q1/q2/q3/q4 问题初稿（并行）-> 分别人工审核
按需 paper-figure -> 人工审核
paper-draft-model-solution（假设 + 模型 + 结果）-> 人工审核
问题重述 -> 问题分析 -> 评价改进 -> 参考文献 -> 摘要 -> 组装
每个节点：机器验证 -> 人工审核 -> 解锁下游

每问初稿记录该问的证据、约束、结果和图件需求。只有当初稿或后续写作阶段提交了可追溯的结论、源字段和信息增益时，才生成图件。

安装

克隆仓库：

git clone https://github.com/chen2993/mcm-plugin.git
cd mcm-plugin
python assets\validate_agents.py

Claude Code

将已检出的仓库登记为本地 marketplace，再安装插件：

claude plugin marketplace add <path-to-mcm-plugin>
claude plugin install mcm-plugin@mcm-plugin-marketplace --scope user

OpenCode

在 OpenCode 配置中将本地 skills/ 目录加入 skills.paths；使用完整工作流时，保持 agents/ 与 skills/ 同级。仓库根目录的 AGENTS.md 定义跨宿主的调度规则。

Codex

通过宿主提供的本地插件安装方式使用本仓库。Codex 元数据位于 .codex-plugin/plugin.json，跨宿主调度规则位于 AGENTS.md。

修改插件 manifest、Skill 或 Agent 文件后，必须重启宿主程序以重新加载。

首次使用

1. 运行 pre-env-check。
2. 在新的竞赛工作区运行 pre-init。该步骤会创建工作区本地的 .mcm/ 状态、报告、审核文件和验证台账。
3. 运行 pre-ingest，批准 H1 快照审核后运行 pre-triage。
4. 使用 mcm-workflow-control 完成角色派发、验证和阶段转换。

每份 Agent 任务必须包含 role、scope、inputs、forbidden_reads、writes、acceptance、failure 和规范化 skills 字段。派发前执行校验：

python assets\agent_task_check.py <task.json> --plugin .

人工审核与反馈

每个论文节点必须先通过机器验证，才能进入人工审核：

python assets\paper_human_review.py --workdir . create --stage paper-question-draft-q1
# 人工完成 .mcm/review/paper/paper-question-draft-q1.md
python assets\paper_human_review.py --workdir . approve --stage paper-question-draft-q1

changes_requested 会将当前阶段退回 pending，并将下游工作标记为 stale。

插件工作流反馈与论文修改分开记录，写入工作区本地的 PLUGIN_IMPROVEMENT_LEDGER.md：

python assets\plugin_improvement_ledger.py --workdir . capture `
  --stage paper-workflow --category workflow --severity high `
  --summary "<可复现问题>" --expected "<预期行为>" `
  --conversation "<人工原话或经批准的摘要>"

该台账只保存改进所需的最小反馈，不会自动归档完整对话、附件或竞赛材料。

验证

在仓库根目录运行：

python assets\validate_agents.py
python -m unittest assets.test_paper_workflow_gates
python -m unittest skills.paper-figure.tests.test_mcm_figure_templates skills.paper-figure.tests.test_figure_safety
python assets\security_preflight.py --workdir .

对于已完成的竞赛工作区，使用 paper-final-verify，或执行：

python assets\final_verify.py --workdir <workspace> --stage paper

目录结构

路径	用途
skills/	阶段 Skill 和跨阶段工作流契约
agents/	职责边界明确的执行 Agent 提示词
assets/	校验器、迁移工具、测试夹具和图件辅助脚本
docs/	数据、Agent、报告、论文和并行所有权契约
templates/	工作用 LaTeX 模板资产
.claude-plugin/	Claude Code marketplace 元数据
.codex-plugin/	Codex 插件元数据

范围与限制

• 本插件是工作流系统，不保证数学结论正确，也不能替代竞赛规则。
• templates/mcm.cls 是工作用模板，必须与当届官方模板和提交规则核对后再使用。
• 公开可访问的参考资源不等于允许再分发；详见 THIRD_PARTY_NOTICES.md。
• 运行时 Skill 加载遥测依赖宿主支持。回执证明和任务校验是可审计控制，不能取代宿主运行轨迹。

贡献与安全

参见 CONTRIBUTING.md 和 SECURITY.md。本项目按 MIT License 发布。