smart-search-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smart Search CLI

Use the local

smart-search

command as the default execution layer for web research. The skill decides routing; the CLI performs the work; JSON or saved files provide evidence.

将本地

smart-search

命令作为网页研究的默认执行层。由Skill决定路由；CLI执行具体操作；JSON或保存的文件提供证据。

Default workflow

默认工作流程

Run
```
smart-search doctor --format json
```
when configuration or availability is uncertain.
If
```
doctor
```
reports missing configuration, use
```
smart-search setup
```
or
```
smart-search config set KEY VALUE
```
when the user provides keys. Do not ask users to edit global environment variables by default.
If
```
doctor
```
returns
```
ok: true
```
, use only
```
smart-search
```
CLI subcommands for web research. Do not call Codex native web search in the same task.
Use
```
smart-search smoke --mock --format json
```
after CLI/provider architecture changes. Use
```
--live
```
only when real keys are available and the user expects live checks.
Use
```
smart-search search
```
for realtime, broad, community, or multi-source synthesis.
Use
```
smart-search exa-search
```
for official documentation, API references, papers, and low-noise source discovery.
Use
```
smart-search context7-library
```
/
```
context7-docs
```
only for library, SDK, API, framework, or documentation intent.
Use
```
smart-search zhipu-search
```
for Chinese, domestic, current, or domain-filtered web source discovery.
Use
```
smart-search anysearch-*
```
only for experimental AnySearch acceptance and vertical-domain boundary tests; do not treat it as the default web-search or fetch fallback.
Use
```
smart-search exa-similar
```
when the user gives a representative URL and wants related pages or neighboring sources.
Use
```
smart-search fetch
```
when the user gives a URL or a claim depends on page content.
Use
```
smart-search map
```
when a documentation site or domain structure matters.

Use

smart-search model current

only to inspect explicit provider models. To change models, use

smart-search config set XAI_MODEL ...

smart-search config set OPENAI_COMPATIBLE_MODEL ...

For current-news, policy, finance, health, or other high-risk facts, do not answer from broad
```
search.content
```
alone. Find reliable URLs with
```
exa-search
```
,
```
zhipu-search
```
, or source-focused
```
search
```
, then
```
fetch
```
key pages and summarize only what the fetched text supports.
Preserve command lines and source URLs in your answer. Prefer citing fetched pages or
```
primary_sources
```
; treat
```
extra_sources
```
as follow-up candidates, not verified evidence for generated claims.

当配置或可用性不确定时，运行
```
smart-search doctor --format json
```
。
如果
```
doctor
```
报告缺少配置，在用户提供密钥时使用
```
smart-search setup
```
或
```
smart-search config set KEY VALUE
```
。默认情况下不要要求用户编辑全局环境变量。
如果
```
doctor
```
返回
```
ok: true
```
，仅使用
```
smart-search
```
CLI子命令进行网页研究。同一任务中不要调用Codex原生网页搜索。
在CLI/提供商架构变更后，使用
```
smart-search smoke --mock --format json
```
。仅当有真实密钥且用户需要实时检查时才使用
```
--live
```
。
使用
```
smart-search search
```
进行实时、广泛、社区化或多来源的信息综合。
使用
```
smart-search exa-search
```
查找官方文档、API参考、论文和低噪音来源。
仅当意图是查找库、SDK、API、框架或文档时，使用
```
smart-search context7-library
```
/
```
context7-docs
```
。
使用
```
smart-search zhipu-search
```
查找中文、国内、实时或域名过滤的网页来源。
仅在实验性AnySearch验收和垂直领域边界测试时使用
```
smart-search anysearch-*
```
；不要将其作为默认网页搜索或抓取的备选方案。
当用户提供代表性URL并需要相关页面或邻近来源时，使用
```
smart-search exa-similar
```
。
当用户提供URL或某个声明依赖于页面内容时，使用
```
smart-search fetch
```
。
当文档站点或域名结构很重要时，使用
```
smart-search map
```
。

仅使用

smart-search model current

检查明确的提供商模型。要更改模型，使用

smart-search config set XAI_MODEL ...

或

smart-search config set OPENAI_COMPATIBLE_MODEL ...

。

对于时事新闻、政策、金融、健康或其他高风险事实，不要仅依靠宽泛的
```
search.content
```
作答。使用
```
exa-search
```
、
```
zhipu-search
```
或聚焦来源的
```
search
```
找到可靠URL，然后
```
fetch
```
关键页面，仅总结抓取文本支持的内容。
在回答中保留命令行和来源URL。优先引用抓取的页面或
```
primary_sources
```
；将
```
extra_sources
```
视为后续候选，而非生成声明的已验证证据。

Deep Research Mode

深度研究模式

Use Deep Research Mode when the user asks for

深度搜索

深度调研

深入搜索

deep search

deep research

, multi-source verification, cross-checking, serious review, or selection/comparison research. This is a capability-based orchestration workflow: the AI agent calls

smart-search deep "question" --format json

to get an offline plan, then composes existing

smart-search

CLI building blocks, the CLI executes those later commands, and JSON/Markdown files provide reproducible evidence.

smart-search deep

is a public planner entrypoint, not an executor; it does not call providers, run

doctor

, or fetch pages by default. It does not change default

smart-search search

, and it does not depend on an MCP session.

Do not select a fixed topic recipe. Market, product, technical docs, news, policy, claim-checking, and URL-first prompts are examples of user language, not schema modes. Decide from intent dimensions and capability needs.

Before running deep research commands, run

smart-search deep "question" --format json

and use the returned

research_plan

as your planning artifact. Use this shape:

json

{
  "mode": "deep_research",
  "query_mode": "deep",
  "question": "user question",
  "trigger_source": "explicit_cli",
  "difficulty": "standard|high",
  "intent_signals": {
    "recency_requirement": "none|recent|current",
    "docs_api_intent": false,
    "locale_domain_scope": "global|china|known_domains|mixed",
    "known_url": false,
    "source_authority_need": "normal|high",
    "claim_risk": "low|medium|high",
    "cross_validation_need": "normal|high",
    "breadth_depth_budget": "quick|standard|deep"
  },
  "decomposition": [
    {
      "id": "sq1",
      "question": "subquestion",
      "reason": "why this subquestion is needed",
      "required_capabilities": ["broad_discovery"]
    }
  ],
  "capability_plan": [
    {
      "capability": "broad_discovery",
      "tools": ["search"],
      "reason": "Find the initial answer shape and candidate sources."
    }
  ],
  "preflight": {
    "tool": "doctor",
    "command": "smart-search doctor --format json",
    "when": "configuration or availability is uncertain"
  },
  "evidence_policy": "fetch_before_claim",
  "steps": [
    {
      "id": "s1",
      "subquestion_id": "sq1",
      "tool": "search",
      "purpose": "broad discovery",
      "command": "smart-search search \"query\" --validation balanced --extra-sources 1 --format json --output C:\\tmp\\smart-search-evidence\\YYYYMMDD-HHMM-topic\\01-search.json",
      "output_path": "C:\\tmp\\smart-search-evidence\\YYYYMMDD-HHMM-topic\\01-search.json"
    }
  ],
  "gap_check": {
    "required": true,
    "rule": "fetch missing evidence for key claims or downgrade them to unverified candidates"
  },
  "final_answer_policy": "cite fetched evidence, list unverified candidates, and include key commands",
  "usage_boundary": {
    "search": "smart-search search runs live fast/broad search immediately.",
    "deep": "smart-search deep is an offline planner; it does not execute provider calls or fetch pages.",
    "execution": "An AI agent or user executes the listed steps with existing CLI commands, then performs gap_check."
  }
}

Allowed

steps[].tool

values are

search

exa-search

exa-similar

zhipu-search

context7-library

context7-docs

fetch

, and

map

. Each step must include

id

subquestion_id

purpose

command

, and

output_path

doctor

is preflight and must not appear in

steps[]

. Simple plans may have one subquestion; complex plans should use 2-6 subquestions unless the user explicitly asks for exhaustive coverage.

Capability boundaries:

```
search
```
: broad discovery and synthesis through
```
main_search
```
; inspect
```
routing_decision
```
,
```
provider_attempts
```
,
```
fallback_used
```
, and
```
source_warning
```
. Do not treat broad answers as proof for high-risk claims.
```
exa-search
```
: low-noise discovery for official docs, APIs, papers, product pages, known domains, trusted media, and recency-filtered source search.
```
exa-similar
```
: adjacent-source discovery when a known reliable URL is available.
```
zhipu-search
```
: Chinese, domestic, current, or domain-filtered source discovery.
```
context7-library
```
/
```
context7-docs
```
: library, SDK, API, framework, and documentation intent only.
```
fetch
```
: page-content evidence. Use it before claim-level conclusions.
```
map
```
: site structure exploration before many fetches from one site; not claim evidence by itself.

Default Deep Research orchestration:

Run
```
smart-search doctor --format json
```
as preflight when configuration is uncertain.

Call

smart-search deep "question" --format json

to create an offline

research_plan

Inspect
```
intent_signals
```
,
```
decomposition
```
, and
```
capability_plan
```
; do not choose fixed topic recipe ids.
Execute planned
```
search --validation balanced --extra-sources 1..3
```
steps for broad discovery and read routing metadata.
Execute planned
```
exa-search
```
,
```
exa-similar
```
,
```
zhipu-search
```
,
```
context7-library
```
,
```
context7-docs
```
, or
```
map
```
only when their capability boundary matches the intent.
Use
```
fetch
```
on key URLs before making claim-level statements.
Run
```
gap_check
```
: if an important claim lacks fetched evidence, fetch another source or mark the claim/source as unverified.

Default evidence policy is

fetch_before_claim

: key claims in the final answer must be supported by fetched page text. Treat

primary_sources

and

extra_sources

as discovery candidates until the relevant URL has been fetched. The final answer should include fetched evidence, unverified candidate sources, and key commands used.

Deep Research smoke matrix for workflow maintenance is mock-full plus live-limited. Mock-full coverage should include trigger phrases, normal search requests that should not trigger Deep Research, required

research_plan

fields, allowed tool whitelist,

fetch_before_claim

, evidence output paths, capability boundaries,

intent_signals

capability_plan

gap_check

, simple current prompts such as

深度搜索一下最近的比特币行情

, docs/API prompts, claim-verification prompts, user-provided URL fetch-first flows, missing-provider failure guidance, and the rule that fixed topic recipe ids are not required schema. Live-limited coverage should run

doctor

, one broad

search

, one

exa-search

, and one

fetch

only when real keys are available and the user expects live checks.

Standard user-facing Deep Research tests:

powershell

smart-search deep "深度搜索一下最近的比特币行情" --format json
smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --budget deep --format json
smart-search deep "帮我核验这个说法是真是假：某某工具已经完全替代 Tavily 做 AI 搜索了" --format json
smart-search deep "https://example.com/source" --format json

当用户要求

深度搜索

、

深度调研

、

深入搜索

、

deep search

、

deep research

、多来源验证、交叉核对、严谨审查或选型对比研究时，使用深度研究模式。这是基于能力的编排工作流：AI Agent调用

smart-search deep "question" --format json

获取离线计划，然后组合现有

smart-search

CLI构建块，CLI执行后续命令，JSON/Markdown文件提供可复现的证据。

smart-search deep

是公共规划入口，而非执行器；默认情况下它不会调用提供商、运行

doctor

或抓取页面。它不会更改默认的

smart-search search

，也不依赖MCP会话。

不要选择固定的主题模板。市场、产品、技术文档、新闻、政策、声明核查和以URL优先的提示是用户语言示例，而非模式类型。根据意图维度和能力需求做出决策。

运行深度研究命令前，先执行

smart-search deep "question" --format json

，并将返回的

research_plan

作为规划依据。使用以下格式：

json

{
  "mode": "deep_research",
  "query_mode": "deep",
  "question": "user question",
  "trigger_source": "explicit_cli",
  "difficulty": "standard|high",
  "intent_signals": {
    "recency_requirement": "none|recent|current",
    "docs_api_intent": false,
    "locale_domain_scope": "global|china|known_domains|mixed",
    "known_url": false,
    "source_authority_need": "normal|high",
    "claim_risk": "low|medium|high",
    "cross_validation_need": "normal|high",
    "breadth_depth_budget": "quick|standard|deep"
  },
  "decomposition": [
    {
      "id": "sq1",
      "question": "subquestion",
      "reason": "why this subquestion is needed",
      "required_capabilities": ["broad_discovery"]
    }
  ],
  "capability_plan": [
    {
      "capability": "broad_discovery",
      "tools": ["search"],
      "reason": "Find the initial answer shape and candidate sources."
    }
  ],
  "preflight": {
    "tool": "doctor",
    "command": "smart-search doctor --format json",
    "when": "configuration or availability is uncertain"
  },
  "evidence_policy": "fetch_before_claim",
  "steps": [
    {
      "id": "s1",
      "subquestion_id": "sq1",
      "tool": "search",
      "purpose": "broad discovery",
      "command": "smart-search search \"query\" --validation balanced --extra-sources 1 --format json --output C:\\tmp\\smart-search-evidence\\YYYYMMDD-HHMM-topic\\01-search.json",
      "output_path": "C:\\tmp\\smart-search-evidence\\YYYYMMDD-HHMM-topic\\01-search.json"
    }
  ],
  "gap_check": {
    "required": true,
    "rule": "fetch missing evidence for key claims or downgrade them to unverified candidates"
  },
  "final_answer_policy": "cite fetched evidence, list unverified candidates, and include key commands",
  "usage_boundary": {
    "search": "smart-search search runs live fast/broad search immediately.",
    "deep": "smart-search deep is an offline planner; it does not execute provider calls or fetch pages.",
    "execution": "An AI agent or user executes the listed steps with existing CLI commands, then performs gap_check."
  }
}

steps[].tool

允许的值为

search

、

exa-search

、

exa-similar

、

zhipu-search

、

context7-library

、

context7-docs

、

fetch

和

map

。每个步骤必须包含

id

、

subquestion_id

、

purpose

、

command

和

output_path

。

doctor

属于预检查，不得出现在

steps[]

中。简单计划可包含一个子问题；复杂计划应使用2-6个子问题，除非用户明确要求全面覆盖。

能力边界：

```
search
```
：通过
```
main_search
```
进行广泛发现和综合；检查
```
routing_decision
```
、
```
provider_attempts
```
、
```
fallback_used
```
和
```
source_warning
```
。不要将宽泛的回答视为高风险声明的证据。
```
exa-search
```
：用于查找官方文档、API、论文、产品页面、已知域名、可信媒体和按时效性过滤的来源的低噪音发现工具。
```
exa-similar
```
：当有已知可靠URL时，用于发现相关来源。
```
zhipu-search
```
：用于查找中文、国内、实时或域名过滤的网页来源。
```
context7-library
```
/
```
context7-docs
```
：仅用于查找库、SDK、API、框架和文档的场景。
```
fetch
```
：页面内容证据。在得出声明级结论前使用。
```
map
```
：从单个站点进行多次抓取前探索站点结构；本身不构成声明证据。

默认深度研究编排：

当配置不确定时，运行
```
smart-search doctor --format json
```
作为预检查。

调用

smart-search deep "question" --format json

创建离线

research_plan

。

检查
```
intent_signals
```
、
```
decomposition
```
和
```
capability_plan
```
；不要选择固定的主题模板ID。
执行规划好的
```
search --validation balanced --extra-sources 1..3
```
步骤进行广泛发现，并读取路由元数据。
仅当能力边界与意图匹配时，执行规划好的
```
exa-search
```
、
```
exa-similar
```
、
```
zhipu-search
```
、
```
context7-library
```
、
```
context7-docs
```
或
```
map
```
。
在做出声明级陈述前，对关键URL使用
```
fetch
```
。
执行
```
gap_check
```
：如果重要声明缺少抓取的证据，抓取另一个来源或将声明/来源标记为未验证。

默认证据策略为

fetch_before_claim

：最终答案中的关键声明必须有抓取的页面文本支持。在相关URL被抓取前，将

primary_sources

和

extra_sources

视为发现候选。最终答案应包含抓取的证据、未验证的候选来源以及使用的关键命令。

工作流维护的深度研究冒烟测试矩阵为全模拟加有限实时。全模拟覆盖应包括触发短语、不应触发深度研究的普通搜索请求、必填

research_plan

字段、允许的工具白名单、

fetch_before_claim

、证据输出路径、能力边界、

intent_signals

、

capability_plan

、

gap_check

、简单实时提示（如

深度搜索一下最近的比特币行情

）、文档/API提示、声明验证提示、用户提供URL优先抓取流程、提供商缺失故障指导，以及不需要固定主题模板ID的规则。有限实时覆盖应在有真实密钥且用户需要实时检查时，仅运行

doctor

、一次宽泛

search

、一次

exa-search

和一次

fetch

。

面向用户的标准深度研究测试：

powershell

smart-search deep "深度搜索一下最近的比特币行情" --format json
smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --budget deep --format json
smart-search deep "帮我核验这个说法是真是假：某某工具已经完全替代 Tavily 做 AI 搜索了" --format json
smart-search deep "https://example.com/source" --format json

Provider Routing

提供商路由

```
search
```
builds
```
main_search
```
from configured peer providers:
```
XAI_API_KEY
```
for xAI Responses and
```
OPENAI_COMPATIBLE_API_URL
```
+
```
OPENAI_COMPATIBLE_API_KEY
```
for OpenAI-compatible Chat Completions.
Official xAI uses the Responses API
```
/responses
```
route through
```
XAI_*
```
. Compatible relays/gateways use Chat Completions
```
/chat/completions
```
through
```
OPENAI_COMPATIBLE_*
```
.
```
OPENAI_COMPATIBLE_STREAM=true
```
or
```
search --stream
```
sets
```
stream=true
```
only for OpenAI-compatible
```
search
```
and provider-side
```
fetch
```
; it is a relay compatibility switch and does not affect xAI Responses, URL description, or source ranking.

Legacy

SMART_SEARCH_API_URL

SMART_SEARCH_API_KEY

SMART_SEARCH_API_MODE

SMART_SEARCH_MODEL

, and

SMART_SEARCH_XAI_TOOLS

are unsupported config keys.

xAI Responses mode may use only
```
XAI_TOOLS=web_search,x_search
```
and a subset of those tools.
Chat Completions mode must not send xAI
```
web_search
```
/
```
x_search
```
tools or legacy
```
search_parameters
```
; xAI Chat Completions Live Search is deprecated.
The standard minimum profile requires one configured provider in each of
```
main_search
```
,
```
docs_search
```
, and fetch capability. Missing required capabilities should be treated as a hard configuration failure.
AnySearch is reported only as optional experimental
```
vertical_search
```
; it is not part of the
```
web_search
```
fallback and is not required by the
```
standard
```
minimum profile.
```
search
```
exposes
```
--validation fast|balanced|strict
```
,
```
--fallback auto|off
```
, and
```
--providers auto|CSV
```
. Default validation is
```
balanced
```
; fallback only happens within the same capability.
xAI Responses is the default main answer route for Grok/xAI. In
```
fallback=auto
```
, a failed xAI Responses main route can fall back to OpenAI-compatible only when the OpenAI-compatible provider is separately configured.
Docs routing uses Exa first, then Context7 only for docs/API/SDK/library/framework intent.
Zhipu is a general web-search reinforcement and same-capability fallback for Chinese, domestic, current, or domain-filtered source discovery.
```
search
```
calls Tavily and/or Firecrawl only when
```
--extra-sources N
```
is greater than 0.
With both Tavily and Firecrawl configured,
```
search --extra-sources N
```
splits extra sources between them, with Tavily receiving about 60% and Firecrawl the rest.
Search JSON separates
```
primary_sources
```
,
```
extra_sources
```
, and backward-compatible merged
```
sources
```
.
```
primary_sources
```
are extracted from the primary model answer.
```
extra_sources
```
are parallel Tavily / Firecrawl candidates and are not automatically used to verify
```
content
```
.
```
fetch
```
tries Tavily first and uses Firecrawl only as a fallback when Tavily returns no content.
```
map
```
currently uses Tavily only.
```
exa-search
```
and
```
exa-similar
```
use Exa only.
```
context7-library
```
and
```
context7-docs
```
use Context7 only.
```
anysearch-domains
```
,
```
anysearch-search
```
,
```
anysearch-extract
```
, and
```
anysearch-batch
```
use AnySearch only. Treat results as acceptance evidence until the target vertical domain is reviewed.
```
zhipu-search
```
uses Zhipu only.
Zhipu support currently corresponds to the official Zhipu Web Search API route, using
```
ZHIPU_API_URL
```
plus
```
ZHIPU_SEARCH_ENGINE
```
; it is not Zhipu Chat Completions
```
tools=[web_search]
```
, not Search Agent, and not the MCP Server.
```
ZHIPU_SEARCH_ENGINE
```
defaults to
```
search_std
```
. Official Web Search API service values include
```
search_std
```
,
```
search_pro
```
,
```
search_pro_sogou
```
, and
```
search_pro_quark
```
; keep custom values possible because official services may change.
```
TAVILY_API_URL
```
only affects Tavily REST calls and does not proxy Zhipu. Zhipu defaults to
```
https://open.bigmodel.cn/api
```
unless
```
ZHIPU_API_URL
```
is set.
```
doctor
```
tests configured main-search providers, Exa, Tavily, Zhipu, and Context7 connectivity. Firecrawl status currently means the key is configured, not that a live Firecrawl request succeeded.

```
search
```
通过配置的对等提供商构建
```
main_search
```
：使用
```
XAI_API_KEY
```
调用xAI Responses，使用
```
OPENAI_COMPATIBLE_API_URL
```
+
```
OPENAI_COMPATIBLE_API_KEY
```
调用兼容OpenAI的Chat Completions。
官方xAI通过
```
XAI_*
```
使用Responses API的
```
/responses
```
路由。兼容中继/网关通过
```
OPENAI_COMPATIBLE_*
```
使用Chat Completions的
```
/chat/completions
```
路由。
```
OPENAI_COMPATIBLE_STREAM=true
```
或
```
search --stream
```
仅对兼容OpenAI的
```
search
```
和提供商端
```
fetch
```
设置
```
stream=true
```
；这是中继兼容性开关，不影响xAI Responses、URL描述或来源排序。

旧版

SMART_SEARCH_API_URL

、

SMART_SEARCH_API_KEY

、

SMART_SEARCH_API_MODE

、

SMART_SEARCH_MODEL

和

SMART_SEARCH_XAI_TOOLS

为不支持的配置密钥。

xAI Responses模式仅可使用
```
XAI_TOOLS=web_search,x_search
```
及其子集工具。
Chat Completions模式不得发送xAI的
```
web_search
```
/
```
x_search
```
工具或旧版
```
search_parameters
```
；xAI Chat Completions实时搜索已弃用。
标准最小配置文件要求
```
main_search
```
、
```
docs_search
```
和抓取能力各配置一个提供商。缺少所需能力应视为严重配置故障。
AnySearch仅作为可选实验性
```
vertical_search
```
报告；它不属于
```
web_search
```
备选方案，也不是
```
standard
```
最小配置文件的必需项。
```
search
```
支持
```
--validation fast|balanced|strict
```
、
```
--fallback auto|off
```
和
```
--providers auto|CSV
```
。默认验证模式为
```
balanced
```
；仅在同一能力范围内触发备选方案。
xAI Responses是Grok/xAI的默认主要回答路由。在
```
fallback=auto
```
时，xAI Responses主路由失败后仅当单独配置了兼容OpenAI的提供商时，才会回退到该提供商。
文档路由优先使用Exa，仅当意图是查找文档/API/SDK/库/框架时才回退到Context7。
Zhipu是中文、国内、实时或域名过滤来源发现的通用网页搜索增强工具和同能力备选方案。
仅当
```
--extra-sources N
```
大于0时，
```
search
```
才会调用Tavily和/或Firecrawl。
当同时配置了Tavily和Firecrawl时，
```
search --extra-sources N
```
会在两者之间分配额外来源，Tavily约占60%，Firecrawl占剩余部分。
搜索JSON将
```
primary_sources
```
、
```
extra_sources
```
和向后兼容的合并
```
sources
```
分开。
```
primary_sources
```
从主模型回答中提取。
```
extra_sources
```
是并行的Tavily / Firecrawl候选，不会自动用于验证
```
content
```
。
```
fetch
```
优先尝试Tavily，仅当Tavily未返回内容时才使用Firecrawl作为备选。
```
map
```
目前仅使用Tavily。
```
exa-search
```
和
```
exa-similar
```
仅使用Exa。
```
context7-library
```
和
```
context7-docs
```
仅使用Context7。
```
anysearch-domains
```
、
```
anysearch-search
```
、
```
anysearch-extract
```
和
```
anysearch-batch
```
仅使用AnySearch。在目标垂直领域审核完成前，将结果视为验收证据。
```
zhipu-search
```
仅使用Zhipu。
Zhipu支持目前对应官方Zhipu网页搜索API路由，使用
```
ZHIPU_API_URL
```
加
```
ZHIPU_SEARCH_ENGINE
```
；它不是Zhipu Chat Completions的
```
tools=[web_search]
```
，不是搜索Agent，也不是MCP Server。
```
ZHIPU_SEARCH_ENGINE
```
默认为
```
search_std
```
。官方网页搜索API服务值包括
```
search_std
```
、
```
search_pro
```
、
```
search_pro_sogou
```
和
```
search_pro_quark
```
；允许自定义值，因为官方服务可能变更。
```
TAVILY_API_URL
```
仅影响Tavily REST调用，不代理Zhipu。Zhipu默认使用
```
https://open.bigmodel.cn/api
```
，除非设置了
```
ZHIPU_API_URL
```
。
```
doctor
```
测试已配置的主搜索提供商、Exa、Tavily、Zhipu和Context7的连通性。Firecrawl状态目前仅表示已配置密钥，不代表实时Firecrawl请求成功。

Evidence Files

证据文件

For multi-source research, use

--output

to save evidence under

C:\tmp\smart-search-evidence\

with a descriptive timestamped filename. Stdout should still contain the full JSON result unless markdown or content output was explicitly chosen for human reading.

For claim-level evidence, prefer this order:

Discover candidate URLs with
```
exa-search
```
or source-focused
```
search
```
.
Fetch the exact pages that matter.
Use broad
```
search
```
only as synthesis or discovery, and mark claims as unverified when only
```
extra_sources
```
are available.

Prefer shorter, source-directed commands:

powershell

smart-search exa-search "Reuters Iran Hormuz latest" --num-results 5 --include-highlights --format json --output C:\tmp\smart-search-evidence\iran-hormuz-exa.json
smart-search exa-search "OpenAI Responses API documentation" --include-domains platform.openai.com developers.openai.com --num-results 5 --include-text --format json
smart-search exa-similar "https://example.com/source" --num-results 5 --format json
smart-search fetch "https://example.com/source" --format json --output C:\tmp\smart-search-evidence\source-fetch.json
smart-search search "Iran Hormuz latest military talks" --extra-sources 3 --timeout 90 --format json --output C:\tmp\smart-search-evidence\iran-hormuz-search.json

对于多来源研究，使用

--output

将证据保存到

C:\tmp\smart-search-evidence\

目录下，文件名包含描述性时间戳。除非明确选择markdown或内容输出供人类阅读，否则标准输出仍应包含完整的JSON结果。

对于声明级证据，优先遵循以下顺序：

使用
```
exa-search
```
或聚焦来源的
```
search
```
发现候选URL。
抓取关键页面。
仅将宽泛的
```
search
```
用于综合或发现，当仅有的来源是
```
extra_sources
```
时，将声明标记为未验证。

优先使用更简短、指向来源的命令：

powershell

smart-search exa-search "Reuters Iran Hormuz latest" --num-results 5 --include-highlights --format json --output C:\tmp\smart-search-evidence\iran-hormuz-exa.json
smart-search exa-search "OpenAI Responses API documentation" --include-domains platform.openai.com developers.openai.com --num-results 5 --include-text --format json
smart-search exa-similar "https://example.com/source" --num-results 5 --format json
smart-search fetch "https://example.com/source" --format json --output C:\tmp\smart-search-evidence\source-fetch.json
smart-search search "Iran Hormuz latest military talks" --extra-sources 3 --timeout 90 --format json --output C:\tmp\smart-search-evidence\iran-hormuz-search.json

Local wrapper contract

本地包装器约定

Expect
```
smart-search
```
to resolve from the user's PATH.
This bundled skill is maintained with the
```
smartsearch
```
repository.
Prefer the CLI's local config file managed by
```
smart-search setup
```
/
```
smart-search config
```
.
Environment variables remain supported for CI and advanced users, and override the local config file.
Do not ask users to set Windows global API-key environment variables by default.
If keys are changed with
```
smart-search config set
```
, rerun the CLI; no Codex restart is needed.
If PATH is changed, a new terminal or Codex restart may be needed.

On Windows, the default local config file is

%LOCALAPPDATA%\smart-search\config.json

. Linux/macOS default to

~/.config/smart-search/config.json

In sandboxed runtimes (Codex CLI, containers, CI) where the default config directory is not writable or must be pinned, set
```
SMART_SEARCH_CONFIG_DIR
```
to an absolute writable path. The CLI uses it for both config and relative logs and skips default-directory selection.
Earlier Windows source defaults used
```
~\.config\smart-search\config.json
```
, while some installs were already pinned to
```
%LOCALAPPDATA%\smart-search
```
through
```
SMART_SEARCH_CONFIG_DIR
```
. If the new default file is missing but the old file exists,
```
doctor
```
reports
```
legacy_windows_home
```
as the active source so upgrades do not silently lose configuration. It also reports the override value and whether it matches the current default.
Use
```
smart-search doctor --format json
```
for agent/script parsing and
```
smart-search doctor --format markdown
```
when a human wants a detailed diagnostic report.

smart-search doctor --format json

returns

ok: false

, follow the

error

field's guidance (

smart-search setup

smart-search config set KEY VALUE

); do not silently fall back to native web search.

Interactive
```
smart-search setup
```
is a language-selecting grouped wizard with arrow-key / Space / Enter provider selection. It guides users through required
```
main_search
```
,
```
docs_search
```
, and fetch capability, then optional
```
web_search
```
reinforcement.
The setup wizard prints beginner filling examples for official-service and relay/pooled-endpoint minimum profiles. Keep that guidance on stderr so stdout remains parseable JSON/Markdown/content output.
Use
```
smart-search setup --lang en
```
for an English wizard and
```
smart-search setup --advanced
```
only when low-level config keys must be shown one by one.

Use

smart-search setup --non-interactive --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_std"

to save Zhipu Web Search API endpoint and search service without prompts.

Use
```
smart-search setup --non-interactive --openai-compatible-stream true
```
only when an OpenAI-compatible relay benefits from SSE streaming for long requests. Default remains false.

Use

smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "key"

only for experimental AnySearch acceptance; do not add it to the normal minimum-profile setup.

Interactive setup asks for Zhipu API key, API URL, and search service when optional
```
web_search
```
reinforcement selects Zhipu.
Use
```
TAVILY_API_URL=https://<host>/api/tavily
```
for Tavily Hikari / pooled endpoints. Root host and
```
/mcp
```
inputs are normalized by setup;
```
/mcp
```
itself is not the REST base Smart Search should call.
```
TAVILY_TIMEOUT_SECONDS
```
controls the Tavily
```
doctor
```
connectivity timeout and defaults to
```
30
```
. Raise it for slower pooled/community Tavily endpoints before judging the provider unhealthy.
Use
```
FIRECRAWL_API_URL
```
only for a Firecrawl-compatible REST base. Official default is
```
https://api.firecrawl.dev/v2
```
.

假设
```
smart-search
```
可从用户的PATH中找到。
此捆绑Skill与
```
smartsearch
```
代码库一同维护。
优先使用由
```
smart-search setup
```
/
```
smart-search config
```
管理的CLI本地配置文件。
环境变量仍支持用于CI和高级用户，且优先级高于本地配置文件。
默认情况下不要要求用户设置Windows全局API密钥环境变量。
如果使用
```
smart-search config set
```
更改了密钥，重新运行CLI即可；无需重启Codex。
如果PATH发生变更，可能需要重启终端或Codex。
在Windows上，默认本地配置文件为
```
%LOCALAPPDATA%\smart-search\config.json
```
。Linux/macOS默认路径为
```
~/.config/smart-search/config.json
```
。
在沙箱运行时（Codex CLI、容器、CI），如果默认配置目录不可写或必须固定，设置
```
SMART_SEARCH_CONFIG_DIR
```
为绝对可写路径。CLI将使用该路径存储配置和相对日志，并跳过默认目录选择。
早期Windows源默认使用
```
~\.config\smart-search\config.json
```
，而部分安装已通过
```
SMART_SEARCH_CONFIG_DIR
```
固定到
```
%LOCALAPPDATA%\smart-search
```
。如果新默认文件缺失但旧文件存在，
```
doctor
```
会将
```
legacy_windows_home
```
报告为活动源，以便升级不会静默丢失配置。它还会报告覆盖值以及是否与当前默认匹配。
对于Agent/脚本解析，使用
```
smart-search doctor --format json
```
；当人类需要详细诊断报告时，使用
```
smart-search doctor --format markdown
```
。

如果

smart-search doctor --format json

ok: false

，遵循

error

字段的指导（

smart-search setup

或

smart-search config set KEY VALUE

）；不要静默回退到原生网页搜索。

交互式
```
smart-search setup
```
是支持语言选择的分组向导，使用箭头键/空格/回车键选择提供商。它引导用户完成必需的
```
main_search
```
、
```
docs_search
```
和抓取能力配置，然后是可选的
```
web_search
```
增强配置。
设置向导会打印官方服务和中继/池化端点最小配置文件的入门示例。将这些指导输出到stderr，以便stdout保持可解析的JSON/Markdown/内容输出。
使用
```
smart-search setup --lang en
```
启动英文向导；仅当需要逐个显示低级配置密钥时，使用
```
smart-search setup --advanced
```
。

使用

smart-search setup --non-interactive --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_std"

保存Zhipu网页搜索API端点和搜索服务，无需提示。

仅当兼容OpenAI的中继从SSE流中受益以处理长请求时，使用
```
smart-search setup --non-interactive --openai-compatible-stream true
```
。默认值仍为false。

仅在实验性AnySearch验收时，使用

smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "key"

；不要将其添加到常规最小配置文件设置中。

交互式设置在选择Zhipu作为可选
```
web_search
```
增强时，会要求输入Zhipu API密钥、API URL和搜索服务。
对于Tavily Hikari / 池化端点，使用
```
TAVILY_API_URL=https://<host>/api/tavily
```
。设置会规范化根主机和
```
/mcp
```
输入；
```
/mcp
```
本身不是Smart Search应调用的REST基础路径。
```
TAVILY_TIMEOUT_SECONDS
```
控制Tavily
```
doctor
```
连通性超时，默认值为
```
30
```
。对于较慢的池化/社区Tavily端点，在判定提供商不健康前先提高该值。
仅当使用兼容Firecrawl的REST基础路径时，使用
```
FIRECRAWL_API_URL
```
。官方默认值为
```
https://api.firecrawl.dev/v2
```
。

Command Patterns

命令模式

powershell

smart-search search "query" --extra-sources 5 --timeout 90 --format json --output result.json
smart-search search "query" --stream --format json
smart-search search "query" --platform "Reuters" --model "model-id" --extra-sources 3 --timeout 90 --format json
smart-search search "nba战报" --format content
smart-search search "query" --validation strict --fallback auto --providers auto --format json
smart-search exa-search "query" --num-results 5 --search-type neural --include-text --include-highlights --include-domains docs.example.com developer.mozilla.org --format json
smart-search exa-similar "https://example.com/article" --num-results 5 --format json
smart-search context7-library "react" "hooks" --format json
smart-search context7-docs "/facebook/react" "useEffect cleanup" --format json
smart-search zhipu-search "today China AI news" --count 5 --format json
smart-search anysearch-domains security --format json
smart-search anysearch-search "CVE-2024-3094" --domain security.cve --max-results 3 --format json
smart-search anysearch-extract "https://example.com/source" --format json
smart-search anysearch-batch "AAPL" "RAG papers" --max-results 2 --format json
smart-search fetch "https://example.com" --format markdown --output page.md
smart-search map "https://docs.example.com" --instructions "Find API reference pages" --max-depth 1 --max-breadth 20 --limit 50 --format json
smart-search setup
smart-search setup --lang en
smart-search setup --advanced
smart-search setup --non-interactive --install-skills hermes
smart-search setup --non-interactive --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_std"
smart-search setup --non-interactive --openai-compatible-stream true
smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "key"
smart-search setup --non-interactive --tavily-api-url "https://api.tavily.com" --tavily-key "key"
smart-search --version
smart-search config path --format json
smart-search config list --format json
smart-search config list --format markdown
smart-search config set XAI_API_KEY "key" --format json
smart-search config set XAI_MODEL "grok-4-fast" --format json
smart-search config set XAI_TOOLS "web_search,x_search" --format json
smart-search config set OPENAI_COMPATIBLE_API_URL "https://api.openai.com/v1" --format json
smart-search config set OPENAI_COMPATIBLE_API_KEY "key" --format json
smart-search config set OPENAI_COMPATIBLE_MODEL "model-id" --format json
smart-search config set OPENAI_COMPATIBLE_STREAM "true" --format json
smart-search config set ANYSEARCH_API_URL "https://api.anysearch.com/mcp" --format json
smart-search config set ANYSEARCH_API_KEY "key" --format json
smart-search config set ANYSEARCH_TIMEOUT_SECONDS "30" --format json
smart-search config set EXA_API_KEY "key" --format json
smart-search config set CONTEXT7_API_KEY "key" --format json
smart-search config set ZHIPU_API_KEY "key" --format json
smart-search config set ZHIPU_API_URL "https://open.bigmodel.cn/api" --format json
smart-search config set ZHIPU_SEARCH_ENGINE "search_pro" --format json
smart-search config set TAVILY_API_URL "https://api.tavily.com" --format json
smart-search config set TAVILY_TIMEOUT_SECONDS "45" --format json
smart-search config set FIRECRAWL_API_URL "https://api.firecrawl.dev/v2" --format json
smart-search model current --format json
smart-search doctor --format json
smart-search doctor --format markdown
smart-search regression
smart-search smoke --mock --format json
smart-search smoke --mock --format markdown

Short aliases are supported for interactive use:

powershell

smart-search --v
smart-search s "query" --format json
smart-search s "nba战报" --format content
smart-search f "https://example.com" --format markdown
smart-search exa "OpenAI Responses API documentation" --format json
smart-search z "today China AI news" --format json
smart-search c7 "react" "hooks" --format json
smart-search c7docs "/facebook/react" "useEffect cleanup" --format json
smart-search cfg ls --format json
smart-search d --format markdown
smart-search mdl cur --format json
smart-search sm --format json
smart-search reg

powershell

smart-search search "query" --extra-sources 5 --timeout 90 --format json --output result.json
smart-search search "query" --stream --format json
smart-search search "query" --platform "Reuters" --model "model-id" --extra-sources 3 --timeout 90 --format json
smart-search search "nba战报" --format content
smart-search search "query" --validation strict --fallback auto --providers auto --format json
smart-search exa-search "query" --num-results 5 --search-type neural --include-text --include-highlights --include-domains docs.example.com developer.mozilla.org --format json
smart-search exa-similar "https://example.com/article" --num-results 5 --format json
smart-search context7-library "react" "hooks" --format json
smart-search context7-docs "/facebook/react" "useEffect cleanup" --format json
smart-search zhipu-search "today China AI news" --count 5 --format json
smart-search anysearch-domains security --format json
smart-search anysearch-search "CVE-2024-3094" --domain security.cve --max-results 3 --format json
smart-search anysearch-extract "https://example.com/source" --format json
smart-search anysearch-batch "AAPL" "RAG papers" --max-results 2 --format json
smart-search fetch "https://example.com" --format markdown --output page.md
smart-search map "https://docs.example.com" --instructions "Find API reference pages" --max-depth 1 --max-breadth 20 --limit 50 --format json
smart-search setup
smart-search setup --lang en
smart-search setup --advanced
smart-search setup --non-interactive --install-skills hermes
smart-search setup --non-interactive --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_std"
smart-search setup --non-interactive --openai-compatible-stream true
smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "key"
smart-search setup --non-interactive --tavily-api-url "https://api.tavily.com" --tavily-key "key"
smart-search --version
smart-search config path --format json
smart-search config list --format json
smart-search config list --format markdown
smart-search config set XAI_API_KEY "key" --format json
smart-search config set XAI_MODEL "grok-4-fast" --format json
smart-search config set XAI_TOOLS "web_search,x_search" --format json
smart-search config set OPENAI_COMPATIBLE_API_URL "https://api.openai.com/v1" --format json
smart-search config set OPENAI_COMPATIBLE_API_KEY "key" --format json
smart-search config set OPENAI_COMPATIBLE_MODEL "model-id" --format json
smart-search config set OPENAI_COMPATIBLE_STREAM "true" --format json
smart-search config set ANYSEARCH_API_URL "https://api.anysearch.com/mcp" --format json
smart-search config set ANYSEARCH_API_KEY "key" --format json
smart-search config set ANYSEARCH_TIMEOUT_SECONDS "30" --format json
smart-search config set EXA_API_KEY "key" --format json
smart-search config set CONTEXT7_API_KEY "key" --format json
smart-search config set ZHIPU_API_KEY "key" --format json
smart-search config set ZHIPU_API_URL "https://open.bigmodel.cn/api" --format json
smart-search config set ZHIPU_SEARCH_ENGINE "search_pro" --format json
smart-search config set TAVILY_API_URL "https://api.tavily.com" --format json
smart-search config set TAVILY_TIMEOUT_SECONDS "45" --format json
smart-search config set FIRECRAWL_API_URL "https://api.firecrawl.dev/v2" --format json
smart-search model current --format json
smart-search doctor --format json
smart-search doctor --format markdown
smart-search regression
smart-search smoke --mock --format json
smart-search smoke --mock --format markdown

交互式使用支持短别名：

powershell

smart-search --v
smart-search s "query" --format json
smart-search s "nba战报" --format content
smart-search f "https://example.com" --format markdown
smart-search exa "OpenAI Responses API documentation" --format json
smart-search z "today China AI news" --format json
smart-search c7 "react" "hooks" --format json
smart-search c7docs "/facebook/react" "useEffect cleanup" --format json
smart-search cfg ls --format json
smart-search d --format markdown
smart-search mdl cur --format json
smart-search sm --format json
smart-search reg

Guardrails

防护规则

Prefer JSON for agent parsing and markdown for fetched page text intended for reading.
Use
```
--output
```
for multi-source work, long pages, or anything the answer may need to cite later.
Keep
```
--extra-sources
```
small (
```
1
```
to
```
3
```
) unless the user asks for broad coverage. Large values are slower and can add noise.
Do not cite
```
extra_sources
```
as proof for a sentence in
```
content
```
; fetch the URL first or cite it only as a candidate source.
Prefer
```
exa-search --include-domains
```
for official documentation when likely domains are known.
Do not expose API keys. Treat
```
doctor
```
output as safe only because it is expected to mask secrets.
In this CLI-first workflow, native
```
web_search
```
is disabled unless the user explicitly configures another approved route.
If
```
doctor
```
or a command fails, report the failure and recovery steps; do not silently fall back to another web-search route.
If the user explicitly asks to bypass smart-search, state that another approved web-search route must be configured first.
Do not use legacy MCP tool names in prompts, notes, or generated instructions for this workflow.
Treat key rotation as a hard safety gate when previous key values were pasted into chat or logs.
For provider architecture maintenance, verify the distributable contract rather than the current developer machine's wrappers or local config. Keep fallback same-capability only.
Treat xAI Responses and OpenAI-compatible as peer
```
main_search
```
providers. Do not reuse one provider's URL/key to fabricate the other provider as a fallback.

对于Agent解析优先使用JSON，供人类阅读的抓取页面文本优先使用markdown。
对于多来源工作、长页面或后续可能需要引用的内容，使用
```
--output
```
。
保持
```
--extra-sources
```
较小（
```
1
```
到
```
3
```
），除非用户要求广泛覆盖。较大的值会更慢且可能增加噪音。
不要将
```
extra_sources
```
作为
```
content
```
中语句的证据；先抓取URL，或将其仅作为候选来源引用。
当已知可能的域名时，优先使用
```
exa-search --include-domains
```
查找官方文档。
不要暴露API密钥。仅当
```
doctor
```
输出预期会屏蔽敏感信息时，才将其视为安全内容。
在这个CLI优先的工作流中，原生
```
web_search
```
默认禁用，除非用户明确配置了其他已批准的路由。
如果
```
doctor
```
或某个命令失败，报告失败和恢复步骤；不要静默回退到其他网页搜索路由。
如果用户明确要求绕过smart-search，说明必须先配置其他已批准的网页搜索路由。
在这个工作流的提示、注释或生成的说明中，不要使用旧版MCP工具名称。
当之前的密钥值已粘贴到聊天或日志中时，将密钥轮换视为硬性安全关卡。
对于提供商架构维护，验证可分发约定而非当前开发机器的包装器或本地配置。仅在同一能力范围内保留备选方案。
将xAI Responses和兼容OpenAI的服务视为对等的
```
main_search
```
提供商。不要复用一个提供商的URL/密钥将另一个提供商伪装成备选方案。

Supporting Reference

参考资料

Read

references/cli-contract.md

when you need command details, output fields, exit codes, or regression expectations.

当需要命令细节、输出字段、退出代码或回归预期时，请阅读

references/cli-contract.md

。