dsh-rss 0.3.0 → 0.3.1

package/README.en.md

@@ -1,12 +1,18 @@
 # 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
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+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
 
@@ -86,9 +92,9 @@ 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
 
-MIT
+MIT

package/README.md

@@ -13,7 +13,11 @@ DSH（DeepSeek Harness）的 RSS/Atom 订阅工具插件：管理订阅源，抓
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+按 `@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 文本。
 
 ## 安装
 
@@ -95,11 +99,11 @@ rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
 
 ```bash
 pnpm install
-pnpm test       # 构建 + 63 个测试
+pnpm test       # 构建 + 离线测试（fetch 与 DNS 均使用夹具）
 ```
 
 发布前门禁：危险模式扫描、manifest 自检、`pnpm audit --prod`、全量测试，以及全新 profile 的真实启动冒烟测试。
 
 ## License
 
-MIT
+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,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
  */
@@ -13,6 +11,20 @@ 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: {
@@ -24,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
  */
@@ -15,19 +13,12 @@ import { buildRssTools } from './tools.js';
 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',
@@ -36,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/tools.d.ts

@@ -5,6 +5,10 @@
  * @module dsh-rss/tools
  */
 import { type ResolvedRssConfig } from './config.js';
+import type { RssToolExecution } from './execution.js';
+import { type FetchLike, type DnsLookupLike } from './network.js';
+export type { RssToolExecution } from './execution.js';
+export { isBlockedNetworkAddress, type FetchLike, type DnsLookupLike } from './network.js';
 /** 模型可见的内容块。 */
 export interface ContentBlock {
     type: 'text';
@@ -23,7 +27,7 @@ export interface RssToolDefinition {
         schema: Record<string, unknown>;
         render(args: unknown, value: unknown): ContentBlock[];
     };
-    execute(args: unknown, exec: unknown): Promise<unknown>;
+    execute(args: unknown, exec?: RssToolExecution): Promise<unknown>;
     timeoutMs?: number;
 }
 /** 工具所需的 settings scope 最小面。 */
@@ -31,12 +35,6 @@ export interface RssSettingsScope {
     get(): unknown;
     update(patch: Record<string, unknown>): Promise<void>;
 }
-/** 可注入的 fetch 实现（测试用假 fetch 替换真网络）。 */
-export type FetchLike = (url: string, init?: {
-    headers?: Record<string, string>;
-    redirect?: string;
-    signal?: AbortSignal;
-}) => Promise<Response>;
 /** 单个订阅源的增量游标：已知条目 id 列表与更新时间。 */
 export interface FeedCursor {
     guids: string[];
@@ -49,9 +47,10 @@ export declare function advanceCursor(prev: FeedCursor | undefined, entries: unk
 /** 用游标过滤出未见过的条目（无游标时全部视为新）。 */
 export declare function filterNewEntries(cursor: FeedCursor | undefined, entries: unknown[]): unknown[];
 /**
- * 构建七个工具定义。每个 execute 惰性读取配置与订阅，错误时抛出中文指引。
+ * 构建九个工具定义。每个 execute 惰性读取配置与订阅，错误时抛出中文指引。
  * @param config - 已解析配置。
  * @param settingsScope - dsh-rss settings scope（get/update）。
  * @param fetchImpl - 可选注入的 fetch（测试用），缺省按 proxyUrl 构造。
+ * @param lookupImpl - 可选注入的 DNS 查询（测试用），缺省使用系统 DNS。
  */
-export declare function buildRssTools(config: ResolvedRssConfig, settingsScope: RssSettingsScope, fetchImpl?: FetchLike): RssToolDefinition[];
+export declare function buildRssTools(config: ResolvedRssConfig, settingsScope: RssSettingsScope, fetchImpl?: FetchLike, lookupImpl?: DnsLookupLike): RssToolDefinition[];

package/lib/tools.js

@@ -8,9 +8,10 @@ import { writeFile } from 'node:fs/promises';
 import { addFeed, findFeedsByName, parseFeedsYaml, removeFeed, serializeFeeds } from './feeds.js';
 import { buildOpml, importOpmlFeeds, parseOpml } from './opml.js';
 import { parseFeed } from './parser.js';
-import { createProxyFetch } from './proxy-fetch.js';
+import { assertHttpUrl, fetchFeedXml } from './network.js';
+import { resolveOpmlOutputPath } from './workspace.js';
+export { isBlockedNetworkAddress } from './network.js';
 const TIMEOUT_MS = 30000;
-const PROXY_HINT = '。若该订阅源需要特殊代理（梯子）才能访问，请在 cordis.patch.yml 里给 dsh-rss 配置 proxyUrl（如 http://127.0.0.1:7890）后重启。';
 /**
  * 编译作者 DSL 为原始 JSON Schema（正是 defineTool 存为 definition.parameters 的值）。
  * 原生线路会原样下发该值，原始 DSL 会被模型 API 拒绝（schema must be a JSON Schema）。
@@ -56,54 +57,6 @@ function clampedInteger(args, key, fallback, min, max) {
         return fallback;
     return Math.min(max, Math.max(min, value));
 }
-function assertHttpUrl(url) {
-    if (!/^https?:\/\//i.test(url)) {
-        throw new Error('订阅源地址必须是 http(s):// 开头的完整地址，例如 https://example.com/feed.xml。');
-    }
-}
-/** 构造默认 fetch：配置了 proxyUrl 时走插件级代理。 */
-function makeFetch(cfg) {
-    if (cfg.proxyUrl === '')
-        return globalThis.fetch;
-    return createProxyFetch(cfg.proxyUrl);
-}
-/**
- * 抓取订阅源 XML：校验地址、限时、限制体积、剥 BOM。
- */
-async function fetchFeedXml(url, cfg, fetchImpl) {
-    assertHttpUrl(url);
-    const fetcher = fetchImpl ?? makeFetch(cfg);
-    let response;
-    try {
-        response = await fetcher(url, {
-            headers: {
-                'user-agent': cfg.userAgent,
-                accept: 'application/rss+xml, application/atom+xml, application/xml, text/xml, */*',
-            },
-            redirect: 'follow',
-            signal: AbortSignal.timeout(cfg.timeoutMs),
-        });
-    }
-    catch (error) {
-        throw new Error('抓取失败：' + (error instanceof Error ? error.message : String(error)) + PROXY_HINT);
-    }
-    if (!response.ok) {
-        throw new Error('抓取失败：服务器返回 HTTP ' + response.status + '。');
-    }
-    let bytes;
-    try {
-        bytes = new Uint8Array(await response.arrayBuffer());
-    }
-    catch (error) {
-        throw new Error('读取订阅源内容失败：' + (error instanceof Error ? error.message : String(error)));
-    }
-    if (bytes.length > cfg.maxBodyBytes) {
-        throw new Error('订阅源内容超过 ' + cfg.maxBodyBytes + ' 字节上限，已停止读取。');
-    }
-    let xml = new TextDecoder('utf-8', { fatal: false }).decode(bytes);
-    xml = xml.replace(/^\uFEFF/, '');
-    return { xml, finalUrl: response.url || url };
-}
 // ---------- 输出 JSON Schema ----------
 const feedItemSchema = {
     type: 'object',
@@ -444,12 +397,13 @@ function renderHealth(_args, value) {
 }
 // ---------- 工具构建 ----------
 /**
- * 构建七个工具定义。每个 execute 惰性读取配置与订阅，错误时抛出中文指引。
+ * 构建九个工具定义。每个 execute 惰性读取配置与订阅，错误时抛出中文指引。
  * @param config - 已解析配置。
  * @param settingsScope - dsh-rss settings scope（get/update）。
  * @param fetchImpl - 可选注入的 fetch（测试用），缺省按 proxyUrl 构造。
+ * @param lookupImpl - 可选注入的 DNS 查询（测试用），缺省使用系统 DNS。
  */
-export function buildRssTools(config, settingsScope, fetchImpl) {
+export function buildRssTools(config, settingsScope, fetchImpl, lookupImpl) {
     const cfg = config;
     const getFeeds = () => {
         const value = settingsScope.get();
@@ -472,7 +426,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: listSchema,
             render: renderList,
         },
-        async execute(rawArgs) {
+        async execute() {
             const feeds = getFeeds();
             return { count: feeds.length, feeds };
         },
@@ -490,20 +444,20 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: addSchema,
             render: renderAdd,
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const url = requiredString(args, 'url', '订阅源地址');
             assertHttpUrl(url);
             const name = optionalString(args, 'name') ?? '';
             const category = optionalString(args, 'category') ?? '';
-            const { xml, finalUrl } = await fetchFeedXml(url, cfg, fetchImpl);
+            const { xml, finalUrl } = await fetchFeedXml(url, cfg, exec, fetchImpl, lookupImpl);
             const parsed = parseFeed(xml, finalUrl);
             const effectiveName = name !== '' ? name : parsed.feed.title;
             const { feeds, added, existed } = addFeed(getFeeds(), url, effectiveName, category);
             await persistFeeds(feeds);
             return { added, existed, count: feeds.length, feedTitle: parsed.feed.title, feedType: parsed.feed.feedType };
         },
-        timeoutMs: TIMEOUT_MS,
+        timeoutMs: cfg.timeoutMs,
     };
     const rssRemove = {
         name: 'rss_remove',
@@ -549,7 +503,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: fetchSchema,
             render: renderFetch,
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             let url = optionalString(args, 'url');
             const name = optionalString(args, 'name');
@@ -569,7 +523,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             assertHttpUrl(url);
             const limit = clampedInteger(args, 'limit', 20, 1, 100);
             const incremental = args.incremental === true;
-            const { xml, finalUrl } = await fetchFeedXml(url, cfg, fetchImpl);
+            const { xml, finalUrl } = await fetchFeedXml(url, cfg, exec, fetchImpl, lookupImpl);
             const parsed = parseFeed(xml, finalUrl);
             if (!incremental) {
                 const entries = parsed.entries.slice(0, limit);
@@ -582,7 +536,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             const entries = fresh.slice(0, limit);
             return { url: finalUrl, feed: parsed.feed, entries, truncated: fresh.length > limit, incremental: true, newCount: fresh.length };
         },
-        timeoutMs: TIMEOUT_MS,
+        timeoutMs: cfg.timeoutMs,
     };
     const rssCheck = {
         name: 'rss_check',
@@ -594,11 +548,11 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: checkSchema,
             render: renderCheck,
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const url = requiredString(args, 'url', '订阅源地址');
             assertHttpUrl(url);
-            const { xml, finalUrl } = await fetchFeedXml(url, cfg, fetchImpl);
+            const { xml, finalUrl } = await fetchFeedXml(url, cfg, exec, fetchImpl, lookupImpl);
             const parsed = parseFeed(xml, finalUrl);
             return {
                 ok: true,
@@ -609,7 +563,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
                 description: parsed.feed.description,
             };
         },
-        timeoutMs: TIMEOUT_MS,
+        timeoutMs: cfg.timeoutMs,
     };
     const rssOpmlExport = {
         name: 'rss_opml_export',
@@ -621,15 +575,19 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: opmlExportSchema,
             render: renderOpmlExport,
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const feeds = getFeeds();
             const opml = buildOpml(feeds);
             const target = optionalString(args, 'path');
+            let outputPath = '';
             if (target !== undefined) {
-                await writeFile(target, opml, 'utf8');
+                exec?.signal.throwIfAborted();
+                outputPath = await resolveOpmlOutputPath(target, exec);
+                exec?.signal.throwIfAborted();
+                await writeFile(outputPath, opml, { encoding: 'utf8', signal: exec?.signal });
             }
-            return { opml, path: target ?? '', feedCount: feeds.length };
+            return { opml, path: outputPath, feedCount: feeds.length };
         },
         timeoutMs: TIMEOUT_MS,
     };
@@ -674,7 +632,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             schema: searchSchema,
             render: renderSearch,
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const query = requiredString(args, 'query', '搜索关键词').toLowerCase();
             const limit = clampedInteger(args, 'limit', 20, 1, 50);
@@ -698,7 +656,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
                 if (hits.length >= limit)
                     break;
                 try {
-                    const { xml, finalUrl } = await fetchFeedXml(feed.url, cfg, fetchImpl);
+                    const { xml, finalUrl } = await fetchFeedXml(feed.url, cfg, exec, fetchImpl, lookupImpl);
                     const parsed = parseFeed(xml, finalUrl);
                     for (const entry of parsed.entries) {
                         const rec = asRecord(entry);
@@ -713,6 +671,7 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
                     }
                 }
                 catch (error) {
+                    exec?.signal.throwIfAborted();
                     failedFeeds.push({ url: feed.url, name: feed.name, error: error instanceof Error ? error.message : String(error) });
                 }
             }

package/lib/workspace.d.ts

@@ -0,0 +1,6 @@
+import type { RssToolExecution } from './execution.js';
+/**
+ * 把模型给出的 OPML 相对路径约束在本次调用的 session cwd 内。
+ * 同时解析父目录的真实路径并拒绝目标符号链接，避免通过链接越界。
+ */
+export declare function resolveOpmlOutputPath(requestedPath: string, exec: RssToolExecution | undefined): Promise<string>;

package/lib/workspace.js

@@ -0,0 +1,42 @@
+/** 将 OPML 文件输出约束在工具调用所属的会话工作区。 */
+import { lstat, realpath } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, relative, resolve, sep, win32 } from 'node:path';
+function isWithin(root, target) {
+    const rel = relative(root, target);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel));
+}
+/**
+ * 把模型给出的 OPML 相对路径约束在本次调用的 session cwd 内。
+ * 同时解析父目录的真实路径并拒绝目标符号链接，避免通过链接越界。
+ */
+export async function resolveOpmlOutputPath(requestedPath, exec) {
+    if (isAbsolute(requestedPath) || win32.isAbsolute(requestedPath)) {
+        throw new Error('OPML 输出 path 必须是相对当前会话工作区的路径，不能使用绝对路径。');
+    }
+    const sessionCwd = exec?.agent?.session.header.cwd;
+    if (typeof sessionCwd !== 'string' || sessionCwd.trim() === '') {
+        throw new Error('无法确定本次调用的 session cwd，已拒绝写入 OPML 文件。');
+    }
+    const lexicalRoot = resolve(sessionCwd);
+    const lexicalTarget = resolve(lexicalRoot, requestedPath);
+    if (!isWithin(lexicalRoot, lexicalTarget)) {
+        throw new Error('OPML 输出 path 不能越过当前会话工作区。');
+    }
+    const canonicalRoot = await realpath(lexicalRoot);
+    const canonicalParent = await realpath(dirname(lexicalTarget));
+    const canonicalTarget = resolve(canonicalParent, basename(lexicalTarget));
+    if (!isWithin(canonicalRoot, canonicalTarget)) {
+        throw new Error('OPML 输出 path 通过符号链接越过了当前会话工作区。');
+    }
+    try {
+        const stat = await lstat(lexicalTarget);
+        if (stat.isSymbolicLink())
+            throw new Error('OPML 输出目标不能是符号链接。');
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+        if (code !== 'ENOENT')
+            throw error;
+    }
+    return canonicalTarget;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rss",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DSH RSS 订阅工具插件：管理订阅源、OPML 导入导出、抓取解析 RSS/Atom 并保留正文（rss_list / rss_add / rss_remove / rss_fetch / rss_check / rss_opml_export / rss_opml_import）",
   "type": "module",
   "main": "lib/index.js",