mirror of https://github.com/openmlsys/openmlsys-zh.git synced 2026-10-29 03:24:10 +08:00

Files

Yeqi Huang 9be2fb30f7 feat: add Excalidraw diagram agent skill for book figures (#507 )

Add a project-level Agent Skill at .claude/skills/excalidraw-diagram
(symlinked from .agents/skills for other agents) that guides AI agents
to draw book figures with Excalidraw: editable .excalidraw source next
to exported SVG/PNG in v1/img/chNN, no PDF references, a palette that
stays legible on the dark-mode #e8e8e8 image backdrop, and separate
-zh variants for figures with text.

Adapted from github/awesome-copilot excalidraw-diagram-generator (MIT):
templates normalized to Excalifont and proper bound-text labels, plus a
stdlib-only check_figures.py linter for scenes and chapter image refs.
Document the skill in CONTRIBUTING_en.md and CONTRIBUTING_zh.md.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-26 02:11:55 +00:00

5.0 KiB

Raw Blame History

贡献指南

注意： 本项目的 v1 版本已归档（位于 v1/ 目录），不再接受新的贡献。请将所有内容贡献提交至 v2（v2/ 目录）。

仓库结构说明

openmlsys/
├── v2/                        # 第二版（当前活跃版本，接受贡献）
│   ├── zh_chapters/           # 中文章节源文件
│   │   ├── 00_chapter_preface/    # 各章目录（数字前缀 + 名称）
│   │   ├── 01_chapter_introduction/
│   │   ├── ...
│   │   ├── index.md           # 全书首页
│   │   └── SUMMARY.md         # 由脚本自动生成，勿手动编辑
│   ├── en_chapters/           # 英文章节源文件（结构与中文章节一致）
│   ├── config/
│   │   ├── en_config/         # 英文版 mdBook 配置
│   │   └── zh_config/         # 中文版 mdBook 配置
├── v1/                        # 第一版（已归档）
├── CONTRIBUTING/              # 贡献指南与相关文档
├── img/                       # 全书共享图片资源
├── references/                # 参考文献目录
├── tools/                     # 构建与预处理脚本
│   ├── prepare_mdbook.py      # 核心预处理：解析自定义语法、生成 SUMMARY
│   └── mdbook_preprocessor.py # mdBook 预处理器入口
└── build_mdbook_v2.sh         # v2 一键构建脚本

重要：SUMMARY.md 由 tools/prepare_mdbook_zh.py 根据 index.md 中的 toc 块自动生成，请勿手动修改。

环境准备

# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. 安装 mdBook
cargo install mdbook

# 3. 克隆仓库（需预先安装 Python 3）
git clone https://github.com/openmlsys/openmlsys.git
cd openmlsys

本地构建

构建 v2 中英文双版本

bash build_mdbook_v2.sh

构建产物输出至 .mdbook-v2-zh/book（中文）和 .mdbook-v2/book（英文）。

实时预览

# 中文版实时预览
cd v2/config/zh_config && mdbook serve --open
# 英文版实时预览
cd v2/config/en_config && mdbook serve --open

修改 zh_chapters/ 或 en_chapters/ 下的源文件后，浏览器将自动刷新。

注意：预处理脚本会在每次构建时重新生成 SUMMARY.md，如遇构建报错请先检查 index.md 中 toc 块的格式是否正确。

写作规范

详细的自定义语法（公式、图片标签、文献引用、代码块等）及图片规范，请参阅 写作样式规范。

使用 AI Agent 绘图（Excalidraw Skill）

仓库内置了项目级 Agent Skill .claude/skills/excalidraw-diagram/。 .agents/skills/excalidraw-diagram 是指向同一目录的符号链接。让 Claude Code 或其他支持 Agent Skills 格式的 Agent 为本书绘图时，它们会自动加载该 Skill。

该 Skill 要求 Agent：

将可编辑的 .excalidraw 源文件与导出的 SVG/PNG 一起放在 v1/img/ch<NN>/
为含文字的图另做 -zh 中文版本
使用在暗色模式下同样清晰的配色
不引用 PDF 图片

提交前可运行以下命令检查图片源文件与章节中的引用：

python3 .claude/skills/excalidraw-diagram/scripts/check_figures.py v1/img/ch06 v2/zh_chapters/06_chapter_training_systems/index.md

提交流程

Fork 本仓库并创建功能分支：

git checkout -b feat/chapter-xxx-section-yyy

本地构建验证：修改完成后运行 bash build_mdbook_v2.sh，确保无报错
提交代码：遵循语义化提交信息
```
git commit -m "feat(zh): 新增第X章第Y节内容"
git commit -m "feat(en): Add content for chapter X section Y"
git commit -m "ci: update main.yml"
```
常用前缀：feat（新内容）、fix（修正错误）、refactor（重组结构）、style（格式调整）、ci（构建流程更新）
发起 Pull Request：目标分支为 main，请使用 PR 模板：
- 中文 PR 模板
- 英文 PR 模板
代码审查：PR要求至少有一位非本人Contributor进行检查，且github action将会自动验证新增内容是否可以编译通过

常见问题

Q：如何添加新章节？

在 v2/zh_chapters/ 下新建 chapter_<名称>/ 目录
创建 index.md，在其中使用 toc 块列出各节
在全书 v2/zh_chapters/index.md 的 toc 块中注册新章节
确保本地构建通过后再提交 PR

Q：参考文献如何添加？

在 mlsys.bib 中添加 BibTeX 格式的文献条目，然后在正文中使用 :cite:key`` 引用。

Q：构建时提示找不到图片怎么处理？

检查图片路径是否以 ../img/ 开头（相对于章节目录），以及图片文件是否已提交至 img/ 目录。

5.0 KiB Raw Blame History Unescape Escape