model-first-reasoning

Model-First Reasoning（MFR）

一种严谨的方法论：在进行任何推理或实现之前，必须先构建显式的问题模型。该模型将成为一个冻结的契约，约束所有后续工作。

基于 Kumar & Rana（2025），《Model-First Reasoning LLM Agents: Reducing Hallucinations through Explicit Problem Modeling》（arXiv:2512.14474）

MFR 为何有效

幻觉不仅仅是生成错误陈述——它是缺少对问题空间的明确定义模型时进行推理的一种症状。

推理不会创建结构，而是在结构上运作。当结构是隐式的或不稳定时，推理就会变得不可靠。MFR 提供“软符号 grounding”——提供足够的结构来稳定推理，同时不施加僵硬的形式主义。

核心原则

阶段 1 生成 MODEL。阶段 2 仅在该模型范围内进行推理／实现。

这可以避免常见的失败模式：推理引入临时决策、遗漏约束，或编造未以问题定义为依据的行为。

不可妥协的规则

1. **阶段 1（建模）**不得生成代码或解决方案步骤——只能生成形式化模型
2. **阶段 2（实现）**不得引入新的实体、状态、操作或约束
3. 如果需要模型中没有的内容：准确输出 MODEL INCOMPLETE + 需要添加的内容，然后停止
4. 不得编造 API 或依赖项。如果未提供，则应提问（未知项）或创建明确标记为 STUB 的存根

将模型作为契约

创建模型后，在编写代码之前运行一次 MODEL AUDIT：

审计检查项

检查项	描述
覆盖度	每项用户需求都恰好归入以下之一：约束、目标／验收标准，或操作的前置条件／效果
可操作性	计划所需的每项操作都已作为操作列出
一致性	约束之间没有相互矛盾；操作效果不会违反不变量
可测试性	每项约束至少有 1 个测试预言

如果任何审计检查未通过，请修改模型（仍处于阶段 1），直至通过。

冻结规则

审计通过后，将模型视为只读的事实来源。

如果在实现过程中发现信息缺失：

1. 输出一个 MODEL PATCH（最小改动）
2. 使用更新后的模型，从头重新开始阶段 2

验证

创建模型后，将其写入 model.json 并运行验证器：

python scripts/validate-model.py model.json

退出代码：

• 0 = 有效，可进入阶段 2
• 1 = 结构无效（修正后重试）
• 2 = 有效但存在未知项（阶段 1 结束后停止）

输出格式

阶段 1：MODEL

模型可以用自然语言、半结构化文本或 JSON 表示。灵活性有助于提升遵循度——关键在于表示必须明确、可检查且稳定。

对于代码生成任务，推荐使用以下结构化格式。请参考 MODEL_TEMPLATE.json：

{
  "deliverable": {
    "description": "What we're building",
    "files_expected": ["path/to/file.ts", ...]
  },
  "entities": [
    {"name": "EntityName", "description": "...", "properties": [...]}
  ],
  "state_variables": [
    {"name": "varName", "type": "...", "initial": "...", "description": "..."}
  ],
  "actions": [
    {
      "name": "actionName",
      "description": "...",
      "preconditions": ["..."],
      "effects": ["..."],
      "parameters": [...]
    }
  ],
  "constraints": [
    {"id": "C1", "statement": "...", "type": "invariant|precondition|postcondition"}
  ],
  "initial_state": ["description of starting conditions"],
  "goal": ["acceptance criteria"],
  "assumptions": ["things we assume to be true"],
  "unknowns": ["questions that must be answered before proceeding"],
  "requirement_trace": [
    {
      "requirement": "<verbatim from user>",
      "represented_as": "goal|constraint|action",
      "ref": "C1|action_name|goal_item"
    }
  ],
  "test_oracles": [
    {"id": "T1", "maps_to": ["C1"], "description": "how to verify constraint"}
  ]
}

重要：如果 unknowns 不为空，阶段 1 结束后必须停止。未知项解决前，不得实现。

阶段 1.5：MODEL AUDIT

返回：

{
  "audit_pass": true|false,
  "issues": [
    {"type": "coverage|operability|consistency|testability", "detail": "..."}
  ]
}

如果 audit_pass 为 false，请停止并返回阶段 1 修改模型。

阶段 2：实现

仅使用冻结的模型：

A）计划

使用编号步骤，每一步都必须是已定义操作的实例：

Step 1: [action_name]
  - Preconditions check: [list which preconditions are satisfied]
  - Effects applied: [what state changes]
  - Constraints check: [C1, C2, ...]

B）代码

创建 deliverable.files_expected 中的所有文件：

模型元素	代码映射
entities / state_variables	类型、接口、数据模型
actions	带验证和明确失败模式的函数／模块
constraints	运行时检查、防御性解析、不变量

C）测试

实现所有 test_oracles。每项约束都必须至少由 1 个测试覆盖。

D）验证映射

对于每项约束，记录：

• 在代码中的强制执行位置（文件:行）
• 覆盖该约束的测试

何时使用 MFR

MFR 在以下场景中最有价值：

• 复杂状态机——状态转换必须有效
• 包含不变量的业务逻辑——必须始终遵守的规则
• 数据转换——输入／输出契约至关重要
• 多步骤工作流——各步骤之间存在依赖关系
• 安全关键功能——错误代价高昂
• 协作式规范——模型充当文档

不适用场景： 简单的单步骤任务，显式建模的开销大于其收益。

与其他推理策略的关系

MFR 是互补的，而非竞争关系：

• 与 Chain-of-Thought 配合： 在第 2 阶段使用 CoT，基于模型进行逐步推理
• 与 ReAct 配合： 将模型视为持久状态，由操作对其进行处理
• 与规划 Agent 配合： 模型提供领域规范，供规划器据此推理

MFR 提供了一个基础层，可提升约束密集型领域中任何推理策略的稳健性。

工作流示例

User: Build a shopping cart that enforces: max 10 items, no duplicate SKUs,
      total can't exceed $1000

You: [PHASE 1: MODEL]
{
  "entities": [
    {"name": "CartItem", "properties": ["sku", "price", "quantity"]}
  ],
  "constraints": [
    {"id": "C1", "statement": "cart.items.length <= 10", "type": "invariant"},
    {"id": "C2", "statement": "all SKUs in cart are unique", "type": "invariant"},
    {"id": "C3", "statement": "sum(items.price * items.quantity) <= 1000", "type": "invariant"}
  ],
  "actions": [
    {
      "name": "addItem",
      "preconditions": ["cart.items.length < 10", "sku not in cart", "new total <= 1000"],
      "effects": ["item added to cart"]
    }
  ],
  ...
}

[PHASE 1.5: MODEL AUDIT]
{
  "audit_pass": true,
  "issues": []
}

[PHASE 2: IMPLEMENTATION]
// Now implementing strictly from the model...

请记住

模型不是额外负担——它本身就是规范。复杂推理中的大多数失败都是表征问题，而非推理问题：推理本身没有问题，但它基于对问题不完整或不稳定的理解进行。

通过将模型外化，我们让假设可供检查、约束可强制执行、错误可诊断。模型成为意图与实现之间的契约。

先建模，再推理。绝不可颠倒顺序。