\r

latex-modular\r

\r

触发场景\r

\r

文件更新约束\r

\r

本技能的 .md 文件禁止使用 Write/Edit 工具更新。\r 必须用 scripts/ 下的 Python 脚本原子写入（tmp + os.replace()）。\r \r | 文件 | 更新方式 | 脚本 |\r |------|----------|--------|\r | SKILL.md frontmatter | Python 原子写入 | scripts/update_frontmatter.py |\r | SKILL.md 正文 | Python 直接重建 | scripts/safe_write.py 的 safe_write() |\r | scripts/components/*.txt | Python 写入 | scripts/component_manager.py |\r | references/*.md | scripts/safe_write.py | 随技能自带 |\r \r

• [把这段 LaTeX 做成模块化模板]\r
• [生成一个 LaTeX 文档，用模块化方式]\r
• [重构这个 LaTeX 代码进模块化体系]\r
• [提取 LaTeX 的组件，做成可复用模块]\r
• [用 latex-modular 生成一个...文档]\r
• [验证这段 LaTeX 能不能编译通过]\r \r 不触发：\r
• 用户只是问 [LaTeX 怎么写]——这是闲聊\r
• 用户要求直接编辑 .tex 文件而不使用模块化方式\r \r

核心能力\r

\r

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。\r \r

• extract 模式 — 从已有 LaTeX 代码中提取文档头、宏包、自定义命令、环境、样式，保存为可复用组件\r
• compose 模式 — 通过 Python 脚本按模块组合生成完整 LaTeX 文档，确保编译无错误\r
• refactor 模式 — 将原始 LaTeX 代码重构进模块化体系，保留原文语义，按模块拆分存储\r
• validate 模式 — 使用 lualatex 编译验证生成的 .tex 文件，报告错误并返回修复建议\r
• template 模式 — 模板库+自定义保存+内容注入。支持 --template 按名加载、--save-as 保存自定义模板、--content 注入正文、--list-templates 等，内置 article/report 两种预设模板（scripts/template.py + scripts/templates/）\r \r

渐进式文件索引\r

\r | 文件 | 位置 | 说明 |\r |------|------|------|\r | references/guide.md | 使用指南 | 完整使用指南（触发词、工作流程、输出格式） |\r | references/architecture.md | 架构说明 | 内部架构（组件分类、组合引擎、验证器） |\r | references/antipatterns.md | 反模式 | 常见 LaTeX 错误 + 正确做法 |\r | references/faq.md | FAQ | 常见问题解答（宏包冲突、字体问题、编译错误） |\r | references/changelog.md | 更新日志 | 版本更新记录 |\r | references/component-spec.md | 组件规范 | 命名、参数、依赖声明 |\r \r

脚本工具\r

\r | 脚本 | 功能 |\r |------|------|\r | scripts/compose.py | 模块组合引擎，按依赖顺序组合组件 |\r | scripts/extract.py | 从 LaTeX 源文件提取组件 |\r | scripts/validate.py | 编译验证，调用 lualatex 并检查输出 |\r | scripts/refactor.py | 重构引擎，将原始 LaTeX 转为模块化结构 |\r | scripts/template.py | 模板库管理：--template 加载、--save-as 保存、--content 注入、--list-templates 等 |\r | scripts/component_manager.py | 组件库管理（增删改查） |\r | scripts/safe_write.py | 原子写入工具（tmp + os.replace）|\r | scripts/update_frontmatter.py | 更新 SKILL.md frontmatter |\r \r

依赖\r

\r

• Python 3.11+（推荐 3.13.12 managed）\r
• lualatex（默认，推荐）：/c/Program Files/MiKTeX/miktex/bin/x64/lualatex\r
• 也可通过 --engine xelatex 切换为 xelatex\r
• 不推荐 pdflatex\r
• 首次编译时 MiKTeX 会自动安装缺失宏包，可能需要等待\r
• 中文字体依赖：SimSun、SimHei、KaiTi、FangSong（Windows 系统自带）\r \r

工作流程\r

\r

extract 模式（提取组件）\r

\r

1. 读取用户提供的 LaTeX 源文件\r
2. 解析文档结构：导言区（\documentclass 到 \begin{document}）、正文区\r
3. 提取组件并分类保存到 scripts/components/：\r
   • preamble/*.tex — 宏包引入、颜色定义、字体配置\r
   • environments/*.tex — 自定义环境（mylist、mycolumns 等）\r
   • commands/*.tex — 自定义命令（\ imu、\seeref 等）\r
   • styles/*.tex — 章节样式、目录样式、页眉页脚\r
   • tables/*.tex — 表格样式模板\r
   • graphics/*.tex — 图片插入模板\r
4. 生成组件索引 scripts/components/manifest.json\r \r

compose 模式（组合生成）\r

\r

1. 读取 scripts/components/manifest.json 获取可用组件列表\r
2. 根据用户需求选择所需组件\r
3. 调用 scripts/compose.py 按正确顺序组合：\r
   • 第1层：文档类声明\r
   • 第2层：宏包引入（自动去重）\r
   • 第3层：自定义命令和环境\r
   • 第4层：样式配置\r
   • 第5层：文档正文（用户提供）\r
4. 输出完整 .tex 文件\r \r

组件库结构\r

\r

scripts/components/\r
├── manifest.json          # 组件索引\r
├── preamble/              # 导言区组件\r
│   ├── class-settings.txt\r
│   └── packages.txt\r
├── environments/          # 自定义环境\r
│   ├── mylist.txt\r
│   ├── mycolumns.txt\r
│   └── abstract-env.txt\r
├── commands/              # 自定义命令\r
│   ├── title-commands.txt\r
│   └── background.txt\r
├── styles/                # 样式配置\r
│   ├── section-style.txt\r
│   ├── toc-style.txt\r
│   └── header-footer.txt\r
├── tables/                # 表格模板\r
│   └── table-style.txt\r
└── graphics/              # 图片模板\r
    └── figure-insert.txt\r
```\r
\r
### refactor 模式（重构）\r
\r
1. 读取原始 LaTeX 文件\r
2. 解析并提取各组件到 `scripts/components/` 对应目录\r
3. 生成模块化版本的主文档（使用 \\input{} 或 \\include{} 引入组件）\r
4. 验证重构后文档编译通过\r
\r
### validate 模式（编译验证）\r
\r
1. 调用 `scripts/validate.py`\r
2. 使用系统 lualatex 编译 .tex 文件\r
3. 捕获编译输出，解析错误和警告\r
4. 返回结构化报告：成功/失败、错误位置、修复建议\r