feat(scaffold): redesign paper scaffold + clarify doc responsibilities

Scaffold (mytoolkit init paper): - default to portable Elsevier elsarticle [review,3p,11pt] (was ctexart/Fandol) - TeX Live Libertinus fonts (serif+math+mono), no system-font dependency - xelatex one-engine via latexmk; figure/abstract/keyword frontmatter - PDF bookmarks expand to two levels (bookmarksopenlevel=2) - fix diffpreamble.dtx: define \DIFadd/\DIFdel (latexdiff highlighted now compiles) Docs responsibility split: - CLAUDE.md owns design decisions/constraints; exact scaffold specs live only in the generated main.tex header (self-documenting, no drift) - README/SKILL point to those; README command table gains `voice` - reconcile source-of-truth wording across CLAUDE.md / README / SKILL
2026-06-29 00:47:48 +08:00
parent 587eac8837
commit f45b46073a
9 changed files with 93 additions and 60 deletions
@@ -83,4 +83,4 @@ mytoolkit templates list

 > **重要**：修改 `contrib/mytoolkit` 中的源码、或用 `git pull` / `git submodule update` 拉取更新后，**都必须重新执行 `make install`**（或 `mytoolkit update`）。Python 的 editable 安装不会自动跟踪源码改动，不重装则 CLI 调用的仍是旧版本。验证方式：`mytoolkit --version` 或 `which mytoolkit`。

-> **唯一真源**：mytoolkit 的具体用法、命令参数、模板说明以 **已安装的 mytoolkit 包** 为准。读取详细文档时，先运行 `mytoolkit info paths` 查看资源路径，或用 `mytoolkit info docs <name>` 直接打印参考文档。若 `mytoolkit` 命令不可用，可按默认开发路径 `~/workspace/contrib/mytoolkit/` 查找。本 skill 的 `references/` 仅作为速查补充。
+> **唯一真源**：mytoolkit 的具体用法、命令参数、模板说明以 **已安装的 mytoolkit 包** 为准（`mytoolkit info paths` 查路径、`mytoolkit info docs <name>` 打印参考文档）。**设计决策与仓库约定**（脚手架取舍、文档生成工作流、命名等）见仓库 `CLAUDE.md`。若 `mytoolkit` 命令不可用，可按默认开发路径 `~/workspace/contrib/mytoolkit/` 查找。本 skill 的 `references/` 仅作为 `info docs` 未覆盖命令的速查补充。
@@ -11,7 +11,7 @@ mytoolkit latex count paper.tex
 ## 论文脚手架 / 投稿模板

 ```bash
-mytoolkit init paper <dir>           # 新建论文项目（ctexart + Fandol 跨平台字体）
+mytoolkit init paper <dir>           # 新建论文项目（elsarticle 脚手架，xelatex，可移植；精确配置见生成的 main.tex 头部注释，设计约束见仓库 CLAUDE.md §3）
 mytoolkit init journal               # 列出投稿套件
 mytoolkit init journal elsevier      # Elsevier / ieee / springer 套件 → ./submit-<name>/
 ```
@@ -48,6 +48,7 @@ mytoolkit --help
 | `latex` | `compile` / `count` |
 | `bib` | `to-markdown` / `cv-update` |
 | `video` | `avi-to-mp4` |
+| `voice` | Text-to-speech via Volcengine/Doubao (`voice tts`, mp3/wav/pcm) |
 | `webpage` | Docusaurus build/list/rebuild/push |
 | `mail` | IMAP/SMTP client (read/draft/forward/reply, no auto-send) |
 | `templates` | Inspect template root; external override still possible |
@@ -81,7 +82,7 @@ Registry is stored at `~/.mytoolkit/templates.json` (or `$MYTOOLKIT_HOME/templat
 ## Project scaffolds

 ```bash
-mytoolkit init paper <dir>     # create a LaTeX paper project (ctexart + Fandol fonts)
+mytoolkit init paper <dir>     # create a LaTeX paper project (Elsevier elsarticle, xelatex, fully portable)
 ```

 This generates `main.tex`, `Makefile`, `references.bib`, `diffpreamble.dtx`, `figs/`, `analysis/`.
@@ -1,6 +1,12 @@
 # MyToolkit 项目配置

-> **唯一真源**：本文档是 `.claude/skills/mytoolkit/` 的唯一真源。mytoolkit 的功能、命令、模板、约定以本文档和 `README.md` 为准；修改 mytoolkit 时请同步更新本文档，skill 本身只保留触发词和简要分工。
+> **职责分工**（避免重复与漂移）：
+> - **参数/用法细节** → 已安装包的 `mytoolkit info docs <name>`（无 `info docs` 的命令看 skill `references/` 速查）为准；
+> - **设计决策与仓库约定**（文档生成工作流、脚手架/期刊套件取舍、命名、依赖、TTS 配置）→ **本文档**为准；
+> - **`README.md`** → 面向用户的 CLI 手册（安装、命令总表、config 文件）；
+> - **skill（`SKILL.md` + `references/`）** → Agent 路由层：触发词、与其他 skill 的分工、决策速查表，以及 `info docs` 未覆盖命令的薄速查。
+>
+> 改动 mytoolkit 的行为/命令/模板时，需**同步更新**受影响的：本文档、`README.md`、包内 `info docs`、skill `references/`。

 本项目是个人 CLI 工具集，命令入口为 `mytoolkit`。

@@ -22,13 +28,7 @@ Markdown 为唯一源格式，正式文档统一通过 `mytoolkit` 生成，不

 ### 例外：短文档直接手写 Word

-**审稿意见、评审意见**等 1-2 页的短文档，可直接复制对应 reference docx 模板到目标目录，在 Word 里直接撰写和修改。无需先写 Markdown 再转换。
-
- 模板路径：`mytoolkit/templates/md-to-docx/review/template.docx`（审稿/评审意见）
- 好处：省去转换步骤，用户可直接在 Word 中调整格式和内容
- 适用条件：单篇、无复杂版本控制需求、内容较短（通常 < 2 页）
-
-批量生成或需要版本控制时，仍回退到 Markdown → docx 工作流。
+审稿/评审意见等 1-2 页短文档，可直接复制 reference docx 模板 `mytoolkit/templates/md-to-docx/review/template.docx` 到目标目录，在 Word 内撰写，跳过 Markdown→convert。完整工作流策略（何时手写 vs 走 convert）见 workspace `CLAUDE.md §8`。

 ### 资源定位

@@ -75,10 +75,15 @@ mytoolkit voice tts "文本" -v zh_male_wennuanahu_moon_bigtts --format mp3 --sp
 ### 新建论文项目

 ```bash
-mytoolkit init paper <dir>        # ctexart + Fandol 跨平台中文字体；含 Makefile/diffpreamble/figs/analysis
+mytoolkit init paper <dir>        # 默认 Elsevier elsarticle 模板（全平台可移植）
 ```

-脚手架结构：`main.tex`（`\documentclass[UTF8, fontset=fandol]{ctexart}`）、`references.bib`（根目录）、`Makefile`（latexmk + xelatex，`make` 编译、`make highlighted OLDTEX=...` 出 latexdiff 修订稿）、`figs/`、`analysis/`。字体用 **Fandol**（随 TeX Live 自带，Mac/Win/Linux 编译一致），英文/公式用默认 Latin Modern。
+生成 `main.tex`/`Makefile`/`diffpreamble.dtx`/`references.bib`/`figs/`/`analysis/`。**精确配置（文档类选项、字号、字体、书签层级）以脚手架 `main.tex` 头部注释为准，本文档不复述以免漂移。**
+
+改脚手架时须保持的**设计约束**：
+- 文档类 **elsarticle**；正文+数学只用 **TeX Live 自带字体**（当前 Libertinus），**禁止写死系统/专有字体（如 Cambria）**，否则破坏可移植性；
+- 统一 **xelatex** 一个引擎（latexmk 驱动），便于后续加中文/系统字体；
+- `make` 编译、`make highlighted OLDTEX=...` 出 latexdiff 修订稿；`diffpreamble.dtx` 标记增删。

 ### 切换投稿期刊模板

@@ -8,11 +8,11 @@ OLDTEX ?= old.tex
 MAKELOG = $(OUTDIR)/make.log
 TEXLOG  = $(OUTDIR)/$(PROJECT).log
 ARTIFACTS = $(PROJECT).aux $(PROJECT).bbl $(PROJECT).blg $(PROJECT).log $(PROJECT).out \
-	$(PROJECT).toc $(PROJECT).synctex.gz $(PROJECT).fls $(PROJECT).fdb_latexmk $(PROJECT).xdv
+	$(PROJECT).toc $(PROJECT).synctex.gz $(PROJECT).fls $(PROJECT).fdb_latexmk $(PROJECT).xdv $(PROJECT).spl

 all:
 	@mkdir -p $(OUTDIR)
-	@echo "Compiling $(PROJECT).tex (full log: $(MAKELOG))..."
+	@echo "Compiling $(PROJECT).tex (xelatex, full log: $(MAKELOG))..."
 	@$(LATEXMK) -xelatex -outdir=$(OUTDIR) -interaction=nonstopmode $(PROJECT).tex < /dev/null > $(MAKELOG) 2>&1; \
 	status=$$?; \
 	if [ $$status -ne 0 ]; then \
@@ -1,38 +1,40 @@
-# 论文项目
+# Paper Project

-本项目由 `mytoolkit init paper` 初始化。
+This project was initialized with `mytoolkit init paper`. It uses the Elsevier
+`elsarticle` document class (bundled with TeX Live, default Computer Modern fonts,
+fully portable) and compiles with `xelatex` via `latexmk`.

-## 目录结构
+## Directory Structure

- `main.tex`：论文主文件
- `Makefile`：编译脚本
- `diffpreamble.dtx`：`latexdiff` 样式 preamble
- `references.bib`：参考文献
- `figs/`：图片
- `analysis/`：分析脚本与数据
- `build/`：编译输出（自动生成）
+- `main.tex`: main paper file
+- `Makefile`: build script
+- `diffpreamble.dtx`: `latexdiff` style preamble
+- `references.bib`: bibliography
+- `figs/`: figures
+- `analysis/`: analysis scripts and data
+- `build/`: build output (auto-generated)

-## 编译
+## Build

 ```bash
 make
 ```

-编译成功后生成 `main.pdf`。
+A successful build produces `main.pdf`.

-## 生成修订高亮稿
+## Generate a Revision-highlighted Draft

-把上一版论文 tex 备份为 `old.tex`（或任意路径），然后：
+Back up the previous version of the paper as `old.tex` (or any path), then:

 ```bash
-make highlighted              # 默认对比 old.tex
+make highlighted              # compares against old.tex by default
 make highlighted OLDTEX=path/to/prev.tex
 ```

-生成 `highlighted.tex`，编译后即为带修订标记的 PDF。
+This generates `highlighted.tex`; compiling it gives a PDF with revision marks.

-## 其他命令
+## Other Commands

- `make clean`：清理编译产物
- `make watch`：持续编译预览
- `make show-errors`：查看最近编译错误
+- `make clean`: remove build artifacts
+- `make watch`: continuous preview compilation
+- `make show-errors`: show the most recent build errors
@@ -1,7 +1,7 @@
 \RequirePackage[normalem]{ulem} %DIF PREAMBLE
-\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1} %DIF PREAMBLE
-\providecommand{\DIFaddtex}[1]{{\protect\color{red}{#1}}} %DIF PREAMBLE
-\providecommand{\DIFdeltex}[1]{}                                %DIF PREAMBLE
+\RequirePackage{color} %DIF PREAMBLE
+\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}} %DIF PREAMBLE
+\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}     %DIF PREAMBLE
 %DIF SAFE PREAMBLE %DIF PREAMBLE
 \providecommand{\DIFaddbegin}{} %DIF PREAMBLE
 \providecommand{\DIFaddend}{} %DIF PREAMBLE
@@ -1,52 +1,69 @@
-\documentclass[UTF8, fontset=fandol]{ctexart}
-\usepackage{amsmath, amssymb, amsfonts}
-\usepackage{geometry}
+%% Elsevier submission template (elsarticle.cls — bundled with TeX Live).
+%% Options: review (1.5 line spacing) | preprint | final | 1p/3p/5p | times | 10/11/12pt.
+\documentclass[review,3p,11pt]{elsarticle}
+
+\usepackage{amsmath,amssymb,amsfonts}
+\usepackage{libertinus}   % portable serif + matching math (TeX Live bundled)
 \usepackage{graphicx}
+\usepackage{lineno}
 \usepackage{hyperref}
-\usepackage[numbers]{natbib}
+% PDF outline expanded to two levels (section + subsection) by default.
+\hypersetup{bookmarksopen=true, bookmarksopenlevel=2}

-\geometry{a4paper, margin=2.5cm}
-
-\title{论文标题}
-\author{作者姓名}
-\date{\today}
+\journal{Journal Name}

 \begin{document}

-\maketitle
+\begin{frontmatter}
+
+\title{Paper Title}
+
+\author[inst1]{Zhengshou Lai}
+\ead{laizhengsh@mail.sysu.edu.cn}
+
+\affiliation[inst1]{organization={School of Civil Engineering, Sun Yat-sen University},
+    city={Zhuhai},
+    country={China}}

 \begin{abstract}
-在此撰写摘要。
+Write the abstract here.
 \end{abstract}

-\section{引言}
+\begin{keyword}
+keyword one \sep keyword two \sep keyword three
+\end{keyword}

-引言部分。
+\end{frontmatter}

-\section{方法}
+\section{Introduction}

-方法部分。可插入公式：
+Introduction section~\cite{example2024}.
+
+\section{Methods}
+
+Methods section. An equation can be inserted as follows:
 \begin{equation}
    \frac{\partial u}{\partial t} + \nabla \cdot \mathbf{F} = 0 .
 \end{equation}

-\section{结果与讨论}
+\section{Results and Discussion}

-结果部分。可按以下方式插入图片：
+Results section. A figure can be inserted as follows:
 %
 % \begin{figure}[htbp]
 %     \centering
 %     \includegraphics[width=0.8\textwidth]{figs/example.pdf}
-%     \caption{示例图片}
+%     \caption{Example figure}
 %     \label{fig:example}
 % \end{figure}
 %

-\section{结论}
+\section{Conclusions}

-结论部分。
+Conclusions section.

-\bibliographystyle{plainnat}
+%% Elsevier numbered style. Use elsarticle-harv for author-year.
+\bibliographystyle{elsarticle-num}
 \bibliography{references}

 \end{document}
@@ -1 +1,9 @@
-@comment{Placeholder bibliography file. Add BibTeX entries below.}
+@article{example2024,
+  title   = {An example reference},
+  author  = {Doe, Jane and Smith, John},
+  journal = {Journal of Examples},
+  volume  = {1},
+  number  = {1},
+  pages   = {1--10},
+  year    = {2024}
+}