# Changelog

## [0.9.0] - 2026-09-11

### Changed / 变更

- **Modular TypeScript Architecture Refactoring / 模块化 TypeScript 架构重构**:
  - Refactored monolithic codebase into dedicated modules following the official DeepSeek Harness plugin development guide (`docs/cookbook/adding-a-package.md` and `docs/user/develop/basic/index.md`).
  - Separated public types into `src/types.ts` (`SearxngWebConfig`, `SearchOutcome`, `FetchOutcome`, `WebSearchProvider`, `WebFetchProvider`).
  - Extracted Schemastery validation into `src/config.ts`.
  - Extracted SSRF validation and host protection into `src/ssrf.ts` (strict http/https protocol check, host pre-validation, loopback/private/reserved range blocking).
  - Extracted HTML text reduction into `src/html.ts`.
  - Extracted bounded fetch with timeout and cancellation semantics into `src/http.ts`.
  - Extracted search provider with sticky failover into `src/search-provider.ts` and fetch provider into `src/fetch-provider.ts`.
  - Exported unified plugin entry with backward-compatible API from `src/index.ts`.
  - Recompiled and verified all 23 standalone tests pass.

## [0.8.0] - 2026-09-11

### Changed / 变更

- **DeepSeek Harness 0.1.5-rc.2 compatibility verified & manifest modernization / 适配 DeepSeek Harness 0.1.5-rc.2 与清单规范现代化**:
  - Added `manifestVersion: 1` under `package.json.dsh` conforming to `@deepseek-ai/dsh-package-manifest`.
  - Added explicit host engine compatibility in `package.json.engines`: `"dsh": "^0.1.5-rc.2"`.
  - Added peerDependencies for `@deepseek-ai/dsh-web` at `^0.1.5-rc.2`.
  - Refreshed all bilingual documentation (`README.md`, `README.zh.md`, `INSTALL.md`, `INSTALL.zh.md`, `UPDATE.md`, `UPDATE.zh.md`, `USAGE.md`, `USAGE.zh.md`, `CONFIG.md`, `CONFIG.zh.md`, `UNINSTALL.md`, `UNINSTALL.zh.md`) for `0.1.5-rc.2` verification and version `0.8.0`.

## [0.7.0] - 2026-09-10

### Changed / 变更

- **DeepSeek Harness 0.1.5-rc.1 compatibility verified**: the `ctx.web` provider seam (`packages/web/web/src`, `registerSearchProvider` / `registerFetchProvider`) is source-identical between `0.1.5-alpha.1` and `0.1.5-rc.1`, and the vendored `@deepseek-ai/cordis` `4.0.2` / `@deepseek-ai/schemastery` `3.18.2` are unchanged — no code or config migration required. The only `tool-web` delta is scope-aware system-prompt text, which this bundle does not consume.
- **Node floor raised to `>=22`** (`engines`), matching the harness floor (`^22.19.0 || >=24.0.0`).
- **Documentation refresh**: new standalone `INSTALL.md` / `INSTALL.zh.md` (install via `dsh plugin add` / pnpm per `docs/user/develop/basic/publish.md` semantics) and `USAGE.md` / `USAGE.zh.md` (each tool + params + examples, cross-checked against `src/index.ts` and the rc.1 tool seam); `CONFIG.md` / `CONFIG.zh.md` rewritten against the actual `Config` schema (the old tables documented non-existent `maxResults` / `defaults` keys); `README.zh-CN.md` renamed to `README.zh.md`; all links and the `files` manifest updated.
- **兼容性：已在 deepseek-harness 0.1.5-rc.1 上完成验证**：`ctx.web` provider 缝（`packages/web/web/src`，`registerSearchProvider` / `registerFetchProvider`）在 `0.1.5-alpha.1` 与 `0.1.5-rc.1` 之间源码完全一致，内置 `@deepseek-ai/cordis` `4.0.2` / `@deepseek-ai/schemastery` `3.18.2` 未变——无需代码或配置迁移。`tool-web` 唯一的差异是 scope 感知的 system-prompt 文案，本 bundle 不消费该缝。
- **Node 底线升至 `>=22`**（`engines`），与 harness 底线（`^22.19.0 || >=24.0.0`）对齐。
- **文档刷新**：新增独立 `INSTALL.md` / `INSTALL.zh.md`（按 `docs/user/develop/basic/publish.md` 语义经 `dsh plugin add` / pnpm 安装）与 `USAGE.md` / `USAGE.zh.md`（每个工具的参数与示例，均对照 `src/index.ts` 与 rc.1 工具缝逐项核对）；`CONFIG.md` / `CONFIG.zh.md` 按实际 `Config` schema 重写（旧表格记载了不存在的 `maxResults` / `defaults` 键）；`README.zh-CN.md` 重命名为 `README.zh.md`；所有链接与 `files` 清单一并更新。

## [0.6.0] - 2026-09-09

### Changed / 变更

- **DeepSeek Harness 0.1.5-alpha.1 compatibility verified**: Verified on the latest DSH release. Added standard `prepare` build script in `package.json` for seamless source installation.
- **Documentation Standard Suite**: Added dedicated standalone `CONFIG.md`, `CONFIG.zh.md`, `UPDATE.md`, `UPDATE.zh.md`, `UNINSTALL.md`, and `UNINSTALL.zh.md`.
- **Package Manifest**: Registered all documentation files into `files` manifest for complete tarball and npm distribution.
- **兼容性：已在 deepseek-harness 0.1.5-alpha.1 最新发布版上完成全面验证**：添加 `prepare` 构建脚本，支持最新 pnpm 与源码安装机制；新增独立的配置、更新与卸载全套说明文档。

## [0.5.9] - 2026-09-04

### Changed / 变更

- **Compatibility: verified against deepseek-harness `0.1.3-alpha.1` (latest release).** The seam (`ctx.web` search/fetch provider registry, `web` / `tool-web` rows, Schemastery config, SSRF guard, HTML→text, sticky `baseUrls` failover) is source-identical since `0.1.2-rc.1`, and the vendored `@deepseek-ai/cordis` `4.0.2` / loader patch mechanism are unchanged — no code or config migration required. 0.1.3's headline changes (environment-proxy support, Session persistence rework, file attachments) do not touch any seam this bundle consumes. README/README.zh-CN requirements updated to `0.1.3-alpha.1`; tests all pass. **/ 兼容性：已在 deepseek-harness `0.1.3-alpha.1` 最新发行版上验证。** 缝接口（`ctx.web` 搜索/抓取注册、`web` / `tool-web` 行、Schemastery 配置、SSRF 防护、HTML→文本、粘性 `baseUrls` 故障转移）自 `0.1.2-rc.1` 以来源码完全一致，内置 `@deepseek-ai/cordis` `4.0.2` / loader 补丁机制亦未变化，无需代码或配置迁移。0.1.3 的主要变更（环境代理支持、Session 持久化重构、文件附件）均不涉及本 bundle 消费的任何缝。README/README.zh-CN 环境要求已更新为 `0.1.3-alpha.1`；测试全部通过。

## [0.5.8] - 2026-09-03

### Fixed / 修复

- **Fix: the `tool-web` re-enable row now clears `disabled` explicitly (`disabled: false`).** The loader's id-patch merge is **per-key**: a config-only row restates `config` but leaves the `disabled: true` shipped by the `@deepseek-ai/dsh-web-app` bundle in place, so on a clean install into a web profile the model never saw `web_search` / `web_fetch` even though this bundle has restated the row since 0.4.0. Verified with `dsh --profile web --dump-config`: the composed `tool-web` row now carries `disabled: false` and both tools mount. / **修复：`tool-web` 重启用行现在显式清除 `disabled`（`disabled: false`）。** loader 的按 id 补丁合并是**按键生效**的：仅带 `config` 的行会重述配置但保留 `@deepseek-ai/dsh-web-app` bundle 自带的 `disabled: true`，因此干净安装到 web profile 后，即使本 bundle 自 0.4.0 起就重述了该行，模型也看不到 `web_search` / `web_fetch`。已用 `dsh --profile web --dump-config` 验证：组合后的 `tool-web` 行现为 `disabled: false`，两个工具正常挂载。

## [0.5.7] - 2026-09-03

### Changed / 变更

- **Compatibility: verified against deepseek-harness `0.1.2-rc.1` (latest `master`).** The seam (`ctx.web` search/fetch provider registry, `web` / `tool-web` rows, Schemastery config, SSRF guard, HTML→text, sticky `baseUrls` failover) is unchanged since `0.1.2-alpha.5`, and the vendored `@deepseek-ai/cordis` `4.0.2` / loader patch mechanism are unchanged — no code or config migration required. README/README.zh-CN requirements updated to `0.1.2-rc.1`; tests ALL PASS. **/ 兼容性：已在 deepseek-harness `0.1.2-rc.1` 最新 `master` 上验证。** 缝接口（`ctx.web` 搜索/抓取注册、`web` / `tool-web` 行、Schemastery 配置、SSRF 防护、HTML→文本、粘性 `baseUrls` 故障转移）自 `0.1.2-alpha.5` 以来未变，内置 `@deepseek-ai/cordis` `4.0.2` / loader 补丁机制亦未变化，无需代码或配置迁移。README/README.zh-CN 环境要求已更新为 `0.1.2-rc.1`；测试全部通过。

## [0.5.6] - 2026-09-02

### Changed / 变更

- **Compatibility: verified against deepseek-harness `0.1.2-alpha.5` (latest `master`).** Seam (`ctx.web` search/fetch provider registry, `web` / `tool-web` rows, Schemastery config, SSRF guard, HTML→text, sticky `baseUrls` failover) unchanged since `0.1.2-alpha.4` — no code or config migration required. README/README.zh-CN requirements updated to `0.1.2-alpha.5`. **/ 兼容性：已在 deepseek-harness `0.1.2-alpha.5` 最新 `master` 上验证。** 缝接口（`ctx.web` 搜索/抓取注册、`web` / `tool-web` 行、Schemastery 配置、SSRF 防护、HTML→文本、粘性 `baseUrls` 故障转移）自 `0.1.2-alpha.4` 以来未变，无需代码或配置迁移。README/README.zh-CN 环境要求已更新为 `0.1.2-alpha.5`。

## [0.5.5] - 2026-09-02

### Changed / 变更

- **Compatibility: verified against deepseek-harness `0.1.2-alpha.4` (latest `master`).** Seam (`ctx.web` search/fetch provider registry, `web` / `tool-web` rows, Schemastery config, SSRF guard, HTML→text, sticky `baseUrls` failover) unchanged since `0.1.2-alpha.3` — no code or config migration required. Bumped install tarball reference to `0.5.5` and completed bilingual six-section coverage (Release / Changelog / Install / Uninstall / Usage / Config — bilingual). **/ 兼容性：已在 deepseek-harness `0.1.2-alpha.4` 最新 `master` 上验证。** 缝接口（`ctx.web` 搜索/抓取注册、`web` / `tool-web` 行、Schemastery 配置、SSRF 防护、HTML→文本、粘性 `baseUrls` 故障转移）自 `0.1.2-alpha.3` 以来未变，无需代码或配置迁移。安装包引用升级至 `0.5.5`，并补齐双语六项覆盖（发行版 / 更新说明 / 安装 / 卸载 / 使用 / 配置——双语）。

## [0.5.4] - 2026-09-01

### Changed / 变更

- **Adapted to deepseek-harness `0.1.2-alpha.3` (master).** Between
  `0.1.2-alpha.2` and `0.1.2-alpha.3` the `ctx.web` seam
  (`registerSearchProvider` / `registerFetchProvider`), the `web` /
  `tool-web` config rows, and the provider contracts are unchanged —
  `packages/web` moved only its version pins in that release — so no plugin
  code changes were required. `@deepseek-ai/cordis` stays at `4.0.2` and
  `@deepseek-ai/schemastery` moves to `^3.18.2` (the revision the alpha.3
  checkout builds against); the committed `lib/index.js` is rebuilt and the
  full test suite passes against the new package set.
- **适配 deepseek-harness `0.1.2-alpha.3`（master）。** 从 `0.1.2-alpha.2`
  到 `0.1.2-alpha.3`，`ctx.web` 缝（`registerSearchProvider` /
  `registerFetchProvider`）、`web` / `tool-web` 配置行以及 provider 契约均
  未变化——该版本 `packages/web` 仅移动版本号——因此无需改动插件代码。
  `@deepseek-ai/cordis` 保持 `4.0.2`，`@deepseek-ai/schemastery` 升至
  `^3.18.2`（alpha.3 检出所依赖的 revision）；重新构建了随包提交的
  `lib/index.js`，全部测试在新区间依赖下通过。

## [0.5.3] - 2026-08-31

### Changed / 变更

- **Adapted to deepseek-harness `0.1.2-alpha.2` (master).** Between
  `0.1.2-alpha.1` and `0.1.2-alpha.2` the `ctx.web` seam
  (`registerSearchProvider` / `registerFetchProvider`), the `web` /
  `tool-web` config rows, and the provider contracts are unchanged, so no
  plugin code changes were required. `devDependencies` now pin
  `@deepseek-ai/cordis` at `4.0.2`; the committed `lib/index.js` is rebuilt
  and the full test suite passes against the new package set.
- **适配 deepseek-harness `0.1.2-alpha.2`（master）。** 从 `0.1.2-alpha.1`
  到 `0.1.2-alpha.2`，`ctx.web` 缝（`registerSearchProvider` /
  `registerFetchProvider`）、`web` / `tool-web` 配置行以及 provider 契约均
  未变化，因此无需改动插件代码。`devDependencies` 锁定
  `@deepseek-ai/cordis` 至 `4.0.2`；重新构建了随包提交的 `lib/index.js`，
  全部测试在新区间依赖下通过。

## [0.5.2] - 2026-08-30

### Changed

- README: install section aligned with the `dsh-tinyfish-search` layout —
  `dsh plugin add` plus repository / tarball / `github:` alternatives
  (README.md and README.zh-CN.md).

## [0.5.1] - 2026-08-30

### Changed

- **npm package renamed: dropped the `@maxwell-feng/` scope.** The package is
  now published as **`dsh-searxng-web`** (aligned with the unscoped
  `dsh-tinyfish-search` convention). All install commands, badges and docs
  use the new name; the old `@maxwell-feng/dsh-searxng-web` package is
  deprecated. No code, config or behavior changes — the bundle layer,
  provider ids (`searxng-web` / `searxng-web-fetch`) and install steps are
  identical apart from the name.

## [0.5.0] - 2026-08-29

### Compatibility

- **Adapted to deepseek-harness `0.1.2-alpha.1` (master)**: the `ctx.web`
  seam (`registerSearchProvider` / `registerFetchProvider`) and the `web` /
  `tool-web` config rows are unchanged from `0.4.0` — provider registration
  now returns fiber-scoped disposers, which the plugin's registrations rely
  on as before.
- `web_fetch` now reports the final URL after redirects (`Response.url`) in
  the result's `url` field, matching the current `dsh-web` seam contract
  ("the final URL after allowed redirects").
- `@deepseek-ai/cordis` stays `4.0.1`.

All notable changes to this project are documented in this file.
Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [0.4.0] - 2026-08-24

### Added

- **Multi-endpoint sticky failover** via the new `baseUrls` config field —
  an ordered endpoint list for instances reachable through several doors at
  once (public IPv4 + public IPv6 + LAN is the canonical triple-stack):
  - Attempts start at the last endpoint that succeeded (sticky) and walk the
    remaining list once per call.
  - Only network-level failures (connection refused / unreachable / timeout /
    DNS) advance to the next endpoint; any HTTP answer proves the door is
    alive and its status is surfaced as-is, so auth problems are never masked.
  - When every endpoint is unreachable a single `network`-classified error is
    raised after one full pass.
  - `baseUrls` takes precedence over `baseUrl` when non-empty; entries are
    trimmed and de-duplicated. Single-`baseUrl` configurations behave exactly
    as before.

### Changed

- Provider `available()` now reflects the resolved endpoint list; the load
  log line reports the endpoint count and primary door.

## [0.3.0] - 2026-08-23

### Added

- Instance authentication, for deployments behind an API-key gate or an
  authenticating reverse proxy (searxng + caddy/nginx):
  - `headers` — extra HTTP headers attached to SearXNG requests only
    (e.g. `X-API-Key`).
  - `basicAuth.username` / `basicAuth.password` — sets the Authorization
    header for caddy `basic_auth` / nginx `auth_basic` front doors.
  - Credentials never ride on `web_fetch` requests (model-chosen
    third-party pages must stay credential-free). Setting both `basicAuth`
    and a user-supplied `headers.Authorization` fails at load time.
- A Schemastery `Config` schema per the dsh plugin docs
  (`docs/user/develop/basic/config`): configuration is now validated at load
  time with actionable errors; defaults mirror the previous defensive
  fallbacks, so existing configs behave identically.

### Changed

- The 403 error message now distinguishes "credentials rejected" from "JSON
  output disabled" when instance credentials are configured.
- New dependency: `@deepseek-ai/schemastery` (runtime, used by the loader).

## [0.2.0] - 2026-08-23

### Changed

- **Rewritten in TypeScript** (`src/index.ts` → committed `lib/index.js`).
  Same runtime behavior; the codebase now has full strict-mode types for the
  config, the ctx.web provider contracts, and the SearXNG JSON response.
- Installs still need no build: `lib/` is committed, so npm and git installs
  load the prebuilt entry directly (no `prepare` script, no pnpm
  `allowBuilds` entry).

### Added

- `tsconfig.json` (strict, NodeNext) and a `Development` section in both
  READMEs (`npm run build` / `npm test`).
- CI compiles the TypeScript source before running the test suite
  (`npm ci` → `npm test` in both workflows).

## [0.1.1] - 2026-08-23

### Changed

- Documentation: npm install is now the recommended method (GitHub install
  kept as an alternative); requirements note the verified dsh version
  (`0.1.1-rc.2`); added a maintainer release-process section.
- CI: publish workflow mirrors `@maxwell-feng/dsh-windows-ocr` — `v*` tags
  trigger tests + npm publish via OIDC trusted publishing; standalone test
  suite made fully offline/self-contained.

## [0.1.0] - 2026-08-23

### Added

- `ctx.web` search provider (`searxng-web`) backed by the SearXNG JSON API:
  the native `web_search` tool now executes against your own instance —
  keyless, self-hosted, no third-party search vendor.
- `ctx.web` fetch provider (`searxng-web-fetch`): a bounded GET reader for
  the native `web_fetch` tool. HTML responses are reduced to readable text
  (script/style stripped, tags removed, entities decoded) and capped at
  `fetchMaxChars`.
- SSRF guard on `web_fetch` targets (private / loopback / link-local /
  CGNAT ranges refused by default; disable with `ssrfGuard: false`).
- Configurable search defaults forwarded to SearXNG per query: `language`,
  `safesearch`, `categories`, `engines`, `timeRange`.
- Bundle ships a ready-made patch layer: installing it points `ctx.web` at
  SearXNG and re-enables `web_fetch` — no extra wiring needed.
- Bilingual README (English / 简体中文).