apaam/mytoolkit
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ce2d0ac5b0b7c1f5c7cc954d2d734e9473d789de
mytoolkit/AGENTS.md
T

7.4 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.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 的 ~/.xiaohe/agent/config.json 已迁移合并到本文件；xiaohe-agent 专属运行时偏好（如 default_agent、backend_provider、vps_*、workspace_root）保留在 ~/.xiaohe/agent/settings.json。xiaohe 通过 mytoolkit env CLI 读写 provider API key；myagents 作为纯 launcher 不触碰本文件。

3. 语音合成 (TTS)

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

配置方式见上方 §2 配置管理。

用法

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 脚手架与投稿模板

模板三分法（按用途，勿混放）：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 同步。

uv sync

测试

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