# **【文枢·数学】智能评分系统架构蓝图 (WenShu-Math Blueprint)**

**Version**: 1.0
**Status**: Draft
**Owner**: HiFi Agent Studio
**Date**: 2025-12-05

---

## **1. 核心愿景与定义 (Vision & Definition)**

### **1.1 身份宣言**
我们不构建“自动批改脚本”，我们要构建的是 **“具备专家级认知能力的虚拟数学助教”**。
遵循 **HiFi Agent Studio** 的价值观，本项目旨在解决传统OCR批改系统的“弱逻辑、无过程、低诊断”痛点，通过 **CCPE（智核提示工程）** 将人类数学专家的隐性思维（如一题多解判定、过程分判定、错误归因）显性化，并注入AI。

### **1.2 核心差异化**
与“文枢·语文”的“登山模型”（水平分级）不同，“文枢·数学”采用 **“通关模型”** ：
*   **从“审美鉴赏”转向“逻辑状态机”**：不评价“好不好”，只判定“对不对”及“通不通”。
*   **引入 ECF (Error Carried Forward) 机制**：模拟真人阅卷，允许“错误传递”，精准给付过程分。
*   **从“得分”转向“诊断”**：利用教材锚点，实现从“扣分”到“知识点补救”的闭环。

---

## **2. 系统架构：“四层漏斗”理科版 (System Architecture)**

基于文枢通用架构，针对理科特性进行重构：

*   **L1: 宪法层 (Constitution Layer) - [逻辑公理库]**
    *   不再是年级水平描述，而是 **《数学逻辑判例法》** 。
    *   定义什么是 `VALID` (逻辑有效)、`JUMP_VALID` (合理跳步)、`ECF` (错误传递) 以及原子动作约束（如“设未知数规范”）。
*   **L2: 规则生成层 (Prosecutor Layer) - [逻辑架构师]**
    *   **角色**：检察官 (Prosecutor)。
    *   **任务**：输入题目与标答，进行 **“解法泛化”** ，生成包含多路径（Pathfinding）的结构化评分细则（JSON刑法）。
*   **L3: 执行层 (Judge Layer) - [严谨判官]**
    *   **角色**：法官 (Judge)。
    *   **任务**：基于“刑法”，比对学生答卷，执行状态机判定，输出结构化判决书。
*   **L4: 诊断层 (Doctor Layer) - [诊疗系统]**
    *   **任务**：解析判决书，提取错误根因，映射至具体教材版本章节，生成补救方案。

---

## **3. 核心工作流 (Core Workflow)**

### **Step 1: 立法 (Legislation) —— 检察官介入**
*   **输入**:
    *   题目文本/图片 + 标准答案（自然语言）。
    *   **元数据**: 年级（决定跳步容忍度）、教材版本（如“人教A版”）、总分。
    *   *Reference*: [附件1：数学检察官CCPE定义]
*   **过程**:
    *   语义解析 -> 知识图谱调用 -> **多解法路径预测** -> 步骤切分 -> 权重分配。
*   **输出**:
    *   **《案件执行刑法 (Criminal Law JSON)》**：包含合法路径树、关键得分点、教材知识点锚点。

### **Step 2: 审判 (Judgement) —— 法官介入**
*   **输入**:
    *   《案件执行刑法》 (from Step 1)。
    *   学生答卷切片图 (Evidence)。
    *   (可选) 辅助OCR文本提示。
    *   *Reference*: [附件2：数学法官CCPE定义]
*   **过程**:
    *   手写体识别 -> 路径匹配 (Path Matching) -> 步骤状态判定 (State Check) -> **ECF处理** -> 异常标记。
*   **输出**:
    *   **《判决书 (Verdict JSON)》**：包含最终得分、步骤级详情、错误归因代码。

### **Step 3: 归因与反馈 (Diagnosis) —— 医生介入**
*   **输入**: 《判决书》。
*   **过程**: 聚合错误类型（如“运算失误” vs “概念不清”） -> 关联教材章节。
*   **输出**: 错题本条目、推荐微课、强化练习题。

---

## **4. 关键数据协议 (Key Data Protocols)**

为确保工程落地的确定性，核心交互协议如下：

### **4.1 检察官输入协议 (Input for Prosecutor)**
```json
{
  "grade": "高二",
  "textbook_context": {
    "version": "人教A版(2019)",
    "module": "选择性必修第二册"
  },
  "question_data": { "text": "...", "images": [...] },
  "standard_solution": "教师提供的自然语言解题步骤..."
}
```

### **4.2 法官输出协议 (Output from Judge)**
*此结构为后续“错题本”的核心数据源。*
```json
{
  "verdict": {
    "total_score": 11,
    "step_details": [
      {
        "step_id": 1,
        "status": "PERFECT",
        "score": 4,
        "student_segment": "OCR识别到的学生笔迹"
      },
      {
        "step_id": 2,
        "status": "ECF_GRANTED", // 关键：错误传递给分
        "score": 3,
        "deduction_reason": "上一步计算错误，但本步逻辑正确"
      }
    ],
    "diagnosis": {
      "error_code": "ERR_CALC", // 错误枚举
      "root_cause": "二次项系数处理错误",
      "textbook_anchor": "选修2_2.2节_等差数列性质" // 只有输入了教材版本，这里才能生成
    }
  }
}
```

---

## **5. 落地执行策略 (Execution Strategy)**

遵循 **HiFi "Hybrid Engineering" & "Wizard of Oz"** 原则：

### **Phase 1: 模拟与校准 (The Wizard)**
*   **目标**：验证“宪法”与“检察官”生成的规则是否足够覆盖真实学生样本。
*   **行动**：
    1.  收集50道典型高中数学大题（涵盖代数、几何、统计）。
    2.  人工（专家）扮演“检察官”，手写生成JSON刑法。
    3.  使用AI（法官）跑通评分。
    4.  **Process is Data**：记录AI法官的每一次误判，反向修正“宪法”中的原子动作约束。

### **Phase 2: 检察官自动化 (The Automation)**
*   **目标**：让AI接管“规则生成”工作。
*   **行动**：
    1.  部署数学检察官Prompt。
    2.  输入教师标答，自动化生成规则。
    3.  人工审核规则的“泛化性”（是否涵盖了非标答的合法路径）。

### **Phase 3: 闭环集成 (The Integration)**
*   **目标**：接入教材数据库，打通诊断层。
*   **行动**：
    1.  建立“教材目录知识图谱”（Mapping Table）。
    2.  前端渲染：在学生作业上高亮错误步骤，并直接推送教材链接。

---

## **6. 配套文档清单 (Attachments)**

以下文档将作为本蓝图的附录，直接指导开发与Prompt编写：

*   **[Doc-01] 文枢·数学逻辑宪法 (Math-Constitution v1.0)**
    *   *内容*：定义 `global_logic_scale`，原子动作约束库，状态机逻辑。
    *   *状态*：[已就绪/引用Json]
*   **[Doc-02] 数学检察官 CCPE 定义 (Prosecutor Agent Profile)**
    *   *内容*：Prompt架构，负责将自然语言标答转译为结构化多路径规则。
    *   *状态*：[已就绪]
*   **[Doc-03] 数学法官 CCPE 定义 (Judge Agent Profile)**
    *   *内容*：Prompt架构，负责执行评分、OCR校对、ECF判定。
    *   *状态*：[待完善]
*   **[Doc-04] 错误代码与教材映射表 (Diagnosis Enum & Mapping)**
    *   *内容*：定义 `ERR_CALC`, `ERR_LOGIC` 等枚举值及教材元数据结构。
    *   *状态*：[待开发]