apaam/mytoolkit
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
089da9763361883b9997348cab335ad1d5259dd5
mytoolkit/AGENTS.md
T
Zhengshou Lai 089da97633 install: refuse runner worktrees and bind the CLI Python. 
Keep editable installs on the canonical checkout so PATH mytoolkit cannot silently pick up a stale GHA _work tree.
2026-08-11 21:16:05 +08:00

8.8 KiB
Raw Blame History

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 包一起安装，不依赖仓库路径：

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.* 分层格式）。

mytoolkit env set secrets.api_keys.ark <key>
mytoolkit env set secrets.api_keys.volc_tts <api_key>   # TTS 新版 API Key（X-Api-Key）
mytoolkit env set secrets.volcengine.app_id <appid>      # STT 旧版应用凭证
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 配置管理。

用法

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 仍用旧版 secrets.volcengine.app_id / access_token（TTS 已改用 secrets.api_keys.volc_tts）：

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 投稿套件，自包含）。

新建论文项目

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 标记增删。

新建手册项目（技术与使用文档）

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）：

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 同步。

本机安装（防串源）

真源检出：~/Documents/myBin/mytoolkit（远程 apaam/mytoolkit）。

cd ~/Documents/myBin/mytoolkit && make install
python3 -m pip show mytoolkit | grep Editable
# 必须是 .../Documents/myBin/mytoolkit
  • 禁止在 ~/.xiaohe/actions-runner/_work/... 或任意 GHA worktree 里 pip install -e
  • 禁止把 xiaohe-agent/packages/mytoolkit submodule 当开发树安装（那只是 pin）
  • make install 会拒绝上述路径，并装进 PATH 上 mytoolkit 所用的 Python

测试

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()
Reference in New Issue View Git Blame Copy Permalink