dsh-rss 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# dsh-rss
+
+DSH（DeepSeek Harness）的 RSS/Atom 订阅工具插件：管理订阅源，抓取并解析 RSS 0.9x / 1.0 / 2.0 与 Atom，给模型提供五个可直接调用的工具。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-rss
+```
+
+安装后重启 Web 服务即可。
+
+## 配置
+
+在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时插件也能加载，只是全部用默认值）：
+
+```yaml
+- id: rss
+  name: 'dsh-rss'
+  config:
+    # proxyUrl: http://127.0.0.1:7890   # 部分订阅源需要特殊代理（梯子）才能访问时启用
+    timeoutMs: 15000                     # 抓取超时（毫秒，默认 15000）
+    # maxBodyBytes: 5242880              # 订阅源体积上限（默认 5MB，防超大响应）
+    # userAgent: 'dsh-rss/0.1.0'         # 自定义抓取 UA
+    # feedsYaml: |                        # 可选：预置订阅列表（也可用 rss_add 工具添加）
+    #   - url: https://example.com/feed.xml
+    #     name: 示例订阅
+    #     category: 技术
+```
+
+## 工具一览
+
+| 工具 | 作用 | 关键参数 |
+| :-- | :-- | :-- |
+| `rss_list` | 列出已订阅源 | 无 |
+| `rss_add` | 添加订阅（先抓取校验地址） | `url` 必填；`name`/`category` 可选 |
+| `rss_remove` | 删除订阅 | `url` 或 `name` 至少一个 |
+| `rss_fetch` | 抓取解析订阅源，返回源信息与条目 | `url` 或 `name` 至少一个；`limit` 1-100 默认 20 |
+| `rss_check` | 校验地址是否为可解析的订阅源 | `url` 必填 |
+
+### 示例
+
+```text
+rss_add { url: https://example.com/feed.xml, name: 我的订阅 }
+rss_fetch { name: 我的订阅, limit: 10 }
+rss_check { url: https://example.com/feed.xml }
+```
+
+## 订阅存储
+
+订阅列表保存在 settings 的 `dsh-rss` 命名空间（`feedsYaml` 字段）里：`rss_add` / `rss_remove` 会自动读写并持久化，重启后仍在；也可以在配置里用 `feedsYaml` 预置初始订阅。同名订阅请用 `url` 区分。
+
+## 特殊代理（梯子）
+
+大部分订阅源可以直接访问；少数订阅源需要特殊代理（梯子）才能连通。遇到 `抓取失败` 且提示需要代理时，把 `proxyUrl` 配成你的本地代理地址（如 `http://127.0.0.1:7890`）并重启即可。代理只作用于本插件的抓取请求，不影响同进程其他插件。
+
+## 解析能力
+
+- RSS 2.0 / RSS 1.0（RDF）/ Atom 三种格式，统一归一化输出
+- 实体解码、CDATA、`content:encoded`、`dc:creator`、`itunes` 等常见字段
+- RFC 822 / ISO 8601 日期统一转 ISO 8601 UTC（`pubDate`），原始文本保留在 `pubDateRaw`
+- 相对链接按订阅源地址解析成绝对链接
+- 摘要去 HTML 标签并截断到 500 字符；正文全文读取在后续版本提供
+- 安全：不解析 DTD/外部实体，内容只做文本抽取；响应体积上限 5MB；抓取超时可配
+
+## 开发
+
+```bash
+pnpm install
+pnpm test       # 构建 + 47 个测试
+```
+
+发布前门禁：危险模式扫描、manifest 自检、`pnpm audit --prod`、全量测试，以及全新 profile 的真实启动冒烟测试。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-rss 组合包补丁：把 RSS 订阅工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载，但每个工具在调用时
+# 会抛出带中文指引的错误，提示补全配置后重启。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: rss
+#     name: 'dsh-rss'
+#     config:
+#       # proxyUrl: http://127.0.0.1:7890   # 部分订阅源需要特殊代理（梯子）时启用
+#       timeoutMs: 15000                     # 抓取超时（毫秒）
+#       # feedsYaml: |                        # 可选：预置订阅列表（也可用 rss_add 工具添加）
+#       #   - url: https://example.com/feed.xml
+#       #     name: 示例订阅
+#
+- insert:
+    - id: rss
+      name: 'dsh-rss'
+      config:
+        timeoutMs: 15000

package/lib/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * dsh-rss 配置解析：把 cordis.patch.yml 里的行配置解析成强类型配置。
+ * 缺失字段给默认值；非法字段抛出带中文指引的错误。
+ *
+ * @module dsh-rss/config
+ */
+/** 插件行配置（cordis.patch.yml 里的 config 段，可缺省）。 */
+export interface RssConfig {
+    proxyUrl?: string;
+    timeoutMs?: number;
+    maxBodyBytes?: number;
+    userAgent?: string;
+    feedsYaml?: string;
+}
+/** 解析后的配置：所有字段都有值。 */
+export interface ResolvedRssConfig {
+    proxyUrl: string;
+    timeoutMs: number;
+    maxBodyBytes: number;
+    userAgent: string;
+    feedsYaml: string;
+}
+/**
+ * 解析并校验配置。
+ * @param config - 插件行配置（可能为 undefined/null）。
+ * @throws 配置值非法时抛出中文错误。
+ */
+export declare function resolveConfig(config: RssConfig | undefined | null): ResolvedRssConfig;

package/lib/config.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-rss 配置解析：把 cordis.patch.yml 里的行配置解析成强类型配置。
+ * 缺失字段给默认值；非法字段抛出带中文指引的错误。
+ *
+ * @module dsh-rss/config
+ */
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_MAX_BODY_BYTES = 5 * 1024 * 1024;
+const DEFAULT_USER_AGENT = 'dsh-rss/0.1.0 (DeepSeek Harness RSS plugin)';
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * 解析并校验配置。
+ * @param config - 插件行配置（可能为 undefined/null）。
+ * @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。');
+    }
+    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。');
+        }
+        timeoutMs = Math.min(120000, Math.max(1000, Math.round(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。');
+        }
+        maxBodyBytes = Math.min(50 * 1024 * 1024, Math.max(1024 * 1024, Math.round(cfg.maxBodyBytes)));
+    }
+    const userAgent = optionalString(cfg.userAgent) ?? DEFAULT_USER_AGENT;
+    const feedsYaml = optionalString(cfg.feedsYaml) ?? '';
+    return { proxyUrl, timeoutMs, maxBodyBytes, userAgent, feedsYaml };
+}

package/lib/feeds.d.ts

@@ -0,0 +1,30 @@
+/** 单个订阅。 */
+export interface Feed {
+    url: string;
+    name: string;
+    category: string;
+}
+/**
+ * 解析 feedsYaml 为订阅数组。空文本返回空数组；非法 YAML / 缺 url 抛中文错误。
+ */
+export declare function parseFeedsYaml(text: string): Feed[];
+/** 订阅数组序列化回 YAML 文本（带使用说明头）。 */
+export declare function serializeFeeds(feeds: Feed[]): string;
+/**
+ * 添加订阅：按 url（不区分大小写）去重；已存在时合并更新 name/category。
+ */
+export declare function addFeed(feeds: Feed[], url: string, name: string, category: string): {
+    feeds: Feed[];
+    added: Feed;
+    existed: boolean;
+};
+/**
+ * 删除订阅：url 精确匹配（不区分大小写），或 name 匹配所有同名项（不区分大小写）。
+ * 两者都缺或没有匹配项时抛中文错误。
+ */
+export declare function removeFeed(feeds: Feed[], url?: string, name?: string): {
+    feeds: Feed[];
+    removed: Feed[];
+};
+/** 按名字找订阅（不区分大小写）。 */
+export declare function findFeedsByName(feeds: Feed[], name: string): Feed[];

package/lib/feeds.js

@@ -0,0 +1,118 @@
+/**
+ * 订阅列表存取：feedsYaml（settings 里的 YAML 文本）与 Feed 对象数组互转。
+ *
+ * @module dsh-rss/feeds
+ */
+import YAML from 'yaml';
+const FEEDS_HEADER = [
+    '# dsh-rss 订阅源列表',
+    '# 每行一个订阅：url 必填，name（显示名）与 category（分类）可选。',
+    '# 也可以直接写字符串：- https://example.com/feed.xml',
+    '',
+];
+/**
+ * 解析 feedsYaml 为订阅数组。空文本返回空数组；非法 YAML / 缺 url 抛中文错误。
+ */
+export function parseFeedsYaml(text) {
+    const trimmed = (text ?? '').trim();
+    if (trimmed === '')
+        return [];
+    let raw;
+    try {
+        raw = YAML.parse(trimmed);
+    }
+    catch (error) {
+        throw new Error('订阅配置（feedsYaml）不是合法的 YAML：' + (error instanceof Error ? error.message : String(error)) + '。请在设置页修正 dsh-rss 的订阅列表。');
+    }
+    if (raw === null || raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new Error('订阅配置（feedsYaml）必须是一个列表（每行 - url: ...）。请在设置页修正 dsh-rss 的订阅列表。');
+    }
+    const feeds = [];
+    for (let index = 0; index < raw.length; index++) {
+        const item = raw[index];
+        let url = '';
+        let name = '';
+        let category = '';
+        if (typeof item === 'string') {
+            url = item.trim();
+        }
+        else if (typeof item === 'object' && item !== null) {
+            const rec = item;
+            url = typeof rec.url === 'string' ? rec.url.trim() : '';
+            name = typeof rec.name === 'string' ? rec.name.trim() : '';
+            category = typeof rec.category === 'string' ? rec.category.trim() : '';
+        }
+        if (url === '') {
+            throw new Error('订阅配置（feedsYaml）第 ' + (index + 1) + ' 项缺少 url 字段。请在设置页修正 dsh-rss 的订阅列表。');
+        }
+        feeds.push({ url, name, category });
+    }
+    return feeds;
+}
+/** 订阅数组序列化回 YAML 文本（带使用说明头）。 */
+export function serializeFeeds(feeds) {
+    const rows = [];
+    for (const feed of feeds) {
+        const rec = { url: feed.url };
+        if (feed.name !== '')
+            rec.name = feed.name;
+        if (feed.category !== '')
+            rec.category = feed.category;
+        rows.push(rec);
+    }
+    const body = YAML.stringify(rows).trimEnd();
+    return FEEDS_HEADER.join('\n') + body + '\n';
+}
+function sameUrl(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+/**
+ * 添加订阅：按 url（不区分大小写）去重；已存在时合并更新 name/category。
+ */
+export function addFeed(feeds, url, name, category) {
+    const cleanUrl = url.trim();
+    const cleanName = name.trim();
+    const cleanCategory = category.trim();
+    const existing = feeds.find((feed) => sameUrl(feed.url, cleanUrl));
+    if (existing) {
+        const merged = {
+            url: existing.url,
+            name: cleanName !== '' ? cleanName : existing.name,
+            category: cleanCategory !== '' ? cleanCategory : existing.category,
+        };
+        const next = feeds.map((feed) => feed === existing ? merged : feed);
+        return { feeds: next, added: merged, existed: true };
+    }
+    const added = { url: cleanUrl, name: cleanName, category: cleanCategory };
+    return { feeds: [...feeds, added], added, existed: false };
+}
+/**
+ * 删除订阅：url 精确匹配（不区分大小写），或 name 匹配所有同名项（不区分大小写）。
+ * 两者都缺或没有匹配项时抛中文错误。
+ */
+export function removeFeed(feeds, url, name) {
+    const cleanUrl = (url ?? '').trim();
+    const cleanName = (name ?? '').trim();
+    if (cleanUrl === '' && cleanName === '') {
+        throw new Error('删除订阅需要提供 url 或 name 参数（至少一个）。');
+    }
+    const removed = [];
+    const next = feeds.filter((feed) => {
+        const match = (cleanUrl !== '' && sameUrl(feed.url, cleanUrl)) || (cleanName !== '' && feed.name.toLowerCase() === cleanName.toLowerCase());
+        if (match)
+            removed.push(feed);
+        return !match;
+    });
+    if (removed.length === 0) {
+        const hint = cleanUrl !== '' ? '（url=' + cleanUrl + '）' : '（name=' + cleanName + '）';
+        throw new Error('没有找到匹配的订阅' + hint + '。可用 rss_list 查看已订阅源。');
+    }
+    return { feeds: next, removed };
+}
+/** 按名字找订阅（不区分大小写）。 */
+export function findFeedsByName(feeds, name) {
+    const needle = name.trim().toLowerCase();
+    return feeds.filter((feed) => feed.name.trim().toLowerCase() === needle);
+}

package/lib/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * dsh-rss —— RSS/Atom 订阅工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把五个面向模型的工具（rss_list / rss_add / rss_remove /
+ * rss_fetch / rss_check）注册进宿主进程的工具注册表，并把订阅列表接入 settings
+ * 命名空间（dsh-rss.feedsYaml）。配置缺失时插件照常加载，工具在 execute 时才抛出
+ * 带中文指引的错误。
+ *
+ * @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 inject: string[];
+/** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
+export interface RssPluginContext {
+    settings: {
+        register(ns: string, schema: unknown, options?: {
+            base?: Record<string, unknown>;
+            applies?: string;
+        }): RssSettingsScope;
+    };
+    tools: {
+        register(definition: RssToolDefinition): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置、注册 settings 命名空间与五个 RSS 工具。
+ * @param ctx - 宿主上下文（至少含 settings.register 与 tools.register）。
+ * @param config - 插件配置（可缺省）。
+ */
+export declare function apply(ctx: RssPluginContext, config?: RssConfig | null): void;
+export * from './config.js';
+export * from './feeds.js';
+export * from './parser.js';
+export * from './proxy-fetch.js';
+export * from './settings.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,50 @@
+/**
+ * dsh-rss —— RSS/Atom 订阅工具插件（node 半身，配置走 cordis.patch.yml）。
+ *
+ * 插件导出 apply(ctx, config)：把五个面向模型的工具（rss_list / rss_add / rss_remove /
+ * rss_fetch / rss_check）注册进宿主进程的工具注册表，并把订阅列表接入 settings
+ * 命名空间（dsh-rss.feedsYaml）。配置缺失时插件照常加载，工具在 execute 时才抛出
+ * 带中文指引的错误。
+ *
+ * @module dsh-rss
+ */
+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 inject = ['settings', 'tools'];
+/**
+ * 插件入口：解析配置、注册 settings 命名空间与五个 RSS 工具。
+ * @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 settingsScope = ctx.settings.register(RSS_SETTINGS_NAMESPACE, RssSettingsSchema, {
+        base: { feedsYaml: cfg.feedsYaml },
+        applies: 'live',
+    });
+    const disposers = [];
+    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();
+        });
+    }
+}
+export * from './config.js';
+export * from './feeds.js';
+export * from './parser.js';
+export * from './proxy-fetch.js';
+export * from './settings.js';
+export * from './tools.js';

package/lib/parser.d.ts

@@ -0,0 +1,42 @@
+/** 条目附件（播客等）。 */
+export interface RssEnclosure {
+    url: string;
+    type: string;
+    length: string;
+}
+/** 归一化后的条目。所有字符串字段都有值，categories 恒为数组，enclosure 缺省时省略。 */
+export interface RssEntry {
+    title: string;
+    link: string;
+    guid: string;
+    pubDate: string;
+    pubDateRaw: string;
+    author: string;
+    summary: string;
+    categories: string[];
+    enclosure?: RssEnclosure;
+}
+/** 订阅源元信息。 */
+export interface RssFeedMeta {
+    url: string;
+    title: string;
+    link: string;
+    description: string;
+    language: string;
+    lastBuildDate: string;
+    generator: string;
+    feedType: 'rss' | 'atom' | 'rdf';
+    entryCount: number;
+}
+/** 解析结果。 */
+export interface ParsedFeed {
+    feed: RssFeedMeta;
+    entries: RssEntry[];
+}
+/**
+ * 解析 XML 文本为归一化结构。
+ * @param xmlText - 订阅源 XML 原文。
+ * @param url - 订阅源地址（用于解析相对链接）。
+ * @throws 内容为空 / XML 非法 / 缺少 feed 根元素时抛中文错误。
+ */
+export declare function parseFeed(xmlText: string, url: string): ParsedFeed;