diff --git a/.claude/skills/mytoolkit/SKILL.md b/.agents/skills/mytoolkit/SKILL.md similarity index 98% rename from .claude/skills/mytoolkit/SKILL.md rename to .agents/skills/mytoolkit/SKILL.md index 820018b..049973c 100644 --- a/.claude/skills/mytoolkit/SKILL.md +++ b/.agents/skills/mytoolkit/SKILL.md @@ -84,4 +84,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 ` 打印参考文档）。**设计决策与仓库约定**（脚手架取舍、文档生成工作流、命名等）见仓库 `CLAUDE.md`。若 `mytoolkit` 命令不可用，可按默认开发路径 `~/workspace/contrib/mytoolkit/` 查找。本 skill 的 `references/` 仅作为 `info docs` 未覆盖命令的速查补充。 +> **唯一真源**：mytoolkit 的具体用法、命令参数、模板说明以 **已安装的 mytoolkit 包** 为准（`mytoolkit info paths` 查路径、`mytoolkit info docs ` 打印参考文档）。**设计决策与仓库约定**（脚手架取舍、文档生成工作流、命名等）见仓库 `AGENTS.md`。若 `mytoolkit` 命令不可用，可按默认开发路径 `~/workspace/contrib/mytoolkit/` 查找。本 skill 的 `references/` 仅作为 `info docs` 未覆盖命令的速查补充。 diff --git a/.claude/skills/mytoolkit/references/bib.md b/.agents/skills/mytoolkit/references/bib.md similarity index 100% rename from .claude/skills/mytoolkit/references/bib.md rename to .agents/skills/mytoolkit/references/bib.md diff --git a/.claude/skills/mytoolkit/references/convert.md b/.agents/skills/mytoolkit/references/convert.md similarity index 100% rename from .claude/skills/mytoolkit/references/convert.md rename to .agents/skills/mytoolkit/references/convert.md diff --git a/.claude/skills/mytoolkit/references/image.md b/.agents/skills/mytoolkit/references/image.md similarity index 100% rename from .claude/skills/mytoolkit/references/image.md rename to .agents/skills/mytoolkit/references/image.md diff --git a/.claude/skills/mytoolkit/references/latex.md b/.agents/skills/mytoolkit/references/latex.md similarity index 55% rename from .claude/skills/mytoolkit/references/latex.md rename to .agents/skills/mytoolkit/references/latex.md index e86a854..b7ed9e4 100644 --- a/.claude/skills/mytoolkit/references/latex.md +++ b/.agents/skills/mytoolkit/references/latex.md @@ -11,9 +11,13 @@ mytoolkit latex count paper.tex ## 论文脚手架 / 投稿模板 ```bash -mytoolkit init paper # 新建论文项目（elsarticle 脚手架，xelatex，可移植；精确配置见生成的 main.tex 头部注释，设计约束见仓库 CLAUDE.md §3） +mytoolkit init paper # 新建论文项目（elsarticle 脚手架，xelatex，可移植；精确配置见生成的 main.tex 头部注释，设计约束见仓库 AGENTS.md §3） mytoolkit init journal # 列出投稿套件 mytoolkit init journal elsevier # Elsevier / ieee / springer 套件 → ./submit-/ ``` -投稿套件自带文档类与 bst，`make`（pdflatex+bibtex）直接编译；自动复用当前目录 `references.bib`。Springer 切样式只改 `\documentclass[...,sn-xxx]{sn-jnl}` 选项，勿写 `\bibliographystyle`。详见 CLAUDE.md §3。 +投稿套件自带文档类与 bst，`make`（pdflatex+bibtex）直接编译；自动复用当前目录 `references.bib`。Springer 切样式只改 `\documentclass[...,sn-xxx]{sn-jnl}` 选项，勿写 `\bibliographystyle`。详见 AGENTS.md §3。 + +### PDF 命名约定 + +脚手架默认输出 `main.pdf`，初始化后应将其重命名为简短、有意义的项目关键词。若目录采用 `lai2026-irregular-drag` 这类 `<作者><年份>-<关键词>` 形式，PDF 命名时应**去掉 `lai2026`/`liu2026` 等作者年份前缀**，只取后面关键词部分（如 `irregular-drag.pdf`）。也可在编译前把 `main.tex` 改为该目标名，让 `make` 直接生成目标 PDF，避免交付/归档时出现多个无区分的 `main.pdf`。 diff --git a/.claude/skills/mytoolkit/references/mail.md b/.agents/skills/mytoolkit/references/mail.md similarity index 100% rename from .claude/skills/mytoolkit/references/mail.md rename to .agents/skills/mytoolkit/references/mail.md diff --git a/.claude/skills/mytoolkit/references/others.md b/.agents/skills/mytoolkit/references/others.md similarity index 100% rename from .claude/skills/mytoolkit/references/others.md rename to .agents/skills/mytoolkit/references/others.md diff --git a/.claude/skills/mytoolkit/references/pdf.md b/.agents/skills/mytoolkit/references/pdf.md similarity index 100% rename from .claude/skills/mytoolkit/references/pdf.md rename to .agents/skills/mytoolkit/references/pdf.md diff --git a/.claude/skills/mytoolkit/references/video.md b/.agents/skills/mytoolkit/references/video.md similarity index 100% rename from .claude/skills/mytoolkit/references/video.md rename to .agents/skills/mytoolkit/references/video.md diff --git a/.claude/skills/mytoolkit/references/webpage.md b/.agents/skills/mytoolkit/references/webpage.md similarity index 100% rename from .claude/skills/mytoolkit/references/webpage.md rename to .agents/skills/mytoolkit/references/webpage.md diff --git a/.claude b/.claude new file mode 120000 index 0000000..c0ca468 --- /dev/null +++ b/.claude @@ -0,0 +1 @@ +.agents \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d8b3f4f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,133 @@ +# MyToolkit 项目配置 + +> **职责分工**（避免重复与漂移）： +> - **参数/用法细节** → 已安装包的 `mytoolkit info docs `（无 `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`。 + +--- + +## 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 模板 `mytoolkit/templates/md-to-docx/review/template.docx` 到目标目录，在 Word 内撰写，跳过 Markdown→convert。完整工作流策略（何时手写 vs 走 convert）见 workspace `CLAUDE.md §8`。 + +### 资源定位 + +模板、参考文档、项目脚手架都随 `mytoolkit` Python 包一起安装，不依赖仓库路径： + +```bash +mytoolkit info paths # 打印 package/templates/references/scaffolds 路径 +mytoolkit info docs convert # 打印 convert 完整参考文档 +``` + +skill 或其他脚本应通过上述命令定位资源，避免硬编码 `~/workspace/contrib/mytoolkit/`。 + +--- + +## 2. 配置管理 + +通过 `mytoolkit env` 管理，存储于 `~/.mytoolkit/config.json`（`keys.*` 格式）。 + +```bash +mytoolkit env set apikey_ark +mytoolkit env set volc_appid +mytoolkit env set volc_access_token +mytoolkit env list # 查看所有 key +mytoolkit env export # 导出为 shell export 语句 +``` + +本文件仅管理 mytoolkit 自身配置。Skill 脚本各自由其自身管理 API key（读取 `~/.xiaohe/agent/config.json`），与本配置独立。 + +## 3. 语音合成 (TTS) + +通过火山引擎（豆包）WebSocket API 实现，命令为 `mytoolkit voice tts`。 + +配置方式见上方 §2 配置管理。 + +### 用法 + +```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 = 正常） + +--- + +## 4. LaTeX 论文脚手架与投稿模板 + +### 新建论文项目 + +```bash +mytoolkit init paper # 默认 Elsevier elsarticle 模板（全平台可移植） +``` + +生成 `main.tex`/`Makefile`/`diffpreamble.dtx`/`references.bib`/`figs/`。**精确配置（文档类选项、字号、字体、书签层级）以脚手架 `main.tex` 头部注释为准，本文档不复述以免漂移。** + +改脚手架时须保持的**设计约束**： +- 文档类 **elsarticle**；正文+数学只用 **TeX Live 自带字体**（当前 Libertinus），**禁止写死系统/专有字体（如 Cambria）**，否则破坏可移植性； +- 统一 **xelatex** 一个引擎（latexmk 驱动），便于后续加中文/系统字体； +- `make` 编译、`make highlighted OLDTEX=...` 出 latexdiff 修订稿；`diffpreamble.dtx` 标记增删。 + +### 切换投稿期刊模板 + +各出版社“投稿套件”预置在包内 `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/`。 + +--- + +## 5. 依赖管理 + +项目使用 `uv` 管理依赖。修改 `pyproject.toml` 后运行 `uv sync` 同步。 + +```bash +uv sync +``` + +--- + +## 6. 命名规范 + +- **文件与文件夹**：英文统一使用 kebab-case，如 `review-comments.docx` +- **代码中的函数与变量**：统一使用 snake_case，如 `review_comments()` diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index d8b3f4f..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,133 +0,0 @@ -# MyToolkit 项目配置 - -> **职责分工**（避免重复与漂移）： -> - **参数/用法细节** → 已安装包的 `mytoolkit info docs `（无 `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`。 - ---- - -## 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 模板 `mytoolkit/templates/md-to-docx/review/template.docx` 到目标目录，在 Word 内撰写，跳过 Markdown→convert。完整工作流策略（何时手写 vs 走 convert）见 workspace `CLAUDE.md §8`。 - -### 资源定位 - -模板、参考文档、项目脚手架都随 `mytoolkit` Python 包一起安装，不依赖仓库路径： - -```bash -mytoolkit info paths # 打印 package/templates/references/scaffolds 路径 -mytoolkit info docs convert # 打印 convert 完整参考文档 -``` - -skill 或其他脚本应通过上述命令定位资源，避免硬编码 `~/workspace/contrib/mytoolkit/`。 - ---- - -## 2. 配置管理 - -通过 `mytoolkit env` 管理，存储于 `~/.mytoolkit/config.json`（`keys.*` 格式）。 - -```bash -mytoolkit env set apikey_ark -mytoolkit env set volc_appid -mytoolkit env set volc_access_token -mytoolkit env list # 查看所有 key -mytoolkit env export # 导出为 shell export 语句 -``` - -本文件仅管理 mytoolkit 自身配置。Skill 脚本各自由其自身管理 API key（读取 `~/.xiaohe/agent/config.json`），与本配置独立。 - -## 3. 语音合成 (TTS) - -通过火山引擎（豆包）WebSocket API 实现，命令为 `mytoolkit voice tts`。 - -配置方式见上方 §2 配置管理。 - -### 用法 - -```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 = 正常） - ---- - -## 4. LaTeX 论文脚手架与投稿模板 - -### 新建论文项目 - -```bash -mytoolkit init paper # 默认 Elsevier elsarticle 模板（全平台可移植） -``` - -生成 `main.tex`/`Makefile`/`diffpreamble.dtx`/`references.bib`/`figs/`。**精确配置（文档类选项、字号、字体、书签层级）以脚手架 `main.tex` 头部注释为准，本文档不复述以免漂移。** - -改脚手架时须保持的**设计约束**： -- 文档类 **elsarticle**；正文+数学只用 **TeX Live 自带字体**（当前 Libertinus），**禁止写死系统/专有字体（如 Cambria）**，否则破坏可移植性； -- 统一 **xelatex** 一个引擎（latexmk 驱动），便于后续加中文/系统字体； -- `make` 编译、`make highlighted OLDTEX=...` 出 latexdiff 修订稿；`diffpreamble.dtx` 标记增删。 - -### 切换投稿期刊模板 - -各出版社“投稿套件”预置在包内 `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/`。 - ---- - -## 5. 依赖管理 - -项目使用 `uv` 管理依赖。修改 `pyproject.toml` 后运行 `uv sync` 同步。 - -```bash -uv sync -``` - ---- - -## 6. 命名规范 - -- **文件与文件夹**：英文统一使用 kebab-case，如 `review-comments.docx` -- **代码中的函数与变量**：统一使用 snake_case，如 `review_comments()` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/Makefile b/Makefile index a365085..40097c0 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ help: @echo "Usage: make [target]" @echo "" @echo " install Install mytoolkit in editable mode (current Python) and sync skill" - @echo " sync-skill Copy the bundled Claude skill to ~/.claude/skills/mytoolkit/" + @echo " sync-skill Copy the bundled agent skill to ~/.agents/skills/mytoolkit/" @echo " uninstall Uninstall mytoolkit and remove shell completions" install: @@ -17,13 +17,13 @@ install: @$(MAKE) -s sync-skill sync-skill: - @echo "Syncing Claude skill to ~/.claude/skills/mytoolkit/ ..." - @mkdir -p "$(HOME)/.claude/skills" + @echo "Syncing agent skill to ~/.agents/skills/mytoolkit/ ..." + @mkdir -p "$(HOME)/.agents/skills" @if command -v rsync >/dev/null 2>&1; then \ - rsync -av --delete "$(ROOT_DIR)/.claude/skills/mytoolkit/" "$(HOME)/.claude/skills/mytoolkit/"; \ + rsync -av --delete "$(ROOT_DIR)/.agents/skills/mytoolkit/" "$(HOME)/.agents/skills/mytoolkit/"; \ else \ - rm -rf "$(HOME)/.claude/skills/mytoolkit"; \ - cp -R "$(ROOT_DIR)/.claude/skills/mytoolkit" "$(HOME)/.claude/skills/mytoolkit"; \ + rm -rf "$(HOME)/.agents/skills/mytoolkit"; \ + cp -R "$(ROOT_DIR)/.agents/skills/mytoolkit" "$(HOME)/.agents/skills/mytoolkit"; \ fi uninstall: diff --git a/README.md b/README.md index 34ca210..99075ce 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Personal CLI toolkit — unified entry point for everyday file conversion, forma ## Install ```bash -make install # install CLI + sync bundled Claude skill +make install # install CLI + sync bundled agent skill mytoolkit --version mytoolkit templates list # verify bundled templates are found ``` @@ -13,7 +13,7 @@ mytoolkit templates list # verify bundled templates are fou `make install` 会同时： 1. 用 editable 模式安装 `mytoolkit`； 2. 自动安装 zsh/bash 补全到当前 Python prefix 的共享目录； -3. 把 bundled Claude skill 同步到 `~/.claude/skills/mytoolkit/`。 +3. 把 bundled agent skill 同步到 `~/.agents/skills/mytoolkit/`。 补全由 `mytoolkit` 自己管理，无需手动写 `~/.local/bin/completions`，也无需在 `.zshrc` 里 `eval`。首次运行任意 `mytoolkit` 命令时会自动补齐；也可以手动检查状态：