dsh-rss 0.2.0 → 0.3.1

package/README.en.md

@@ -1,9 +1,19 @@
 # dsh-rss
 
+![npm](https://img.shields.io/npm/v/dsh-rss) ![downloads](https://img.shields.io/npm/dm/dsh-rss) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-rss) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-rss?style=social)
+
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 DSH (DeepSeek Harness) plugin for RSS/Atom subscriptions: manage feeds, fetch and parse RSS 0.9x / 1.0 / 2.0 and Atom, with OPML bulk import/export, exposing seven model-facing tools.
 
+## Compatibility
+
+Adapted to the tool execution contracts in `@deepseek-ai/dsh@0.1.3-alpha.1`. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
+Fetches honor the Harness cancellation signal through DNS, response streaming, and cross-feed searches. Hostname preflight checks reject loopback, private, and link-local addresses by default, including redirect destinations. Set `allowPrivateNetwork: true` for trusted internal feeds.
+
+`rss_opml_export.path` is relative to the calling session's workspace, with an existing parent directory. Absolute paths, traversal, and links outside the workspace are rejected; the result returns the absolute written path. File writes request Harness approval by default (`opmlWriteApproval: false` disables this gate). Omit `path` to return only OPML text.
+
 ## Installation
 
 ```bash
@@ -12,6 +22,15 @@ dsh plugin --profile web add dsh-rss
 
 Restart the web service after installing.
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-rss
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 Override the plugin row in your profile's `cordis.patch.yml` (the plugin also loads with all defaults when absent):
@@ -73,7 +92,7 @@ Most feeds are reachable directly; a few require a special proxy from your netwo
 
 ```bash
 pnpm install
-pnpm test       # builds + 55 tests
+pnpm test       # build + offline tests with explicit fetch and DNS fixtures
 ```
 
 ## License

package/README.md

@@ -9,7 +9,15 @@
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 
-DSH（DeepSeek Harness）的 RSS/Atom 订阅工具插件：管理订阅源，抓取并解析 RSS 0.9x / 1.0 / 2.0 与 Atom，支持 OPML 批量导入导出，给模型提供七个可直接调用的工具。
+DSH（DeepSeek Harness）的 RSS/Atom 订阅工具插件：管理订阅源，抓取并解析 RSS 0.9x / 1.0 / 2.0 与 Atom，支持 OPML 批量导入导出，给模型提供九个可直接调用的工具。
+
+## 兼容性
+
+按 `@deepseek-ai/dsh@0.1.3-alpha.1` 的工具执行接口适配。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
+抓取接收 Harness 的取消信号，取消 DNS、网络读取或跨源搜索时保留原始取消原因。默认预检域名解析结果并拒绝回环、私网和链路本地地址；每次重定向都重新校验。可信内网源可显式配置 `allowPrivateNetwork: true`。
+
+`rss_opml_export.path` 必须相对本次调用的会话工作区，父目录须已存在；工具拒绝绝对路径、目录穿越和指向工作区外的链接，并返回实际写入文件的绝对路径。文件写入默认通过 Harness 审批门，`opmlWriteApproval: false` 可关闭该门；省略 `path` 时仅返回 OPML 文本。
 
 ## 安装
 
@@ -19,6 +27,15 @@ dsh plugin --profile web add dsh-rss
 
 安装后重启 Web 服务即可。
 
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-rss
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+
 ## 配置
 
 在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时插件也能加载，只是全部用默认值）：
@@ -48,6 +65,8 @@ dsh plugin --profile web add dsh-rss
 | `rss_check` | 校验地址是否为可解析的订阅源 | `url` 必填 |
 | `rss_opml_export` | 导出订阅列表为 OPML 2.0 文本（可写入文件） | `path` 可选 |
 | `rss_opml_import` | 从 OPML 2.0 文本批量导入订阅源 | `opml` 必填 |
+| `rss_search` | 跨订阅源关键词搜索条目（标题/摘要/正文/作者） | `query` 必填；`name`/`url`/`since`/`limit` 可选 |
+| `rss_health` | 插件自检（配置/订阅/游标/解析器，离线） | 无 |
 
 ### 示例
 
@@ -80,7 +99,7 @@ rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 55 个测试
+pnpm test       # 构建 + 离线测试（fetch 与 DNS 均使用夹具）
 ```
 
 发布前门禁：危险模式扫描、manifest 自检、`pnpm audit --prod`、全量测试，以及全新 profile 的真实启动冒烟测试。
@@ -88,4 +107,3 @@ pnpm test       # 构建 + 55 个测试
 ## License
 
 MIT
-

package/lib/config.d.ts

@@ -11,6 +11,8 @@ export interface RssConfig {
     maxBodyBytes?: number;
     userAgent?: string;
     feedsYaml?: string;
+    allowPrivateNetwork?: boolean;
+    opmlWriteApproval?: boolean;
 }
 /** 解析后的配置：所有字段都有值。 */
 export interface ResolvedRssConfig {
@@ -19,6 +21,8 @@ export interface ResolvedRssConfig {
     maxBodyBytes: number;
     userAgent: string;
     feedsYaml: string;
+    allowPrivateNetwork: boolean;
+    opmlWriteApproval: boolean;
 }
 /**
  * 解析并校验配置。

package/lib/config.js

@@ -6,9 +6,30 @@
  */
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_BODY_BYTES = 5 * 1024 * 1024;
-const DEFAULT_USER_AGENT = 'dsh-rss/0.2.0 (DeepSeek Harness RSS plugin)';
-function optionalString(value) {
-    return typeof value === 'string' ? value : undefined;
+const DEFAULT_USER_AGENT = 'dsh-rss/0.3.1 (DeepSeek Harness RSS plugin)';
+function configRecord(config) {
+    if (config === undefined || config === null)
+        return {};
+    if (typeof config !== 'object' || Array.isArray(config)) {
+        throw new Error('dsh-rss config 必须是对象。');
+    }
+    return config;
+}
+function optionalString(config, key) {
+    const value = config[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(key + ' 必须是字符串。');
+    return value;
+}
+function optionalBoolean(config, key, fallback) {
+    const value = config[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new Error(key + ' 必须是 true 或 false。');
+    return value;
 }
 /**
  * 解析并校验配置。
@@ -16,26 +37,37 @@ function optionalString(value) {
  * @throws 配置值非法时抛出中文错误。
  */
 export function resolveConfig(config) {
-    const cfg = config ?? {};
-    const proxyUrl = (optionalString(cfg.proxyUrl) ?? '').trim();
-    if (proxyUrl !== '' && !/^https?:\/\//i.test(proxyUrl)) {
-        throw new Error('proxyUrl 必须是 http(s):// 开头的地址，例如 http://127.0.0.1:7890。');
+    const cfg = configRecord(config);
+    const proxyUrl = (optionalString(cfg, 'proxyUrl') ?? '').trim();
+    if (proxyUrl !== '') {
+        try {
+            const parsed = new URL(proxyUrl);
+            if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.hostname === '')
+                throw new Error();
+        }
+        catch {
+            throw new Error('proxyUrl 必须是有效的 http(s) 地址，例如 http://127.0.0.1:7890。');
+        }
     }
     let timeoutMs = DEFAULT_TIMEOUT_MS;
     if (cfg.timeoutMs !== undefined) {
-        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {
-            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒），例如 15000。');
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isInteger(cfg.timeoutMs) || cfg.timeoutMs < 1000 || cfg.timeoutMs > 120000) {
+            throw new Error('timeoutMs 必须是 1000 到 120000 之间的整数（毫秒），例如 15000。');
         }
-        timeoutMs = Math.min(120000, Math.max(1000, Math.round(cfg.timeoutMs)));
+        timeoutMs = cfg.timeoutMs;
     }
     let maxBodyBytes = DEFAULT_MAX_BODY_BYTES;
     if (cfg.maxBodyBytes !== undefined) {
-        if (typeof cfg.maxBodyBytes !== 'number' || !Number.isFinite(cfg.maxBodyBytes) || cfg.maxBodyBytes <= 0) {
-            throw new Error('maxBodyBytes 必须是大于 0 的数字（字节），例如 5242880。');
+        if (typeof cfg.maxBodyBytes !== 'number' || !Number.isInteger(cfg.maxBodyBytes) || cfg.maxBodyBytes < 1024 * 1024 || cfg.maxBodyBytes > 50 * 1024 * 1024) {
+            throw new Error('maxBodyBytes 必须是 1048576 到 52428800 之间的整数（字节），例如 5242880。');
         }
-        maxBodyBytes = Math.min(50 * 1024 * 1024, Math.max(1024 * 1024, Math.round(cfg.maxBodyBytes)));
+        maxBodyBytes = cfg.maxBodyBytes;
     }
-    const userAgent = optionalString(cfg.userAgent) ?? DEFAULT_USER_AGENT;
-    const feedsYaml = optionalString(cfg.feedsYaml) ?? '';
-    return { proxyUrl, timeoutMs, maxBodyBytes, userAgent, feedsYaml };
+    const userAgent = (optionalString(cfg, 'userAgent') ?? DEFAULT_USER_AGENT).trim();
+    if (userAgent === '')
+        throw new Error('userAgent 不能为空字符串。');
+    const feedsYaml = optionalString(cfg, 'feedsYaml') ?? '';
+    const allowPrivateNetwork = optionalBoolean(cfg, 'allowPrivateNetwork', false);
+    const opmlWriteApproval = optionalBoolean(cfg, 'opmlWriteApproval', true);
+    return { proxyUrl, timeoutMs, maxBodyBytes, userAgent, feedsYaml, allowPrivateNetwork, opmlWriteApproval };
 }

package/lib/execution.d.ts

@@ -0,0 +1,11 @@
+/** Harness 0.1.3 传给工具实现的最小执行上下文。 */
+export interface RssToolExecution {
+    readonly signal: AbortSignal;
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}

package/lib/execution.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -1,17 +1,30 @@
 /**
  * dsh-rss —— RSS/Atom 订阅工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：把七个面向模型的工具（rss_list / rss_add / rss_remove /
- * rss_fetch / rss_check / rss_opml_export / rss_opml_import）注册进宿主进程的工具注册表，并把订阅列表接入 settings
- * 命名空间（dsh-rss.feedsYaml）。配置缺失时插件照常加载，工具在 execute 时才抛出
- * 带中文指引的错误。
+ * 插件导出 apply(ctx, config)：把九个面向模型的 RSS 工具注册进宿主进程的工具注册表，
+ * 并把订阅列表接入 settings 命名空间（dsh-rss.feedsYaml）。
  *
  * @module dsh-rss
  */
 import { type RssConfig } from './config.js';
 import { type RssSettingsScope, type RssToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.settings 与 ctx.tools，必须显式声明，否则宿主会抛 cannot get property without inject。 */
+export declare const name = "rss";
 export declare const inject: string[];
+type RssPreToolDecision = {
+    kind: 'allow';
+} | {
+    kind: 'deny';
+    reason: string;
+} | {
+    kind: 'ask';
+    reason?: string;
+};
+interface RssPendingToolExecution {
+    readonly name: string;
+    readonly arguments: unknown;
+}
+type RssPreExecuteListener = (exec: RssPendingToolExecution, next: () => Promise<RssPreToolDecision>) => Promise<RssPreToolDecision>;
 /** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
 export interface RssPluginContext {
     settings: {
@@ -23,10 +36,11 @@ export interface RssPluginContext {
     tools: {
         register(definition: RssToolDefinition): () => void;
     };
-    on?(event: string, listener: () => void): () => void;
+    on(event: 'tools/pre-execute', listener: RssPreExecuteListener): () => void;
+    on(event: 'dispose', listener: () => void): () => void;
 }
 /**
- * 插件入口：解析配置、注册 settings 命名空间与五个 RSS 工具。
+ * 插件入口：严格解析配置、注册 settings 命名空间、九个 RSS 工具与 OPML 写入审批门。
  * @param ctx - 宿主上下文（至少含 settings.register 与 tools.register）。
  * @param config - 插件配置（可缺省）。
  */

package/lib/index.js

@@ -1,10 +1,8 @@
 /**
  * dsh-rss —— RSS/Atom 订阅工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：把七个面向模型的工具（rss_list / rss_add / rss_remove /
- * rss_fetch / rss_check / rss_opml_export / rss_opml_import）注册进宿主进程的工具注册表，并把订阅列表接入 settings
- * 命名空间（dsh-rss.feedsYaml）。配置缺失时插件照常加载，工具在 execute 时才抛出
- * 带中文指引的错误。
+ * 插件导出 apply(ctx, config)：把九个面向模型的 RSS 工具注册进宿主进程的工具注册表，
+ * 并把订阅列表接入 settings 命名空间（dsh-rss.feedsYaml）。
  *
  * @module dsh-rss
  */
@@ -12,21 +10,15 @@ import { resolveConfig } from './config.js';
 import { RSS_SETTINGS_NAMESPACE, RssSettingsSchema } from './settings.js';
 import { buildRssTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.settings 与 ctx.tools，必须显式声明，否则宿主会抛 cannot get property without inject。 */
+export const name = 'rss';
 export const inject = ['settings', 'tools'];
 /**
- * 插件入口：解析配置、注册 settings 命名空间与五个 RSS 工具。
+ * 插件入口：严格解析配置、注册 settings 命名空间、九个 RSS 工具与 OPML 写入审批门。
  * @param ctx - 宿主上下文（至少含 settings.register 与 tools.register）。
  * @param config - 插件配置（可缺省）。
  */
 export function apply(ctx, config) {
-    let cfg;
-    try {
-        cfg = resolveConfig(config);
-    }
-    catch (error) {
-        console.warn('[dsh-rss] ' + (error instanceof Error ? error.message : String(error)));
-        cfg = resolveConfig(null);
-    }
+    const cfg = resolveConfig(config);
     const settingsScope = ctx.settings.register(RSS_SETTINGS_NAMESPACE, RssSettingsSchema, {
         base: { feedsYaml: cfg.feedsYaml },
         applies: 'live',
@@ -35,12 +27,24 @@ export function apply(ctx, config) {
     for (const definition of buildRssTools(cfg, settingsScope)) {
         disposers.push(ctx.tools.register(definition));
     }
-    if (typeof ctx.on === 'function') {
-        ctx.on('dispose', () => {
-            for (const dispose of disposers)
-                dispose();
+    if (cfg.opmlWriteApproval) {
+        ctx.on('tools/pre-execute', async (exec, next) => {
+            if (exec.name !== 'rss_opml_export')
+                return next();
+            const args = typeof exec.arguments === 'object' && exec.arguments !== null
+                ? exec.arguments
+                : {};
+            const path = typeof args.path === 'string' ? args.path.trim() : '';
+            if (path === '')
+                return next();
+            const safeLabel = path.replace(/[\r\n]/g, ' ').slice(0, 200);
+            return { kind: 'ask', reason: '将 RSS 订阅列表导出并写入当前会话工作区文件：' + safeLabel };
         });
     }
+    ctx.on('dispose', () => {
+        for (const dispose of disposers)
+            dispose();
+    });
 }
 export * from './config.js';
 export * from './feeds.js';

package/lib/network.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedRssConfig } from './config.js';
+import type { RssToolExecution } from './execution.js';
+/** 可注入的 fetch 实现（测试用假 fetch 替换真网络）。 */
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    redirect?: string;
+    signal?: AbortSignal;
+}) => Promise<Response>;
+/** 可注入的 DNS 查询（测试不依赖公网 DNS）。 */
+export type DnsLookupLike = (hostname: string) => Promise<readonly {
+    address: string;
+    family: number;
+}[]>;
+export declare function assertHttpUrl(url: string): void;
+/** 仅允许可公开路由的地址，避免回环、私网、链路本地和保留地址。 */
+export declare function isBlockedNetworkAddress(address: string): boolean;
+export declare function fetchFeedXml(url: string, cfg: ResolvedRssConfig, exec: RssToolExecution | undefined, fetchImpl?: FetchLike, lookupImpl?: DnsLookupLike): Promise<{
+    xml: string;
+    finalUrl: string;
+}>;

package/lib/network.js

@@ -0,0 +1,232 @@
+/** RSS 网络边界：地址校验、重定向、响应大小与调用取消。 */
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { createProxyFetch } from './proxy-fetch.js';
+const MAX_REDIRECTS = 5;
+const PROXY_HINT = '。若该订阅源需要特殊代理（梯子）才能访问，请在 cordis.patch.yml 里给 dsh-rss 配置 proxyUrl（如 http://127.0.0.1:7890）后重启。';
+function parseHttpUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('订阅源地址必须是 http(s):// 开头的完整地址，例如 https://example.com/feed.xml。');
+    }
+    if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || parsed.hostname === '') {
+        throw new Error('订阅源地址必须是 http(s):// 开头的完整地址，例如 https://example.com/feed.xml。');
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+        throw new Error('订阅源地址不能包含用户名或密码。');
+    }
+    return parsed;
+}
+export function assertHttpUrl(url) {
+    parseHttpUrl(url);
+}
+function ipv4Bytes(address) {
+    if (isIP(address) !== 4)
+        return null;
+    return address.split('.').map((part) => Number(part));
+}
+function ipv6Words(address) {
+    let input = address.toLowerCase().replace(/^\[|\]$/g, '').split('%', 1)[0];
+    if (isIP(input) !== 6)
+        return null;
+    if (input.includes('.')) {
+        const lastColon = input.lastIndexOf(':');
+        const v4 = ipv4Bytes(input.slice(lastColon + 1));
+        if (v4 === null)
+            return null;
+        input = input.slice(0, lastColon) + ':' + ((v4[0] << 8) | v4[1]).toString(16) + ':' + ((v4[2] << 8) | v4[3]).toString(16);
+    }
+    const halves = input.split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] === '' ? [] : halves[0].split(':');
+    const right = halves.length === 1 || halves[1] === '' ? [] : halves[1].split(':');
+    const zeroCount = halves.length === 2 ? 8 - left.length - right.length : 0;
+    if (zeroCount < 0 || (halves.length === 1 && left.length !== 8))
+        return null;
+    const words = [...left, ...Array.from({ length: zeroCount }, () => '0'), ...right].map((word) => Number.parseInt(word, 16));
+    return words.length === 8 && words.every((word) => Number.isInteger(word) && word >= 0 && word <= 0xffff) ? words : null;
+}
+/** 仅允许可公开路由的地址，避免回环、私网、链路本地和保留地址。 */
+export function isBlockedNetworkAddress(address) {
+    const v4 = ipv4Bytes(address);
+    if (v4 !== null) {
+        const [a, b] = v4;
+        return a === 0
+            || a === 10
+            || a === 127
+            || (a === 100 && b >= 64 && b <= 127)
+            || (a === 169 && b === 254)
+            || (a === 172 && b >= 16 && b <= 31)
+            || (a === 192 && b === 168)
+            || (a === 198 && (b === 18 || b === 19))
+            || a >= 224;
+    }
+    const v6 = ipv6Words(address);
+    if (v6 === null)
+        return true;
+    const isUnspecified = v6.every((word) => word === 0);
+    const isLoopback = v6.slice(0, 7).every((word) => word === 0) && v6[7] === 1;
+    const isUniqueLocal = (v6[0] & 0xfe00) === 0xfc00;
+    const isLinkLocal = (v6[0] & 0xffc0) === 0xfe80;
+    const isMulticast = (v6[0] & 0xff00) === 0xff00;
+    if (isUnspecified || isLoopback || isUniqueLocal || isLinkLocal || isMulticast)
+        return true;
+    const isMappedV4 = v6.slice(0, 5).every((word) => word === 0) && v6[5] === 0xffff;
+    const isCompatibleV4 = v6.slice(0, 6).every((word) => word === 0);
+    if (isMappedV4 || isCompatibleV4) {
+        const mapped = [v6[6] >> 8, v6[6] & 0xff, v6[7] >> 8, v6[7] & 0xff].join('.');
+        return isBlockedNetworkAddress(mapped);
+    }
+    return false;
+}
+function mergedSignal(timeoutMs, callerSignal) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    return callerSignal === undefined ? timeoutSignal : AbortSignal.any([callerSignal, timeoutSignal]);
+}
+async function lookupWithSignal(hostname, lookupImpl, signal) {
+    signal.throwIfAborted();
+    return await new Promise((resolveLookup, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        void Promise.resolve().then(() => lookupImpl(hostname)).then((addresses) => {
+            signal.removeEventListener('abort', onAbort);
+            resolveLookup(addresses);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+async function assertPublicUrl(url, cfg, lookupImpl, signal) {
+    if (cfg.allowPrivateNetwork)
+        return;
+    const hostname = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        throw new Error('出于安全原因，默认禁止访问 localhost。若确需访问可信内网源，请显式配置 allowPrivateNetwork: true。');
+    }
+    if (isIP(hostname) !== 0) {
+        if (isBlockedNetworkAddress(hostname)) {
+            throw new Error('出于安全原因，默认禁止访问回环、私网、链路本地或保留地址：' + hostname + '。若确需访问可信内网源，请显式配置 allowPrivateNetwork: true。');
+        }
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await lookupWithSignal(hostname, lookupImpl, signal);
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        throw new Error('无法安全解析订阅源域名 ' + hostname + '：' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (addresses.length === 0)
+        throw new Error('无法安全解析订阅源域名 ' + hostname + '：DNS 未返回地址。');
+    const blocked = addresses.find((entry) => isBlockedNetworkAddress(entry.address));
+    if (blocked !== undefined) {
+        throw new Error('出于安全原因，域名 ' + hostname + ' 解析到了非公网地址 ' + blocked.address + '，已拒绝访问。若确需访问可信内网源，请显式配置 allowPrivateNetwork: true。');
+    }
+}
+/** 构造默认 fetch：配置了 proxyUrl 时走插件级代理。 */
+function makeFetch(cfg) {
+    if (cfg.proxyUrl === '')
+        return globalThis.fetch;
+    return createProxyFetch(cfg.proxyUrl);
+}
+/**
+ * 抓取订阅源 XML：校验地址、限时、限制体积、剥 BOM。
+ */
+async function readResponseText(response, maxBodyBytes, signal) {
+    signal.throwIfAborted();
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+        await response.body?.cancel('response body exceeds maxBodyBytes');
+        throw new Error('订阅源内容超过 ' + maxBodyBytes + ' 字节上限，已停止读取。');
+    }
+    if (response.body === null)
+        return '';
+    const reader = response.body.getReader();
+    const onAbort = () => { void reader.cancel(signal.reason).catch(() => { }); };
+    signal.addEventListener('abort', onAbort, { once: true });
+    const decoder = new TextDecoder('utf-8', { fatal: false });
+    let byteLength = 0;
+    let text = '';
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const chunk = await reader.read();
+            signal.throwIfAborted();
+            if (chunk.done)
+                break;
+            byteLength += chunk.value.byteLength;
+            if (byteLength > maxBodyBytes) {
+                await reader.cancel('response body exceeds maxBodyBytes');
+                throw new Error('订阅源内容超过 ' + maxBodyBytes + ' 字节上限，已停止读取。');
+            }
+            text += decoder.decode(chunk.value, { stream: true });
+        }
+        return text + decoder.decode();
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+        reader.releaseLock();
+    }
+}
+export async function fetchFeedXml(url, cfg, exec, fetchImpl, lookupImpl = async (hostname) => await lookup(hostname, { all: true, verbatim: true })) {
+    let currentUrl = parseHttpUrl(url);
+    const fetcher = fetchImpl ?? makeFetch(cfg);
+    const signal = mergedSignal(cfg.timeoutMs, exec?.signal);
+    let response;
+    try {
+        for (let redirectCount = 0;; redirectCount++) {
+            signal.throwIfAborted();
+            await assertPublicUrl(currentUrl, cfg, lookupImpl, signal);
+            response = await fetcher(currentUrl.href, {
+                headers: {
+                    'user-agent': cfg.userAgent,
+                    accept: 'application/rss+xml, application/atom+xml, application/xml, text/xml, */*',
+                },
+                redirect: 'manual',
+                signal,
+            });
+            signal.throwIfAborted();
+            if (![301, 302, 303, 307, 308].includes(response.status))
+                break;
+            const location = response.headers.get('location');
+            if (location === null)
+                break;
+            await response.body?.cancel('following validated redirect');
+            if (redirectCount >= MAX_REDIRECTS)
+                throw new Error('抓取失败：重定向次数超过 ' + MAX_REDIRECTS + ' 次上限。');
+            currentUrl = parseHttpUrl(new URL(location, currentUrl).href);
+        }
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        if (error instanceof Error && (error.message.includes('出于安全原因') || error.message.includes('无法安全解析') || error.message.includes('重定向次数超过')))
+            throw error;
+        throw new Error('抓取失败：' + (error instanceof Error ? error.message : String(error)) + PROXY_HINT);
+    }
+    if (response === undefined)
+        throw new Error('抓取失败：未收到服务器响应。');
+    if (!response.ok) {
+        await response.body?.cancel('unsuccessful feed response');
+        throw new Error('抓取失败：服务器返回 HTTP ' + response.status + '。');
+    }
+    const reportedUrl = response.url === '' ? currentUrl : parseHttpUrl(response.url);
+    await assertPublicUrl(reportedUrl, cfg, lookupImpl, signal);
+    let xml;
+    try {
+        xml = await readResponseText(response, cfg.maxBodyBytes, signal);
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        if (error instanceof Error && error.message.includes('字节上限'))
+            throw error;
+        throw new Error('读取订阅源内容失败：' + (error instanceof Error ? error.message : String(error)));
+    }
+    xml = xml.replace(/^\uFEFF/, '');
+    return { xml, finalUrl: reportedUrl.href };
+}

package/lib/settings.d.ts

@@ -9,10 +9,13 @@ export declare const RSS_SETTINGS_NAMESPACE = "dsh-rss";
 /** settings 页形状：目前只有订阅列表（YAML 文本）。 */
 export declare const RssSettingsSchema: z<Schemastery.ObjectS<{
     feedsYaml: z<string, string>;
+    cursorsJson: z<string, string>;
 }>, Schemastery.ObjectT<{
     feedsYaml: z<string, string>;
+    cursorsJson: z<string, string>;
 }>>;
 /** settings 解析后的值。 */
 export interface RssSettingsValue {
     feedsYaml: string;
+    cursorsJson: string;
 }

package/lib/settings.js

@@ -9,4 +9,5 @@ export const RSS_SETTINGS_NAMESPACE = 'dsh-rss';
 /** settings 页形状：目前只有订阅列表（YAML 文本）。 */
 export const RssSettingsSchema = z.object({
     feedsYaml: z.string().default(''),
+    cursorsJson: z.string().default(''),
 });