# 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 生效。