Skip to content

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

fix(mastery): resume pending cards and guard Markdown assessments

yepyhun6532c8c2a708
diff --git a/.github/tdd/mastery-group-delivery-resume.md b/.github/tdd/mastery-group-delivery-resume.md
new file mode 100644
index 000000000..6dde080cb
--- /dev/null
+++ b/.github/tdd/mastery-group-delivery-resume.md
@@ -0,0 +1,50 @@
+# Grouped-card delivery and exact pending-card resume
+
+## Reproduction
+
+The finish guard recognized `1. A question?` but allowed `### 1. Topic`
+followed by a question in the next paragraph. A reply could solicit several
+answers without calling mastery_quiz. Existing pending cards also lacked a
+direct re-presentation action, encouraging reconstruction in prose.
+
+Tests use generic synthetic topics and isolated stores. No private learner
+transcript, external provider inference or live learning-state edit is included.
+
+## RED / GREEN
+
+RED checkpoint 7e16a93a: 10 intended failures, 11 passes on the clean contribution.
+The root integration additionally reproduced the original captured shape before
+the fix, without exporting its content.
+
+GREEN on the clean contribution: 131 focused tests in 18.53s (21 delivery,
+31 grouped interaction, 79 existing capability neighbors). Separate root
+source-integrated scope: 137 passed in 25.89s. Counts overlap and are not
+coverage percentages or a global-suite assertion.
+
+One actual MessageList DOM test passed in clean and root worktrees: resumed
+card and cumulative partial-grade receipt in one new message restore the saved
+answer/graded lock with older history absent, keep the remaining item editable,
+submit only that item and filter private extra fields. Existing frontend
+behavior is reused; no new production UI surface is added.
+
+## Invariants and review
+
+- Exact current parent ID and eligible status are checked inside register_question.
+- Historical/stale/answered/terminal IDs and fresh-contract/resume conflicts reject.
+- Existing replies, results, question identity and credit are preserved.
+- Committed but ungraded answers require grading first; no invented UI verdict.
+- Stored partial results replay through a public-field allowlist, not private keys.
+- Explicit assessment intent plus multiple question-bearing numbered blocks
+ triggers correction; ordinary explanations and quoted/code examples do not.
+- The same existing card builder, delivery callback and tool metadata are used.
+
+Independent state/security review found no blocking issue. The separate local
+preparation bridge validates remaining saved source snapshots; that bridge is
+not copied into this native contribution.
+
+## Limits
+
+The textual guard is defense in depth, not universal semantic intent detection.
+This fixes registered delivery/resumption, not question selection from a requested
+reference bank, semantic answer grading, or all model teaching decisions.
+No live-model benchmark, full coverage or billing-savings claim is made.
diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.py
index ade10fb2c..5d3c8c984 100644
--- a/deeptutor/capabilities/mastery/loop.py
+++ b/deeptutor/capabilities/mastery/loop.py
@@ -60,7 +60,7 @@ _MULTIPART_INTENT_RE = re.compile(
re.IGNORECASE,
)
_NUMBERED_QUESTION_RE = re.compile(
- r"^\s*(?:\*\*)?\d{1,2}[.)、](?:\*\*)?\s+[^\n]*[??]", re.MULTILINE
+ r"^\s*(?:#{1,6}\s+)?(?:\*\*)?\d{1,2}[.)、](?:\*\*)?\s+", re.MULTILINE
)
# A reply that announces a question without posing one. Matched against the
# tail of the reply only, where an announcement lands, so ordinary discussion
@@ -161,9 +161,18 @@ def _looks_like_plain_choice_quiz(text: str) -> bool:
def _looks_like_multipart_assessment(text: str) -> bool:
prose = _QUOTED_CARD_TEXT_RE.sub(" ", text)
- return (
- bool(_MULTIPART_INTENT_RE.search(prose)) and len(_NUMBERED_QUESTION_RE.findall(prose)) >= 2
- )
+ if not _MULTIPART_INTENT_RE.search(prose):
+ return False
+ # Markdown frequently puts the title on the numbered line and the actual
+ # question in the following paragraph. Count question-bearing blocks, not
+ # only same-line stems; quoted/code examples were removed above.
+ starts = list(_NUMBERED_QUESTION_RE.finditer(prose))
+ questions = 0
+ for index, start in enumerate(starts):
+ end = starts[index + 1].start() if index + 1 < len(starts) else len(prose)
+ if re.search(r"[??]", prose[start.end():end]):
+ questions += 1
+ return questions >= 2
def _turn_has_graded(context: UnifiedContext) -> bool:
@@ -385,10 +394,12 @@ class MasteryLoopCapability:
)
if not state.get("card_posted") and _looks_like_multipart_assessment(final_text):
return (
- "That reply presented a new numbered assessment as unregistered prose. "
+ "That reply presented a numbered assessment as unregistered prose. "
"For memory/procedure practice, call mastery_quiz with a questions group "
"so each answer has its own stored contract and result. If an older question "
- "is pending, preserve it unless the learner explicitly requested replacement; "
+ "is pending and you want to show it again, call mastery_quiz with "
+ "pending_action='resume' and its exact parent resume_question_id, without "
+ "new questions or answer keys. Preserve it unless the learner explicitly requested replacement; "
"then use its current question ID and a literal replacement_request quote. "
"Do not concatenate expected answers or claim that a prose list is a card. "
"If this is teaching rather than assessment, explain directly without "
diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
index dbefca5df..29a551c78 100644
--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
@@ -87,7 +87,7 @@ session:
# how a round runs, this one says what to do about the objective in front of you.
playbook: |-
**Incremental group replies:** A learner may answer only some children. Pass those real answers to `mastery_grade`, preserve unanswered siblings, and read `complete` / `remaining_question_ids` before claiming the whole group is finished. Do not ask for already graded answers again.
- **Registered grouped practice:** When the learner requests questions together, use `mastery_quiz.questions` for a bounded group of two to four separately answerable memory/procedure questions. Each item must name a real objective and carry its own supported question and private answer contract; do not concatenate expected answers or pose official numbered assessments in prose. A group is one active interaction with separate results, not extra mastery credit. If an unrelated older question is still pending, explain that briefly. Replace it only for an explicit current learner request, using `pending_action: replace`, the fresh `replace_question_id`, and `replacement_request` as a literal quote from that request. Otherwise retain it. Never infer abandonment from silence or a pacing preference. Do not call the single-question tool twice and promise two cards. Unsupported objective types still use their native qualitative assessment path.
+ **Registered grouped practice:** When the learner requests questions together, use `mastery_quiz.questions` for a bounded group of two to four separately answerable memory/procedure questions. Each item must name a real objective and carry its own supported question and private answer contract; do not concatenate expected answers or pose official numbered assessments in prose. A group is one active interaction with separate results, not extra mastery credit. If an unrelated older question is still pending, explain that briefly. Replace it only for an explicit current learner request, using `pending_action: replace`, the fresh `replace_question_id`, and `replacement_request` as a literal quote from that request. Otherwise retain it. Never infer abandonment from silence or a pacing preference. Do not call the single-question tool twice and promise two cards. Unsupported objective types still use their native qualitative assessment path. When an existing registered card should be shown again, call mastery_quiz with pending_action: resume and its exact current parent resume_question_id, omitting new-question and replacement arguments. This re-presents the stored card; it does not replace it or award credit. Do not reconstruct pending questions as a prose list.
**Concise but explanatory:** Do not replace teaching with a list of names, priority labels or compressed definitions. At the learner's requested level, explain the necessary meaning and one useful connection or concrete example before assessing it. After feedback that an explanation was too terse, supply the missing link rather than another equally compressed formulation. Split useful teaching into connected steps when needed; there is no fixed word quota or compulsory question after each step.
**Source-grounded visual study:** Honor explanation, practice and review as explicit learner choices; explain untaught prerequisites at the requested level before assessment. Use `mastery_note_explained` after an explanation; this records coverage without mastery credit. An outline is never evidence of teaching. A concise explanation-only turn may end without a quiz; explicit deferral uses `mastery_defer_objective` and does not claim mastery.
When the goal includes figure understanding, declare the relevant objective's `required_visual_tasks` in the outline (`identification`, `relationship`, `table_graph`, `comparison`). Generic text scores do not satisfy these. Read `mastery_status.visual_requirements` and `learning_stages`; explain whether the next work addresses missing independent evidence, prior difficulty or due review.
diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
index b7995cd03..8a8e168a2 100644
--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
@@ -84,7 +84,7 @@ session:
# 教学策略。与 loop 协议分开:上面说的是「一轮怎么走」,这里说的是「针对这个知识点做什么」。
playbook: |-
**分次回答组合题:** 学习者可以只回答部分子题。把这些实际回答传给 `mastery_grade`,保留尚未回答的子题,并在宣称整组已完成前检查 `complete` / `remaining_question_ids`。不要重复索取已经评分的回答。
- **已登记的组合练习**:学习者要求一起回答问题时,用 `mastery_quiz.questions` 建立二至四题的有界组合;每题独立作答,只用于 memory/procedure 知识点。每题必须指向真实知识点并保存自己的、有来源支持的题目与私密答案契约;不能把答案拼接后一起模糊判分,也不能把正式编号考核写在正文里。组合只有一个活跃交互,但结果分别归属各题,不额外授予掌握分。若仍有不相关的旧待答题,简短说明;只有学习者当前明确要求替换时,才用 `pending_action: replace`、最新 `replace_question_id` 和当前请求的逐字引用 `replacement_request` 替换,否则保留。沉默或节奏偏好不是放弃旧题的证据。不要连续调用单题工具后承诺两张卡片;不支持的知识点类型仍走原有定性考核流程。
+ **已登记的组合练习**:学习者要求一起回答问题时,用 `mastery_quiz.questions` 建立二至四题的有界组合;每题独立作答,只用于 memory/procedure 知识点。每题必须指向真实知识点并保存自己的、有来源支持的题目与私密答案契约;不能把答案拼接后一起模糊判分,也不能把正式编号考核写在正文里。组合只有一个活跃交互,但结果分别归属各题,不额外授予掌握分。若仍有不相关的旧待答题,简短说明;只有学习者当前明确要求替换时,才用 `pending_action: replace`、最新 `replace_question_id` 和当前请求的逐字引用 `replacement_request` 替换,否则保留。沉默或节奏偏好不是放弃旧题的证据。不要连续调用单题工具后承诺两张卡片;不支持的知识点类型仍走原有定性考核流程。 需要再次展示已有登记题卡时,调用 mastery_quiz,只传 pending_action: resume 和最新父题 resume_question_id,不传新题契约或替换参数;这只重新展示存储题卡,不替换它也不授予掌握分。不要把待答题重新写成纯文本列表。
**简洁但讲清楚**:不要用名称列表、重要性标签或压缩定义代替教学。按学习者需要的深度,先讲必要的含义以及一个有用联系或具体例子,再考核。学习者说解释太简略时,补上缺失的联系,不要换成同样简略的说法。需要时把教学拆成连贯小步;没有固定字数配额,也不要求每一步之后都出题。
**来源扎实的视觉学习:** 尊重学习者明确选择的讲解、练习或复习,按要求的层次先解释必要前置知识。讲解后调用 `mastery_note_explained`,只记录已讲解覆盖,不授予掌握分;生成提纲不等于教学。仅需简洁讲解时可以不出题;明确暂缓用 `mastery_defer_objective`,不能假称已掌握。
目标包含原图理解时,在对应提纲目标声明 `required_visual_tasks`(identification、relationship、table_graph、comparison)。通用文字题高分不能替代这些任务。查看 `mastery_status.visual_requirements` 和 `learning_stages`,解释下一步来自缺少独立证据、此前困难还是到期复习。
diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.py
index 654ea4c3f..9b78d9963 100644
--- a/deeptutor/capabilities/mastery/tools.py
+++ b/deeptutor/capabilities/mastery/tools.py
@@ -1027,7 +1027,9 @@ class MasteryQuizTool(BaseTool):
definition.description += (
" For several separately graded questions use questions (two to four single-question "
"objects) in ONE call, not prose or repeated calls. One parent ends the turn. "
- "A pending item is retained unless the learner explicitly requests replacement."
+ "A pending item is retained unless the learner explicitly requests replacement. "
+ "To show the CURRENT pending card again, use pending_action='resume' and "
+ "its exact parent resume_question_id only; do not regenerate questions or keys."
)
definition.parameters.extend(
[
@@ -1048,8 +1050,14 @@ class MasteryQuizTool(BaseTool):
name="pending_action",
type="string",
required=False,
- enum=["retain", "replace"],
- description="Retain existing pending question by default; replace only on an explicit learner request.",
+ enum=["retain", "replace", "resume"],
+ description="Retain by default; replace only on an explicit learner request; resume re-presents the exact existing card without a new contract.",
+ ),
+ ToolParameter(
+ name="resume_question_id",
+ type="string",
+ required=False,
+ description="Exact CURRENT pending parent question_id from mastery_status, only with pending_action='resume'. Omit all new-question and replacement parameters.",
),
ToolParameter(
name="replace_question_id",
@@ -1079,6 +1087,22 @@ class MasteryQuizTool(BaseTool):
if progress is None:
return _no_built_path_result("mastery_quiz")
pending_action = kwargs.get("pending_action", "retain")
+ resume_id = kwargs.get("resume_question_id")
+ if pending_action == "resume":
+ contract_fields = {
+ "knowledge_point_id", "question", "expected_answer", "question_type", "options",
+ "explanation", "difficulty", "visual", "questions", "replace_question_id", "replacement_request",
+ }
+ if (
+ not isinstance(resume_id, str) or not resume_id.strip()
+ or any(kwargs.get(field) is not None for field in contract_fields)
+ ):
+ return ToolResult(
+ content="Resume needs only pending_action='resume' and the exact pending parent resume_question_id; omit new-question and replacement arguments.",
+ success=False,
+ )
+ elif resume_id is not None:
+ return ToolResult(content="resume_question_id requires pending_action='resume'.", success=False)
if pending_action == "replace":
request = kwargs.get("replacement_request")
learner_message = kwargs.get("_learner_message")
@@ -1093,7 +1117,9 @@ class MasteryQuizTool(BaseTool):
success=False,
)
raw_questions = kwargs.get("questions")
- if raw_questions is None:
+ if pending_action == "resume":
+ pending, echoed_options = None, False
+ elif raw_questions is None:
built = await self._build_question(kwargs, progress)
if isinstance(built, ToolResult):
return built
@@ -1154,16 +1180,18 @@ class MasteryQuizTool(BaseTool):
pending,
pending_action=pending_action,
replace_question_id=str(kwargs.get("replace_question_id") or ""),
+ resume_question_id=str(resume_id or ""),
session_id=_resolve_session_id(kwargs),
turn_id=_resolve_turn_id(kwargs),
)
except MasteryInteractionError as exc:
return ToolResult(content=str(exc), success=False)
pending = interaction.question
+ kp, _, _ = find_knowledge_point(progress, pending.knowledge_point_id)
public_question = public_pending_question(pending)
card = build_question_card(
pending,
- objective_name=kp.name if not pending.questions else "",
+ objective_name=kp.name if kp is not None and not pending.questions else "",
attempt=attempt_number(progress, pending.knowledge_point_id),
)
if pending.questions:
@@ -1225,7 +1253,7 @@ class MasteryQuizTool(BaseTool):
"button. That list was removed from the stem. Pass the ask in "
"'question' and the choices only in 'options'."
)
- if not pending.questions and kp.type in QUALITATIVE_TYPES:
+ if not pending.questions and kp is not None and kp.type in QUALITATIVE_TYPES:
# The mirror of ``record_qualitative_for_path``, which refuses
# outright when mastery_assess is aimed at a quantitative
# objective. This direction stays allowed — a question is a fair
@@ -1240,10 +1268,34 @@ class MasteryQuizTool(BaseTool):
"their own words and record that with mastery_assess."
)
- return ToolResult(
- content=notice,
- metadata={"mastery_quiz": payload, QUESTION_CARD_KEY: card},
- )
+ metadata = {"mastery_quiz": payload, QUESTION_CARD_KEY: card}
+ if pending_action == "resume" and pending.questions and interaction.result.get("results"):
+ # The original grade message may be outside the current history
+ # page. Reuse its public cumulative receipt to restore leaf locks;
+ # this is a replay, never another grading call or mastery credit.
+ result = {
+ key: interaction.result[key] for key in (
+ "question_id", "question_type", "complete", "remaining_question_ids",
+ "is_correct", "result",
+ ) if key in interaction.result
+ }
+ leaf_fields = {
+ "question_id", "knowledge_point_id", "is_correct", "learner_answer",
+ "correct_label", "correct_body", "explanation", "result", "independent", "diagnosis",
+ }
+ result["results"] = [
+ {key: value for key, value in leaf.items() if key in leaf_fields}
+ for leaf in interaction.result["results"]
+ ]
+ metadata["mastery_grade"] = {
+ "question_id": pending.question_id,
+ "question_type": "group",
+ "complete": False,
+ "remaining_question_ids": interaction.result.get("remaining_question_ids", []),
+ "replayed": True,
+ "result": result,
+ }
+ return ToolResult(content=notice, metadata=metadata)
async def _build_question(self, kwargs, progress):
kp_id = str(kwargs.get("knowledge_point_id") or "").strip()
diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.py
index e15c5b1a6..98e7c4cb9 100644
--- a/deeptutor/learning/service.py
+++ b/deeptutor/learning/service.py
@@ -654,10 +654,11 @@ class LearningService:
def register_question(
self,
book_id: str,
- pending: PendingQuestion,
+ pending: PendingQuestion | None,
*,
pending_action: str = "retain",
replace_question_id: str = "",
+ resume_question_id: str = "",
session_id: str = "",
turn_id: str = "",
) -> tuple[LearningProgress, MasteryInteraction, bool]:
@@ -667,8 +668,13 @@ class LearningService:
existing interaction instead of overwriting its expected answer.
"""
- if pending_action not in {"retain", "replace"}:
- raise MasteryInteractionError("pending_action must be retain or replace")
+ if pending_action not in {"retain", "replace", "resume"}:
+ raise MasteryInteractionError("pending_action must be retain, replace or resume")
+ if pending_action == "resume":
+ if pending is not None or replace_question_id or not resume_question_id:
+ raise MasteryInteractionError("Resume needs only the exact pending parent question_id")
+ elif pending is None or resume_question_id:
+ raise MasteryInteractionError("A new question contract cannot include resume_question_id")
def register(tx):
active = tx.active_interaction()
@@ -691,6 +697,28 @@ class LearningService:
active = persisted
else:
tx.put_interaction(active)
+ if pending_action == "resume":
+ if active is None or active.interaction_id != resume_question_id:
+ raise StaleInteractionError(
+ resume_question_id, active.interaction_id if active else ""
+ )
+ if active.status not in {
+ InteractionStatus.REGISTERED, InteractionStatus.AWAITING_INPUT,
+ }:
+ raise MasteryInteractionError("This question is no longer awaiting input; refresh mastery_status")
+
+ graded_ids = {
+ result["question_id"] for result in (active.result or {}).get("results", [])
+ }
+ if set(active.answers) - graded_ids:
+ raise MasteryInteractionError(
+ "Grade the committed answers before re-presenting the remaining card"
+ )
+ known_ids = {kp.id for module in tx.progress.modules for kp in module.knowledge_points}
+ for question in active.question.questions or [active.question]:
+ if question.question_id not in graded_ids and question.knowledge_point_id not in known_ids:
+ raise MasteryInteractionError("The pending objective changed; refresh mastery_status")
+ return active, False
if active is not None and pending_action == "retain":
if bool(pending.questions) != bool(active.question.questions):
raise MasteryInteractionError(
diff --git a/web/tests/mastery-question-group.spec.tsx b/web/tests/mastery-question-group.spec.tsx
index d965e1d4d..60be34a8b 100644
--- a/web/tests/mastery-question-group.spec.tsx
+++ b/web/tests/mastery-question-group.spec.tsx
@@ -113,6 +113,45 @@ describe("grouped mastery assessment", () => {
answers: [{ questionId: "part-b", text: "Remaining answer" }] });
});
+ it("restores a resumed partial group from the receipt in its own message without older history", async () => {
+ const user = userEvent.setup();
+ const onAnswer = vi.fn(() => true);
+ const resumedEvent = event({
+ mastery_quiz: { status: "resumed", question_id: "group-1" },
+ mastery_question: {
+ ...group,
+ questions: group.questions.map((part) => ({ ...part, expected_answer: "PRIVATE_QUESTION_KEY" })),
+ },
+ mastery_grade: { question_id: "group-1", complete: false, replayed: true,
+ remaining_question_ids: ["part-b"], result: {
+ question_id: "group-1", question_type: "group", is_correct: null, complete: false,
+ remaining_question_ids: ["part-b"], results: [
+ { question_id: "part-a", is_correct: true, learner_answer: "A", correct_label: "A",
+ explanation: "First part already confirmed.", expected_answer: "PRIVATE_GRADE_KEY" },
+ ],
+ } },
+ });
+ // The re-presentation is the only loaded message: the original question
+ // and earlier grade are intentionally absent from this history page.
+ const messages = [{ id: 20, role: "assistant" as const, content: "", parentMessageId: null,
+ capability: "mastery_path", events: [resumedEvent] }];
+ const restored = collectMasteryGrades(messages);
+ expect(restored.get("part-a")?.learnerAnswer).toBe("A");
+ expect(restored.get("group-1")?.complete).toBe(false);
+ expect(JSON.stringify([...restored.values()])).not.toContain("PRIVATE_");
+ render(<ChatMessageList messages={messages} isStreaming={false}
+ onCopyAssistantMessage={async () => undefined} onRegenerateMessage={() => undefined}
+ onAnswerMasteryQuestion={onAnswer} />);
+ expect(screen.getByRole("button", { name: /Matching description/ })).toBeDisabled();
+ expect(screen.getByText("First part already confirmed.")).toBeInTheDocument();
+ expect(screen.getByRole("textbox")).toBeEnabled();
+ expect(document.body.textContent).not.toContain("PRIVATE_");
+ await user.type(screen.getByRole("textbox"), "Answer after resuming");
+ await user.click(screen.getByRole("button", { name: "Submit" }));
+ expect(onAnswer).toHaveBeenCalledExactlyOnceWith({ questionId: "group-1", text: "2. Answer after resuming",
+ answers: [{ questionId: "part-b", text: "Answer after resuming" }] });
+ });
+
it("releases the sending latch on partial acknowledgement and preserves unsent edits", async () => {
const user = userEvent.setup();
const onSubmit = vi.fn<(payload: UserReplyPayload) => boolean>(() => true);