web-access-cli 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ English | [简体中文](README_CN.md)
 [![CI](https://github.com/Juexe/web-access-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Juexe/web-access-cli/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-An agent-neutral CLI for web capabilities. It defines search and web content extraction as stable capabilities while normalizing differences among Tavily, Exa, Brave, SearXNG, AnySearch, XCrawl, Firecrawl, Jina, and other providers behind a unified internal schema.
+An agent-neutral CLI for web capabilities. It defines search and web content extraction as stable capabilities while normalizing differences among Tavily, Exa, Bocha, Brave, SearXNG, AnySearch, XCrawl, DeepSeek, Firecrawl, Jina, and other providers behind a unified internal schema.
 
 The CLI is the primary product interface. It is not tied to Pi, Claude Code, Codex, Cursor, OpenCode, or any other agent. Skills, MCP integrations, and agent plugins may only integrate as adapters on top of the CLI; they must not leak into the core capabilities or provider implementations.
 
@@ -13,35 +13,35 @@ The CLI is the primary product interface. It is not tied to Pi, Claude Code, Cod
 
 | Capability | Provider types | Normalized output |
 | --- | --- | --- |
-| `search` | Tavily, Exa, Brave, SearXNG, AnySearch, XCrawl | `rank`, `title`, `url`, `snippet` |
+| `search` | Tavily, Exa, Bocha, Brave, SearXNG, AnySearch, XCrawl, DeepSeek | `rank`, `title`, `url`, `snippet` |
 | `extract` | Firecrawl v2, Jina Reader, Exa Contents, AnySearch, XCrawl, HTTP | Markdown `Document` |
 
-A provider type describes an implementation, while a provider instance is a configurable instance of that type. One type can have multiple instances, such as `exa_team` and `exa_personal`. A route is an ordered array of instance IDs that determines both which instances are enabled and the order in which `auto` tries them.
+A provider type describes an implementation, while a provider instance is a configurable instance of that type. One type can have multiple instances, such as `exa_team` and `exa_personal`. A `providers` route is an ordered array of instance IDs that determines which instances are enabled and the initial `auto` order. The CLI stores the learned effective order in the sibling `_providers` field.
 
 ## Installation
 
 Node.js 22.19 or later is required.
 
-The npm package has not been published yet. Build and run the CLI from source:
+Install the CLI from npm:
 
 ```sh
-git clone https://github.com/Juexe/web-access-cli.git
-cd web-access-cli
-pnpm install --frozen-lockfile
-pnpm build
-node dist/cli.js --help
+npm install --global web-access-cli
+web-access --help
 ```
 
-After building, an optional global installation can point to the absolute repository path:
+Alternatively, install it with pnpm:
 
 ```sh
-pnpm add --global <absolute-path-to-web-access-cli>
+pnpm add --global web-access-cli
 web-access --help
 ```
 
-For development in this repository:
+For development from source:
 
 ```sh
+git clone https://github.com/juexe/web-access-cli.git
+cd web-access-cli
+pnpm install --frozen-lockfile
 pnpm check
 pnpm pack:check
 ```
@@ -82,6 +82,7 @@ web-access search "browser automation" --include-domain example.com --exclude-do
 
 web-access extract https://example.com/article
 web-access extract https://example.com/article --provider http --timeout 30000
+web-access extract https://example.com/article --json
 
 web-access providers --pretty
 web-access doctor --pretty
@@ -98,7 +99,7 @@ The CLI provides the `search` and `extract` capability commands, the `providers`
 - `--pretty`: Pretty-print JSON. By default, JSON is written on a single line.
 - `--help`, `--version`: Print standard CLI help or version text.
 
-Except for help and version output, stdout always contains exactly one JSON envelope. Diagnostic messages are never mixed into stdout.
+Extract succeeds with Markdown by default. Its YAML front matter contains only the final Instance ID (`provider`), the returned document URL (`url`), and a non-empty trimmed title (`title`). Add `extract --json` when a schema v2 envelope is required; `--pretty` and `--debug` also select JSON. Extract failures, including `partial` results, always remain JSON envelopes. Search, diagnostics, and `config edit` continue to output JSON. Diagnostic messages are never mixed into stdout.
 
 ## Configuration
 
@@ -108,11 +109,13 @@ The default path on every platform is `~/.config/web-access-cli/config.json`, wh
 
 `web-access config edit` creates parent directories and a complete default configuration when the file is missing, then opens it with the operating system's default application for JSON files. An existing file is opened byte-for-byte as-is, even when it is temporarily invalid JSON; it is never overwritten or reformatted. The command waits only for the operating system to accept the open request, not for the editor to close. On success, envelope `data` contains the absolute `path`, `created`, and `opened: true`. A default-application launch failure returns `open_failed`; a configuration file that was created successfully remains available for manual editing.
 
+`config edit` itself never rewrites existing content. After an `auto` capability call succeeds or encounters fallback-eligible failures, the CLI atomically updates `search._providers` or `extract._providers`. If the default configuration does not exist, the first `auto` call that produces a learning result creates the complete default configuration. `_providers` is CLI-managed and cannot enable an instance outside `providers`. Missing, malformed, duplicate, unknown, or membership-mismatched internal entries reset the whole capability to the declared route. Delete `_providers` to restore the user-declared initial order manually.
+
 The complete JSON Schema is available at [schemas/config.schema.json](schemas/config.schema.json). Example:
 
 ```json
 {
-  "$schema": "https://unpkg.com/web-access-cli@0.1.0/schemas/config.schema.json",
+  "$schema": "https://unpkg.com/web-access-cli@0.3.0/schemas/config.schema.json",
   "providers": [
     {
       "id": "exa_team",
@@ -150,14 +153,16 @@ The complete JSON Schema is available at [schemas/config.schema.json](schemas/co
 }
 ```
 
-The built-in instances are `tavily`, `exa`, `brave`, `searxng`, `firecrawl`, `jina`, `http`, `anysearch`, and `xcrawl`. A configuration entry with the same ID overrides fields on the built-in instance. A custom ID creates another instance of the selected type. An instance is enabled only when it appears in the corresponding `providers` route. AnySearch defaults to `https://api.anysearch.com` and supports anonymous calls; XCrawl defaults to `https://run.xcrawl.com` and requires an API key.
+The built-in instances are `tavily`, `exa`, `bocha`, `brave`, `searxng`, `firecrawl`, `jina`, `http`, `anysearch`, `xcrawl`, and `deepseek`. A configuration entry with the same ID overrides fields on the built-in instance. A custom ID creates another instance of the selected type. An instance is enabled only when it appears in the corresponding `providers` route. Bocha defaults to `https://api.bocha.cn` and requires an API key; AnySearch defaults to `https://api.anysearch.com` and supports anonymous calls; XCrawl defaults to `https://run.xcrawl.com` and requires an API key; DeepSeek defaults to `https://api.deepseek.com/anthropic/v1` and requires an API key.
 
 Default routes:
 
-- Search: `tavily -> exa -> brave -> searxng -> anysearch -> xcrawl`
+- Search: `tavily -> exa -> bocha -> brave -> searxng -> anysearch -> xcrawl -> deepseek`
 - Extract: `firecrawl -> jina -> exa -> anysearch -> xcrawl -> http`
 
-The default routes include every built-in instance that supports the corresponding capability. Custom instance IDs are merged into the instance list but must still be added to routes explicitly. An omitted route uses the defaults above, while an explicit empty array disables that capability. In `auto` mode, incompletely configured instances are skipped; AnySearch can be called anonymously with its default base URL, and XCrawl is skipped until an API key is configured. Both instance types accept `searchFilterMode`: `strict` (default; freshness skips the provider) or `best_effort` (rewrites freshness into a query fragment). Domain constraints are rewritten into the query and strictly re-applied locally. XCrawl Extract always uses synchronous Scrape with Markdown output; Map, Crawl, and asynchronous jobs are outside the current CLI capabilities.
+The default routes include every built-in instance that supports the corresponding capability. Custom instance IDs are merged into the instance list but must still be added to routes explicitly. An omitted route uses the defaults above, while an explicit empty array disables that capability. In `auto` mode, incompletely configured instances are skipped; AnySearch can be called anonymously with its default base URL, while XCrawl and DeepSeek are skipped until their API keys are configured. AnySearch and XCrawl accept `searchFilterMode`: `strict` (default; freshness skips the provider) or `best_effort` (rewrites freshness into a query fragment). Domain constraints are rewritten into the query and strictly re-applied locally. XCrawl Extract always uses synchronous Scrape with Markdown output; Map, Crawl, and asynchronous jobs are outside the current CLI capabilities.
+
+DeepSeek Search performs a full Anthropic-compatible Messages model turn with the native `web_search_20250305` server tool, so it can have higher latency and cost than a dedicated search endpoint. It is last in the default route and is reached only after earlier providers are unavailable, return a final non-2xx HTTP response, or otherwise fail recoverably. The adapter accepts URLs only from structured `web_search_tool_result` blocks, joins citation excerpts by URL, and never extracts URLs from model prose. Domain constraints are rewritten into the query and strictly re-applied locally; `freshness` is unsupported and skips DeepSeek with a recoverable error. Redirects are rejected without contacting the `Location` target. Provider-private `encrypted_content` payloads are omitted from `raw` because they are opaque, cannot be displayed or decoded by the CLI, and add no diagnostic value.
 
 ### Credentials and URLs
 
@@ -167,6 +172,7 @@ Environment variables take precedence over plaintext keys in JSON. Built-in inst
 | --- | --- | --- |
 | Tavily | `TAVILY_API_KEY` | `TAVILY_BASE_URL` |
 | Exa | `EXA_API_KEY` | `EXA_BASE_URL` |
+| Bocha | `BOCHA_API_KEY` | `BOCHA_BASE_URL`, default `https://api.bocha.cn` |
 | Brave | `BRAVE_API_KEY` | `BRAVE_BASE_URL` |
 | SearXNG | None | `SEARXNG_BASE_URL`, required |
 | Firecrawl | `FIRECRAWL_API_KEY` | `FIRECRAWL_BASE_URL` |
@@ -174,17 +180,23 @@ Environment variables take precedence over plaintext keys in JSON. Built-in inst
 | HTTP | None | None |
 | AnySearch | `ANYSEARCH_API_KEY`, optional | `ANYSEARCH_BASE_URL`, default `https://api.anysearch.com` |
 | XCrawl | `XCRAWL_API_KEY` | `XCRAWL_BASE_URL`, default `https://run.xcrawl.com` |
+| DeepSeek | `DEEPSEEK_API_KEY` | No standard environment variable; default `https://api.deepseek.com/anthropic/v1` |
 
 Custom instances use `apiKeyEnv` and `baseUrlEnv` to name their environment variables. Every remote provider can define a `baseUrl` and additional `headers`. The public `api.firecrawl.dev` service requires a key; a self-hosted Firecrawl v2 instance can run without one.
 
 ## Execution and fallback
 
-`--provider auto` follows the configured route order:
+`--provider auto` follows the effective `_providers` order, or starts from `providers` when the internal field is absent or invalid:
 
 1. An instance with incomplete configuration is recorded as a failed attempt and skipped.
-2. Recoverable errors, including network errors, timeouts, rate limits, 5xx responses, oversized responses, and missing usable content, cause the router to try the next instance.
-3. Non-recoverable errors, including authentication errors, invalid input, and unsupported content, stop execution immediately.
-4. If every instance fails, the command returns `provider_exhausted`. The best short content produced during extraction is preserved in `partial`.
+2. A final provider HTTP response outside 2xx, including authentication, request, rate-limit, and server errors, causes the router to try the next instance.
+3. Other recoverable errors, including network errors, timeouts, oversized responses, and missing usable content, also cause the router to continue.
+4. Non-recoverable failures without a final non-2xx response, including invalid input and unsupported content detected in a successful response, stop execution immediately.
+5. If every instance fails, the command returns `provider_exhausted`. The best short content produced during extraction is preserved in `partial`.
+
+After each `auto` call, a successful instance moves to the front, untried instances remain in the middle, and instances with the fallback-eligible failures above move stably to the back. Relative order within each group is preserved. The order stays unchanged when every instance fails. Search and Extract learn independently; explicit instances, non-fallback failures, and user cancellation never update the order. Writes use atomic replacement, and the last writer wins across concurrent processes.
+
+An attempt keeps the provider's original error code, HTTP status, and `retryable` value. `retryable` describes whether the original operation can be retried against the same provider; it is not the sole condition for switching to the next provider in an automatic route.
 
 Selecting an instance explicitly executes it strictly without fallback. If the instance is not in the route, the command returns `provider_disabled`.
 
@@ -192,39 +204,13 @@ Default limits are a 60-second total timeout and a 20-second per-attempt timeout
 
 ## Output contract
 
-Successful response example:
+Capability commands use output schema version 2. Their default envelope is intentionally small:
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "ok": true,
-  "command": "search",
-  "durationMs": 183,
-  "request": {
-    "query": "Agent-neutral web CLI",
-    "provider": "auto",
-    "limit": 5,
-    "includeDomains": [],
-    "excludeDomains": []
-  },
-  "provider": { "id": "exa", "type": "exa" },
-  "attempts": [
-    {
-      "provider": { "id": "tavily", "type": "tavily" },
-      "status": "failed",
-      "durationMs": 0,
-      "error": {
-        "code": "provider_unavailable",
-        "message": "tavily 未完成 search 所需配置",
-        "retryable": true
-      }
-    },
-    {
-      "provider": { "id": "exa", "type": "exa" },
-      "status": "success",
-      "durationMs": 183
-    }
-  ],
+  "provider": "exa",
   "data": {
     "results": [
       {
@@ -234,14 +220,27 @@ Successful response example:
         "snippet": "Example snippet"
       }
     ]
-  },
-  "raw": {}
+  }
 }
 ```
 
-The Chinese `message` value above matches the CLI's current error output contract.
+Default capability output contains only `schemaVersion`, `ok`, the final Instance ID and normalized `data`. Failures contain a compact `error` and, when providers were attempted, `attempts` entries with only Instance ID, error code and optional HTTP status. Extract quality failures may include a `partial` document without raw provider data. If the learned order cannot be written, either a success or failure envelope additionally contains `warnings: [{ "code": "provider_order_update_failed", "message": "..." }]` without replacing the primary result. Search and extract input errors use the same compact failure shape.
+
+For human-readable extraction, the default Markdown output starts with YAML front matter and then the provider-normalized Markdown body. Metadata values use JSON double-quoted scalar encoding and the body is not modified. Existing scripts and other machine consumers should append `--json` explicitly.
+
+Example default extract output:
+
+```markdown
+---
+provider: "local_http"
+url: "https://example.com/article"
+title: "Example title"
+---
+
+# Article content
+```
 
-`raw` contains only the response body from the final success or best failure. It never contains requests, response headers, or every historical response. API keys are redacted from serializable `raw` data and error messages. Stable schemas are available in [schemas](schemas).
+Use `--debug` on `search` or `extract` only for protocol troubleshooting. It adds a nested `debug` object containing the request, durations, complete attempts and the final or best-failure raw response. Raw data remains recursively redacted and is not part of normal Agent calls. `providers`, `doctor`, and `config edit` retain their detailed diagnostic envelopes; all envelopes use schema version 2. Stable schemas are available in [schemas](schemas).
 
 Exit codes:
 
@@ -250,7 +249,7 @@ Exit codes:
 - `1`: Runtime, provider, doctor, or default-application launch failure
 - `130`: User cancellation
 
-`providers` lists each instance's type, capabilities, route status, credential source, and base URL source. `doctor` performs local configuration checks only and does not call remote APIs. If an enabled route contains an unconfigured instance, the command returns `doctor_failed` with exit code `1`.
+`providers` lists each instance's type, capabilities, route status, credential source, and base URL source. Its `searchRoute` and `extractRoute` fields show the effective order for the next `auto` call. `doctor` performs local configuration checks only and does not call remote APIs. If an enabled route contains an unconfigured instance, the command returns `doctor_failed` with exit code `1`.
 
 ## HTTP and security boundaries
 

package/README_CN.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/Juexe/web-access-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Juexe/web-access-cli/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-一个 Agent-neutral 的网页能力 CLI。它把“搜索”和“网页正文提取”定义为稳定能力，把 Tavily、Exa、Brave、SearXNG、AnySearch、XCrawl、Firecrawl、Jina 等差异收敛到内部统一 schema。
+一个 Agent-neutral 的网页能力 CLI。它把“搜索”和“网页正文提取”定义为稳定能力，把 Tavily、Exa、Bocha、Brave、SearXNG、AnySearch、XCrawl、DeepSeek、Firecrawl、Jina 等差异收敛到内部统一 schema。
 
 CLI 是主要产品形态，不绑定 Pi、Claude Code、Codex、Cursor、OpenCode 或其他 Agent。Skill、MCP 和 Agent 插件只能作为 CLI 上层 adapter 接入，不能污染核心能力和 Provider 实现。
 
@@ -13,35 +13,35 @@ CLI 是主要产品形态，不绑定 Pi、Claude Code、Codex、Cursor、OpenCo
 
 | 能力 | Provider Type | 统一输出 |
 | --- | --- | --- |
-| `search` | Tavily、Exa、Brave、SearXNG、AnySearch、XCrawl | `rank`、`title`、`url`、`snippet` |
+| `search` | Tavily、Exa、Bocha、Brave、SearXNG、AnySearch、XCrawl、DeepSeek | `rank`、`title`、`url`、`snippet` |
 | `extract` | Firecrawl v2、Jina Reader、Exa Contents、AnySearch、XCrawl、HTTP | Markdown `Document` |
 
-Provider Type 描述实现类型；Provider Instance 是一份可配置实例。一个 Type 可以有多个 Instance，例如 `exa_team` 和 `exa_personal`。Route 是有序 Instance ID 数组，既决定启用状态，也决定 `auto` 的尝试顺序。
+Provider Type 描述实现类型；Provider Instance 是一份可配置实例。一个 Type 可以有多个 Instance，例如 `exa_team` 和 `exa_personal`。`providers` Route 是有序 Instance ID 数组，决定启用状态和 `auto` 的初始顺序；CLI 会把学习后的实际顺序保存在同级 `_providers`。
 
 ## 安装
 
 要求 Node.js 22.19 或更高版本。
 
-npm 包尚未发布。当前请从源码构建并运行：
+从 npm 全局安装：
 
 ```sh
-git clone https://github.com/Juexe/web-access-cli.git
-cd web-access-cli
-pnpm install --frozen-lockfile
-pnpm build
-node dist/cli.js --help
+npm install --global web-access-cli
+web-access --help
 ```
 
-构建完成后，也可以使用仓库绝对路径安装为全局命令：
+也可以使用 pnpm 安装：
 
 ```sh
-pnpm add --global <web-access-cli 仓库绝对路径>
+pnpm add --global web-access-cli
 web-access --help
 ```
 
-在仓库中开发：
+从源码开发：
 
 ```sh
+git clone https://github.com/juexe/web-access-cli.git
+cd web-access-cli
+pnpm install --frozen-lockfile
 pnpm check
 pnpm pack:check
 ```
@@ -82,6 +82,7 @@ web-access search "browser automation" --include-domain example.com --exclude-do
 
 web-access extract https://example.com/article
 web-access extract https://example.com/article --provider http --timeout 30000
+web-access extract https://example.com/article --json
 
 web-access providers --pretty
 web-access doctor --pretty
@@ -98,7 +99,7 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 - `--pretty`：格式化 JSON；默认输出单行 JSON。
 - `--help`、`--version`：输出常规 CLI 帮助或版本文本。
 
-除帮助与版本外，命令的 stdout 始终只有一个 JSON envelope。诊断信息不会混入 stdout。
+`extract` 成功时默认输出 Markdown，文首 YAML front matter 只包含最终 Instance ID（`provider`）、Provider 返回的文档 URL（`url`）和非空的去除首尾空白标题（`title`）。需要 schema v2 envelope 时显式追加 `extract --json`；`--pretty` 和 `--debug` 也会选择 JSON。提取失败（包括 `partial`）始终输出 JSON envelope。`search`、诊断命令和 `config edit` 继续输出 JSON。诊断信息不会混入 stdout。
 
 ## 配置
 
@@ -108,11 +109,13 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 
 `web-access config edit` 会在配置文件缺失时创建父目录和完整默认配置，再用系统为 JSON 文件关联的默认应用打开；已有文件会原样打开，即使内容暂时不是有效 JSON 也不会被覆盖或格式化。命令只等待系统接受打开请求，不等待编辑器关闭。成功 envelope 的 `data` 包含绝对 `path`、是否新建的 `created` 和 `opened: true`。无法启动默认应用时返回 `open_failed`；如果配置刚刚创建成功，文件仍会保留以便手动打开。
 
+`config edit` 本身不会改写已有内容；能力命令使用 `auto` 成功或发生可回退失败后，会原子更新 `search._providers` 或 `extract._providers`。默认配置尚不存在时，首次产生学习结果的 `auto` 调用会创建完整默认配置。`_providers` 由 CLI 管理，不会启用 `providers` 之外的 Instance；其内容缺失、格式错误、重复、引用未知 ID 或与 `providers` 成员集合不一致时会整组重置。删除 `_providers` 可以手动恢复用户声明的初始顺序。
+
 完整 JSON Schema 位于 [schemas/config.schema.json](schemas/config.schema.json)。示例：
 
 ```json
 {
-  "$schema": "https://unpkg.com/web-access-cli@0.1.0/schemas/config.schema.json",
+  "$schema": "https://unpkg.com/web-access-cli@0.3.0/schemas/config.schema.json",
   "providers": [
     {
       "id": "exa_team",
@@ -150,14 +153,16 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 }
 ```
 
-内置 Instance 为 `tavily`、`exa`、`brave`、`searxng`、`firecrawl`、`jina`、`http`、`anysearch`、`xcrawl`。配置同 ID 时会覆盖内置实例的字段；自定义 ID 可以创建同 Type 的额外实例。只有出现在对应 `providers` Route 中的实例才启用。AnySearch 默认 base URL 为 `https://api.anysearch.com`，支持匿名调用；XCrawl 默认 base URL 为 `https://run.xcrawl.com`，必须配置 API key。
+内置 Instance 为 `tavily`、`exa`、`bocha`、`brave`、`searxng`、`firecrawl`、`jina`、`http`、`anysearch`、`xcrawl`、`deepseek`。配置同 ID 时会覆盖内置实例的字段；自定义 ID 可以创建同 Type 的额外实例。只有出现在对应 `providers` Route 中的实例才启用。Bocha 默认 base URL 为 `https://api.bocha.cn`，必须配置 API key；AnySearch 默认 base URL 为 `https://api.anysearch.com`，支持匿名调用；XCrawl 默认 base URL 为 `https://run.xcrawl.com`，必须配置 API key；DeepSeek 默认 base URL 为 `https://api.deepseek.com/anthropic/v1`，必须配置 API key。
 
 默认 Route：
 
-- Search：`tavily -> exa -> brave -> searxng -> anysearch -> xcrawl`
+- Search：`tavily -> exa -> bocha -> brave -> searxng -> anysearch -> xcrawl -> deepseek`
 - Extract：`firecrawl -> jina -> exa -> anysearch -> xcrawl -> http`
 
-默认 Route 包含支持对应 Capability 的全部内置 Instance。自定义 ID 会合并到 Instance 列表，但仍需显式加入 Route；省略 Route 时使用上述默认值，显式空数组则禁用对应能力。`auto` 会跳过未完成配置的 Instance；AnySearch 使用默认 base URL 时可匿名调用，XCrawl 则在配置 API key 前被跳过。两类 Instance 均可设置 `searchFilterMode`：`strict`（默认，遇到 freshness 时跳过）或 `best_effort`（将日期改写为查询片段）。域名条件会改写查询并在本地再次严格过滤。XCrawl Extract 固定使用同步 Scrape 的 Markdown 输出；Map、Crawl 和异步任务不属于当前 CLI 能力。
+默认 Route 包含支持对应 Capability 的全部内置 Instance。自定义 ID 会合并到 Instance 列表，但仍需显式加入 Route；省略 Route 时使用上述默认值，显式空数组则禁用对应能力。`auto` 会跳过未完成配置的 Instance；AnySearch 使用默认 base URL 时可匿名调用，XCrawl 和 DeepSeek 则在配置 API key 前被跳过。AnySearch 与 XCrawl 可设置 `searchFilterMode`：`strict`（默认，遇到 freshness 时跳过）或 `best_effort`（将日期改写为查询片段）。域名条件会改写查询并在本地再次严格过滤。XCrawl Extract 固定使用同步 Scrape 的 Markdown 输出；Map、Crawl 和异步任务不属于当前 CLI 能力。
+
+DeepSeek Search 通过 Anthropic-compatible Messages API 调用原生 `web_search_20250305` server tool，一次搜索是完整模型轮次，因此延迟和成本可能高于专用搜索 endpoint。它位于默认 Route 末尾，仅在前序 Provider 未配置、返回最终非 2xx HTTP 响应或发生其他可恢复失败后触发。Adapter 只接受 `web_search_tool_result` 中的结构化 URL，按 URL 合并 citation 摘要，绝不从模型 prose 中猜测 URL。域名条件会改写查询并在本地再次严格过滤；DeepSeek 不支持 `freshness`，遇到该参数时以可恢复错误跳过；重定向会被严格拒绝，且不会访问 `Location` 目标。Provider 私有的 `encrypted_content` 是 CLI 无法展示或解码的 opaque payload，不具备诊断价值，因此会从 `raw` 中移除。
 
 ### 凭据和 URL
 
@@ -167,6 +172,7 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 | --- | --- | --- |
 | Tavily | `TAVILY_API_KEY` | `TAVILY_BASE_URL` |
 | Exa | `EXA_API_KEY` | `EXA_BASE_URL` |
+| Bocha | `BOCHA_API_KEY` | `BOCHA_BASE_URL`，默认 `https://api.bocha.cn` |
 | Brave | `BRAVE_API_KEY` | `BRAVE_BASE_URL` |
 | SearXNG | 无 | `SEARXNG_BASE_URL`，必需 |
 | Firecrawl | `FIRECRAWL_API_KEY` | `FIRECRAWL_BASE_URL` |
@@ -174,17 +180,23 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 | HTTP | 无 | 无 |
 | AnySearch | `ANYSEARCH_API_KEY`，可选 | `ANYSEARCH_BASE_URL`，默认 `https://api.anysearch.com` |
 | XCrawl | `XCRAWL_API_KEY` | `XCRAWL_BASE_URL`，默认 `https://run.xcrawl.com` |
+| DeepSeek | `DEEPSEEK_API_KEY` | 无标准环境变量；默认 `https://api.deepseek.com/anthropic/v1` |
 
 自定义 Instance 使用 `apiKeyEnv` 和 `baseUrlEnv` 指定自己的环境变量。所有远端 Provider 都可以设置 `baseUrl` 和附加 `headers`。公共 `api.firecrawl.dev` 需要 key；自托管 Firecrawl v2 可以不设置 key。
 
 ## 执行与回退
 
-`--provider auto` 按 Route 顺序执行：
+`--provider auto` 按 `_providers` 的有效顺序执行；字段不存在或无效时从 `providers` 开始：
 
 1. 未完成配置的实例会记录为失败 attempt 并跳过。
-2. 网络错误、超时、限流、5xx、响应过大、无可用正文等可恢复错误会尝试下一个实例。
-3. 鉴权错误、无效输入、不支持的内容等不可恢复错误会立即停止。
-4. 所有实例失败时返回 `provider_exhausted`。提取过程中产生的最佳短正文会保留在 `partial`。
+2. Provider 返回的最终 HTTP 响应不在 2xx 范围时，包括鉴权、请求、限流和服务器错误，Router 会尝试下一个实例。
+3. 网络错误、超时、响应过大、无可用正文等其他可恢复错误也会继续 Route。
+4. 没有最终非 2xx 响应的不可恢复错误，例如无效输入或在成功响应中检测到不支持的内容，会立即停止。
+5. 所有实例失败时返回 `provider_exhausted`。提取过程中产生的最佳短正文会保留在 `partial`。
+
+每次 `auto` 调用完成后，成功 Instance 移到队头，未尝试 Instance 保持在中间，发生上述可回退失败的 Instance 稳定移到队尾；三组内部顺序不变。所有 Instance 都失败时顺序不变。Search 与 Extract 独立学习；显式 Instance、不可回退错误和用户取消不会更新顺序。写入采用原子替换，并发进程由最后写入者生效。
+
+Attempt 会保留 Provider 的原始错误码、HTTP status 和 `retryable` 值。`retryable` 表示原始操作是否适合对同一 Provider 重试，不再是自动 Route 切换到下一 Provider 的唯一条件。
 
 显式指定 Instance 时严格执行，不触发 fallback。若实例不在 Route 中，返回 `provider_disabled`。
 
@@ -192,39 +204,13 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 
 ## 输出契约
 
-成功示例：
+能力命令使用 output schema v2，默认 envelope 刻意保持精简：
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "ok": true,
-  "command": "search",
-  "durationMs": 183,
-  "request": {
-    "query": "Agent-neutral web CLI",
-    "provider": "auto",
-    "limit": 5,
-    "includeDomains": [],
-    "excludeDomains": []
-  },
-  "provider": { "id": "exa", "type": "exa" },
-  "attempts": [
-    {
-      "provider": { "id": "tavily", "type": "tavily" },
-      "status": "failed",
-      "durationMs": 0,
-      "error": {
-        "code": "provider_unavailable",
-        "message": "tavily 未完成 search 所需配置",
-        "retryable": true
-      }
-    },
-    {
-      "provider": { "id": "exa", "type": "exa" },
-      "status": "success",
-      "durationMs": 183
-    }
-  ],
+  "provider": "exa",
   "data": {
     "results": [
       {
@@ -234,12 +220,27 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
         "snippet": "Example snippet"
       }
     ]
-  },
-  "raw": {}
+  }
 }
 ```
 
-`raw` 只包含最终成功或最佳失败的 response body，不包含请求、响应 headers 或所有历史响应。API key 会从可序列化的 `raw` 和错误消息中脱敏。稳定 schema 位于 [schemas](schemas)。
+能力命令成功时默认只有 `schemaVersion`、`ok`、最终 Instance ID 和规范化 `data`。失败时包含精简 `error`；实际尝试过 Provider 时，`attempts` 只保留 Instance ID、错误码和可选 HTTP status。提取质量失败可包含不含 raw 的 `partial` 文档。排序无法写回时，成功或失败 envelope 会额外包含 `warnings: [{ "code": "provider_order_update_failed", "message": "..." }]`，但不会覆盖主要结果。搜索和提取输入错误也使用相同的精简失败结构。
+
+面向人的提取默认输出以 YAML front matter 开头、随后是 Provider 规范化的 Markdown 正文。元数据值统一使用 JSON 双引号标量编码，正文内容不改写。已有脚本和其他机器消费者应显式追加 `--json`。
+
+默认提取输出示例：
+
+```markdown
+---
+provider: "local_http"
+url: "https://example.com/article"
+title: "Example title"
+---
+
+# Article content
+```
+
+只有协议排障时才在 `search` 或 `extract` 上使用 `--debug`。该选项会增加嵌套 `debug`，其中包含 request、耗时、完整 attempts 以及最终成功或最佳失败的 raw 响应；raw 仍会递归脱敏，常规 Agent 调用不应使用此选项。`providers`、`doctor` 和 `config edit` 保留详细诊断 envelope；所有 envelope 使用 schema version 2。稳定 schema 位于 [schemas](schemas)。
 
 退出码：
 
@@ -248,7 +249,7 @@ CLI 提供 `search`、`extract` 两个能力命令，`providers`、`doctor` 两
 - `1`：运行时/provider/doctor/默认应用启动失败
 - `130`：用户取消
 
-`providers` 会列出每个 Instance 的 Type、能力、Route 启用状态、凭据来源和 base URL 来源。`doctor` 只做本地配置检查，不主动调用远端 API；当已启用 Route 中存在未配置 Instance 时，命令返回 `doctor_failed` 和退出码 `1`。
+`providers` 会列出每个 Instance 的 Type、能力、Route 启用状态、凭据来源和 base URL 来源；`searchRoute` 与 `extractRoute` 是下一次 `auto` 使用的有效顺序。`doctor` 只做本地配置检查，不主动调用远端 API；当已启用 Route 中存在未配置 Instance 时，命令返回 `doctor_failed` 和退出码 `1`。
 
 ## HTTP 与安全边界
 

package/THIRD_PARTY_NOTICES.md

@@ -33,16 +33,31 @@
 
 Pi-specific 的工具注册、UI、Agent 生命周期与协议代码没有进入本项目。
 
+## DeepSeek Harness web-search-deepseek
+
+DeepSeek Search Provider 的 Anthropic-compatible Messages wire shape、结构化结果解析与 citation 映射参考并改写自：
+
+- 项目：`deepseek-harness`
+- 仓库：`https://github.com/deepseek-ai/deepseek-harness.git`
+- 上游路径：`packages/web/web-search-deepseek`
+- 参考提交：`99f6f02fecdb7dff40c3fbc9470f5907c29f74ca`
+- Copyright 2026 DeepSeek
+- 许可证：MIT（适用的许可文本与上文所列 MIT 文本相同）
+
+动态 Settings、Credential Service、Session event、LLM seam 和 Agent 集成代码没有进入本项目。
+
 ## npm 依赖
 
 发行包直接使用以下开源组件：
 
 - `@mozilla/readability`：Apache-2.0
 - `commander`：MIT
+- `jsonc-parser`：MIT
 - `linkedom`：ISC
 - `open`：MIT
 - `turndown`：MIT
 - `typebox`：MIT
 - `undici`：MIT
+- `write-file-atomic`：ISC
 
 开发依赖包括 Biome、tsx、TypeScript 及对应类型包。各组件的完整许可证和版权声明以随 npm 包发布的许可证文件及其上游仓库为准。本文件不替代任何第三方许可证。

package/dist/cli-output.js

@@ -0,0 +1,18 @@
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+export function formatExtractMarkdown(envelope) {
+    const { document } = envelope.data;
+    const lines = [
+        "---",
+        `provider: ${yamlScalar(envelope.provider)}`,
+        `url: ${yamlScalar(document.sourceUrl)}`,
+    ];
+    const title = document.title.trim();
+    if (title)
+        lines.push(`title: ${yamlScalar(title)}`);
+    lines.push("---", "", "");
+    const content = document.content;
+    return `${lines.join("\n")}${content.endsWith("\n") ? content : `${content}\n`}`;
+}
+//# sourceMappingURL=cli-output.js.map

package/dist/cli-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-output.js","sourceRoot":"","sources":["../src/cli-output.ts"],"names":[],"mappings":"AAIA,SAAS,UAAU,CAAC,KAAa;IAChC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,qBAAqB,CACpC,QAAgC;IAEhC,MAAM,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG;QACb,KAAK;QACL,aAAa,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAC5C,QAAQ,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE;KACxC,CAAC;IACF,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC1B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,EAAE,CAAC;AAClF,CAAC"}

package/dist/cli.js

@@ -2,8 +2,10 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { Command, CommanderError, InvalidArgumentError, Option, } from "commander";
+import { formatExtractMarkdown } from "./cli-output.js";
 import { loadConfig } from "./config/config.js";
 import { executeConfigEdit } from "./config/edit.js";
+import { createProviderOrderWriter } from "./config/provider-order.js";
 import { executeDoctor, executeProviders } from "./core/diagnostics.js";
 import { asWebAccessError, WebAccessError } from "./core/errors.js";
 import { errorEnvelope, executeExtract, executeSearch } from "./core/router.js";
@@ -48,6 +50,32 @@ function exitCode(envelope) {
 function writeEnvelope(envelope, pretty) {
     process.stdout.write(`${JSON.stringify(envelope, null, pretty ? 2 : undefined)}\n`);
 }
+function writeOutput(envelope, mode, pretty) {
+    if (mode === "markdown" && isExtractSuccessEnvelope(envelope)) {
+        process.stdout.write(formatExtractMarkdown(envelope));
+        return;
+    }
+    writeEnvelope(envelope, pretty);
+}
+function isExtractSuccessEnvelope(envelope) {
+    return (envelope.ok &&
+        "provider" in envelope &&
+        typeof envelope.provider === "string" &&
+        "data" in envelope &&
+        typeof envelope.data === "object" &&
+        envelope.data !== null &&
+        "document" in envelope.data &&
+        typeof envelope.data.document === "object" &&
+        envelope.data.document !== null &&
+        "sourceUrl" in envelope.data.document &&
+        typeof envelope.data.document.sourceUrl === "string" &&
+        "title" in envelope.data.document &&
+        typeof envelope.data.document.title === "string" &&
+        "content" in envelope.data.document &&
+        typeof envelope.data.document.content === "string" &&
+        "contentType" in envelope.data.document &&
+        envelope.data.document.contentType === "text/markdown");
+}
 export function createProgram(run, dependencies = {}) {
     const program = new Command();
     const runConfigEdit = dependencies.executeConfigEdit ?? executeConfigEdit;
@@ -56,7 +84,7 @@ export function createProgram(run, dependencies = {}) {
         .description("Agent-neutral 的网页搜索与内容提取 CLI")
         .version(VERSION)
         .option("--config <path>", "指定 JSON 配置文件")
-        .option("--pretty", "格式化 JSON 输出", false)
+        .option("--pretty", "格式化 JSON 输出；extract 同时选择 JSON 模式", false)
         .showSuggestionAfterError();
     program.configureOutput({ writeErr: () => { }, outputError: () => { } });
     program.exitOverride();
@@ -74,6 +102,7 @@ export function createProgram(run, dependencies = {}) {
         .option("--include-domain <domain>", "仅包含域名，可重复", collect, [])
         .option("--exclude-domain <domain>", "排除域名，可重复", collect, [])
         .option("--timeout <milliseconds>", "总超时毫秒数", integer)
+        .option("--debug", "输出完整路由和脱敏原始响应", false)
         .action((query, options) => {
         run(async () => {
             const globals = program.opts();
@@ -94,18 +123,23 @@ export function createProgram(run, dependencies = {}) {
             return executeSearch(request, {
                 loaded,
                 signal: processSignal.signal,
+                debug: options.debug,
+                persistProviderOrder: createProviderOrderWriter(loaded),
             });
         });
     });
     program
         .command("extract")
-        .description("提取网页正文并转换为 Markdown")
+        .description("提取网页正文并转换为 Markdown（--json/--pretty/--debug 输出 JSON）")
         .argument("<url>", "HTTP(S) URL")
         .option("-p, --provider <id>", "provider instance id，或 auto", "auto")
         .option("--timeout <milliseconds>", "总超时毫秒数", integer)
+        .option("--json", "输出 JSON envelope", false)
+        .option("--debug", "输出完整路由和脱敏原始响应", false)
         .action((url, options) => {
+        const globals = program.opts();
+        const outputMode = options.json || options.debug || globals.pretty ? "json" : "markdown";
         run(async () => {
-            const globals = program.opts();
             const loaded = loadConfig(globals.config);
             const request = {
                 url: httpUrl(url),
@@ -115,8 +149,10 @@ export function createProgram(run, dependencies = {}) {
             return executeExtract(request, {
                 loaded,
                 signal: processSignal.signal,
+                debug: options.debug,
+                persistProviderOrder: createProviderOrderWriter(loaded),
             });
-        });
+        }, outputMode);
     });
     program
         .command("providers")
@@ -148,7 +184,9 @@ const processSignal = new AbortController();
 process.once("SIGINT", () => processSignal.abort());
 async function main() {
     let pending;
-    const program = createProgram((task) => {
+    let pendingOutputMode = "json";
+    const program = createProgram((task, mode = "json") => {
+        pendingOutputMode = mode;
         pending = Promise.resolve().then(task);
     });
     if (process.argv.length <= 2) {
@@ -162,7 +200,7 @@ async function main() {
         if (!pending)
             throw new WebAccessError("invalid_input", "必须指定命令");
         const envelope = await pending;
-        writeEnvelope(envelope, !!program.opts().pretty);
+        writeOutput(envelope, pendingOutputMode, !!program.opts().pretty);
         process.exitCode = exitCode(envelope);
     }
     catch (caught) {