DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(mastery): reorder existing modules through reviewed commits
yepyhun982615faafbb
diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yamlindex 7d0df0c6a..c3a853788 100644--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml@@ -72,6 +72,7 @@ session:**The outline is organised around their goal, not around a document's table of contents.** They are mastering a subject, not finishing a book. So: never transcribe one book's chapter order into modules; never write "this book's overview", "this chapter", or "the author argues" — phrasing that quietly demotes a whole mastery route to a single reading; a document is one piece of evidence about the subject, even when it is the only one. Several documents get reorganised around the subject, not turned into one module each.Once the outline exists, walk them through it — what each module is for and why they come in this order — and ask what they want changed. Change it on the spot. When they are happy, say plainly that the outline is settled; when they want to begin, `mastery_mode` to `study`.+ **Module sequence and content edits are distinct.** To move an existing module earlier or later, include `module_order` in the reviewed preview: every current module ID exactly once, in the requested order. Content edits are optional. Review the exact diff and commit before claiming a saved sequence change; a renamed objective or a conversational detour does not reorder the sidebar. This preserves mastered evidence and unanswered questions, and does not waive prerequisites or change the current objective. Use the commit receipt to distinguish the applied order from the current order after a later edit.study: |-**This mode is for learning.** Work the agreed outline forward, one knowledge point at a time, through its gate.diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yamlindex efe2104cb..b2b8c9671 100644--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml@@ -70,6 +70,7 @@ session:**大纲是围绕他的目标组织的,不是围绕某一份资料的目录。** 他要精通的是一个主题,不是读完一本书。所以:不要把某本书的章节顺序照搬成模块;不要出现「本书全景」「本章」「作者认为」这类把整条路线降格成一次读书的说法;一份资料只是这个主题的若干证据之一,哪怕它只有一份。多份资料要按主题重新组织到一起,而不是一份一个模块。大纲定下来之后,把它讲给他听——每个模块是干什么的、为什么是这个顺序——并请他提意见。他不满意就当场改。他认可之后,明确告诉他大纲已经定稿;他想开始学,就用 `mastery_mode` 切到 `study`。+ **模块顺序与内容修改是两回事。** 要前移或后移已有模块,在审阅预览中传入 `module_order`:按请求的顺序列出全部现有模块 ID,每个恰好一次;内容修改可省略。检查精确差异并提交后才能宣称顺序已保存;改写知识点或临时换话题不会重排侧边栏。重排保留已掌握证据和待答问题,不豁免先修要求,也不改变当前知识点。根据提交回执区分实际提交的顺序与后续编辑后的当前顺序。study: |-**这个模式是用来学的。** 沿着已经定好的大纲推进,一个知识点一个知识点地过门槛。diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.pyindex 5e10a0730..c117e87ba 100644--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@ -2223,7 +2223,13 @@ class MasteryReviseTool(BaseTool):"edits, action=preview returns the exact proposed state changes ""without saving. Review them, then use action=commit with only ""that preview_id in a later model round. Omit action for the "- "existing immediate revision behavior."+ "existing immediate content revision behavior. To change the "+ "displayed module sequence, use action=preview with module_order "+ "containing every existing module ID exactly once; content edits "+ "are optional. Reordering preserves objective IDs and evidence; "+ "it does not abandon an unanswered question or change the active "+ "objective. Never report an order change from a content-only edit "+ "or from an uncommitted preview."),parameters=[ToolParameter(@@ -2239,6 +2245,17 @@ class MasteryReviseTool(BaseTool):description="Commit only: the identifier returned by the reviewed preview.",required=False,),+ ToolParameter(+ name="module_order",+ type="array",+ items={"type": "string"},+ description=(+ "Preview only: complete requested sequence of existing module IDs. "+ "Omit to keep order unchanged; may be used without content edits. "+ "Does not rename modules, waive prerequisites, or move the current objective."+ ),+ required=False,+ ),ToolParameter(name="module_id",type="string",@@ -2323,7 +2340,7 @@ class MasteryReviseTool(BaseTool):if action == "commit":if any(kwargs.get(key) is not None- for key in ("module_id", "modules", "rewrite", "add", "remove")+ for key in ("module_id", "modules", "rewrite", "add", "remove", "module_order")):return ToolResult(content="Commit takes only preview_id; omit all revision edits.", success=False@@ -2343,6 +2360,7 @@ class MasteryReviseTool(BaseTool):"status": "committed",**receipt,"path_revision": progress.version,+ "current_module_order": [module.id for module in progress.modules],"map": map_summary(progress),},meta_key="mastery_revise",@@ -2350,9 +2368,20 @@ class MasteryReviseTool(BaseTool):if kwargs.get("preview_id") is not None:return ToolResult(content="Use preview_id only with action commit.", success=False)- specs, spec_error = _revise_specs(kwargs)- if spec_error is not None:- return ToolResult(content=spec_error, success=False)+ module_order = kwargs.get("module_order")+ if module_order is not None and action != "preview":+ return ToolResult(+ content="Module reordering requires action preview followed by a reviewed commit.",+ success=False,+ )+ specs = {}+ if module_order is None or any(+ kwargs.get(key) is not None+ for key in ("module_id", "modules", "rewrite", "add", "remove")+ ):+ specs, spec_error = _revise_specs(kwargs)+ if spec_error is not None:+ return ToolResult(content=spec_error, success=False)progress = _load_path(service, path_id)if progress is None or not progress.modules:@@ -2360,7 +2389,7 @@ class MasteryReviseTool(BaseTool):try:applied, targets, revised_by_module, resets_by_module = _plan_module_revision(- progress, specs+ progress, specs, module_order=module_order)except (ValueError, TypeError) as exc:return ToolResult(content=str(exc), success=False)@@ -2720,7 +2749,12 @@ def _revised_point_id(module_id: str, taken: set[str]) -> str:index += 1-def _plan_module_revision(progress: LearningProgress, specs: dict[str, dict[str, Any]]):+def _plan_module_revision(+ progress: LearningProgress,+ specs: dict[str, dict[str, Any]],+ *,+ module_order: list[str] | None = None,+):"""Shared planner for direct and reviewed revisions; never mutates stored state."""known_modules = {m.id: m for m in progress.modules}targets: list[LearningModule] = []@@ -2774,6 +2808,10 @@ def _plan_module_revision(progress: LearningProgress, specs: dict[str, dict[str,for module in applied:for point in module.knowledge_points:point.prerequisite_ids = [rewrite_ids.get(ref, ref) for ref in point.prerequisite_ids]+ if module_order is not None:+ from deeptutor.learning.outline_revision import reorder_modules++ applied = reorder_modules(applied, module_order)return applied, targets, revised_by_module, resets_by_modulediff --git a/deeptutor/learning/outline_revision.py b/deeptutor/learning/outline_revision.pyindex ddfc615f5..19f3d32ff 100644--- a/deeptutor/learning/outline_revision.py+++ b/deeptutor/learning/outline_revision.py@@ -6,7 +6,30 @@ import hashlibimport jsonfrom typing import Any-from deeptutor.learning.models import LearningProgress+from deeptutor.learning.models import LearningModule, LearningProgress+++def reorder_modules(+ modules: list[LearningModule], module_order: list[str]+) -> list[LearningModule]:+ """Reorder an existing module set without changing objective identity or content."""+ known = {module.id: module for module in modules}+ if (+ not isinstance(module_order, list)+ or not all(isinstance(module_id, str) and module_id for module_id in module_order)+ or len(module_order) != len(known)+ or len(set(module_order)) != len(module_order)+ or set(module_order) != set(known)+ or len(known) != len(modules)+ ):+ raise ValueError(+ "module_order must contain every existing module ID exactly once, "+ "with no omitted, duplicate, or foreign IDs."+ )+ return [+ known[module_id].model_copy(deep=True, update={"order": index})+ for index, module_id in enumerate(module_order)+ ]def state_digest(progress: LearningProgress) -> str:diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.pyindex 8fed67b89..9459fd993 100644--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@ -1292,6 +1292,8 @@ class LearningService:"modules": [module.model_dump(mode="json") for module in proposed.modules],"changes": changes,"effects": effects,+ "before_module_order": [module.id for module in original.modules],+ "proposed_module_order": [module.id for module in proposed.modules],}preview_id = tx.record_module_preview(payload, session_id=session_id)return {@@ -1299,6 +1301,11 @@ class LearningService:"base_revision": expected_revision,"changes": changes,"effects": effects,+ "before_module_order": payload["before_module_order"],+ "proposed_module_order": payload["proposed_module_order"],+ "module_order_changed": (+ payload["before_module_order"] != payload["proposed_module_order"]+ ),}, proposeddef commit_module_revision(@@ -1353,6 +1360,7 @@ class LearningService:"applied_revision": draft["committed_revision"]if replayedelse tx.base_revision + 1,+ "applied_module_order": [module["id"] for module in draft["modules"]],}return tx.progress, receipt