dsh-math-modeling-agent 0.1.0 → 0.1.2

package/README.md

@@ -1,126 +1,155 @@
-# MathModelingAgent for DSH
-
-证据驱动的数学建模智能体插件：状态机编排 + 主张/义务/证据账本 + 独立验证协议 + MCM/ICM 终审。继承 MathModelingAgent v3.1 的"分解 + 迭代"方法论，把验证裁决权从 LLM 主观打分换成可复现证据。
-
-## 继承与改良
-
-- **继承**：数据探查、子问题分解、顺序求解、带接受/拒绝标准的建模-分析-修正循环、停滞检测（源自 [IMO25](https://github.com/lyang36/IMO25) 的分解+迭代思想）。
-- **改良**：原项目的验证者是"分析者 LLM 打 1-5 分"；本插件改为**义务账本 + 工具执行证据 + 独立审计**——LLM 只负责提出主张和攻击，不再负责裁决正确性。旧仓库保持原样未动。
-
-## 特性
-
-- **状态机**：9 个可恢复终态（SOLVED / PARTIAL / CONDITIONAL / INCONCLUSIVE / REFUTED / INFEASIBLE / UNIDENTIFIABLE / BLOCKED / CANCELLED），每次转移必须引用证据或 issue。
-- **证据账本**：每个主张强制登记验证义务（数值→独立重算+误差界；最优性→KKT/对偶/精确搜索，否则只能声称"已找到最优"；预测→防泄漏划分+基线+校准……），证据强度不得弱于主张强度。
-- **验证协议**：固定攻击顺序 + PASS / FAIL / INCONCLUSIVE 三态裁决，INCONCLUSIVE 禁止升格。
-- **崩溃恢复**：原子快照 + 追加日志 + 跨进程锁，stale 锁与残留 guard 自动回收。
-- **MCM/ICM 终审**：一票否决与奖项封顶 + 七类 100 分 + 固定 14 节报告。
-- **零运行时依赖**：Python、Lean、Wolfram 全部可选，缺失时验证等级降级，绝不伪造执行。
-
-## 工作流
-
-```mermaid
-stateDiagram-v2
-    [*] --> TRIAGE
-    TRIAGE --> SCOPE_FROZEN
-    SCOPE_FROZEN --> INPUT_PROFILED
-    INPUT_PROFILED --> CLAIMS_REGISTERED
-    CLAIMS_REGISTERED --> CANDIDATES_READY
-    CANDIDATES_READY --> ATTEMPT
-    ATTEMPT --> EXECUTE
-    EXECUTE --> VERIFY
-    VERIFY --> REVISE
-    VERIFY --> RESEARCH
-    VERIFY --> FORK
-    REVISE --> ATTEMPT
-    RESEARCH --> CANDIDATES_READY
-    FORK --> ATTEMPT
-    VERIFY --> SOLVED
-    VERIFY --> PARTIAL
-    VERIFY --> CONDITIONAL
-    VERIFY --> INCONCLUSIVE
-    VERIFY --> REFUTED
-    VERIFY --> INFEASIBLE
-    VERIFY --> UNIDENTIFIABLE
-    VERIFY --> BLOCKED
-    VERIFY --> CANCELLED
+# MathModelingAgent
+
+> **模型负责提出，工具负责验证，证据决定结论。**
+
+面向开放式数学建模、预测、优化、估计、仿真、机制分析与数学建模竞赛题。
+
+与普通 "LLM + Python" 工作流的区别只有一句话：**它不会把"代码跑通了""模型觉得合理""优化器返回一个解"当成结论正确的证据。** 关键结论登记为**主张（Claim）**，每个主张有明确的**验证义务（Obligation）**，再通过独立计算、反例、误差界、形式验证、文献证据或复现实验生成**证据（Evidence）**；证据不足就必须继续修正、降低结论强度，或明确返回 `INCONCLUSIVE`。
+
+## 工作方式
+
+1. **题目与数据**：明确问题目标、输入、约束、缺失信息与歧义。
+2. **理解与拆解**：拆成可验证的子问题，登记假设、候选模型与关键主张。
+3. **建模与执行**：提出候选方案，用数值计算、优化、仿真、符号计算、文献、形式验证执行并保留产物。
+4. **证据验证**：独立重算、检查单位量纲、对照公式与代码、查找数据泄漏、比较基线、做敏感性分析、构造反例、查引用与可复现性。**证据不足就回去修正，而不是硬通过。**
+5. **结果交付**：说明哪些结论已支持、哪些有条件、哪些无法判断，以及如何复现、当前运行为何结束。
+
+## 核心：Claim → Obligation → Evidence
+
+**Claim（主张）**：影响结论的重要陈述，如"C1：该方案是全局最优解"、"C2：模型可泛化到训练数据之外"。
+
+**Obligation（义务）**：按主张类型要求证据——
+
+- 数值结果：独立重算 + 容差 + 误差界 + 输入配置一致
+- 最优性：精确搜索 / 可证上下界 / KKT / 对偶 / 形式证明；只有启发式优化结果时只能说"当前搜索下的最佳解"，不能升级为"全局最优"
+- 预测能力：防泄漏划分 + 基线 + 验证/测试集 + 校准 + 不确定性
+
+**Evidence（证据）**：记录方法、工具、命令、环境、输入输出哈希、退出码、产物、容差、局限与支持的主张；等级：
+
+```text
+NOT_CHECKED → DERIVED → EXECUTED → VERIFIED → INDEPENDENTLY_VERIFIED → EXTERNALLY_VALIDATED
 ```
 
-任意非终态可直达 BLOCKED / CANCELLED。ATTEMPT 永远不能直接跳到 SOLVED。
+原则：**证据强度不能弱于主张强度。**
 
-## 安装
+## 验证协议
 
-固定 GitHub 版本（发布流程需先创建 v0.1.0 tag）：
+验证不是让另一个 LLM 再"看一遍答案"，而是按固定顺序攻击：
 
-~~~bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.1.0
-~~~
+1. **任务覆盖**：是否真回答原问题、是否偷换代理指标、是否漏子问题
+2. **数学与约束**：单位、量纲、定义域、边界、约束、推导
+3. **推导与实现一致性**：公式 ↔ 代码 ↔ 参数 ↔ 结果
+4. **数据与实验设计**：标签、划分、数据泄漏、后验参数、来源
+5. **模型可信度**：基线、不确定性、敏感性、鲁棒性、外部效度、更简单替代
+6. **可复现性**：版本、种子、配置、命令、引用真实性
+7. **反例攻击**：边界案例、失败案例、更简单解释
 
-npm 发布后，或本地 `npm pack` 生成的 tarball 路径：
+裁决只有三态：
 
-~~~bash
-dsh plugin --profile web add dsh-math-modeling-agent
-~~~
+- `PASS`：可复现证据支持
+- `FAIL`：矛盾 / 反例 / 无效方法 / 复现失败
+- `INCONCLUSIVE`：证据不足——**不能因为"看起来合理"升级为 PASS**
 
-不要用 `dsh plugin add .` 安装本地目录：它会按目录名安装且不激活 bundle。安装后验证组合配置并重启 host：
+## 终态与进展
 
-~~~bash
-dsh --profile web --dump-config
-dsh web
-~~~
+不只有 `SOLVED`：`PARTIAL` 部分解决 / `CONDITIONAL` 结论依赖条件 / `INCONCLUSIVE` 证据不足 / `REFUTED` 被反驳 / `INFEASIBLE` 不可行 / `UNIDENTIFIABLE` 信息不足 / `BLOCKED` 外部阻塞 / `CANCELLED` 取消。**`ATTEMPT` 永远不能直接跳到 `SOLVED`。**
 
-## 核心机制
+**算进展**：关闭一条义务、新增可复现证据、反驳候选、收紧界或区间、移除阻塞、修复问题、正确降低结论强度。
+**不算进展**：换说法、同参数重跑、写更长、`exit 0`、模型说"有信心"。
+连续多轮无进展 → 换方向 / 请求用户决策 / 以非 SOLVED 状态暂停。
 
-### 状态机与 SOLVED 门禁
+**SOLVED 硬门禁**：范围冻结 + 必选义务全 PASS + 关键对抗检查通过 + 可复现材料齐全 + 局限已声明；High-Assurance 还需独立审计（审计器只读产物，不依赖求解过程的私有推理）。
 
-每轮尝试有一个目标并记录：候选与假设增量、实际执行的命令或推导产物、新证据 ID、关闭的义务、打开/关闭的 issue、是否产生可审计进展、预算消耗、下一步行动。判定"进展"只认：关闭义务、新增可复现证据、反驳候选、收紧界或不确定区间、移除阻塞、正确弱化不支持的断言——重述、同参数重跑、更长的散文、工具 exit 0 都不算。连续两轮无进展进入停滞审查，第三轮无进展必须实质换方向（FORK）、交给用户决策，或以非 SOLVED 终态暂停。
+## 两个 Skill
 
-SOLVED 硬门禁：范围冻结 + 全部必选义务 PASS + 关键对抗检查通过 + 可复现材料齐全 + 局限已声明；High-Assurance 模式还必须通过一次只拿产物、不注入思维链的独立审计。
+- **`math-modeling-agent`**：建立和推进模型。目标不是"写一篇看似完整的答案"，而是把问题推进到**有证据支持的结论，或清晰可恢复的科学状态**。
+- **`math-modeling-audit`**：独立审计已有模型/论文，逐条回答哪些主张 PASS / FAIL / INCONCLUSIVE 以及为什么；**不替作者修改**。
 
-### 主张 / 义务 / 证据
+## 工具：可插拔，缺失就降级
 
-- **主张记录**：ID、原文、类型、量词范围、假设、风险、验证义务、证据 ID、独立反查、状态、局限。
-- **证据记录**：方法、工具、时间戳、覆盖的主张、输入输出哈希、命令/环境、退出码、产物、容差、局限，以及六档等级：NOT_CHECKED / DERIVED / EXECUTED / VERIFIED / INDEPENDENTLY_VERIFIED / EXTERNALLY_VALIDATED。
-- **强度匹配**：训练集分数不能支撑泛化结论；单个优化器返回点不能支撑全局最优；形式化证明不能支撑未形式化的现实假设。不支持的断言只能弱化，不能放宽验证规则。
+工具只是产生证据的方式，可以替换，工作流不变。
 
-### 验证协议
+- **Python** 可选（推荐）：需要计算时在运行目录内创建隔离环境（数值计算、数据分析、优化、仿真、绘图、独立重算）
+- **Lean** 可选：形式化验证；不自动安装；**形式命题被证明 ≠ 现实主张被证明**
+- **Wolfram** 可选：符号计算、解析推导、恒等式验证
+- **文献研究**：未知方法、证据缺口、参数依据不足、换方向时检索；私有原始数据不进检索
 
-冻结输入（哈希题目、数据、代码、配置、环境）→ 重建主张映射 → 按固定顺序攻击：任务覆盖与代理指标替换 → 单位/量纲/定义域/约束 → 推导与实现一致性 → 数据泄漏/标签/划分/后验参数 → 基线/不确定性/敏感性/外部效度 → 可复现性与引用真实性 → 反例/失败案例/更简单替代。裁决只允许 PASS（可复现证据支撑）、FAIL（矛盾/反例/无效方法/复现失败）、INCONCLUSIVE（证据不足），且 INCONCLUSIVE 不得因为"看起来合理"升格为 PASS。
+工具缺失不会伪装成验证成功：记录缺失 → 降低证据等级 → 降低结论强度 → 保留未满足的义务。
 
-### 崩溃恢复与并发
+## 可恢复运行
 
-默认运行根目录 `math-modeling-runs/<task-id>/`。`run.json` 原子快照、`events.jsonl` 追加式转移日志、`ledger.json` 主张账本；`run-state.mjs` 提供 init / transition / validate / recover 四个命令。跨进程互斥锁带 ownerId 与 stale 回收（进程已死且超时自动接管），空锁文件与残留 reclaim guard 按 mtime 回收，Windows 共享冲突自动重试；恢复时校验日志并跳过哈希未变的已完成工作，任何 provider/解析器失败都保留原始产物与最佳候选。
+默认运行目录 `math-modeling-runs/<task-id>/`：
 
-### MCM/ICM 终审
+```text
+run.json            # 原子状态快照
+ledger.json         # 范围、假设、主张、义务、子问题、候选、issue
+events.jsonl        # 追加式转移日志
+attempts/<n>/       # 每轮报告与产物
+research/  walls/   # 文献检索 / 放弃方向的突破备忘录
+reproducibility.json  final-report.md
+```
 
-`math-modeling-audit` Skill 内置模拟 100 分终审（非 COMAP 官方评分表）：Stage 1 一票否决与奖项封顶（14 项检查，逐项给出证据链封顶）；Stage 2 七类评分共 100 分（问题理解与分解 10、数据/证据/参数 12、模型构建 22、求解算法与可复现 16、结果验证与可信度 24、结论与推广 8、写作与图表 8）；Stage 3 模型逐个尸检；Stage 4 关键结果审计；Stage 5 按 MCM A/B/C 或 ICM D/E/F 启用专项检查；Stage 6 依据 93-100 Outstanding Candidate 等 band 判定奖项，输出固定 14 节报告。
+崩溃恢复：跨进程互斥锁 + stale 锁与 reclaim guard 回收 + Windows 共享冲突重试；已完成且输入未变的工作不重跑；任何失败都保留最佳候选与原始产物。
 
-### 工具与降级
+## MCM / ICM 终审（audit Skill）
 
-`capability-probe.mjs` 探测 PATH 并实测可用性。Python 可选但推荐：仅在需要计算时用 `python-environment.mjs` 在运行目录内创建隔离 uv/venv 环境，只安装所需 PyPI 包（VCS 依赖与任意索引需用户批准）；Lean 与 Wolfram 可选，永不自动安装，Lean 结果必须附无 sorry/admit 证明与自然语言-形式语句忠实性检查；缺失能力只降低证据等级（unverified / partially_verified），不伪造执行结果。
+模拟终审框架（**非 COMAP 官方评分表**）：一票否决与奖项封顶 → 七类 100 分评分 → 模型逐个审计 → 关键结果审计 → MCM A/B/C 与 ICM D/E/F 专项 → 固定 14 节终审报告。评分不修改建模侧的 SOLVED 判定。
 
-## 运行产物
+## 快速开始
+
+安装：
+
+```bash
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.1.2
+dsh --profile web --dump-config   # 检查组合层
+dsh web                          # 然后重启
+```
 
-~~~text
-math-modeling-runs/<task-id>/
-├── run.json              # 原子状态快照
-├── ledger.json           # 范围、假设、主张、义务、子问题、候选、issue
-├── events.jsonl          # 追加式转移日志
-├── problem-brief.md      # 问题摘要
-├── inputs.json           # 输入与数据画像
-├── attempts/<n>/         # 每轮：report.md + 代码/产物（存在时）
-├── research/             # 文献检索与候选方法矩阵（发生研究时）
-├── walls/                # 放弃方向的突破备忘录（放弃时）
-├── reproducibility.json  # 数据/代码/配置版本、锁、种子、命令
-└── final-report.md       # 终态报告
-~~~
+（npm 通道：`dsh plugin --profile web add dsh-math-modeling-agent`）
+
+开始建模——直接描述任务即可，不需要选内部状态、验证器或文件名：
+
+```text
+建立这个数学建模问题的模型，先分析题目和数据。
+任何"最优""显著""泛化"的结论都必须提供相应证据，证据不足不要强行确定。
+```
+
+独立审计——给已有论文/模型/代码：
+
+```text
+独立审计这份结果，逐条给出 PASS / FAIL / INCONCLUSIVE，不要帮我修改原文。
+```
+
+## 项目结构
+
+```text
+skills/
+├── math-modeling-agent/   # 建模、执行、修正、生成证据
+└── math-modeling-audit/   # 独立复算、反例攻击、证据审查、MCM/ICM 终审
+tests/                     # 状态机、锁与恢复、验证协议、打包完整性、MCM 评分
+cordis.patch.yml  package.json  README.md  LICENSE
+```
 
 ## 卸载
 
-~~~bash
+```bash
 dsh plugin --profile web remove dsh-math-modeling-agent
-~~~
+```
+
+然后重启当前 DSH host。
+
+## 设计原则
+
+1. 模型可以提出结论，但不能自己给自己判卷。
+2. `exit 0` 只是程序状态，不是数学结论。
+3. 不确定性是合法答案：`INCONCLUSIVE` 优于编造。
+4. 结论强度必须匹配证据强度。
+5. 失败应该被保留：反例与失败方向防止下一轮重蹈覆辙。
+6. 结果应可被他人复检：数据、代码、命令、哈希、验证记录、局限。
+
+## 方法论来源
 
-卸载后重启当前 host。
+继承"问题分解 + 多轮尝试 + 失败后换方向"的 Agent 建模思想（受 [IMO25](https://github.com/lyang36/IMO25) 等启发）。核心变化：**把验证裁决从 LLM 主观评价中拿出来**——不是"分析者觉得 4/5 分可以通过"，而是 `Claim → Obligation → 工具/独立检查 → Evidence → PASS / FAIL / INCONCLUSIVE`。LLM 可以提出主张、攻击主张，但不能仅凭自己的判断宣布主张已被证明。
 
 ## License
 

package/cordis.patch.yml

@@ -4,5 +4,9 @@
       config:
         providerName: dsh-math-modeling-agent
         includeDefaultRoots: false
-        bundledSkillDir: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"
+        # The Loader evaluates !!js against the ROOT include context: `baseUrl`
+        # is the profile directory (e.g. ~/.dsh/profiles/web/), NOT this bundle's
+        # directory. Resolve this package through the profile's own node_modules so
+        # the skill root works for npm, github, pnpm, and file: installs alike.
+        bundledSkillDir: !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', process.getBuiltinModule('node:url').pathToFileURL(process.getBuiltinModule('node:module').createRequire(baseUrl + 'noop.js').resolve('dsh-math-modeling-agent/package.json')).href))"
         watch: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-math-modeling-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Evidence-driven mathematical modeling and verification skills for DeepSeek Harness",
   "type": "module",
   "files": [
@@ -31,4 +31,4 @@
       "patch": "./cordis.patch.yml"
     }
   }
-}
+}