Imported from oneMuggle/sage (backend/skills/skill_md/shipped/paper-writing/SKILL.md). Install upstream with npx skills add oneMuggle/sage --skill paper-writing. Copyright stays with the author (Apache-2.0).

期刊论文写作

shipped 基础版。triggers 留空——靠 when_to_use 语义判断激活；用户可派生自定义版本并自行加触发词。与 builtin WriterSkill 的关系：WriterSkill 产纯文本；本技能走 office 工具面产出格式合规的正式 docx。

触发条件

"帮我写一篇关于 XX 的论文 / 期刊投稿"
"把这份研究整理成毕业论文第三章"
"写论文，格式按学校要求（页边距/字号/行距…）"

工作流（五步，不要跳步）

1. 大纲确认（必须先问）

用 ask_user_question 与用户确认：论文主题、目标章节结构（如摘要/ 引言/方法/实验/结论）、篇幅要求、是否有单位格式要求（页边距/字号/ 行距/页码/标题样式）。格式要求将映射进 content.format_spec—— 明确告诉用户"格式由引擎保证，正文不用手写编号"。

2. 分章起草（write_file 落盘）

逐章用 write_file 把草稿写成 markdown 落盘（如 <工作区>/paper/01-引言.md）。落盘而非直接输出——长文不占上下文，便于用户逐章修订后再汇编。

3. 文献准备

用户给了 .bib 内容/文件 → 先调 office_parse_bibtex 解析为结构化条目；
没有文献文件 → 把用户提供的文献手工整理成 references 条目（每条必有唯一 key，如 zhang2023）。
引用标记不要手写 [1]——在段落 citations 里填 key，引擎自动编号。
正文"如图 N 所示 / 见表 N"不要手编 N——写占位符 {{fig:图题注}} / {{tbl:表题注}}，生成时写成 Word 交叉引用域（更新域自动跟随题注重排；未匹配题注会生成失败并提示）。

4. 生成 docx（office_create 一次成形）

调 office_create（doc_type=word），content 结构：

{
  "title": "论文标题",
  "format_spec": {
    "page": {"size": "A4", "margins_cm": {"top": 2.5, "bottom": 2.5, "left": 3.0, "right": 3.0}},
    "body": {"font_size_pt": 12, "line_spacing": 1.5, "first_line_indent_cm": 0.74},
    "headings": {"h1": {"font_size_pt": 15, "bold": true}},
    "footer": {"page_number": true},
    "numbering": true,
    "toc": {},
    "figure_index": {},
    "table_index": {}
  },
  "metadata": {"author": "作者名", "keywords": "关键词1；关键词2"}
  "references": [{"key": "zhang2023", "ref_type": "journal", "title": "...", "authors": ["..."], "year": "2023", "source": "..."}],
  "citation_style": "gbt7714",
  "paragraphs": [
    {"text": "引言", "heading": "h1"},
    {"text": "如文献所述……", "citations": ["zhang2023"]}
  ]
}

要点：format_spec 只在用户明示格式要求时才细配；参考文献节自动生成，标题不要写"参考文献"段；标题文本不要手写编号（numbering 引擎生成）。 toc/figure_index/table_index 需要目录/插图清单/表格清单时才加；生成时在 office_create 带 refresh_toc: true（需本机 Word + pywin32），交付即真页码，无需手动更新域。

5. 自检与修复（交付前必做）

调 office_lint_word（file_path=生成的文档，format_spec 与第 4 步一致）。

样式/编号/题注类违规 → office_repair_word（同 format_spec）自动修复（默认写 -repaired.docx 新文件），修复后自动复检；
引用类违规（citation/coverage）不可自动修——补齐缺失引用标记或核对 references 后重新生成；
迭代直到 ok=true 或用户接受。

版式补充能力

标题层级支持 h1-h5（四级/五级标题编号 1.1.1.1 自动续排）
首页不同页眉页脚（封面页无页眉/不同页脚，first_page_different）
奇偶页页眉页脚（odd_even_pages，书籍排版场景）
横排分节（section_breaks：宽表格页单独横排，其余纵向）
目录域（toc）+ 真页码刷新：office_create 带 refresh_toc: true 或事后调 office_refresh_toc（Word COM）；无 Word 环境在 Word 里 Ctrl+A → F9 手动更新
图表目录（figure_index / table_index：插图清单/表格清单各占一页，收录 SEQ 题注；随刷新域一并得真页码）
交叉引用占位符（{{fig:题注}}/{{tbl:题注}} → REF 域，见第 2 步）
嵌入照片/扫描件 >8MB 时，本机装有 Pillow 会自动压缩到阈值内（pip install -r backend/requirements-optional.txt）；未安装则

10MB 的图会被拒绝，请先手工压缩

数据表附表（可选）

论文需要数据附表（问卷统计/实验数据）时，用 office_create（doc_type=excel）生成 xlsx：header_style 表头样式、freeze_header 冻结首行、 autofit_columns 自适应列宽、number_formats 数字格式（金额/百分比）、 conditional_formats 数据条/色阶、data_validations 下拉选项、 print_setup 打印横向单页宽——跟 Sage 说需求即可，无需手写格式。文档核心属性（作者/主题/关键词，metadata）与 Word 侧同款支持。

不做的事（YAGNI）

❌ 不自动下载文献全文（联网检索走 academic-search 技能，人工确认入库）
❌ 不预设期刊专用模板（编辑部模板场景走 office_analyze_word_template + office_fill_word_template，那是模板填充通路）
❌ 不替用户做学术判断（创新点/结论表述由用户确认）

paper-writing

About