opensource

docs/DEPLOYMENT.md

@@ -0,0 +1,186 @@
+## 项目部署与维护
+
+### 🏗️ 项目架构
+
+本项目依托 Cloudflare 强大的生态系统，实现了高效、轻量与良好的可扩展性。
+
+> 各核心组件协同工作，构成了一个从数据输入、处理到输出的完整闭环。
+
+*   **☁️ Cloudflare Workers**: 作为项目的**核心执行环境**，负责处理所有 HTTP 请求、调度任务、调用外部 API 以及执行 AI 内容生成逻辑。
+*   **🗄️ Cloudflare KV**: 作为项目的**持久化存储**，用于保存配置信息、缓存数据以及每日生成的报告内容，提供了低延迟的键值对存储能力。
+*   **🔌 外部 API 整合**:
+    *   **AI 模型 API**: 集成 Google Gemini 和 OpenAI 兼容 API，为内容摘要和再创作提供强大的 AI 支持。
+    *   **内容源 API**:
+        *   **Folo API**: 默认的信息聚合来源，可灵活配置抓取不同的 Folo 源。
+        *   **GitHub Trending API**: 获取 GitHub 每日热门项目，追踪开源趋势。
+    *   **发布渠道 API**:
+        *   **GitHub API**: 用于将处理好的内容自动推送到指定的 GitHub 仓库。
+*   **🛠️ Wrangler**: Cloudflare官方的命令行工具，用于项目的本地开发、环境配置和一键部署。
+
+### 🚀 快速开始
+
+#### 1. 准备工作
+
+首先，请确保您的开发环境中已安装 Node.js 和 npm。
+
+- **安装 Wrangler CLI**:
+  ```bash
+  npm install -g wrangler
+  或
+  npm install -g @cloudflare/wrangler
+  ```
+
+- **克隆项目代码**:
+  ```bash
+  git clone https://github.com/justlovemaki/CloudFlare-AI-Insight-Daily.git
+  cd CloudFlare-AI-Insight-Daily
+  ```
+
+#### 2. 配置环境变量
+
+项目的核心配置均在 `wrangler.toml` 文件中完成。请根据您的需求修改 `[vars]` 部分的配置。
+
+> **注意**：使用 `**` 标记的为 **必填项**。
+
+```toml
+# wrangler.toml
+
+# 项目名称
+name = "ai-insight-daily" 
+# Worker 入口文件
+main = "src/index.js" 
+# 兼容性日期
+compatibility_date = "2024-05-20"
+# 在开发模式下是否启用 Worker，设置为 true 可以在 workers.dev 子域上预览。
+workers_dev = true
+
+[vars]
+# ========================
+# 基础功能配置
+# ========================
+**LOGIN_USERNAME** = "your_login_username"
+**LOGIN_PASSWORD** = "your_login_password"
+DAILY_TITLE = "AI洞察日报"
+PODCAST_TITLE = "来生小酒馆"
+PODCAST_BEGIN = "嘿，亲爱的V，欢迎收听新一期的来生情报站，我是你们的老朋友，何夕2077"
+PODCAST_END = "今天的情报就到这里，注意隐蔽，赶紧撤离"
+
+# ========================
+# AI 模型配置
+# ========================
+# 可选值: "GEMINI" 或 "OPEN"
+**USE_MODEL_PLATFORM** = "GEMINI" 
+OPEN_TRANSLATE = "true"
+
+# Gemini 配置
+**GEMINI_API_KEY** = "your_gemini_api_key"
+GEMINI_API_URL = "https://generativelanguage.googleapis.com"
+DEFAULT_GEMINI_MODEL = "gemini-2.5-flash-preview-05-20"
+
+# OpenAI 兼容 API 配置 (如 DeepSeek)
+OPENAI_API_KEY = "your_openai_compatible_key"
+OPENAI_API_URL = "https://api.deepseek.com"
+DEFAULT_OPEN_MODEL = "deepseek-chat"
+
+# ========================
+# GitHub 发布配置
+# ========================
+**GITHUB_TOKEN** = "your_github_personal_access_token"
+**GITHUB_REPO_OWNER** = "your_github_username"
+**GITHUB_REPO_NAME** = "your_repo_name"
+**GITHUB_BRANCH** = "main"
+
+# ========================
+# 内容源配置 (按需配置)
+# ========================
+# Folo 源
+FOLO_COOKIE_KV_KEY = "folo_auth_cookie"
+FOLO_DATA_API = "https://api.follow.is/entries"
+FOLO_FILTER_DAYS = "1"
+
+# 其他内容源 ID 和抓取页数...
+AIBASE_FEED_ID = "......" 
+AIBASE_FETCH_PAGES = "2" 
+XIAOHU_FEED_ID = "......" 
+XIAOHU_FETCH_PAGES = "2" 
+HGPAPERS_FEED_ID = "......"
+HGPAPERS_FETCH_PAGES = "2" 
+TWITTER_LIST_ID = "......"
+TWITTER_FETCH_PAGES = "2" 
+```
+
+#### 3. 本地开发与调试
+
+- **配置 KV 命名空间**:
+  1.  在 Cloudflare 控制台 > `Workers 和 Pages` > `KV` 中创建一个新的 KV 命名空间。
+  2.  将创建的 KV ID 添加到 `wrangler.toml` 文件中：
+      ```toml
+      kv_namespaces = [
+        { 
+            binding = "DATA_KV",  # 代码中使用的绑定名称
+            id = "your_kv_namespace_id"  # 在 Cloudflare 控制台找到的 ID
+        }
+      ]
+      ```
+
+- **启动本地开发服务**:
+  ```bash
+  wrangler dev
+  ```
+  该命令会启动一个本地服务器（通常在 `http://localhost:8787`），您可以直接在浏览器中访问以进行调试。
+
+#### 4. 部署到 Cloudflare
+
+- **登录 Cloudflare**:
+  ```bash
+  wrangler login
+  ```
+
+- **一键部署**:
+  ```bash
+  wrangler deploy
+  ```
+  部署成功后，Wrangler 会返回一个公开的 `*.workers.dev` 域名，您的 AI 洞察日报服务已在线上运行！
+
+### 🗓️ 定时生成 Pages 站点 (可选)
+
+如果您希望将每日报告自动发布为 GitHub Pages 静态网站，可以按照以下步骤配置一个 Docker 定时任务。
+
+1.  **前提条件**: 确保您的目标 GitHub 仓库已开启 GitHub Actions 和 GitHub Pages 功能。仓库中应包含 `unzip_and_commit.yml` 工作流文件。
+
+2.  **修改配置**: 进入 `cron-docker` 目录。
+    *   编辑 `Dockerfile`，修改 `ENV` 部分为您自己的仓库信息和可选的图片代理地址。
+    *   编辑 `scripts/work/book.toml`，修改 `title` 和 `src` 路径。
+    *   (可选) 修改 `Dockerfile` 中的 cron 表达式以自定义每日执行时间。
+
+3.  **构建并运行 Docker 容器**:
+    ```bash
+    # 进入 cron-docker 目录
+    cd cron-docker
+
+    # 构建 Docker 镜像
+    docker build -t ai-daily-cron-job .
+
+    # 在后台启动容器
+    docker run -d --name ai-daily-cron ai-daily-cron-job
+    ```
+
+4.  **验证部署**: 定时任务触发后，会自动生成内容并推送到您的仓库。稍等片刻，即可通过您的 GitHub Pages 地址（例如 `https://<user>.github.io/<repo>/today/book/`）访问生成的日报。
+
+### ❓ F.A.Q
+
+#### 如何获取 `feedId` 和 `listId`？
+
+-   **Folo Feed ID**: 登录 Folo.so 后，在浏览器地址栏中找到 `feedId`。
+    ![获取 Folo Feed ID](images/folo-1.png)
+
+-   **Twitter List ID**: 在 Twitter 上打开您想关注的列表，`listId` 就在地址栏中。
+    ![获取 Twitter List ID](images/folo-2.png)
+
+#### 🔑 如何获取 API 密钥？
+
+-   **Google Gemini API Key**:
+    访问 [Google AI for Developers](https://ai.google.dev/gemini-api/docs/api-key?hl=zh-cn) 创建您的 API 密钥。
+
+-   **GitHub Personal Access Token**:
+    请参照 [GitHub 官方文档](https://docs.github.com/zh/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) 生成一个具有 `repo` 权限的 Token。

docs/EXTENDING.md

@@ -0,0 +1,89 @@
+## 项目拓展性：如何添加新的数据源
+
+“AI 洞察日报”项目设计具有良好的可扩展性，允许开发者轻松集成新的数据源，以丰富内容类型或增加现有类型的覆盖范围。以下是添加新数据源的详细步骤：
+
+1.  **创建新的数据源文件**：
+    -   在 `src/dataSources/` 目录下创建一个新的 JavaScript 文件，例如 `src/dataSources/yourNewDataSource.js`。
+    -   这个文件需要导出一个包含两个核心方法的对象：
+        -   `fetch(env)`：一个异步函数，负责从外部 API 获取原始数据。`env` 参数包含了 `wrangler.toml` 中配置的环境变量，你可以利用这些变量来配置 API 密钥、URL 等。
+        -   `transform(rawData, sourceType)`：一个函数，负责将 `fetch` 方法获取到的原始数据转换为项目统一的数据格式。统一格式应包含 `id`, `url`, `title`, `content_html` (或 `description`), `date_published` (或 `pubDate`), `authors` (或 `author`) 等字段，以便项目能够正确处理和展示。`sourceType` 参数表示当前数据源的类型（例如 'news', 'project'）。
+        -   `generateHtml(item)` (可选)：一个函数，如果该数据源的内容需要特定的 HTML 渲染方式，则实现此方法。它接收一个统一格式的 `item` 对象，并返回用于在前端页面展示的 HTML 字符串。如果未提供此方法，系统将使用默认的 HTML 渲染逻辑。注意：同一分类下，只有第一个数据源需要实现 `generateHtml` 方法。
+
+    **示例 `src/dataSources/yourNewDataSource.js` 结构：**
+    ```javascript
+    // src/dataSources/yourNewDataSource.js
+    const YourNewDataSource = {
+        type: 'your-new-type', // 定义数据源的唯一类型标识
+        async fetch(env) {
+            // 使用 env.YOUR_API_KEY, env.YOUR_API_URL 等配置进行 API 请求
+            const response = await fetch(env.YOUR_API_URL);
+            const data = await response.json();
+            return data; // 返回原始数据
+        },
+        transform(rawData, sourceType) {
+            // 将原始数据转换为统一格式
+            return rawData.items.map(item => ({
+                id: item.id,
+                url: item.url,
+                title: item.title,
+                content_html: item.content, // 或 item.description
+                published_date: item.publishedAt, // 或 item.date_published
+                authors: [{ name: item.author }], // 或 item.authors
+                source_type: sourceType, // 标记数据来源类型
+            }));
+        },
+        generateHtml(item) {
+            // 可选：自定义 HTML 渲染逻辑
+            return `
+                <h3><a href="${item.url}" target="_blank">${item.title}</a></h3>
+                <small>发布日期: ${new Date(item.published_date).toLocaleDateString()} - 作者: ${item.authors.map(a => a.name).join(', ')}</small>
+                <div class="content-html">${item.content_html}</div>
+            `;
+        }
+    };
+    export default YourNewDataSource;
+    ```
+
+2.  **导入新的数据源**：
+    -   打开 `src/dataFetchers.js` 文件。
+    -   在文件顶部，使用 `import` 语句导入你新创建的数据源模块：
+        ```javascript
+        import YourNewDataSource from './dataSources/yourNewDataSource.js';
+        ```
+
+3.  **注册新的数据源**：
+    -   在 `src/dataFetchers.js` 文件中找到 `dataSources` 对象。
+    -   根据你的需求，将新的数据源添加到现有类型（如 `news`, `project`, `paper`, `socialMedia`）的 `sources` 数组中，或者创建一个新的数据类型并添加进去。
+    -   **添加到现有类型示例**：
+        ```javascript
+        export const dataSources = {
+            news: { name: '新闻', sources: [AibaseDataSource, XiaohuDataSource, YourNewDataSource] },
+            // ... 其他类型
+        };
+        ```
+    -   **创建新的数据类型示例**：
+        ```javascript
+        export const dataSources = {
+            // ... 现有类型
+            yourNewCategory: { name: '你的新类别名称', sources: [YourNewDataSource] },
+        };
+        ```
+
+4.  **更新 `wrangler.toml` (如果需要)**：
+    -   如果你的新数据源需要额外的 API 密钥、URL 或其他配置，请在 `wrangler.toml` 文件的 `[vars]` 部分添加相应的环境变量。
+    -   例如：
+        ```toml
+        [vars]
+        # ... 其他变量
+        YOUR_API_KEY = "your_api_key_here"
+        YOUR_API_URL = "https://api.yournewsource.com"
+        ```
+
+5.  **调整提示词 (如果需要 AI 处理)**：
+    -   如果新添加的数据源内容需要通过 AI 模型进行摘要、格式化或生成其他形式的内容，你可能需要调整或创建新的提示词。
+    -   **创建新的提示词文件**：在 `src/prompt/` 目录下，可以创建新的 JavaScript 文件（例如 `yourNewPrompt.js`）来定义如何根据新数据源的特点构建 AI 提示词。同时，可以创建相应的 Markdown 文件（例如 `systemPromptYourNewType.md`）来存储系统提示词的文本内容。
+    -   **在 `src/handlers/genAIContent.js` 中集成**：根据新数据源的类型，修改 `src/handlers/genAIContent.js` 文件。这通常包括：
+        -   引入并调用新的提示词逻辑（如果创建了新的提示词文件）。
+        -   在 `handleGenAIContent` 函数内部的 `switch (item.type)` 语句中，为新的 `item.type` 添加一个 `case`，定义如何从新数据源的统一格式数据中提取文本内容，作为 AI 模型的输入。
+
+通过以上步骤，你就可以轻松地为“AI 洞察日报”项目添加新的数据源，使其能够聚合更多样化的 AI 相关内容，或其他垂直领域的信息。这使得项目的功能更加丰富，同时也为开发者提供了一个灵活的扩展机制，以满足不断变化的需求。