Skip to content

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

fix(mastery): 阻止历史回忆递归归档膨胀

AleFlyX8f9fb42b6bc0
diff --git a/deeptutor/capabilities/mastery/history.py b/deeptutor/capabilities/mastery/history.py
index 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, Any
if 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.py
index bf7c9bddd..886af2835 100644
--- a/deeptutor/capabilities/mastery/memory.py
+++ b/deeptutor/capabilities/mastery/memory.py
@@ -9,7 +9,11 @@ from __future__ import annotations
import json
from 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_images
from deeptutor.services.llm.types import StreamOutcome
from 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 replayed
if 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__.py
index 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.py
new file mode 100644
index 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.py
index 5e086ac91..55c50be0f 100644
--- a/tests/tools/test_read_source.py
+++ b/tests/tools/test_read_source.py
@@ -1,10 +1,14 @@
from __future__ import annotations
import asyncio
+import json
+
+import pytest
from deeptutor.core.context import UnifiedContext
from deeptutor.runtime.agentic.tool_dispatch import _prepare_tool_args
from deeptutor.runtime.registry.tool_registry import ToolRegistry
+from deeptutor.tools.builtin import ReadSourceTool
def _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)}