rssany 0.1.2 → 0.1.4

package/README.md

@@ -14,13 +14,12 @@
 ## 功能概览
 
 - **统一订阅**：在 `.rssany/sources.json` 中配置网站列表、标准 RSS、IMAP 邮件等，由调度器按 `refresh` 策略拉取。
-- **可插拔信源**：`app/plugins/builtin/` 与 `.rssany/plugins/` 中的 **Site** 插件（`.rssany.js` / `.rssany.ts`），自定义列表解析与详情规则。
+- **可插拔信源**：**Site / Source** 插件（`.rssany.js` / `.rssany.ts`），见 **[插件配置说明](./docs/plugins.md)**。
 - **正文与解析**：在信源 `fetchItems`（及需要的 `ctx.extractItem` 等）内完成；入库后跑 pipeline。
 - **固定 pipeline**：`app/pipeline/` 中打标签、翻译等，由 `.rssany/config.json` 的 `pipeline.steps` 开关（**不是**用户目录下的 pipeline 插件）。
 - **LLM 辅助**：解析、提取、标签、翻译等可按配置走 OpenAI 兼容接口。
 - **站点登录**：需登录的站点通过 Puppeteer 管理 Cookie（与产品用户账号无关）。
 - **可选远端投递**：若 `config.json` 中 `**deliver.url`** 非空，在写库与 pipeline 完成后将条目以 `**{ sourceRef, items }**` JSON **POST** 到该 URL（由 `app/deliver/post.ts` 发送）；留空则仅本地消费。
-- **MCP**：条目检索等能力以 MCP 暴露，供 Cursor、Claude 等使用。
 - **Web 界面**：SvelteKit 构建产物由后端托管；**Feeds** 等需 **邮箱校验**；`**/admin`** 需 `**users.role === 'admin'**`（可从 `**/me**` 进入）。
 
 ---
@@ -42,82 +41,62 @@
 
 ## 快速开始
 
-### 环境要求
+日常使用只需 **Node.js 20.x–23.x**（与 `package.json` 的 `engines` 一致）：
 
-- Node.js **20.x–23.x**（与 `package.json` 的 `engines` 字段一致）
-- **pnpm**
-
-### 安装依赖
+### 全局安装（推荐）
 
 ```bash
-pnpm install
-pnpm run webui:install
+npm install -g rssany   # 与 npm i -g rssany 相同
+rssany
 ```
 
-### 配置
-
-1. 复制环境变量示例并按需填写（JWT、OAuth、SMTP、LLM 等）：
-  ```bash
-   cp .env.example .env
-  ```
-2. 信源与全局配置：首次启动会在 **`~/.rssany/`**（Windows：`%USERPROFILE%\.rssany\`）下自动从包内 **`init/`** 目录中的默认数据复制生成 `sources.json`、`config.json`（若已存在则不会覆盖）。也可手动复制仓库里的 `init/sources.json`、`init/config.json`。
-3. （可选）LLM：在 `.env` 中设置 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` 等。
+安装包内已包含构建好的后端与 Web 界面；启动后用浏览器打开终端里提示的地址（默认 **`http://127.0.0.1:18473/`**，端口可在**运行命令时当前目录**下的 `.env` 里设置 `PORT`）。
 
-### 运行
+- **数据目录**：首次运行会在 **`~/.rssany/`**（Windows：`%USERPROFILE%\.rssany\`）自动从包内 **`init/`** 生成 `sources.json`、`config.json` 等（已存在则不会覆盖）。
+- **可选配置**：在启动 `rssany` 时的**当前目录**放置 `.env`（可参考仓库里的 `.env.example`），用于 JWT、OAuth、SMTP、LLM（如 `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL`）等。
+- **重置全部本地数据**（结束占用 `PORT` 的进程并删除用户目录，慎用）：执行 **`rssany reset`**；在含 `.env` 的目录下运行可读取 `PORT` / `RSSANY_USER_DIR`，或事先在环境里导出这些变量。
 
-**开发**（后端根路径托管 `webui` 构建产物，改前端需重新构建或 watch）：
-
-```bash
-# 推荐：API + 前端 watch（修改 Svelte 后自动写入构建目录，刷新浏览器即可）
-pnpm run dev:all
-
-# 或分步：先打一次前端再起后端
-pnpm run webui:build
-pnpm dev
-```
+等价于在项目里执行 `node node_modules/rssany/dist/index.js`；CLI 名为 **`rssany`**。
 
-默认监听 `**http://127.0.0.1:18473/**`（端口见 `.env.example` 中 `PORT`，避免与常见开发端口冲突）。
+### 从源码运行（开发 / 贡献）
 
-**重置本地数据**（结束占用 `PORT` 的监听进程，并删除 **`~/.rssany/`**，或 `RSSANY_USER_DIR` 所设目录）：
+需要 **pnpm**：
 
 ```bash
-pnpm reset
+pnpm install
+pnpm run webui:install
+cp .env.example .env   # 按需修改
 ```
 
-**仅调试 WebUI 热更新**（可选）：`cd webui && pnpm dev`（Vite 代理到本机后端，见 `webui/vite.config.ts`）。
-
-**生产**：
+**开发**（后端托管 `webui` 构建目录；改前端可 watch）：
 
 ```bash
-pnpm run webui:build && pnpm start
+pnpm run dev:all
 ```
 
-### npm 全局安装（或 `npx`）
+或分步：`pnpm run webui:build` 后 `pnpm dev`。
 
-发布包时 `prepublishOnly` 会执行 `build:all`（后端 `vite build` + `webui:build`）。安装后：
+**仅调试 WebUI 热更新**（可选）：`cd webui && pnpm dev`（Vite 代理到本机后端，见 `webui/vite.config.ts`）。
 
-```bash
-npm install -g rssany
-rssany
-```
+**生产**（本仓库）：`pnpm run webui:build && pnpm start`。
 
-重置数据（结束 `PORT` 监听进程并删除用户目录）：**`rssany reset`**（与仓库内 **`pnpm reset`** 相同逻辑；可在含 `.env` 的目录下执行以读取 `PORT` / `RSSANY_USER_DIR`）。
+**重置本地数据**（与全局安装的 `rssany reset` 逻辑相同）：`pnpm reset`。
 
-用户数据在 **`~/.rssany/`**（Windows：`%USERPROFILE%\.rssany`），与工作目录无关。可选环境变量 **`RSSANY_USER_DIR`** 可指定其它路径。等价于 `node node_modules/rssany/dist/index.js`；CLI 名称为 `rssany`。内置 `app/plugins/builtin/`、`statics/`、`webui/build` 随包安装路径解析。
+发布到 npm 时 `prepublishOnly` 会执行 `build:all`（后端 `vite build` + `webui:build`）。
 
 ---
 
 ## 数据流（简图）
 
 ```
-sources.json / Site 插件
+sources.json / 信源插件
   → 调度器触发 fetchItems
   → upsertItems
   → pipeline（每条一次）
   → [可选] deliver.url POST（出站，非入站 API）
 ```
 
-消费侧：**RSS/XML**、`**/api/*`**、**MCP**、Web UI。
+消费侧：**RSS/XML**、`**/api/*`**、Web UI。
 
 ---
 
@@ -130,11 +109,9 @@ sources.json / Site 插件
 
 ---
 
-## 插件与配置
-
-### 信源插件（Site）
+## 配置
 
-放置于 `**app/plugins/builtin/**` 或 `**.rssany/plugins/**`（扁平），用户插件可与内置插件同 `id` 覆盖。最小约定包括 `id`、`listUrlPattern` 等（详见 `app/scraper/sources/web/site.ts`）。
+**信源插件（Site / Source）**：目录约定、`listUrlPattern` / `pattern`、`fetchItems`、与 `sources.json` 的关系等，见 **[docs/plugins.md](./docs/plugins.md)**。
 
 ### Pipeline（固定代码）
 
@@ -173,8 +150,9 @@ sources.json / Site 插件
 ## 仓库目录（摘要）
 
 ```
-├── app/                 # 后端：路由、feeder、scraper、pipeline、mcp、db、auth…
+├── app/                 # 后端：路由、feeder、scraper、pipeline、db、auth…
 │   └── plugins/builtin/ # 内置信源 *.rssany.js
+├── docs/                # 用户文档（如 plugins.md）
 └── webui/               # SvelteKit 前端
 
 ~/.rssany/               # 运行时用户数据（首次启动创建；或 RSSANY_USER_DIR）

package/dist/index.js

@@ -134,6 +134,18 @@ function getEffectiveItemFields(item, lng) {
     content: (t?.content != null && t.content !== "" ? t.content : item.content) ?? ""
   };
 }
+function pubDateToIsoOrNull(pubDate) {
+  if (pubDate == null) return null;
+  if (pubDate instanceof Date) {
+    const ms = pubDate.getTime();
+    return Number.isNaN(ms) ? null : pubDate.toISOString();
+  }
+  if (typeof pubDate === "string") {
+    const s = pubDate.trim();
+    return s || null;
+  }
+  return null;
+}
 function normalizeAuthor(author) {
   if (author == null) return void 0;
   if (Array.isArray(author)) return author.filter((s2) => typeof s2 === "string" && s2.trim()).map((s2) => s2.trim());
@@ -619,7 +631,7 @@ async function upsertItems(items, sourceUrlOverride) {
         const nextSummary = normalizeText(item.summary) || null;
         const nextAuthorArr = normalizeAuthor(item.author);
         const nextAuthor = nextAuthorArr?.length ? JSON.stringify(nextAuthorArr) : null;
-        const nextPubDate = item.pubDate instanceof Date ? item.pubDate.toISOString() : item.pubDate ?? null;
+        const nextPubDate = pubDateToIsoOrNull(item.pubDate);
         const nextTags = item.tags?.length ? JSON.stringify(item.tags) : null;
         const nextImageUrl = typeof item.imageUrl === "string" && item.imageUrl.trim() ? item.imageUrl.trim() : null;
         const info = stmt.run({
@@ -687,7 +699,7 @@ async function updateItemContent(item) {
         const arr = normalizeAuthor(item.author);
         return arr?.length ? JSON.stringify(arr) : null;
       })(),
-      pubDate: item.pubDate instanceof Date ? item.pubDate.toISOString() : item.pubDate ?? null,
+      pubDate: pubDateToIsoOrNull(item.pubDate),
       tags: item.tags?.length ? JSON.stringify(item.tags) : null,
       translations: item.translations && Object.keys(item.translations).length > 0 ? JSON.stringify(item.translations) : null
     });
@@ -2514,7 +2526,7 @@ function feedItemsToPayload(items) {
     guid: i.guid,
     title: i.title,
     link: i.link,
-    pubDate: i.pubDate instanceof Date ? i.pubDate.toISOString() : (/* @__PURE__ */ new Date()).toISOString(),
+    pubDate: pubDateToIsoOrNull(i.pubDate) ?? (/* @__PURE__ */ new Date()).toISOString(),
     author: i.author,
     summary: i.summary,
     content: i.content,
@@ -2575,7 +2587,7 @@ function toRssEntry(item, lng) {
     link: item.link,
     description: desc,
     guid: item.guid,
-    published: item.pubDate?.toISOString?.() ?? void 0,
+    published: pubDateToIsoOrNull(item.pubDate) ?? void 0,
     imageUrl: item.imageUrl
   };
 }
@@ -2957,7 +2969,7 @@ function registerRssApiRoutes(app) {
             link: item.link,
             summary,
             author: item.author,
-            pubDate: item.pubDate instanceof Date ? item.pubDate.toISOString() : item.pubDate
+            pubDate: pubDateToIsoOrNull(item.pubDate)
           };
         })
       });