merge dev into main

.env.example

@@ -15,6 +15,10 @@ FC_DB_SQLITE_PATH=./db
 # Cache Configuration
 FC_REDIS_URI=redis://localhost:6379/
 
+# Outbound HTTP User-Agent defaults
+FC_HTTP_USER_AGENT_FEED="FeedCraft/2.0"
+FC_HTTP_USER_AGENT_HTML="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36"
+
 # LLM Configuration
 FC_LLM_API_BASE=https://api.openai.com/v1
 FC_LLM_API_KEY=sk-your-api-key-here
@@ -28,4 +32,4 @@ FC_PUPPETEER_HTTP_ENDPOINT=http://localhost:3000
 # Frontend Configuration
 FRONTEND_PORT=5173
 FRONTEND_HOST=localhost
-VITE_API_BASE_URL=http://localhost:8080
+VITE_API_BASE_URL=http://localhost:8080

.github/workflows/docker-publish.yml

@@ -99,7 +99,7 @@ jobs:
       # https://github.com/docker/build-push-action
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           file: build/Dockerfile
           context: .

.github/workflows/lint.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           version: latest
 
-      - uses: pnpm/action-setup@v3
+      - uses: pnpm/action-setup@v6
         with:
           version: 9
 

README.md

@@ -19,17 +19,17 @@ Doc: [English](https://feed-craft-doc.vercel.app/en) | [简体中文](https://fe
 
 **FeedCraft** is a simple, powerful RSS feed processing tool.  
 It can serve as middleware to handle your RSS feeds; you can use it to extract the main text, perform intelligent translation, generate article summaries through AI, filter articles using natural language, and more.  
-It includes a built-in visual RSS generator (HTML/Curl/Search to RSS) that can turn web pages, API responses, or search results into RSS feeds.
+It includes a built-in visual RSS generator (HTML/JSON/Search to RSS) that can turn web pages, JSON API responses, or search results into RSS feeds.
 
 **FeedCraft** 是一个简单、强大的 RSS 源处理工具.
 他可以作为一个中间件处理你的 RSS 源, 你可以用它来提取正文、智能翻译、通过 AI 生成文章摘要、通过自然语言筛选文章等.
-它内置了可视化 RSS 生成器 (HTML/Curl/Search to RSS)，支持将网页、API (Curl) 或搜索结果转换为 RSS 订阅源。
+它内置了可视化 RSS 生成器 (HTML/JSON/Search to RSS)，支持将网页、JSON API (Curl) 或搜索结果转换为 RSS 订阅源。
 
 ## 核心特性
 
 - 开源可自部署. 可以作为中间件与现有的任何 RSS 阅读器协同使用
 - AI Power, 可以接入 Open AI 接口兼容的 LLM 对 RSS 进行处理, 可自定义 prompt
-- **HTML/Curl/Search to RSS**: 内置可视化 RSS 生成器，支持将网页、API (Curl) 或搜索结果转换为 RSS 订阅源
+- **HTML/JSON/Search to RSS**: 内置可视化 RSS 生成器，支持将网页、JSON API (支持 Curl 语句导入) 或搜索结果转换为 RSS 订阅源
 - 支持**便携模式**(portable mode, 即用即走, 只需要在原 RSS 地址前面加个前缀即可), 和**高级模式**(dock mode,
   在后台页面自定义 RSS 地址和各类深度加工参数)
 
@@ -87,7 +87,6 @@ https://feed-craft.colinx.one
 控制台默认账号`admin`, 密码 `adminadmin`, 登陆后请尽快修改默认密码
 
 ```yaml
-version: "3"
 services:
   app.feed-craft:
     image: ghcr.io/colin-xkl/feed-craft
@@ -129,6 +128,7 @@ services:
       FC_LLM_API_MODEL: gemini-pro/chatgpt-3.5/... # 默认使用的模型
       FC_LLM_API_TYPE: openai # openai 或 ollama
       FC_DEFAULT_TARGET_LANG: zh-CN # (Optional) LLM 处理任务的默认目标语言
+      LOG_LEVEL: info # (Optional) 日志级别，如 info, debug, trace
   service.redis:
     image: redis:6-alpine
     container_name: feedcraft_redis

doc-site/src/content/docs/en/guides/advanced/customization.md

@@ -65,12 +65,15 @@ You can configure FeedCraft using environment variables in `docker-compose.yml`.
 
 - **FC_PUPPETEER_HTTP_ENDPOINT**: Address of the Browserless/Chrome instance. Required for `fulltext-plus`.
 - **FC_REDIS_URI**: Redis connection address. Used for caching to speed up processing and reduce AI token consumption.
+- **FC_HTTP_USER_AGENT_FEED**: (Optional) Default `User-Agent` for feed-style outbound requests, such as fetching RSS/XML resources. Search provider requests are temporarily grouped into this same rule.
+- **FC_HTTP_USER_AGENT_HTML**: (Optional) Default `User-Agent` for HTML page fetches, such as fulltext extraction and the HTML-to-RSS tooling. **Note:** If the value contains spaces or parentheses, it must be enclosed in quotes.
 - **FC_LLM_API_KEY**: API Key for OpenAI or compatible services (like DeepSeek, Gemini, etc.).
 - **FC_LLM_API_MODEL**: Default model to use (e.g., `gemini-pro`, `gpt-3.5-turbo`). **Multiple Models Support:** You can provide a comma-separated list of models (e.g., `gpt-3.5-turbo,gpt-4`). FeedCraft will randomly select a model for each request and automatically retry with others if a call fails.
 - **FC_LLM_API_BASE**: API endpoint address. For OpenAI-compatible APIs, usually ends with `/v1`.
 - **FC_LLM_API_TYPE**: (Optional) `openai` (default) or `ollama`.
 - **FC_LLM_MAX_CONCURRENCY**: (Optional) Global maximum concurrency for LLM requests (default: `3`). Limits concurrent API calls to prevent rate limits.
 - **FC_DOMAIN_MAX_CONCURRENCY**: (Optional) Maximum concurrent requests per target domain during web scraping like fulltext extraction (default: `3`). Prevents overwhelming target servers.
+- **LOG_LEVEL**: (Optional) Log level for the backend application (e.g., `info`, `debug`, `trace`). Overrides the default level set by `ENV`.
 
 ### External Services
 

doc-site/src/content/docs/en/guides/advanced/html-to-rss.md

@@ -11,7 +11,7 @@ sidebar:
 FeedCraft includes a visual **HTML to RSS** tool that allows you to generate selectors for creating RSS feeds from websites that don't provide them natively.
 
 :::note
-This tool is designed for HTML pages. If you need to process a JSON API, use the [CURL to RSS](/en/guides/advanced/curl-to-rss/) instead.
+This tool is designed for HTML pages. If you need to process a JSON API, use the [JSON to RSS](/en/guides/advanced/json-to-rss/) instead.
 :::
 
 ## Overview

doc-site/src/content/docs/en/guides/advanced/curl-to-rss.md → doc-site/src/content/docs/en/guides/advanced/json-to-rss.md

@@ -1,5 +1,5 @@
 ---
-title: CURL to RSS
+title: JSON to RSS
 description: Convert any JSON API response into an RSS feed with jq selectors and optional templates.
 sidebar:
   order: 3
@@ -8,11 +8,11 @@ sidebar:
     variant: success
 ---
 
-FeedCraft includes a **CURL to RSS** tool that allows you to fetch data from JSON APIs, extract fields with `jq`, and optionally post-process them with templates before generating an RSS feed.
+FeedCraft includes a **JSON to RSS** tool that allows you to fetch data from JSON APIs, extract fields with `jq`, and optionally post-process them with templates before generating an RSS feed.
 
 ## Overview
 
-The CURL to RSS tool helps you:
+The JSON to RSS tool helps you:
 
 1.  **Fetch** JSON data from an API endpoint (supporting custom headers and methods).
 2.  **Parse** the JSON structure using `jq` syntax, then optionally use templates to build the final RSS fields.
@@ -21,13 +21,13 @@ The CURL to RSS tool helps you:
 
 ## How to use
 
-Navigate to **Worktable > Curl to RSS** in the admin dashboard.
+Navigate to **Worktable > JSON to RSS** in the admin dashboard.
 
 ### Step 1: Request Configuration
 
 You need to define how to fetch the JSON data.
 
-- **Import from Curl**: You can paste a `curl` command to automatically populate the URL, method, headers, and body. This is useful if you copy the request from your browser's Developer Tools.
+- **Import from cURL**: You can paste a `curl` command to automatically populate the URL, method, headers, and body. This is useful if you copy the request from your browser's Developer Tools.
 - **Method**: Select `GET` or `POST`.
 - **URL**: The API endpoint URL.
 - **Headers**: Add any necessary headers (e.g., `Authorization`, `Content-Type`).
@@ -50,6 +50,28 @@ The tool uses **[jq](https://jqlang.github.io/jq/)** syntax for querying JSON, a
 - **Date Selector**: (Optional) Path to the publication date.
 - **Content Selector**: (Optional) Path to the full content or summary.
 
+#### Using Templates (Optional)
+
+You can use [Go Templates](https://pkg.go.dev/text/template) to further process extracted values.
+
+**Available Variables:**
+
+- `.Fields`: The parsed field values (e.g., `.Fields.Title`, `.Fields.Link`, `.Fields.Date`, `.Fields.Description`).
+- `.Item`: The raw JSON item object (e.g., `.Item.id`, `.Item.author.name`).
+
+**Built-in Functions:**
+
+- `trimSpace`: Removes leading and trailing whitespace.
+- `trim`: Removes specified leading and trailing characters.
+- `default`: Provides a fallback value if the field is empty.
+
+**Examples:**
+
+- **Clean up whitespace in title**: `{{ .Fields.Title | trimSpace }}`
+- **Build absolute URLs**: `https://example.com/article/{{ .Item.id }}`
+- **Remove specific prefixes**: `{{ .Fields.Description | trim "Prefix: " }}`
+- **Fallback values**: `{{ default .Fields.Description "No summary available" }}`
+
 Click **Run Preview** to verify your selectors, then click **Next Step**.
 
 ### Step 3: Feed Metadata

doc-site/src/content/docs/en/guides/advanced/tools.md

@@ -48,6 +48,21 @@ The **Craft Dependencies** (System Health) tool visualizes the internal relation
 If you encounter errors like "Craft not found", use this tool to trace the broken link in your configuration.
 :::
 
+## System Runtime
+
+The **System Runtime** (Observability) tool provides a comprehensive dashboard for monitoring the health and execution status of your resources.
+
+- **Usage**:
+  1. Navigate to **Tools > System Runtime**.
+- **Features**:
+  - **Resource Health**: View the current status (Healthy, Degraded, Paused) of Recipes and other components, including consecutive failures.
+  - **Execution Logs**: Track detailed execution history, success rates, and specific error types (e.g., Timeout, Network, Parse) across all runs.
+  - **System Notifications**: Review automated alerts regarding resource state transitions (e.g., when a Recipe becomes degraded). You can also subscribe to these alerts via the built-in RSS feed at `/system/notifications/rss`.
+
+:::tip
+If a Recipe fails repeatedly and becomes "Paused", you can use the System Runtime dashboard to manually "Resume" it after fixing the underlying issue.
+:::
+
 ## Debug Tools
 
 ### LLM Debug

doc-site/src/content/docs/en/guides/start/concepts.md

@@ -57,6 +57,11 @@ You can configure processors for a Topic Feed to automatically handle the combin
 - **Limit**: Keeps only the most recent items.
 
 **Managing Topic Feeds:**
+
+:::caution
+The Topic Feed feature is currently under active development. Its UI entry point in the admin dashboard has been temporarily hidden until the feature is stable and ready for general use.
+:::
+
 Navigate to **Worktable > Topic Feed** to create and manage topics.
 
 - **Create**: Define a title, add multiple input URIs (e.g. `feedcraft://recipe/my-recipe` or external RSS URLs), and set your aggregator config.

doc-site/src/content/docs/zh-tw/guides/advanced/customization.md

@@ -65,12 +65,15 @@ sidebar:
 
 - **FC_PUPPETEER_HTTP_ENDPOINT**: Browserless/Chrome 實例的地址。`fulltext-plus` 功能必須。
 - **FC_REDIS_URI**: Redis 連線地址。用於快取，加快處理速度並減少 AI Token 消耗。
+- **FC_HTTP_USER_AGENT_FEED**: （可選）feed 類外部請求的預設 `User-Agent`，例如抓取 RSS/XML 資源時使用。搜尋提供方請求目前也暫時歸入這一規則。
+- **FC_HTTP_USER_AGENT_HTML**: （可選）HTML 頁面抓取的預設 `User-Agent`，例如全文提取和 HTML 轉 RSS 工具使用。**注意：** 如果該值包含空格或括號，必須使用引號括起來。
 - **FC_LLM_API_KEY**: OpenAI 或相容服務（如 DeepSeek, Gemini 等）的 API Key。
 - **FC_LLM_API_MODEL**: 預設使用的模型（如 `gemini-pro`, `gpt-3.5-turbo`）。**支援多個模型：** 你可以提供一個逗號分隔的模型列表（例如 `gpt-3.5-turbo,gpt-4`）。FeedCraft 會為每個請求隨機選擇一個模型，如果調用失敗，會自動重試列表中的其他模型。
 - **FC_LLM_API_BASE**: API 介面地址。如果是相容 OpenAI 的 API，通常以 `/v1` 結尾。
 - **FC_LLM_API_TYPE**: (可選) `openai` (預設) 或 `ollama`.
 - **FC_LLM_MAX_CONCURRENCY**: (可選) 全局最大 LLM 併發請求數（預設: `3`）。用於限制併發請求數量以防止觸發 API 速率限制。
 - **FC_DOMAIN_MAX_CONCURRENCY**: (可選) 網頁抓取（如全文提取）時每個目標域名的最大併發數（預設: `3`）。防止抓取目標伺服器負載過高。
+- **LOG_LEVEL**: (可選) 後端應用的日誌級別 (例如 `info`, `debug`, `trace`)。覆蓋 `ENV` 設定的預設級別。
 
 ### 外部服務
 

doc-site/src/content/docs/zh-tw/guides/advanced/html-to-rss.md

@@ -11,7 +11,7 @@ sidebar:
 FeedCraft 內建了視覺化的 **從 HTML 網頁生成 RSS (HTML to RSS)** 工具，允許你生成選取器，以便為那些沒有提供 RSS 的網站建立訂閱源。
 
 :::note
-此工具專為 HTML 頁面設計。如果你需要處理 JSON API，請使用 [從 CURL 語句生成 RSS](/zh-tw/guides/advanced/curl-to-rss/)。
+此工具專為 HTML 頁面設計。如果你需要處理 JSON API，請使用 [從 JSON 生成 RSS](/zh-tw/guides/advanced/json-to-rss/)。
 :::
 
 ## 概覽

doc-site/src/content/docs/zh-tw/guides/advanced/curl-to-rss.md → doc-site/src/content/docs/zh-tw/guides/advanced/json-to-rss.md

@@ -1,5 +1,5 @@
 ---
-title: 從 CURL 語句生成 RSS
+title: 從 JSON 生成 RSS
 description: 使用 jq 提取欄位，並透過可選模板將任意 JSON API 響應轉換為 RSS 訂閱源。
 sidebar:
   order: 3
@@ -8,7 +8,7 @@ sidebar:
     variant: success
 ---
 
-FeedCraft 包含一個 **從 CURL 語句生成 RSS (CURL to RSS)** 工具，允許你從 JSON API 獲取資料，先用 `jq` 提取欄位，再透過可選模板將其轉換為 RSS 訂閱源。
+FeedCraft 包含一個 **從 JSON 生成 RSS (JSON to RSS)** 工具，允許你從 JSON API 獲取資料，先用 `jq` 提取欄位，再透過可選模板將其轉換為 RSS 訂閱源。
 
 ## 概覽
 
@@ -21,13 +21,13 @@ JSON RSS 生成器可以幫助你：
 
 ## 如何使用
 
-在管理後台導航至 **工作台 > Curl 轉 RSS**。
+在管理後台導航至 **工作台 > JSON 轉 RSS**。
 
 ### 第一步：請求配置 (Request Configuration)
 
 你需要定義如何獲取 JSON 資料。
 
-- **從 Curl 匯入 (Import from Curl)**：你可以貼上 `curl` 命令來自動填充 URL、方法、請求標頭和請求體。這在你從瀏覽器開發者工具複製請求時非常有用。
+- **從 cURL 匯入 (Import from cURL)**：你可以貼上 `curl` 命令來自動填充 URL、方法、請求標頭和請求體。這在你從瀏覽器開發者工具複製請求時非常有用。
 - **方法 (Method)**：選擇 `GET` 或 `POST`。
 - **URL**：API 端點 URL。
 - **Headers**：添加任何必要的請求標頭（例如 `Authorization`, `Content-Type`）。
@@ -50,6 +50,28 @@ JSON RSS 生成器可以幫助你：
 - **日期選取器 (Date Selector)**：（可選）發布日期的路徑。
 - **內容選取器 (Content Selector)**：（可選）完整內容或摘要的路徑。
 
+#### 使用模板 (可選)
+
+你可以使用 [Go Templates](https://pkg.go.dev/text/template) 語法對提取的值進行進一步處理。
+
+**可用變數：**
+
+- `.Fields`：已解析的欄位值（例如 `.Fields.Title`, `.Fields.Link`, `.Fields.Date`, `.Fields.Description`）。
+- `.Item`：原始 JSON 列表項物件（例如 `.Item.id`, `.Item.author.name`）。
+
+**內建函數：**
+
+- `trimSpace`：移除首尾的空白字元。
+- `trim`：移除首尾指定的字元。
+- `default`：如果欄位為空，提供一個預設值。
+
+**範例：**
+
+- **清理標題空白字元**：`{{ .Fields.Title | trimSpace }}`
+- **拼接完整連結**：`https://example.com/article/{{ .Item.id }}`
+- **移除特定前缀**：`{{ .Fields.Description | trim "Prefix: " }}`
+- **預設值兜底**：`{{ default .Fields.Description "暫無摘要" }}`
+
 點擊 **執行預覽 (Run Preview)** 驗證你的選取器，然後點擊 **下一步 (Next Step)**。
 
 ### 第三步：訂閱源元數據 (Feed Metadata)

doc-site/src/content/docs/zh-tw/guides/advanced/tools.md

@@ -48,6 +48,21 @@ FeedCraft 提供了一些內建工具來幫助您除錯 RSS 來源並監控系
 如果遇到 "Craft not found" 等錯誤，可以使用此工具追蹤配置中的斷鏈。
 :::
 
+## 系統運行狀態 (System Runtime)
+
+**系統運行狀態** (Observability) 工具提供了一個全面的儀表板，用於監控資源的健康狀況和執行狀態。
+
+- **使用方法**:
+  1. 導航至 **工具 > 系統運行狀態**。
+- **功能**:
+  - **資源健康 (Resource Health)**: 查看配方及其他組件的當前狀態（健康、降級、暫停），包括連續失敗次數。
+  - **執行日誌 (Execution Logs)**: 追蹤詳細的執行歷史、成功率以及每次運行的具體錯誤類型（例如：超時、網路錯誤、解析錯誤）。
+  - **系統通知 (System Notifications)**: 查看關於資源狀態轉換的自動警報（例如當配方降級時）。您還可以透過內建的 RSS 來源 `/system/notifications/rss` 訂閱這些警報。
+
+:::tip
+如果配方反覆失敗並變為「暫停 (Paused)」狀態，您可以在解決根本問題後，透過系統運行狀態儀表板手動將其「恢復 (Resume)」。
+:::
+
 ## 除錯工具 (Debug Tools)
 
 ### LLM 除錯 (LLM Debug)

doc-site/src/content/docs/zh-tw/guides/start/concepts.md

@@ -57,6 +57,11 @@ sidebar:
 - **限制 (Limit)**：僅保留最新發布的指定數量項目。
 
 **管理主題訂閱：**
+
+:::caution
+Topic Feed (主題訂閱) 功能當前仍在開發完善中。其在管理後台的入口已被臨時隱藏，待功能穩定就緒後將重新開放。
+:::
+
 在管理後台導航至 **工作台 (Worktable) > 主題訂閱 (Topic Feed)** 頁面建立和管理主題。
 
 - **建立**：定義標題，添加多個輸入 URI（例如 `feedcraft://recipe/my-recipe` 或外部 RSS 連結），並配置你的聚合規則。

doc-site/src/content/docs/zh/guides/advanced/customization.md

@@ -65,12 +65,15 @@ sidebar:
 
 - **FC_PUPPETEER_HTTP_ENDPOINT**: Browserless/Chrome 实例的地址。`fulltext-plus` 功能必须。
 - **FC_REDIS_URI**: Redis 连接地址。用于缓存，加快处理速度并减少 AI Token 消耗。
+- **FC_HTTP_USER_AGENT_FEED**: （可选）feed 类外部请求的默认 `User-Agent`，例如抓取 RSS/XML 资源时使用。搜索提供方请求目前也临时归入这一规则。
+- **FC_HTTP_USER_AGENT_HTML**: （可选）HTML 页面抓取的默认 `User-Agent`，例如全文提取和 HTML 转 RSS 工具使用。**注意：** 如果该值包含空格或括号，必须使用引号括起来。
 - **FC_LLM_API_KEY**: OpenAI 或兼容服务（如 DeepSeek, Gemini 等）的 API Key。
 - **FC_LLM_API_MODEL**: 默认使用的模型（如 `gemini-pro`, `gpt-3.5-turbo`）。**支持多个模型：** 你可以提供一个逗号分隔的模型列表（例如 `gpt-3.5-turbo,gpt-4`）。FeedCraft 会为每个请求随机选择一个模型，如果调用失败，会自动重试列表中的其他模型。
 - **FC_LLM_API_BASE**: API 接口地址。如果是兼容 OpenAI 的 API，通常以 `/v1` 结尾。
 - **FC_LLM_API_TYPE**: (可选) `openai` (默认) 或 `ollama`.
 - **FC_LLM_MAX_CONCURRENCY**: (可选) 全局最大 LLM 并发请求数（默认: `3`）。用于限制并发请求数量以防止触发 API 速率限制。
 - **FC_DOMAIN_MAX_CONCURRENCY**: (可选) 网页抓取（如全文提取）时每个目标域名的最大并发数（默认: `3`）。防止抓取目标服务器负载过高。
+- **LOG_LEVEL**: (可选) 后端应用的日志级别 (例如 `info`, `debug`, `trace`)。覆盖 `ENV` 设置的默认级别。
 
 ### 外部服务
 

doc-site/src/content/docs/zh/guides/advanced/html-to-rss.md

@@ -11,7 +11,7 @@ sidebar:
 FeedCraft 内置了可视化的 **从 HTML 网页生成 RSS (HTML to RSS)** 工具，允许你生成选择器，以便为那些没有提供 RSS 的网站创建订阅源。
 
 :::note
-此工具专为 HTML 页面设计。如果你需要处理 JSON API，请使用 [从 CURL 语句生成 RSS](/zh/guides/advanced/curl-to-rss/)。
+此工具专为 HTML 页面设计。如果你需要处理 JSON API，请使用 [从 JSON 生成 RSS](/zh/guides/advanced/json-to-rss/)。
 :::
 
 ## 概览