@magic6/dsh-web-fallback-chain 0.0.0-stage → 0.2.3
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.
- package/CHANGELOG.md +49 -0
- package/LICENSE +21 -0
- package/README.md +245 -2
- package/README.zh-CN.md +213 -0
- package/cordis.patch.yml +24 -0
- package/icon.svg +15 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +81 -4
- package/src/chains/fetch-plugin.js +213 -0
- package/src/chains/fetch.js +224 -0
- package/src/chains/search-plugin.js +108 -0
- package/src/chains/search.js +159 -0
- package/src/client.js +1655 -0
- package/src/config.js +245 -0
- package/src/index.js +137 -0
- package/src/policy/index.js +37 -0
- package/src/policy/modes.js +179 -0
- package/src/policy/providers.js +191 -0
- package/src/prompt.js +104 -0
- package/src/providers/http.js +213 -0
- package/src/providers/index.js +65 -0
- package/src/providers/vendors.js +309 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [0.2.3] - 2026-11-16
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- npm package renamed to `@magic6/dsh-web-fallback-chain`; npm requires a scoped
|
|
12
|
+
package for the first automated publish.
|
|
13
|
+
- README: update the npm installation command.
|
|
14
|
+
|
|
15
|
+
## [0.2.2] - 2026-11-16
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- npm distribution: install with `dsh plugin --profile web add dsh-web-fallback-chain`.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- README: document npm installation and use absolute links for the language switch.
|
|
24
|
+
|
|
25
|
+
## [0.2.1] - 2026-11-16
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- README: add a visible English / Simplified Chinese language switch.
|
|
30
|
+
|
|
31
|
+
## [0.2.0] - 2026-11-16
|
|
32
|
+
|
|
33
|
+
First public release.
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- Package and repository renamed to `dsh-web-fallback-chain`. The mounted entry id
|
|
38
|
+
remains `web-fallback` so existing profile patches keep working.
|
|
39
|
+
- README rewritten with the measured ranking, free-only semantics, installation and
|
|
40
|
+
configuration reference. Added a Chinese translation.
|
|
41
|
+
- Added CI, security policy and contribution guide.
|
|
42
|
+
|
|
43
|
+
### Verified
|
|
44
|
+
|
|
45
|
+
- `npm test`: 162 passing, 0 failing.
|
|
46
|
+
- Settings client rendered through `vm` with a fake module loader (see
|
|
47
|
+
`test/client-render.test.js`).
|
|
48
|
+
|
|
49
|
+
Earlier internal versions (0.1.x) are preserved in the private development history.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 T-splines
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,246 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-web-fallback-chain
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** | [简体中文](https://github.com/T-splines/dsh-web-fallback-chain/blob/main/README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
**One ranked, cost-aware chain for web search and fetch in DeepSeek Harness — measured quality, free-only mode, and a single settings page.**
|
|
6
|
+
|
|
7
|
+
DSH's `ctx.web` selects exactly **one** provider per capability, and its config is a pinned
|
|
8
|
+
provider id rather than a priority list. "Best first, something free when the best fails"
|
|
9
|
+
cannot be expressed in a profile. This plugin registers one provider per capability whose
|
|
10
|
+
internal order *is* that list — and ships the individual legs so you can pin any of them
|
|
11
|
+
directly.
|
|
12
|
+
|
|
13
|
+
- [Why this exists](#why-this-exists)
|
|
14
|
+
- [What makes it different](#what-makes-it-different)
|
|
15
|
+
- [What it registers](#what-it-registers)
|
|
16
|
+
- [Install](#install)
|
|
17
|
+
- [Ranking](#ranking)
|
|
18
|
+
- [The free-only switch](#the-free-only-switch)
|
|
19
|
+
- [Settings page](#settings-page)
|
|
20
|
+
- [Configuration](#configuration)
|
|
21
|
+
- [Why one package and not four](#why-one-package-and-not-four)
|
|
22
|
+
- [Tests](#tests)
|
|
23
|
+
- [Compatibility](#compatibility)
|
|
24
|
+
|
|
25
|
+
## Why this exists
|
|
26
|
+
|
|
27
|
+
A DSH profile can say *which* web provider to use, but not *in what order to try several*.
|
|
28
|
+
When the primary search or fetch fails, the request fails; there is no "try the free leg
|
|
29
|
+
next" seam. Rebuilding that seam in every deployment means four packages, four settings
|
|
30
|
+
pages, and a lockstep upgrade problem.
|
|
31
|
+
|
|
32
|
+
This plugin puts the ordered chain back into the provider slot:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
web_search ──▶ search-chain ──▶ deepseek-search-rich ──▶ anysearch ──▶ tavily
|
|
36
|
+
web_fetch ──▶ fetch-chain ──▶ anysearch ──▶ tavily ──▶ deepseek-fetch-rich ──▶ http*
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`http*` is an optional plain-HTTP leg supplied by the deployment (for example a separate
|
|
40
|
+
web-fetch plugin); this package does not register it. The first **available** leg serves
|
|
41
|
+
each request; the rest are attempted only when it fails or returns too little. The order is
|
|
42
|
+
a quality ranking, not a cost ranking. With the default `freeOnly: true`, paid legs are
|
|
43
|
+
skipped at call time, so the first available leg is the first *free* one.
|
|
44
|
+
|
|
45
|
+
## What makes it different
|
|
46
|
+
|
|
47
|
+
- **Measured, not guessed.** Defaults come from this plugin's own benchmark: blind-scored
|
|
48
|
+
fetches on 15 pages, blind-scored search relevance on 10 queries, and 20-site availability
|
|
49
|
+
runs. The numbers are a starting point you can reorder, not a promise about any page.
|
|
50
|
+
- **Free-only actually skips paid legs.** `freeOnly` is checked at call time. Turning it off
|
|
51
|
+
restores the *same* order instead of maintaining a second list.
|
|
52
|
+
- **One package, one settings page.** Reorder legs with ▲▼, toggle free-only, annotate which
|
|
53
|
+
leg served a fallback, and switch read mode. No second config to keep in sync.
|
|
54
|
+
- **Honest fallback.** The chain returns lossless JSON, can write the serving leg into the
|
|
55
|
+
output, and does not treat a short page as a failure unless you opt in
|
|
56
|
+
(`minBodyChars` defaults to 0).
|
|
57
|
+
- **Provider-specific value.** DeepSeek search maps the `summary` field (600–800 chars), not
|
|
58
|
+
just a snippet; AnySearch is the leg that got through bot walls in testing; Tavily is the
|
|
59
|
+
free leg that extracts PDFs.
|
|
60
|
+
- **Tested where it matters.** 162 `node --test` cases, including the real settings client
|
|
61
|
+
rendered through `vm` with a fake module loader, and round-trip tests for every
|
|
62
|
+
registered settings field.
|
|
63
|
+
|
|
64
|
+
## What it registers
|
|
65
|
+
|
|
66
|
+
| id | capability | what it is |
|
|
67
|
+
|:--|:--|:--|
|
|
68
|
+
| `search-chain` | search | the ordered search chain (pin `searchProvider` to this) |
|
|
69
|
+
| `fetch-chain` | fetch | the ordered fetch chain (pin `fetchProvider` to this) |
|
|
70
|
+
| `deepseek-search-rich` | search | DeepSeek search, mapping `summary` (600–800 chars) not just `snippet` |
|
|
71
|
+
| `deepseek-fetch-rich` | fetch | DeepSeek fetch |
|
|
72
|
+
| `anysearch` | search + fetch | AnySearch; the only leg that got through bot walls in testing |
|
|
73
|
+
| `tavily` | search + fetch | Tavily; the only free leg here that extracts PDFs |
|
|
74
|
+
|
|
75
|
+
`http` is intentionally **not** in this table: it is a deployment-supplied leg, not part of
|
|
76
|
+
this package. The chains can name it, and a fetch that falls through to it will use it when
|
|
77
|
+
another plugin registers that id.
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
Requirements: DSH `0.2.2-rc.x`, Node.js 20+, and **at least one** of
|
|
82
|
+
`DEEPSEEK_API_KEY`, `ANYSEARCH_API_KEY`, `TAVILY_API_KEY`. A leg without its key is still
|
|
83
|
+
registered but reports itself unavailable, so a chain with no keys has nothing to call.
|
|
84
|
+
An optional plain-HTTP leg (`http`) can be supplied by a separate web-fetch plugin.
|
|
85
|
+
|
|
86
|
+
### From npm
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
dsh plugin --profile web add @magic6/dsh-web-fallback-chain
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### From source
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
git clone https://github.com/T-splines/dsh-web-fallback-chain.git
|
|
96
|
+
cd dsh-web-fallback-chain
|
|
97
|
+
dsh plugin --profile web add "$PWD"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The package is a bundle (`dsh.bundle.patch`), so its default entry is mounted by the
|
|
101
|
+
bundle. Pin the chain providers in your profile patch
|
|
102
|
+
(`$DSH_HOME/profiles/<profile>/cordis.patch.yml`):
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
- id: web
|
|
106
|
+
config:
|
|
107
|
+
searchProvider: search-chain
|
|
108
|
+
fetchProvider: fetch-chain
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Reload the profile (or restart the web app), then open **Plugins → Installed →
|
|
112
|
+
dsh-web-fallback-chain**. The settings card is rendered on the plugin's detail page.
|
|
113
|
+
If your profile already pins another provider, replace those pins with the two ids above.
|
|
114
|
+
|
|
115
|
+
The profile entry id stays `web-fallback`. If you are upgrading from the old package name
|
|
116
|
+
`dsh-web-fallback`, remove the old package first; installing both would mount the same entry
|
|
117
|
+
twice. Existing settings keep working because the entry id did not change.
|
|
118
|
+
|
|
119
|
+
To verify the composition without starting an agent:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
dsh --profile web --dump-config | grep -A6 'id: web-fallback'
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Ranking
|
|
126
|
+
|
|
127
|
+
Defaults are **strictly by measured quality, descending**, identical for every read mode:
|
|
128
|
+
|
|
129
|
+
| leg | quality | cost | key |
|
|
130
|
+
|:--|:--|:--|:--|
|
|
131
|
+
| `deepseek-search-rich` | 9.6 | paid | `DEEPSEEK_API_KEY` |
|
|
132
|
+
| `anysearch` | 7.3 | free | `ANYSEARCH_API_KEY` |
|
|
133
|
+
| `tavily` | 7.3 | free | `TAVILY_API_KEY` |
|
|
134
|
+
| `deepseek-fetch-rich` | 5.4 | paid | `DEEPSEEK_API_KEY` |
|
|
135
|
+
| `http` | 4.0 | free | — (external leg, not shipped) |
|
|
136
|
+
|
|
137
|
+
Search order: `deepseek-search-rich → anysearch → tavily`.
|
|
138
|
+
Fetch order: `anysearch → tavily → deepseek-fetch-rich → http` (the last one only when an
|
|
139
|
+
external web-fetch plugin registers it).
|
|
140
|
+
|
|
141
|
+
`quality` is for ordering only — it is not a promise about a particular page. The numbers
|
|
142
|
+
come from the plugin's own benchmark; your corpus may rank differently. Reorder the ladders
|
|
143
|
+
on the settings page and the plugin writes the flat `order` / `searchOrder` list.
|
|
144
|
+
|
|
145
|
+
**First available means primary.** The first leg whose key is present and that is not
|
|
146
|
+
skipped by `freeOnly` serves the request; the rest are tried only when it fails or returns
|
|
147
|
+
too little. The list is ordered by "how good is what comes back", not by "how cheap is the
|
|
148
|
+
attempt".
|
|
149
|
+
|
|
150
|
+
## The free-only switch
|
|
151
|
+
|
|
152
|
+
`freeOnly` (default **on**) skips every leg marked `paid` **at call time**. It does not
|
|
153
|
+
reorder anything: the ranking is one list, and turning the switch off restores the same
|
|
154
|
+
sequence. The settings page shows billed legs greyed out rather than hiding them, so the
|
|
155
|
+
displayed list always matches the stored one.
|
|
156
|
+
|
|
157
|
+
Reading only `process.env` and skipping paid legs is the whole of it — there is no second
|
|
158
|
+
configuration to keep in sync.
|
|
159
|
+
|
|
160
|
+
## Settings page
|
|
161
|
+
|
|
162
|
+
It lives on the plugin's detail page — **Plugins → Installed → dsh-web-fallback-chain** —
|
|
163
|
+
not under Settings. The card has five primary controls, because every setting already has a
|
|
164
|
+
measured default and none of them is something you must fill in:
|
|
165
|
+
|
|
166
|
+
- two switches — `freeOnly`, `annotateFallback`
|
|
167
|
+
- one choice — `defaultMode` (`brief` / `deep` / `list` / `page`)
|
|
168
|
+
- two ladders with ▲▼ to reorder a leg
|
|
169
|
+
|
|
170
|
+
There is also an **Advanced** section for the settings you are more likely to touch:
|
|
171
|
+
`minBodyChars`, `timeoutMs`, the `enable` allow-list (as mount checkboxes), per-leg
|
|
172
|
+
`cost`, `deepseekNeedContent`, `anysearchTag`, and the three API keys.
|
|
173
|
+
|
|
174
|
+
## Configuration
|
|
175
|
+
|
|
176
|
+
The table below is the full field reference, including the few fields that remain
|
|
177
|
+
patch-only:
|
|
178
|
+
|
|
179
|
+
| field | where | meaning |
|
|
180
|
+
|:--|:--|:--|
|
|
181
|
+
| `minBodyChars` | Advanced | **Default 0 (off): HTTP status alone decides.** When set, a shorter body counts as a miss and the chain continues. A length floor cannot separate a site footer (142–332 chars) from a legitimately short page: `example.com` has 171 characters of real content. |
|
|
182
|
+
| `timeoutMs` | Advanced | per-leg timeout. Default 30000. |
|
|
183
|
+
| `order` / `searchOrder` | ▲▼ arrows | the flat ladder per capability. Covers every mode at once and takes precedence over the shipped per-mode defaults. |
|
|
184
|
+
| `modeOrders` | patch only | per-capability, per-mode override: `{ fetch: { deep: [...] } }`. Only set this to make one mode behave differently; an uncovered mode falls back to `order`. If `order` is empty too, the shipped per-mode defaults apply — that is how the no-config default works. |
|
|
185
|
+
| `enable` | Advanced | an **allow-list** of legs this plugin registers. **Empty means all.** Use it to keep a provider from ever being called — e.g. leaving a billed leg out so it is unreachable even with free-only off. |
|
|
186
|
+
| `providers` | Advanced (cost) / patch (rest) | per-leg metadata overrides: `cost` (what `freeOnly` reads), `maxChars` (per-mode budget), `requiresKey`, `kinds`, `note`. `quality` is documentation only; runtime ordering comes from `order` / `modeOrders`. |
|
|
187
|
+
| `deepseekNeedContent` | Advanced | DeepSeek search full-text. Billed per call either way; the response grows from ~5 KB to ~45 KB. |
|
|
188
|
+
| `anysearchTag` | Advanced | vertical routing, e.g. `code.doc`. It changes query semantics, not ranking. |
|
|
189
|
+
| `anysearchParams` | patch only | extra AnySearch query parameters, passed through as-is. |
|
|
190
|
+
|
|
191
|
+
> **Save rewrites the config block.** The settings page writes the whole `config` mapping
|
|
192
|
+
> through the host's `configForms` writer, which replaces the block wholesale — comments
|
|
193
|
+
> placed inside a config block do not survive a save. That is why this table exists instead
|
|
194
|
+
> of comment blocks in `cordis.patch.yml`. Comments elsewhere in the file are unaffected.
|
|
195
|
+
|
|
196
|
+
API keys are entered on the page and stored in the host credential store, which the legs
|
|
197
|
+
consult **before** the environment. A key typed into the page works without a restart.
|
|
198
|
+
|
|
199
|
+
## Why one package and not four
|
|
200
|
+
|
|
201
|
+
This started as four packages (policy / vendors / fetch chain / search chain) on a
|
|
202
|
+
single-responsibility argument. In practice that produced four settings pages, one package
|
|
203
|
+
that could not be configured at all (the shared policy has no `apply()`), and a lockstep
|
|
204
|
+
upgrade problem. Modules are the right unit for internal separation; a package is the right
|
|
205
|
+
unit for installing and configuring, and there should be exactly one.
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
config.js one schema -> one settings page
|
|
209
|
+
policy/ who is free, which mode wants which order, how much text
|
|
210
|
+
providers/ the vendor HTTP legs
|
|
211
|
+
chains/ ordering and fallback logic
|
|
212
|
+
prompt.js the one system-prompt section (when to reach for web_search)
|
|
213
|
+
client.js the settings page
|
|
214
|
+
cordis.patch.yml the default config, every field listed
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Tests
|
|
218
|
+
|
|
219
|
+
```bash
|
|
220
|
+
npm install --no-audit --no-fund # peer dependencies provide the test imports
|
|
221
|
+
npm test
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
There is no build step. `npm install` is still required in a fresh checkout because the
|
|
225
|
+
tests import `@deepseek-ai/schemastery` and `@deepseek-ai/dsh-web`; they are declared as
|
|
226
|
+
peer dependencies, not bundled.
|
|
227
|
+
`test/client-render.test.js` runs the real `client.js` through `vm` with a fake
|
|
228
|
+
`__ModuleLoader__`, a fake `primitives` shaped like the shipped one, and a fake context that
|
|
229
|
+
expands `inject().hooks` the way the shell does. It exists because static checks missed five
|
|
230
|
+
different ways this page disappeared — including `Button` being a `forwardRef` object rather
|
|
231
|
+
than a callable function, which blanked the entire card.
|
|
232
|
+
|
|
233
|
+
One class of bug appeared three times and is now covered systematically: `settingsTextField`
|
|
234
|
+
is a *string* field, so a spec that overrides only `parse` leaves the read direction broken
|
|
235
|
+
and any non-string value (boolean, array, object) reads back as `''`. A test asserts the round
|
|
236
|
+
trip for every registered field spec.
|
|
237
|
+
|
|
238
|
+
## Compatibility
|
|
239
|
+
|
|
240
|
+
- DSH `0.2.2-rc.x` (the `engines.dsh` range is `>=0.2.2-0 <0.3.0-0`).
|
|
241
|
+
- Node.js 20+.
|
|
242
|
+
- The plugin is independent of DeepSeek; DSH and the named providers are separate projects.
|
|
243
|
+
|
|
244
|
+
## License
|
|
245
|
+
|
|
246
|
+
MIT. See [LICENSE](LICENSE).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# dsh-web-fallback-chain
|
|
2
|
+
|
|
3
|
+
[English](https://github.com/T-splines/dsh-web-fallback-chain/blob/main/README.md) | **简体中文**
|
|
4
|
+
|
|
5
|
+
**给 DeepSeek Harness 的网页搜索与抓取提供一条按质量排序、带成本感知的回退链——实测排序、free-only 开关、一个设置页。**
|
|
6
|
+
|
|
7
|
+
DSH 的 `ctx.web` 每个能力只能选**一个** provider,配置里写的是固定 id 而不是优先级列表,
|
|
8
|
+
所以「先试最好的,失败后自动退到免费的」无法在 profile 里表达。本插件为每个能力注册一个
|
|
9
|
+
provider,其内部顺序就是那张优先级列表;同时把每个独立档位也注册出来,想单钉哪一个都可以。
|
|
10
|
+
|
|
11
|
+
- [为什么需要它](#为什么需要它)
|
|
12
|
+
- [差异点](#差异点)
|
|
13
|
+
- [注册了什么](#注册了什么)
|
|
14
|
+
- [安装](#安装)
|
|
15
|
+
- [默认排序](#默认排序)
|
|
16
|
+
- [free-only 开关](#free-only-开关)
|
|
17
|
+
- [设置页](#设置页)
|
|
18
|
+
- [配置](#配置)
|
|
19
|
+
- [为什么是一个包而不是四个](#为什么是一个包而不是四个)
|
|
20
|
+
- [测试](#测试)
|
|
21
|
+
- [兼容性](#兼容性)
|
|
22
|
+
|
|
23
|
+
## 为什么需要它
|
|
24
|
+
|
|
25
|
+
DSH profile 能指定「用哪个网页 provider」,但不能指定「按什么顺序试多个」。主搜索或抓取
|
|
26
|
+
失败时请求就失败,没有「再试下一个免费档」的接缝。若在每个部署里各写一遍,就会变成四个包、
|
|
27
|
+
四个设置页,以及升级时必须同步改的锁步问题。
|
|
28
|
+
|
|
29
|
+
本插件把有序链放回 provider 槽位:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
web_search ──▶ search-chain ──▶ deepseek-search-rich ──▶ anysearch ──▶ tavily
|
|
33
|
+
web_fetch ──▶ fetch-chain ──▶ anysearch ──▶ tavily ──▶ deepseek-fetch-rich ──▶ http*
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`http*` 是可选的普通 HTTP 档,由部署方另行提供(例如另一个 web-fetch 插件);本包
|
|
37
|
+
**不注册**它。链首的**可用**档服务每个请求;其余档只在它失败或返回内容太少时才尝试。
|
|
38
|
+
顺序按「返回质量」排,不是按「尝试成本」排。默认 `freeOnly: true` 时付费档在调用时被
|
|
39
|
+
跳过,所以实际链首是第一个免费可用档。
|
|
40
|
+
|
|
41
|
+
## 差异点
|
|
42
|
+
|
|
43
|
+
- **实测排序,不是拍脑袋。** 默认顺序来自本插件自己的 benchmark:15 个页面盲评抓取质量、
|
|
44
|
+
10 条查询盲评搜索相关性、20 个站点的可用性测试。数字是起点,不是对某个页面的承诺。
|
|
45
|
+
- **free-only 真的会跳过付费档。** `freeOnly` 在**调用时**判断;关闭后恢复的是**同一份**
|
|
46
|
+
顺序,而不是另外维护一张表。
|
|
47
|
+
- **一个包、一个设置页。** ▲▼ 调整档位、切换 free-only、标注回退来源、切换读取模式;
|
|
48
|
+
没有第二份配置需要同步。
|
|
49
|
+
- **诚实的回退。** 链结果是无损 JSON,可以把实际服务的档位写进输出;短正文默认不算失败
|
|
50
|
+
(`minBodyChars` 默认 0),需要时再开启长度门槛。
|
|
51
|
+
- **每个 provider 都有明确价值。** DeepSeek 搜索映射 `summary`(600–800 字)而不只是
|
|
52
|
+
snippet;AnySearch 是实测能穿过 bot 墙的档位;Tavily 是免费档里能抽取 PDF 的那个。
|
|
53
|
+
- **在关键位置有测试。** 162 个 `node --test` 用例,包括用 `vm` + 假模块加载器渲染真实设置页,
|
|
54
|
+
以及每个设置字段的往返测试。
|
|
55
|
+
|
|
56
|
+
## 注册了什么
|
|
57
|
+
|
|
58
|
+
| id | 能力 | 说明 |
|
|
59
|
+
|:--|:--|:--|
|
|
60
|
+
| `search-chain` | search | 有序搜索链(把 `searchProvider` 钉到它) |
|
|
61
|
+
| `fetch-chain` | fetch | 有序抓取链(把 `fetchProvider` 钉到它) |
|
|
62
|
+
| `deepseek-search-rich` | search | DeepSeek 搜索,映射 `summary`(600–800 字) |
|
|
63
|
+
| `deepseek-fetch-rich` | fetch | DeepSeek 抓取 |
|
|
64
|
+
| `anysearch` | search + fetch | AnySearch;实测唯一能穿过 bot 墙的档位 |
|
|
65
|
+
| `tavily` | search + fetch | Tavily;免费档里唯一能抽取 PDF 的 |
|
|
66
|
+
|
|
67
|
+
`http` 故意**不在**这张表里:它由部署方提供,不属于本包。链里可以点名它;当另一个插件
|
|
68
|
+
注册了该 id 时,抓取链退到它就会使用它。
|
|
69
|
+
|
|
70
|
+
## 安装
|
|
71
|
+
|
|
72
|
+
要求:DSH `0.2.2-rc.x`、Node.js 20+,以及 `DEEPSEEK_API_KEY`、`ANYSEARCH_API_KEY`、
|
|
73
|
+
`TAVILY_API_KEY` 中**至少一个**。没有 key 的档仍会注册并自报不可用,所以一个 key 都没有
|
|
74
|
+
时链里没有可调用的档。可选的普通 HTTP 档(`http`)需要另装 web-fetch 插件提供。
|
|
75
|
+
|
|
76
|
+
### 从 npm 安装
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
dsh plugin --profile web add @magic6/dsh-web-fallback-chain
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### 从源码安装
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
git clone https://github.com/T-splines/dsh-web-fallback-chain.git
|
|
86
|
+
cd dsh-web-fallback-chain
|
|
87
|
+
dsh plugin --profile web add "$PWD"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
包本身是一个 bundle(`dsh.bundle.patch`),默认 entry 由 bundle 挂载。把链 provider 钉到
|
|
91
|
+
profile 补丁里(`$DSH_HOME/profiles/<profile>/cordis.patch.yml`):
|
|
92
|
+
|
|
93
|
+
```yaml
|
|
94
|
+
- id: web
|
|
95
|
+
config:
|
|
96
|
+
searchProvider: search-chain
|
|
97
|
+
fetchProvider: fetch-chain
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
重新加载 profile(或重启 web app),打开 **插件 → 已安装插件 → 网页回退链
|
|
101
|
+
(dsh-web-fallback-chain)**,设置卡片就在插件详情页上。如果 profile 里已经钉了别的
|
|
102
|
+
provider,把那些钉换掉即可。
|
|
103
|
+
|
|
104
|
+
profile entry id 仍是 `web-fallback`。如果从旧包名 `dsh-web-fallback` 升级,请先卸载旧包;
|
|
105
|
+
两个都装会把同一个 entry 挂载两次。entry id 没变,原有设置继续有效。
|
|
106
|
+
|
|
107
|
+
不启动 agent 验证组合树:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
dsh --profile web --dump-config | grep -A6 'id: web-fallback'
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## 默认排序
|
|
114
|
+
|
|
115
|
+
默认**严格按实测质量降序**,所有读取模式一致:
|
|
116
|
+
|
|
117
|
+
| 档位 | 质量 | 成本 | key |
|
|
118
|
+
|:--|:--|:--|:--|
|
|
119
|
+
| `deepseek-search-rich` | 9.6 | 付费 | `DEEPSEEK_API_KEY` |
|
|
120
|
+
| `anysearch` | 7.3 | 免费 | `ANYSEARCH_API_KEY` |
|
|
121
|
+
| `tavily` | 7.3 | 免费 | `TAVILY_API_KEY` |
|
|
122
|
+
| `deepseek-fetch-rich` | 5.4 | 付费 | `DEEPSEEK_API_KEY` |
|
|
123
|
+
| `http` | 4.0 | 免费 | —(外部档,不由本包提供) |
|
|
124
|
+
|
|
125
|
+
搜索顺序:`deepseek-search-rich → anysearch → tavily`。
|
|
126
|
+
抓取顺序:`anysearch → tavily → deepseek-fetch-rich → http`(最后一档只有外部
|
|
127
|
+
web-fetch 插件注册时才存在)。
|
|
128
|
+
|
|
129
|
+
`quality` 只用于排序,不是对某个页面的承诺;数字来自本插件自己的 benchmark,你的语料可能
|
|
130
|
+
排序不同。设置页调整后写入扁平的 `order` / `searchOrder`,对所有模式同时生效。
|
|
131
|
+
|
|
132
|
+
## free-only 开关
|
|
133
|
+
|
|
134
|
+
`freeOnly`(默认**开启**)在**调用时**跳过所有标记为 `paid` 的档位。它**不重排**:排序只有
|
|
135
|
+
一份,关闭开关后恢复同一序列。设置页把付费档灰显而不是隐藏,所以显示顺序始终等于存储顺序。
|
|
136
|
+
|
|
137
|
+
## 设置页
|
|
138
|
+
|
|
139
|
+
设置页在插件详情页上——**插件 → 已安装插件 → 网页回退链**——不在「设置」里。
|
|
140
|
+
卡片只有五个主要控件,因为每个设置都有实测默认值,没有一个是必须填的:
|
|
141
|
+
|
|
142
|
+
- 两个开关:`freeOnly`、`annotateFallback`
|
|
143
|
+
- 一个选择:`defaultMode`(`brief` / `deep` / `list` / `page`)
|
|
144
|
+
- 两个 ▲▼ 阶梯:搜索链、抓取链
|
|
145
|
+
|
|
146
|
+
卡片里还有一个**高级**区,放的是比较可能调整的设置:`minBodyChars`、`timeoutMs`、
|
|
147
|
+
`enable` 白名单(以挂载勾选框呈现)、每档 `cost`、`deepseekNeedContent`、
|
|
148
|
+
`anysearchTag`,以及三个 API key。
|
|
149
|
+
|
|
150
|
+
## 配置
|
|
151
|
+
|
|
152
|
+
下表是完整字段参考,包括少数只能写补丁的字段:
|
|
153
|
+
|
|
154
|
+
| 字段 | 位置 | 含义 |
|
|
155
|
+
|:--|:--|:--|
|
|
156
|
+
| `minBodyChars` | 高级 | **默认 0(关闭):只看 HTTP 状态。** 设置后,短正文算未命中并继续链。长度门槛分不清页脚(142–332 字)和合法短页面:`example.com` 有 171 字真实正文。 |
|
|
157
|
+
| `timeoutMs` | 高级 | 单档超时,默认 30000。 |
|
|
158
|
+
| `order` / `searchOrder` | ▲▼ 箭头 | 每个能力的扁平阶梯;覆盖所有模式,优先于内置的按模式默认值。 |
|
|
159
|
+
| `modeOrders` | 仅补丁 | 按能力、按模式的覆盖:`{ fetch: { deep: [...] } }`。只给需要特殊行为的模式用;未覆盖的模式回落到 `order`。如果 `order` 也为空,则使用内置的按模式默认值——这正是「零配置默认行为」的来源。 |
|
|
160
|
+
| `enable` | 高级 | 允许注册的档位白名单。**空 = 全部**。用来让某个 provider 永远不被调用。 |
|
|
161
|
+
| `providers` | 高级(cost)/ 补丁(其余) | 每档元数据覆盖:`cost`(`freeOnly` 读它)、`maxChars`、`requiresKey`、`kinds`、`note`。`quality` 只作文档,运行时不读。 |
|
|
162
|
+
| `deepseekNeedContent` | 高级 | DeepSeek 搜索全文;无论开关都按次计费,响应从 ~5 KB 涨到 ~45 KB。 |
|
|
163
|
+
| `anysearchTag` | 高级 | 垂直路由,例如 `code.doc`;改变查询语义,不改变排序。 |
|
|
164
|
+
| `anysearchParams` | 仅补丁 | 额外 AnySearch 参数,原样透传。 |
|
|
165
|
+
|
|
166
|
+
> **保存会重写 config 块。** 设置页通过宿主的 `configForms` 写入器整体替换 `config` 映射,
|
|
167
|
+
> 所以 config 块里的注释不会在保存后保留。这就是本表存在的原因;文件其它位置的注释不受影响。
|
|
168
|
+
|
|
169
|
+
API key 在设置页输入,存进宿主凭据库;各档位**先查凭据库、再查环境变量**,所以页面上
|
|
170
|
+
输入的 key 无需重启即可生效。
|
|
171
|
+
|
|
172
|
+
## 测试
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
npm install --no-audit --no-fund # peer 依赖提供测试所需的 import
|
|
176
|
+
npm test
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
没有构建步骤,但干净 checkout 必须先 `npm install`:测试会 import
|
|
180
|
+
`@deepseek-ai/schemastery` 与 `@deepseek-ai/dsh-web`,它们声明为 peer 依赖,不随包分发。
|
|
181
|
+
|
|
182
|
+
`test/client-render.test.js` 用 `vm`、假 `__ModuleLoader__`、假 `primitives` 和按宿主方式
|
|
183
|
+
展开 `inject().hooks` 的假上下文,运行真实的 `client.js`。静态检查曾漏掉五种「页面消失」的
|
|
184
|
+
方式(包括 `Button` 是 `forwardRef` 对象而不是可调用函数),所以这里用真实渲染路径锁住。
|
|
185
|
+
|
|
186
|
+
另有一类 bug 出现过三次:`settingsTextField` 是**字符串**字段,spec 只覆盖 `parse` 会让读取方向
|
|
187
|
+
失效,任何非字符串值(boolean/array/object)都读回 `''`。现在对每个注册字段都做往返断言。
|
|
188
|
+
|
|
189
|
+
## 为什么是一个包而不是四个
|
|
190
|
+
|
|
191
|
+
最初按单一职责拆成四个包(策略 / 厂商 / 抓取链 / 搜索链)。实际结果是四个设置页、一个
|
|
192
|
+
根本无法配置的包(共享策略没有 `apply()`),以及升级时必须同步改版本的锁步问题。模块是
|
|
193
|
+
内部拆分的好单位;安装和配置的单位应当是包,而且只应该有一个。
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
config.js 一份 schema -> 一个设置页
|
|
197
|
+
policy/ 谁免费、哪个模式要什么顺序、正文取多少
|
|
198
|
+
providers/ 各厂商 HTTP 档
|
|
199
|
+
chains/ 排序与回退逻辑
|
|
200
|
+
prompt.js 唯一一段系统提示(何时使用 web_search)
|
|
201
|
+
client.js 设置页
|
|
202
|
+
cordis.patch.yml 默认配置,每个字段都列出
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## 兼容性
|
|
206
|
+
|
|
207
|
+
- DSH `0.2.2-rc.x`(`engines.dsh` 为 `>=0.2.2-0 <0.3.0-0`)。
|
|
208
|
+
- Node.js 20+。
|
|
209
|
+
- 本插件与 DeepSeek 官方无关;DSH 与文中 provider 都是独立项目。
|
|
210
|
+
|
|
211
|
+
## 许可
|
|
212
|
+
|
|
213
|
+
MIT,见 [LICENSE](LICENSE)。
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
- insert:
|
|
2
|
+
- id: web-fallback
|
|
3
|
+
name: dsh-web-fallback-chain
|
|
4
|
+
config:
|
|
5
|
+
# Every field below is declared so the plugin resolves cleanly: a
|
|
6
|
+
# `volatile()` field that is absent from the config is read during schema
|
|
7
|
+
# resolution, before injection completes, and throws. Omit one and the
|
|
8
|
+
# plugin silently fails to register.
|
|
9
|
+
freeOnly: true
|
|
10
|
+
defaultMode: brief
|
|
11
|
+
order: []
|
|
12
|
+
searchOrder: []
|
|
13
|
+
modeOrders: {}
|
|
14
|
+
# 0 = 关闭:只看 HTTP 状态。曾经是 600,但它把 example.com(171 字真实正文)
|
|
15
|
+
# 判成失败,于是链绕到另一个档拿了 958 字的六语种重复内容——更长、更糟,
|
|
16
|
+
# 却看起来像成功。长度无法区分「页脚」和「合法短页面」。
|
|
17
|
+
minBodyChars: 0
|
|
18
|
+
annotateFallback: true
|
|
19
|
+
enable: []
|
|
20
|
+
providers: {}
|
|
21
|
+
timeoutMs: 30000
|
|
22
|
+
deepseekNeedContent: false
|
|
23
|
+
anysearchTag: ''
|
|
24
|
+
anysearchParams: ''
|
package/icon.svg
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="wfb-chain" x1="0" y1="0" x2="1" y2="1">
|
|
4
|
+
<stop offset="0%" stop-color="#7FB7FC" />
|
|
5
|
+
<stop offset="100%" stop-color="#658EFF" />
|
|
6
|
+
</linearGradient>
|
|
7
|
+
</defs>
|
|
8
|
+
<!-- Three ranked legs: the top one serves, the two below are the fallbacks. -->
|
|
9
|
+
<rect x="7" y="8" width="14" height="5" rx="2.5" fill="url(#wfb-chain)" />
|
|
10
|
+
<rect x="7" y="16" width="11" height="5" rx="2.5" fill="#7FB7FC" fill-opacity="0.55" />
|
|
11
|
+
<rect x="7" y="24" width="8" height="5" rx="2.5" fill="#7FB7FC" fill-opacity="0.3" />
|
|
12
|
+
<!-- The arrow that makes the order meaningful. -->
|
|
13
|
+
<path d="M24 10.5h4.5M26.5 8l2.5 2.5-2.5 2.5" stroke="#658EFF" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
|
|
14
|
+
<path d="M24 18.5h4.5M26.5 16l2.5 2.5-2.5 2.5" stroke="#7FB7FC" stroke-opacity="0.6" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" />
|
|
15
|
+
</svg>
|
package/locale/en.json
ADDED