Moelog AI Q&A Links WP Registry grade A. No security issues foundWP RegistryNo security issues foundOpen the reportA

Tested PHP: 8.3
Stable tag: 2.0.9 License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

🧠 Description

Moelog AI Q&A Links 會自動在你的文章或頁面結尾，加入一個互動式的 AI Q&A 問題清單。 當讀者點擊問題時，會開啟一個新分頁，從 OpenAI、Google Gemini 或 Anthropic Claude 獲取 AI 生成的答案。

這個回答頁面具備乾淨的 HTML 佈局、打字機動畫效果、內建的快取系統（包含靜態檔案），以及一個可選的 STM (結構化資料模式)，旨在幫助搜尋引擎和 AI 爬蟲更好地理解頁面內容。

展示頁面： 範例問題：GitHub是怎樣的一個網站?它的用途是什麼?
演示頁面：https://www.moelog.com/qna/qba-4cb-3257/

✨ Key Features

• 多供應商支援: 可串接 OpenAI (GPT-4o-mini 等)、Google Gemini (Gemini 2.5 Flash 等) 和 Anthropic Claude。
• 高度客製化: 可自訂系統提示 (System Prompt)、模型、溫度 (Temperature)。
• 智慧語言偵測: 內建規則自動偵測 (繁中/日文/英文)，無需 API。
• 雙層快取系統: 使用 WordPress Transients 和靜態 HTML 檔案雙層快取，大幅提升載入速度。
• 智慧預生成: 使用內容雜湊 (Content Hash) 偵測，僅在文章或問題變更時才重新生成答案，節省 API 成本。
• 後台管理介面:
  • 在文章編輯頁提供「AI 問題清單」Metabox。
  • 支援拖曳排序、新增/刪除問題、即時字數統計。
  • Gutenberg (區塊編輯器) 相容。
  • AJAX 「重新生成全部」 按鈕，可手動清除快取並觸發預生成。
• 路由與模板:
  • 使用 qna/slug-hash-id/ 的漂亮固定網址 (Pretty URL) 格式。
  • 使用 HMAC 雜湊確保 URL 安全，防止猜測。
  • 可自訂路由基底 (預設 qna) 與快取目錄名稱。
• Shortcode 支援:
  • [moelog_aiqna index="N"] - 在文章任意位置插入指定問題（index 範圍：1-8）。
  • 完整問題清單會自動附加在文章底部，已通過短碼顯示的問題會自動排除，避免重複。
• 安全性:
  • API 金鑰加密: 使用 AES-256-CBC 強加密演算法 (搭配隨機 IV) 儲存 API Key，金鑰源自 WordPress Salts。
  • 嚴格 CSP: 完整支援內容安全策略 (CSP)，所有內聯腳本/樣式均使用 nonce 驗證。
• 模組化架構: 程式碼清晰，易於維護 (Core / Router / Renderer / Cache / Metabox / AI_Client / Pregenerate)。
• 多語言支援: 內建繁體中文 (zh_TW)、英文 (en_US)、日文 (ja) 完整翻譯。
• 開發者文檔: 完整技術文檔 (docs/)，包含架構、API 參考、Hooks/Filters、STM 模式、國際化指南。

🚀 STM (Structured Data Mode)

STM 模式可協助搜尋引擎和 AI 爬蟲「解析」你的 AI 答案頁，此功能不保證索引或排名。

啟用時 (可選):

• SEO 標籤: 將 Robots 標籤設為 index, follow。
• Canonical: 加入 canonical 標籤，並指向原始文章 (關鍵 SEO 策略)。
• 結構化資料: 注入 QAPage (問答頁) 和 BreadcrumbList (麵包屑) 的 JSON-LD Schema。
• 快取標頭 (CDN 友善):
  • 輸出 Cache-Control (含 s-maxage, stale-while-revalidate)。
  • 輸出 Last-Modified 和 ETag 標頭。
  • 完整支援 304 Not Modified，大幅節省爬蟲預算與伺服器資源。
• Sitemap:
  • 產生 AI 問答專用的 Sitemap 索引與分頁 (ai-qa-sitemap.php)。
  • 使用 .php 結尾以避免與其他 SEO 外掛的 .xml 路由衝突。
  • 自動在 robots.txt 中宣告 Sitemap 位置。
  • 在發布文章時自動 ping Google 和 Bing。
• 爬蟲放行: 自動允許 Googlebot、Bingbot 等主流爬蟲存取。

停用時 (預設):

• SEO 標籤: 使用 noindex, nofollow 防止重複內容與爬蟲索引。
• 不 輸出 Schema、Sitemap 或 Ping。

🧩 Shortcodes

使用說明：

• 短碼用於在文章任意位置插入單一問題連結。
• 文章底部會自動附加完整的問題清單，已通過短碼顯示的問題會自動排除，避免重複顯示。
• 例如：使用 [moelog_aiqna index="1"] 在文章中間顯示問題 1，底部清單會自動只顯示問題 2、3 等。
• 注意： [moelog_aiqna]（無 index 參數）已移除，改為只支援單一問題模式，以簡化使用並避免與自動附加清單衝突。

🧮 Caching System

• TTL: 可在後台設定 1–365 天 (預設 30 天)。
• 機制: 結合 WordPress transient 和 wp-content/ 中的靜態 .html 檔案。
• 管理: 內建全域清除、或在文章編輯頁清除單篇快取。
• 標頭: 輸出 CDN 友善的 Cache-Control 標頭 (含 stale-while-revalidate)。
• 智慧生成: 使用內容雜湊偵測文章變更，僅在需要時重建快取。
• 快取佔位符: 靜態快取中的 CSP nonce 會被替換為 {{PLACEHOLDER}}，在讀取時才動態填入當次請求的 nonce，兼顧安全與效能。

⚙️ Performance & Stability

• 模組化架構: 核心邏輯分離 (Core, Router, Renderer, Cache, Metabox, Pregenerate, AI_Client)。
• 依賴管理: 透過 spl_autoload_register 自動載入類別。
• 生命週期: 嚴謹的啟用/停用/卸載流程。
  • 啟用: 智慧刷新固定網址 (Deferred Flush)，自動產生 HMAC 密鑰。
  • 升級: v1.8.3 自動遷移並加密舊的明文 API Key。
  • 卸載: 徹底清除所有 options, post_meta, transients 和靜態快取目錄。
• 相容性:
  • Sitemap 使用 .php 結尾，避免與主流 SEO 外掛 (Slim SEO, AIOSEO 等) 衝突。
  • Metabox 使用 MutationObserver 相容 Gutenberg 編輯器。
• 環境檢查: 啟用時檢查 PHP 版本，後台檢查 json, hash, mbstring 等擴充。

🔐 Security

• API Key 加密: 使用 AES-256-CBC 和 WordPress Salts 衍生金鑰，安全儲存 API Key。
• CSP & Nonce: 嚴格的內容安全策略 (CSP)，所有內聯腳本/樣式均使用 nonce 驗證。
• 安全輸出: 所有後台與前端輸出均經過 esc_html / esc_attr / wp_kses 嚴格過濾。
• URL 安全: 使用 HMAC 雜湊生成回答頁 URL，防止惡意枚舉或竄改。
• XSS 防護: AI 回答內容中的 HTML 被嚴格過濾，on... 事件被移除，連結 (URL) 會被轉換為無害的 <span> 標籤。
• 濫用防護: 內建 IP 基礎的頻率限制 (Rate Limiting)。
• IP 偵測: 預設只信任 REMOTE_ADDR。一般反向代理與 Cloudflare 必須分別設定可信 proxy CIDR；只有獨立的 Cloudflare 清單可授權 CF-Connecting-IP。
• 隱私友善限流: 僅以 WordPress site salt 產生的短期匿名雜湊進行限流與回饋去重，不將完整 IP 保存到回報郵件或傳送給 AI provider。

可信 proxy 可在 wp-config.php 設定；只應填寫實際直連 WordPress 主機且會清理轉送標頭的 proxy/CDN 網段：

define('MOELOG_AIQNA_TRUSTED_PROXIES', [
    '10.0.0.0/8',
    '2001:db8:ffff::/48',
]);

💬 Privacy

本外掛只會將以下資料傳送給 AI 服務供應商 (OpenAI / Gemini / Claude)：

• 由網站作者在後台預設的問題。
• (可選) 如果勾選「包含文章內容」，則會傳送原文內容作為上下文。
• 系統提示 (System Prompt) 和語言設定。

不會將訪客 IP、User-Agent 或其他訪客個人資料傳送給 AI provider。為防止公開端點濫用，站點本地會短期保存由 IP 與 WordPress site salt 產生、不可直接還原 IP 的匿名識別與限流計數。所有 AI provider 通訊均透過 HTTPS。

🧩 Changelog

2.0.9 (2026-07-30) – 回饋統計修復

• 📊 修復: 觀看、好評、差評次數不再歸零。原本清除或過期靜態 HTML 快取時（包含每次儲存文章都會觸發的自動清除）會連帶刪掉累積的統計數據。
• 🧹 孤兒清理: 改為比對每篇文章目前的問題清單來判定殘留統計，不再依賴快取檔案是否存在；只有真正被移除的問題才會清理。
• 👁️ 觀看去重: 移除瀏覽器端永久 localStorage 標記，改由後端 24 小時視窗單獨負責，管理員清除統計後對既有訪客立即生效。
• 🔄 重置可靠性: 清除所有回饋統計改用世代計數器讓去重 key 失效，在 persistent object cache（Redis／Memcached）環境同樣有效。
• 🖼️ 顯示: 靜態頁不再烙印過期數字，避免先顯示舊值再更正的閃動。

2.0.8 (2026-07-17) – Milestone B 完善

• 🔒 代理信任: CF-Connecting-IP 改由獨立 Cloudflare／CDN CIDR 清單授權；一般 trusted proxy 即使收到偽造的 Cloudflare 標頭也只依可信 XFF chain 解析。
• 🚦 Feedback 限流: transient 滑動視窗改為固定視窗與資料庫原子遞增，提供可觀察狀態 hook；拒絕時回傳 HTTP 429 與 Retry-After。
• 🧹 快取維護: 升級 migration 不再加密 index.html，並會修復既有誤加密控制檔；卸載清理安全支援大小寫、底線與點的自訂快取目錄。
• 📝 Metadata: 修正 lifecycle 類別的 @since 版本標記。

2.0.7 (2026-07-17) – 緊急修復

• 🐛 修復: 當其他外掛或佈景先載入舊版 Parsedown（1.7 之前，無 setSafeMode()）時，答案頁會發生 fatal error。內建解析器已改用外掛專屬類別名稱（Moelog_AIQnA_Parsedown），不再與外部同名類別衝突。

2.0.6 (2026-07-17) – 正確性與穩定性

• 🔄 更新器: GitHub 更新只接受精確命名的 Release ZIP asset，不再退回原始碼壓縮檔。
• ⚙️ 設定: 自訂 URL 前綴（pretty_base）與快取目錄（static_dir）現在確實生效；舊版 wp-config 常數仍可作為最高優先覆蓋。
• 🔐 靜態快取: 頁面內容以 AES-256-GCM 加密，Nginx／Caddy／IIS 即使直接回傳快取檔也不會洩漏 HTML；遭竄改或舊版明文檔案一律不輸出。
• 🧬 快取指紋: 答案快取與頁面快取分層版本化——版面或模板變更只免費重新渲染，不會觸發付費 AI 重生成。
• 💰 費用控管: 全站每日／每月 AI 產生額度（預設 100／2000，0 為不限制）、同題併發鎖，以及可設定的最大輸出 tokens（預設 2048）。
• 🚦 可用性: 暫時性容量與 provider 錯誤改回 HTTP 503 並附 Retry-After，不再回 500。
• 🧩 Provider: 結構化回傳結果——錯誤文字不再可能被寫入答案快取，翻譯檔變更也不影響成敗判定。
• 🤖 Anthropic: 新安裝預設模型改為 claude-opus-4-8；已保存的模型設定不會被改寫。
• 🧹 生命週期: 停用時清除所有排程事件；卸載時以 allowlist 方式清除 options、文章 meta、transients、額度計數、鎖及追蹤過的快取目錄。
• ✅ CI: GitHub Actions 品質矩陣（PHP 7.4–8.5）、wp-env WordPress 整合測試，以及版本一致性 gate 與 draft release 流程。

2.0.5 (2026-07-16) – 自動更新

• ✨ 新增: 透過 GitHub Releases 自動更新(內附 Plugin Update Checker 5.6,MIT 授權);優先下載 Release 的發布包 asset,而非原始碼壓縮檔。
• ✨ 新增: moelog_aiqna_questions_block_html filter,佈景可自訂問題清單容器標記,不必修改外掛檔案,客製化不再被自動更新洗掉。

2.0.4 (2026-07-16) – 安全性修補

• 🔒 公開政策: 非公開、密碼保護、不存在文章及無效答案 token 採一致 404，且在讀取問題、快取或呼叫 AI 前拒絕。
• 🔒 靜態快取: Apache cache 目錄禁止直接 HTTP 存取，既有 .htaccess 會自動安全升級；正常答案 URL 仍由 PHP 輸出。
• 🔒 可信代理: 預設只信任 REMOTE_ADDR，只有明確設定的 proxy CIDR 才解析 Cloudflare／X-Forwarded-For。
• 🔒 回饋端點: 伺服器驗證公開文章與實際問題、重算 hash，並加入 view/vote/report 基本限流與重送防護。
• 🔑 Gemini: API key 改由 x-goog-api-key header 傳送，不再出現在 request URL。
• 🤖 Anthropic: Opus 4.7／4.8、Sonnet 5 與未知模型採保守參數集合，不再以模型名稱 regex 猜測 sampling 能力。
• ℹ️ Anthropic alias: 浮動 *-latest alias 視為未知模型，預設省略 temperature；經站點 contract test 後可用 filter 明確允許。
• ℹ️ 相容性: 不修改既有公開答案 URL，也不自動改寫使用者已保存的 model ID。

2.0.3 (2026-05-08) – 結構化資料修正

• 🐛 修正: QAPage Schema 缺少 Google Search Console 標示的建議欄位：於 acceptedAnswer 補上 upvoteCount 與 url；於 mainEntity（Question）補上 author 與 datePublished；於 acceptedAnswer.author 補上 url。

2.0.2 (2026-04-21) – 錯誤修正 & 維護更新

• 🐛 修正: Anthropic 預設模型 ID 日期後綴錯誤，並升級至最新 claude-opus-4-7。
• 🐛 修正: is_error_message() 中 Gemini 和 Anthropic 的已知錯誤訊息與實際回傳字串不符，導致錯誤訊息可能被寫入靜態快取。
• 🐛 修正: 靜態快取在每次讀取時會呼叫 touch() 重置 mtime，導致快取永遠不會過期。已移除 touch() 呼叫，快取 TTL 現在可正常運作。
• 🐛 修正: 版本遷移函數 moelog_aiqna_check_upgrade() 的執行順序錯誤（1.8.3 先於 1.8.0），導致新安裝時 1.8.0 的 TTL 初始化遷移被跳過。
• 🐛 修正: moelog_aiqna_clear_route_cache() 實際上無法清除 PHP static 變數快取。改用 $reset 參數機制，現在可真正重置 pretty_base 和 static_dir 的快取值。
• ✨ 新功能: 在「顯示設定」分頁新增「顯示問題區塊」開關（對應 block_enabled 設定，原本只能透過程式碼控制）。
• 🔧 更新: Gemini API 端點從實驗性的 v1beta 升級為穩定版 v1。
• 🔧 修正: 建立快取目錄時，.htaccess 保護檔案不再包含多餘的前導空白。

2.0.1 (2026-02-19) – Layout Refinement & Custom Banner

• 🎨 版面優化: 以純 CSS 取代背景圖片，實現精確的白邊、間距與圓角控制。
• 🎨 字體統一: 內文、列表、標題全面改用 px 固定字體大小，手機/平板響應式同步更新。
• 🖼️ 自訂 Banner: 新增後台上傳功能，可透過 WordPress 媒體庫選擇自訂 Banner（建議 880 × 240 px）。
• 🐛 修正: 補回因重構遺漏的 answer.js script 標籤。
• 🌍 國際化: 補充自訂 Banner 相關字串的英文 (en_US) 與日文 (ja) 翻譯。

2.0.0 (2026-02-18) – Major UI Overhaul & CSS Refinement

• 📝 Markdown 支援: 引入 Parsedown，在答案渲染前正確轉換 Markdown。
• 🎨 樣式修正: 修正回答頁的CSS，配合 Markdown 的內容。
• 🎨 UI 重新設計: 後台管理介面採用素雅風格設計。

1.10.2 (2025-11-28) – 錯誤修正 & 改進

• 🐛 修正: 刪除快取檔案後，快取統計立即更新（不再顯示舊數據）。
• 🐛 修正: STM (結構化資料模式) 設定不再因儲存其他分頁而被重置。
• 🔒 安全: 問題回報功能新增防濫用機制（IP 頻率限制、蜜罐欄位、字數限制）。
• ✨ 新功能: 新增「回饋功能」開關，可在後台顯示設定中啟用/停用互動回饋。
• ✨ 新功能: 新增「清除所有回饋統計」按鈕，可一鍵刪除所有瀏覽/好評/差評數據。
• 🎨 UI: 移除系統資訊頁面中重複的快取統計區塊。
• ⚡ 效能: 快取管理頁面現在始終顯示即時統計。
• 🌍 國際化: 新增完整語言包支援（繁體中文 zh_TW、英文 en_US、日文 ja）。
• 📚 文檔: 新增技術文檔 docs/ 目錄，包含架構、API、Hooks、STM 模式、國際化等 8 份技術文件。

1.10.1 (2025-11-26) – PHP 8.x 相容性 & 程式碼品質

• 🐘 PHP 8.x 相容性: 完整支援 PHP 8.0, 8.1, 8.2, 8.3。
• 🔧 修正: preg_replace(), json_decode(), trim(), parse_url() null 處理。
• 🎨 UI 優化: 為所有後台區段標題添加統一的 Emoji 圖示。
• 🎨 UI 優化: 移除多餘的 <hr> 分隔線，版面更整潔。
• 🔒 安全性: 增強主插件實例的單例模式實作。
• ⚡ 效能: 為沒有持久物件快取的環境添加 transient 頻率限制備援。

🧭 Support

Bug reports & feature suggestions:
🌐 Official site: https://www.moelog.com/
💻 GitHub: https://github.com/Horlicks-p/moelog-ai-qna-links

🧩 License

This plugin is licensed under GPL v2 or later. You are free to modify and redistribute it. © 2025