# DSH Math Modeling Team Plugin Pack

> ## 🎉 Good luck to everyone in the 2026 CUMCM!
>
> May your problem reading be accurate, your models defensible, your code run right the first time, your figures instantly readable, and your paper finished with time to spare.
>
> Seven things once the problem drops: split the problem → get a minimal runnable first → attack your own model → always review your figures → page through the rendered PDF before submitting → have two different models review → three members, three folders, commit only your own.
>
> **Go math modelers!** 🚀

Team-based math modeling workflow plugins for **DeepSeek Harness**. It distills the methodologies of mature math-modeling skill repos into **2 installable agent presets**, paired with a **multi-folder Git collaboration** model (Gitee/GitHub), so multiple people can work independently in their own workspaces without interference.

Hosted under the GitHub Topic: **`dsh-plugin`**.

> 简体中文说明见 [README.md](README.md) | English docs below.

> ⚠️ **Since DSH 0.2.0 this repository ships as a bundle plugin package.** DSH 0.2.0 no longer reads `$DSH_HOME/.agent-presets/`; presets must be declared by a bundle. See [Installation](#installation).

## What this is

In DeepSeek Harness, an **agent preset** is a role configuration: a persona (job responsibility), a set of tools, and **Skills** (role capability documents) installed with the preset. Each session that picks a preset gains that role's full capability set.

This pack provides **2 role presets**:

| Preset ID | Role | Who | Core capabilities |
|---|---|---|---|
| `model-code` | Modeling + Programming Agent | 2 modeling/coding members (shared) | Problem analysis, model building, Python/MATLAB solving, results & figures, reproducibility manifest; includes modeler/coder/algorithm/viz docs |
| `paper` | Paper Agent | 1 paper-writing member | Paper writing (Word/LaTeX), evidence retrieval & verification, independent review gate; includes paper-writer/award-review/evidence-search docs |

### Each preset contains
- `cordis.patch.yml` — the **preset declarations** (`@deepseek-ai/dsh-agent-preset` rows): `persona` / tool set / skill mounts; see the comments in that file
- `package.json` — the bundle declaration (`dsh.bundle.patch` points at `cordis.patch.yml`)
- `presets/<id>/skills/<name>/SKILL.md` — the role's primary skill (responsibilities, workflow, quality gates, collaboration rules)
- `presets/<id>/skills/<name>/references/` — methodology docs installed with the preset (loaded on demand)

### Key features
- **Team collaboration**: preset embeds a "3-folder Git repo" protocol (`member-a/`, `member-b/`, `member-c/`) — each member commits only their own folder, no interference
- **Quality gates**: Modeling final-check M1 / minimal runnable P1 / **robustness attack final-check M2** / coding final-check P2 / evidence outline W1 / paper final-check W2
- **M2 robustness attack final-check**: systematically "attack" every core model — propose model → attack model → re-verify with an alternative method → add uncertainty → out-of-sample test → state the applicability boundary — to keep conclusions that cannot survive scrutiny out of the paper (with real 2023 CUMCM-C attack cases)
- **Figure QA (mandatory image-review gate)**: **prefer reading figures directly with the main model's `read_image`** when it supports images; otherwise dispatch a sub-agent on a **vision-capable model in the current environment** via `workflow` (auto-probe models whose `inputModalities` includes `image`; e.g. DeepSeek V4.1 Flash or `kimi-coding/kimi-for-coding`, not hardcoded). **Every formal figure must be reviewed one-by-one to PASS with records before P2/W2**; on FAIL, a "fix → re-review" loop runs until PASS — figures that skipped image review cannot pass the final-check gates
- **Independent-model review (both models review once each)**: **Kimi K3-256K + DeepSeek V4.1 Flash** each review independently once, cross-covering blind spots — factuality / consistency / completeness / **model attack** / citation check; fabricated numbers are blocked on the spot

## Model division of labor

Assign models by **capability complementarity** — **no specific model is required**. Configure per the table below using the models available in your environment (do not hardcode model names):

| Role | Capability needed | How to choose |
|---|---|---|
| **Main model** | Broad world knowledge, sharp judgment, strong reasoning | Pick the **most knowledgeable/reasoning-capable** model in your environment (problem understanding, modeling analysis, paper writing) |
| **Programming** | Strong coding/engineering | Pick the **strongest coding** model (may differ from the main model); dispatch it via `workflow` to write code, run results, compile/convert |
| **Review (≥2 different models, once each)** | Different vendor / different strength than the producer | **Pick at least two different models, each reviewing independently once**, cross-covering blind spots |
| **Vision** | Accepts image input, cost-controlled | Prefer an **economy vision model** (high-frequency lightweight task) |

**How to probe**: use the `llm` service's `listProviders()` / `resolveModelInfo()` to list available models and capabilities, then pick per the table above. If no suitable model exists for a role, state the limitation honestly.

> **Validated example on this host** (reference only, not required): main Kimi K3 · programming DeepSeek V4.1 Flash · review Kimi K3-256K + DeepSeek V4.1 Flash (each once) · vision DeepSeek V4.1 Flash (`deepseek-official/deepseek-flash`) or Kimi K2.7 Code (`kimi-coding/kimi-for-coding`). **Any model meeting the capabilities above works.**

## Independent model review (multiple different models, each reviewing once, adversarial)

**Why**: a model that both produces and accepts has no critical distance — fabricated numbers, inconsistent definitions, and contradictions go unnoticed. Having **multiple models of different vendors and strengths each review once** cross-covers their blind spots.

**How**: dispatch **two** review sub-agents via `workflow`'s `agent(prompt, { provider, model })`, pinned respectively to **Kimi K3-256K** and **DeepSeek V4.1 Flash**; record both verdicts (PASS/FAIL + issue list), and any issue from either side must be fixed and re-reviewed under the re-review loop.

**Review dimensions** (both runs):
- **Factuality**: can the headline numbers be traced to `results/` and the figures? Any fabrication?
- **Consistency**: are definitions/symbols/conclusions coherent across summary, body, tables, and figures?
- **Completeness**: do all sub-problems get covered?
- **Model attack**: question each core model's assumptions (instrument validity / key parameter values / baseline dependence / stockout truncation / share stability) and verify the stated applicability boundary
- **Citation check**: do references exist and are they cited correctly?

**Blocked instance (2023 CUMCM-C run)**: a fabricated number "0.78" in a draft was flagged (not present in the data) → removed, replaced with the honest interval (0.7, 0.8).

**Relation to M2**: M2 (modeling role) attacks the models at production time; independent review (paper role) re-checks the paper with both models at delivery time — two lines of defense, front and back.

## Reusable global skill

The repo ships a directory installable as a **global skill** (drop it under a DSH shared user skill root; any preset discovers it):

- `skills/vision-subagent/` — vision sub-agent (visual QA). Install:
  ```bash
  # Copy to the DSH shared user skill root; any preset session auto-discovers it
  cp -R skills/vision-subagent ~/.agents/skills/vision-subagent
  # Windows:
  # Copy-Item -Recurse .\skills\vision-subagent "$env:USERPROFILE\.agents\skills\vision-subagent"
  ```
  DSH's `dsh-skill-filesystem` scans `~/.agents/skills/`, `~/.dsh/skills/`, project `.dsh/skills`, etc.; once placed, it is discovered automatically — no config change needed.

## Installation

### Prerequisites
- DeepSeek Harness **0.2.0 or newer** (0.2.0 made bundle declarations the only preset source)
- Keep this repository at a **durable local path**: the desktop profile references it with `link:`, so **moving or deleting the directory breaks the presets**
- Installing executes plugin code and requires Full access / approval

### Method 1: Web plugin page (recommended)
Desktop → **Settings → Plugins → Install local bundle**, and pick the **repository root** (the directory containing `package.json`).

### Method 2: Desktop's bundled CLI
A desktop profile can only be managed by the desktop's own CLI (a globally npm-installed `dsh` refuses). The `plugin` subcommand forwards the remaining arguments to pnpm inside the profile directory, so `add` / `remove` / `list` all work:
```powershell
$env:ELECTRON_RUN_AS_NODE='1'
& 'F:\dsh\DeepSeek Harness.exe' --expose-internals `
  'F:\dsh\resources\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\cli.js' `
  plugin --profile desktop add "link:<absolute path to this repo>"
# list installed plugins
& 'F:\dsh\DeepSeek Harness.exe' --expose-internals `
  'F:\dsh\resources\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\cli.js' `
  plugin --profile desktop list
```

### Method 3: `plugin_manager` in a session
Have any session call `plugin_manager` with `action: install_bundle` and `target` set to the **absolute path of this repository**. It performs the dependency install and bundle selection itself.

After a successful install the profile's `package.json` gains one dependency and one bundle entry. This repository is mounted as a `link:` (symlink), so **restarting the desktop app** is enough to pick up edits — no reinstall needed.

### Verify installation
**Restart the desktop app** (closing the window only hides it to the tray; use the tray menu's Quit, or end every `DeepSeek Harness.exe`), then open a new session: the preset picker should list **`建模编程 Agent`** and **`论文 Agent`**, and the plugin page should show `preset-model-code` / `preset-paper` as activated rather than broken. To re-check declarations, query `Config.listConfigs` through `cordis_inspect_query` with the `preset-<id>` entry id.

### Migrating from the legacy layout (0.1.x / `.agent-presets`)
- The 0.1.x `~/.dsh/.agent-presets/<id>/{preset.yml,agent.cordis.yml,skills/}` directory is **no longer read** by 0.2.0 and can be deleted once the new presets work.
- Do **not** copy the old `agent.cordis.yml` verbatim: its `@deepseek-ai/dsh-workflow-worker-thread` row was replaced by `@deepseek-ai/dsh-workflow-ptc` in 0.2.0 and fails at activation.
- `cordis.patch.yml` here rebuilds the 0.2.0 shipped `cordis` preset baseline and keeps the original customizations: both role personas, `tool-web.fetch: false` (search only), `tool-todo.allowParallelInProgress: true`; skill directories resolve from the **installed package**, not a preset directory.

## Quick start (team collaboration mode)

1. Create an empty private repo on Gitee/GitHub (shared by the team)
2. On first clone, initialize the `member-a/`, `member-b/`, `member-c/` three-folder baseline per `docs/team-collaboration.md`
3. 2 members open `model-code` preset sessions in separate workspaces, each cloning the repo and committing their own modeling+coding deliverables to their `member-*` folder, then push
4. The paper member opens a `paper` preset session, `git pull`s A & B's deliverables, writes the paper in `member-c/`, and pushes
5. Everyone commits only their own `member-*` folder — no interference

Per-role kickoff prompt templates: see `docs/team-collaboration.md`.

## Full workflow (two presets + team collaboration)

### Detailed flowchart

```mermaid
flowchart LR
    subgraph team["Team (3 people · 3 independent workspaces)"]
        direction TB
        A["Member A (model-code preset)"]
        B["Member B (model-code preset)"]
        C["Member C (paper preset)"]
    end

    subgraph mc["📐 Modeling & coding role (model-code)"]
        direction TB
        S1["① Modeling phase<br/>read problem → check attachments → split sub-problems<br/>→ choose models → design solve & verify plan"]
        G1["M1 modeling final-check<br/>requirements covered?<br/>sub-problems complete? correct criteria?"]
        D1["Deliver: problem analysis report.md<br/>term table.md"]
        S2["② Coding kickoff<br/>data prep (cleaning/returns/outliers)<br/>→ minimal runnable code → real run"]
        G2["P1 minimal runnable<br/>real results produced?"]
        S3["③ M2 robustness attack final-check<br/>identify attack points → alternative methods → intervals<br/>→ out-of-sample test → applicability boundary"]
        G3["M2 pass criteria<br/>attack list/alt methods/intervals<br/>/out-of-sample/boundary all present"]
        S4["④ Full-scale compute & figures<br/>3 figure types (raw/process/result)<br/>≥3 each covering all sub-problems"]
        S5["⑤ Figure QA<br/>vision sub-agent one-by-one review (mandatory)"]
        G4["P2 coding final-check<br/>real results · complete reproducibility manifest<br/>figures skipped image review → fail"]
        D2["Deliver: results/ tables + reproducibility manifest.json<br/>figures/ 3 types"]
        S1 --> G1 --> D1 --> S2 --> G2 --> S3 --> G3 --> S4 --> S5 --> G4 --> D2
    end

    subgraph pp["📄 Paper role (paper)"]
        direction TB
        T1["① Pull A/B deliverables<br/>git pull member-a/b"]
        T2["② Build evidence base<br/>read analysis report/results/figures<br/>per-sub-problem evidence list + gap log"]
        T3["③ Evidence search & verify<br/>multi-source search → dedup → cross-check citations"]
        T4["④ W1 evidence outline<br/>structure × evidence mapping<br/>+ model defense checklist (maps to M2)"]
        G5["W1 pass criteria<br/>evidence per chapter · no orphan conclusions<br/>defense checklist complete"]
        T5["⑤ Write paper<br/>Word (OMML) / LaTeX (optional)<br/>official template adaptation → render PDF"]
        T6["⑥ Figure QA<br/>vision sub-agent one-by-one review (mandatory)"]
        T6b["⑦ Rendered-PDF page review (mandatory)<br/>each page → image → vision sub-agent per-page<br/>table overflow / bad fonts / tiny fonts / layout / blank pages"]
        T7["⑧ Independent review<br/>both models review once each<br/>(K3-256K + V4.1 Flash)"]
        G6["W2 paper final-check<br/>formulas↔results · no empty fig/table<br/>numbering/citations continuous · boundary stated<br/>figure-review records · rendered-PDF review PASS · independent review PASS"]
        D3["Deliver: final paper.docx/pdf<br/>review record.md · code appendix · AI-use disclosure"]
        T1 --> T2 --> T3 --> T4 --> G5 --> T5 --> T6 --> T6b --> T7 --> G6 --> D3
    end

    D2 -->|"git add member-a/b<br/>commit · push"| REPO["Git repo<br/>member-a / member-b / member-c"]
    REPO -->|"git pull (read-only others)"| T1
    V1["🖼️ Vision sub-agent (global skill)<br/>probe vision model → read_image<br/>FAIL → fix → re-review → PASS"]
    V2["⚔️ Independent review model<br/>factuality/consistency/completeness<br/>model attack/citation check"]
    V1 -.-> S5
    V1 -.-> T6
    V2 -.-> T7
```

### Gate check details

| Gate | Role | What it checks |
|---|---|---|
| **M1 modeling final-check** | modeling/coding | All problem requirements have a model/plan; no sub-problem missed; constraints & criteria understood correctly |
| **P1 minimal runnable** | modeling/coding | Minimal code runs before full-scale compute and produces real results |
| **M2 robustness attack final-check** | modeling/coding | Core models survive systematic attack: identify threats (3-5 attack points, e.g. instrument validity / elasticity value / baseline dependence / stockout truncation / share stability) → alternative-method verification → uncertainty intervals → out-of-sample test → applicability boundary; attack list complete to pass |
| **P2 coding final-check** | modeling/coding | All sub-problems have real results & figures; numbers traceable; reproducibility manifest complete; **all formal figures reviewed by vision sub-agent to PASS with records** |
| **W1 evidence outline** | paper | Structure × evidence (fig/table/conclusion) mapping; no orphan conclusions; **model defense checklist included** (maps to M2 attack results) |
| **W2 paper final-check** | paper | Formulas↔results consistent; no empty figs/tables; figures cover all sub-problems; numbering/citations continuous; references bidirectional; applicability boundary stated; **all figures reviewed by vision sub-agent to PASS with records**; **rendered-PDF per-page review PASS with records** (table overflow / bad fonts / tiny fonts / layout / blank pages); independent review results merged |

### Mandatory image review / rendered-PDF review / independent review (cross-cutting)

- **Figure QA (mandatory image-review gate)**: **prefer the main model's direct `read_image`** when its `inputModalities` includes `image`; otherwise auto-probe a vision model (validated: DeepSeek V4.1 Flash, `kimi-coding/kimi-for-coding`; not hardcoded) and dispatch a vision sub-agent via `workflow` to review every formal figure one-by-one (title/axes/legend/data/blank-overlap/claim support). **FAIL → fix per defects → re-review, loop until PASS**; each "FAIL reason → fix action → re-review result" is recorded. **Required in both P2 and W2: figures that skipped image review cannot pass the final-check gates.**
- **Rendered-PDF page review (mandatory)**: after the final PDF is produced, render every page to an image (pdftoppm/PyMuPDF, 300 DPI) and have the vision sub-agent review **each page** — table overflow/truncation, abnormal fonts (mojibake/missing glyphs), unreadably small fonts, layout issues (overlap/misalignment/orphan lines), blank/duplicate pages, header/footer anomalies, blurry/cropped images, bad page breaks. FAIL → fix layout → re-render → re-review page by page, until all PASS; records kept. **Required in W2: papers that skipped rendered-PDF page review do not pass.** (More checks: see `self-review framework` / `LaTeX format spec` docs)
- **Independent-model review (both models review once each)**: adversarial critique by **Kimi K3-256K + DeepSeek V4.1 Flash**, each reviewing independently once — factuality (numbers traceable / no fabrication), consistency (definitions coherent), completeness (sub-problems covered), **model attack** (question instrument validity / parameter values / baseline dependence / stockout truncation / share stability), citation check (references exist & cited correctly). Must run before W2; fabricated numbers are blocked on the spot.

### Collaboration essentials

- **3 independent workspaces + 1 Git repo + 3 folders** (member-a/b/c); each commits only their own folder — no interference
- Deliverable contract: modeling/coding 6 items (analysis report / term table / scripts / results / figures / reproducibility manifest); paper 4 items (evidence outline / paper / review record / AI-use disclosure)
- Bounded iteration: max 2 fix rounds per review; when the budget is exhausted, output a decision memo — never infinite polishing

## Documentation

- [Vision sub-agent](docs/vision-subagent.md) — vision review when the main model cannot read images
- [Team collaboration](docs/team-collaboration.md) — 3-folder collaboration protocol, handoff contract, per-role prompts
- [Attribution](docs/attribution.md) — methodology provenance from the two reference repos
- [Sample run record](docs/sample-run.md) — a full end-to-end run on the real 2023 CUMCM Problem C
- [Model Capability Configuration Guide](docs/model-capabilities.md) — image input declarations, sub-agent allowlist, common error reference (incl. the V4.1 Flash image-capability fix)

## Sample showcase

Result of a full end-to-end run on the real **2023 CUMCM Problem C (Vegetable Pricing & Restocking)** — see [sample run](docs/sample-run.md) for the full pipeline and data:

- [Sample paper `examples/sample-paper.pdf`](examples/sample-paper.pdf) — 33-page final paper (XeLaTeX, 18 figures)
- `examples/figures/` — 15 result figures covering **raw / process / result** stages and all of Q1–Q3:

**Q1 Sales distribution & relationships**

![Q1 sales concentration](examples/figures/Q1_单品销量集中度.png)

![Q1 category correlation heatmap](examples/figures/Q1_品类相关热力图.png)

| | |
|---|---|
| ![Q1 seasonal factor](examples/figures/Q1_季节因子.png) | ![Q1 day-of-week factor](examples/figures/Q1_周内因子.png) |
| **Seasonal factor** (summer/CNY peaks) | **Day-of-week factor** (weekend peak) |

| | |
|---|---|
| ![Q1 clustering dendrogram](examples/figures/process_Q1_品类聚类树状图.png) | ![Q1 raw daily sales](examples/figures/raw_Q1_日销量时序.png) |
| **Category clustering** | **Raw daily sales series** |

**Q2 Category price-volume & restocking/pricing**

![Q2 backtest comparison](examples/figures/Q2_回测收益对比.png)

| | |
|---|---|
| ![Q2 price elasticity](examples/figures/Q2_量价弹性.png) | ![Q2 category pricing markup](examples/figures/Q2_品类定价加成.png) |
| **Price elasticity** | **Category mark-up pricing** |

**Q3 Single-item restocking & pricing**

| | |
|---|---|
| ![Q3 restock volume](examples/figures/Q3_单品补货量.png) | ![Q3 item profit](examples/figures/Q3_单品收益.png) |
| **Selected-item restock volume** | **Item profit** |

| | |
|---|---|
| ![Q3 item pricing](examples/figures/Q3_单品定价.png) | ![Q3 sensitivity](examples/figures/process_Q3_灵敏度分析.png) |
| **Item pricing** | **Satisfaction-revenue sensitivity** |

## Methodology attribution

The role methodology docs in this pack are distilled from (docs only; no scripts/tool sources are shipped):

- [XiaoMaColtAI/math-modeling-skill](https://github.com/XiaoMaColtAI/math-modeling-skill) — 3-stage workflow (modeling/coding/paper), quality gates, algorithm library, scientific-viz spec, reproducibility manifest. **Synced to v1.3.0** (incl. new Delivery & Deadline Protocol, figure contract, per-role doc updates; upstream's own DSH preset pack `dsh-plugin/math-modeling-agent` is NOT merged — we keep our own dual-role collaboration orchestration).
- [sweetcornna/mathodology](https://github.com/sweetcornna/mathodology) — award-grade review gates (blind judging / bounded iteration), evidence search, full workflow methodology. **Synced to latest** (incl. paper_graph prior-art/retraction check, two-level category routing updates in evidence search)

## License

MIT (most permissive; attribution required)