dsh-math-modeling-agent 0.5.0 → 0.5.1

package/README.md

@@ -69,6 +69,46 @@ MathModelingAgent 把它改造成闭环：
 4. **证据验证**：独立重算、检查单位量纲、对照公式与代码、查找数据泄漏、比较基线、做敏感性分析、构造反例、查引用与可复现性。**证据不足就回去修正，而不是硬通过。**
 5. **结果交付**：说明哪些结论已支持、哪些有条件、哪些无法判断，以及如何复现、当前运行为何结束。
 
+## Chat-first 输出顺序
+
+每个重点环节都会先把完整、可读、可追问的文本直接输出在聊天正文中，再等待用户纠正或确认；确认后才写入 artifact，并允许 run-state 进入下一阶段。适用范围包括 D0/D-R、数据画像、全局假设、候选方向、SP1…、模型、计算结果、验证、鲁棒性、评价和 D4。
+
+如果某一阶段只生成了文件、工具摘要或一句结论，而没有在聊天中展示完整内容，它不算完成，真实 run 会停在当前阶段。
+
+## 模式、算力消耗与组合建议
+
+模式预算是一次 run 的执行上限，不代表一定会全部消耗。粗略可以用下面的模型理解总成本：
+
+```text
+C_total ≈ A × (C_model + C_compute + C_verify) + Q × C_research
+```
+
+- A：允许的尝试轮数；
+- C_model：每轮模型分析、代码生成和报告整理的成本；
+- C_compute：每轮数值计算、优化或仿真的成本；
+- C_verify：每轮独立重算、反例、鲁棒性和一致性检查的成本；
+- Q：文献/方法检索次数；
+- C_research：每次检索、阅读和整理的成本。
+
+当前默认预算如下。计算预算只表示工具执行上限，不等同于模型 token 费用；实际消耗取决于问题复杂度、是否触发修正、工具耗时和证据缺口。
+
+| 模式 | 最大尝试轮数 | 文献检索预算 | 计算预算上限 | 相对 Fast 的计算预算 |
+| --- | ---: | ---: | ---: | ---: |
+| Fast | 2 | 0 | 60 秒 | 1× |
+| Standard | 12 | 12 | 1800 秒 | 30× |
+| High-Assurance | 24 | 30 | 7200 秒 | 120× |
+
+High-Assurance 还要求独立审计和更严格的终态门禁，因此通常比表中的计算预算比例更慢；但它不是“必然正确”，只是给验证、反例和修正留下更多预算。
+
+### 推荐组合
+
+1. **Fast → Standard**：先用低成本判断题目类型和可行方向，再对选定方向完整建模。适合普通练习题。
+2. **Standard → High-Assurance**：先完成 Q1 → Q2 → Q3，再只对最终候选做高保证复核。适合数学建模竞赛和论文交付，通常最划算。
+3. **Fast → Standard → High-Assurance**：先筛选，再完整求解，最后审计。适合问题复杂、验证成本高或需要提交论文的任务。
+4. **直接 High-Assurance**：只在结论风险高、问题依赖多或必须尽量减少遗漏时使用；不建议对尚未稳定的早期方向直接使用。
+
+模式在 run 初始化时确定。需要升档时创建新的 run 或 correction lineage，可以复用输入快照，但不能静默修改原 run 的历史结果。
+
 ## 核心：Claim → Obligation → Evidence
 
 **Claim（主张）**：影响结论的重要陈述，如"C1：该方案是全局最优解"、"C2：模型可泛化到训练数据之外"。
@@ -115,11 +155,11 @@ LEGACY_UNVERIFIED → DERIVED → EXECUTED → VERIFIED → INDEPENDENTLY_VERIFI
 
 **SOLVED 硬门禁**：范围冻结 + 必选 verification 通过并聚合为 `SATISFIED` 的 obligations + `SUPPORTED` claims + 关键对抗检查通过 + 可复现材料齐全 + 局限已声明；High-Assurance 还需独立审计（审计器只读产物，不依赖求解过程的私有推理）。
 
-## 当前版本：v0.5.0 Evidence-driven pipeline
+## 当前版本：v0.5.1 Evidence-driven pipeline
 
 本版本新增：v3 run/ledger evidence graph；独立的 verification / obligation / claim / run 状态；inputs/raw 冻结快照和 SHA-256 校验；typed verification recipes；真实输出量化后的硬约束复检；九段科学报告、symbols 和 Answer Coverage；结构化失败启发；PROJECT_INITIAL_REVIEW 与 PAPER_FINAL_REVIEW 两种论文质量评审；以及不修改父 run 的 correction lineage。
 
-`PASS` 只表示某条 verification recipe 通过，不自动表示 claim `SUPPORTED` 或 run `SOLVED`。用户 waiver、未证明全局最优和部分证据只能进入 `CONDITIONAL`。CUMCM/MCM/ICM 评分是 paper-quality proxy，不是官方 CUMCM/COMAP 评分。0.4.1 仍可安装，v2 历史运行迁移后证据降级为 `LEGACY_UNVERIFIED`。
+`PASS` 只表示某条 verification recipe 通过，不自动表示 claim `SUPPORTED` 或 run `SOLVED`。用户 waiver、未证明全局最优和部分证据只能进入 `CONDITIONAL`。CUMCM/MCM/ICM 评分是 paper-quality proxy，不是官方 CUMCM/COMAP 评分。
 
 ## 两个 Skill
 
@@ -172,7 +212,7 @@ D3 方向/D4 裁决），`run-state.mjs gate` 在每次状态转移前强制校
 安装：
 
 ```bash
-dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.5.0
+dsh plugin --profile web add github:yohanchen1/MathModelingAgent#v0.5.1
 dsh --profile web --dump-config   # 检查组合层（应看到 dsh-math-modeling-agent-skills 行）
 dsh web                          # 重启以加载插件
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-math-modeling-agent",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Evidence-driven mathematical modeling and verification skills for DeepSeek Harness",
   "type": "module",
   "files": [

package/skills/math-modeling-agent/SKILL.md

@@ -15,7 +15,7 @@ Move one mathematical problem from scoped intake to an evidence-backed conclusio
 
 Accept problem text, attachments, or an existing run directory.
 
-Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is a DEEP three-beat exchange — LLM presents a complete analysis with its evidence chain, the user responds with substance (corrections, background, their own references), the LLM updates the artifact and shows the delta. Decision points: D0 six-section restatement / D1 routing once per task, D-R literature research before any candidate is built, D2 assumptions and D3 direction per subproblem, D2' on mid-subproblem discoveries, D4 verdict per round. Show the runlog digest in the chat after every round (references/report-contract.md); announce one status line before every transition; the user may interrupt at any time.
+Interaction model (references/interaction-protocol.md): execution details stay autonomous (file names, tool adapters, state fields), but every model-shaping decision is a DEEP three-beat exchange — LLM first presents the complete text in the chat body, the user responds with substance (corrections, background, their own references), then the LLM records the confirmed chat presentation, writes the artifact, and shows the delta. Decision points: D0 six-section restatement / D1 routing once per task, D-R literature research before any candidate is built, D2 assumptions and D3 direction per subproblem, D2' on mid-subproblem discoveries, D4 verdict per round. Every major phase (data profile, assumptions, claims, candidate, subproblem analysis, model, verification, robustness, evaluation and correction) follows the same chat-first rule. Show the runlog digest in the chat after every round (references/report-contract.md); announce one status line before every transition; the user may interrupt at any time.
 
 Return a concise current status, supported claims, unresolved obligations, attempt delta, artifact path, and next action or final report. The legacy Modeler → Analyzer → Correction behavior mapping is recorded in `references/original-project-parity.md`.
 

package/skills/math-modeling-agent/references/interaction-protocol.md

@@ -24,6 +24,33 @@ High-impact points (D0, D-R, D2) may loop beats 2-3 as many times as needed
 until the user says "可以了". Mathematical modeling is a deep activity;
 "skim and start solving" is a protocol violation.
 
+## Chat-first phase presentation (v0.5)
+
+每个重点环节必须先在聊天正文中展示完整、可读、可追问的文本，不能只写入 artifact，也不能只显示工具调用摘要。顺序固定为：
+
+1. LLM 在聊天中给出完整内容、依据链、当前结论和可能被推翻的条件；
+2. 给用户留下纠正、补充背景或确认的机会；
+3. 用户确认后记录 chat presentation（content hash、呈现时间、用户确认时间和先于 artifact 的顺序）；
+4. 再写入 problem-brief、analysis log、assumptions、model、result 或 report artifact；
+5. 最后才允许 run-state transition。
+
+重点阶段与最小呈现内容如下：
+
+| 阶段 | 聊天中必须完整展示 |
+|---|---|
+| D-R | 检索到的方法/背景、来源、适用范围和限制 |
+| D0 / SCOPE_FROZEN | 六段式问题重述、依赖关系和待澄清问题 |
+| INPUT_PROFILED | 每个附件的字段、单位、坐标系、范围和异常 |
+| D2-G / CLAIMS_REGISTERED | 全局假设、依据、风险、Claims 和 Obligations |
+| D3 / CANDIDATES_READY | 候选方向矩阵、选择理由、文献列和排除方向 |
+| SP1… / ATTEMPT | 当前子问题的问题分析、输入、假设、目标和边界 |
+| MODEL / EXECUTE | 完整模型方案、公式、参数、算法和预期输出 |
+| VERIFICATION | 验证路径、反例、容差、结果和未覆盖范围 |
+| EVALUATION / CORRECTION | 评价 finding、影响的 Claims、修正方案和 lineage |
+| D4 / terminal | 本轮完整结果、证据摘要、局限和最终状态建议 |
+
+run-state 只能验证结构化记录，不能直接观察聊天 UI；因此 chat presentation 是显式的 fail-closed 约束，而不是把写文件误认为已展示。缺失 presentation 时，真实 run 不得进入下一阶段。
+
 ## L1 decision points (MUST ask via the question tool)
 
 | Point | Trigger | Question | Default |
@@ -106,6 +133,12 @@ record to real files on disk.
 
 In v0.5, report/evaluation/terminal transitions also read answer-coverage.json when the v3 ledger has registered requirements. Missing or stale mappings are hard blockers; partial mappings and explicit waivers are conditional-only. EVALUATE and CORRECTION_REQUIRED are non-final lifecycle states. An evaluation finding creates a correction lineage and never rewrites the parent run or silently upgrades a claim.
 
+### Chat-first enforcement
+
+For every major phase, the complete readable content must appear in the chat body before any phase artifact is written or state transition is attempted. The agent must show the evidence chain, current conclusion, limitations and falsification conditions, then invite user correction or confirmation. Only after confirmation may it call recordChatPresentation, write problem-brief/analysis/assumption/model/result/report artifacts, and invoke gate or transition.
+
+A v3 real run has scope.chatFirstRequired=true and stores presentation records in ledger.scope.presentations. Each record must identify its stage, chat channel, content hash, presentedAt, userConfirmedAt, fullTextPresented=true and presentedBeforeArtifact=true. The machine gate cannot observe the UI directly, so it treats a missing or malformed record as a hard blocker and never treats a file-only artifact as proof of chat presentation. Major stages are D-R, D0, INPUT_PROFILED, D2-G, D3, each SPn, MODEL, VERIFICATION, EVALUATION, CORRECTION and D4.
+
 ## Phase pace — interactive beats between phases (v2.8)
 
 The exposition is delivered PHASE BY PHASE, never as a firehose. The phase

package/skills/math-modeling-agent/schemas/ledger.schema.json

@@ -43,6 +43,15 @@
         "robustnessExempt": {
           "type": "boolean",
           "description": "True only for tasks with no perturbable parameters (pure proofs); terminal states otherwise require a PASSED robustness-kind obligation."
+        },
+        "chatFirstRequired": {
+          "type": "boolean",
+          "description": "Require complete chat presentation and user confirmation before each major phase transition."
+        },
+        "presentations": {
+          "type": "array",
+          "description": "Chat-first records: complete text presented, content hash, user confirmation and presentation order.",
+          "items": { "type": "object" }
         }
       }
     },

package/skills/math-modeling-agent/scripts/evidence-store.mjs

@@ -258,7 +258,7 @@ export function createGraph(taskId) {
   return {
     schemaVersion: 3,
     taskId,
-    scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false },
+    scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false, chatFirstRequired: true, presentations: [] },
     requirements: [],
     assumptions: [],
     claims: [],

package/skills/math-modeling-agent/scripts/run-state.mjs

@@ -14,6 +14,12 @@ export const MODE_DEFAULTS = Object.freeze({
   standard: Object.freeze({ attempts: 12, researchQueries: 12, computeSeconds: 1800 }),
   'high-assurance': Object.freeze({ attempts: 24, researchQueries: 30, computeSeconds: 7200 }),
 })
+export const CHAT_PHASE_REQUIREMENTS = Object.freeze({
+  SCOPE_FROZEN: 'D0', INPUT_PROFILED: 'INPUT_PROFILED', CLAIMS_REGISTERED: 'D2-G',
+  CANDIDATES_READY: 'D3', ATTEMPT: 'SUBPROBLEM', EXECUTE: 'MODEL', VERIFY: 'VERIFICATION',
+  EVALUATE: 'EVALUATION', CORRECTION_REQUIRED: 'CORRECTION', REVISE: 'CORRECTION',
+  SOLVED: 'D4', CONDITIONAL: 'D4', PARTIAL: 'D4', INCONCLUSIVE: 'D4', REFUTED: 'D4',
+})
 
 const NON_FINAL_STATES = ['TRIAGE', 'SCOPE_FROZEN', 'INPUT_PROFILED', 'CLAIMS_REGISTERED', 'CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'EVALUATE', 'CORRECTION_REQUIRED', 'REVISE', 'RESEARCH', 'FORK']
 const FINAL_STATES = ['SOLVED', 'PARTIAL', 'CONDITIONAL', 'INCONCLUSIVE', 'REFUTED', 'INFEASIBLE', 'UNIDENTIFIABLE', 'BLOCKED', 'CANCELLED']
@@ -383,7 +389,7 @@ function validateJournal(events, diagnostics) {
   })
 }
 
-export async function initRun(root, { taskId, mode = 'standard', budget, budgets, contract }, runtime = {}) {
+export async function initRun(root, { taskId, mode = 'standard', budget, budgets, contract, chatFirstRequired = contract === true }, runtime = {}) {
   assertTaskId(taskId); assertMode(mode)
   const effectiveBudget = { ...MODE_DEFAULTS[mode], ...(budget ?? budgets ?? {}) }
   const budgetDiagnostics = []
@@ -398,7 +404,7 @@ export async function initRun(root, { taskId, mode = 'standard', budget, budgets
     }
     const ledger = {
       schemaVersion: SCHEMA_VERSION, taskId,
-      scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false, ...(contract === false ? { contractExempt: true } : {}) },
+      scope: { independentAuditPassed: false, interactions: [], decisionStack: [], robustnessExempt: false, chatFirstRequired: chatFirstRequired === true, presentations: [], ...(contract === false ? { contractExempt: true } : {}) },
       assumptions: [], claims: [], obligations: [], subproblems: [], candidates: [], issues: [],
       requirements: [], evidence: [], verifications: [], failures: [],
     }
@@ -521,12 +527,35 @@ function hasSubproblemD2(scope, subproblem) {
   return scope.interactions.some(entry => entry && entry.decisionPoint === 'D2' &&
     (Array.isArray(entry.scope) ? entry.scope.includes(subproblem) : entry.subproblem === subproblem))
 }
+function presentationIsValid(record, stage, subproblem) {
+  if (!record || record.channel !== 'chat' || record.status !== 'PRESENTED' || record.fullTextPresented !== true || record.presentedBeforeArtifact !== true) return false
+  if (typeof record.id !== 'string' || record.id.trim() === '' || typeof record.contentHash !== 'string' || !/^[a-f0-9]{64}$/i.test(record.contentHash)) return false
+  if (typeof record.presentedAt !== 'string' || record.presentedAt.trim() === '' || typeof record.userConfirmedAt !== 'string' || record.userConfirmedAt.trim() === '') return false
+  if (stage === 'SUBPROBLEM' || stage === 'MODEL' || stage === 'VERIFICATION') return (record.stage === stage || (stage === 'SUBPROBLEM' && record.stage === subproblem)) && record.subproblem === subproblem
+  return record.stage === stage || (stage === 'SUBPROBLEM' && record.stage === subproblem)
+}
+
+function hasChatPresentation(scope, stage, subproblem) {
+  return Array.isArray(scope?.presentations) && scope.presentations.some(record => presentationIsValid(record, stage, subproblem))
+}
+
+function chatPresentationViolations(scope, target, subproblem) {
+  if (scope?.chatFirstRequired !== true) return []
+  const stage = CHAT_PHASE_REQUIREMENTS[target]
+  const required = target === 'SCOPE_FROZEN' ? ['D-R', 'D0'] : (stage ? [stage] : [])
+  const missing = required.filter(value => !(value === 'SUBPROBLEM' && !subproblem) && !hasChatPresentation(scope, value, subproblem))
+  const subject = subproblem ? ' for ' + subproblem : ''
+  return missing.map(value => 'chat presentation for ' + value + subject + ' is required before ' + target + ' (show the complete text in chat and obtain user confirmation)')
+}
+
 function interactionContractViolations(run, ledger, to, reason, subproblem) {
   if (ledger.schemaVersion !== SCHEMA_VERSION) return []
   const scope = ledger.scope ?? {}
   if (scope.contractExempt === true) return []
   const violations = []
   const transitional = to !== undefined
+  const presentationTarget = transitional ? to : run.status
+  violations.push(...chatPresentationViolations(scope, presentationTarget, subproblem))
   const earlyStop = ['BLOCKED', 'CANCELLED'].includes(run.status)
   const statusOrder = ['TRIAGE', 'RESEARCH', 'SCOPE_FROZEN', 'INPUT_PROFILED', 'CLAIMS_REGISTERED', 'CANDIDATES_READY', 'ATTEMPT', 'EXECUTE', 'VERIFY', 'EVALUATE', 'CORRECTION_REQUIRED', 'REVISE', 'FORK']
   const reached = (target) => transitional
@@ -580,8 +609,9 @@ function interactionContractViolations(run, ledger, to, reason, subproblem) {
   }
   return violations
 }
-function enforceInteractionContract(run, ledger, to, reason) {
-  const violations = interactionContractViolations(run, ledger, to, reason)
+function enforceInteractionContract(run, ledger, to, reason, subproblem) {
+  if (ledger.scope?.chatFirstRequired !== true) return
+  const violations = interactionContractViolations(run, ledger, to, reason, subproblem)
   if (violations.length > 0) throw new Error(`interaction contract violated: ${violations.join('; ')}`)
 }
 
@@ -605,6 +635,7 @@ function validateTransitionInput(input) {
     if (input[key] !== undefined && (!Array.isArray(input[key]) || input[key].some(id => typeof id !== 'string'))) throw new Error(`${key} must be an array of strings`)
   }
   if (linkedIds(input).length === 0) throw new Error('transition requires at least one evidence or issue ID')
+  if (input.subproblem !== undefined && input.subproblem !== null && (typeof input.subproblem !== 'string' || input.subproblem.trim() === '')) throw new Error('subproblem must be a nonempty string or null')
   if (input.patch !== undefined && (!isObject(input.patch) || Object.keys(input.patch).some(key => key !== 'bestCandidateId'))) throw new Error('patch may only contain bestCandidateId')
   if (input.patch && (!Object.hasOwn(input.patch, 'bestCandidateId') || (input.patch.bestCandidateId !== null && typeof input.patch.bestCandidateId !== 'string'))) throw new Error('bestCandidateId must be a string or null')
 }
@@ -621,6 +652,39 @@ function validateAuthoritativeState(run, ledger, events) {
   if (diagnostics.length > 0) throw new Error(`invalid run state: ${diagnostics.join('; ')}`)
 }
 
+const PRESENTATION_STAGES = new Set(['D-R', ...new Set(Object.values(CHAT_PHASE_REQUIREMENTS))])
+
+function validateChatPresentationRecord(record) {
+  if (!isObject(record)) throw new TypeError('chat presentation must be an object')
+  for (const field of ['id', 'stage', 'channel', 'contentHash', 'presentedAt', 'userConfirmedAt', 'status']) {
+    if (typeof record[field] !== 'string' || record[field].trim() === '') throw new TypeError(field + ' is required')
+  }
+  if (!PRESENTATION_STAGES.has(record.stage) && !/^SP[0-9]+$/.test(record.stage)) throw new TypeError('chat presentation stage is invalid')
+  if (record.channel !== 'chat') throw new TypeError('chat presentation channel must be chat')
+  if (record.status !== 'PRESENTED') throw new TypeError('chat presentation status must be PRESENTED')
+  if (!/^[a-f0-9]{64}$/i.test(record.contentHash)) throw new TypeError('chat presentation contentHash must be SHA-256 hex')
+  if (record.fullTextPresented !== true) throw new TypeError('fullTextPresented must be true')
+  if (record.presentedBeforeArtifact !== true) throw new TypeError('presentedBeforeArtifact must be true')
+  if (['SUBPROBLEM', 'MODEL', 'VERIFICATION'].includes(record.stage) && (typeof record.subproblem !== 'string' || record.subproblem.trim() === '')) throw new TypeError(record.stage + ' presentation requires subproblem')
+  return record
+}
+
+export async function recordChatPresentation(root, record, runtime = {}) {
+  validateChatPresentationRecord(record)
+  return withLock(root, MUTATION_LOCK_FILE, 'chat-presentation', async () => {
+    const p = paths(root)
+    const ledger = await readJson(p.ledger)
+    if (ledger.schemaVersion !== SCHEMA_VERSION) throw new Error('chat presentations require a v3 ledger')
+    ledger.scope ??= {}
+    ledger.scope.presentations ??= []
+    if (!Array.isArray(ledger.scope.presentations)) throw new Error('ledger.scope.presentations must be an array')
+    if (ledger.scope.presentations.some(value => value?.id === record.id)) throw new Error('duplicate chat presentation id: ' + record.id)
+    ledger.scope.presentations.push(clone(record))
+    await atomicWrite(p.ledger, ledger, runtime)
+    return clone(record)
+  }, runtime)
+}
+
 export async function transitionRun(root, input, runtime = {}) {
   validateTransitionInput(input)
   return withLock(root, MUTATION_LOCK_FILE, 'transition', async () => {
@@ -631,6 +695,7 @@ export async function transitionRun(root, input, runtime = {}) {
     validateAuthoritativeState(run, ledger, events)
     if (!isAllowedTransition(run.status, input.to)) throw new Error(illegalTransitionMessage(run.status, input.to))
     if (input.to === 'SOLVED') enforceSolvedGate(run, ledger)
+    enforceInteractionContract(run, ledger, input.to, input.reason, input.subproblem)
     const timestamp = now()
     const bestCandidateId = input.patch && Object.hasOwn(input.patch, 'bestCandidateId') ? input.patch.bestCandidateId : run.bestCandidateId
     const next = { ...run, status: input.to, currentAttempt: nextAttempt(run.currentAttempt, input.to), eventSequence: run.eventSequence + 1, bestCandidateId, updatedAt: timestamp }
@@ -814,7 +879,7 @@ async function cli(argv) {
       process.exitCode = 1
       return { error: `interaction contract violated: ${gate.violations.join('; ')}`, gate }
     }
-    return transitionRun(root, { to: options.to, reason: options.reason, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
+    return transitionRun(root, { to: options.to, reason: options.reason, subproblem: options.subproblem, evidenceIds: options.evidence ? options.evidence.split(',').filter(Boolean) : [], issueIds: options.issues ? options.issues.split(',').filter(Boolean) : [], patch: options.candidate ? { bestCandidateId: options.candidate } : undefined })
   }
   if (command === 'validate') {
     const result = await validateRun(root, options['task-id'])