dsh-rss 0.2.0 → 0.3.1

package/lib/tools.d.ts

@@ -1,10 +1,14 @@
 /**
- * 七个面向模型的 RSS 工具：list / add / remove / fetch / check / opml_export / opml_import。
+ * 九个面向模型的 RSS 工具：list / add / remove / fetch / check / opml_export / opml_import / search / health（fetch 支持增量）。
  * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
  *
  * @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,16 +35,22 @@ 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[];
+    updatedAt: string;
+}
+/** 解析 settings 里的增量游标 JSON，损坏时返回空对象（不阻断功能）。 */
+export declare function parseCursors(json: string): Record<string, FeedCursor>;
+/** 合并本次抓到的条目 id，截断到上限，返回新游标。 */
+export declare function advanceCursor(prev: FeedCursor | undefined, entries: unknown[], now: string): FeedCursor;
+/** 用游标过滤出未见过的条目（无游标时全部视为新）。 */
+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

@@ -1,5 +1,5 @@
 /**
- * 七个面向模型的 RSS 工具：list / add / remove / fetch / check / opml_export / opml_import。
+ * 九个面向模型的 RSS 工具：list / add / remove / fetch / check / opml_export / opml_import / search / health（fetch 支持增量）。
  * 直接调用 ctx.tools.register 注册【编译好的 JSON Schema】参数与 canonical 输出。
  *
  * @module dsh-rss/tools
@@ -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',
@@ -295,14 +248,162 @@ function renderOpmlImport(_args, value) {
     }
     return [{ type: 'text', text: lines.join('\n') }];
 }
+const CURSOR_GUID_LIMIT = 200;
+/** 条目唯一 id：优先 guid，退回 link，再退回 标题|发布时间。 */
+function entryId(entry) {
+    const rec = asRecord(entry);
+    const guid = typeof rec.guid === 'string' && rec.guid !== '' ? rec.guid : '';
+    if (guid !== '')
+        return guid;
+    const link = typeof rec.link === 'string' && rec.link !== '' ? rec.link : '';
+    if (link !== '')
+        return link;
+    const title = typeof rec.title === 'string' ? rec.title : '';
+    const pubDate = typeof rec.pubDate === 'string' ? rec.pubDate : '';
+    return title + '|' + pubDate;
+}
+/** 解析 settings 里的增量游标 JSON，损坏时返回空对象（不阻断功能）。 */
+export function parseCursors(json) {
+    if (json.trim() === '')
+        return {};
+    try {
+        const value = JSON.parse(json);
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return {};
+        const out = {};
+        for (const [url, cur] of Object.entries(value)) {
+            const rec = typeof cur === 'object' && cur !== null ? cur : {};
+            const guids = Array.isArray(rec.guids) ? rec.guids.filter((g) => typeof g === 'string') : [];
+            out[url] = { guids, updatedAt: typeof rec.updatedAt === 'string' ? rec.updatedAt : '' };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** 合并本次抓到的条目 id，截断到上限，返回新游标。 */
+export function advanceCursor(prev, entries, now) {
+    const known = new Set(prev?.guids ?? []);
+    for (const entry of entries)
+        known.add(entryId(entry));
+    const guids = [...known];
+    return { guids: guids.slice(-CURSOR_GUID_LIMIT), updatedAt: now };
+}
+/** 用游标过滤出未见过的条目（无游标时全部视为新）。 */
+export function filterNewEntries(cursor, entries) {
+    if (cursor === undefined || cursor.guids.length === 0)
+        return entries;
+    const known = new Set(cursor.guids);
+    return entries.filter((entry) => !known.has(entryId(entry)));
+}
+// ---------- 搜索辅助 ----------
+/** 解析 since 参数为毫秒时间戳，非法时报错。 */
+function parseSinceMs(input) {
+    if (input === undefined)
+        return null;
+    const text = input.trim();
+    const ms = /^\d{4}-\d{2}-\d{2}$/.test(text) ? Date.parse(text + 'T00:00:00Z') : Date.parse(text);
+    if (Number.isNaN(ms)) {
+        throw new Error('since 参数不是有效日期，请给形如 2026-08-01 或 2026-08-01T00:00:00Z 的值。');
+    }
+    return ms;
+}
+/** 关键词是否命中条目的标题/摘要/正文/作者/分类（不区分大小写）。 */
+function entryMatches(entry, queryLower) {
+    const rec = asRecord(entry);
+    const fields = [];
+    for (const key of ['title', 'summary', 'content', 'author']) {
+        const value = rec[key];
+        if (typeof value === 'string')
+            fields.push(value);
+    }
+    const categories = rec.categories;
+    if (Array.isArray(categories)) {
+        for (const category of categories) {
+            if (typeof category === 'string')
+                fields.push(category);
+        }
+    }
+    return fields.some((value) => value.toLowerCase().includes(queryLower));
+}
+// ---------- 搜索与健康自检输出 Schema ----------
+const searchHitSchema = {
+    type: 'object',
+    properties: {
+        feedName: { type: 'string' },
+        feedUrl: { type: 'string' },
+        title: { type: 'string' },
+        link: { type: 'string' },
+        pubDate: { type: 'string' },
+        summary: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const searchSchema = {
+    type: 'object',
+    properties: {
+        count: { type: 'integer' },
+        hits: { type: 'array', items: searchHitSchema },
+        failedFeeds: { type: 'array', items: { type: 'object', additionalProperties: true } },
+    },
+    additionalProperties: true,
+};
+const healthSchema = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        plugin: { type: 'string' },
+        feedCount: { type: 'integer' },
+        proxyConfigured: { type: 'boolean' },
+        cursorCount: { type: 'integer' },
+        parserSelfTest: { type: 'boolean' },
+        config: { type: 'object', additionalProperties: true },
+    },
+    additionalProperties: true,
+};
+/** rss_search 的渲染。 */
+function renderSearch(_args, value) {
+    const rec = asRecord(value);
+    const hits = Array.isArray(rec.hits) ? rec.hits : [];
+    const failed = Array.isArray(rec.failedFeeds) ? rec.failedFeeds : [];
+    const lines = ['搜索命中 ' + hits.length + ' 条：'];
+    for (const hit of hits) {
+        const item = asRecord(hit);
+        const title = typeof item.title === 'string' && item.title !== '' ? item.title : '(无标题)';
+        const from = typeof item.feedName === 'string' && item.feedName !== '' ? '【' + item.feedName + '】' : '';
+        const pubDate = typeof item.pubDate === 'string' && item.pubDate !== '' ? '（' + item.pubDate + '）' : '';
+        const link = typeof item.link === 'string' && item.link !== '' ? ' ' + item.link : '';
+        lines.push('- ' + from + title + pubDate + link);
+    }
+    for (const item of failed) {
+        const row = asRecord(item);
+        lines.push('- 抓取失败 ' + String(row.name ?? row.url ?? '') + '：' + String(row.error ?? ''));
+    }
+    return [{ type: 'text', text: lines.join('\n') }];
+}
+/** rss_health 的渲染。 */
+function renderHealth(_args, value) {
+    const rec = asRecord(value);
+    const ok = rec.ok === true;
+    const lines = [
+        'dsh-rss 自检' + (ok ? '：正常。' : '：发现异常，请查看下方详情。'),
+        '- 订阅源数量：' + String(rec.feedCount ?? 0),
+        '- 特殊代理（梯子）：' + (rec.proxyConfigured === true ? '已配置' : '未配置'),
+        '- 增量游标数量：' + String(rec.cursorCount ?? 0),
+        '- 解析器自检：' + (rec.parserSelfTest === true ? '通过' : '失败'),
+    ];
+    return [{ type: 'text', text: lines.join('\n') }];
+}
 // ---------- 工具构建 ----------
 /**
- * 构建七个工具定义。每个 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();
@@ -325,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 };
         },
@@ -343,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',
@@ -377,19 +478,32 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
         },
         timeoutMs: TIMEOUT_MS,
     };
+    const readCursorsJson = () => {
+        const value = settingsScope.get();
+        return value !== null && typeof value === 'object' && typeof value.cursorsJson === 'string' ? value.cursorsJson : '';
+    };
+    const persistCursors = async (cursors) => {
+        try {
+            await settingsScope.update({ cursorsJson: JSON.stringify(cursors) });
+        }
+        catch (error) {
+            throw new Error('写入增量游标失败（可能已被其他会话修改，请重试）：' + (error instanceof Error ? error.message : String(error)));
+        }
+    };
     const rssFetch = {
         name: 'rss_fetch',
-        description: '抓取并解析一个 RSS/Atom 订阅源，返回源信息与最新条目（标题、链接、guid、发布时间、作者、摘要、分类、附件）。url 与 name 至少给一个：name 查已订阅源（同名多个时需改用 url），url 直接抓取任意地址。limit 控制返回条数（1-100，默认 20），超过部分以 truncated=true 提示。',
+        description: '抓取并解析一个 RSS/Atom 订阅源，返回源信息与最新条目（标题、链接、guid、发布时间、作者、摘要、分类、附件）。url 与 name 至少给一个：name 查已订阅源（同名多个时需改用 url），url 直接抓取任意地址。limit 控制返回条数（1-100，默认 20），超过部分以 truncated=true 提示。incremental=true 时启用增量模式：只返回上次抓取以来的新条目（按条目 id 去重，游标持久化在 settings），适合定时巡检省 token。',
         parameters: compileParameters({
             url: { type: 'string', description: '订阅源地址（可选，与 name 至少给一个）。' },
             name: { type: 'string', description: '已订阅源的名字（可选，可用 rss_list 查看）。' },
             limit: { type: 'integer', description: '返回条数，1-100，默认 20。' },
+            incremental: { type: 'boolean', description: '增量模式：只返回上次抓取后的新条目（默认 false）。' },
         }),
         output: {
             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');
@@ -408,12 +522,21 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
             }
             assertHttpUrl(url);
             const limit = clampedInteger(args, 'limit', 20, 1, 100);
-            const { xml, finalUrl } = await fetchFeedXml(url, cfg, fetchImpl);
+            const incremental = args.incremental === true;
+            const { xml, finalUrl } = await fetchFeedXml(url, cfg, exec, fetchImpl, lookupImpl);
             const parsed = parseFeed(xml, finalUrl);
-            const entries = parsed.entries.slice(0, limit);
-            return { url: finalUrl, feed: parsed.feed, entries, truncated: parsed.entries.length > limit };
+            if (!incremental) {
+                const entries = parsed.entries.slice(0, limit);
+                return { url: finalUrl, feed: parsed.feed, entries, truncated: parsed.entries.length > limit };
+            }
+            const cursors = parseCursors(readCursorsJson());
+            const fresh = filterNewEntries(cursors[url], parsed.entries);
+            cursors[url] = advanceCursor(cursors[url], parsed.entries, new Date().toISOString());
+            await persistCursors(cursors);
+            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',
@@ -425,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,
@@ -440,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',
@@ -452,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,
     };
@@ -491,5 +618,98 @@ export function buildRssTools(config, settingsScope, fetchImpl) {
         },
         timeoutMs: TIMEOUT_MS,
     };
-    return [rssList, rssAdd, rssRemove, rssFetch, rssCheck, rssOpmlExport, rssOpmlImport];
+    const rssSearch = {
+        name: 'rss_search',
+        description: '跨订阅源搜索条目：实时抓取已订阅源，对标题/摘要/正文/作者/分类做不区分大小写的关键词匹配。query 必填；name 或 url 可限定单个订阅；since 过滤发布日期（如 2026-08-01）；limit 控制返回条数（1-50，默认 20）。个别源抓取失败会单独报告，不影响其他源的搜索。',
+        parameters: compileParameters({
+            query: { type: 'string', required: true, description: '搜索关键词（必填，不区分大小写）。' },
+            name: { type: 'string', description: '只搜索这个名字的订阅（可选）。' },
+            url: { type: 'string', description: '只搜索这个地址的订阅（可选）。' },
+            since: { type: 'string', description: '只要该日期之后发布的条目（可选，如 2026-08-01）。' },
+            limit: { type: 'integer', description: '返回条数，1-50，默认 20。' },
+        }),
+        output: {
+            schema: searchSchema,
+            render: renderSearch,
+        },
+        async execute(rawArgs, exec) {
+            const args = asRecord(rawArgs);
+            const query = requiredString(args, 'query', '搜索关键词').toLowerCase();
+            const limit = clampedInteger(args, 'limit', 20, 1, 50);
+            const sinceMs = parseSinceMs(optionalString(args, 'since'));
+            const urlFilter = optionalString(args, 'url');
+            const nameFilter = optionalString(args, 'name');
+            let targets = getFeeds();
+            if (urlFilter !== undefined)
+                targets = targets.filter((feed) => feed.url.toLowerCase() === urlFilter.toLowerCase());
+            if (nameFilter !== undefined)
+                targets = findFeedsByName(targets, nameFilter);
+            if (targets.length === 0) {
+                if (urlFilter !== undefined || nameFilter !== undefined) {
+                    throw new Error('没有找到匹配的订阅。可用 rss_list 查看订阅列表。');
+                }
+                throw new Error('当前还没有订阅。请先用 rss_add 添加订阅。');
+            }
+            const hits = [];
+            const failedFeeds = [];
+            for (const feed of targets) {
+                if (hits.length >= limit)
+                    break;
+                try {
+                    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);
+                        const at = Date.parse(typeof rec.pubDate === 'string' ? rec.pubDate : '');
+                        if (sinceMs !== null && !Number.isNaN(at) && at < sinceMs)
+                            continue;
+                        if (entryMatches(entry, query)) {
+                            hits.push({ feedName: feed.name, feedUrl: feed.url, ...rec });
+                            if (hits.length >= limit)
+                                break;
+                        }
+                    }
+                }
+                catch (error) {
+                    exec?.signal.throwIfAborted();
+                    failedFeeds.push({ url: feed.url, name: feed.name, error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return { count: hits.length, hits, failedFeeds };
+        },
+        timeoutMs: Math.min(300000, Math.max(TIMEOUT_MS, cfg.timeoutMs * 10)),
+    };
+    const rssHealth = {
+        name: 'rss_health',
+        description: 'dsh-rss 自检：检查配置有效性、订阅数量、增量游标与解析器自检（不发任何网络请求）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: healthSchema,
+            render: renderHealth,
+        },
+        async execute() {
+            const feeds = getFeeds();
+            const settingsValue = settingsScope.get();
+            const cursorsJson = settingsValue !== null && typeof settingsValue === 'object' && typeof settingsValue.cursorsJson === 'string' ? settingsValue.cursorsJson : '';
+            let parserSelfTest = false;
+            try {
+                const sample = parseFeed('<?xml version="1.0"?><rss version="2.0"><channel><title>selftest</title><item><title>item</title></item></channel></rss>', 'https://selftest.local/');
+                parserSelfTest = sample.entries.length === 1 && sample.feed.feedType === 'rss';
+            }
+            catch {
+                parserSelfTest = false;
+            }
+            return {
+                ok: parserSelfTest,
+                plugin: 'dsh-rss',
+                feedCount: feeds.length,
+                proxyConfigured: cfg.proxyUrl !== '',
+                cursorCount: Object.keys(parseCursors(cursorsJson)).length,
+                parserSelfTest,
+                config: { timeoutMs: cfg.timeoutMs, maxBodyBytes: cfg.maxBodyBytes, userAgent: cfg.userAgent },
+            };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    return [rssList, rssAdd, rssRemove, rssFetch, rssCheck, rssOpmlExport, rssOpmlImport, rssSearch, rssHealth];
 }

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;
+}