「希沃智教π：不漏一题，不落一人」赛道参赛项目 · 开题材料仓库
从自动判分到过程诊断，让每个学生都被认真对待。
面向 K12 数学、物理、英语作业场景，《智批π》不是又一个"OCR → 判对错 → 模板评语"的自动批改工具，而是：
AI 错因诊断系统 + 教师可控批改工作台 + 学生长期学习画像 + 班级教学闭环平台
普通 AI 批改回答的是"这道题对不对"；《智批π》回答的是：
学生为什么错？错在哪一步？老师是否信任这个判断？下一步该怎么补？下节课该怎么教？
| # | 创新点 | 解决的问题 | 实现状态 |
|---|---|---|---|
| 1 | 步骤级证据链批改 | 把理科题拆为"题意理解→公式选择→数值代入→单位检查→最终答案"等批改节点，识别部分正确的过程并给过程分 | Demo 已实现：每步判分附引用学生作答原文的证据（evidence），字迹难辨步骤显式标注并提示人工复核 |
| 2 | 红黄绿置信度分流 | 高置信度 AI 自动批、中置信度教师一键确认、低置信度转人工——AI 没把握就交给老师，教师保留最终裁决权 | Demo 已实现：§9.7 五因子公式真实计算，答案匹配度由教师上传的答案页逐题比对得出、无题库时按重归一化剔除；另设跨厂商双模型交叉验证为后置防线，分差超过满分 15% 一票否决转人工 |
| 3 | 两层错因标签 + 长期错因画像 | 不止"哪个知识点错得多"，而是"为什么错"（概念/公式/计算/单位/审题/图形…），并持续追踪学生错因演变 | Demo 已实现：§6.11 十类错因标签 + 学生个人错因画像与趋势判断（历史时间线为模拟数据，界面已标注） |
| 4 | 批改→讲评→补救→复测教学闭环 | 批改数据自动生成班级薄弱点热力图、下节课讲评建议与补救练习，从批改工具升级为教学决策助手 | Demo 已实现：班级看板薄弱点 + 讲评建议 + 讲评课件大纲一键复制为讲评课件底稿（Markdown，可粘贴至希沃白板、飞书文档等备课环境） |
| 路径 | 内容 |
|---|---|
| docs/01-开题报告.md | 开题报告：Part 1 命题前置分析与洞察 + Part 2 整体解决方案设计 |
| docs/02-详细设计方案.md | 完整产品与技术设计方案（21 章：痛点、创新点、架构、数据库、API、Demo、风险、合规） |
| docs/03-行业研究与竞品分析.md | 行业数据、政策环境、8 家竞品横向对比、机会洞察 |
| docs/04-技术说明文档.md | OCR 方案、知识建模、评语生成策略、置信度分流实现（对应命题交付要求） |
| docs/05-批改样例与数据分析.md | 三学科批改样例解读 + 45 人班级模拟学情分析样本 |
| docs/06-参考资料清单.md | 42 条参考资料（行业报告 / 竞品资料 / 学术研究 / 政策文件 / 技术资料 / 教师负担调研 / 飞书 AI 能力 / 成本资料） |
| docs/07-实测评测方案与报告.md | 实测评测方案（预注册） |
| docs/08-实测踩坑记录.md | 实测踩坑与分流/网关观测 |
| docs/09-教师工作台P0改造说明.md | 教师工作台 P0：同屏审卷 / 步骤级改判 / 筛选批量（设计完成·待实现） |
| docs/00-命题原文.md | 赛道命题原文 |
| prompts/grading_prompts.md | 过程级批改 / 错因归因 / 个性化评语 / 班级讲评等 6 个生产级 Prompt |
| samples/ | 数学、物理、英语三份完整批改样例（输入 → 逐步批改 → 分流 → 教师审核，JSON） |
| demo/ | 可运行 Demo 原型（FastAPI，默认 mock 模式免 API Key） |
| team/团队介绍与分工.md | 团队成员、分工与协作机制 |
方式一：一键启动（推荐，Windows） —— 双击 demo/run_demo.bat，或在 PowerShell 中运行 demo/run_demo.ps1。脚本自动探测可用 Python（避开 Microsoft Store 占位命令）→ 安装依赖 → 启动服务并打开浏览器。
方式二：手动启动
cd demo
pip install -r requirements.txt
python -m uvicorn app:app --port 8010浏览器打开 http://127.0.0.1:8010，即可体验完整闭环：作业照片提交（38 份内置真实作业，或本地上传）→ 手写识别（多模态大模型三阶段：版面解析 → 内容归属 → 定向复识）→ 过程级批改（逐步证据链 + 错因标签 + 个性化评语）→ 教师工作台（红黄绿 + 终审改分/改错因/改评语 + 通过率回灌置信度）→ 班级看板（薄弱点 + 讲评课件大纲生成 + 学生个人错因画像）。
-
内置样例：三科真实作业照片，语文 7 / 数学 5 / 英语 7 份学生页，配 19 份教师答案页（「题库」夹，用于建题库），卷面无姓名信息；
-
免 API Key 可看：批改结果、教师工作台、班级看板三屏用的是内置基线数据（3 道题 × 11 份不同水平作答，覆盖绿/黄/红全部分流，置信度按设计方案公式真实计算）；
-
拍照识别需要一枚多模态密钥：内置样例是真实作业原件、没有预置转写，未配密钥时识别会明确报不可用，不做假降级；
-
真实模型模式（环境变量，均为 OpenAI 兼容接口）：
ZHIPI_VLM_API_KEY/ZHIPI_VLM_BASE_URL/ZHIPI_VLM_MODEL：多模态手写识别（默认qwen-vl-max），配置后可识别任意上传的作业照片；ZHIPI_LLM_API_KEY/ZHIPI_LLM_BASE_URL/ZHIPI_LLM_MODEL：文本过程级批改（如 DeepSeek / Qwen），大模型按 Rubric 逐步批改并输出证据链；ZHIPI_DOUBLE_CHECK：二次批改一致性开关（默认开启，设0关闭），两次独立批改的吻合度作为置信度因子；ZHIPI_LLM_API_KEY_2/ZHIPI_LLM_BASE_URL_2/ZHIPI_LLM_MODEL_2：双模型交叉验证（选配，三项配齐生效），黄/红结果由第二模型复核，分歧显著强制转人工。
只配一把 VLM Key 也能跑通全链路——文本批改自动复用该凭据。
- 内置样例批改（约 30 秒）：「① 拍照提交」→ 在「数学样例」夹点「查看夹内文件」→ 任一份点「加入待批清单」→「全部批改」，查看逐步证据链批改结果与画回原图的批改痕迹；
- 教师答案页建题库（现场高光）：切到「题库 · 教师答案页」夹，勾选同一套答案的若干份 →「合并建库」，再回学生夹批改，判分即按教师标准答案逐题对齐；也可直接上传自己的作业照片走同一条链路（需配置
ZHIPI_VLM_API_KEY）； - 教师工作台终审：对一份黄色作答「终审修改」（改分 / 改判错因 / 修订评语），提交后可见该题教师通过率回灌置信度因子的提示，同题未终审作答置信度实时更新；
- 班级看板：一键生成讲评课件大纲并复制为讲评课件底稿（可粘贴至希沃白板、飞书文档等备课环境），查看学生个人错因画像与趋势判断；
- 飞书协同：推送审核提醒互动卡片 + 同步多维表格学情台账。
按比赛规则"参赛作品至少须运用 1 项飞书 AI 产品能力"，本方案遵循**"批改在系统、协同在飞书"**原则设计集成（详见设计方案 §13.2 与技术说明文档）：
| 集成点 | 使用的飞书能力 | 作用 | 实现状态 |
|---|---|---|---|
| 学情台账（主用） | 多维表格 + AI 字段捷径 | 批改结果自动写入班级学情台账，AI 字段生成一句话错因摘要与个性化学习建议，仪表盘呈现薄弱点 | Demo 已实现（live 模式需配置凭据） |
| 审核流转 | 机器人互动卡片 | 批改完成即推送教师待审卡片（红黄绿统计 + 一键跳转），终审后可选推送家长评语卡片 | Demo 已实现（live 模式需配置凭据） |
| 讲评助手 | 知识问答 / Aily | 错因标签体系、Rubric 与学情报告沉淀飞书知识库，教师在飞书内问答获取讲评建议 | 设计完成·入围后实施 |
| 讲评提纲 | 文档 AI | 讲评建议一键导出飞书文档，AI 润色后供教研组协作批注 | 部分实现（大纲生成 Demo 已实现，文档 AI 润色入围后实施） |
各集成点实现状态与设计方案 §13.2 的标注一致。
Demo 已内置飞书集成模块（demo/pipeline/feishu.py），两种模式：演示模式（未配置凭据）做内容预览，展示将推送的卡片内容与将写入的表格记录；live 模式（配置 ZHIPI_FEISHU_WEBHOOK 等环境变量）真实推送互动卡片、真实写入多维表格。现场演示采用 live 模式，任何异常自动降级为演示模式，满足"现场可演示飞书 AI 功能实际应用效果"的比赛要求。
| 成员 | 院校 | 专业 | 分工 |
|---|---|---|---|
| 成员 A | 汕头大学 | 机械工程 | 场景与算法：理科过程题建模、错因标签体系、Rubric 与批改 Prompt |
| 成员 B | 中山大学 | 集成电路工程 | 识别与流程：图像预处理、OCR/多模态链路、置信度分流、学情看板 |
| 成员 C | 西安电子科技大学 | 计算机技术 | 系统工程：前后端、数据库、API、LLM 接入与部署 |
三个专业恰好对应系统三条技术主线：理科场景建模（机械工程）→ 识别与流程链路（集成电路工程）→ 系统工程实现（计算机技术）。
依照比赛跨校组队规则，第一负责人为成员 A（所在学校：汕头大学）。
- 本仓库为参赛开题材料；
docs/05中的班级学情数据为模拟数据，仅用于演示分析口径与报告形态，已在文中显著标注； - Demo 内置 38 份真实作业照片（三科学生页 19 份 + 配对教师答案页 19 份），卷面本身不含姓名学号，以匿名
item_id标识； - 方案遵循《个人信息保护法》《未成年人网络保护条例》《生成式人工智能服务管理暂行办法》要求设计（见设计方案 §19.5），优先选用可私有化部署的国产大模型。
ZhiPi-AI-Homework-Grading/
├── DESIGN.md 界面与视觉设计规范（含逐次改版回写表）
├── docs/ 开题报告、行业研究、技术文档、实测报告、40 强赛方案正文
│ └── assets/ 方案配图与动图（图源见 tools/figures/）
├── demo/ 可运行 Demo 原型（FastAPI）
│ ├── pipeline/ 批改链路：PDF 拆页、三阶段识别、答案页建库、整页批改、
│ │ 原图留痕、置信度分流、学情分析、飞书集成
│ ├── data/ 演示数据（内置样例作业页不入库，见 .gitignore）
│ ├── static/ 前端静态资源
│ └── tools/ 探针、走查脚本与内置样例打包（pack_demo_pages.py）
├── product/ 产品化重构：状态外置到 SQLite，可多 worker、可测试
├── prompts/ 批改与错因诊断 Prompt
├── samples/ 三学科批改样例（输入 → 逐步批改 → 分流 → 教师审核，JSON）
├── tools/figures/ 方案配图的 HTML 图源与渲染脚本
├── design-mock/ 界面设计稿
├── deploy/ 部署配置
└── team/ 团队材料
docs/02-详细设计方案.md 是产品与技术的主文档，DESIGN.md 管界面与视觉规范，README 只做入口概览；
demo/ 是参赛演示的实现所在，product/ 是同一套价值的产品化重构版，
prompts/ 与 docs/ 分别承载批改口径与评测/行业依据。
本仓库为参赛开题材料，不是一个可自由复用的开源软件包。当前未附加代码许可证，原因是
samples/、design-mock/、team/ 中的部分素材涉及第三方内容与团队成员信息，其再授权范围尚未逐项核定。
在此前提下：
- 可以引用、阅读、评审本仓库内容用于比赛评审、学术交流与方案参考；
- 需要事先联系：将本仓库的代码、Prompt、设计稿或批改样例用于再分发、商业用途或衍生产品；
docs/05中的班级学情数据为模拟数据；Demo 的内置样例是真实作业照片，因此不随仓库分发 （见.gitignore），仓库内不含任何真实学生作业与身份信息（详见「七、合规声明」）。
素材授权范围核定后会补充正式 LICENSE。