feat(automation): 添加 RAG 数据自动更新工作流和状态管理

- 创建 GitHub Actions 工作流实现博客内容变更后自动更新向量数据库
- 引入 .ingest_state.json 文件记录处理状态实现增量更新
- 更新相关文档说明自动化流程和配置要求
- 优化聊天框 API 请求错误处理逻辑

Author: hobbytp

docs/PRD/PRD-基于RAG的博客数字分身助手-v1.1.md

@@ -45,24 +45,9 @@ sequenceDiagram
 文件位置：/scripts/ingest.py
 
 * **环境依赖**：requests, python-frontmatter (需生成 requirements.txt)  
-* **鉴权配置**：脚本需读取环境变量 CLOUDFLARE\_ACCOUNT\_ID 和 CLOUDFLARE\_API\_TOKEN（注意：CF\_ 前缀已弃用，需使用 CLOUDFLARE\_ 前缀）。  
-* **处理逻辑**：  
-  1. **解析 Frontmatter**：遍历 content/posts/\*.md，提取 title, date, url (slug)。  
-  2. **文本切片 (Chunking)**：  
-     * 清洗 Markdown 符号 (去除图片、粗体标记等)。  
-     * 长度控制：约 500 字符/chunk，重叠 50 字符。  
-  3. **生成确定性 ID (关键)**：  
-     * **ID 生成规则**：md5(full\_url \+ chunk\_index)。  
-     * **目的**：实现幂等性。如果文章内容未变，重新运行脚本时，生成的向量 ID 不变，Cloudflare 会执行 Upsert (覆盖) 而不是 Insert (新增)，防止数据库产生重复脏数据。  
-  4. **向量化与存储**：  
-     * 调用 Cloudflare Workers AI REST API 生成向量。  
-     * 调用 Vectorize REST API 批量上传 (ndjson 格式)。  
-* **Metadata 设计**：  
-  {  
-    "url": "/posts/my-k8s-article/",  
-    "title": "K8s 学习笔记",  
-    "text": "Kubernetes 是一个容器编排平台..."  
-  }
+* **鉴权配置**：脚本需读取环境变量 CLOUDFLARE\_ACCOUNT\_ID 和 CLOUDFLARE\_API\_TOKEN。  
+* **状态管理**：使用 `.ingest_state.json` 记录文件哈希，实现增量更新。  
+* **自动化**：通过 GitHub Actions (`.github/workflows/rag-ingest.yml`) 自动触发，并自动提交状态文件。
 
 ### **模块 B: 后端 API (Pages Function)**
 
@@ -98,16 +83,10 @@ sequenceDiagram
 
 描述：嵌入博客的悬浮聊天窗。  
 文件位置：layouts/partials/chatbox.html
+样式文件：assets/css/extended/chat.css (移动到 extended 目录以被 Hugo 自动处理)
 
 * **技术栈**：Vanilla JS (无框架依赖，确保轻量)。  
-* **UI 构成**：  
-  * **Launcher**：右下角悬浮圆钮 (SVG Icon)。  
-  * **Chat Window**：包含 Header (博主头像), Message List (滚动区), Input Area。  
-* **交互逻辑**：  
-  * **状态管理**：维护一个简单的 chatHistory 数组在内存中。  
-  * **Markdown 渲染**：引入轻量级库 marked.js (通过 CDN 引入)，将 AI 返回的 markdown 文本转为 HTML 显示。  
-  * **Loading 态**：发送请求时，显示 "思考中..." 动画，且禁用输入框。  
-  * **引用展示**：解析后端返回的 metadata，在气泡下方用小字显示 "Ref: \[文章标题\]" 链接，增加可信度。
+* **依赖**：marked.js (用于渲染 Markdown 回复)。
 
 ## **5\. 提示词工程规范 (System Prompt Spec)**
 
@@ -150,4 +129,5 @@ Cursor 提示 (Cursor Prompts)：
 2. requirements.txt: Python 依赖列表。  
 3. functions/api/chat.js: 含历史记录处理的后端。  
 4. layouts/partials/chatbox.html: 含 marked.js 集成的前端。  
-5. assets/css/chat.css: 适配移动端的样式。
+5. assets/css/extended/chat.css: 适配移动端的样式。  
+6. .github/workflows/rag-ingest.yml: 自动化数据更新工作流。

docs/ingest-strategy.md

@@ -71,20 +71,15 @@ make ingest-data
 make ingest-data FILE=content/posts/new-article.md
 ```
 
-### 方式 3: Git Hook（自动化）
+### 方式 3: GitHub Actions（CI/CD） - **推荐**
 
-可以添加到 Git pre-commit hook，自动处理修改的文件：
+已配置 `.github/workflows/rag-ingest.yml`。
+每次推送到 `main` 分支且包含 `content/` 目录变更时，会自动运行摄取脚本。
+脚本会自动提交更新后的 `.ingest_state.json` 文件，保持状态同步。
 
-```bash
-# 安装 Git hooks（如果还没有）
-bash scripts/setup_git_hooks.sh
-
-# 然后每次提交包含 .md 文件时，会自动运行摄取脚本
-```
-
-### 方式 4: GitHub Actions（CI/CD）
-
-可以添加到 GitHub Actions workflow，在推送时自动运行。
+需配置 Secrets：
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_API_TOKEN`
 
 ## 📝 自动化方案
 
@@ -123,28 +118,29 @@ make ingest-data FILE=content/posts/new-article.md  # 处理单个文件
 - 需要配置 Git hooks
 - 可能增加提交时间
 
-### 方案 C: GitHub Actions（CI/CD 集成）
+### 方案 C: GitHub Actions（CI/CD 集成） - **已采用**
 
-在 GitHub Actions workflow 中添加步骤：
+在 `.github/workflows/rag-ingest.yml` 中实现：
 
 ```yaml
-- name: Ingest blog content to Vectorize
-  env:
-    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+- name: Run Ingestion Script
   run: |
-    pip install -r requirements.txt
     python scripts/ingest.py
+- name: Commit State File
+  run: |
+    git add .ingest_state.json
+    git commit -m "🤖 Update RAG ingestion state"
+    git push
 ```
 
 **优点**：
-- 完全自动化
-- 在云端运行，不占用本地资源
-- 可以设置定时任务
+- 完全自动化，无需本地操作
+- 自动处理新文章（包括自动生成的 Daily AI）
+- 状态文件自动同步，避免重复计算
 
-**缺点**：
-- 需要配置 GitHub Secrets
-- 每次推送都会运行（可能不必要）
+**注意**：
+- 确保 GitHub Secrets 配置正确
+- 赋予 Workflow `contents: write` 权限以提交状态文件
 
 ### 方案 D: 增量更新脚本（推荐用于频繁更新）
 

docs/rag-chatbot-setup.md

@@ -84,26 +84,21 @@ uv pip install -r requirements.txt
    - **Metric**: `cosine` (推荐) 或 `euclidean`
 6. 点击 "Create"
 
-### 步骤 2: 运行数据摄取脚本
+### 步骤 2: 数据摄取（自动化）
+
+推荐使用 GitHub Actions 自动处理。每次推送到 main 分支时，如果内容有更新，系统会自动更新向量数据库。
+
+您也可以手动运行脚本：
 
 ```bash
-# 处理所有 Markdown 文件
+# 处理所有 Markdown 文件（增量更新）
 python scripts/ingest.py
 
-# 处理单个文件（测试用）
-python scripts/ingest.py --file zh/posts/welcome.md
-
-# 自定义内容目录和基础URL
-python scripts/ingest.py --content-dir content --base-url https://hobbytp.github.io
+# 强制重新处理所有文件
+python scripts/ingest.py --force
 ```
 
-脚本会：
-- 扫描 `content/` 目录下的所有 `.md` 文件（排除 `_index.md`）
-- 解析 frontmatter，提取标题、日期等信息
-- 清洗 Markdown 符号，将文本切片（约500字符/chunk，重叠50字符）
-- 生成确定性ID（基于URL和chunk索引，实现幂等性）
-- 调用 Cloudflare Workers AI 生成向量
-- 批量上传到 Vectorize
+**注意**：脚本会在本地生成 `.ingest_state.json` 文件，用于记录已处理文件的状态。建议将此文件提交到 Git，以实现多人协作和 CI/CD 状态同步。
 
 ### 步骤 3: 配置 Cloudflare Pages
 

layouts/partials/chatbox.html

@@ -130,7 +130,9 @@ <h3>数字分身</h3>
         scrollToBottom();
 
         try {
-            const response = await fetch('/api/chat', {
+            const apiBase = "{{ with site.Params.chatApiBase }}{{ . }}{{ end }}";
+            const endpoint = (apiBase && apiBase !== "") ? `${apiBase}/api/chat` : "/api/chat";
+            const response = await fetch(endpoint, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json'
@@ -140,17 +142,22 @@ <h3>数字分身</h3>
                     history: chatHistory.slice(0, -1) // 不包含刚才发送的最新消息
                 })
             });
-            
-            const data = await response.json();
+            const contentType = response.headers.get('content-type') || '';
+            let data = null;
+            if (contentType.includes('application/json')) {
+                data = await response.json();
+            } else {
+                const text = await response.text();
+                console.error('API returned non-JSON:', text.slice(0, 200));
+            }
 
             // 移除Loading
             loadingDiv.remove();
 
-            if (response.ok) {
+            if (response.ok && data && typeof data === 'object') {
                 await appendMessage('assistant', data.response || "抱歉，我没有理解你的问题。");
             } else {
-                console.error('API error:', data.error);
-                await appendMessage('assistant', '抱歉，服务暂时无法响应。请稍后再试或联系管理员。');
+                await appendMessage('assistant', '抱歉，服务暂不可用或未部署。');
             }
         } catch (error) {
             loadingDiv.remove();

openspec/changes/complete-digital-twin/proposal.md

@@ -23,9 +23,15 @@
   - 明确指定“找不到内容”时的回复语为用户要求的：“没有找到相关内容”。
   - 确保 AI 默认使用中文回答。
 
+### 4. 自动化 RAG 数据更新
+- **操作**: 创建 `.github/workflows/rag-ingest.yml`。
+- **原因**: 确保每次博客内容更新（包括自动生成的 Daily AI）后，向量数据库能自动同步更新。
+- **配置**: 使用 GitHub Actions 监听 `content/` 目录变更，运行 `scripts/ingest.py`，并回写状态文件 `.ingest_state.json`。
+
 ## 验证计划
 1.  **样式验证**: 部署后检查右下角是否出现悬浮聊天按钮，点击是否能正常展开聊天窗口。
 2.  **功能验证**: 发送测试消息（如“你好”），确认是否收到回复。
 3.  **Markdown 验证**: 询问需要代码块或列表回复的问题，确认渲染是否正常。
 4.  **RAG 验证**: 询问博客相关问题，确认回复基于上下文。
 5.  **Fallback 验证**: 询问无关问题（如“番茄炒蛋怎么做”），确认回复“没有找到相关内容”。
+6.  **自动化验证**: 提交一篇新文章，检查 GitHub Actions 是否自动触发并成功更新向量库。

openspec/changes/complete-digital-twin/tasks.md

@@ -1,7 +1,9 @@
 # Tasks
 
-- [ ] Create OpenSpec proposal file <!-- id: 0 -->
-- [ ] Move `assets/css/chat.css` to `assets/css/extended/chat.css` <!-- id: 1 -->
-- [ ] Add marked.js CDN to `layouts/partials/chatbox.html` <!-- id: 2 -->
-- [ ] Update system prompt in `functions/api/chat.js` <!-- id: 3 -->
+- [x] Create OpenSpec proposal file <!-- id: 0 -->
+- [x] Move `assets/css/chat.css` to `assets/css/extended/chat.css` <!-- id: 1 -->
+- [x] Add marked.js CDN to `layouts/partials/chatbox.html` <!-- id: 2 -->
+- [x] Update system prompt in `functions/api/chat.js` <!-- id: 3 -->
+- [x] Create GitHub Workflow `.github/workflows/rag-ingest.yml` <!-- id: 5 -->
+- [x] Generate and commit `.ingest_state.json` <!-- id: 6 -->
 - [ ] Commit and push changes <!-- id: 4 -->