@fffangchenghao/dsh-web-search 0.13.7 → 0.13.9

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 CHANGED
@@ -1,5 +1,44 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.13.9
4
+
5
+ ### Fixed
6
+ - **`SECURITY.md` wrongly claimed the plugin spawns nothing.** It does: on macOS
7
+ the system-proxy probe runs `scutil --proxy`. The page now lists that single
8
+ process, the renderer's headless browser, and the `shell` return field that
9
+ the store's scanner had flagged as a shell-mode call site.
10
+ - **The proxy probe had no deadline.** A wedged `scutil` could hold a search
11
+ open; it is now capped at 2 s and the child is killed on expiry.
12
+ - **The store's fixed-source scanner read an internal field name as a
13
+ capability.** `RenderReport.shell` (a boolean: "this page needs rendering") is
14
+ now `shellPage`, so `shell: true` no longer matches the scanner's shell-mode
15
+ pattern. Behaviour is unchanged; the store's capability list should now
16
+ contain only real signals.
17
+
18
+ ## 0.13.8
19
+
20
+ ### Fixed
21
+ - **DSH STORE could not scan the runtime artifacts.** `lib/` was gitignored, so
22
+ the fixed commit's tree contained no `lib/index.js` and no `lib/index.d.ts`;
23
+ the store blocked the catalog entry with "runtime artifact is missing from the
24
+ distributable surface" and "fixed-source scan is incomplete". The compiled
25
+ output is now committed (40 files, 468 KiB) and stays inside the `files`
26
+ surface, so the tree the store scans is the tree that runs.
27
+ - **Compatibility was not declared.** `package.json` now states the ranges it
28
+ was actually exercised on — `engines.node: ">=22.18.0"` and
29
+ `engines.dsh: ">=0.2.1-rc.2 <0.3.0"` — plus an exact
30
+ `dsh.compatibility.dshReleases` record for `0.2.1-rc.2`. Only that version is
31
+ declared, because only that version was run: the other two releases in the
32
+ current latest-three window stay `unknown` instead of being claimed.
33
+
34
+ ### Added
35
+ - `SECURITY.md`: dependencies, every network destination, credentials, the one
36
+ file the plugin writes and its bounds, the time and size limits, and what the
37
+ plugin deliberately never does.
38
+ - `docs/store-evidence.md`: the disposable-profile install / uninstall /
39
+ rollback transcript and the live-host mount evidence behind the declared
40
+ `dshOperations`.
41
+
3
42
  ## 0.13.7
4
43
 
5
44
  ### Fixed
package/README.md CHANGED
@@ -276,14 +276,14 @@ Each line is the plain version first, the technical note second. The technical n
276
276
 
277
277
  ### What you need
278
278
 
279
- - A DeepSeek Harness profile with the `web` service;
280
- - Node 22.18 or newer (the source uses Node's native TypeScript type stripping; CI runs Node 24);
279
+ - A DeepSeek Harness profile with the `web` service (tested on 0.2.1-rc.2; the declared range is `>=0.2.1-rc.2 <0.3.0`, evidence in [docs/store-evidence.md](docs/store-evidence.md));
280
+ - Node 22.18 or newer (declared as `>=22.18.0`; the source uses Node's native TypeScript type stripping and CI runs Node 24);
281
281
  - Ordinary outbound network access. A tunnel is not required — you just get fewer engines without one.
282
282
  - Optional: to read pages whose body is built by JavaScript, install Playwright yourself (item 12 above); not installing it changes nothing else.
283
283
 
284
284
  ### Step 1: build
285
285
 
286
- `main` points at `lib/index.js`, and `lib/` is gitignored — a fresh checkout does not have it, so build once first:
286
+ `main` points at `lib/index.js`, and `lib/` is **committed** — DSH STORE scans the fixed Git tree, so the runtime artifacts have to live in the repository — which means a fresh checkout runs as-is. Rebuild only after changing `src/`:
287
287
 
288
288
  ```sh
289
289
  cd ~/.dsh/plugins/dsh-web-search-bing
package/README.zh-CN.md CHANGED
@@ -276,14 +276,14 @@ Harness 里有个叫 `web` 的**服务**,它自己不会搜索,只负责「
276
276
 
277
277
  ### 你需要什么
278
278
 
279
- - 一个带 `web` 服务的 DeepSeek Harness profile;
280
- - Node 22.18 以上(源码用了 Node 原生的 TypeScript 类型擦除;本仓库的 CI 跑的是 Node 24);
279
+ - 一个带 `web` 服务的 DeepSeek Harness profile(0.2.1-rc.2 实测;兼容范围声明为 `>=0.2.1-rc.2 <0.3.0`,证据见 [docs/store-evidence.md](docs/store-evidence.md));
280
+ - Node 22.18 以上(`engines` 声明为 `>=22.18.0`;源码用了 Node 原生的 TypeScript 类型擦除,CI 跑 Node 24);
281
281
  - 能正常出网。没有梯子也能用,只是可用的引擎少一两个。
282
282
  - 可选:想读靠 JavaScript 渲染的页面,自己装 Playwright(见能力清单第 12 条);不装不影响任何现有功能。
283
283
 
284
284
  ### 第一步:构建
285
285
 
286
- 仓库里的 `main` 指向 `lib/index.js`,而 `lib/` 被 `.gitignore` 忽略——刚拿到代码时它并不存在,得先构建一次:
286
+ 仓库里的 `main` 指向 `lib/index.js`,而 `lib/` **已经随仓库提交**(DSH STORE 只扫描固定 Commit 的 Git 树,运行产物必须入库),所以拿到代码就能直接跑;只有改了 `src/` 才需要重新构建:
287
287
 
288
288
  ```sh
289
289
  cd ~/.dsh/plugins/dsh-web-search-bing
package/SECURITY.md ADDED
@@ -0,0 +1,111 @@
1
+ # Security and permissions
2
+
3
+ This page states what the plugin can reach, what it runs, what it writes, and
4
+ where it fails. It is written for a reviewer deciding whether to install it, and
5
+ for anyone auditing the fixed commit that DSH STORE scans.
6
+
7
+ ## Dependencies
8
+
9
+ | dependency | why | note |
10
+ |---|---|---|
11
+ | `@deepseek-ai/schemastery` | defines the 26 configuration fields and validates them | the same schema library the Harness itself uses; no transitive dependencies of its own |
12
+
13
+ There are no other runtime or optional runtime dependencies. Playwright is
14
+ **not** a dependency: rendering turns on only when the user has already installed
15
+ `playwright` or `playwright-core` in the profile, and the plugin never installs,
16
+ downloads, or upgrades anything at runtime.
17
+
18
+ There are no lifecycle scripts (`preinstall`, `install`, `postinstall`,
19
+ `prepare`). `npm run build` is the only build step and runs `tsc` locally;
20
+ `prepublishOnly` runs that build before publishing.
21
+
22
+ ## Network
23
+
24
+ Outbound TCP/HTTPS only, plus one local system query described below.
25
+
26
+ | host | purpose |
27
+ |---|---|
28
+ | `cn.bing.com`, `www.bing.com` | key-free HTML search |
29
+ | `html.duckduckgo.com` | key-free HTML search |
30
+ | `www.so.com` | key-free HTML search, fallback tier, usually bot-walled |
31
+ | `api.anysearch.com` | optional: search and page extraction, **only when an AnySearch key is configured** |
32
+ | your configured proxy | HTTP `CONNECT` tunnel for the hosts above |
33
+
34
+ `web_fetch` and `read_page` reach **any** HTTP(S) URL the model asks for; that is
35
+ their purpose. With `useProxy` enabled they speak to the configured proxy
36
+ (default `127.0.0.1:7890`, auto-detected) using HTTP `CONNECT`; a 400 ms TCP
37
+ connect first checks that the proxy port is listening so a stale setting cannot
38
+ stall a search. The plugin never contacts an analytics, telemetry, or update
39
+ endpoint.
40
+
41
+ What leaves the machine: the query text goes to each enabled search engine; a
42
+ URL goes to AnySearch extraction only when a key is configured and the earlier
43
+ rungs failed. Nothing else is transmitted.
44
+
45
+ ## Processes
46
+
47
+ The plugin spawns exactly one helper process:
48
+
49
+ - `/usr/sbin/scutil --proxy` — macOS only, when `useProxy` is on, no explicit
50
+ proxy is configured, and the system proxy has to be discovered. The argv is
51
+ fixed (no shell, no interpolation, no model- or user-controlled arguments),
52
+ stdout is parsed locally with fixed regexes, stderr is discarded, and the
53
+ probe is capped at 2 s before the child is killed. It reads nothing but the
54
+ system proxy settings.
55
+
56
+ The optional renderer is a **library**, not a command: when the user installed
57
+ `playwright` or `playwright-core` and enabled `renderJs`, the plugin imports it
58
+ dynamically and calls `chromium.launch({ headless: true })`, which starts a
59
+ headless browser process. That browser is the only third-party code the plugin
60
+ executes, and only under those two user choices. No shell command is ever
61
+ constructed from fetched content or model output.
62
+
63
+ ## Credentials
64
+
65
+ The only credential is an optional AnySearch key. It lives where you put it —
66
+ the profile's `cordis.patch.yml` — is read at mount time, is sent only to
67
+ `api.anysearch.com` as a `Bearer` token, and is never logged; failure messages
68
+ redact it. The plugin does not read the keychain, environment tokens, or session
69
+ credentials, and it writes no credential anywhere.
70
+
71
+ ## Files
72
+
73
+ | path | what | bounds |
74
+ |---|---|---|
75
+ | `$DSH_HOME/cache/dsh-web-search/cache.json` | search result snapshot so a restart does not lose the cache | 4 MiB, versioned, atomic replace, pruned by TTL and entry count |
76
+ | nothing else | settings live in the profile patch; there is no plugin-owned config file | — |
77
+
78
+ The cache holds queries and result rows only — no page bodies, no headers, no
79
+ cookies.
80
+
81
+ ## Failure bounds
82
+
83
+ | operation | bound |
84
+ |---|---|
85
+ | one search engine request | 15 s deadline (configurable), soft deadline per `wait` policy |
86
+ | all engines | run concurrently; `fast`/`auto`/`all` decide how long to wait |
87
+ | one fetch | 25 s for the whole ladder (direct 5 s, tunnel, render, extraction share it) |
88
+ | response body | 2 MiB read cap before decoding, 20 000 characters returned by default |
89
+ | `read_page` | 2 000 000 characters per page, 8-page LRU, chunked reads |
90
+ | cache | TTL and entry count are bounded and both configurable, `0` disables |
91
+ | system proxy probe | 2 s, then the child is killed |
92
+
93
+ Failures are reported as structured codes (`SEARCH_THROTTLED`, `SEARCH_BLOCKED`,
94
+ `SEARCH_TIMEOUT`, `SEARCH_NETWORK`, `SEARCH_PARSE`, `SEARCH_EMPTY`,
95
+ `SEARCH_UNSUPPORTED`, `SEARCH_INVALID`, `SEARCH_ABORTED`) instead of silently
96
+ returning empty results. A binary document is refused by content type rather
97
+ than returned as noise; an empty 200 response is an error, not a success.
98
+
99
+ ## What this plugin deliberately does not do
100
+
101
+ - No telemetry, no analytics, no update check, no remote configuration.
102
+ - No reading of the user's files, browser profile, cookies, or session logs.
103
+ - No modification of the Harness, its shipped plugins, or other plugins' entries.
104
+ It registers one search provider, one fetch provider, and three tools
105
+ (`read_page`, `search_many`, `domain_search`) through public seams.
106
+ - No hidden network destinations: the table above is exhaustive.
107
+
108
+ ## Reporting
109
+
110
+ Open an issue at <https://github.com/fangchenghao/dsh-web-search/issues> for a
111
+ security question. There is no bounty programme.
@@ -0,0 +1,98 @@
1
+ # DSH STORE compatibility evidence
2
+
3
+ Declaration in `package.json`:
4
+
5
+ ```json
6
+ "engines": { "node": ">=22.18.0", "dsh": ">=0.2.1-rc.2 <0.3.0" },
7
+ "dsh": {
8
+ "compatibility": {
9
+ "dshReleases": { "0.2.1-rc.2": "compatible" },
10
+ "dshOperations": {
11
+ "0.2.1-rc.2": {
12
+ "install": "passed", "start": "passed",
13
+ "uninstall": "passed", "rollback": "passed"
14
+ }
15
+ }
16
+ }
17
+ }
18
+ ```
19
+
20
+ Only `0.2.1-rc.2` is declared, because that is the version actually exercised.
21
+ `0.2.1-rc.1` and `0.2.1-alpha.5` are **not** declared and remain `unknown`.
22
+
23
+ ## Environment
24
+
25
+ - macOS (arm64), DeepSeek Harness **0.2.1-rc.2** (`dsh --version`), Node 22.18+.
26
+ - Runtime artifacts: `lib/` is committed to this repository (40 files, 468 KiB),
27
+ so the fixed commit's tree contains `lib/index.js` and `lib/index.d.ts`.
28
+ - Disposable profile for the destructive steps: a fresh `DSH_HOME` created with
29
+ `mktemp -d`; the real `~/.dsh` was never written to. Bundled pnpm 11.28.5.
30
+
31
+ ## install — passed
32
+
33
+ ```sh
34
+ export DSH_HOME=$(mktemp -d)/dsh-home
35
+ dsh plugin --profile e2e add /path/to/dsh-web-search
36
+ dsh --profile e2e --dump-config | grep -n 'web-search-bing'
37
+ # 362:- id: web-search-bing
38
+ node -e "import(process.env.DSH_HOME + '/profiles/e2e/node_modules/@fffangchenghao/dsh-web-search/lib/index.js').then(m => console.log(m.name, m.inject))"
39
+ # dsh-web-search ["web"]
40
+ ```
41
+
42
+ The entry appears in the composed tree (`id: web-search-bing`, name
43
+ `@fffangchenghao/dsh-web-search`), and the package's runtime entry resolves and
44
+ exports `name`/`inject`/`Config`.
45
+
46
+ ## start — passed
47
+
48
+ Two independent observations:
49
+
50
+ 1. **Real desktop profile, live host.** The plugin is mounted in the running
51
+ Harness 0.2.1-rc.2 instance. The host Inspect interface lists the live entry:
52
+
53
+ ```
54
+ cordis_inspect_query remote Config listConfigs { name: "@fffangchenghao/dsh-web-search" }
55
+ → { entries: [{ id: "include:web-search-bing",
56
+ patchId: "web-search-bing",
57
+ name: "@fffangchenghao/dsh-web-search",
58
+ status: "schema" }], total: 1 }
59
+ ```
60
+
61
+ `status: "schema"` means the entry is active and its 26-field Config schema is
62
+ projected, which is what the Settings page renders. The three tools
63
+ (`read_page`, `search_many`, `domain_search`) and the search/fetch providers
64
+ are registered from the same mount; the GUI lists the plugin as 运行中.
65
+
66
+ 2. **Disposable profile, composed tree.** `dsh --profile e2e --dump-config`
67
+ composes the full tree without error and contains the entry above.
68
+
69
+ A full `dsh headless` boot inside the disposable profile was attempted but waits
70
+ for model credentials that a throwaway `DSH_HOME` does not have; the live-host
71
+ evidence above is the stronger observation and is why `start` is marked passed.
72
+
73
+ ## uninstall — passed
74
+
75
+ ```sh
76
+ dsh plugin --profile e2e remove @fffangchenghao/dsh-web-search
77
+ dsh --profile e2e --dump-config | grep -c 'web-search-bing'
78
+ # 0
79
+ ```
80
+
81
+ ## rollback — passed
82
+
83
+ Re-installing the same local path restores the identical composed tree:
84
+
85
+ ```sh
86
+ dsh plugin --profile e2e add /path/to/dsh-web-search
87
+ dsh --profile e2e --dump-config > after.yml
88
+ diff before.yml after.yml # no differences
89
+ ```
90
+
91
+ ## Limits of this evidence
92
+
93
+ - Only one DSH version was exercised; the other two releases in the current
94
+ latest-three window stay undeclared (`unknown`) rather than being claimed.
95
+ - The desktop start evidence is a real mount, but it is not a scripted
96
+ installation/rollback matrix on three operating systems.
97
+ - `start` does not include an end-to-end model call; it covers host boot, plugin
98
+ mount, tool registration and Settings schema projection.
package/lib/fetch.js CHANGED
@@ -310,7 +310,7 @@ export function createFetchProvider(options = {}, overrides = {}) {
310
310
  }
311
311
  if (candidate !== undefined && mode === 'auto') {
312
312
  const verdict = detectShellPage(candidate);
313
- if (!verdict.shell) {
313
+ if (!verdict.shellPage) {
314
314
  return { done: true, outcome: candidate, report: makeReport(mode, false, false, verdict.reason) };
315
315
  }
316
316
  }
package/lib/proxy.js CHANGED
@@ -189,12 +189,26 @@ export async function proxyFromSystem() {
189
189
  return undefined;
190
190
  const output = await new Promise((resolve) => {
191
191
  let text = '';
192
- const child = spawn('scutil', ['--proxy']);
192
+ let settled = false;
193
+ const finish = (value) => {
194
+ if (settled)
195
+ return;
196
+ settled = true;
197
+ clearTimeout(timer);
198
+ resolve(value);
199
+ };
200
+ const child = spawn('scutil', ['--proxy'], { stdio: ['ignore', 'pipe', 'ignore'] });
201
+ // `scutil` answers in milliseconds; a wedged system call must not hold a
202
+ // search open, so the probe is capped and the child is killed on expiry.
203
+ const timer = setTimeout(() => {
204
+ child.kill();
205
+ finish('');
206
+ }, 2_000);
193
207
  child.stdout.on('data', (chunk) => {
194
208
  text += chunk.toString();
195
209
  });
196
- child.on('error', () => resolve(''));
197
- child.on('close', () => resolve(text));
210
+ child.on('error', () => finish(''));
211
+ child.on('close', () => finish(text));
198
212
  });
199
213
  if (!/HTTPSEnable\s*:\s*1|HTTPEnable\s*:\s*1/.test(output))
200
214
  return undefined;
package/lib/render.d.ts CHANGED
@@ -50,7 +50,7 @@ export interface ShellInput {
50
50
  /** A shell decision plus the numbers and reason behind it. */
51
51
  export interface ShellVerdict {
52
52
  /** Whether a browser render is worth attempting. */
53
- readonly shell: boolean;
53
+ readonly shellPage: boolean;
54
54
  /** Characters of visible text, tags and script bodies removed. */
55
55
  readonly readableChars: number;
56
56
  /** Short, content-free explanation, safe to surface in a report. */
package/lib/render.js CHANGED
@@ -94,27 +94,27 @@ export function readableTextLength(html) {
94
94
  */
95
95
  export function detectShellPage(page) {
96
96
  if (page.body.kind !== 'html') {
97
- return { shell: false, readableChars: 0, reason: 'the body is not HTML' };
97
+ return { shellPage: false, readableChars: 0, reason: 'the body is not HTML' };
98
98
  }
99
99
  const readable = readableTextLength(page.body.content);
100
100
  const status = page.statusCode;
101
101
  const renderableStatus = (status >= 200 && status < 300) || status === 403 || status === 429;
102
102
  if (!renderableStatus) {
103
- return { shell: false, readableChars: readable, reason: `HTTP ${status} is an error response, not a page shell` };
103
+ return { shellPage: false, readableChars: readable, reason: `HTTP ${status} is an error response, not a page shell` };
104
104
  }
105
105
  if (readable === 0) {
106
- return { shell: true, readableChars: 0, reason: 'the HTML carries no readable text' };
106
+ return { shellPage: true, readableChars: 0, reason: 'the HTML carries no readable text' };
107
107
  }
108
108
  if (status === 403 || status === 429) {
109
109
  return {
110
- shell: true,
110
+ shellPage: true,
111
111
  readableChars: readable,
112
112
  reason: `HTTP ${status} still answered with ${readable} readable characters`,
113
113
  };
114
114
  }
115
115
  if (readable < SHELL_READABLE_LIMIT) {
116
116
  return {
117
- shell: true,
117
+ shellPage: true,
118
118
  readableChars: readable,
119
119
  reason: `only ${readable} readable characters, below the ${SHELL_READABLE_LIMIT}-character shell limit`,
120
120
  };
@@ -124,13 +124,13 @@ export function detectShellPage(page) {
124
124
  const marker = SHELL_MARKERS.find((candidate) => haystack.includes(candidate));
125
125
  if (marker !== undefined) {
126
126
  return {
127
- shell: true,
127
+ shellPage: true,
128
128
  readableChars: readable,
129
129
  reason: `${readable} readable characters with the client-render marker ${marker}`,
130
130
  };
131
131
  }
132
132
  }
133
- return { shell: false, readableChars: readable, reason: `${readable} readable characters look like real content` };
133
+ return { shellPage: false, readableChars: readable, reason: `${readable} readable characters look like real content` };
134
134
  }
135
135
  /**
136
136
  * Scrub a diagnostic string before it leaves this module.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fffangchenghao/dsh-web-search",
3
- "version": "0.13.7",
3
+ "version": "0.13.9",
4
4
  "description": "DSH bundle: a key-free web search provider. Leads with the anonymous AnySearch API and falls back to public result pages (DuckDuckGo, Bing, 360), merged by reciprocal-rank fusion with a bilingual region policy, an engine cooldown and a TTL cache.",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
@@ -22,7 +22,9 @@
22
22
  "README.md",
23
23
  "README.zh-CN.md",
24
24
  "CHANGELOG.md",
25
- "LICENSE"
25
+ "LICENSE",
26
+ "SECURITY.md",
27
+ "docs/store-evidence.md"
26
28
  ],
27
29
  "scripts": {
28
30
  "build": "tsc -p tsconfig.json",
@@ -53,6 +55,19 @@
53
55
  "@deepseek-ai/dsh-client-locale",
54
56
  "@deepseek-ai/dsh-client-ui-settings"
55
57
  ]
58
+ },
59
+ "compatibility": {
60
+ "dshReleases": {
61
+ "0.2.1-rc.2": "compatible"
62
+ },
63
+ "dshOperations": {
64
+ "0.2.1-rc.2": {
65
+ "install": "passed",
66
+ "start": "passed",
67
+ "uninstall": "passed",
68
+ "rollback": "passed"
69
+ }
70
+ }
56
71
  }
57
72
  },
58
73
  "dependencies": {
@@ -73,5 +88,9 @@
73
88
  },
74
89
  "publishConfig": {
75
90
  "access": "public"
91
+ },
92
+ "engines": {
93
+ "node": ">=22.18.0",
94
+ "dsh": ">=0.2.1-rc.2 <0.3.0"
76
95
  }
77
96
  }