rssany 0.3.2 → 0.3.3

package/.env.example

@@ -1,52 +1,52 @@
-# ─── 服务基础 ────────────────────────────────────────────────────────────────
-PORT=18473
-NODE_ENV=production
-
-# 前端地址，OAuth 回调后重定向至此
-APP_URL=https://rssany.com
-
-# ─── 认证（必填）────────────────────────────────────────────────────────────
-# JWT 签名密钥，至少 32 位随机字符串，例如：openssl rand -base64 32
-JWT_SECRET=change-me-to-a-random-32-char-secret
-
-# ─── Google OAuth（可选）────────────────────────────────────────────────────
-# 在 https://console.cloud.google.com/apis/credentials 创建 OAuth 2.0 客户端
-# 授权回调 URI 填：https://your-domain.com/api/auth/google
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-
-# ─── GitHub OAuth（可选）────────────────────────────────────────────────────
-# 在 https://github.com/settings/applications/new 创建 OAuth App
-# Authorization callback URL 填：https://your-domain.com/api/auth/github
-GITHUB_CLIENT_ID=
-GITHUB_CLIENT_SECRET=
-
-# ─── 邮件发送（全部放 env，无需在 config.json 写 email 节）─────────────────────
-# SMTP 配置
-SMTP_HOST=smtp.example.com
-SMTP_PORT=465
-SMTP_SECURE=true
-SMTP_USER=your@example.com
-SMTP_PASS=your-smtp-password
-
-
-# Resend API Key（driver=resend 时使用；https://resend.com/api-keys）
-RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
-
-# ─── LLM（解析 / Pipeline 等；也可在管理后台「设置 → LLM」写入 .rssany/config.json）──
-OPENAI_API_KEY=sk-...
-OPENAI_BASE_URL=https://api.openai.com/v1
-OPENAI_MODEL=gpt-4o-mini
-
-
-# ─── 用户数据目录（可选）──────────────────────────────────────────────────────
-# 默认：用户主目录下的 .rssany/（Windows：%USERPROFILE%\.rssany）
-# RSSANY_USER_DIR=/path/to/custom
-
-# ─── 数据库（本地 SQLite）────────────────────────────────────────────────────
-# 主库路径：<用户数据>/.rssany/data/rssany.db（启动时自动建表）；可选：
-# RSSANY_DB_JOURNAL=delete  在 Windows 热重载场景下降低 WAL 损坏风险
-
-# ─── 缓存目录（可选）────────────────────────────────────────────────────────
-# 默认：<用户数据>/.rssany/cache；可单独覆盖：
-# CACHE_DIR=/path/to/custom/cache
+# ─── 服务基础 ────────────────────────────────────────────────────────────────
+PORT=18473
+NODE_ENV=production
+
+# 前端地址，OAuth 回调后重定向至此
+APP_URL=https://rssany.com
+
+# ─── 认证（必填）────────────────────────────────────────────────────────────
+# JWT 签名密钥，至少 32 位随机字符串，例如：openssl rand -base64 32
+JWT_SECRET=change-me-to-a-random-32-char-secret
+
+# ─── Google OAuth（可选）────────────────────────────────────────────────────
+# 在 https://console.cloud.google.com/apis/credentials 创建 OAuth 2.0 客户端
+# 授权回调 URI 填：https://your-domain.com/api/auth/google
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# ─── GitHub OAuth（可选）────────────────────────────────────────────────────
+# 在 https://github.com/settings/applications/new 创建 OAuth App
+# Authorization callback URL 填：https://your-domain.com/api/auth/github
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# ─── 邮件发送（全部放 env，无需在 config.json 写 email 节）─────────────────────
+# SMTP 配置
+SMTP_HOST=smtp.example.com
+SMTP_PORT=465
+SMTP_SECURE=true
+SMTP_USER=your@example.com
+SMTP_PASS=your-smtp-password
+
+
+# Resend API Key（driver=resend 时使用；https://resend.com/api-keys）
+RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
+
+# ─── LLM（解析 / Pipeline 等；也可在管理后台「设置 → LLM」写入 .rssany/config.json）──
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4o-mini
+
+
+# ─── 用户数据目录（可选）──────────────────────────────────────────────────────
+# 默认：用户主目录下的 .rssany/（Windows：%USERPROFILE%\.rssany）
+# RSSANY_USER_DIR=/path/to/custom
+
+# ─── 数据库（本地 SQLite）────────────────────────────────────────────────────
+# 主库路径：<用户数据>/.rssany/data/rssany.db（启动时自动建表）；可选：
+# RSSANY_DB_JOURNAL=delete  在 Windows 热重载场景下降低 WAL 损坏风险
+
+# ─── 缓存目录（可选）────────────────────────────────────────────────────────
+# 默认：<用户数据>/.rssany/cache；可单独覆盖：
+# CACHE_DIR=/path/to/custom/cache

package/README.md

@@ -1,69 +1,78 @@
-# RSSAny - 把任何信息变成RSS订阅
-
-
-> 按信源抓取网页 / RSS / 邮件等，解析、补全文、打标签与翻译后**入库**，再按需生成 **RSS / Atom / JSON Feed** 与 JSON API。
-
-**RSSAny** 是一套自托管的订阅管线：列表 URL → **抓取与解析**（规则 / LLM）→ **正文提取**（自定义 / Readability / LLM）→ **upsert 去重** → 固定 **pipeline**（打标签、翻译等）→ 对外提供 `**/rss`** 等输出。
-
-## 界面预览
-
-![RSSAny Web 界面截图](images/ScreenShot_2026-04-10_153307_558.png)
-
----
-
-## 功能概览
-
-- **统一订阅**：在 `.rssany/sources.json` 中配置网站列表、标准 RSS、IMAP 邮件等，由调度器按 `refresh` 策略拉取。
-- **可插拔信源**：**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` 发送）；留空则仅本地消费。
-- **Web 界面**：SvelteKit 构建产物由后端托管；**Feeds** 等需 **邮箱校验**；`**/admin`** 需 `**users.role === 'admin'**`（可从 `**/me**` 进入）。
-
----
-
-## 技术栈（摘要）
-
-
-| 层级  | 说明                                                           |
-| --- | ------------------------------------------------------------ |
-| 运行时 | Node.js **20–23**（见 `package.json` `engines`）                |
-| 后端  | Hono、`tsx` 开发入口                                              |
-| 数据  | **SQLite**（Node.js 内置 `node:sqlite`，Node.js 20+），默认 **`~/.rssany/data/rssany.db`**（Windows：`%USERPROFILE%\.rssany\data\rssany.db`） |
-
----
-
-## 快速开始
-
-日常使用只需 **Node.js 20.x–23.x**（与 `package.json` 的 `engines` 一致）：
-
-### 全局安装（推荐）
-
-```bash
+# RSSAny - 把任何信息变成RSS订阅
+
+
+> 按信源抓取网页 / RSS / 邮件等，解析、补全文、打标签与翻译后**入库**，再按需生成 **RSS / Atom / JSON Feed** 与 JSON API。
+
+**RSSAny** 是一套自托管的订阅管线：列表 URL → **抓取与解析**（规则 / LLM）→ **正文提取**（自定义 / Readability / LLM）→ **upsert 去重** → 固定 **pipeline**（打标签、翻译等）→ 对外提供 `**/rss`** 等输出。
+
+## 界面预览
+
+![RSSAny Web 界面截图](images/ScreenShot_2026-04-10_153307_558.png)
+
+---
+
+## 功能概览
+
+- **统一订阅**：在 `.rssany/sources.json` 中配置网站列表、标准 RSS、IMAP 邮件等，由调度器按 `refresh` 策略拉取。
+- **可插拔信源**：**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` 发送）；留空则仅本地消费。
+- **Web 界面**：SvelteKit 构建产物由后端托管；**Feeds** 等需 **邮箱校验**；`**/admin`** 需 `**users.role === 'admin'**`（可从 `**/me**` 进入）。
+
+---
+
+## 技术栈（摘要）
+
+
+| 层级  | 说明                                                           |
+| --- | ------------------------------------------------------------ |
+| 运行时 | Node.js **20–23**（见 `package.json` `engines`）                |
+| 后端  | Hono、`tsx` 开发入口                                              |
+| 数据  | **SQLite**（Node.js 内置 `node:sqlite`，Node.js 20+），全局安装默认 **`{npm prefix}/var/rssany/data/rssany.db`** |
+
+## 快速开始
+
+日常使用只需 **Node.js 20.x–23.x**（与 `package.json` 的 `engines` 一致）：
+
+### 全局安装（推荐）
+
+```bash
 npm install -g rssany   # 与 npm i -g rssany 相同
 rssany start
 ```
 
+**macOS / Linux（系统自带 Node）** 若 `npm install -g` 报 `EACCES`，先一次性配置 npm 使用用户目录（仍是 npm 命令，无需 sudo）：
+
+```bash
+npm config set prefix "$HOME/.local"
+export PATH="$HOME/.local/bin:$PATH"   # 可写入 ~/.zshrc 或 ~/.bashrc
+npm install -g rssany
+```
+
+使用 **nvm / fnm** 安装的 Node 通常可直接 `npm install -g rssany`，无需上述配置。
+
 安装包内已包含构建好的后端与 Web 界面；用 **`rssany start`** 后台启动并直接返回访问地址（默认 **`http://127.0.0.1:18473/`**，端口可在**运行命令时当前目录**下的 `.env` 里设置 `PORT`）；用 **`rssany stop`** 关闭后台服务并输出执行状态。
-
-- **数据目录**：首次运行会在 **`~/.rssany/`**（Windows：`%USERPROFILE%\.rssany\`）自动从包内 **`init/`** 生成 `sources.json`、`config.json` 等（已存在则不会覆盖）。
+
+- **数据目录**：全局安装时落在 **npm prefix 下的 `var/rssany/`**（例如 `~/.local/var/rssany/` 或 nvm 的 `.../node/v22.x/var/rssany/`），与 `lib/node_modules/rssany` 同级，升级 npm 包不会覆盖配置与数据库。源码开发时使用仓库内 **`.rssany/`**。仍可用 **`RSSANY_USER_DIR`** 覆盖。
+- **从 `~/.rssany` 迁移**：若新目录尚不存在且旧目录有数据，首次启动会自动迁移。
 - **可选配置**：在启动 `rssany start` 时的**当前目录**放置 `.env`（可参考仓库里的 `.env.example`），用于 JWT、OAuth、SMTP、LLM（如 `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL`）等。
-- **重置全部本地数据**（结束占用 `PORT` 的进程并删除用户目录，慎用）：执行 **`rssany reset`**；在含 `.env` 的目录下运行可读取 `PORT` / `RSSANY_USER_DIR`，或事先在环境里导出这些变量。
-
+- **重置全部本地数据**（结束占用 `PORT` 的进程并删除用户目录，慎用）：执行 **`rssany reset`**；在含 `.env` 的目录下运行可读取 `PORT` / `RSSANY_USER_DIR`，或事先在环境里导出这些变量。
+
 CLI 名为 **`rssany`**；裸 `rssany` 只显示用法，不再直接进入服务运行状态。
-
-### 从源码运行（开发 / 贡献）
-
+
+### 从源码运行（开发 / 贡献）
+
 需要 **npm**：
-
-```bash
+
+```bash
 npm install
 npm run webui:install
-cp .env.example .env   # 按需修改
-```
-
+cp .env.example .env   # 按需修改
+```
+
 **开发**（单一后端地址；前端静态构建自动 watch）：
 
 ```bash
@@ -73,97 +82,97 @@ npm run dev
 该命令会先启动 `webui` 静态构建 watch，等首轮 HTML 构建完成后再启动后端服务；浏览器只访问后端地址（默认 `http://127.0.0.1:3999/`），不再单独启动前端开发服务器。
 
 或分步：一个终端运行 `npm run webui:watch`，另一个终端运行 `npm run dev:backend`。
-
+
 **生产**（本仓库）：`npm run webui:build && npm start`。
-
+
 **重置本地数据**（与全局安装的 `rssany reset` 逻辑相同）：`npm run reset`。
-
-发布到 npm 时 `prepublishOnly` 会执行 `build:all`（后端 `vite build` + `webui:build`）。
-
----
-
-## 数据流（简图）
-
-```
-sources.json / 信源插件
-  → 调度器触发 fetchItems
-  → upsertItems
-  → pipeline（每条一次）
-  → [可选] deliver.url POST（出站，非入站 API）
-```
-
-消费侧：**RSS/XML**、`**/api/*`**、Web UI。
-
----
-
-## 常用 HTTP 能力
-
-### RSS 输出
-
-- **按条件从库中生成**：支持 `search`、`tags`、`lng`、`limit` 等查询参数；可用 `subscribed=1` 限定为 `sources.json` 中出现的 ref。
-- **按 URL 即时抓取**：`GET /rss/https://example.com/...`（具体行为以路由实现为准）。
-
----
-
-## 配置
-
-**信源插件（Site / Source）**：目录约定、`listUrlPattern` / `pattern`、`fetchItems`、与 `sources.json` 的关系等，见 **[docs/plugins.md](./docs/plugins.md)**。
-
-### Pipeline（固定代码）
-
-`**app/pipeline/**`，通过 `**.rssany/config.json**` 配置步骤，例如：
-
-```json
-{
-  "pipeline": {
-    "steps": [
-      { "id": "tagger", "enabled": true },
-      { "id": "translator", "enabled": false }
-    ]
-  },
-  "deliver": {
-    "url": ""
-  }
-}
-```
-
-`deliver.url` 非空时会对处理完成的条目向该 URL 发起出站 POST；留空则不投递。
-
-### `sources.json` 片段示例
-
-```json
-{
-  "sources": [
-    { "ref": "https://example.com/feed.xml", "label": "Example", "refresh": "1h" }
-  ]
-}
-```
-
-合法 `refresh` 取值包括：`10min`、`30min`、`1h`、`6h`、`12h`、`1day`（默认）、`3day`、`7day`。
-
----
-
-## 仓库目录（摘要）
-
-```
-├── app/                 # 后端：路由、feeder、scraper、pipeline、db、auth…
-│   └── plugins/builtin/ # 内置信源 *.rssany.js
-├── docs/                # 用户文档（如 plugins.md）
-└── webui/               # SvelteKit 前端
-
-~/.rssany/               # 运行时用户数据（首次启动创建；或 RSSANY_USER_DIR）
-    ├── sources.json
-    ├── config.json
-    ├── tags.json
-    ├── data/rssany.db   # SQLite 主库
-    ├── cache/
-    └── plugins/         # 用户插件覆盖内置
-```
-
-更细的模块说明见 **[AGENTS.md](./AGENTS.md)**（与代码迭代同步，若有出入以代码为准）。
-
----
-
-## 许可证
-
+
+发布到 npm 时 `prepublishOnly` 会执行 `build:all`（后端 `vite build` + `webui:build`）。
+
+---
+
+## 数据流（简图）
+
+```
+sources.json / 信源插件
+  → 调度器触发 fetchItems
+  → upsertItems
+  → pipeline（每条一次）
+  → [可选] deliver.url POST（出站，非入站 API）
+```
+
+消费侧：**RSS/XML**、`**/api/*`**、Web UI。
+
+---
+
+## 常用 HTTP 能力
+
+### RSS 输出
+
+- **按条件从库中生成**：支持 `search`、`tags`、`lng`、`limit` 等查询参数；可用 `subscribed=1` 限定为 `sources.json` 中出现的 ref。
+- **按 URL 即时抓取**：`GET /rss/https://example.com/...`（具体行为以路由实现为准）。
+
+---
+
+## 配置
+
+**信源插件（Site / Source）**：目录约定、`listUrlPattern` / `pattern`、`fetchItems`、与 `sources.json` 的关系等，见 **[docs/plugins.md](./docs/plugins.md)**。
+
+### Pipeline（固定代码）
+
+`**app/pipeline/**`，通过 `**.rssany/config.json**` 配置步骤，例如：
+
+```json
+{
+  "pipeline": {
+    "steps": [
+      { "id": "tagger", "enabled": true },
+      { "id": "translator", "enabled": false }
+    ]
+  },
+  "deliver": {
+    "url": ""
+  }
+}
+```
+
+`deliver.url` 非空时会对处理完成的条目向该 URL 发起出站 POST；留空则不投递。
+
+### `sources.json` 片段示例
+
+```json
+{
+  "sources": [
+    { "ref": "https://example.com/feed.xml", "label": "Example", "refresh": "1h" }
+  ]
+}
+```
+
+合法 `refresh` 取值包括：`10min`、`30min`、`1h`、`6h`、`12h`、`1day`（默认）、`3day`、`7day`。
+
+---
+
+## 仓库目录（摘要）
+
+```
+├── app/                 # 后端：路由、feeder、scraper、pipeline、db、auth…
+│   └── plugins/builtin/ # 内置信源 *.rssany.js
+├── docs/                # 用户文档（如 plugins.md）
+└── webui/               # SvelteKit 前端
+
+~/.rssany/               # 运行时用户数据（首次启动创建；或 RSSANY_USER_DIR）
+    ├── sources.json
+    ├── config.json
+    ├── tags.json
+    ├── data/rssany.db   # SQLite 主库
+    ├── cache/
+    └── plugins/         # 用户插件覆盖内置
+```
+
+更细的模块说明见 **[AGENTS.md](./AGENTS.md)**（与代码迭代同步，若有出入以代码为准）。
+
+---
+
+## 许可证
+
 MIT

package/app/plugins/builtin/email.rssany.js

@@ -1,92 +1,92 @@
-// 内置 IMAP 邮件插件：匹配 imap://、imaps:// 协议 URL
+// 内置 IMAP 邮件插件：匹配 imap://、imaps:// 协议 URL
 export const id = "__email__";
 export const name = "Email";
 export const pattern = /^imaps?:\/\//;
 export const priority = 0;
 export const refreshInterval = "30min";
 
-function parseImapUrl(sourceId) {
-  const url = new URL(sourceId);
-  const host = url.hostname;
-  const port = url.port ? parseInt(url.port, 10) : 993;
-  const secure = url.protocol === "imaps:" || port === 993;
-  const user = decodeURIComponent(url.username);
-  const pass = decodeURIComponent(url.password);
-  const folder = decodeURIComponent(url.pathname.slice(1)) || "INBOX";
-  const limit = Math.max(1, parseInt(url.searchParams.get("limit") ?? "30", 10));
-  return { host, port, secure, user, pass, folder, limit };
-}
-
-function makeGuid(messageId, uid, host, createHash) {
-  const raw = messageId ?? `${uid}@${host}`;
-  return createHash("sha256").update(raw).digest("hex");
-}
-
-export async function fetchItems(sourceId, ctx) {
-    const { deps } = ctx;
-    const { host, port, secure, user, pass, folder, limit } = parseImapUrl(sourceId);
-    const client = new deps.ImapFlow({
-      host,
-      port,
-      secure,
-      auth: { user, pass },
-      logger: false,
-    });
-
-    client.on("error", (err) => {
-      deps.logger.error("source", "IMAP 连接异常", { err: err?.message, host, folder });
-    });
-
-    const items = [];
-    let connected = false;
-    try {
-      await client.connect();
-      connected = true;
-      const lock = await client.getMailboxLock(folder);
-      try {
-        const mailbox = client.mailbox;
-        if (mailbox === false) return [];
-        const total = mailbox.exists ?? 0;
-        if (total === 0) return [];
-        const start = Math.max(1, total - limit + 1);
-        for await (const msg of client.fetch(`${start}:*`, { source: true, envelope: true })) {
-          try {
-            if (msg.source === undefined || msg.envelope === undefined) continue;
-            const parsed = await deps.simpleParser(msg.source);
-            const envelope = msg.envelope;
-            const guid = makeGuid(envelope.messageId, msg.uid, host, deps.createHash);
-            const title = parsed.subject ?? envelope.subject ?? "(无主题)";
-            const fromAddr = envelope.from?.[0];
-            const authorRaw = fromAddr?.name || fromAddr?.address || undefined;
-            const author = authorRaw ? [authorRaw] : undefined;
-            const pubDate = parsed.date ?? envelope.date ?? new Date();
-            const link = `imap://${host}/${encodeURIComponent(folder)}#${msg.uid}`;
-            const htmlBody = typeof parsed.html === "string" ? parsed.html : undefined;
-            const textBody = typeof parsed.text === "string" ? parsed.text : undefined;
-            const content = htmlBody ?? (textBody ? `<pre>${textBody}</pre>` : undefined);
-            const summary = textBody?.slice(0, 300) || undefined;
-            items.push({ guid, title, link, pubDate, author, summary, content });
-          } catch (err) {
-            deps.logger.warn("source", "解析单封邮件失败", { err: err?.message });
-          }
-        }
-      } finally {
-        lock.release();
-      }
-    } catch (err) {
-      deps.logger.warn("source", "拉取 IMAP 邮件失败", { err: err?.message, host, folder });
-      return [];
-    } finally {
-      if (connected && client.usable) {
-        try {
-          await client.logout();
-        } catch (err) {
-          deps.logger.warn("source", "IMAP 退出连接失败", { err: err?.message, host, folder });
-        }
-      } else {
-        client.close();
-      }
-    }
-    return items.sort((a, b) => b.pubDate.getTime() - a.pubDate.getTime());
+function parseImapUrl(sourceId) {
+  const url = new URL(sourceId);
+  const host = url.hostname;
+  const port = url.port ? parseInt(url.port, 10) : 993;
+  const secure = url.protocol === "imaps:" || port === 993;
+  const user = decodeURIComponent(url.username);
+  const pass = decodeURIComponent(url.password);
+  const folder = decodeURIComponent(url.pathname.slice(1)) || "INBOX";
+  const limit = Math.max(1, parseInt(url.searchParams.get("limit") ?? "30", 10));
+  return { host, port, secure, user, pass, folder, limit };
+}
+
+function makeGuid(messageId, uid, host, createHash) {
+  const raw = messageId ?? `${uid}@${host}`;
+  return createHash("sha256").update(raw).digest("hex");
+}
+
+export async function fetchItems(sourceId, ctx) {
+    const { deps } = ctx;
+    const { host, port, secure, user, pass, folder, limit } = parseImapUrl(sourceId);
+    const client = new deps.ImapFlow({
+      host,
+      port,
+      secure,
+      auth: { user, pass },
+      logger: false,
+    });
+
+    client.on("error", (err) => {
+      deps.logger.error("source", "IMAP 连接异常", { err: err?.message, host, folder });
+    });
+
+    const items = [];
+    let connected = false;
+    try {
+      await client.connect();
+      connected = true;
+      const lock = await client.getMailboxLock(folder);
+      try {
+        const mailbox = client.mailbox;
+        if (mailbox === false) return [];
+        const total = mailbox.exists ?? 0;
+        if (total === 0) return [];
+        const start = Math.max(1, total - limit + 1);
+        for await (const msg of client.fetch(`${start}:*`, { source: true, envelope: true })) {
+          try {
+            if (msg.source === undefined || msg.envelope === undefined) continue;
+            const parsed = await deps.simpleParser(msg.source);
+            const envelope = msg.envelope;
+            const guid = makeGuid(envelope.messageId, msg.uid, host, deps.createHash);
+            const title = parsed.subject ?? envelope.subject ?? "(无主题)";
+            const fromAddr = envelope.from?.[0];
+            const authorRaw = fromAddr?.name || fromAddr?.address || undefined;
+            const author = authorRaw ? [authorRaw] : undefined;
+            const pubDate = parsed.date ?? envelope.date ?? new Date();
+            const link = `imap://${host}/${encodeURIComponent(folder)}#${msg.uid}`;
+            const htmlBody = typeof parsed.html === "string" ? parsed.html : undefined;
+            const textBody = typeof parsed.text === "string" ? parsed.text : undefined;
+            const content = htmlBody ?? (textBody ? `<pre>${textBody}</pre>` : undefined);
+            const summary = textBody?.slice(0, 300) || undefined;
+            items.push({ guid, title, link, pubDate, author, summary, content });
+          } catch (err) {
+            deps.logger.warn("source", "解析单封邮件失败", { err: err?.message });
+          }
+        }
+      } finally {
+        lock.release();
+      }
+    } catch (err) {
+      deps.logger.warn("source", "拉取 IMAP 邮件失败", { err: err?.message, host, folder });
+      return [];
+    } finally {
+      if (connected && client.usable) {
+        try {
+          await client.logout();
+        } catch (err) {
+          deps.logger.warn("source", "IMAP 退出连接失败", { err: err?.message, host, folder });
+        }
+      } else {
+        client.close();
+      }
+    }
+    return items.sort((a, b) => b.pubDate.getTime() - a.pubDate.getTime());
   }