Zhengshou Lai
b49e2f7b38
- transcribe_flash 新增 api_key 参数：新版 X-Api-Key 单头鉴权， 无则回退旧版 X-Api-App-Key / X-Api-Access-Key 双头 - stt_cmd 优先读 secrets.api_keys.volc_tts，appid/token 降为回退 - _get_tts_credentials 更名 _get_voice_credentials（TTS/STT 共用）
180 lines
9.0 KiB
Markdown
180 lines
9.0 KiB
Markdown
# MyToolkit 项目配置
|
||
|
||
> **职责分工**（避免重复与漂移）：
|
||
> - **参数/用法细节** → 已安装包的 `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`。
|
||
|
||
---
|
||
|
||
## 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 `AGENTS.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`（`secrets.*`、`paths.*`、`connections.*`、`settings.*` 分层格式）。
|
||
|
||
```bash
|
||
mytoolkit env set secrets.api_keys.ark <key>
|
||
mytoolkit env set secrets.api_keys.volc_tts <api_key> # TTS/STT 新版 API Key（X-Api-Key，推荐）
|
||
mytoolkit env set secrets.volcengine.app_id <appid> # 旧版应用凭证（回退用）
|
||
mytoolkit env set secrets.volcengine.access_token <token>
|
||
mytoolkit env list # 查看所有 key
|
||
mytoolkit env export # 导出为 shell export 语句
|
||
```
|
||
|
||
本文件是 mytoolkit 与所有 skill 脚本的真源。旧版 `~/.xiaohe/agent/config.json` 中的工具类 key、账号、路径等已迁移合并到本文件；xiaohe-agent 专属运行时偏好（如 `default_agent`、`backend_provider`、`vps_*`、`workspace_root`）保留在 `~/.xiaohe/agent/settings.json`。xiaohe 的 provider API key 由 xiaohe 自己保存在 `~/.xiaohe/agent/secrets.json`，不经过 mytoolkit；`myagents` 作为纯 launcher 不触碰本文件。
|
||
|
||
## 3. 语音合成 (TTS)
|
||
|
||
通过火山引擎（豆包）API 实现，命令为 `mytoolkit voice tts`。TTS 优先用新版 **API Key**（`secrets.api_keys.volc_tts`，`X-Api-Key` 鉴权，HTTP 端点），旧版 `secrets.volcengine.app_id` / `access_token` 仅作回退。
|
||
|
||
配置方式见上方 §2 配置管理。
|
||
|
||
### 用法
|
||
|
||
```bash
|
||
mytoolkit voice tts "你好，世界"
|
||
mytoolkit voice tts -f script.txt
|
||
mytoolkit voice tts "文本" -v zh_female_xiaohe_uranus_bigtts --format mp3 --speed 10 -o output.mp3
|
||
```
|
||
|
||
可用音色：`zh_male_m191_uranus_bigtts`（经典男声）、`zh_female_xiaohe_uranus_bigtts`（经典女声，默认）、`ICL_uranus_zh_female_yuanqitianmei_tob`（阳光甜妹）
|
||
|
||
格式：`mp3`（默认）、`wav`、`pcm`
|
||
|
||
语速：`-50` 到 `100`（0 = 正常）
|
||
|
||
### 语音识别 (STT)
|
||
|
||
豆包录音文件识别极速版（flash ASR），STT 优先用新版 **API Key**（`secrets.api_keys.volc_tts`，`X-Api-Key` 鉴权，与 TTS 同一个 key），旧版 `secrets.volcengine.app_id` / `access_token` 仅作回退：
|
||
|
||
```bash
|
||
mytoolkit voice stt -i clip.webm
|
||
mytoolkit voice stt -i clip.wav -o out.txt
|
||
mytoolkit voice stt -i clip.wav --no-correct # 跳过大模型纠错
|
||
```
|
||
|
||
识别请求会带 ASR 原生热词（默认「小荷」）与可选对话上下文（`--history-file`）。`--correct` 可再开文本大模型兜底纠错（默认关闭）。webm / m4a 等会尽量经 `ffmpeg` 转 16 kHz mono wav。
|
||
|
||
---
|
||
|
||
## 4. LaTeX 脚手架与投稿模板
|
||
|
||
模板三分法（按用途，勿混放）：`templates/`（convert 转换模板，md 为源）/ `scaffolds/`（init 项目脚手架，LaTeX 源工程）/ `journals/`（init journal 投稿套件，自包含）。
|
||
|
||
### 新建论文项目
|
||
|
||
```bash
|
||
mytoolkit init paper <dir> # 默认 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` 标记增删。
|
||
|
||
### 新建手册项目（技术与使用文档）
|
||
|
||
```bash
|
||
mytoolkit init manual <dir> # LaTeX 手册模板（ctexart，xelatex）
|
||
```
|
||
|
||
与 Typst `md-to-pdf/manual` 模板同一视觉风格（封面 + 目录 + 彩色标题 + 四色提示框 + 代码高亮 + 三线表），**配色与版式改动须两个模板同步**。生成 `main.tex`/`Makefile`/`README.md`；字体用 `\IfFontExistsTF` 守卫引用 Times New Roman + SimSun/SimHei/KaiTi（公文风格，Office 自带），缺失时回落 ctex 自动字体集。交付型手册项目可进一步仿照 proposal 做法把字体文件放入项目 `fonts/` 自包含（注意字体授权，勿公开分发）。
|
||
|
||
### 切换投稿期刊模板
|
||
|
||
各出版社“投稿套件”预置在包内 `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` 同步。
|
||
|
||
### 本机安装（防串源）
|
||
|
||
真源检出：`xiaohe-agent/packages/mytoolkit`（submodule → `apaam/mytoolkit`）。
|
||
本机旁路克隆（如 `~/Documents/myBin/mytoolkit`）仅作备份，不要用来 `make install`。
|
||
|
||
```bash
|
||
cd <xiaohe-agent>/packages/mytoolkit && make install
|
||
# 或随 monorepo：cd <xiaohe-agent> && make update / ./setup.sh
|
||
python3 -m pip show mytoolkit | grep Editable
|
||
# 必须是 .../xiaohe-agent/packages/mytoolkit
|
||
```
|
||
|
||
- **禁止**在 `~/.xiaohe/actions-runner/_work/...` 里 `pip install -e`（会把 CLI 指到 ephemeral 树）
|
||
- `make install` 会拒绝上述 runner worktree
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
make test # 或 uv run pytest tests/ -q
|
||
```
|
||
|
||
- 第一层：CLI 冒烟（`tests/test_cli_smoke.py`）——所有命令 `--help` 必须退出码为 0，覆盖 import 链断裂/注册丢失。
|
||
- 第二层：纯逻辑单测（`config` / `templates_registry` / `md_to_pdf` 纯函数）。
|
||
- 不测外部 API（voice/image）与重型二进制真实调用；pandoc 相关用例用 `skipif` 保护。
|
||
- `tests/conftest.py` 在 import 前把 `MYTOOLKIT_HOME` 指向临时目录，测试永不触碰真实 `~/.mytoolkit`。
|
||
- 新增命令时必须保证冒烟测试通过；新纯函数优先补单测。
|
||
|
||
---
|
||
|
||
## 6. 命名规范
|
||
|
||
- **文件与文件夹**：英文统一使用 kebab-case，如 `review-comments.docx`
|
||
- **代码中的函数与变量**：统一使用 snake_case，如 `review_comments()`
|