國中數學幾何圖形技能（jh-math-geometry）

技能概覽

本技能生成適合試卷、簡報、教材的幾何 SVG 圖形，並輸出為 PNG 圖片檔， 可直接插入 Word 文件或 PowerPoint 投影片。

環境約定（任何使用前先做）：

• 腳本在本技能目錄（這份 SKILL.md 所在資料夾）的 scripts/，以 $GEOM_DIR 代表
• 產出一律放當前工作目錄的 output/geometry_output/
• Windows 若無 python3 指令請改用 python；Bash 片段請在 Git Bash／WSL 執行

GEOM_DIR="<本技能目錄的絕對路徑>/scripts"   # 例：~/.claude/skills/jh-math-geometry/scripts
mkdir -p output/geometry_output
python3 -m pip install -q cairosvg python-docx python-pptx   # 首次使用安裝一次；Linux 系統 Python 拒絕時加 --break-system-packages

處理流程

Step 1：理解需求

根據使用者的描述，判斷需要哪些圖形。若不確定，先快速確認：

• 哪個單元（三角形/四邊形/圓/立體...）？
• 需要標哪些字母/數字？
• 是否有特殊標記（直角符號、等邊刻度、角弧）？
• 輸出目標：Word、PPTX 或純圖片下載？

Step 2：建立圖形規格 JSON

依需求建立 spec，儲存至 output/geometry_spec.json：

{
  "figures": [
    {
      "id": "fig1",
      "type": "triangle",
      "config": {
        "subtype": "right",
        "vertex_labels": ["A", "B", "C"],
        "right_angle_at": "C",
        "side_labels": {"AB": "5", "BC": "3", "CA": "4"}
      },
      "canvas": {"width": 280, "height": 220}
    }
  ],
  "options": {"format": "png", "dpi": 150}
}

詳細參數見本技能目錄下的 references/figure-catalog.md（讀取該檔案）。

Step 3：執行渲染

python3 "$GEOM_DIR/geometry_renderer.py" output/geometry_spec.json output/geometry_output/
ls output/geometry_output/

Step 4：視覺確認

讀取產生的 .svg（或 .png）檔案確認圖形是否正確。 若有錯誤（標籤偏移、比例不佳），調整 config 後重新執行。

Step 5：輸出

純圖片

PNG 已在 output/geometry_output/<id>.png，直接告知使用者路徑。

插入 Word

python3 - <<EOF
from docx import Document
from docx.shared import Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH
import sys; sys.path.insert(0, "$GEOM_DIR")
from insert_to_docx import insert_figure, figures_from_manifest

doc = Document()   # 或 Document('existing.docx')
figures_from_manifest('output/geometry_output/manifest.json', doc, width_cm=7.0)
doc.save('output/geometry.docx')
print("✅ output/geometry.docx")
EOF

插入 PowerPoint

python3 - <<EOF
from pptx import Presentation
import sys; sys.path.insert(0, "$GEOM_DIR")
from insert_to_pptx import figures_from_manifest

prs = Presentation()   # 或 Presentation('existing.pptx')
figures_from_manifest('output/geometry_output/manifest.json', prs,
                      mode='individual', title_prefix='幾何圖形')
prs.save('output/geometry.pptx')
print("✅ output/geometry.pptx")
EOF

最後在對話中列出產出檔案的路徑。

被其他技能呼叫的標準流程

當 jh-math-exam 或 soil-teaching-deck 等技能需要幾何圖形時， 直接在那個技能的流程中插入以下步驟：

# 1. 找到腳本目錄：同 repo 的 skills/jh-math-geometry/scripts/，或已安裝的 jh-math-geometry 技能
GEOM_DIR=""
for d in "$SKILL_DIR/../jh-math-geometry/scripts" "$HOME/.claude/skills/jh-math-geometry/scripts" \
         "./skills/jh-math-geometry/scripts"; do
  [ -f "$d/geometry_renderer.py" ] && GEOM_DIR="$d" && break
done
python3 -m pip install -q cairosvg

# 2. 建立圖形 spec（Claude 根據題目需求自行決定內容）
mkdir -p output/geometry_output
cat > output/geometry_spec.json << 'SPEC'
{
  "figures": [
    {"id": "q3_fig", "type": "triangle", "config": {...}, "canvas": {"width":250,"height":200}}
  ],
  "options": {"format": "png", "dpi": 150}
}
SPEC

# 3. 渲染
python3 "$GEOM_DIR/geometry_renderer.py" output/geometry_spec.json output/geometry_output/

# 4. 取得 PNG 路徑供插入
FIGURE_PNG="output/geometry_output/q3_fig.png"

圖形類型速查表

標記系統

參考資料位置

以下路徑皆相對於本技能目錄：

注意事項

1. cairosvg 安裝：首次使用先 pip install cairosvg；Windows 裝不了 cairo 時，渲染器仍會輸出 SVG，可用 scripts/svgtoimage.py（Inkscape 備援）或 Edge headless（msedge --headless --screenshot=<out.png> file:///<abs.svg>）轉 PNG
2. 座標確認：讀取 .svg 確認後再插入文件
3. 畫布尺寸：試卷用圖建議 280×220；簡報用圖建議 360×280
4. 字體：SVG 使用 serif，匯出 PNG 後在 Word/PPTX 中外觀一致
5. 多圖批次：figures 陣列可一次放多個圖形，manifest.json 記錄所有輸出路徑