DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(mastery): 阻止历史回忆递归归档膨胀
AleFlyX8f9fb42b6bc0
diff --git a/deeptutor/capabilities/mastery/history.py b/deeptutor/capabilities/mastery/history.pyindex 2407871e6..54a9fea9f 100644--- a/deeptutor/capabilities/mastery/history.py+++ b/deeptutor/capabilities/mastery/history.py@@ -1,7 +1,8 @@"""Lossless sharing of repeated mastery state inside one model request.This is a request projection, not session compaction. Raw history stays intact.-Only known state fields are eligible; dialogue and source/tool evidence are not.+Known state fields can be shared; prior exact-history reads become recall+references so an archive never embeds another archive's body."""from __future__ import annotations@@ -53,10 +54,71 @@ def project_mastery_replay(messages: list[dict[str, Any]]) -> list[dict[str, Anyif not (m.get("role") == "user" and (isinstance(m.get("_context_snapshot"), str)))])+ reference_history_reads(projected)share_mastery_history(projected, len(projected))return projected+def reference_history_reads(messages: list[dict[str, Any]]) -> None:+ """Replace recalled archive bodies in an owned historical copy, not storage.++ Resolve each result against its preceding call batch: providers may reuse+ call IDs in later turns. Never inspect or recursively decode the recalled+ body when the call already identifies the archive.+ """+ sources: dict[str, str] = {}+ for message in messages:+ if message.get("role") == "assistant":+ sources = {}+ calls = message.get("tool_calls") or []+ counts = Counter(call.get("id") for call in calls)+ for call in calls:+ function = call.get("function", {})+ if (+ function.get("name") not in {"read_source", "pdf"}+ or counts[call.get("id")] != 1+ ):+ continue+ try:+ args = json.loads(function.get("arguments", "{}"))+ except (ValueError, TypeError):+ continue+ source_id = args.get("source_id") if isinstance(args, dict) else None+ if isinstance(args, dict) and not source_id:+ sources[call["id"]] = ""+ elif isinstance(source_id, str) and source_id.strip().startswith("hs-tutor-"):+ sources[call["id"]] = source_id.strip()+ elif message.get("role") == "tool":+ source_id = sources.pop(message.get("tool_call_id"), None)+ content = message.get("content")+ if source_id == "" and isinstance(content, str):+ # The reader may infer the only source when its ID was omitted.+ # Our archive/page envelope puts the ID first. Decode just that+ # small header, never the potentially multi-megabyte JSON body.+ prefix = '{"archive_id":'+ if content.startswith(prefix):+ try:+ inferred, _ = json.JSONDecoder().raw_decode(+ content[len(prefix) : 256].lstrip()+ )+ if isinstance(inferred, str) and inferred.startswith("hs-tutor-"):+ source_id = inferred+ except ValueError:+ pass+ if source_id and isinstance(content, str) and not content.startswith("Error:"):+ message["content"] = json.dumps(+ {+ "archive_id": source_id,+ "note": "Previously recalled tutoring history. Use read_source with this "+ "archive_id as source_id to inspect the original exchange again.",+ },+ ensure_ascii=False,+ separators=(",", ":"),+ )+ else:+ sources = {}++def share_mastery_history(messages: list[dict[str, Any]], history_end: int) -> None:"""Share exact repeated state in the owned historical request copy in-place.diff --git a/deeptutor/capabilities/mastery/memory.py b/deeptutor/capabilities/mastery/memory.pyindex bf7c9bddd..886af2835 100644--- a/deeptutor/capabilities/mastery/memory.py+++ b/deeptutor/capabilities/mastery/memory.py@@ -9,7 +9,11 @@ from __future__ import annotationsimport jsonfrom typing import Any-from deeptutor.capabilities.mastery.history import STATE_REFERENCE_NOTICE, project_mastery_replay+from deeptutor.capabilities.mastery.history import (+ STATE_REFERENCE_NOTICE,+ project_mastery_replay,+ reference_history_reads,+)from deeptutor.services.llm.image_replay import deduplicate_user_imagesfrom deeptutor.services.llm.types import StreamOutcomefrom deeptutor.services.prompt.language import language_label@@ -35,7 +39,9 @@ MEMORY_NOTICE = ("answer, explanation or preference is unclear, use read_source with its archive ID ""to recover that original exchange. Do not invent remembered details or assume ""understanding just because a topic was explained. Recall only relevant exchanges, "- "not the entire archive on every turn."+ "not the entire archive on every turn. Previously recalled archive bodies are "+ "represented by archive_id references, not copied into later exchanges. "+ "Large archive reads are paginated; use the returned next_offset when needed.")@@ -57,13 +63,15 @@ def archive_text(group: list[dict[str, Any]]) -> str:return [text_part(v) for v in value]return value+ replayed = replay_group(group)+ reference_history_reads(replayed)messages = [{k: text_part(v)for k, v in message.items()if k in {"role", "content", "tool_calls", "tool_call_id", "name"}}- for message in replay_group(group)+ for message in replayedif not (message.get("role") == "user" and (message.get("_context_snapshot")))]return json.dumps(diff --git a/deeptutor/tools/builtin/__init__.py b/deeptutor/tools/builtin/__init__.pyindex a3e51eff7..d5a1c7b0d 100644--- a/deeptutor/tools/builtin/__init__.py+++ b/deeptutor/tools/builtin/__init__.py@@ -1067,6 +1067,8 @@ class ReadSourceTool(_PromptHintsMixin, BaseTool):``_augment_tool_kwargs``. The tool itself stays stateless."""+ HISTORY_PAGE_CHARS = 16_000+def get_definition(self) -> ToolDefinition:return ToolDefinition(name="read_source",@@ -1075,7 +1077,8 @@ class ReadSourceTool(_PromptHintsMixin, BaseTool):"the preview shown in the Attached Sources manifest is ""insufficient to answer the user's question. The id must be ""copied verbatim from the manifest — do not invent ids. Do not "- "call this on every source 'just in case'."+ "call this on every source 'just in case'. Tutoring history "+ "(hs-tutor-*) is paginated; use next_offset to read the next page."),parameters=[ToolParameter(@@ -1088,6 +1091,14 @@ class ReadSourceTool(_PromptHintsMixin, BaseTool):"session), qb- (question-bank entry), at- (document attachment)."),),+ ToolParameter(+ name="offset",+ type="integer",+ description="Character offset for an hs-tutor-* history page; starts at 0.",+ required=False,+ default=0,+ minimum=0,+ ),],)@@ -1117,9 +1128,32 @@ class ReadSourceTool(_PromptHintsMixin, BaseTool):),success=False,)+ content = str(full_text)+ metadata: dict[str, Any] = {"source_id": source_id, "char_count": len(content)}+ if source_id.startswith("hs-tutor-"):+ offset = kwargs.get("offset", 0)+ if type(offset) is not int or not 0 <= offset < len(content):+ return ToolResult(+ content="Error: offset must be a non-negative integer within the archive.",+ success=False,+ )+ if offset or len(content) > self.HISTORY_PAGE_CHARS:+ end = min(offset + self.HISTORY_PAGE_CHARS, len(content))+ next_offset = end if end < len(content) else None+ metadata.update(offset=offset, next_offset=next_offset)+ content = json.dumps(+ {+ "archive_id": source_id,+ "offset": offset,+ "next_offset": next_offset,+ "total_chars": len(content),+ "content": content[offset:end],+ },+ ensure_ascii=False,+ )return ToolResult(- content=str(full_text),- metadata={"source_id": source_id, "char_count": len(str(full_text))},+ content=content,+ metadata=metadata,public_result={"content": "Attached source inspected privately."}if kwargs.get("_mastery_source_context")else None,diff --git a/tests/capabilities/test_mastery_history_recursion.py b/tests/capabilities/test_mastery_history_recursion.pynew file mode 100644index 000000000..22f6e30e1--- /dev/null+++ b/tests/capabilities/test_mastery_history_recursion.py@@ -0,0 +1,142 @@+"""Exact recall must not archive its own output again (#2032)."""++from copy import deepcopy+import json+from types import SimpleNamespace+from unittest.mock import AsyncMock, MagicMock++import pytest++from deeptutor.capabilities.mastery.history import project_mastery_replay+from deeptutor.capabilities.mastery.memory import MasteryContextBuilder, archive_text+from deeptutor.services.session.model_history import normalize_model_turn+from deeptutor.tools.builtin import ReadSourceTool+++def exchange(number, source_id, content, *, tool_name="read_source"):+ calls = [+ {+ "id": f"recall-{i}",+ "type": "function",+ "function": {+ "name": tool_name,+ "arguments": json.dumps({"source_id": source_id}),+ },+ }+ for i in range(2)+ ]+ messages = [+ {"role": "user", "content": f"Learner correction {number}"},+ {"role": "assistant", "content": "Let me recall.", "tool_calls": calls},+ *[{"role": "tool", "tool_call_id": call["id"], "content": content} for call in calls],+ {"role": "assistant", "content": f"Tutor explanation {number}"},+ ]+ return [+ {"id": number * 2 - 1, **messages[0]},+ {+ "id": number * 2,+ **messages[-1],+ "metadata": {"model_turn": {"version": 1, "messages": messages}},+ },+ ]+++async def test_repeated_recall_archive_cycles_do_not_nest_or_grow_exponentially():+ tool = ReadSourceTool()+ sources = {+ "hs-tutor-0": json.dumps(+ {+ "archive_id": "hs-tutor-0",+ "messages": [{"role": "user", "content": "Original learner misconception"}],+ }+ )+ }+ for number in range(1, 20):+ previous = f"hs-tutor-{(number - 1) * 2}"+ read = await tool.execute(source_id=previous, source_index=sources)+ assert read.success+ rows = exchange(number, previous, read.content)+ original = deepcopy(rows)+ archived = archive_text(rows)+ messages = json.loads(archived)["messages"]+ assert normalize_model_turn({"version": 1, "messages": messages}) is not None+ assert f"Learner correction {number}" in archived+ assert f"Tutor explanation {number}" in archived+ for message in messages:+ if message["role"] == "tool":+ assert json.loads(message["content"])["archive_id"] == previous+ assert read.content not in message["content"]+ assert len(archived) < 2000+ assert rows == original+ sources[f"hs-tutor-{number * 2}"] = archived+ # Following a reference still retrieves the original evidence.+ read = await tool.execute(source_id="hs-tutor-0", source_index=sources)+ assert json.loads(read.content)["messages"][0]["content"] == "Original learner misconception"+++async def test_legacy_oversized_recall_is_projected_without_rewriting_saved_turns():+ # Simulate an already polluted stored result. No recursive JSON decoding is+ # needed: the original call tells us which archive owns that evidence.+ rows = exchange(2, "hs-tutor-2", 'old nested "archive" \\ payload ' * 100_000)+ original = deepcopy(rows)+ store = MagicMock()+ store.get_session = AsyncMock(return_value={})+ store.get_messages_for_context = AsyncMock(return_value=rows)+ store.update_summary = AsyncMock()+ builder = MasteryContextBuilder(store)+ builder._summarize = AsyncMock()+ built = await builder.build(+ session_id="s",+ llm_config=SimpleNamespace(model="gpt-test", context_window=128000, max_tokens=4096),+ )+ builder._summarize.assert_not_awaited()+ store.update_summary.assert_not_awaited()+ assert len(built.history_sources["hs-tutor-4"]) < 2000+ assert len(json.dumps(built.model_history)) < 2000+ assert normalize_model_turn({"version": 1, "messages": built.model_history}) is not None+ assert rows == original+++ "source_id, tool_name, content",+ [+ ("nb-1", "read_source", "Original notebook evidence"),+ ("hs-other-session", "read_source", "Other session evidence"),+ ("hs-tutor-2", "rag", "Original retrieved evidence"),+ ("hs-tutor-2", "read_source", "Error: unknown source_id 'hs-tutor-2'."),+ ],+)+def test_other_evidence_and_failed_reads_stay_verbatim(source_id, tool_name, content):+ rows = exchange(2, source_id, content, tool_name=tool_name)+ messages = rows[-1]["metadata"]["model_turn"]["messages"]+ assert project_mastery_replay(messages) == messages+ assert json.loads(archive_text(rows))["messages"] == messages+++def test_reused_call_ids_in_separate_turns_reference_the_correct_archive():+ first = exchange(2, "hs-tutor-2", "First archive body")+ second = exchange(3, "hs-tutor-4", "Second archive body")+ messages = [+ *first[-1]["metadata"]["model_turn"]["messages"],+ *second[-1]["metadata"]["model_turn"]["messages"],+ ]+ original = deepcopy(messages)+ projected = project_mastery_replay(messages)+ references = [json.loads(m["content"])["archive_id"] for m in projected if m["role"] == "tool"]+ assert references == ["hs-tutor-2", "hs-tutor-2", "hs-tutor-4", "hs-tutor-4"]+ assert project_mastery_replay(projected) == projected+ assert messages == original++[email protected]("tool_name", ["read_source", "pdf"])+async def test_inferred_single_history_source_does_not_reenter_archive(tool_name):+ original = archive_text(exchange(1, "nb-1", "Original notebook evidence"))+ read = await ReadSourceTool().execute(source_index={"hs-tutor-2": original})+ rows = exchange(2, "", read.content, tool_name=tool_name)+ archived = json.loads(archive_text(rows))+ results = [m["content"] for m in archived["messages"] if m["role"] == "tool"]+ assert all(json.loads(result)["archive_id"] == "hs-tutor-2" for result in results)+ assert all("Original notebook evidence" not in result for result in results)diff --git a/tests/tools/test_read_source.py b/tests/tools/test_read_source.pyindex 5e086ac91..55c50be0f 100644--- a/tests/tools/test_read_source.py+++ b/tests/tools/test_read_source.py@@ -1,10 +1,14 @@from __future__ import annotationsimport asyncio+import json++import pytestfrom deeptutor.core.context import UnifiedContextfrom deeptutor.runtime.agentic.tool_dispatch import _prepare_tool_argsfrom deeptutor.runtime.registry.tool_registry import ToolRegistry+from deeptutor.tools.builtin import ReadSourceTooldef _registry() -> ToolRegistry:@@ -83,3 +87,50 @@ def test_alias_defaults_survive_canonical_argument_augmentation() -> None:)assert prepared == [("call-1", "rag_naive", {"mode": "naive"})]+++async def test_large_history_can_be_reconstructed_from_bounded_pages():+ tool = ReadSourceTool()+ original = '学员纠正了之前的答案。"\\\n' * 4000+ sources = {"hs-tutor-2": original}+ offset = 0+ pages = []+ while offset is not None:+ read = await tool.execute(+ source_id="hs-tutor-2",+ source_index=sources,+ offset=offset,+ _mastery_source_context=True,+ )+ assert read.success+ page = json.loads(read.content)+ assert page["offset"] == offset+ assert page["total_chars"] == len(original)+ assert 0 < len(page["content"]) <= tool.HISTORY_PAGE_CHARS+ assert page["next_offset"] == read.metadata["next_offset"]+ assert read.public_result == {"content": "Attached source inspected privately."}+ pages.append(page["content"])+ offset = page["next_offset"]+ assert "".join(pages) == original+ assert sources == {"hs-tutor-2": original}++[email protected]("offset", [-1, True, "0", 1.5, 10, None])+async def test_history_page_rejects_invalid_offsets(offset):+ read = await ReadSourceTool().execute(+ source_id="hs-tutor-2", source_index={"hs-tutor-2": "short"}, offset=offset+ )+ assert not read.success+ assert "offset" in read.content++[email protected]("source_id", ["nb-1", "hs-session", "at-pdf-1", "hs-tutor-2"])+async def test_existing_full_source_reads_are_unchanged(source_id):+ text = "Original evidence" if source_id == "hs-tutor-2" else "Original evidence" * 4000+ read = await ReadSourceTool().execute(source_id=source_id, source_index={source_id: text})+ assert read.success+ assert read.content == text+ assert read.metadata == {"source_id": source_id, "char_count": len(text)}