DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(co-writer): keep automark annotations readable (#1603)
Bingxi Zhao (Frank)1e1e02beaea3
diff --git a/deeptutor/co_writer/edit_agent.py b/deeptutor/co_writer/edit_agent.pyindex b74218887..ad13c2b2d 100644--- a/deeptutor/co_writer/edit_agent.py+++ b/deeptutor/co_writer/edit_agent.py@@ -92,6 +92,13 @@ def save_tool_call(call_id: str, tool_type: str, data: dict[str, Any]) -> str:return str(filepath)+def _readable_automark_output(marked_text: str, original_text: str) -> str:+ """Never insert unsupported rough-notation markup into a Markdown draft."""+ if "data-rough-notation" in marked_text.lower():+ return original_text+ return marked_text++class EditAgent(BaseAgent):"""Co-writer editing agent using unified BaseAgent."""@@ -340,6 +347,7 @@ class EditAgent(BaseAgent):):_chunks.append(_c)response = clean_thinking_tags("".join(_chunks), self.binding, self.get_model())+ response = _readable_automark_output(response, text)# Record operation historyappend_history(diff --git a/deeptutor/co_writer/prompts/en/edit_agent.yaml b/deeptutor/co_writer/prompts/en/edit_agent.yamlindex 9c7423d7d..ab055f5b3 100644--- a/deeptutor/co_writer/prompts/en/edit_agent.yaml+++ b/deeptutor/co_writer/prompts/en/edit_agent.yaml@@ -22,96 +22,18 @@ user_template: |Output only the edited text, without quotes or explanations.auto_mark_system: |- You are a professional academic reading annotation assistant, helping readers quickly grasp the core points of text.+ You are a reading annotation assistant. The result is inserted into an editable Markdown draft, so every annotation must be readable as plain text.- ## Task- Read the input text and **carefully select** the most critical information for annotation. Annotations should help readers quickly locate key points without interfering with reading.+ Preserve the original wording, punctuation, paragraphs, and Markdown. Insert only these visible inline markers:+ - 【term】 for a short key concept, name, or numerical value.+ - 《statement》 for a short definition, finding, or conclusion.- ## Available Tags and Precise Usage Scenarios+ Mark sparingly: at most one term per 100 characters and two statements per paragraph. Do not nest markers or wrap Markdown syntax such as `**` and backticks. Never output HTML, XML, CSS, or data attributes. If nothing needs annotation, return the original text unchanged. Output only the marked draft.- ### 1. Circle - Use Sparingly- ```html- <span data-rough-notation="circle">content</span>- ```- **Applicable Scenarios**:- - Core topic words of articles/paragraphs (e.g., key concepts in paper titles)- - Unique proper nouns, model names (e.g., GPT-4, BERT)- - Key numerical values/metrics (e.g., 95.7%, p<0.05)-- **Limitation**: Maximum 1 per 100 characters, content should not exceed 5 characters-- ### 2. Highlight - Moderate Use- ```html- <span data-rough-notation="highlight">content</span>- ```- **Applicable Scenarios**:- - Definitional statements (e.g., "XX refers to...")- - First appearance of core concepts and their explanations- - Important methodological descriptions-- **Limitation**: Maximum 2 per paragraph, content 2-15 characters-- ### 3. Box - Minimal Use- ```html- <span data-rough-notation="box">content</span>- ```- **Applicable Scenarios**:- - Mathematical formulas, equations- - Specific data points or statistical values- - Code snippets, commands- - Version numbers, dates, and other precise information-- **Limitation**: Maximum 1 per paragraph, content should not exceed 20 characters-- ### 4. Underline - Moderate Use- ```html- <span data-rough-notation="underline">content</span>- ```- **Applicable Scenarios**:- - Conclusive statements- - Key expressions of causal relationships- - Core viewpoints in comparisons or contrasts- - Author's main arguments-- **Limitation**: Maximum 1 per paragraph, content 5-30 characters-- ### 5. Bracket - Use Sparingly- ```html- <span data-rough-notation="bracket">content</span>- ```- **Applicable Scenarios**:- - Entire paragraphs that are core summaries or conclusions- - Important quotations or theorem statements- - Critical warnings or notes-- **Limitation**: Maximum 1-2 per entire article, for truly indispensable complete sentences-- ## Core Rules-- 1. **Exercise Restraint**: Better to annotate less than to over-annotate. Annotation density should not exceed 10% of total text per paragraph.- 2. **No Modifications**: Absolutely must not modify, delete, or add any text from the original, only insert HTML tags.- 3. **Tag Placement**: Tags must be placed inside Markdown symbols (e.g., `**`, `*`, `` ` ``).- 4. **When No Annotation Needed**: If the text has no information worth annotating, return it as-is.-- ## Examples-- **Input**:+ Example input:Deep learning is a subfield of machine learning, and its core is using neural networks to learn data representations.-- **Output**:- <span data-rough-notation="highlight">Deep learning is a subfield of machine learning</span>, and its core is using <span data-rough-notation="circle">neural networks</span> to learn data representations.-- **Input**:- The weather is nice today, perfect for going out for a walk.-- **Output**:- The weather is nice today, perfect for going out for a walk.-- **Input**:- Experimental results show that our proposed method achieved 99.2% accuracy on the MNIST dataset, significantly exceeding the baseline method's 95.1%.-- **Output**:- <span data-rough-notation="underline">Experimental results show that our proposed method achieved <span data-rough-notation="box">99.2%</span> accuracy on the MNIST dataset</span>, significantly exceeding the baseline method's 95.1%.+ Example output:+ 《Deep learning is a subfield of machine learning》, and its core is using 【neural networks】 to learn data representations.auto_mark_user_template: |Process the following text:diff --git a/deeptutor/co_writer/prompts/zh/edit_agent.yaml b/deeptutor/co_writer/prompts/zh/edit_agent.yamlindex d1f65ccbb..436a7510c 100644--- a/deeptutor/co_writer/prompts/zh/edit_agent.yaml+++ b/deeptutor/co_writer/prompts/zh/edit_agent.yaml@@ -22,96 +22,18 @@ user_template: |只输出编辑后的文本,不要包含引号或解释。auto_mark_system: |- 你是一位专业的学术阅读标注助手,帮助读者快速掌握文本的核心要点。+ 你是阅读批注助手。结果会直接写入可编辑的 Markdown 草稿,因此标注必须在纯文本中可读。- ## 任务- 阅读输入文本,**精心选择**最关键的信息进行标注。标注应帮助读者快速定位关键点,而不干扰阅读。+ 保留原文的措辞、标点、段落和 Markdown,只插入以下可见的行内标记:+ - 【术语】标记简短的核心概念、名称或数值。+ - 《关键句》标记简短的定义、发现或结论。- ## 可用标签及精确使用场景+ 保持克制:每 100 字最多标记一个术语,每段最多标记两处关键句。标记不得嵌套,也不要包住 `**`、反引号等 Markdown 符号。绝不输出 HTML、XML、CSS 或 data 属性。如果没有值得标注的内容,原样返回。只输出标注后的草稿。- ### 1. Circle(圈注)- 谨慎使用- ```html- <span data-rough-notation="circle">内容</span>- ```- **适用场景**:- - 文章/段落的核心主题词(如论文标题中的关键概念)- - 独特的专有名词、模型名称(如GPT-4、BERT)- - 关键数值/指标(如95.7%、p<0.05)-- **限制**:每100字符最多1个,内容不超过5个字符-- ### 2. Highlight(高亮)- 适度使用- ```html- <span data-rough-notation="highlight">内容</span>- ```- **适用场景**:- - 定义性陈述(如"XX是指...")- - 核心概念首次出现及其解释- - 重要的方法论描述-- **限制**:每段最多2个,内容2-15个字符-- ### 3. Box(方框)- 最少使用- ```html- <span data-rough-notation="box">内容</span>- ```- **适用场景**:- - 数学公式、方程式- - 具体数据点或统计值- - 代码片段、命令- - 版本号、日期等精确信息-- **限制**:每段最多1个,内容不超过20个字符-- ### 4. Underline(下划线)- 适度使用- ```html- <span data-rough-notation="underline">内容</span>- ```- **适用场景**:- - 结论性陈述- - 因果关系的关键表达- - 比较或对比中的核心观点- - 作者的主要论点-- **限制**:每段最多1个,内容5-30个字符-- ### 5. Bracket(括号)- 谨慎使用- ```html- <span data-rough-notation="bracket">内容</span>- ```- **适用场景**:- - 作为核心摘要或结论的整段- - 重要引用或定理陈述- - 关键警告或注释-- **限制**:整篇文章最多1-2个,用于真正不可或缺的完整句子-- ## 核心规则-- 1. **保持克制**:宁可少标注也不要过度标注。每段的标注密度不应超过文本总量的10%。- 2. **不做修改**:绝对不能修改、删除或添加原文中的任何文字,只能插入HTML标签。- 3. **标签位置**:标签必须放在Markdown符号内(如`**`、`*`、`` ` ``)。- 4. **无需标注时**:如果文本没有值得标注的信息,原样返回。-- ## 示例-- **输入**:+ 输入示例:深度学习是机器学习的一个子领域,其核心是使用神经网络来学习数据表示。-- **输出**:- <span data-rough-notation="highlight">深度学习是机器学习的一个子领域</span>,其核心是使用<span data-rough-notation="circle">神经网络</span>来学习数据表示。-- **输入**:- 今天天气很好,适合出去散步。-- **输出**:- 今天天气很好,适合出去散步。-- **输入**:- 实验结果表明,我们提出的方法在MNIST数据集上达到了99.2%的准确率,显著超过了基线方法的95.1%。-- **输出**:- <span data-rough-notation="underline">实验结果表明,我们提出的方法在MNIST数据集上达到了<span data-rough-notation="box">99.2%</span>的准确率</span>,显著超过了基线方法的95.1%。+ 输出示例:+ 《深度学习是机器学习的一个子领域》,其核心是使用【神经网络】来学习数据表示。auto_mark_user_template: |处理以下文本:diff --git a/tests/api/test_co_writer.py b/tests/api/test_co_writer.pyindex 7ab752dce..db3d65088 100644--- a/tests/api/test_co_writer.py+++ b/tests/api/test_co_writer.py@@ -159,6 +159,15 @@ def test_load_history_survives_corrupt_file(tmp_path, monkeypatch):assert edit_agent.load_history() == []+def test_automark_never_returns_unsupported_rough_notation_markup():+ original = "Deep learning uses neural networks."+ marked = '<span data-rough-notation="circle">Deep learning</span> uses neural networks.'+ assert edit_agent._readable_automark_output(marked, original) == original+ assert edit_agent._readable_automark_output(+ "【Deep learning】 uses neural networks.", original+ ) == ("【Deep learning】 uses neural networks.")++def _docx_bytes_from_document(document: DocxDocument) -> bytes:buf = BytesIO()document.save(buf)