yingfungsolar/docs/superpowers/specs/2026-09-12-ai-blog-template-deepseek-design.md

AI Blog 通用化（Template-ready）＋ 轉用 DeepSeek 官方 (Design Spec)

• 日期：2026-09-12
• 狀態：已與客戶確認方向
• 背景：本網站打算做成可重用 template，套用到唔同公司。但現時 AI Blog 嘅 system prompt 硬編碼咗「香港村屋太陽能公司『盈豐太陽能』」，只啱太陽能公司用。同時客戶想由 DeepInfra 轉用 DeepSeek 官方供應商。
• 本 spec 只涵蓋 AI Blog 生成；其他太陽能硬編碼內容（config.ts、其他 seed、前台文案）唔喺今次範圍。
• 相關：2026-09-11-structure-ai-deploy-design.md（AI Blog 原始設計）依然有效，本 spec 係其「通用化 + 供應商」修訂。

---

1. 目標與非目標

目標

1. 提示詞通用化：src/lib/ai.ts 嘅 buildSystemPrompt 唔再綁死任何行業／公司；角色同公司資料一律由後台設定提供，令同一套 code 可套用到任何行業。
2. 轉用 DeepSeek 官方：預設供應商改成 https://api.deepseek.com＋deepseek-flash，並處理 DeepSeek「思考模式預設開啟」對生成嘅影響。
3. 後台易輸入：/admin/ai 為公司背景同寫作風格加格式指引，令新公司開箱即用。

非目標 (Out of scope)

• 輸出格式維持 TITLE / CONTENT / META_DESC；唔加 SECTION、唔加 AI 封面圖（同原 spec 一致）。
• 關鍵字佇列、generate-next、Tavily 研究、供應商設定 UI 行為不變。
• 唔改關鍵字 discovery／排程生成（維持唔做）。
• config.ts、其他太陽能 seed 內容唔郁。

---

2. 提示詞模型（結構化欄位）

沿用現有「結構化欄位」做法（同 webtemplate 一致），唔引入完整可編輯 prompt 模板：

欄位	來源	角色
ai_context_prompt	後台	角色／寫作風格／語氣／目標受眾（可寫行業）
ai_business_context	後台	公司事實（grounding）：公司名稱／行業／業務範圍／主要地區／主要產品服務／目標客群／特色定位
（SEO/GEO 規則 + 輸出格式）	ai.ts code	通用、唔綁行業，維持穩定輸出

buildSystemPrompt 組合順序維持：contextPrompt → businessContext → research → 通用任務指示。

通用任務指示（取代原硬編碼角色）：

你係一位專業嘅 SEO 內容寫手。請根據上面嘅公司背景同寫作風格，
就以下主題寫一篇 800–1200 字嘅繁體中文（香港廣東話書面語）博客文章。
主題：<topic>
要求：
- 標題要放焦點關鍵字，首 100 字內再出現一次，關鍵字密度約 1–2%。
- 用 ## / ### 分段，段落清晰易讀。
- 開頭先畀一段總結（summary-first），再展開。
- 內容要實用、準確，符合公司業務；唔好作出未經證實嘅承諾或數字。
- 適合 SEO 同 AI 搜尋（GEO）：用問答式小標題、必要時用列表。
輸出格式（必須嚴格跟隨，唔要加額外說明）：
TITLE: <文章標題>
CONTENT:
<Markdown 正文，唔需要重複標題>
META_DESC: <160 字以內 SEO 描述>

語言維持「繁體中文（香港）」（本網站只做中文）；如需調整語言／語氣，經 ai_context_prompt 指定。

---

3. DeepSeek 供應商

3.1 預設值

Key	舊值	新值
ai_base_url	https://api.deepinfra.com/v1/openai	https://api.deepseek.com
ai_chat_model	deepseek-ai/DeepSeek-V3-0324	deepseek-flash

DeepSeek base URL 係 OpenAI 相容，現有 callChat 會自動接 /chat/completions，無需改 endpoint 邏輯。

模型選擇：deepseek-flash（DeepSeek-V4.1-Flash）——快、平、支援繁體中文，適合每日 SEO blog。後台仍可自行改為 deepseek-v4-pro 或其他供應商。

3.2 思考模式

DeepSeek 思考模式預設開啟（effort high），會令：temperature 失效、reasoning token 佔用 max_tokens（有機會正文被截斷）。

決策：生成時關閉思考模式。

• callChat 只在 baseUrl 含 deepseek.com 時加 thinking: { type: "disabled" }，保留 temperature: 0.7。
• 其他 OpenAI 相容供應商唔會收到非標準 thinking 參數，維持兼容。
• max_tokens 由 2200 提升到 4000（中文 800–1200 字連 Markdown 需要）。

3.3 現行已部署 D1

site_settings 由 DB 讀取，code 預設只在 key 缺失時生效。已部署 DB 仍有舊 deepinfra 值，處理方式：

• 部署後手動去 /admin/ai 改 Base URL＋模型；AI_API_KEY secret 換成 DeepSeek key（wrangler secret put AI_API_KEY）。
• 唔重跑 db:seed：seed 用 INSERT OR REPLACE，會覆蓋所有後台改過嘅設定。

---

4. 檔案改動

檔案	改動
src/lib/ai.ts	通用化 buildSystemPrompt；預設 baseUrl/model 改 DeepSeek；callChat 加 conditional thinking disabled、max_tokens: 4000
src/schemas/ai.ts	ai_base_url / ai_chat_model 預設值同步
scripts/seed.sql	ai_base_url / ai_chat_model 改預設；ai_business_context 改通用格式範本
src/pages/admin/ai.astro	模型／URL 預設值同步；公司背景＋寫作風格加 placeholder／格式說明
src/lib/AGENTS.md、根 AGENTS.md	更新 AI Blog 合約描述（DeepSeek 預設、通用提示詞）

---

5. 驗證

• npm run build（唯一 build 驗證）。
• npm run dev（:4321）：.dev.vars 填 DeepSeek AI_API_KEY → 登入 /admin/ai → 用通用公司背景 + 一個主題生成，確認：
  1. 草稿成功寫入並 redirect 去編輯頁；
  2. 唔再出現太陽能字眼（除非公司背景自己寫）；
  3. 無 timeout、正文完整（未被 max_tokens 截斷）。

---

6. 決策記錄

• 提示詞採「結構化欄位」而唔係完整可編輯 prompt 模板：保輸出格式穩定、最貼近 webtemplate、改動最少（YAGNI）。
• 模型預設 deepseek-flash：成本／速度平衡；deepseek-v4-pro 貴約 3–4 倍。
• 關閉思考模式：格式最穩定、最快、最便宜；temperature 生效。