@fffangchenghao/dsh-web-search 0.24.0 → 0.24.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.
@@ -0,0 +1,203 @@
1
+ # Engines
2
+
3
+ What each engine is asked for, how its answer is parsed, and what was actually
4
+ measured on this network. The registry is `HOSTS` in `src/engines.ts`; the
5
+ parsers are in `src/parsers.ts`; the shared request path is
6
+ `src/transport.ts`.
7
+
8
+ - [Architecture](architecture.md)
9
+ - [Troubleshooting](troubleshooting.md)
10
+ - [README](../README.md) · [中文说明](../README.zh-CN.md)
11
+
12
+ ## The shared request
13
+
14
+ Every engine gets the same base headers, built in `src/transport.ts`:
15
+
16
+ ```
17
+ user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15
18
+ accept-language: zh-CN,zh;q=0.9,en;q=0.8
19
+ accept: application/json (JSON POST engines)
20
+ accept: text/html,application/xhtml+xml (scraped pages)
21
+ content-type: application/json (JSON POST engines only)
22
+ ```
23
+
24
+ - **Route.** `anysearch`, `cn.bing` and `so` go direct first and are retried
25
+ through the tunnel only if the direct attempt fails. `ddg-html`, `www.bing` and
26
+ `ddg-lite` are `viaProxy`: they tunnel from the start, and they are filtered out
27
+ of a run when no proxy is available rather than failing slowly.
28
+ - **Deadline.** `timeoutMs` per attempt (default 15 000 ms). Direct requests use
29
+ `AbortSignal.timeout` combined with the caller's signal; tunnelled requests use
30
+ the socket timeouts in `src/proxy.ts`.
31
+ - **Redirects.** Direct requests let `fetch` follow them; tunnelled requests
32
+ follow up to four hops themselves.
33
+ - **Echo check.** Every scraped page must contain one query token of at least
34
+ three characters (`echoesQuery`) or it is treated as a rate-limit page. JSON
35
+ engines set `skipEcho` because their envelope validates itself.
36
+
37
+ ## `anysearch` — anonymous JSON API
38
+
39
+ | | |
40
+ | --- | --- |
41
+ | Request | `POST https://api.anysearch.com/v1/search` |
42
+ | Body | `{"query":"<query>","max_results":20}` |
43
+ | Region / weight | `both` / 2 (two slots per fusion round) |
44
+ | Tier | primary |
45
+
46
+ The response is an envelope, not markup:
47
+
48
+ ```json
49
+ { "code": 0, "message": "success", "request_id": "…",
50
+ "data": { "results": [{ "title": "…", "url": "…", "snippet": "…", "content": "…" }], "metadata": { } } }
51
+ ```
52
+
53
+ `parseAnySearch` requires `code === 0` and an array at `data.results`; anything
54
+ else — a non-zero code, bad JSON, a missing array — yields `[]` rather than an
55
+ exception. Rows are dropped when `url` does not resolve to an absolute `http(s)`
56
+ URL, and empty `title`/`snippet` fields are omitted. The extra `content` field is
57
+ deliberately ignored: the seam wants a citable title/link/snippet, and the body
58
+ belongs to `web_fetch`.
59
+
60
+ A live capture (see [fixtures](../test/fixtures/README.md)) shows the envelope
61
+ and rows above, plus the service's error shape: an empty query is answered with
62
+ HTTP 400 and `{"code":-1,"message":"Query is required."}`.
63
+
64
+ The endpoint is metered: anonymous calls return at most 10 results, and the
65
+ provider's free tier with a key is documented upstream as 1 000 requests per day.
66
+ That is why the engine asks for 20 rows (`ANYSEARCH_MAX_RESULTS`) but the merge
67
+ sees at most what the service sends.
68
+
69
+ ## `ddg-html` — DuckDuckGo HTML
70
+
71
+ | | |
72
+ | --- | --- |
73
+ | Request | `GET https://html.duckduckgo.com/html/?q=<urlencoded query>` |
74
+ | Region / weight | `global` / 1 |
75
+ | Tier / route | primary / tunnel only |
76
+
77
+ The richest English endpoint of the three DuckDuckGo faces here. `parseDdgHtml`
78
+ matches anchors whose `class` is `result__a` (single or double quotes, any
79
+ attribute order), takes the anchor text as the title, and looks for an element
80
+ with `class="result__snippet"` between this anchor and the next one as the
81
+ snippet. Hrefs may be direct or wrapped as `/l/?uddg=<percent-encoded>`, which
82
+ `resolveHref` unwraps.
83
+
84
+ Measured: the live capture on 2026-10-22 serves **direct** hrefs, not the `uddg`
85
+ wrapper that the original implementation was written against. The unwrapper is
86
+ kept because the wrapper still appears, and it is pinned by a synthetic fixture.
87
+
88
+ ## `cn.bing` — Bing China
89
+
90
+ | | |
91
+ | --- | --- |
92
+ | Request | `GET https://cn.bing.com/search?q=<urlencoded query>` |
93
+ | Region / weight | `cn` / 1 |
94
+ | Tier / route | primary / direct first, tunnel retry |
95
+
96
+ The Chinese workhorse: the `cn` host targets the mainland index, mixed
97
+ Chinese/English queries work, and the result URLs are direct links. No market
98
+ parameters are sent.
99
+
100
+ ## `www.bing` — Bing international (fallback)
101
+
102
+ | | |
103
+ | --- | --- |
104
+ | Request | `GET https://www.bing.com/search?q=<urlencoded>&setmkt=en-US&setlang=en&cc=US` |
105
+ | Region / weight | `global` / 1 |
106
+ | Tier / route | fallback / tunnel only |
107
+
108
+ `parseBing` splits the page on `<li class="b_algo"`, takes the first
109
+ `<h2><a href>` pair as title and URL, and the first `<p>` as the snippet.
110
+
111
+ Links are frequently Bing click trackers — `/ck/a?...&u=a1<base64url>` — where
112
+ the `&` arrives HTML-escaped as `&amp;`. `resolveHref` decodes `&amp;`/`&#38;`
113
+ first, base64url-decodes the payload, and rejects the tracker if no real target
114
+ comes out.
115
+
116
+ **Why it is only a fallback.** Measured on stopword-heavy English queries it
117
+ matched a single token and answered with unrelated pages: `how to set up postgres
118
+ logical replication` returned jigsaw-puzzle sites for "set", while the engines
119
+ above stayed on topic. It is worth reaching only when nothing else answered.
120
+
121
+ ## `so` — 360 search
122
+
123
+ | | |
124
+ | --- | --- |
125
+ | Request | `GET https://www.so.com/s?q=<urlencoded query>` |
126
+ | Region / weight | `cn` / 1 |
127
+ | Tier / route | primary / direct first, tunnel retry |
128
+
129
+ `parseSo` splits on `class="res-list"`, finds the heading `<h3 class="res-title…">`
130
+ (the served class value carries a trailing space, and the wrapper is a `<li>` for
131
+ ordinary results and a `<div>` for rich ones, so the element name is not matched),
132
+ then reads the **`data-mdurl`** attribute of the first anchor after it. The
133
+ `href` is a 360 click tracker, which is not a citable source: a result without
134
+ `data-mdurl` is skipped. The snippet comes from `class="res-list-summary"`.
135
+
136
+ ## `ddg-lite` — DuckDuckGo Lite (fallback)
137
+
138
+ | | |
139
+ | --- | --- |
140
+ | Request | `GET https://lite.duckduckgo.com/lite/?q=<urlencoded query>` |
141
+ | Region / weight | `global` / 1 |
142
+ | Tier / route | fallback / tunnel only |
143
+
144
+ `parseDdgLite` accepts single- or double-quoted attributes, because this page
145
+ serves `class='result-link'` where Bing serves double quotes. Each hit is
146
+ examined up to the next hit, which is where its sibling
147
+ `<td class='result-snippet'>` lives.
148
+
149
+ ## Parser regressions
150
+
151
+ Six failures were paid for once and are now pinned by tests and fixtures:
152
+
153
+ 1. a Bing `&amp;u=a1<base64url>` tracker must decode to the real target, not a
154
+ `bing.com/ck/a` URL;
155
+ 2. a DuckDuckGo `/l/?uddg=<urlencoded>` wrapper must unwrap to the target;
156
+ 3. a single-quoted `class='result-link'` must still be parsed;
157
+ 4. 360's `data-mdurl` must be used, not the click tracker;
158
+ 5. an AnySearch envelope with `code !== 0` must yield `[]`;
159
+ 6. `echoesQuery` must reject a rate-limit/captcha page served for a different
160
+ query.
161
+
162
+ Fixtures: [test/fixtures/README.md](../test/fixtures/README.md) lists every file,
163
+ the exact URL it came from, the query and the capture date (2026-10-22). Two
164
+ files are synthetic and marked as such: the `uddg` wrapper and Bing's
165
+ rate-limited reply, whose block page could not be provoked on demand.
166
+
167
+ ## What was measured
168
+
169
+ Timings on this network, with a tunnel on:
170
+
171
+ | Situation | Time |
172
+ | --- | --- |
173
+ | CJK query, `auto` | 1.4–2.3 s |
174
+ | CJK query, domestic engines only (no AnySearch) | 0.2–0.7 s |
175
+ | ASCII query, `auto` | 2.6–3.8 s |
176
+
177
+ Coverage for an English query: 16–30 sources across 12–21 distinct domains, and
178
+ the first 8 slots are 8/8 on-topic foreign documentation. The A/B evidence for
179
+ leading CJK queries with AnySearch is in the [README](../README.md#ab-evidence-cjk-queries-need-anysearch-too).
180
+
181
+ Admission is weighted, scoring is not: with weights 2/1/1 over lists of 10, 10
182
+ and 4 results at `limit: 8`, the 8 slots split 4/2/2 between the engines. The
183
+ previous rule multiplied every row of an engine by its weight, which let
184
+ AnySearch fill all 8 slots and starved the Chinese engines completely (8/0/0).
185
+
186
+ Block pages seen in practice:
187
+
188
+ - 360 served its `访问异常页面` with a captcha under rapid unattended requests;
189
+ - another domestic engine (Shenma, not part of this registry) served an `x5sec`
190
+ punish page during the same measurements;
191
+ - Bing answered repeated rapid requests with a "trending" feed belonging to
192
+ somebody else's search — HTTP 200, so only the echoed-query check catches it.
193
+
194
+ That evidence is why block pages and echoed-query mismatches cool an engine down
195
+ instead of being retried on every search.
196
+
197
+ ## What could not be made to work
198
+
199
+ - **Google.** A tunnelled `www.google.com/search` returns a JavaScript shell
200
+ (94 KB, 1–3 links); headless Chrome is redirected to `google.com.hk` and gets a
201
+ reCAPTCHA page. `gbv=1`, a consent cookie and a mobile user agent all failed.
202
+ - **Public SearXNG instances.** Eight were tried; all answered 429, 403 or
203
+ something that was not JSON.
Binary file
@@ -0,0 +1,84 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1400" height="760" viewBox="0 0 1400 760" role="img" aria-labelledby="title desc">
2
+ <title id="title">Ranking quality, measured offline: baseline and parameter sweep</title>
3
+ <desc id="desc">Baseline precision, recall and MRR at 8 for the current 0.24.x replay over 20 fixed queries, plus the 81-configuration marginal sweep.</desc>
4
+ <defs>
5
+ <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#0a1120"/><stop offset="0.55" stop-color="#0d1626"/><stop offset="1" stop-color="#0a1322"/>
7
+ </linearGradient>
8
+ <linearGradient id="card" x1="0" y1="0" x2="0" y2="1">
9
+ <stop offset="0" stop-color="#122138"/><stop offset="1" stop-color="#0d1829"/>
10
+ </linearGradient>
11
+ <filter id="glow" x="-40%" y="-40%" width="180%" height="180%">
12
+ <feGaussianBlur stdDeviation="8" result="blur"/><feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
13
+ </filter>
14
+ <style>
15
+ .sans { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif; }
16
+ .title { fill: #f4f7fb; font-size: 38px; font-weight: 700; letter-spacing: -0.6px; }
17
+ .sub { fill: #8ea3bf; font-size: 17px; }
18
+ .h2 { fill: #f4f7fb; font-size: 24px; font-weight: 700; }
19
+ .h3 { fill: #9db1cc; font-size: 15px; font-weight: 600; letter-spacing: 0.2px; }
20
+ .muted { fill: #8195b0; font-size: 14px; }
21
+ .tiny { fill: #6f839d; font-size: 12.5px; }
22
+ .val { fill: #dbe8f8; font-size: 17px; font-weight: 600; }
23
+ .axis { fill: #8ba0bb; font-size: 15px; font-weight: 600; }
24
+ .blue { fill: #11243d; stroke: #5b8def; }
25
+ .green { fill: #112a2a; stroke: #37c996; }
26
+ .orange { fill: #2b2418; stroke: #f0a43a; }
27
+ </style>
28
+ </defs>
29
+ <rect width="1400" height="760" fill="url(#bg)"/>
30
+ <text x="60" y="62" class="sans title">Ranking quality, measured offline</text>
31
+ <text x="60" y="98" class="sans sub">20 fixed queries, tier-aware replay of recorded fixtures; no network. v0.24.x.</text>
32
+ <rect x="60" y="135" width="600" height="565" rx="16" fill="url(#card)" stroke="#294563" stroke-width="1.5"/>
33
+ <rect x="700" y="135" width="640" height="565" rx="16" fill="url(#card)" stroke="#294563" stroke-width="1.5"/>
34
+ <text x="90" y="184" class="sans h2">Baseline (v0.24.x replay)</text>
35
+ <text x="730" y="184" class="sans h2">Parameter sweep: marginal MRR@8</text>
36
+ <text x="730" y="211" class="sans muted">81 configurations, paired bootstrap vs defaults</text>
37
+ <rect x="190" y="465.6" width="82" height="144.4" rx="5" fill="none" stroke="#5b8def" stroke-width="2.5" class="blue" opacity="0.95"/>
38
+ <text x="231" y="495.6" text-anchor="middle" class="sans val" fill="#5b8def">0.4375</text>
39
+ <text x="231" y="652" text-anchor="middle" class="sans axis">P@8</text>
40
+ <rect x="395" y="348.8" width="82" height="261.2" rx="5" fill="none" stroke="#37c996" stroke-width="2.5" class="green" opacity="0.95"/>
41
+ <text x="436" y="378.8" text-anchor="middle" class="sans val" fill="#37c996">0.7917</text>
42
+ <text x="436" y="652" text-anchor="middle" class="sans axis">R@8</text>
43
+ <rect x="515" y="343.6" width="82" height="266.4" rx="5" fill="none" stroke="#f0a43a" stroke-width="2.5" class="orange" opacity="0.95"/>
44
+ <text x="556" y="373.6" text-anchor="middle" class="sans val" fill="#f0a43a">0.8071</text>
45
+ <text x="556" y="652" text-anchor="middle" class="sans axis">MRR@8</text>
46
+ <line x1="88" y1="610" x2="632" y2="610" stroke="#39536f" stroke-width="1"/>
47
+ <text x="90" y="681" class="sans tiny">n=20, k=8; 8 engines (7 primary + 1 fallback), zero-hit queries: 0</text>
48
+ <text x="745" y="258" class="sans h3">rrfConstant</text>
49
+ <rect x="745" y="442.7" width="38" height="147.3" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
50
+ <text x="764" y="432.7" text-anchor="middle" class="sans tiny" fill="#37c996">0.834</text>
51
+ <text x="764" y="615" text-anchor="middle" class="sans tiny">40</text>
52
+ <rect x="792" y="465.8" width="38" height="124.2" rx="4" fill="#0f2036" stroke="#5b8def" stroke-width="2" opacity="0.97"/>
53
+ <text x="811" y="455.8" text-anchor="middle" class="sans tiny" fill="#5b8def">0.828</text>
54
+ <text x="811" y="615" text-anchor="middle" class="sans tiny">60</text>
55
+ <rect x="839" y="496.9" width="38" height="93.1" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
56
+ <text x="858" y="486.9" text-anchor="middle" class="sans tiny" fill="#37c996">0.819</text>
57
+ <text x="858" y="615" text-anchor="middle" class="sans tiny">80</text>
58
+ <text x="935" y="258" class="sans h3">authorityBoost</text>
59
+ <rect x="935" y="466.9" width="38" height="123.1" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
60
+ <text x="954" y="456.9" text-anchor="middle" class="sans tiny" fill="#37c996">0.827</text>
61
+ <text x="954" y="615" text-anchor="middle" class="sans tiny">0.1</text>
62
+ <rect x="982" y="471.6" width="38" height="118.4" rx="4" fill="#0f2036" stroke="#5b8def" stroke-width="2" opacity="0.97"/>
63
+ <text x="1001" y="461.6" text-anchor="middle" class="sans tiny" fill="#5b8def">0.826</text>
64
+ <text x="1001" y="615" text-anchor="middle" class="sans tiny">0.25</text>
65
+ <rect x="1029" y="466.9" width="38" height="123.1" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
66
+ <text x="1048" y="456.9" text-anchor="middle" class="sans tiny" fill="#37c996">0.827</text>
67
+ <text x="1048" y="615" text-anchor="middle" class="sans tiny">0.4</text>
68
+ <text x="1125" y="258" class="sans h3">freshnessBoost</text>
69
+ <rect x="1125" y="483.6" width="38" height="106.4" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
70
+ <text x="1144" y="473.6" text-anchor="middle" class="sans tiny" fill="#37c996">0.823</text>
71
+ <text x="1144" y="615" text-anchor="middle" class="sans tiny">0.1</text>
72
+ <rect x="1172" y="478.0" width="38" height="112.0" rx="4" fill="#0f2036" stroke="#5b8def" stroke-width="2" opacity="0.97"/>
73
+ <text x="1191" y="468.0" text-anchor="middle" class="sans tiny" fill="#5b8def">0.825</text>
74
+ <text x="1191" y="615" text-anchor="middle" class="sans tiny">0.2</text>
75
+ <rect x="1219" y="443.8" width="38" height="146.2" rx="4" fill="#0f2036" stroke="#37c996" stroke-width="2" opacity="0.97"/>
76
+ <text x="1238" y="433.8" text-anchor="middle" class="sans tiny" fill="#37c996">0.834</text>
77
+ <text x="1238" y="615" text-anchor="middle" class="sans tiny">0.35</text>
78
+ <line x1="728" y1="590" x2="1310" y2="590" stroke="#39536f" stroke-width="1"/>
79
+ <rect x="730" y="632" width="580" height="62" rx="8" fill="#0b1728" stroke="#2f4b6a" stroke-width="1"/>
80
+ <text x="746" y="651" class="sans tiny" fill="#dbe8f8" font-weight="700">Best grid point: rrf=40, authority=0.25, freshness=0.35</text>
81
+ <text x="746" y="668" class="sans tiny" fill="#37c996">MRR 0.8583 vs 0.8071 default (+0.0512)</text>
82
+ <text x="746" y="685" class="sans tiny" fill="#f0a43a">95% CI [0.0000, +0.1250] touches zero: a direction, not a proven win</text>
83
+ <text x="730" y="725" class="sans tiny" fill="#6f839d">Blue = shipped default. Marginals average every configuration in the grid.</text>
84
+ </svg>
@@ -6,6 +6,8 @@ This note answers three questions from the public 30-query comparison:
6
6
  2. Can the AnySearch tail and the Chinese Rust miss be fixed?
7
7
  3. Does the fix require a vector database or a different retrieval model?
8
8
 
9
+ > **Version note (2026-11-02):** 0.24.0 added Windows system-proxy discovery, and 0.24.1 and 0.24.2 are documentation/metadata patches. The search path is unchanged, so these 0.23.0 measurements still describe 0.24.x.
10
+
9
11
  The short answer: Exa is a different architecture, not a faster RRF loop. This
10
12
  plugin can borrow tail-tolerance and source-specific facts, but copying Exa's
11
13
  semantic index would be a different product. The changes below improve the
@@ -0,0 +1,160 @@
1
+ # 让 DSH 插件的配置出现在「设置」里:四层判定链
2
+
3
+ > 结论先行:一个插件配置项要能在 Settings 里编辑,需要**同时**满足四层条件。
4
+ > 任何一层不满足,症状都完全一样——**设置页空白**。这就是它难 debug 的原因。
5
+ > 本文的 file:line 均来自 `DeepSeek Harness.app/Contents/Resources/app.asar`(2026-10 版本)。
6
+
7
+ ## 症状
8
+
9
+ 设置页显示插件标题和描述,但下面没有控件;或显示「当前部署尚未提供此插件的设置」。
10
+ 插件本身加载正常(工具能用),日志里可能有一行 `warning: 1 entry did not activate`。
11
+
12
+ ## 四层判定链
13
+
14
+ ### 第 1 层:插件必须真正激活(`fiber.state === 2`)
15
+
16
+ `@deepseek-ai/dsh-settings/lib/index.js` 的 `describe()` 开头:
17
+
18
+ ```js
19
+ const schema = this.schema(entry);
20
+ if (schema === undefined || entry.fiber === undefined
21
+ || entry.fiber.runtime === null || entry.fiber.state !== 2) return [];
22
+ ```
23
+
24
+ 而 `schema(entry)` 是:
25
+
26
+ ```js
27
+ schema(entry) {
28
+ const schema = entry.fiber?.runtime?.Config;
29
+ return schema !== undefined && 'toJSON' in schema ? schema : undefined;
30
+ }
31
+ ```
32
+
33
+ **要点:schema 挂在「运行时对象」上,不是模块命名空间上。**
34
+
35
+ Loader 的 `unwrapExports`(`cordis-plugin-loader/lib/index.js:669`):
36
+
37
+ ```js
38
+ exports = exports.default ?? exports;
39
+ ```
40
+
41
+ | 插件导出写法 | 结果 |
42
+ |---|---|
43
+ | `export function apply` + `export { Config }`(无 default) | ✅ `plugin` = 命名空间,`plugin.Config` 命中 |
44
+ | `export default Object.assign(apply, { Config, inject })` | ✅ `plugin` = default,`Config` 命中 |
45
+ | `export default apply` 再另写 `export const Config` | ❌ default 存在 → 命名空间被丢弃 → `runtime.Config` 为 undefined |
46
+
47
+ **函数式插件若用 default 导出,必须把 `Config` 和 `inject` 一起挂上去**;只挂 `Config` 会得到
48
+ `Error: cannot get property "web" without inject`——Cordis 从它挂载的那个对象读 `inject`。
49
+
50
+ ### 第 2 层:配置校验必须通过
51
+
52
+ Loader 只校验一次,校验的是 **`entry.options.config`(patch 里的原始值)**:
53
+
54
+ ```js
55
+ // cordis/lib/index.js:1355 → :1345 → :956
56
+ const result = runtime.Config['~standard'].validate(config);
57
+ if (result.issues) throw new ValidationError(result.issues);
58
+ return result.value;
59
+ ```
60
+
61
+ **校验后的 `result.value` 里,每个 volatile 字段都是 `{ get }` 持有器,不是值。**
62
+
63
+ 最容易踩的坑:**别把已经解析过的 config 再喂回 schema**。
64
+
65
+ ```ts
66
+ // ❌ 在 apply 内部这样写,必炸
67
+ const settings = Config(config as PluginConfig);
68
+ // ValidationError: $.timeoutMs expected number but got [object Object]
69
+ ```
70
+
71
+ 这条错误消息**没有** `invalid config:` 前缀,说明它是 schemastery 抛的(你自己的代码),
72
+ 却被 Host 报成「entry did not activate」,极易误判成插件加载失败。
73
+
74
+ 正确做法:先解包再校验,或干脆只在校验时用 plain 值、输出时优先用调用方的持有器。
75
+
76
+ ### 第 3 层:至少一个字段带 `meta.volatile`
77
+
78
+ `lib/types/schema.js:43`:
79
+
80
+ ```js
81
+ export function volatileForm(schema) {
82
+ if (schema.meta.volatile) return plainSchema(schema);
83
+ if (schema.type === 'object') {
84
+ // 只保留 volatileForm !== undefined 的子字段
85
+ return Object.keys(dict).length === 0 ? undefined : z.object(dict);
86
+ }
87
+ return undefined;
88
+ }
89
+ ```
90
+
91
+ `describe()` 里 `if (form === undefined) return [];`——**一个 volatile 字段都没有,整个命名空间被丢弃**。
92
+
93
+ ### 第 4 层:消费方必须 `.get()`
94
+
95
+ 一旦标了 `.volatile()`,schema 解析结果是 `{ get: fn }`:
96
+
97
+ ```js
98
+ z.object({ timeoutMs: z.number().default(15000).volatile() })({})
99
+ // → { timeoutMs: { get: [Function], [Symbol(cosmokit.volatile.write)]: [Function] } }
100
+ // .get() === 15000
101
+ ```
102
+
103
+ 所以读取处必须解包:
104
+
105
+ ```ts
106
+ const read = (v: unknown) => {
107
+ const holder = v as { get?: unknown } | null;
108
+ return typeof holder?.get === 'function' ? (holder.get as () => unknown)() : v;
109
+ };
110
+ ```
111
+
112
+ 数组也一样——`{}` 只是持有器的 **JSON 形态**(`get` 是函数、writer 是 symbol)。不标数组反而会让
113
+ 设置页保存时报 `Config field "hosts" is not volatile`(`dsh-settings/lib/types/index.js:351`)。
114
+
115
+ ## 最小 checklist(新插件抄这个)
116
+
117
+ ```ts
118
+ export const Config = z.object({
119
+ someScalar: z.string().default('').description('…').volatile(), // 标量标 volatile
120
+ someArray: z.array(z.string()).default([]).description('…').volatile(), // 数组也标
121
+ });
122
+
123
+ export function apply(ctx, config) {
124
+ // config 里已是持有器:读的时候必须 .get()
125
+ const value = config.someScalar.get();
126
+ }
127
+
128
+ export default Object.assign(apply, { Config, inject }); // Config + inject 一起挂
129
+ ```
130
+
131
+ 保存/生效语义:**只有 volatile 字段变化**才走 live commit(原地改持有器、不重挂载,
132
+ `cordis-plugin-loader/lib/index.js:382-435`);其他字段变化会整个插件重挂载。因此
133
+ 如果插件在 `apply` 里缓存了配置快照,volatile 的实时改动对缓存那份不生效——要么每次调用重读,
134
+ 要么接受「需重挂载」。
135
+
136
+ ## 诊断顺序(不要跳步)
137
+
138
+ 1. **先确认插件激活**:看有没有 `did not activate`,有就先修激活,别动设置页;
139
+ 2. **确认 `runtime.Config` 存在**:`describe()` 第一行就依赖它;
140
+ 3. **确认 patch 校验通过**:注意报错有没有 `invalid config:` 前缀,没有就是你自己代码抛的;
141
+ 4. **确认命名空间被收录**:字段有没有 `meta.volatile`;
142
+ 5. **确认客户端读的是正确的 ns 名**:`entry.options.id`(通常等于 patch 里的 `id`);
143
+ 6. 最后才怀疑客户端渲染。
144
+
145
+ ## 这次踩过的四个误判(供警惕)
146
+
147
+ | 当时的判断 | 为什么看起来合理 | 实际 |
148
+ |---|---|---|
149
+ | 「客户端没 inject `configForms`」 | 页面确实什么都没渲染 | 真实存在但非根因 |
150
+ | 「表单是异步投影,读太早」 | 加订阅后报错消失 | 真实存在但非根因 |
151
+ | 「字段缺 `.volatile()`」 | 官方插件都有这个标记 | 真实存在但非根因 |
152
+ | 「要重装/换安装方式」 | 别的插件能显示,我们是手装的 | 无关 |
153
+
154
+ **根因是第 2 层**:`apply` 内部二次校验已解析的 config,抛在 plugin 内 → 表现为「未激活」。
155
+ 四层都修对之后页面才出来——所以每次只修一层,症状看起来完全没变。
156
+
157
+ **教训:先定位「命名空间有没有被 Host 收录」,再改客户端。** 客户端加一行诊断
158
+ (把 `settings.describe()` 返回的 ns 列表打印出来)能在 10 分钟内省掉上面四个误判。
159
+
160
+ > 同一份内容也作为 skill 存放在 `~/.dsh/skills/dsh-plugin-settings-form/SKILL.md`(自包含,触发时一次性加载)。改这里时请同步改那边。
@@ -77,7 +77,7 @@ comparable across commits; `--record` is the only mode that touches the network.
77
77
 
78
78
  ![Baseline and sweep](images/bench.png)
79
79
 
80
- Baseline (v0.15.0, 20 queries, k=8, tier-aware replay):
80
+ Baseline (current v0.24.x replay, 20 queries, k=8; tier-aware protocol introduced in 0.15.0):
81
81
 
82
82
  | metric | overall | Chinese | English |
83
83
  |---|---:|---:|---:|
@@ -29,7 +29,7 @@ Only `0.2.1-rc.2` is declared, because that is the version actually exercised.
29
29
  `mktemp -d`; the real `~/.dsh` was never written to. Bundled pnpm 11.28.5.
30
30
  - **Windows CI:** GitHub Actions `windows-latest`, Node 24. Install, typecheck,
31
31
  the full test suite, build and the entry-point import all pass. Run:
32
- https://github.com/fangchenghao/dsh-web-search/actions/runs/40354223874
32
+ https://github.com/fangchenghao/dsh-web-search/actions/runs/41389877558
33
33
  (the matrix also runs on macOS and Ubuntu). This is a CI environment, not a
34
34
  claim about every Windows terminal or proxy client.
35
35