══════════════════════════════════════════════════════════════
     作 品 介 紹
     名 稱 ： penink-ai · 以筆墨之力，解構人工智慧
     類 型 ： AI 全領域教學部落格 ＋ 內建 AI 助手
     線 上 ： https://wh-penink.pages.dev （原 WH-penink 網域）
     技 術 ： Astro / Tailwind CSS / JavaScript / TypeScript
     部 署 ： Cloudflare Pages（免費方案 ＋ Functions ＋ KV）
══════════════════════════════════════════════════════════════


一、這是什麼
──────────────────────────────────────────────────────────────
penink-ai（原 WH-penink）是一個專注於「AI 教學與開源實踐」的繁體中文部落格，
主題涵蓋大語言模型（LLM）、提示工程（Prompt Engineering）、
AI 繪圖（Stable Diffusion / ComfyUI / ControlNet）、AI Agent、
RAG 知識庫、本地部署（Ollama）、LoRA / QLoRA 微調等，共超過
25 篇教學文章。

它不只是一般的部落格，還內建了一位由本機開源模型驅動的
AI 助手「小墨」：

  主要功能
  ＊ 教學文章：分類完整，從入門到進階一次搞懂
  ＊ 精選文章：首頁重點曝光，快速進入主題
  ＊ AI 助手「小墨」：回答任何 AI 問題，也可針對單篇
    文章內容回答
  ＊ 開源作品展示：自動從 GitHub 同步作品與星數
  ＊ 全站與單頁瀏覽計數（Cloudflare KV 即時統計）
  ＊ 電子報訂閱：輸入信箱即可訂閱更新
  ＊ 管理後台：上傳／刪除作品、立即同步 GitHub

  設計風格
  以「筆墨」為意象的黑白對比 × 紫色強調色，支援淺色／深色
  兩種主題，手機與電腦皆友善顯示。


二、製作過程
──────────────────────────────────────────────────────────────
  開發流程
  1. 規劃架構
       決定用 Astro 靜態生成 ＋ Cloudflare Pages 免費托管，
       零伺服器成本、全球 CDN 加速。
  2. 建立設計系統
       先完成站點資訊與文章資料結構（site.ts），再以
       Tailwind 建好全站版面與元件（卡片、按鈕、提示詞卡）。
  3. 實作頁面
       首頁、文章總覽、作品牆、關於、聊天、管理後台等頁面，
       並撰寫文章內容與 SVG 封面。
  4. 接上 AI「小墨」
       Pages Functions 呼叫本機 Ollama 開源模型，做成 AI 客服；
       「小墨」的文章問答模式：推文章給它，它針對內容回答。
  5. 加上動態功能
       瀏覽計數：KV 記數，前端即時顯示；
       電子報：訂閱寫入 KV；
       作品同步：獨立 Worker 每小時掃描 GitHub repo
       （含去重、抓 og:image 預覽圖）。
  6. 測試與部署
       本機預覽、建置、上傳 Cloudflare Pages，實際網址驗證。

  技術筆記
  ・ Astro 靜態生成，SEO 友善、載入快。
  ・ Pages Functions 讓靜態站也能有 API 後端。
  ・ AI 走本機模型，資料不外送、不收集使用者個資。


三、使用教學
──────────────────────────────────────────────────────────────
  ① 閱讀文章
     首頁往下滑即可看到「精選文章」與「全部文章」，
     或到「文章總覽」依分類瀏覽（大語言模型 / 提示工程 /
     AI 繪圖 / AI Agent / 本地部署 / 程式開發…）。
  ② 逛逛開源作品
     首頁或「作品」頁可看到作者的所有開源專案，含 GitHub
     星數、說明與下載連結。
  ③ 問 AI「小墨」
     「開始跟小墨聊天」→ 直接輸入問題即可；想問特定文章的
     內容時，從文章頁把文章推給小墨，它會針對該篇文章回答。
  ④ 訂閱電子報
     在站內輸入 Email 訂閱，有新文章時即可收到通知。
  ⑤ 管理作品（管理員）
     到 /admin 輸入管理密碼，可上傳新作品、刪除作品、
     或按下「立即同步」讓網站即時抓取 GitHub 最新狀態。


四、注意事項
──────────────────────────────────────────────────────────────
  ＊ 本專案為公開教學內容，不含任何私密資料或金鑰。
  ＊ AI「小墨」由作者本機模型提供；若模型服務離線，
    聊天功能會暫時無法使用，不影響文章瀏覽。
  ＊ 瀏覽計數與訂閱資料存放於 Cloudflare KV，僅做統計用途。


五、保存資訊
──────────────────────────────────────────────────────────────
  本資料夾即專案原始碼（src 頁面、public 資產、functions
  後端、worker 同步程式、部署設定），可直接在本機執行：

      npm install         安裝相依套件
      npm run dev         本機開發 → http://localhost:4321
      npm run build       建置輸出至 dist/
      npm run preview     預覽建置結果

  線上正式版：https://wh-penink.pages.dev

══════════════════════════════════════════════════════════════
    文件完成 · 以上為公開資訊，不含任何私密資料
══════════════════════════════════════════════════════════════