AI Blog 改用 DeepSeek 官方並通用化提示詞
buildSystemPrompt 不再綁死太陽能行業，角色與公司資料改由 後台 ai_context_prompt / ai_business_context 提供；預設供應商 改為 https://api.deepseek.com 與 deepseek-flash。callChat 只在 baseUrl 含 deepseek.com 時加 thinking: { type: "disabled" }， 並將 max_tokens 提升至 4000，避免思考模式令 temperature 失效 同正文被截斷。 同步更新 schemas、seed、/admin/ai 預設值同 placeholder， 以及 AGENTS.md、spec、plan 文件。
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# 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` 預設值同步 |
|
||||
| `migrations/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 生效。
|
||||
Reference in New Issue
Block a user