yjh051108/mmkit/paper-write-zh

Chinese Paper LaTeX Writing

Draft a Chinese LaTeX paper section by section: $ARGUMENTS

Constants

• PAPER_TYPE — bachelor/master/journal. Default journal.
• MAX_PAGES — bachelor=25, master=55, journal=15. Body pages must be ≥ MAX_PAGES.
• CUSTOM_REQUIREMENTS — Highest priority.
• REVIEWER_SCRIPT — External reviewer script reviewer_client.py

Inputs

1. PAPER_PLAN.md — outline with data analysis summary
2. NARRATIVE_REPORT.md — research narrative
3. figures/ — PDFs + latex_includes*.tex + tikz_diagrams.tex（TikZ，编译为 tikz_diagrams.pdf）
4. user_data/ — user materials (.cls/.docx templates, data files)

If user_data/ has CSV/JSON, read exact values with pandas before writing experiment chapters.

Load shared rules

cat _utils/writing_rules.md 2>/dev/null || cat skills/shared-scripts/writing_rules.md

docx 模式（output_format = docx）

当 params.output_format == 'docx'：只产出 paper/main.md 一个文件（≥ 5KB），禁止生成 .tex、禁止残留 LaTeX 命令。Markdown 规范（标题层级/摘要/公式/图表/引用）见本 skill 的 references/docx-mode-zh.md。后续由 docx-cn-engine 转 .docx。

Template selection

Priority: user .cls > user .docx > built-in template

Built-in templates in templates/:

• bachelor_main.tex — 本科毕业论文 (ctexart)
• master_main.tex — 硕士学位论文 (ctexbook)
• journal_main.tex — 期刊论文 (ctexart, two-column)

Copy template to paper/main.tex, replace all bracket placeholders with actual content. Template handles fonts, spacing, margins, gbt7714, headers/footers — do not write main.tex from scratch.

⛔ CRITICAL TEMPLATE RULES:

1. NEVER rewrite main.tex from scratch — the template has carefully tuned preamble
2. NEVER replace `\listoftables`/`\listoffigures` with hand-written text — use auto-generated lists
3. Only replace bracket placeholders ([论文标题], [作者], etc.) with actual content
4. Only modify \input{sections/...} lines to match actual section filenames

<abstract_format>

Abstract format

The template uses manual typesetting for abstracts (\begin{center}{\heiti 摘要}\end{center} + \begin{center}{\bfseries Abstract}\end{center}). Do not use two \begin{abstract} environments — ctexart's abstract title is fixed as "摘要", so the English abstract would also show a Chinese title.

Chinese abstract: 500-700 characters. Aim to fill most of one page but leave 3-4 lines margin at the bottom — overflowing onto a second page looks worse than being slightly short. Content chain: 研究背景与意义 → 现有方法不足 → 本文方法 → 数据来源与处理 → 关键数值结果（精度、R²、p值等）→ 应用价值与建议.

English abstract: 350-500 words, faithful translation covering the same structure and all numerical results. Same principle — fit on one page, do not overflow. </abstract_format>

⛔⛔⛔ 完成铁律（最高优先级，违反则本步骤失败）

根据 `params.output_format` 决定主产物路径：

• PDF 模式（默认）：必须产出 paper/main.tex（基于模板，≥ 5KB）+ paper/sections/*.tex（每章节 ≥ 500 字符）+ paper/references.bib
• docx 模式（用户选 Word 输出）：必须产出 paper/main.md（单文件，含完整论文，≥ 5KB）。禁止产 paper/main.tex

⛔ 如何识别当前模式：

grep -q "Word（.docx）" CLAUDE.md && echo "MODE=docx" || echo "MODE=pdf"

⛔ 结束前必跑产出验证（步骤的最后一步，绝不省略）：

echo "=== 产出验证（必须全部 ✅）==="
MODE=$(grep -q "Word（.docx）" CLAUDE.md 2>/dev/null && echo docx || echo pdf)
echo "MODE: $MODE"
PASS=true
if [ "$MODE" = "docx" ]; then
    [ -f paper/main.md ] && SZ=$(wc -c < paper/main.md) || SZ=0
    if [ "$SZ" -ge 5120 ]; then echo "✅ paper/main.md ($SZ bytes)"; else echo "❌ paper/main.md 缺失或过小 ($SZ bytes)"; PASS=false; fi
else
    [ -f paper/main.tex ] && SZ=$(wc -c < paper/main.tex) || SZ=0
    if [ "$SZ" -ge 5120 ]; then echo "✅ paper/main.tex ($SZ bytes)"; else echo "❌ paper/main.tex 缺失或过小 ($SZ bytes)"; PASS=false; fi
    SECT_COUNT=$(ls paper/sections/*.tex 2>/dev/null | wc -l)
    if [ "$SECT_COUNT" -ge 3 ]; then echo "✅ paper/sections/*.tex ($SECT_COUNT 个章节)"; else echo "❌ paper/sections/ 章节过少 ($SECT_COUNT)"; PASS=false; fi
fi
[ "$PASS" != true ] && echo "⛔ 产出验证失败 — 必须补全后重新跑验证, 不要结束本步骤"

如果验证失败,继续补全产出而不是退出。

Workflow

Step 0: Backup + resume check + 上游验证

⛔ 上游输出完整性检查（写论文前必做）：

echo "=== 上游输出完整性检查 ==="
UPSTREAM_OK=true
 
# 1. 核心文件是否存在
for f in PAPER_PLAN.md RESULTS.md; do
    if [ -f "$f" ]; then
        sz=$(wc -c < "$f")
        echo "✅ $f ($sz 字符)"
        [ "$sz" -lt 500 ] && { echo "  ⚠ 文件过小，内容可能不完整"; UPSTREAM_OK=false; }
    else
        echo "⚠ $f 不存在（将使用最小大纲兜底）"
    fi
done
 
# 2. 实验数据文件
[ -f figures/all_results.json ] && echo "✅ figures/all_results.json" || echo "⚠ 无 all_results.json，数值可能不准确"
[ -f experiment_results.md ] && echo "✅ experiment_results.md" || echo "  （无 experiment_results.md，将依赖 RESULTS.md）"
 
# 3. 图表文件
PDF_COUNT=$(ls figures/*.pdf 2>/dev/null | wc -l)
echo "PDF 图表: $PDF_COUNT 张"
[ "$PDF_COUNT" -eq 0 ] && echo "⚠ 无 PDF 图表，论文将缺少图片"
 
# 4. latex_includes.tex
[ -f figures/latex_includes.tex ] && echo "✅ figures/latex_includes.tex" || echo "⚠ 无 latex_includes.tex，图表嵌入代码缺失"
 
echo "=== 上游检查完成 ==="
$UPSTREAM_OK || echo "⚠ 部分上游文件不完整，继续执行但结果可能欠佳"

Back up existing paper/ to paper-backup-{timestamp}/. Check for incomplete sections:

echo "=== 断点续写检查 ==="
if [ -d "paper/sections" ]; then
    for f in paper/sections/*.tex; do
        [ -f "$f" ] || continue
        chars=$(wc -c < "$f")
        if [ "$chars" -lt 500 ]; then
            echo "⚠ 占位符: $(basename $f) ($chars 字符) — 需要续写"
        else
            echo "✅ 已完成: $(basename $f) ($chars 字符)"
        fi
    done
fi

Resume: only write placeholder sections (<500 chars or contains "待补充"/"placeholder"), skip completed ones (>2000 chars). See <resume_strategy> in writing_rules.md for full details.

⛔ 数值来源规则（全文遵守）： 所有论文中的数值（精度、RMSE、R²、p-value、系数、训练时间等）必须来自 figures/all_results.json 或 RESULTS.md。写任何含数值的章节之前先：

[ -f figures/all_results.json ] && cat figures/all_results.json
[ -f RESULTS.md ] && cat RESULTS.md

从中复制数字原样填入论文。不要凭记忆估算、四舍五入或编造数值。最终的 quality gate 会做数值一致性检查，编造的数字会被发现。

⛔ Claims-Evidence 对照（必须严格遵循规划）：

写每个章节前，先重读 PAPER_PLAN.md 中的 claims-evidence 矩阵：

grep -A 100 'Claims-Evidence\|claim.*evidence\|claim-evidence\|观点.*证据' PAPER_PLAN.md 2>/dev/null | head -30

写作纪律：

• 论文中的每个论断必须对应到规划中的某一行
• 不要添加规划外的新论断（如有新发现，先更新 PAPER_PLAN.md）
• 不要跳过规划中的论断（即使是负面结果也要如实报告）
• 每个论断的数值证据必须与 figures/all_results.json 一致

如果某个规划中的论断在数据中找不到证据，诚实写"初步结果提示 X，更严谨的验证留待未来工作"，不要编造证据。

Step 1: Initialize

Create paper/, copy template to main.tex, generate math_commands.tex (paper-specific commands only — do not redefine \sin, \cos, \log, etc.).

Step 2: Figure inventory

Before writing any section, build a complete inventory of available figures. This prevents empty figure environments (caption without image).

echo "=== Available PDF figures ==="
ls -la figures/*.pdf 2>/dev/null || echo "No PDF figures found"
echo ""
echo "=== Available table files (PDF模式: .tex / Word模式: .md) ==="
ls -la figures/TABLE_*.tex figures/TABLE_*.md 2>/dev/null || echo "No TABLE files found"
echo ""
echo "=== TikZ 几何/算法/架构图 ==="
# TikZ 图由 paper-figure 生成为 figures/tikz_diagrams.tex → 编译成 figures/tikz_diagrams.pdf
# （历史命名可能是 tikz_architecture_examples.tex，一并兼容）。TikZ 的 PDF 已被写进 latex_includes.tex。
ls -la figures/tikz_*.pdf figures/tikz_*.tex 2>/dev/null || echo "No TikZ diagrams"
grep -l 'tikz_' figures/latex_includes.tex >/dev/null 2>&1 && echo "→ TikZ 已在 latex_includes.tex 中，按其图块嵌入对应章节" || true
echo ""
echo "=== latex_includes.tex content (figure→PDF mapping) ==="
cat figures/latex_includes.tex 2>/dev/null || echo "No latex_includes.tex"

From the output above, build a mapping table: figure label → PDF filename → target section. Only embed figures whose PDF files actually exist — do not create figure environments for PDFs that don't exist (this causes empty figures with just a caption and no image).

⛔ TikZ 图（如 `figures/tikz_diagrams.pdf` / `figures/tikz_*.pdf`）必须嵌入论文。 它们已在 latex_includes.tex 中有对应 \includegraphics 图块，按几何/算法/架构图的章节归属嵌入（几何示意图→对应子问题章节，算法流程图→模型建立章节）。禁止漏掉任何 `tikz_*.pdf`。

⛔ 中文论文的图表 caption 必须是中文。 如果 latex_includes.tex 里的 caption 是英文，嵌入时必须翻译成中文。例如：\caption{Model Performance Comparison} → \caption{模型性能对比}。

Also scan figures/*.tex for all \begin{figure} / \begin{table} blocks with their \label{}. After writing, verify all embedded:

grep -oh '\\label{[^}]*}' figures/*.tex 2>/dev/null | sort -u > _all_fig_labels.txt
grep -oh '\\label{[^}]*}' paper/sections/*.tex paper/main.tex 2>/dev/null | sort -u > _embedded_labels.txt
comm -23 _all_fig_labels.txt _embedded_labels.txt  # should be empty

Step 2.5: 文献预检索（写正文之前必须完成）

⛔ 在写任何 \cite{} 之前，必须先建立已验证的文献池。

目的：先搜索到真实存在的论文，写正文时只引用池子里的论文，避免编造不存在的文献。

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
mkdir -p _tmp
 
# 根据论文的关键主题领域搜索真实论文
# （根据你的具体选题调整搜索词）
# 示例：
#   $PYTHON "$SCHOLAR_SCRIPT" bibtex "空间杜宾模型 数字经济" --max 5
#   $PYTHON "$SCHOLAR_SCRIPT" bibtex "算力基础设施 区域发展" --max 5

搜索后，创建 _tmp/_verified_refs.txt，每行一篇已验证论文：

key: lesage_2009_spatial | title: Introduction to Spatial Econometrics | authors: LeSage, Pace | year: 2009 | match: good

写正文时只能引用这个池子里的论文。 如果需要引用池子外的论文，先搜索验证后再加入池子。

兜底：如果 scholar_fetch.py 搜不到或 match_label="low"，用 WebSearch 在 Google Scholar / Semantic Scholar 网站上搜索，手动核实标题+作者+年份后再加入池子。

Step 3: Write each section

Writing order: method/core → experiments → introduction → related work → conclusion. Save each section immediately. If approaching output limit, create % [PLACEHOLDER] files for remaining sections.

⛔ 写实验/结果章节前，必须先读 experiment_results.md / RESULTS.md / figures/*.json 获取精确数值。 不要凭记忆编造结果——所有数值（精度、R²、p 值、系数等）必须从数据文件中提取。

⛔ 写作风格铁律：

• 禁止在正文中使用 `\begin{itemize}` 或 `\begin{enumerate}`。 用连贯段落叙述，需要列举时用"（1）...（2）...（3）..."行内编号或"首先...其次..."过渡词。
• 每段至少 3-5 句话，不要写 1-2 句的短段落。
• 连续段落不能以相同句式开头。

Follow all rules from _utils/writing_rules.md (interleaving, embedding, LaTeX constraints, page filling, resume strategy).

⛔ 图文并茂硬规则（每个章节都必须遵守）：

• 所有 \begin{figure} 必须用 [H]，不要用 [htbp]
• 每张图/表后面必须有 ≥5 行分析文字（数值解读+对比+结论），然后才能放下一张图
• 绝对禁止两张图连续出现中间没有分析段落
• 图片用 \includegraphics[width=0.85\textwidth,keepaspectratio]（以宽度为主，高度自适应）。⛔ 不要再加 height=0.38\textheight 这种小高度限制——在 keepaspectratio 下 height 只会把图压得更小：方形或竖高的图（热力图、雷达图、森林图、混淆矩阵、竖排子图、流程图）会被 0.38 页高卡到只有半页宽，导致"图很小看不清"。只有当某张图确实接近整页高、可能溢出时，才加 height=0.9\textheight 作为防溢出兜底

After each section, check chars:

chars=$(wc -c < "paper/sections/当前章节.tex")
echo "当前章节: $chars 字符"
# Chinese LaTeX ≈ 800-1000 chars/page
# If chapter page budget in PAPER_PLAN.md is 5 pages but only 2000 chars (~2.5 pages), expand immediately

<exemplar_depth>

Writing depth by paper type

本科毕业论文 (30 pages, 5 chapters):

• 绪论 (5-6p): 研究背景 1-2 段 + 国内外研究现状按 2-3 个方向分类综述 + 研究内容与方法 + 论文结构
• 理论基础 (5-6p): 核心概念定义 + 相关理论介绍 + 技术路线说明, each concept in full paragraphs (not one-sentence mentions)
• 方法/系统设计 (8-10p): 整体架构 + 各模块详细设计 + 关键算法/公式 + 实现细节
• 实验/测试 (6-8p): 实验环境 + 数据集 + 评价指标 + 主要结果表 + 对比图 + 结果分析 (1-2 paragraphs per result)
• 总结与展望 (2-3p): 工作总结 + 不足之处 + 未来改进方向

硕士论文 — CS/AI (80 pages, 6 chapters):

• 绪论 (8-10p): 研究背景 2-3 段详细论述 + 国内外研究现状按子领域分 3-4 类每类 3-5 篇详细讨论 + 研究内容与创新点
• 相关工作 (12-14p): 按子领域分组, each sub-field has overview paragraph + representative methods detailed + connection to this work
• 方法 (18-20p): each core concept in full paragraphs (definition → formula → intuition → connection to this work), derivation steps not skipped
• 实现 (10-12p): 系统架构 + 数据流 + 超参数配置 + 工程优化细节
• 实验 (20-24p): every result has 2-3 paragraphs of interpretation (数值分析 + 原因分析 + 与其他方法对比), not just "如表所示我们更好"
• 总结 (4-6p): 改述贡献 + 局限性 + 未来工作