Skip to content

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

perf(explore-context): read the source ahead of the per-turn question

zane-ic04598bfae04
diff --git a/deeptutor/capabilities/explore_context/explorer.py b/deeptutor/capabilities/explore_context/explorer.py
index fa0ae1b3a..c554ebb46 100644
--- a/deeptutor/capabilities/explore_context/explorer.py
+++ b/deeptutor/capabilities/explore_context/explorer.py
@@ -64,6 +64,14 @@ EXPLORE_SOURCE = "chat"
# round runs with tools disabled so it is always forced to finish.
MAX_LOOP_ROUNDS = 5
+# Pre-loading attached sources into the *stable* prefix. The pre-pass starts
+# from scratch every turn and reads the same bytes every time; carrying them in
+# the leading message instead of behind a fresh tool call makes them part of
+# the cache prefix. Set to 0 to keep the original read-through-the-tool layout.
+PRELOAD_SOURCES_ENABLED = True
+PRELOAD_MAX_SOURCES = 2
+PRELOAD_MAX_CHARS = 120_000
+
def _budgets() -> dict:
"""This capability's per-stage token budgets, from agents.yaml.
@@ -191,15 +199,27 @@ class ContextExplorer:
messages: list[dict[str, Any]] = [
{"role": "system", "content": system_prompt},
- {
- "role": "user",
- "content": user_template.format(
- question=(context.user_message or "").strip() or "(empty)",
- mode=str(context.active_capability or "chat"),
- manifest=(context.source_manifest or "").strip() or "(none)",
- ),
- },
]
+ question = (context.user_message or "").strip() or "(empty)"
+ mode = str(context.active_capability or "chat")
+ manifest = (context.source_manifest or "").strip() or "(none)"
+ cache_shaped = self._cache_shaped_messages(
+ source_index=source_index,
+ question=question,
+ mode=mode,
+ manifest=manifest,
+ )
+ if cache_shaped:
+ messages.extend(cache_shaped)
+ else:
+ messages.append(
+ {
+ "role": "user",
+ "content": user_template.format(
+ question=question, mode=mode, manifest=manifest
+ ),
+ }
+ )
tool_schemas = self._read_source_schemas(source_index)
augmenter = self._augmenter(source_index)
client = build_openai_client(self._client_config)
@@ -549,6 +569,81 @@ class ContextExplorer:
except Exception: # pragma: no cover - usage accounting is best-effort
logger.debug("explore_context usage accounting failed", exc_info=True)
+ def _cache_shaped_messages(
+ self,
+ *,
+ source_index: dict[str, str],
+ question: str,
+ mode: str,
+ manifest: str,
+ ) -> list[dict[str, Any]]:
+ """Lay the investigation out so the repeatable bytes come first.
+
+ Provider prompt caches match a *prefix*, so only the bytes before the
+ first per-turn difference can ever be reused. The original layout put
+ the user's question at the top of the first message, which meant the
+ longest shared prefix with the previous turn ended a few tokens in and
+ every byte the pre-pass re-read — including tens of thousands of tokens
+ of unchanged source text — was billed at the miss rate, every turn.
+ Here the question is the *last* message and everything ahead of it
+ (mode, manifest, attached sources) is byte-stable for as long as the
+ attachments are, so it becomes a cache hit.
+
+ Returns ``[]`` when the localized split prompts are absent, leaving the
+ caller on the original single-message layout.
+ """
+ preamble_template = self._t("loop.preamble_template")
+ question_template = self._t("loop.question_template")
+ if not preamble_template or not question_template:
+ return []
+ selected = self._preload_selection(source_index)
+ sources_text = self._render_preloaded_sources(source_index, selected)
+ return [
+ {
+ "role": "user",
+ "content": preamble_template.format(
+ mode=mode, manifest=manifest, sources=sources_text or "(none)"
+ ),
+ },
+ {"role": "user", "content": question_template.format(question=question)},
+ ]
+
+ def _preload_selection(self, source_index: dict[str, str]) -> list[str]:
+ """Which attached sources to carry in the stable prefix.
+
+ Longest first: the point is to move the bytes that would otherwise be
+ re-read and re-billed on every turn into the cached prefix, and the
+ investigation loads the largest source in full anyway. A source larger
+ than the remaining allowance is still taken when it is the first pick,
+ because dropping it would hand the model less than ``read_source``
+ would have.
+ """
+ if not PRELOAD_SOURCES_ENABLED or PRELOAD_MAX_SOURCES <= 0:
+ return []
+ ranked = sorted(
+ (sid for sid, body in source_index.items() if str(body or "").strip()),
+ key=lambda sid: (-len(str(source_index.get(sid) or "")), sid),
+ )
+ selected: list[str] = []
+ total = 0
+ for sid in ranked:
+ if len(selected) >= PRELOAD_MAX_SOURCES:
+ break
+ size = len(str(source_index.get(sid) or ""))
+ if selected and total + size > PRELOAD_MAX_CHARS:
+ continue
+ selected.append(sid)
+ total += size
+ return selected
+
+ def _render_preloaded_sources(self, source_index: dict[str, str], selected: list[str]) -> str:
+ blocks: list[str] = []
+ for sid in selected:
+ body = str(source_index.get(sid) or "").strip()
+ if body:
+ blocks.append(f"### [{sid}] ({self._kind_label(sid)})\n{body}")
+ return "\n\n".join(blocks)
+
@staticmethod
def _source_index(context: UnifiedContext) -> dict[str, str]:
idx = context.metadata.get("source_index")
diff --git a/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml b/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml
index 7e8815654..90a43ff88 100644
--- a/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml
+++ b/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml
@@ -64,6 +64,28 @@ loop:
Begin investigating: call read_source as needed, then write your objective,
thorough investigation.
+ # Cache-shaped split of the same message: everything that repeats across
+ # turns (mode, manifest, attached sources) comes first, and the only per-turn
+ # bytes — the user's request — come last, so the repeated prefix is a prompt
+ # cache hit. Falls back to the single-message user_template above when these
+ # keys are absent.
+ preamble_template: |
+ Current mode: {mode}
+
+ Manifest of readable sources (use read_source to load full text by id):
+ {manifest}
+
+ Full text of this turn's attached sources (already loaded for you — do not
+ call read_source for these again):
+ {sources}
+
+ Begin investigating: call read_source for any further sources you need,
+ then write your objective, thorough investigation.
+
+ question_template: |
+ The user's current request:
+ {question}
+
forced_finish: |
Investigation budget reached. Stop calling tools and write your objective,
thorough investigation now from what you have gathered.
diff --git a/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml b/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml
index 05bf0ff63..76e4e4ca5 100644
--- a/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml
+++ b/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml
@@ -47,6 +47,26 @@ loop:
现在开始调查:按需调用 read_source,然后写出你客观、详尽的调查结论。
+ # 缓存友好版:把「每轮都一样」的内容(模式、清单、来源全文)放在前面,
+ # 把「每轮都变」的用户请求放在最后一条消息。前缀缓存只认公共前缀,
+ # 请求放在最前面会让后面所有稳定内容永远无法命中。
+ # 缺少这两个键时回退到上面的 user_template 单条消息布局。
+ preamble_template: |
+ 当前模式:{mode}
+
+ 可读来源清单(用 read_source 按 id 读取全文):
+ {manifest}
+
+ 本回合附带来源的全文(已为你预先读取,不必再次调用 read_source):
+ {sources}
+
+ 现在开始调查:需要时继续按需调用 read_source 追读其它来源,然后写出你客观、
+ 详尽的调查结论。
+
+ question_template: |
+ 用户当前的请求:
+ {question}
+
forced_finish: |
调查预算已用尽。停止调用工具,用你已经读到的内容,立刻写出客观、详尽的调查结论。