Marble K-9 七科错题诊断 · 图谱与引擎工作流

Overview

把"Marble 那套知识图谱结构"（原子知识点 + 先修依赖 DAG + 掌握证据）落到中国 K-9 七科， 做成错题 → 根因诊断工具：孩子一道题做错，沿知识图谱往回反推，列出最该先查的前置根因。 引擎一套（沿 DAG 反向遍历求全部祖先 + 年龄窗口/局部汇聚度排序），各科图谱各自一张，复用引擎。

当前状态（2026-07-19 收口，七科全建完 + 统一审查通过）：

• 数学/英语/语文：各 1 张图（1-9 合并总图，已内含小学+初中知识点及跨年级桥边）。
• 物理/化学/生物/地理：初中单图即其 K-9 总图（无小学版、无跨年级桥边）。
• 三处存储 MD5 全部一致：源(开发机知识库目录) / skill(本目录) / 归档(技能包产出物目录)。

所有图谱目录：本技能根目录下的 中国*图谱（共 7 个）。

Directory layout

<技能根目录>
├── 中国中小学数学图谱      graph.json（371节点，小学+初中合并）
├── 中国中小学英语图谱      graph.json（245）
├── 中国中小学语文图谱      graph.json（241）
├── 中国初中物理图谱        graph.json（97）+ _cn_phys_build/gen_assets/_audit
├── 中国初中化学图谱        graph.json（58）
├── 中国初中生物图谱        graph.json（93）
├── 中国初中地理图谱        graph.json（66）
├── engine                  diagnose.py(Agent主入口·对话内CLI) / app.py(引擎+7套确定性定位) / config.py / product.py(可选Web) / locate_demo.py
├── validate                review.py(技能内自洽) / review_all_3repo.py(三处MD5) / fix_graphs.py / regen_and_sync.py
├── references              locate_logic.md / restart.md / schema.md
└── scripts                 validate_graph.py / verify_locate.py（旧时代工具，见TODO③）

对话内诊断（主形态 · Agent 在聊天框里直接干）

这个 Skill 是给 Agent 用的，不是给人开网站的。 装好技能后，用户直接在对话里发一道错题，Agent 就跑诊断、在对话里给根因+验证题——不用起服务、不用开浏览器、不用贴图。

触发：用户发来错题文字 / 说「诊断这题」「为什么错」「根因是什么」「出个验证题」。

Agent 工作流（严格按此走）：

1. 判科目：从上下文或显式科目定（数学/英语/语文/物理/化学/生物/地理）。不确定就按题目内容推断，或追问一句。
2. 判概念：用你的 LLM 理解，判断这道题最可能是哪个知识点（例如 He like playing → 一般现在时第三人称单数；直径6cm圆用6×6×3.14算面积 → 圆的面积）。
3. 调 CLI（无需 flask，managed python 直接跑）： python engine/diagnose.py --subject <科目key或中文名> --text "<概念术语> <原题文字>" 把概念术语前置进 --text，让确定性定位层锁死节点（纯原题文字有时缺术语会漏，见诚实边界）。 例：python engine/diagnose.py --subject 英语 --text "一般现在时第三人称单数 He like playing football 漏掉动词加s"
4. 解析 JSON：ok / node_name / node_domain / roots[]。若 ok=false（没定位到），换更具体的概念术语重调一次（最多 2 次）。
5. 在对话里回复用户（同一气泡）：
   • 命中的知识点（node_name + 领域 node_domain）；
   • 根因链（roots，按可疑度排序，已剔除年级/册/章容器，只留真知识点）；
   • 基于最底层根因，用你（对话模型）直接出 1~2 道针对性验证题（不必调引擎里的模型）。

要点：根因 = 确定性逻辑（图谱 DAG 反推，稳定可复现，零模型依赖）；验证题 = 对话模型现出。出验证题不靠引擎，靠你。

可选：看图谱依赖关系（想可视化根因怎么一层层倒推时）才用 Web：python engine/product.py 起服务开浏览器——这是辅助，不是主形态。

可选：Web 可视化（看图谱依赖关系）

仅当用户明确想看图谱与根因的依赖结构时才用（辅助，非主形态）。需 flask 装在隔离 venv（使用 WorkBuddy 管理的 Python 环境）：PORT=6900 python product.py，浏览器开 http://localhost:6900。选科（数学/英语/语文/物理/化学/生物/地理，编程与剪辑不在成品内）→ 贴错题 → 点「诊断」出知识点+根因链（响应约 2 秒）。根因自动剔除年级/册/章容器。

When to use

• 用户发来一道错题 / 说「诊断这题」「为什么错」「根因是什么」→ 走对话内诊断工作流（上节）：调 engine/diagnose.py 拿根因，在对话里给根因链+验证题。这是主场景。
• 用户说"整数学/英语/语文/物理/…"→ 建或扩展对应科目图谱。
• 用户说"诊断定位偏了/根因不精准"→ 改 engine/app.py 的 locate_node 确定性分层，或拆复合节点为子技能。
• 用户说"加个科目"→ 复制 _cn_xxx_build.py 模板改内容，用 GRAPH_PATH 起独立实例。
• 改完图谱或 app.py 后必须重启服务（见 references/restart.md）。

Workflow

1. 建/扩展科目图谱（统一流水线，已验证可复用）

每科四步，产物三处同步：

1. _cn_xxx_build.py：结构化 RAW 定义（册容器 + 知识点 + 跨年级桥边/增强边），内置 pre 引用校验 + 增量环检测（would_cycle，判据=加边前查 topic 是否已能到达 pre，写反会误删共同地基边）→ 生成 graph.json（节点含 deg=被依赖数）。
2. gen_assets_xxx.py：从 graph.json 真源生成 HTML(含诊断模式) + xlsx + 验证报告。模板继承：事件委托点击 + Array.isArray(ev) 防御 + 动态 segs(由真实 grade 推算，跳过空学段) + 交付前 node --check 校验内联 JS。
3. _audit_xxx.py：独立硬审计（环/悬空/孤岛/evidence类型/册容器子节点/语义簇共享根祖先），与生成脚本解耦。
4. 三处同步 + MD5：源/skill/归档 graph.json 与 HTML 的 MD5 必须一致。

数学/英语/语文三科的图谱构建脚本曾为早期模板，其生成器缺点击加固；数据层已与后建科目对齐，审核统一用 review_all_3repo.py 覆盖。

2. 拆复合节点为细粒度子技能（提升根因精度）

当诊断把"分数加法"这类复合节点当根因、但真正薄弱在更细一层时：在 RAW 末尾加子技能节点，把原复合节点的粗粒度先修边改为指向各子技能，子技能再各自指回更底层概念。

3. 改定位逻辑（locate_node 确定性分层）— 七科已齐

engine/app.py 的 locate_node(text) 分层（越靠前越确定、越不依赖模型）： ① 精确双向命中（取最长节点名优先，避免"力"误中"摩擦力"）→ ①-extra 数学 _fraction_subnode(分数加减) / _ratio_node(比家族) → ①-extra 英语 _en_node → ①-extra 语文 _cn_node → ①-extra 物理 _phy_node / 化学 _chem_node / 生物 _bio_node / 地理 _geo_node → ② 语义标签 extract_tags + 确定性打分（7B 仅并列裁判）→ ③ 全量 7B 兜底。 各 _xx_node 按该科常见错误/考点关键词确定性命中，绕开不稳的 7B；由 IS_XX 网关（any(t["id"].startswith("前缀"))）按图谱前缀自动生效。 铁律：定位绝不能依赖 7B（见 references/locate_logic.md）。加新科目照 ①-extra 套路建 _xx_node + IS_XX 门控即可。 详细：references/locate_logic.md。

4. 接线多科目（GRAPH_PATH 环境变量）

config.py 支持 GRAPH_PATH 覆盖（默认指数学图谱）。起某科实例： GRAPH_PATH="../中国初中生物图谱/graph.json" PORT=6805 python app.py。 app.py 诊断逻辑无需改，只读 graph.json 的 topics/dependencies。

5. 校验 / 审查 / 修复（validate/ 工具）

典型流程：review.py 复验 → 发现问题 → fix_graphs.py 修数据层 → regen_and_sync.py 重算产物 → review_all_3repo.py 出三处一致报告。

6. 判卷闭环（零模型优先，不依赖大模型）

拍题 → 工具判对错 → 对了过 → 错了追根因出验证题 → 再拍判 → 循环。

• 零模型判卷：answer_match(standard, student) 归一化比对（数字整串 / 整串互含 / 英文单词级全包含）→ True/False/None。验证题由 gen_verify 出、自带标准答案，故判对错根本不调模型。
• /api/check：验证题作答判对错（优先 answer_match，比对不了才 grade_answer 走 LLM 兜底）。
• /api/deeper：验证题判错后，对该根因节点 diagnose(root_id) 下钻更基础验证题，闭环。
• 诚实边界：零模型判的是"我们出的验证题"（答案在手）；孩子拍的卷子原题无标准答案库，不强判原题对错，而是直接定位根因→出验证题测（测会了=根因补上）。要覆盖原题判错需建"常见题→标准答案"库（TODO）。
• 原理：学习机拍图判作业靠"题库+OCR+答案比对"，不是大模型推理。能确定性/规则/比对解决的，就不要上大模型。

7. 重启服务（仅 Web 可视化需要；对话内诊断不依赖服务，无需此步）

只有用户要开 product.py 看图谱可视化时才需起服务，务必按此规程，否则旧字节码/旧进程污染结果： 严格按 references/restart.md：① 停旧进程（taskkill 可能静默失败，要 netstat 复核端口只剩 1 个新 PID，最稳用 TaskStop）→ ② rm -rf __pycache__ → ③ 用 WorkBuddy 管理的 Python 环境起服务（flask 已装）。 曾因跳过清缓存导致"化简比 2:3"在线仍错定位成"比例尺"，清缓存重启后复测才正确。

Key facts / pitfalls

• 图谱 schema 必须与数学图谱一致，诊断引擎零改动即可复用（失败 99% 是字段名写错）。字段枚举见 references/schema.md。
• 诊断根因排序用「年龄窗口(目标-3岁) + 子图局部汇聚度 + 距目标近」，不能用全局被依赖数（否则所有题都指向加法/乘法）。
• 定位绝不能依赖 7B：本机 Ollama qwen2.5:7b llama-server 会中途崩溃（HTTP 500），所有依赖 7B 兜底定位的科目在 Ollama 宕机时整条链断。七科现已全部建确定性定位层，即使 7B 死也能定位+反推根因。OCR/出验证题/原题变形仍要 LLM，Ollama 宕机优雅降级为 ai_fail（定位+根因不受影响）。
• 判卷零模型优先（架构铁律）：验证题答案在手 → answer_match 直接比对；模型只做兜底。避开了本机 7B 弱且会崩的坑。
• 隔离 venv 路径：使用 WorkBuddy 管理的 Python 环境（flask 已装）。
• 三处同步铁律：源/skill/归档三份 graph.json 与 HTML 的 MD5 必须一致；改真源后必须重算产物并三处同步，否则会出现"线上用旧图"的幽灵问题。
• 重启前不清 __pycache__ = 旧逻辑/旧图谱继续生效（最隐蔽的坑）；taskkill 可能静默失败，务必 netstat 复核端口只剩 1 个 PID。

已知 TODO（交付前/收尾，非 blocker）

1. 根因列表含容器节点：diagnose 反推的"根因"偶尔带上年级/册容器节点（如"八年级下"），技术上正确但 pedagogically 无用。需在 diagnose 返回前过滤容器 id（CONTAINER_ID 规则见 validate/review.py）。
2. 小学数/英生成器未升级：早期模板无点击加固（事件委托/Array.isArray），重跑会回退交互；其 HTML 证据已内联正确（旧 gen 自带 str→数组 防御），仅数据层已修。若要彻底统一可升级这 2 个生成器。
3. 已移除子图目录留空：小学数/英/语和初中数/英/语 6 个子图目录已从技能包中移除（仅保留合并总图），子图源文件保留在开发机知识库中。
4. 答案卡整卷判卷（跨会话桥接，已设计未强制）：出卷会话把"答案卡" {"no","question","answer","node?"} 给本工具，家长拍卷面→extract_student(按题号切片OCR)+answer_match逐题零模型判→错题 locate_node/diagnose 出根因。/api/grade_card 为后端入口。

诚实边界（七科统一）

所有图谱均按教材目录手工拆解，覆盖全课标单元与核心知识点/考点，非学科专家逐册逐题审定。 物理/化学/生物/地理四科为初中单学段图（无小学版），无跨年级桥边、无合并三件套——已如实反映。 诊断精度上限 = 图谱拆解质量；图谱未覆盖的细分薄弱点，定位会退化到 ② 语义标签层或 ③ 7B 兜底。

对话内诊断的定位注意（重要）：各科 _xx_node 是关键词门控的确定性层，需要题目文字含概念术语（如「三单」「浮力」「圆的面积」）才锁死节点。家长发来的裸错题文字往往没有术语（如纯句子 He like playing football），直接调会 ok=false 或误命中。工作流 step 2/3 已规定：Agent 先用 LLM 判断出概念，把术语前置进 --text 再调一次即可精确命中（这也是「你判断根因」的体现）。数学「圆面积」类裸文本偶尔会被「乘法符号」权重拉偏误命中「小数乘法」，同样靠前置「圆的面积」术语纠正。