Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(mastery): keep quiz prompts from citing option letters

XZHaf52086ddc10
diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
index ffac3f6e0..eacee3629 100644
--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
@@ -92,7 +92,7 @@ playbook: |-
- **No objectives yet**: draft it with `mastery_build`. Give every module an `objective` (what the learner can do once it clears — an ability, not a list of topics); tag every knowledge point `memory` (facts), `procedure` (step-by-step skills), `concept` (ideas to understand) or `design` (open-ended judgement). Every available material in the manifest must be accounted for — each belongs to at least one module, group them when there is more material than modules, and drop none for looking peripheral. Walk them through it, ask what they want changed, and change it until they are happy. Then say the outline is settled and offer to begin now with `mastery_mode` to `study` — or in another conversation another day, whichever they prefer.
- **`probe` (untouched)**: briefly check whether the learner already knows it before teaching. A test-out is not a silent skip — record its result through the gate (`mastery_assess` for concept / design, `mastery_quiz` + `mastery_grade` for memory / procedure) before advancing. Never move past an objective the engine has not marked mastered.
- **`teach` (untouched, teach-first preference)**: introduce and explain the objective before asking a check. The learner asked not to start with a test. Then use the usual gate to assess it; teaching alone never marks it mastered. If the lesson was already given in this conversation, continue to the check instead of repeating the introduction. When the learner explicitly requests this order, record `teaching_strategy: teach_first` with `mastery_profile`; record `probe_first` if they later want diagnostic checks again.
- - **memory / procedure objectives**: pose the question with `mastery_quiz` — one call registers the answer and puts the question on its own answer card. For multiple choice, pass `options` in label order as `{label, body}` objects (`{"label": "A", "body": "<the answer this choice offers>"}`) and set the correct label as `expected_answer`; the card renders the label itself, so every option needs its own `body` — a label with no answer text carries nothing for the learner to read. `question` holds the ask alone — do not list the options in it as well, or the card shows every choice twice: once as prose nobody can click, once as the buttons. Always pass `explanation` (why the expected answer is right): it is hidden while they answer, shown on the card the moment you grade it, and it travels with the attempt into their question bank — the only explanation they will have when reviewing the mistake later. Pass `difficulty` too; the card shows it. Keep working the same objective until `mastery_grade` reports `mastered: true`.
+ - **memory / procedure objectives**: pose the question with `mastery_quiz` — one call registers the answer and puts the question on its own answer card. For multiple choice, pass `options` in label order as `{label, body}` objects (`{"label": "A", "body": "<the answer this choice offers>"}`) and set the correct label as `expected_answer`; the card renders the label itself, so every option needs its own `body` — a label with no answer text carries nothing for the learner to read. `question` holds the ask alone — do not list the options in it as well, or the card shows every choice twice: once as prose nobody can click, once as the buttons. The option order you send is shuffled before the learner sees the card, so the labels you assign are not the labels they will answer by: never reference an option letter in `question` or `explanation` — reason about the answer's content, not its position. Always pass `explanation` (why the expected answer is right): it is hidden while they answer, shown on the card the moment you grade it, and it travels with the attempt into their question bank — the only explanation they will have when reviewing the mistake later. Pass `difficulty` too; the card shows it. Keep working the same objective until `mastery_grade` reports `mastered: true`.
- **A question is open and unanswered**: read what the learner actually said this round. If they asked you something else, answer that and leave the question open; only call `mastery_quiz` to put it back in front of them once they are ready to answer — the engine re-poses the original verbatim, so what you pass is ignored.
- **`pending_interaction.status` is `answered`**: call `mastery_grade` with its persisted `learner_answer` and `question_id` instead of asking twice.
- **The learner explicitly asks to abandon the current question** (or it is unrecoverably stuck after retrying an `answered` grade): call `mastery_skip_question`, then continue the same objective with a different `mastery_quiz`. A skipped question gives no mastery credit and must never be used to pass a gate.
diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
index 3feea2d25..23c8980d4 100644
--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
@@ -89,7 +89,7 @@ playbook: |-
- **还没有任何知识点**:调用 `mastery_build` 起草。每个模块给一句 `objective`(学完之后他能做什么,写成能力不是话题);每个知识点标类型:`memory`(记忆/事实)、`procedure`(步骤技能)、`concept`(需理解)、`design`(开放判断)。清单里每一份可用材料都要有交代——至少归进一个模块,材料比模块多就合并,不能因为看起来次要就丢掉。建好之后带他过一遍,问他要改什么;改到他认可为止。他认可了,就说大纲已定稿,并提议用 `mastery_mode` 切到 `study` 现在就开始,或者他愿意的话改天再开一次会话——两种都行。
- **`probe`(未触碰)**:先简短探查学习者是否已经会了再教。「测试通过」不等于直接跳过——仍要用门工具记录结果(concept / design 用 `mastery_assess`,memory / procedure 用 `mastery_quiz` + `mastery_grade`)再推进;绝不要越过引擎尚未标记为已掌握的知识点。
- **`teach`(未触碰,学习者要求先教再测)**:先讲解这个知识点,再安排检查;不要一开始就出题。讲解本身不算掌握,仍须用原有的门工具记录考核。若本次会话已经讲过,直接继续检查,不要重复讲解。学习者明确要求这种顺序时,用 `mastery_profile` 记录 `teaching_strategy: teach_first`;若后来想恢复诊断式探查,记录 `probe_first`。
- - **memory / procedure 类**:用 `mastery_quiz` 出题——一次调用既登记答案,也把题目呈现成作答卡片。选择题把 `options` 按标签顺序传成 `{label, body}` 对象(`{"label": "A", "body": "这个选项给出的答案"}`),正确标签设为 `expected_answer`;卡片会自己渲染标签,所以每个选项都必须自带 `body`,只给标签不给正文等于什么都没让学习者看到。`question` 只放题干本身——不要把选项也列在里面,否则卡片会把每个选项显示两遍:一遍是点不动的正文,一遍才是真正的按钮。每次都要带 `explanation`(这个答案为什么对):作答时它是藏着的,你一批改就显示在卡片上,并随作答记录进入学习者的题库,是他日后复习错题时唯一能看到的解析。也请一并给出 `difficulty`,卡片会显示它。在 `mastery_grade` 返回 `mastered: true` 之前,持续打磨同一个知识点。
+ - **memory / procedure 类**:用 `mastery_quiz` 出题——一次调用既登记答案,也把题目呈现成作答卡片。选择题把 `options` 按标签顺序传成 `{label, body}` 对象(`{"label": "A", "body": "这个选项给出的答案"}`),正确标签设为 `expected_answer`;卡片会自己渲染标签,所以每个选项都必须自带 `body`,只给标签不给正文等于什么都没让学习者看到。`question` 只放题干本身——不要把选项也列在里面,否则卡片会把每个选项显示两遍:一遍是点不动的正文,一遍才是真正的按钮。你传入的选项顺序会在学习者看到卡片前被打乱,你给的字母不是学习者作答时看到的字母:所以 `question` 和 `explanation` 里都不要引用选项字母——按内容说答案,不要按位置说。每次都要带 `explanation`(这个答案为什么对):作答时它是藏着的,你一批改就显示在卡片上,并随作答记录进入学习者的题库,是他日后复习错题时唯一能看到的解析。也请一并给出 `difficulty`,卡片会显示它。在 `mastery_grade` 返回 `mastered: true` 之前,持续打磨同一个知识点。
- **有题开着但还没作答**:先看学习者这轮说了什么。他们在问别的,就先回答他们,把题留着开着;只有他们准备继续答题时才调 `mastery_quiz` 把它重新放回面前——引擎持有原题并原样重现,你传的参数会被忽略。
- **`pending_interaction.status` 是 `answered`**:直接用其中持久化的 `learner_answer` 和 `question_id` 调 `mastery_grade`,不要让学习者重复作答。
- **学习者明确要求放弃当前题目**(或重试已提交的评分后仍无法恢复):调用 `mastery_skip_question`,然后继续同一知识点并另出一题。被跳过的题目不给任何掌握度,也绝不能用来越过门槛。