GitHub 專案網站化與發布 SOP (github-repo-to-ijun-site)

核心操作準則 (Operating Rules)

在進行任何專案網站化與部署作業時，AI Agent 必須恪守以下嚴格規則，確保內容真實、視覺一致且不破壞既有站台架構：

真實本位 (Source of Truth)

以專案檔案為唯一依據

嚴禁捏造不存在的功能、示範連結、尚未發布的狀態或支援格式。撰寫文案前必須先完整檢視 README.md、SKILL.md、程式碼與圖片素材。

工作區隔離 (Preserve Changes)

保護工作區無關變更

Cloudflare Workers Assets 部署時會將整個 output/ 目錄打包發布。在執行部署指令前，必須向使用者展示無關的變更檔案並獲得確認。

視覺規範 (Visual Contract)

WayGround 視覺標竿

以 https://ijun-ai.com/exam/wayground-cli/ 為標準視覺範本。統一採用固定頁首導覽、色彩 CSS 變數（日/夜間模式）、卡片陰影與滿版 16:9 Hero 圖片。

圖片決策機制 (Image Choice)

缺少圖片時主動詢問

絕不隨意使用錯誤截圖作為主圖。當專案缺少合適視覺時，必須暫停並提供「三選一決策」讓使用者明確選擇，不可私自生成或替換。

主網站 10 大分類與路徑規範

所有子網頁一律放置於 output/<category>/<slug>/index.html，並透過二級相對路徑 ../../ 引用主站共用資源：

分類目錄 (Category)	公開網址路徑	適用情境與專案類型
命題工具	`/exam/<slug>/`	測驗、題庫匯入、自動化出題、評量診斷工具 (如 WayGround CLI)
國文教材	`/chinese/<slug>/`	國語文學習教材、字詞辨析、古典詩文互動課件
語文工具	`/lang/<slug>/`	語言學習、語音合成 (TTS)、語音克隆 (VoxCPM2) 等工具
課堂工具	`/class/<slug>/`	隨機抽籤、課堂計時器、分組座位表、即時互動看板
行政文件	`/staff/<slug>/`	公文排版、獎狀套印、研習證明、學校行政輔助腳本
班級經營	`/tutor/<slug>/`	導師班級事務、常規管理、學生個人化 IGP 填寫輔助
多媒體	`/media/<slug>/`	圖片處理、影片下載、字幕整理 (YouTube Transcript)
數位專案	`/app/<slug>/`	通用型數位專案、全端應用、客製化 Web App
研習教材	`/study/<slug>/`	教師研習講義、AI Agent 教學手冊、進階文件 Skill 說明
節慶互動	`/fun/<slug>/`	節慶主題遊戲、猜燈謎、校慶活動專屬小工具

相對路徑轉換規範

從二級分類頁面（例如 output/exam/wayground-cli/index.html）指向主站時，請嚴格使用相對路徑：
• 關於奕鈞老師：../../index.html#about
• 精選教學神器：../../index.html#tools
• 研習教材：../../index.html#materials
• 共用頭像素材：../../assets/gemini_trainer_profile1.png

7 大標準作業流程 (7-Step Workflow)

檢視與規劃 (Inspect & Plan)

確認主網站根目錄（包含 wrangler.toml 與 output/），讀取專案 README.md、腳本與範例。盤點現有圖片資源，依據專案類型提議適當的分類目錄與 URL Slug，並確認首頁歸屬（精選教學神器 或 研習教材，兩者不可重複放入）。

GitHub 建立後的 FB 貼文起草 (Facebook Post Draft)

GitHub Repo 建立後，獨立產出一份事實依據的 Facebook 社群貼文草稿。FB 貼文絕非官網文章的複製品：需採用自然的社群分享語氣、直接明確的標題（禁止使用問句作為主標）、僅描述有文件佐證的功能，並附上開源 GitHub 連結。禁止任何逼問留言、引導私訊或誇大行銷用語。

撰寫專案介紹文章 (Write Article)

重要規範：確保 GitHub 專案的 README.md 首行（或緊隨 # 主標題下方）包含以下固定宣告標註：

README.md 規範文字

由 [奕鈞老師](https://ijun-ai.com/) 製作 | [ijun-ai.com](https://ijun-ai.com/)

介紹文章需保持標題陳述句、段落層次清晰，並可依專案內容自由編排特色卡片、程式碼範例與操作指引。

建立子網頁 Subpage (Build Subpage)

將實體網頁存入 output/<category>/<slug>/index.html。當專案內缺少適合的展示圖片時，必須暫停並詢問使用者以下三選一決策：

選項 1：由 Agent 生成

AI 自動生成一張專屬 Hero 主圖，並放置於主標題與副標題下方（16:9 比例）。

選項 2：由使用者指定

使用者提供本機圖片完整路徑與擺放位置，AI 僅使用該圖，不額外生成。

選項 3：兩者皆是

上方使用使用者指定圖，並在頁尾專案連結區塊上方由 AI 生成一張補充示意圖。

縮圖與效能規範

生成的專案卡片縮圖必須包含：大字標題 + 核心操作介面 + 主要特色元素。
流程：生成 → 檢查文字清晰度 → 壓縮 → 驗證檔案大小（必須小於 500 KB）→ 放入目錄。

整合至主網站首頁 (Homepage Integration)

更新 output/data.json 中的資料項目，將 url 指向新上線的子網頁（如需要置頂於首頁，設定 showOnMain: true）。完成後在主站根目錄執行 Sitemap 產生腳本：

PowerShell / Terminal

python generate_sitemap.py

Cloudflare Workers Assets 部署 (Deploy)

僅在使用者明確要求部署時進行。必須在主網站根目錄執行，嚴禁在獨立子專案或建立獨立 Pages 專案：

PowerShell / Terminal

npx wrangler whoami
npx wrangler deploy

線上驗證與交接 (Verify & Completion)

部署完成後，透過 HTTP 請求確認線上頁面：

HTTP Status 回傳 200 OK。
標題、副標題、Hero 圖片、GitHub 連結均正確顯示。
導覽列連結能正確跳轉至主站對應錨點。
<head> 內包含正確的 <link rel="canonical" href="...">。
若有首頁更新，確認 https://ijun-ai.com/data.json 內容同步無誤。

完成度精確術語 (Completion Language)

在向使用者回報專案進度時，必須使用嚴謹的標準術語，絕不可將未驗證的草稿或本機檔案稱作「已完成」：

● Created locally 本機實體檔案已建立並通過結構檢查。
● Integrated locally 首頁 data.json 與 sitemap 已指向新頁面，但尚未部署上線。
● Deployed Cloudflare 已成功接收並發布 Assets。
● Verified live 線上公開網址與資料整合已完整檢驗通過。

標準子網頁 HTML 結構範本

可直接複製下方符合 WayGround 規範之標準子網頁骨架作為快速起手式：

標準子網頁範本 (index.html)

<!DOCTYPE html>
<html lang="zh-Hant-TW">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>專案名稱｜奕鈞老師</title>
  <meta name="description" content="專案一句話描述與特色介紹。">
  <link rel="canonical" href="https://ijun-ai.com/<category>/<slug>/">
  <!-- OpenGraph / Twitter Tags -->
  <meta property="og:title" content="專案名稱｜奕鈞老師">
  <meta property="og:description" content="專案一句話描述與特色介紹。">
  <meta property="og:url" content="https://ijun-ai.com/<category>/<slug>/">
  <meta property="og:image" content="https://ijun-ai.com/<category>/<slug>/share.png">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">
  <!-- 引入 WayGround 標準樣式 -->
</head>
<body>
  <!-- 頂部標準導覽列 -->
  <header>
    <div class="container nav-wrapper">
      <a href="../../index.html" class="logo"><span>IJUN</span><span class="logo-badge">AI</span></a>
      <button class="hamburger" id="hamburgerBtn" type="button">☰</button>
      <ul class="nav-menu" id="navMenu">
        <li><a href="../../index.html#about" class="nav-link">關於奕鈞老師</a></li>
        <li><a href="../../index.html#tools" class="nav-link">精選教學神器</a></li>
        <li><a href="../../index.html#materials" class="nav-link">研習教材</a></li>
        <li><a href="../../index.html#experience" class="nav-link">講師經歷</a></li>
        <li><a href="../../index.html#works" class="nav-link">投稿作品</a></li>
        <li><button class="theme-toggle" id="themeToggle" type="button">☾ 夜間模式</button></li>
        <li><a href="https://www.facebook.com/profile.php?id=61584090122881" target="_blank" rel="noopener noreferrer" class="yijun-fb-btn"><img src="../../assets/gemini_trainer_profile1.png" alt="奕鈞老師"><span>奕鈞老師 FB</span></a></li>
      </ul>
    </div>
  </header>

  <main class="container">
    <section class="hero">
      <div class="article-heading">
        <p class="eyebrow">PROJECT CATEGORY</p>
        <h1>專案完整名稱</h1>
        <p class="hero-subtitle">一句話總結核心價值與運作方式</p>
      </div>
      <figure class="hero-image">
        <img src="./hero.png" alt="專案核心操作介面圖">
      </figure>
    </section>

    <article class="article-content">
      <!-- 自由編排之專案內容、卡片、程式碼範例與連結 -->
    </article>
  </main>

  <footer class="site-footer">
    <p>由 <a href="https://ijun-ai.com/">奕鈞老師</a> 開發維護 ｜ <a href="https://ijun-ai.com/">ijun-ai.com</a></p>
  </footer>
</body>
</html>