dsh-rss 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.en.md +42 -127
  3. package/README.md +42 -133
  4. package/cordis.patch.yml +3 -1
  5. package/docs/CHANGELOG.en.md +27 -0
  6. package/docs/USAGE.en.md +104 -0
  7. package/docs/USAGE.md +105 -0
  8. package/docs/VALIDATION.md +25 -0
  9. package/docs/validation-2026-10-02-fakeip.md +32 -0
  10. package/docs/validation-language-2026-10-03.md +16 -0
  11. package/lib/client.js +21 -4
  12. package/lib/config.d.ts +4 -0
  13. package/lib/config.js +4 -2
  14. package/lib/network.js +83 -98
  15. package/lib/proxy-fetch.d.ts +6 -0
  16. package/lib/proxy-fetch.js +42 -1
  17. package/lib/public-dns.d.ts +3 -0
  18. package/lib/public-dns.js +49 -0
  19. package/lib/response.d.ts +2 -0
  20. package/lib/response.js +37 -0
  21. package/lib/settings.d.ts +4 -0
  22. package/lib/settings.js +1 -0
  23. package/lib/system-proxy.d.ts +7 -0
  24. package/lib/system-proxy.js +52 -0
  25. package/package.json +11 -7
package/CHANGELOG.md ADDED
@@ -0,0 +1,34 @@
1
+ # 更新记录
2
+
3
+ [返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
4
+
5
+ [历史英文记录](docs/CHANGELOG.en.md)
6
+
7
+ ## 0.5.2 (2026-10-03)
8
+
9
+ - 修复语言切换时菜单滞后一轮；订阅检查、OPML 跳过原因与后台错误引导支持英文，订阅名称和文章保留原文。
10
+ - 验收范围见 [中英文界面检查](docs/validation-language-2026-10-03.md)。
11
+
12
+ ## 0.5.1 (2026-10-02)
13
+
14
+ 修复 VPN 开启 Fake-IP 后外部订阅源被拦截的问题。Windows 默认沿用已启用的手动系统代理；检测到 `198.18.0.0/15` 时，通过 HTTPS DNS 查询真实公网地址，再固定连接地址并保留原域名和 TLS 证书校验。VPN 可以保持开启，无需修改代理软件配置或放开内网访问。抓取、跳转或读取结束后释放本次请求的连接。
15
+
16
+ 106 项 Windows 测试通过；在 VPN 开启、原生 DNS 返回 Fake-IP 的环境中，少数派、Python Insider、NASA 和 GitHub Atom 的检查、添加、抓取、持久化增量去重与搜索通过正常插件调用验证，没有注入测试 DNS 或抓取结果。Python 旧订阅地址也仍可读取。桌面原生窗口的单独验收不包含在这些结果中。
17
+
18
+ ## 0.5.0 (2026-10-02)
19
+
20
+ 新增 **设置 → RSS 订阅** 面板：添加、编辑、移除、搜索、分类筛选、检查可用性与 OPML 导入导出。面板与对话工具共用原有订阅列表，不需要迁移数据。跟随 DSH 的中文/英文和外观设置。
21
+
22
+ OPML 导入先预览新增、重复和无效项，再确认保存。默认保留重复订阅的名称和分类；勾选更新时会展示变化。保存失败或预览过期时保留输入。移除订阅需要确认具体名称和地址。
23
+
24
+ 同时修复损坏 XML 被部分导入、无效/含密码 URL 被接受，以及并发添加覆盖另一笔订阅的问题。检查记录只保留在本次 DSH 运行中，导入不会自动抓取全部订阅。
25
+
26
+ 94 项 Windows 测试通过；在官方 Harness `0.2.0-rc.2` 中实际操作了添加、编辑、筛选、检查、导入、移除、Tab/Enter/Esc、双页面冲突和重启持久化。桌面原生窗口与窄屏交互本轮未完成验收，外部生产订阅未替代为本地模拟测试。
27
+
28
+ ## 0.4.3 (2026-10-01)
29
+
30
+ 修复订阅 URL 的大小写比较：添加、删除、OPML 导入与搜索统一归一化协议、域名和默认端口，保留路径和查询参数的大小写，避免合并或删除不同订阅源。保留此前的代理 Fake-IP DNS 提示和保留地址检查。
31
+
32
+ ## 更早的改动
33
+
34
+ 完整历史可查阅 [GitHub 提交记录](https://github.com/STARDUSTLC666/dsh-rss/commits/master)。
package/README.en.md CHANGED
@@ -1,129 +1,44 @@
1
1
  # dsh-rss
2
2
 
3
- ## 0.5.0 update (2026-10-02)
4
-
5
- Adds **Settings → RSS subscriptions** with add/edit/remove, search, category filters, feed checks and OPML import/export. The panel and conversation tools share the existing subscription list. No migration is needed. UI labels follow the host language and appearance settings.
6
-
7
- Import previews new feeds, duplicate changes and rejected items before confirmation. Existing labels/categories are preserved by default; updates require an explicit checkbox. Failed saves and stale previews preserve your input. Removing a feed requires confirmation of its name and URL.
8
-
9
- Fixes partial imports of malformed XML, acceptance of invalid URLs or embedded credentials, and lost subscriptions during concurrent additions. Check history lasts for the current DSH run; importing does not fetch every feed.
10
-
11
- All 94 Windows tests pass. Actual browser interaction in official-source Harness `0.2.0-rc.2` covers add/edit/filter/check/import/remove, Tab/Enter/Escape, two-page conflicts and restart persistence. Native desktop and narrow-screen interaction remain unverified in this run. Synthetic feeds do not establish production-network compatibility.
12
-
13
- ## 0.4.3 update (2026-10-01)
14
-
15
- Fixes URL comparison for add, remove, OPML import and search. Schemes, hosts and default ports are normalized while case-sensitive paths and query parameters remain distinct, preventing unrelated subscriptions from being merged or removed. Existing Fake-IP DNS guidance and reserved-address checks remain available.
16
-
17
- Validation host: Harness `0.2.0-rc.2` built from official sources (commit `639ed01539`) on 2026-10-01. All 81 Windows tests, the 18-plugin co-load and nine RSS tool contracts pass. Production external feeds still require separate network validation.
18
-
19
- ![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)
20
-
21
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
22
-
23
- 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 nine model-facing tools.
24
-
25
- ## Compatibility
26
-
27
- Version 0.4.0 supports the declarative settings interface introduced in Harness **0.1.7**. The current baseline is official-source **0.2.0-rc.2**. All 18 plugins load together; tool contracts, subscription updates and restart persistence pass in isolation. Live feeds require working network access. Requires Node 22.19 or later within 22.x, or 24 or later.
28
-
29
- 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.
30
-
31
- `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.
32
-
33
- ## Installation
34
-
35
- ```bash
36
- dsh plugin --profile web add dsh-rss
37
- ```
38
-
39
- Restart the web service after installing. Ask your assistant to subscribe to an RSS URL or list your subscriptions; ordinary subscription management needs no configuration-file editing.
40
-
41
- For the desktop profile, use `dsh plugin --profile desktop add dsh-rss` and reopen DSH after installation or updates. The shared web settings surface provides the panel in both shells. Update older installed versions through the plugin manager first.
42
-
43
- ## Subscription panel
44
-
45
- Open **Settings → RSS subscriptions**. New URLs are fetched and checked before saving; the name and category are optional. Renaming or recategorizing an unchanged URL works without the remote feed being online.
46
-
47
- Choose an OPML file (up to 1 MiB) or paste its text, review the preview, then confirm. Rejected URLs include a reason. If another page or tool changed the list, preview again without retyping. Export downloads OPML without changing subscriptions.
48
-
49
- Cards show the most recent check/fetch time, article count or error during this run. Read-only configurations allow viewing, checking and exporting.
50
-
51
- ## Uninstall
52
-
53
- ```bash
54
- dsh plugin --profile web remove dsh-rss
55
- ```
56
-
57
- Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
58
-
59
-
60
- ## Configuration
61
-
62
- Override the plugin row in your profile's `cordis.patch.yml` (the plugin also loads with all defaults when absent):
63
-
64
- ```yaml
65
- - id: rss
66
- name: 'dsh-rss'
67
- config:
68
- # proxyUrl: http://127.0.0.1:7890 # enable when a feed needs a special proxy
69
- timeoutMs: 15000 # fetch timeout in ms (default 15000)
70
- # maxBodyBytes: 5242880 # response size cap (default 5MB, guards oversized responses)
71
- # userAgent: 'dsh-rss/0.2.0' # custom fetch UA
72
- # feedsYaml: | # optional: pre-seed subscriptions (or use the rss_add tool)
73
- # - url: https://example.com/feed.xml
74
- # name: My feed
75
- # category: tech
76
- ```
77
-
78
- ## Tools
79
-
80
- | Tool | Purpose | Key parameters |
81
- | :-- | :-- | :-- |
82
- | `rss_list` | List subscribed feeds | none |
83
- | `rss_add` | Add a subscription (fetches and validates the URL first) | `url` required; `name`/`category` optional |
84
- | `rss_remove` | Remove a subscription | `url` or `name`, at least one |
85
- | `rss_fetch` | Fetch and parse a feed, returning feed info and entries (with full `content`) | `url` or `name`, at least one; `limit` 1-100, default 20 |
86
- | `rss_check` | Validate that a URL is a parseable feed | `url` required |
87
- | `rss_opml_export` | Export subscriptions as OPML 2.0 text (optionally write a file) | `path` optional |
88
- | `rss_opml_import` | Bulk-import subscriptions from OPML 2.0 text | `opml` required |
89
-
90
- | `rss_search` | Search across feeds | `query` required; optional feed, date and limit filters |
91
- | `rss_health` | Check configuration, feeds and cursors offline | none |
92
-
93
- ### Examples
94
-
95
- ```text
96
- rss_add { url: https://example.com/feed.xml, name: my-feed }
97
- rss_fetch { name: my-feed, limit: 10 }
98
- rss_check { url: https://example.com/feed.xml }
99
- rss_opml_export { path: subscriptions.opml }
100
- rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
101
- ```
102
-
103
- ## Subscriptions
104
-
105
- On Harness 0.1.7, subscriptions and read cursors are stored in the current profile’s `rss` entry. Changes apply immediately and survive restart. Default installations automatically import the retired `dsh-rss` section from `settings.yaml` or `settings.yaml.imported` once, preserving the original file and existing profile values. Older hosts retain their original settings storage. Use a URL to distinguish feeds with identical names.
106
-
107
- ## Proxy
108
-
109
- Most feeds are reachable directly; a few require a special proxy from your network. When you hit a `fetch failed` error suggesting a proxy, set `proxyUrl` to your local proxy address (e.g. `http://127.0.0.1:7890`) and restart. The proxy only routes this plugin's fetch requests and does not affect other plugins in the same process.
110
-
111
- ## Parsing capabilities
112
-
113
- - RSS 2.0 / RSS 1.0 (RDF) / Atom, normalized to one output shape
114
- - Entity decoding, CDATA, `content:encoded`, `dc:creator` and other common fields
115
- - RFC 822 / ISO 8601 dates normalized to ISO 8601 UTC (`pubDate`); the raw text stays in `pubDateRaw`
116
- - Relative links resolved against the feed URL
117
- - Summaries stripped of HTML tags and truncated at 500 chars; RSS `content:encoded` / Atom `content` is preserved as a `content` field (tags stripped, up to 20000 chars)
118
- - Safety: no DTD / external entity parsing; 5MB body cap; configurable fetch timeout
119
-
120
- ## Development
121
-
122
- ```bash
123
- pnpm install
124
- pnpm test # build + offline tests with explicit fetch and DNS fixtures
125
- ```
126
-
127
- ## License
128
-
129
- MIT
3
+ [中文](README.md)
4
+
5
+ Subscribe to and read RSS or Atom feeds, and manage updates from DSH.
6
+
7
+ [![npm](https://img.shields.io/npm/v/dsh-rss)](https://www.npmjs.com/package/dsh-rss) [![downloads](https://img.shields.io/npm/dm/dsh-rss)](https://www.npmjs.com/package/dsh-rss)
8
+
9
+ ## What it does
10
+
11
+ - Add feeds, read articles and fetch updates.
12
+ - Import or export OPML and retain article content.
13
+ - Use a feed panel and optional plugin-level proxy configuration.
14
+
15
+ ## Install
16
+
17
+ In DSH Desktop, install `dsh-rss` from the Plugins panel. If the bundled dsh command is available:
18
+
19
+ ```bash
20
+ dsh plugin --profile desktop add dsh-rss
21
+ ```
22
+
23
+ For the web version, replace `desktop` with `web`. Restart DSH after installation.
24
+
25
+ ## Start using it
26
+
27
+ Add a feed in Settings → RSS subscriptions, or ask to subscribe to a feed URL and summarize recent articles.
28
+
29
+ ## Requirements and configuration
30
+
31
+ No account key is required. Feeds are accessed directly by default; a proxy depends on feed reachability from your network.
32
+
33
+ Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
34
+
35
+ ## Documentation
36
+
37
+ - [Usage and troubleshooting](docs/USAGE.en.md)
38
+ - [Changelog](CHANGELOG.md)
39
+ - [Validation scope and history](docs/VALIDATION.md)
40
+ - [Report a problem or suggest a feature](https://github.com/STARDUSTLC666/dsh-rss/issues)
41
+
42
+ ## License
43
+
44
+ [MIT](LICENSE)
package/README.md CHANGED
@@ -1,135 +1,44 @@
1
- [English](README.en.md)
2
-
3
1
  # dsh-rss
4
2
 
5
- ## 0.5.0 更新（2026-10-02）
6
-
7
- 新增 **设置 → RSS 订阅** 面板：添加、编辑、移除、搜索、分类筛选、检查可用性与 OPML 导入导出。面板与对话工具共用原有订阅列表，不需要迁移数据。跟随 DSH 的中文/英文和外观设置。
8
-
9
- OPML 导入先预览新增、重复和无效项，再确认保存。默认保留重复订阅的名称和分类；勾选更新时会展示变化。保存失败或预览过期时保留输入。移除订阅需要确认具体名称和地址。
10
-
11
- 同时修复损坏 XML 被部分导入、无效/含密码 URL 被接受，以及并发添加覆盖另一笔订阅的问题。检查记录只保留在本次 DSH 运行中，导入不会自动抓取全部订阅。
12
-
13
- 94 项 Windows 测试通过；在官方 Harness `0.2.0-rc.2` 中实际操作了添加、编辑、筛选、检查、导入、移除、Tab/Enter/Esc、双页面冲突和重启持久化。桌面原生窗口与窄屏交互本轮未完成验收，外部生产订阅未替代为本地模拟测试。
14
-
15
- ## 0.4.3 更新（2026-10-01）
16
-
17
- 修复订阅 URL 的大小写比较：添加、删除、OPML 导入与搜索统一归一化协议、域名和默认端口，保留路径和查询参数的大小写，避免合并或删除不同订阅源。保留此前的代理 Fake-IP DNS 提示和保留地址检查。
18
-
19
- 验证宿主：官方源码构建的 Harness `0.2.0-rc.2`（commit `639ed01539`，2026-10-01）。81 项 Windows 插件测试、18 个插件共同加载与 9 个 RSS 工具的契约检查通过。真实外部订阅源仍需正常网络连接。
20
-
21
- > **agent 的资讯雷达**：订阅管理 + RSS/Atom 抓取解析。
22
-
23
- ![npm version](https://img.shields.io/npm/v/dsh-rss?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-rss) ![license](https://img.shields.io/npm/l/dsh-rss) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-rss?style=social)
24
-
25
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
26
-
27
-
28
- DSH（DeepSeek Harness）的 RSS/Atom 订阅工具插件：管理订阅源，抓取并解析 RSS 0.9x / 1.0 / 2.0 与 Atom，支持 OPML 批量导入导出，给模型提供九个可直接调用的工具。
29
-
30
- ## 兼容性
31
-
32
- 0.4.0 起适配官方源码构建的 Harness **0.1.7 及以上的声明式设置接口**；当前基线为 **0.2.0-rc.2**，18 个插件同载、工具契约、订阅读写与重启持久化在隔离环境通过验证；真实外部订阅源需要正常网络连接。Node 要求为 22.19 及以上的 22.x，或 24 及以上。
33
-
34
- 抓取接收 Harness 的取消信号，取消 DNS、网络读取或跨源搜索时保留原始取消原因。默认预检域名解析结果并拒绝回环、私网和链路本地地址；每次重定向都重新校验。可信内网源可显式配置 `allowPrivateNetwork: true`。
35
-
36
- `rss_opml_export.path` 必须相对本次调用的会话工作区，父目录须已存在；工具拒绝绝对路径、目录穿越和指向工作区外的链接，并返回实际写入文件的绝对路径。文件写入默认通过 Harness 审批门，`opmlWriteApproval: false` 可关闭该门；省略 `path` 时仅返回 OPML 文本。
37
-
38
- ## 安装
39
-
40
- ```bash
41
- dsh plugin --profile web add dsh-rss
42
- ```
43
-
44
- 安装后重启 Web 服务即可。直接对助手说「订阅这个 RSS 地址，命名为技术资讯」或「列出我的订阅」即可使用，日常增删订阅不需要编辑配置文件。
45
-
46
- 桌面版使用 `dsh plugin --profile desktop add dsh-rss`，安装或更新后重新打开 DSH。网页和桌面的共享设置页面均可显示订阅面板；已安装的旧版本请先通过插件管理器更新。
47
-
48
- ## 订阅面板
49
-
50
- 打开 **设置 → RSS 订阅**。添加时填写 RSS/Atom 地址，名称可留空，分类可选。新地址通过抓取检查后才会保存；编辑原地址的名称或分类不需要源网站在线。
51
-
52
- 导入可选择不超过 1 MiB 的 OPML 文件或粘贴文本。先检查预览，再点击确认；跳过的地址会说明原因。已有订阅发生变化时重新预览即可，原输入仍保留。导出通过浏览器下载 OPML，不会修改订阅。
53
-
54
- 列表卡片显示最近一次手动检查或工具抓取的时间和文章数，失败时显示具体原因。只读配置仍可查看、检查和导出。
55
-
56
- ## 卸载
57
-
58
- ```bash
59
- dsh plugin --profile web remove dsh-rss
60
- ```
61
-
62
- 卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
63
-
64
-
65
- ## 配置
66
-
67
- 在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时插件也能加载，只是全部用默认值）：
68
-
69
- ```yaml
70
- - id: rss
71
- name: 'dsh-rss'
72
- config:
73
- # proxyUrl: http://127.0.0.1:7890 # 部分订阅源需要特殊代理（梯子）才能访问时启用
74
- timeoutMs: 15000 # 抓取超时（毫秒，默认 15000）
75
- # maxBodyBytes: 5242880 # 订阅源体积上限（默认 5MB，防超大响应）
76
- # userAgent: 'dsh-rss/0.2.0' # 自定义抓取 UA
77
- # feedsYaml: | # 可选：预置订阅列表（也可用 rss_add 工具添加）
78
- # - url: https://example.com/feed.xml
79
- # name: 示例订阅
80
- # category: 技术
81
- ```
82
-
83
- ## 工具一览
84
-
85
- | 工具 | 作用 | 关键参数 |
86
- | :-- | :-- | :-- |
87
- | `rss_list` | 列出已订阅源 | 无 |
88
- | `rss_add` | 添加订阅（先抓取校验地址） | `url` 必填；`name`/`category` 可选 |
89
- | `rss_remove` | 删除订阅 | `url` 或 `name` 至少一个 |
90
- | `rss_fetch` | 抓取解析订阅源，返回源信息与条目（含正文 content） | `url` 或 `name` 至少一个；`limit` 1-100 默认 20 |
91
- | `rss_check` | 校验地址是否为可解析的订阅源 | `url` 必填 |
92
- | `rss_opml_export` | 导出订阅列表为 OPML 2.0 文本（可写入文件） | `path` 可选 |
93
- | `rss_opml_import` | 从 OPML 2.0 文本批量导入订阅源 | `opml` 必填 |
94
- | `rss_search` | 跨订阅源关键词搜索条目（标题/摘要/正文/作者） | `query` 必填；`name`/`url`/`since`/`limit` 可选 |
95
- | `rss_health` | 插件自检（配置/订阅/游标/解析器，离线） | 无 |
96
-
97
- ### 示例
98
-
99
- ```text
100
- rss_add { url: https://example.com/feed.xml, name: 我的订阅 }
101
- rss_fetch { name: 我的订阅, limit: 10 }
102
- rss_check { url: https://example.com/feed.xml }
103
- rss_opml_export { path: subscriptions.opml }
104
- rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
105
- ```
106
-
107
- ## 订阅存储
108
-
109
- Harness 0.1.7 把订阅列表和读取游标保存在当前 profile 的 `rss` 配置行；增删后立即生效，重启仍保留。默认安装会自动导入旧 `settings.yaml` 或 `settings.yaml.imported` 的 `dsh-rss` 数据一次，保留原文件，且不覆盖已有 profile 值。旧版宿主继续使用原 settings 存储。同名订阅请用 URL 区分。
110
-
111
- ## 特殊代理（梯子）
112
-
113
- 大部分订阅源可以直接访问；少数订阅源需要特殊代理（梯子）才能连通。遇到 `抓取失败` 且提示需要代理时，把 `proxyUrl` 配成你的本地代理地址（如 `http://127.0.0.1:7890`）并重启即可。代理只作用于本插件的抓取请求，不影响同进程其他插件。
114
-
115
- ## 解析能力
116
-
117
- - RSS 2.0 / RSS 1.0（RDF）/ Atom 三种格式，统一归一化输出
118
- - 实体解码、CDATA、`content:encoded`、`dc:creator`、`itunes` 等常见字段
119
- - RFC 822 / ISO 8601 日期统一转 ISO 8601 UTC（`pubDate`），原始文本保留在 `pubDateRaw`
120
- - 相对链接按订阅源地址解析成绝对链接
121
- - 摘要去 HTML 标签并截断到 500 字符；RSS `content:encoded` / Atom `content` 作为 `content` 字段保留（去标签后最多 20000 字符）
122
- - 安全：不解析 DTD/外部实体，内容只做文本抽取；响应体积上限 5MB；抓取超时可配
123
-
124
- ## 开发
125
-
126
- ```bash
127
- pnpm install
128
- pnpm test # 构建 + 离线测试（fetch 与 DNS 均使用夹具）
129
- ```
130
-
131
- 发布前门禁：危险模式扫描、manifest 自检、`pnpm audit --prod`、全量测试，以及全新 profile 的真实启动冒烟测试。
132
-
133
- ## License
134
-
135
- MIT
3
+ [English](README.en.md)
4
+
5
+ 订阅和阅读 RSS / Atom，在 DSH 中查看与管理更新。
6
+
7
+ [![npm](https://img.shields.io/npm/v/dsh-rss)](https://www.npmjs.com/package/dsh-rss) [![downloads](https://img.shields.io/npm/dm/dsh-rss)](https://www.npmjs.com/package/dsh-rss)
8
+
9
+ ## 功能
10
+
11
+ - 添加订阅、查看文章和抓取更新。
12
+ - 导入、导出 OPML，保留文章正文。
13
+ - 可视化订阅面板，支持插件级网络代理。
14
+
15
+ ## 安装
16
+
17
+ 桌面版可在「插件」面板按包名 `dsh-rss` 安装。已配置 dsh 命令时也可使用：
18
+
19
+ ```bash
20
+ dsh plugin --profile desktop add dsh-rss
21
+ ```
22
+
23
+ 网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
24
+
25
+ ## 开始使用
26
+
27
+ 打开「设置 → RSS 订阅」添加订阅源，或说：“订阅这个 RSS 地址并总结最新文章。”
28
+
29
+ ## 依赖与配置
30
+
31
+ 不需要账号密钥。默认尝试直接连接订阅源；是否需要代理取决于订阅源和当前网络。
32
+
33
+ 详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
34
+
35
+ ## 文档
36
+
37
+ - [使用与排错](docs/USAGE.md)
38
+ - [更新记录](CHANGELOG.md)
39
+ - [验证范围与历史记录](docs/VALIDATION.md)
40
+ - [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-rss/issues)
41
+
42
+ ## License
43
+
44
+ [MIT](LICENSE)
package/cordis.patch.yml CHANGED
@@ -7,7 +7,9 @@
7
7
  # - id: rss
8
8
  # name: 'dsh-rss'
9
9
  # config:
10
- # # proxyUrl: http://127.0.0.1:7890 # 部分订阅源需要特殊代理（梯子）时启用
10
+ # # proxyUrl: http://127.0.0.1:7890 # 可选；覆盖 Windows 系统代理
11
+ # # useSystemProxy: true # 默认自动读取 Windows 手动系统代理
12
+ # # fakeIpDnsFallback: true # 默认兼容 VPN Fake-IP，仍校验真实公网 IP
11
13
  # timeoutMs: 15000 # 抓取超时（毫秒）
12
14
  # # feedsYaml: | # 可选：预置订阅列表（也可用 rss_add 工具添加）
13
15
  # # - url: https://example.com/feed.xml
package/docs/CHANGELOG.en.md ADDED
@@ -0,0 +1,27 @@
1
+ # Historical release notes
2
+
3
+ [Current changelog](../CHANGELOG.md) · [Overview](../README.en.md)
4
+
5
+ These English notes preserve the earlier translations. The main changelog contains the consolidated version history.
6
+
7
+ ## 0.5.1 (2026-10-02)
8
+
9
+ Fixes public feeds being rejected when a VPN returns Fake-IP DNS addresses. Windows uses the enabled manual system proxy by default. For `198.18.0.0/15` answers, HTTPS DNS obtains real public addresses; connections are pinned to validated addresses while preserving the original hostname and TLS certificate verification. Keep the VPN enabled without changing its configuration or allowing private networks. Request-owned connections are released after redirects, errors or body reads.
10
+
11
+ All 106 Windows tests pass. With the VPN enabled and native DNS returning Fake-IP, normal plugin calls pass check/add/fetch/persisted incremental deduplication/search for SSPAI, Python Insider, NASA and GitHub Atom, with no injected DNS or fetch results. The legacy Python feed URL also remains readable. These results do not establish separate native desktop UI acceptance.
12
+
13
+ ## 0.5.0 (2026-10-02)
14
+
15
+ Adds **Settings → RSS subscriptions** with add/edit/remove, search, category filters, feed checks and OPML import/export. The panel and conversation tools share the existing subscription list. No migration is needed. UI labels follow the host language and appearance settings.
16
+
17
+ Import previews new feeds, duplicate changes and rejected items before confirmation. Existing labels/categories are preserved by default; updates require an explicit checkbox. Failed saves and stale previews preserve your input. Removing a feed requires confirmation of its name and URL.
18
+
19
+ Fixes partial imports of malformed XML, acceptance of invalid URLs or embedded credentials, and lost subscriptions during concurrent additions. Check history lasts for the current DSH run; importing does not fetch every feed.
20
+
21
+ All 94 Windows tests pass. Actual browser interaction in official-source Harness `0.2.0-rc.2` covers add/edit/filter/check/import/remove, Tab/Enter/Escape, two-page conflicts and restart persistence. Native desktop and narrow-screen interaction remain unverified in this run. Synthetic feeds do not establish production-network compatibility.
22
+
23
+ ## 0.4.3 (2026-10-01)
24
+
25
+ Fixes URL comparison for add, remove, OPML import and search. Schemes, hosts and default ports are normalized while case-sensitive paths and query parameters remain distinct, preventing unrelated subscriptions from being merged or removed. Existing Fake-IP DNS guidance and reserved-address checks remain available.
26
+
27
+ Validation host: Harness `0.2.0-rc.2` built from official sources (commit `639ed01539`) on 2026-10-01. All 81 Windows tests, the 18-plugin co-load and nine RSS tool contracts pass. Production external feeds still require separate network validation.
package/docs/USAGE.en.md ADDED
@@ -0,0 +1,104 @@
1
+ # dsh-rss usage guide
2
+
3
+ [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ dsh plugin --profile web add dsh-rss
9
+ ```
10
+
11
+ Restart the web service after installing. Ask your assistant to subscribe to an RSS URL or list your subscriptions; ordinary subscription management needs no configuration-file editing.
12
+
13
+ For the desktop profile, use `dsh plugin --profile desktop add dsh-rss` and reopen DSH after installation or updates. The shared web settings surface provides the panel in both shells. Update older installed versions through the plugin manager first.
14
+
15
+ ## Subscription panel
16
+
17
+ Open **Settings → RSS subscriptions**. New URLs are fetched and checked before saving; the name and category are optional. Renaming or recategorizing an unchanged URL works without the remote feed being online.
18
+
19
+ Choose an OPML file (up to 1 MiB) or paste its text, review the preview, then confirm. Rejected URLs include a reason. If another page or tool changed the list, preview again without retyping. Export downloads OPML without changing subscriptions.
20
+
21
+ Cards show the most recent check/fetch time, article count or error during this run. Read-only configurations allow viewing, checking and exporting.
22
+
23
+ ## Uninstall
24
+
25
+ ```bash
26
+ dsh plugin --profile web remove dsh-rss
27
+ ```
28
+
29
+ Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
30
+
31
+ ## Configuration
32
+
33
+ Override the plugin row in your profile's `cordis.patch.yml` (the plugin also loads with all defaults when absent):
34
+
35
+ ```yaml
36
+ - id: rss
37
+ name: 'dsh-rss'
38
+ config:
39
+ # proxyUrl: http://127.0.0.1:7890 # optional override for the Windows system proxy
40
+ # useSystemProxy: true # use the enabled Windows manual proxy by default
41
+ # fakeIpDnsFallback: true # validate real public DNS answers when Fake-IP is detected
42
+ timeoutMs: 15000 # fetch timeout in ms (default 15000)
43
+ # maxBodyBytes: 5242880 # response size cap (default 5MB, guards oversized responses)
44
+ # userAgent: 'dsh-rss/0.2.0' # custom fetch UA
45
+ # feedsYaml: | # optional: pre-seed subscriptions (or use the rss_add tool)
46
+ # - url: https://example.com/feed.xml
47
+ # name: My feed
48
+ # category: tech
49
+ ```
50
+
51
+ ## Tools
52
+
53
+ | Tool | Purpose | Key parameters |
54
+ | :-- | :-- | :-- |
55
+ | `rss_list` | List subscribed feeds | none |
56
+ | `rss_add` | Add a subscription (fetches and validates the URL first) | `url` required; `name`/`category` optional |
57
+ | `rss_remove` | Remove a subscription | `url` or `name`, at least one |
58
+ | `rss_fetch` | Fetch and parse a feed, returning feed info and entries (with full `content`) | `url` or `name`, at least one; `limit` 1-100, default 20 |
59
+ | `rss_check` | Validate that a URL is a parseable feed | `url` required |
60
+ | `rss_opml_export` | Export subscriptions as OPML 2.0 text (optionally write a file) | `path` optional |
61
+ | `rss_opml_import` | Bulk-import subscriptions from OPML 2.0 text | `opml` required |
62
+
63
+ | `rss_search` | Search across feeds | `query` required; optional feed, date and limit filters |
64
+ | `rss_health` | Check configuration, feeds and cursors offline | none |
65
+
66
+ ### Examples
67
+
68
+ ```text
69
+ rss_add { url: https://example.com/feed.xml, name: my-feed }
70
+ rss_fetch { name: my-feed, limit: 10 }
71
+ rss_check { url: https://example.com/feed.xml }
72
+ rss_opml_export { path: subscriptions.opml }
73
+ rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
74
+ ```
75
+
76
+ ## Subscriptions
77
+
78
+ On Harness 0.1.7, subscriptions and read cursors are stored in the current profile’s `rss` entry. Changes apply immediately and survive restart. Default installations automatically import the retired `dsh-rss` section from `settings.yaml` or `settings.yaml.imported` once, preserving the original file and existing profile values. Older hosts retain their original settings storage. Use a URL to distinguish feeds with identical names.
79
+
80
+ ## Proxy
81
+
82
+ Windows uses its enabled manual proxy by default, honoring protocol selection and bypass entries. No PAC scripts are evaluated and OS settings are never modified. An explicit `proxyUrl` takes precedence; `useSystemProxy: false` disables automatic detection. Other platforms can still configure an HTTP(S) `proxyUrl`. These routes apply only to this plugin.
83
+
84
+ When native DNS returns VPN Fake-IP (`198.18.0.0/15`), only the feed hostname is sent to [Cloudflare HTTPS DNS](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/), with Google HTTPS DNS as a service-failure fallback. No URL paths, feed content, credentials or subscription lists are sent. Answers must pass public-address checks, and actual connections are pinned to those addresses. Disable this behavior with `fakeIpDnsFallback: false`. Ordinary public DNS, private DNS and IP literals do not trigger it. Trusted internal feeds still require an explicit `allowPrivateNetwork: true`.
85
+
86
+ ## Parsing capabilities
87
+
88
+ - RSS 2.0 / RSS 1.0 (RDF) / Atom, normalized to one output shape
89
+ - Entity decoding, CDATA, `content:encoded`, `dc:creator` and other common fields
90
+ - RFC 822 / ISO 8601 dates normalized to ISO 8601 UTC (`pubDate`); the raw text stays in `pubDateRaw`
91
+ - Relative links resolved against the feed URL
92
+ - Summaries stripped of HTML tags and truncated at 500 chars; RSS `content:encoded` / Atom `content` is preserved as a `content` field (tags stripped, up to 20000 chars)
93
+ - Safety: no DTD / external entity parsing; 5MB body cap; configurable fetch timeout
94
+
95
+ ## Development
96
+
97
+ ```bash
98
+ pnpm install
99
+ pnpm test # build + offline tests with explicit fetch and DNS fixtures
100
+ ```
101
+
102
+ ## License
103
+
104
+ MIT
package/docs/USAGE.md ADDED
@@ -0,0 +1,105 @@
1
+ # dsh-rss 使用说明
2
+
3
+ [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
4
+
5
+ ## 安装
6
+
7
+ ```bash
8
+ dsh plugin --profile web add dsh-rss
9
+ ```
10
+
11
+ 安装后重启 Web 服务即可。直接对助手说「订阅这个 RSS 地址，命名为技术资讯」或「列出我的订阅」即可使用，日常增删订阅不需要编辑配置文件。
12
+
13
+ 桌面版使用 `dsh plugin --profile desktop add dsh-rss`，安装或更新后重新打开 DSH。网页和桌面的共享设置页面均可显示订阅面板；已安装的旧版本请先通过插件管理器更新。
14
+
15
+ ## 订阅面板
16
+
17
+ 打开 **设置 → RSS 订阅**。添加时填写 RSS/Atom 地址，名称可留空，分类可选。新地址通过抓取检查后才会保存；编辑原地址的名称或分类不需要源网站在线。
18
+
19
+ 导入可选择不超过 1 MiB 的 OPML 文件或粘贴文本。先检查预览，再点击确认；跳过的地址会说明原因。已有订阅发生变化时重新预览即可，原输入仍保留。导出通过浏览器下载 OPML，不会修改订阅。
20
+
21
+ 列表卡片显示最近一次手动检查或工具抓取的时间和文章数，失败时显示具体原因。只读配置仍可查看、检查和导出。
22
+
23
+ ## 卸载
24
+
25
+ ```bash
26
+ dsh plugin --profile web remove dsh-rss
27
+ ```
28
+
29
+ 卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
30
+
31
+ ## 配置
32
+
33
+ 在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时插件也能加载，只是全部用默认值）：
34
+
35
+ ```yaml
36
+ - id: rss
37
+ name: 'dsh-rss'
38
+ config:
39
+ # proxyUrl: http://127.0.0.1:7890 # 可选；覆盖自动读取的 Windows 系统代理
40
+ # useSystemProxy: true # 默认读取 Windows 已启用的手动系统代理
41
+ # fakeIpDnsFallback: true # 默认在 Fake-IP 下查询并校验真实公网地址
42
+ timeoutMs: 15000 # 抓取超时（毫秒，默认 15000）
43
+ # maxBodyBytes: 5242880 # 订阅源体积上限（默认 5MB，防超大响应）
44
+ # userAgent: 'dsh-rss/0.2.0' # 自定义抓取 UA
45
+ # feedsYaml: | # 可选：预置订阅列表（也可用 rss_add 工具添加）
46
+ # - url: https://example.com/feed.xml
47
+ # name: 示例订阅
48
+ # category: 技术
49
+ ```
50
+
51
+ ## 工具一览
52
+
53
+ | 工具 | 作用 | 关键参数 |
54
+ | :-- | :-- | :-- |
55
+ | `rss_list` | 列出已订阅源 | 无 |
56
+ | `rss_add` | 添加订阅（先抓取校验地址） | `url` 必填；`name`/`category` 可选 |
57
+ | `rss_remove` | 删除订阅 | `url` 或 `name` 至少一个 |
58
+ | `rss_fetch` | 抓取解析订阅源，返回源信息与条目（含正文 content） | `url` 或 `name` 至少一个；`limit` 1-100 默认 20 |
59
+ | `rss_check` | 校验地址是否为可解析的订阅源 | `url` 必填 |
60
+ | `rss_opml_export` | 导出订阅列表为 OPML 2.0 文本（可写入文件） | `path` 可选 |
61
+ | `rss_opml_import` | 从 OPML 2.0 文本批量导入订阅源 | `opml` 必填 |
62
+ | `rss_search` | 跨订阅源关键词搜索条目（标题/摘要/正文/作者） | `query` 必填；`name`/`url`/`since`/`limit` 可选 |
63
+ | `rss_health` | 插件自检（配置/订阅/游标/解析器，离线） | 无 |
64
+
65
+ ### 示例
66
+
67
+ ```text
68
+ rss_add { url: https://example.com/feed.xml, name: 我的订阅 }
69
+ rss_fetch { name: 我的订阅, limit: 10 }
70
+ rss_check { url: https://example.com/feed.xml }
71
+ rss_opml_export { path: subscriptions.opml }
72
+ rss_opml_import { opml: "<?xml version=\"1.0\"?>..." }
73
+ ```
74
+
75
+ ## 订阅存储
76
+
77
+ Harness 0.1.7 把订阅列表和读取游标保存在当前 profile 的 `rss` 配置行；增删后立即生效，重启仍保留。默认安装会自动导入旧 `settings.yaml` 或 `settings.yaml.imported` 的 `dsh-rss` 数据一次，保留原文件，且不覆盖已有 profile 值。旧版宿主继续使用原 settings 存储。同名订阅请用 URL 区分。
78
+
79
+ ## 代理与 VPN
80
+
81
+ Windows 上默认读取已启用的手动系统代理，尊重协议与绕过列表；不执行 PAC 脚本，也不修改系统设置。`proxyUrl` 显式配置优先；`useSystemProxy: false` 可关闭自动读取。其他平台仍可通过 `proxyUrl` 配置 HTTP(S) 代理。这些代理仅作用于本插件。
82
+
83
+ 当系统 DNS 返回 VPN 的 Fake-IP（`198.18.0.0/15`）时，默认只向 [Cloudflare HTTPS DNS](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/) 查询订阅源域名；服务不可用时尝试 Google HTTPS DNS。查询不会发送订阅源路径、正文、密钥或订阅列表，回答仍须通过公网地址检查；实际连接固定到检查过的地址。`fakeIpDnsFallback: false` 可关闭该兼容方式。普通公网 DNS、私网 DNS 和 IP 字面量不会触发此查询。可信内网订阅仍需单独显式配置 `allowPrivateNetwork: true`。
84
+
85
+ ## 解析能力
86
+
87
+ - RSS 2.0 / RSS 1.0（RDF）/ Atom 三种格式，统一归一化输出
88
+ - 实体解码、CDATA、`content:encoded`、`dc:creator`、`itunes` 等常见字段
89
+ - RFC 822 / ISO 8601 日期统一转 ISO 8601 UTC（`pubDate`），原始文本保留在 `pubDateRaw`
90
+ - 相对链接按订阅源地址解析成绝对链接
91
+ - 摘要去 HTML 标签并截断到 500 字符；RSS `content:encoded` / Atom `content` 作为 `content` 字段保留（去标签后最多 20000 字符）
92
+ - 安全：不解析 DTD/外部实体，内容只做文本抽取；响应体积上限 5MB；抓取超时可配
93
+
94
+ ## 开发
95
+
96
+ ```bash
97
+ pnpm install
98
+ pnpm test # 构建 + 离线测试（fetch 与 DNS 均使用夹具）
99
+ ```
100
+
101
+ 发布前门禁：危险模式扫描、manifest 自检、`pnpm audit --prod`、全量测试，以及全新 profile 的真实启动冒烟测试。
102
+
103
+ ## License
104
+
105
+ MIT