Skip to content

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

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.py
index 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 history
append_history(
diff --git a/deeptutor/co_writer/prompts/en/edit_agent.yaml b/deeptutor/co_writer/prompts/en/edit_agent.yaml
index 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.yaml
index 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.py
index 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)