jinze-lee/codex-skills-workbench/master-thesis-studio-skill

UTF-8 Reading Guard

Most instructions in this skill are Chinese and all Markdown/JSON files are UTF-8. If Chinese text appears garbled, do not edit or reason from the garbled output. Re-read files with an explicit UTF-8 command:

python -c "from pathlib import Path; import sys; sys.stdout.reconfigure(encoding='utf-8'); print(Path('SKILL.md').read_text(encoding='utf-8'))"

For short targeted reads, prefer Python over PowerShell Get-Content:

python -c "from pathlib import Path; p=Path('references/writing_workflow.md'); print(p.read_text(encoding='utf-8'))"

Load only the needed reference file. Do not bulk-read every Markdown file unless the task is a full Skill audit.

Activation Guard

This skill is opt-in only.

• Use this skill only if the current user message explicitly includes $master-thesis-studio-skill, or explicitly says to use the master-thesis-studio-skill / Master Thesis Studio skill.
• Do not use this skill merely because the user mentions a master's thesis, Southeast University, Word templates, .docx, academic writing, formatting, or document generation.
• If the user discusses thesis/Word work without explicitly opting in, answer normally or ask whether they want to use this skill; do not silently activate this workflow.

Master Thesis Studio

这是一个面向中文硕士论文写作与 Word 自动生成的显式调用 Skill。它把论文写作流程拆成两层：

1. 写作组织层：问诊、确认题目、大纲、章节计划、资产清单、写作边界和中文学术表达。
2. Word/XML 执行层：用内置脚本把 Markdown 写入 Flat OPC XML，再生成新的 DOCX。

除非用户明确要求快速演示，否则必须先确认项目事实和写作边界，再写正文或生成 Word。

总原则

• 所有新生成的论文标题、章节标题、正文、图题、表题、摘要、说明文字默认使用中文。英文只保留在模型名、算法名、指标名、数据集名、代码路径、文件名和必要术语中。
• 不编造真实文献、实验结果、样本量、指标或数据来源。没有依据时写“待补充”“待确认”或使用占位符。
• 不覆盖原始 Word 模板。原始模板固定保存在 01_template/original_template.docx。
• 模板来源可以是内置示例模板，也可以是用户上传或指定的 Word 模板。内置模板为 examples/Template.docx；用户模板支持 .docx 和 .dotx。
• 初始化时如果用户未指定模板，脚本默认使用 examples/Template.docx；如果用户提供模板路径，必须把该路径传给 --template。
• 新 DOCX 只写入 10_output/。XML 中间态只写入 09_state/。
• 创建新论文项目时，必须先新建一个独立项目文件夹，并把该文件夹作为论文项目根目录；不要直接在 Skill 根目录、工作区根目录或桌面散落运行初始化。
• 初始化和后续生成命令应在该论文项目文件夹内运行，项目参数使用 .；调用脚本时使用 Skill 中 scripts/ 的绝对路径，或明确从 Skill 根目录传入项目绝对路径。
• 用户提供已有 Word 时，先确认是否需要反解析。反解析是可选入口，不是必经流程；如果用户只想把该 Word 作为格式模板，可以只初始化模板，不抽取正文内容。
• 写回 Word 前必须检查章节 Markdown、占位符、参考文献、图表和状态文件是否一致。
• 修改占位符、XML 写回、参考文献或章节 Markdown 规则前，先阅读对应 references/ 文件。

第一次响应

第一次使用本 Skill 时，不要直接写论文。先用简短问题确认：

• 论文题目是否已确定，是否需要辅助拟题。
• 学科方向、研究对象、核心方法、创新点是否已确定。
• 当前阶段：未开始、已有想法、已有部分章节、已有完整初稿、只需格式化输出。
• 用户希望的模式：快速初稿、边确认边写、续写已有内容、根据代码/数据转写、只做 Word 写回。
• 已有资产：Word、Markdown、PDF、笔记、参考文献、代码、数据、图片、表格、公式、实验记录。
• 如果已有 Word：它是“格式模板”“已有论文内容”还是“两者都是”；是否希望反解析章节、图、表、公式到项目目录。
• 如果执行反解析：反解析后想做什么，例如只盘点资产、继续写作、修订润色、补缺失章节、重新导出 Word，或做 round-trip 校验。
• 是否允许模拟数据、示例图表或示例实验结果。不允许时只能基于用户材料写作。
• 使用哪个模板：内置东南大学风格示例 examples/Template.docx，还是用户上传/指定的 Word .docx 或 .dotx 模板。

确认结果必须同步写入：

• 00_project/project_manifest.md
• 00_project/thesis_master_index.md
• 00_project/decisions_log.md
• 09_state/project_state.json

阶段执行表

目录职责

• 00_project/project_manifest.md：项目事实、写作模式、用户状态、资产、缺失项和假设。
• 00_project/thesis_master_index.md：总大纲、章节状态、术语表、开放问题。
• 00_project/decisions_log.md：用户确认、重要假设、写作边界和变更记录。
• 03_chapters/：章节计划和章节正文 Markdown。
• 04_figures/figures_manifest.md：图片文件、图题、来源、章节映射、状态。
• 05_tables/tables_manifest.md：表格/数据来源、表题、章节映射、状态。
• 06_code/code_manifest.md：代码资产、可支撑的方法描述、实现细节和实验流程。
• 07_data/data_manifest.md：数据集、实验结果、指标、日志和可支撑结论。
• 08_refs/：参考文献、文献笔记、检索记录和引用元数据。
• 09_state/project_state.json：脚本写回使用的结构化项目状态。
• 09_state/current_working.xml：当前可生成 DOCX 的 Flat OPC XML。
• 09_state/reverse_parse_assets.json：可选反解析生成的真实图、表资源清单和可用性标记。
• 10_output/：最终生成的 DOCX。

何时阅读 References

• 需要问诊、选择写作模式、制定大纲、规划章节或写中文学术正文时，先读 references/writing_workflow.md。
• 需要使用或修改 [[FIG:...]]、[[TBL:...]]、[[EQ:...]]、[[SYM:...]]、[[REF:...]]、[[REF_FIG:...]]、[[REF_TBL:...]] 时，先读 references/placeholders.md。
• 需要处理参考文献格式、引用占位符、GB/T 7714 或 Word 交叉引用时，先读 references/reference_rules.md。
• 需要解析模板、反解析已有 Word、修改 XML 写回逻辑、处理标题样式、页眉页脚、分节符、图、表、公式或 DOCX 生成时，先读 references/xml_mapping_spec.md。
• 需要直接编辑 09_state/project_state.json 时，先读 assets/project_state.schema.json。

章节 Markdown 规范

文件命名

推荐命名：

• 03_chapters/ch01_plan.md
• 03_chapters/ch01_draft.md
• 03_chapters/ch02_plan.md
• 03_chapters/ch02_draft.md

兼容命名：

• 03_chapters/ch1_intro.md
• 03_chapters/ch2_literature.md
• 03_chapters/ch3_method.md
• 03_chapters/ch4_experiments.md
• 03_chapters/ch5_conclusion.md

scripts/apply_markdown_to_xml.py 的读取规则：

1. 优先读取 03_chapters/ch*_draft.md。
2. 如果没有 _draft.md，读取 03_chapters/ch*.md，但排除 *_plan.md。
3. 按文件名中的章节数字排序。
4. 根据 Markdown 的 #、##、### 重建一级、二级、三级标题结构。
5. 顶层 # 第X章 标题 只作为文件导航，写入 Word 时不会作为正文段落重复写入。

章节正文结构

新生成章节正文时使用中文标题，结构如下：

# 第1章 绪论
<!-- chapter_id: ch_1 -->
 
## 1.1 研究背景
 
这里写中文正文。正文应说明问题背景、研究意义和已有材料依据。
 
## 1.2 国内外研究现状
 
这里写中文正文。需要引用但暂无文献时，使用 [[REF:KEYWORD_PLACEHOLDER: 关键词]]。
 
### 1.2.1 某类方法
 
这里写三级小节正文。
 
## 1.3 本文主要工作
 
-使用中文列出本文工作。
-不写没有依据的实验指标。

章节 Markdown 的规则：

• 标题和正文默认中文。不要新生成 Chapter 1 Introduction 这类英文标题，除非用户明确要求英文论文。
• 二级标题使用 ##，三级标题使用 ###。不要在正文段落里伪造标题。
• 不要手写最终 Word 中的图号、表号、公式号或参考文献编号。
• 可以在 Markdown 中写 第1章、1.1 方便阅读；写入 Word 时默认去掉手动编号，避免模板自动编号重复。
• 已确认正文写入 chXX_draft.md。章节目标、素材、待补问题写入 chXX_plan.md，不要混在正文草稿里。
• 如果用户已有英文标题或英文草稿，先确认是翻译成中文还是保留原文。

占位符规范

写正文时使用这些占位符，不要硬编码编号：

• [[FIG:图的稳定描述]]：生成图片占位和图题。
• [[TBL:表的稳定描述]]：生成表题和真实 Word 表格。
• [[EQ:公式]]：生成显示公式和章内编号。
• [[SYM:公式或符号]]：生成行内数学符号。
• [[REF:n]]：生成参考文献交叉引用。
• [[REF:KEYWORD_PLACEHOLDER: 关键词]]：文献未补齐时的临时引用。
• [[REF_FIG:图的稳定描述]]：正文中引用图。
• [[REF_TBL:表的稳定描述]]：正文中引用表。
• [[CODE:路径或说明]]：标记代码资产需求。
• [[DATA:路径或说明]]：标记数据资产需求。

[[TABLE:...]]、[[FIGURE:...]]、[[EQUATION:...]] 可以被脚本兼容为 [[TBL:...]]、[[FIG:...]]、[[EQ:...]]，但新写内容必须使用标准形式。

写作模式

• 从零生成初稿：先读 references/writing_workflow.md，确认题目、方法、创新点、真实性边界，再生成大纲、计划和中文初稿。
• 边做边写：先写章节计划和资产 TODO，稳定章节可先写，实验结果、指标和图表缺失处标记待补。
• 续写已有论文：先确认是否反解析已有 Word。若用户同意，运行反解析并让用户查看 03_chapters/、04_figures/、05_tables/ 后，再决定续写、润色、补章节或导出。
• 资产转写论文：先读 06_code/、07_data/、04_figures/、05_tables/ 和 manifest，确认资产含义，再转写为方法、实验或结果分析。
• 格式整理与 Word 输出：先清洗 Markdown、规范占位符和引用，再执行 XML 写回、DOCX 生成和校验。
• 已有 Word 资产盘点：只抽取章节、图、表、公式和 manifest，不直接重写正文。适合用户想先了解已有论文可复用内容的情况。
• Round-trip 校验：反解析后再写回 Word，对比章节、图、表、公式和资源数量。适合验证模板兼容性或脚本改动。

模板选择

• 内置模板是 examples/Template.docx，文件格式是 Word .docx。它来自东南大学风格论文模板的改造版本。
• 用户可以改用自己的 Word 模板。支持 .docx 和 .dotx；不传 --template 时自动使用内置 examples/Template.docx。
• 如果用户上传了模板，先取得本机可访问的绝对路径，再运行初始化命令：python <skill_dir>/scripts/init_thesis_workspace.py . --template <user_template.docx>。
• 用户提供已有 Word 时，先区分它是“格式模板”还是“已有论文内容”。只作为格式模板时，用 --template 初始化；要抽取正文/图表/公式时，再使用 reverse_parse_docx.py。
• 初始化脚本会把选定模板复制到项目内的 01_template/original_template.docx，并把来源记录到 09_state/template_source.json 和 09_state/project_state.json。

写作要求

• 使用中文硕士论文语体：客观、克制、准确、逻辑清楚。
• 第一章和第二章优先依据 08_refs/、用户笔记和已有论文内容。
• 第三章优先依据代码、系统设计、算法流程、公式和用户确认的方法描述。
• 第四章优先依据真实数据、实验日志、指标表和图表。没有数据时不得编造结论。
• 第五章总结要与前文工作一致，不扩大贡献，不新增未出现的方法或实验。
• 术语必须一致。用户自定义模块名要写成“本文提出/设计/称为”，不要伪装成领域通用术语。
• 不确定内容要标记“待确认”或“待补充”，并记录到 00_project/project_manifest.md 或对应章节计划。

脚本命令

推荐流程：先创建一个新的论文项目文件夹，进入该文件夹，再运行初始化和后续命令。这样 00_project/、03_chapters/、10_output/ 等目录都会生成在这个项目文件夹里。

脚本需要 Python 包 lxml。如果当前 python 缺少 lxml，先改用已经安装 lxml 的 Python 解释器，或在目标解释器中安装 lxml 后再运行。

mkdir <project_dir>
cd <project_dir>
python <skill_dir>/scripts/init_thesis_workspace.py .

默认命令会使用内置 examples/Template.docx。如果用户选择自己的 Word 模板，传入用户模板路径：

python <skill_dir>/scripts/init_thesis_workspace.py . --template <user_template.docx>

如果用户提供的是已有论文内容，并且明确希望解析它，可以直接运行可选反解析入口：

python <skill_dir>/scripts/reverse_parse_docx.py <project_dir> --docx <user_thesis.docx>

反解析完成后先让用户选择下一步：只查看资产、继续写作、修订润色、补缺失章节、重新导出 Word，或执行 round-trip 校验。不要默认立刻重写全文。

在项目文件夹内运行时，项目参数使用 .，脚本路径使用 Skill 的绝对路径：

python <skill_dir>/scripts/flat_opc_converter.py toxml 01_template/original_template.docx 01_template/template.flat.xml
python <skill_dir>/scripts/parse_template_xml.py 01_template/template.flat.xml 09_state/parsed_structure.json
python <skill_dir>/scripts/generate_planning_files.py .
python <skill_dir>/scripts/apply_markdown_to_xml.py . --out 09_state/current_working.xml
python <skill_dir>/scripts/build_new_docx.py . --name thesis_draft_v1.docx
python <skill_dir>/scripts/validate_xml_docx.py .
python <skill_dir>/scripts/reference_tools.py format <refs.json> --style "GB/T 7714"

也可以在 Skill 根目录运行脚本，但必须把 <project_dir> 写成论文项目文件夹的绝对路径，不要省略项目路径。

可选命令：

python scripts/embed_figures_docx.py <input.docx> <output.docx> <figure1.svg> [figure2.svg ...]
python scripts/reverse_parse_docx.py <project_dir> --docx <user_thesis.docx>

不要直接运行 scripts/word_xml_core.py，它是公共脚本导入的内部 Word/XML 引擎。

Word 生成前检查

运行 apply_markdown_to_xml.py 前检查：