@nite07/dsh-search 0.1.2 → 0.1.4
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/README.md +21 -7
- package/README.zh.md +21 -7
- package/dist/client.js +120 -64
- package/dist/index.js +2141 -190
- package/dist/index.js.map +4 -4
- package/docs/BACKENDS.md +80 -0
- package/docs/VERIFICATION.md +11 -0
- package/locale/en.json +16 -8
- package/locale/zh.json +16 -8
- package/package.json +3 -2
package/docs/BACKENDS.md
CHANGED
|
@@ -267,3 +267,83 @@ Remaining documented-only entries: every keyed backend (no credential supplied h
|
|
|
267
267
|
## Retired entries
|
|
268
268
|
|
|
269
269
|
**Serper** was the only candidate whose contract could not be established from public official documentation (the playground is login-gated), so it was removed from the shipped catalogue on 2026-11-17 by user decision. Its config rows are pruned on load, not rejected; no other backend inherits its credential. The pricing facts above stay in this audit because the platform itself still exists.
|
|
270
|
+
|
|
271
|
+
## Reddit (added 2026-11-17)
|
|
272
|
+
|
|
273
|
+
Reddit needs two different paths, because its public REST endpoints changed:
|
|
274
|
+
|
|
275
|
+
| Access mode | Credential | Transport | Notes |
|
|
276
|
+
| --- | --- | --- | --- |
|
|
277
|
+
| `anonymous` (default) | none | Reddit's Android app endpoint (`gql-fed.reddit.com`, persisted operations) | Since 2026-10 the public REST `/search` and `/comments` answer 403 to anonymous tokens, so this mode uses the same anonymous application-only token the Android client obtains. No published quota. |
|
|
278
|
+
| `oauth` | `{clientId, clientSecret}` or those plus `{username, password}` | `oauth.reddit.com` REST | Official API. `client_credentials` reads public data; adding a username and password switches to the script grant. Roughly 100 queries/minute per client for non-commercial use. |
|
|
279
|
+
|
|
280
|
+
The mode lists are ordered by setup cost, and the first mode is the default: Reddit starts on `anonymous` because it needs no account at all.
|
|
281
|
+
|
|
282
|
+
The two modes never fall back to each other: a mode with no usable credential or a rejected token reports an authentication failure naming the mode, and the message says to switch modes rather than doing it silently.
|
|
283
|
+
|
|
284
|
+
`reddit_thread` is a separate tool rather than a search backend: a discussion is not a search result. It returns the post plus a nested comment tree, capped by depth (default 3), top-level count (default 100) and a character budget (20,000), and states when it truncated. Comment text is untrusted user content and is labelled as such in the tool description.
|
|
285
|
+
|
|
286
|
+
Source of the anonymous path: the `bestnite/reddit-readonly-mcp` implementation, which documents the 403 change and the persisted-operation hashes.
|
|
287
|
+
|
|
288
|
+
## X / Twitter (added 2026-11-17)
|
|
289
|
+
|
|
290
|
+
Two access modes, chosen explicitly; neither falls back to the other.
|
|
291
|
+
|
|
292
|
+
| Access mode | Credential | Transport | Cost |
|
|
293
|
+
| --- | --- | --- | --- |
|
|
294
|
+
| `session` (default) | `{authToken, ct0}` — the cookies of a signed-in X browser session | `x.com/i/api/graphql/<queryId>/SearchTimeline` with `x-client-transaction-id` signing | No fee; bounded by the account's own rate limits |
|
|
295
|
+
| `key` | `{bearerToken}` — an app-only bearer token from the X developer console | `api.x.com/2/tweets/search/recent` | Pay per post read, about $0.005 each; the `postsPerSearch` option (default 10) bounds it |
|
|
296
|
+
|
|
297
|
+
X defaults to `session` because it needs no developer app or billing set-up.
|
|
298
|
+
|
|
299
|
+
Facts that shape the design:
|
|
300
|
+
|
|
301
|
+
- The official endpoint rejects `max_results` below 10 and above 100, so the request is always clamped into that window and the caller's `postsPerSearch` cap is applied again to the returned rows. Asking for 3 posts still reads 10 and still costs 10.
|
|
302
|
+
- Recent search only covers roughly the last 7 days. There is no archive access on this tier.
|
|
303
|
+
- `session` mode follows the front end X actually serves now. Since 2026-11 the web app is `x-web`, which runs search server-side and streams the operation into the search page as `{id, name: SearchByRawQuery, variables: {…}}`. The adapter reads that pair out of the document, then calls `GET /i/api/graphql/<queryId>/SearchByRawQuery?variables=…` with the cookies, the public bearer and `x-csrf-token`. No transaction-id signing is involved any more, and none of the old `responsive-web` bundle crawling survives.
|
|
304
|
+
- The variable template is reused verbatim because it carries X's `__relay_internal__pv__*` switches; sending only `features` answers `422 GRAPHQL_VALIDATION_FAILED`. The query id changes with each deploy, so it is cached for ten minutes and rediscovered once on a 404 before the call is reported as broken.
|
|
305
|
+
- The tweet shape moved too: the body is `details.full_text` (long posts still use `note_tweet`), the timestamp is `details.created_at_ms`, and engagement counts sit under `counts`. Fields are located structurally rather than by a fixed path, because X moves them between releases.
|
|
306
|
+
- Both modes surface credentials only as field names in error messages; tokens, cookies and upstream response bodies never appear in output.
|
|
307
|
+
|
|
308
|
+
The behaviour contract for both modes is covered by unit tests with mocked fetch. **Neither mode has been exercised against the live service**: no bearer token and no X cookies were supplied. The `session` parsing paths that depend on X's current layout are listed as assumptions in the port notes.
|
|
309
|
+
|
|
310
|
+
## Outbound identity
|
|
311
|
+
|
|
312
|
+
Every request this plugin sends carries `dsh-search/<version> (+project url)` as its `User-Agent`, with the version injected from `package.json` at build time. Two paths opt out because they impersonate a first-party client, and `withAppUserAgent` leaves any caller-supplied agent alone:
|
|
313
|
+
|
|
314
|
+
- Reddit anonymous mode sends the Android client's device headers.
|
|
315
|
+
- X session mode sends the web client's browser headers for the signing handshake and the GraphQL call.
|
|
316
|
+
|
|
317
|
+
Tests assert both the default and the exemptions, including header containers of every shape (`Headers`, tuple arrays, plain objects).
|
|
318
|
+
|
|
319
|
+
## Credential editing does not require a save
|
|
320
|
+
|
|
321
|
+
Choosing a different access mode used to lock the credential field until the configuration was saved, because the write was validated against the saved reference. The editor now sends the reference it currently shows, validated as an environment-style name, so a mode switch followed by a credential entry works without an intermediate save. Only a reference the provider reports as unwritable stays locked, and the field says why.
|
|
322
|
+
|
|
323
|
+
## Per-call strategy (`web_search_plus`)
|
|
324
|
+
|
|
325
|
+
`web_search` is the harness's own tool; its request shape is fixed by the web seam (`query` plus `maxResults`), so a provider cannot add parameters to it. Strategy overrides therefore live in a second tool:
|
|
326
|
+
|
|
327
|
+
| Argument | Effect |
|
|
328
|
+
| --- | --- |
|
|
329
|
+
| `mode` | `single` or `parallel` for this call; omitted means the configured mode |
|
|
330
|
+
| `backends` | Subset of the enabled backends; anything disabled or unknown is named in the result |
|
|
331
|
+
| `allBackends` | Every enabled backend, before exclusions; cheaper to write than listing ids |
|
|
332
|
+
| `exclude` | Backends to leave out, applied to `allBackends` or to the `backends` list |
|
|
333
|
+
| `backend` | Single backend id; ignored with a note in single mode, where the configured backend wins, and in parallel mode |
|
|
334
|
+
| `compact` | Return `url`, `title` and `publishedAt` only, dropping snippets — the largest lever on result size |
|
|
335
|
+
| `maxResults` | Result bound for this call, 1–50 |
|
|
336
|
+
|
|
337
|
+
A blacklist would otherwise pick up backends that get enabled later, so any call that used `allBackends`, `exclude` or a filtered list reports the effective set: `Backends used in this call: …`. Exclusions naming a backend that is not enabled are reported as ignored rather than silently matching nothing.
|
|
338
|
+
|
|
339
|
+
Overrides never mutate saved configuration and are never cached, so a narrowed call cannot be served from a cache entry produced under a different strategy.
|
|
340
|
+
|
|
341
|
+
The tool itself is switchable: with `tools.webSearchPlus` off the plugin does not register it, so the agent cannot call it rather than calling it and being refused. The switch lives on the Search behaviour tab and defaults to on.
|
|
342
|
+
|
|
343
|
+
`tools.compactByDefault` makes compact results the default for this tool while leaving the plain `web_search` path untouched: the harness's own tool still returns snippets, because they are what its consumers read. An explicit `compact: false` on a call overrides the saved preference.
|
|
344
|
+
|
|
345
|
+
### X session search verification (2026-11-17, live)
|
|
346
|
+
|
|
347
|
+
With a real signed-in session, the adapter returned 8 posts for `deepseek harness`, each with a working `x.com/<handle>/status/<id>` link, a snippet and an ISO timestamp, in one page read plus one GraphQL read. Two failure modes were reproduced deliberately: rejected cookies answer `authentication` (the page comes back signed out), and a page without the embedded operation answers `protocol` naming `SearchByRawQuery` and the maintainer action.
|
|
348
|
+
|
|
349
|
+
The reverse-engineering that this replaced — the `x-client-transaction-id` generator and the `responsive-web` operations crawler — is gone; it was ~660 lines plus a signing test suite that no longer matched the live service.
|
package/docs/VERIFICATION.md
CHANGED
|
@@ -71,3 +71,14 @@ Live check with canonical `language=zh-Hans`, `region=CN` and retry/cache disabl
|
|
|
71
71
|
So an unsupported canonical value is never forwarded as a guess, and a supported one reaches the backend in its own spelling. Saved values are validated against the fixed lists, so a backend-specific spelling can no longer be typed in by hand.
|
|
72
72
|
|
|
73
73
|
The settings snapshot also reports the provider the web seam currently selects. When it is not this plugin, the page states which provider is in effect and offers a one-click switch; the built-in providers stay registered and are simply never selected while `searchProvider: nite-search` is pinned.
|
|
74
|
+
|
|
75
|
+
## Reddit (2026-11-17, live)
|
|
76
|
+
|
|
77
|
+
Anonymous mode was exercised against the real endpoints, with retry and cache disabled:
|
|
78
|
+
|
|
79
|
+
| Call | Result |
|
|
80
|
+
| --- | --- |
|
|
81
|
+
| `searchReddit` "claude code vs codex" | 3 posts returned from r/OpenaiCodex, r/ClaudeCode, r/codex with working permalinks |
|
|
82
|
+
| `fetchRedditThread` on the first permalink | post title resolved, 13 top-level comments parsed, `truncated: true` at the 4,000-character test budget |
|
|
83
|
+
|
|
84
|
+
This confirms the anonymous token flow (Android client id + device headers), the persisted-operation hashes for `SearchPosts` and `PostComments`, the `/by_id` metadata call, and the comment tree shaping. The `oauth` mode is contract-tested only: no client id/secret was supplied, so no live OAuth call was made. Assumptions that remain unverified are listed in the port notes: the OAuth Listing field shapes, and whether the anonymous path keeps working if Reddit closes `/by_id` to those tokens.
|
package/locale/en.json
CHANGED
|
@@ -52,10 +52,10 @@
|
|
|
52
52
|
"notVerified": "Not verified",
|
|
53
53
|
"noData": "No data",
|
|
54
54
|
"attemptsToday": "Attempts today",
|
|
55
|
-
"tier.free": "Free
|
|
56
|
-
"tier.allowance": "Free allowance
|
|
55
|
+
"tier.free": "Free",
|
|
56
|
+
"tier.allowance": "Free allowance",
|
|
57
57
|
"tier.trial": "Trial credits",
|
|
58
|
-
"tier.paid": "Paid
|
|
58
|
+
"tier.paid": "Paid",
|
|
59
59
|
"tier.self-hosted": "Self-hosted",
|
|
60
60
|
"tier.unverified": "Contract unverified · cannot enable",
|
|
61
61
|
"credentialTitle": "Credential storage",
|
|
@@ -66,7 +66,6 @@
|
|
|
66
66
|
"replaceCredential": "Replace credential",
|
|
67
67
|
"deleteCredential": "Delete credential",
|
|
68
68
|
"deleteCredentialConfirm": "Delete this saved credential? This cannot be undone.",
|
|
69
|
-
"saveBeforeCredential": "Save the configuration before changing credentials.",
|
|
70
69
|
"credentialSaved": "Credential change confirmed.",
|
|
71
70
|
"credentialFailed": "Credential change could not be confirmed. The input has been cleared; inspect the current state before trying again.",
|
|
72
71
|
"testTitle": "Test a saved backend",
|
|
@@ -208,7 +207,6 @@
|
|
|
208
207
|
"failure.budget": "Local budget exhausted",
|
|
209
208
|
"failure.circuit-open": "Circuit open",
|
|
210
209
|
"failure.unverified": "Unverified backend",
|
|
211
|
-
"liveVerified": "Live-tested",
|
|
212
210
|
"tabsLabel": "Search settings sections",
|
|
213
211
|
"tab.behavior": "Search behavior",
|
|
214
212
|
"tab.reliability": "Reliability",
|
|
@@ -220,7 +218,17 @@
|
|
|
220
218
|
"activeTitle": "This plugin is not the active search provider",
|
|
221
219
|
"activeOther": "The web seam currently selects “{{provider}}”. Searches keep going there until this plugin is selected.",
|
|
222
220
|
"activateSelf": "Use this plugin for web search",
|
|
223
|
-
"
|
|
224
|
-
"
|
|
225
|
-
"
|
|
221
|
+
"choice.oauth": "OAuth",
|
|
222
|
+
"tier.account": "Own account",
|
|
223
|
+
"choice.session": "Browser session cookies",
|
|
224
|
+
"colorLegend": "Green: free path, own account or self-hosted. Yellow: free allowance. Red: trial credits or paid. Sorted cheapest first.",
|
|
225
|
+
"credentialPending": "Wait for the current action to finish.",
|
|
226
|
+
"credentialRefRequired": "Set a credential reference name first.",
|
|
227
|
+
"credentialReadOnly": "This reference is read-only: another source supplies its value, so the plugin cannot overwrite it. Pick a different reference name, such as DSH_SEARCH_X_SESSION.",
|
|
228
|
+
"credentialPlainKey": "Paste the key itself.",
|
|
229
|
+
"credentialShapeLabel": "Credential format",
|
|
230
|
+
"field.tools.webSearchPlus": "Allow web_search_plus",
|
|
231
|
+
"help.tools.webSearchPlus": "Off hides the tool entirely: the agent then searches only through the configured strategy.",
|
|
232
|
+
"field.tools.compactByDefault": "Compact results by default",
|
|
233
|
+
"help.tools.compactByDefault": "Sources carry only URL, title and date. Saves context when the agent only needs links; a call can still ask for full snippets."
|
|
226
234
|
}
|
package/locale/zh.json
CHANGED
|
@@ -52,10 +52,10 @@
|
|
|
52
52
|
"notVerified": "未核实",
|
|
53
53
|
"noData": "暂无数据",
|
|
54
54
|
"attemptsToday": "今日尝试次数",
|
|
55
|
-
"tier.free": "免费
|
|
56
|
-
"tier.allowance": "免费额度
|
|
55
|
+
"tier.free": "免费",
|
|
56
|
+
"tier.allowance": "免费额度",
|
|
57
57
|
"tier.trial": "试用额度",
|
|
58
|
-
"tier.paid": "
|
|
58
|
+
"tier.paid": "付费",
|
|
59
59
|
"tier.self-hosted": "自托管",
|
|
60
60
|
"tier.unverified": "协议未核实 · 不可启用",
|
|
61
61
|
"credentialTitle": "凭证存储",
|
|
@@ -66,7 +66,6 @@
|
|
|
66
66
|
"replaceCredential": "替换凭证",
|
|
67
67
|
"deleteCredential": "删除凭证",
|
|
68
68
|
"deleteCredentialConfirm": "确定删除已保存的凭证?此操作无法撤销。",
|
|
69
|
-
"saveBeforeCredential": "请先保存配置,再修改凭证。",
|
|
70
69
|
"credentialSaved": "凭证更改已确认。",
|
|
71
70
|
"credentialFailed": "无法确认凭证更改结果,输入内容已清空。请先核对当前状态,再决定是否重新操作。",
|
|
72
71
|
"testTitle": "测试已保存的后端",
|
|
@@ -208,7 +207,6 @@
|
|
|
208
207
|
"failure.budget": "本地额度耗尽",
|
|
209
208
|
"failure.circuit-open": "熔断中",
|
|
210
209
|
"failure.unverified": "后端未核实",
|
|
211
|
-
"liveVerified": "已实测",
|
|
212
210
|
"tabsLabel": "搜索设置分区",
|
|
213
211
|
"tab.behavior": "搜索行为",
|
|
214
212
|
"tab.reliability": "稳定性",
|
|
@@ -220,7 +218,17 @@
|
|
|
220
218
|
"activeTitle": "当前未启用本插件作为搜索源",
|
|
221
219
|
"activeOther": "内置搜索当前选择的是「{{provider}}」。在选中本插件之前,搜索仍会走它。",
|
|
222
220
|
"activateSelf": "设为网页搜索来源",
|
|
223
|
-
"
|
|
224
|
-
"
|
|
225
|
-
"
|
|
221
|
+
"choice.oauth": "OAuth 授权",
|
|
222
|
+
"tier.account": "自带账号",
|
|
223
|
+
"choice.session": "浏览器会话 Cookie",
|
|
224
|
+
"colorLegend": "绿色=免费/自带账号/自托管,黄色=免费额度,红色=试用或付费。由便宜到贵排序。",
|
|
225
|
+
"credentialPending": "当前操作还没结束,稍等。",
|
|
226
|
+
"credentialRefRequired": "请先填一个凭证引用名。",
|
|
227
|
+
"credentialReadOnly": "这个凭证引用是只读的:它的值由其它来源提供,插件无法覆盖。换一个引用名试试,例如 DSH_SEARCH_X_SESSION。",
|
|
228
|
+
"credentialPlainKey": "直接填密钥字符串。",
|
|
229
|
+
"credentialShapeLabel": "凭证格式",
|
|
230
|
+
"field.tools.webSearchPlus": "允许使用 web_search_plus",
|
|
231
|
+
"help.tools.webSearchPlus": "关闭后这个工具不会注册,agent 只能用配置里的固定策略搜索。",
|
|
232
|
+
"field.tools.compactByDefault": "默认返回精简结果",
|
|
233
|
+
"help.tools.compactByDefault": "结果只保留链接、标题和日期。agent 只需要链接时能省下大量上下文;单次调用仍可要求完整摘要。"
|
|
226
234
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nite07/dsh-search",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.4",
|
|
4
4
|
"description": "Explicit-mode multi-backend search with transparent costs and complete Web settings for DSH",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -61,7 +61,8 @@
|
|
|
61
61
|
"esbuild": "^0.28.2",
|
|
62
62
|
"tsx": "^4.20.0",
|
|
63
63
|
"@types/node": "^24.0.0",
|
|
64
|
-
"@types/react": "^19.3.0"
|
|
64
|
+
"@types/react": "^19.3.0",
|
|
65
|
+
"@nite07/search-core": "0.1.0"
|
|
65
66
|
},
|
|
66
67
|
"dsh": {
|
|
67
68
|
"bundle": {
|