# MyToolkit 项目配置

> **唯一真源**：本文档是 `.claude/skills/mytoolkit/` 的唯一真源。mytoolkit 的功能、命令、模板、约定以本文档和 `README.md` 为准；修改 mytoolkit 时请同步更新本文档，skill 本身只保留触发词和简要分工。

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

---

## 1. 文档生成工作流

### 默认规则

Markdown 为唯一源格式，正式文档统一通过 `mytoolkit` 生成，不直接编辑 Word/PDF。

| 目标格式 | 命令 | 模板 |
|---------|------|------|
| PDF | `mytoolkit convert doc.md -o doc.pdf [-t cv/textbook/manual]` | `mytoolkit/templates/md-to-pdf/` (Typst) |
| Word | `mytoolkit convert doc.md -o doc.docx [-t default/review]` | `mytoolkit/templates/md-to-docx/` |

- `mytoolkit/templates/md-to-docx/` 含 `default/`（通用文档）和 `review/`（审稿意见）两个 reference docx 模板
- `mytoolkit/templates/md-to-pdf/` 为 Typst 模板目录，支撑 PDF 生成，直接修改模板需同步更新 mytoolkit

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

**审稿意见、评审意见**等 1-2 页的短文档，可直接复制对应 reference docx 模板到目标目录，在 Word 里直接撰写和修改。无需先写 Markdown 再转换。

- 模板路径：`mytoolkit/templates/md-to-docx/review/template.docx`（审稿/评审意见）
- 好处：省去转换步骤，用户可直接在 Word 中调整格式和内容
- 适用条件：单篇、无复杂版本控制需求、内容较短（通常 < 2 页）

批量生成或需要版本控制时，仍回退到 Markdown → docx 工作流。

### 资源定位

模板、参考文档、项目脚手架都随 `mytoolkit` Python 包一起安装，不依赖仓库路径：

```bash
mytoolkit info paths              # 打印 package/templates/references/scaffolds 路径
mytoolkit info docs convert       # 打印 convert 完整参考文档
```

skill 或其他脚本应通过上述命令定位资源，避免硬编码 `~/workspace/contrib/mytoolkit/`。

---

## 2. 语音合成 (TTS)

通过火山引擎（豆包）WebSocket API 实现，命令为 `mytoolkit voice tts`。

### 配置

```bash
mytoolkit env set volc_appid <appid>
mytoolkit env set volc_access_token <token>
```

### 用法

```bash
mytoolkit voice tts "你好，世界"
mytoolkit voice tts -f script.txt
mytoolkit voice tts "文本" -v zh_male_wennuanahu_moon_bigtts --format mp3 --speed 10 -o output.mp3
```

可用音色：`zh_female_cancan_mars_bigtts`、`zh_female_shuangkuaisisi_moon_bigtts`、`zh_male_wennuanahu_moon_bigtts`（默认）、`zh_male_sunwukong_moon_bigtts`

格式：`mp3`（默认）、`wav`、`pcm`

语速：`-50` 到 `100`（0 = 正常）

---

## 3. LaTeX 论文脚手架与投稿模板

### 新建论文项目

```bash
mytoolkit init paper <dir>        # ctexart + Fandol 跨平台中文字体；含 Makefile/diffpreamble/figs/analysis
```

脚手架结构：`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。

### 切换投稿期刊模板

各出版社“投稿套件”预置在包内 `mytoolkit/journals/`，一条命令落地到子目录，自包含、`make` 直接编译（pdflatex + bibtex）：

```bash
mytoolkit init journal               # 列出可用套件
mytoolkit init journal elsevier      # -> ./submit-elsevier/
mytoolkit init journal springer mydir
```

| 套件 | 文档类 | 类文件来源 |
|------|--------|-----------|
| `elsevier` | `elsarticle` | TeX Live 自带 |
| `ieee` | `IEEEtran` | TeX Live 自带 |
| `springer` | `sn-jnl` | 已随套件打包（含全部 `bst/` 样式） |

- 命令会**自动复用当前目录的 `references.bib`**（若存在）。
- 套件 Makefile 用 pdflatex（期刊惯例）；`BSTINPUTS` 已配好，Springer 的 `bst/` 子目录样式可直接找到。
- **Springer 注意**：参考文献样式由 `\documentclass[...,sn-mathphys-num]{sn-jnl}` 选项决定，**不要再写 `\bibliographystyle`**（重复会让 bibtex 报错）。
- 升级 `sn-jnl.cls`：从 Springer 官网下载最新 zip，替换 `mytoolkit/journals/springer/` 下的 `sn-jnl.cls` 与 `bst/`。

---

## 4. 依赖管理

项目使用 `uv` 管理依赖。修改 `pyproject.toml` 后运行 `uv sync` 同步。

```bash
uv sync
```

---

## 5. 命名规范

- **文件与文件夹**：英文统一使用 kebab-case，如 `review-comments.docx`
- **代码中的函数与变量**：统一使用 snake_case，如 `review_comments()`