@konbakuyomu/smart-search-linux-x64 0.0.0 → 0.1.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/package.json +18 -3
- package/runtime/smart-search/_internal/base_library.zip +0 -0
- package/runtime/smart-search/_internal/certifi/cacert.pem +3959 -0
- package/runtime/smart-search/_internal/certifi/py.typed +0 -0
- package/runtime/smart-search/_internal/libpython3.13.so.1.0 +0 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/INSTALLER +1 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/METADATA +171 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/RECORD +298 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/WHEEL +5 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/licenses/AUTHORS.rst +11 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/licenses/LICENSE +27 -0
- package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/top_level.txt +1 -0
- package/runtime/smart-search/_internal/smart_search/__init__.py +1 -0
- package/runtime/smart-search/_internal/smart_search/activity.py +279 -0
- package/runtime/smart-search/_internal/smart_search/assets/i18n/messages.json +17858 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/SKILL.md +69 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/agents/openai.yaml +3 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/cli-contract.md +21 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/cli-core.md +99 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/command-patterns.md +166 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/deep-research-mode.md +204 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/provider-routing.md +178 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/regression-release.md +46 -0
- package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/setup-config.md +133 -0
- package/runtime/smart-search/_internal/smart_search/assets/ui/index.html +955 -0
- package/runtime/smart-search/_internal/smart_search/cli.py +3651 -0
- package/runtime/smart-search/_internal/smart_search/config.py +1302 -0
- package/runtime/smart-search/_internal/smart_search/desktop_backend.py +709 -0
- package/runtime/smart-search/_internal/smart_search/desktop_catalog.py +166 -0
- package/runtime/smart-search/_internal/smart_search/desktop_cli.py +209 -0
- package/runtime/smart-search/_internal/smart_search/desktop_entry.py +19 -0
- package/runtime/smart-search/_internal/smart_search/desktop_environment.py +629 -0
- package/runtime/smart-search/_internal/smart_search/desktop_skills.py +129 -0
- package/runtime/smart-search/_internal/smart_search/desktop_updates.py +160 -0
- package/runtime/smart-search/_internal/smart_search/desktop_worker.py +117 -0
- package/runtime/smart-search/_internal/smart_search/i18n.py +135 -0
- package/runtime/smart-search/_internal/smart_search/intent_router.py +253 -0
- package/runtime/smart-search/_internal/smart_search/jev.py +473 -0
- package/runtime/smart-search/_internal/smart_search/jev_search.py +719 -0
- package/runtime/smart-search/_internal/smart_search/logger.py +43 -0
- package/runtime/smart-search/_internal/smart_search/provider_descriptions.py +140 -0
- package/runtime/smart-search/_internal/smart_search/provider_errors.py +137 -0
- package/runtime/smart-search/_internal/smart_search/provider_health.py +277 -0
- package/runtime/smart-search/_internal/smart_search/providers/__init__.py +27 -0
- package/runtime/smart-search/_internal/smart_search/providers/anysearch.py +336 -0
- package/runtime/smart-search/_internal/smart_search/providers/base.py +41 -0
- package/runtime/smart-search/_internal/smart_search/providers/context7.py +153 -0
- package/runtime/smart-search/_internal/smart_search/providers/exa.py +191 -0
- package/runtime/smart-search/_internal/smart_search/providers/jina.py +124 -0
- package/runtime/smart-search/_internal/smart_search/providers/openai_compatible.py +977 -0
- package/runtime/smart-search/_internal/smart_search/providers/sciverse.py +351 -0
- package/runtime/smart-search/_internal/smart_search/providers/tinyfish.py +213 -0
- package/runtime/smart-search/_internal/smart_search/providers/xai_responses.py +242 -0
- package/runtime/smart-search/_internal/smart_search/providers/zhipu.py +172 -0
- package/runtime/smart-search/_internal/smart_search/providers/zhipu_mcp.py +287 -0
- package/runtime/smart-search/_internal/smart_search/sciverse_schema.py +437 -0
- package/runtime/smart-search/_internal/smart_search/service.py +4302 -0
- package/runtime/smart-search/_internal/smart_search/skill_installer.py +549 -0
- package/runtime/smart-search/_internal/smart_search/skill_maintenance.py +181 -0
- package/runtime/smart-search/_internal/smart_search/sources.py +429 -0
- package/runtime/smart-search/_internal/smart_search/state_files.py +53 -0
- package/runtime/smart-search/_internal/smart_search/ui_api.py +246 -0
- package/runtime/smart-search/_internal/smart_search/ui_metadata.py +698 -0
- package/runtime/smart-search/_internal/smart_search/ui_server.py +506 -0
- package/runtime/smart-search/_internal/smart_search/utils.py +220 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/INSTALLER +1 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/METADATA +97 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/RECORD +105 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/REQUESTED +0 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/WHEEL +5 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/direct_url.json +1 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/entry_points.txt +2 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/licenses/LICENSE +21 -0
- package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/top_level.txt +1 -0
- package/runtime/smart-search/_internal/wcwidth/_wcwidth_c.abi3.so +0 -0
- package/runtime/smart-search/_internal/wcwidth/_wcwidth_c.pyi +77 -0
- package/runtime/smart-search/_internal/wcwidth/py.typed +0 -0
- package/runtime/smart-search/package.json +49 -0
- package/runtime/smart-search/smart-search +0 -0
- package/README.md +0 -3
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: smart-search-cli
|
|
3
|
+
description: "Instructions for AI agents to use the local smart-search CLI for current web search, source-backed fact checking, URL fetching, site mapping, official/API/documentation search, deep research, and reproducible evidence instead of MCP tools or native web search."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Smart Search CLI
|
|
7
|
+
|
|
8
|
+
Use the local `smart-search` command as the default execution layer for web research. This entrypoint keeps only routing, boundaries, and reference selection; load the focused reference file when command details or provider contracts matter.
|
|
9
|
+
|
|
10
|
+
## What This Skill Is
|
|
11
|
+
|
|
12
|
+
`smart-search-cli` is an instruction bundle for an AI tool. It explains when to call the local `smart-search` executable, which command fits the user's intent, how to preserve source evidence, and how to interpret provider status and fallback fields.
|
|
13
|
+
|
|
14
|
+
- The Skill does not provide search access by itself; the configured `smart-search` CLI and its providers do the work.
|
|
15
|
+
- The Skill is not an MCP server, does not store provider API keys, and does not create Trellis, hooks, agents, or commands.
|
|
16
|
+
- `smart-search setup --install-skills ...` connects selected Agents. Installed Skills use a short bootstrap: run `smart-search agent-guide` for this CLI's current instructions and `smart-search agent-guide references/<name>.md` for a referenced document.
|
|
17
|
+
- The App's **Update Skills** page reads the selected CLI's catalog. Explicit sync backs up changed files; **Remove Skills** backs up and disconnects selected targets. Automatic maintenance belongs to the CLI, works with the App closed, and preserves personal edits. Each connected target retains its CLI installation and configuration profile.
|
|
18
|
+
- After upgrading the CLI, normal use checks its managed Skills; `skills status` remains read-only and `skills update` provides an explicit refresh. Reopen the Agent session after changes (Gemini: `/skills reload`).
|
|
19
|
+
- Skill updates do not change provider configuration or API keys. Missing optional keys remain skipped rather than being treated as successful live checks.
|
|
20
|
+
|
|
21
|
+
## Default Workflow
|
|
22
|
+
|
|
23
|
+
1. Run `smart-search doctor --format json` when configuration or availability is uncertain.
|
|
24
|
+
2. 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.
|
|
25
|
+
3. If OpenAI-compatible `search` hangs or times out after `doctor` succeeds, run `smart-search diagnose openai-compatible --format markdown` and use its summary.
|
|
26
|
+
4. Keep `OPENAI_COMPATIBLE_API_MODE=chat-completions` unless a named relay has passed the official Responses subset probes; set `responses` only for that relay and keep the diagnostic evidence.
|
|
27
|
+
5. 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.
|
|
28
|
+
6. Use `smart-search skills status --targets codex --format json` when the installed global skill may be stale; use `smart-search skills update --targets codex --format json` to refresh it without rerunning setup.
|
|
29
|
+
7. 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.
|
|
30
|
+
8. Treat `TAVILY_ENABLED=false` as an intentional no-network boundary: do not work around it with direct Tavily or `map` calls. Check `doctor` and live smoke for disabled/skipped Tavily state; Firecrawl remains independently configured.
|
|
31
|
+
9. If a result reports a degraded provider in `provider_notices`, or a provider attempt is `skipped`, run `smart-search providers status --format json`. The channel is on a persisted failure cooldown; fix the credential or run `smart-search providers reset PROVIDER` instead of retrying the same failing provider.
|
|
32
|
+
10. Preserve command lines and source URLs in your answer. Prefer citing fetched pages; treat model citations and unread search sources as discovery candidates.
|
|
33
|
+
|
|
34
|
+
## Routing
|
|
35
|
+
|
|
36
|
+
- `search`: single-pass retrieval: Jev or local rules select one suitable channel, which returns results and sources; no automatic assessment, follow-up, filtering, or synthesis.
|
|
37
|
+
- `route`: explain capability routing locally without executing providers; `--router-mode jev --remote` explicitly opts into a potentially billable TypeSafe judgment.
|
|
38
|
+
- `research`: shared bounded loop with Jev or local routing for complementary discovery, fetch/read, evidence gaps, and optional synthesis.
|
|
39
|
+
- `deep`: offline Deep Research planner; it does not run providers, fetch pages, or replace default `search`.
|
|
40
|
+
- `zhipu-search`: Chinese-language, domestic China, policy/regulatory, announcements, current news, or China-local source discovery.
|
|
41
|
+
- `context7-library` / `context7-docs`: library, SDK, API, framework, or documentation intent. Ordinary search uses the first library in Context7's ranked candidates; research may ask Jev to choose a candidate, using the first candidate if Jev fails or no score reaches its threshold. Unresolved libraries allow same-capability fallback. Explicit commands retain the candidate list and supplied library id.
|
|
42
|
+
- `exa-search`: official domains, papers, product pages, trusted pages, date/domain-filtered low-noise discovery, and adjacent source discovery through `exa-similar`.
|
|
43
|
+
- `fetch`: user-provided URLs or any claim that depends on page content.
|
|
44
|
+
- `map`: documentation site or domain structure before fetching many pages from one site.
|
|
45
|
+
- `anysearch-*`: explicit experimental vertical search only. Inspect domains first and do not use AnySearch as default fallback. Parse JSON parameters before repeatable `--param key=value` overrides; `anysearch-extract --max-length` sends only the URL upstream and truncates successful text locally.
|
|
46
|
+
- `sciverse-*`: explicit experimental academic search only. Use for catalog/search/semantic/read/relations; do not use Sciverse as `docs_search`, `standard`, or default `search` / `research` fallback.
|
|
47
|
+
- `providers status` / `providers reset`: inspect or clear the persisted failure cooldown for optional providers; use it when a channel keeps reporting the same failure.
|
|
48
|
+
- `model current`: inspect explicit provider models only. Change models with `smart-search config set XAI_MODEL ...` or `smart-search config set OPENAI_COMPATIBLE_MODEL ...`.
|
|
49
|
+
|
|
50
|
+
## Key Boundaries
|
|
51
|
+
|
|
52
|
+
- `smart-search` should resolve from the user's PATH.
|
|
53
|
+
- Private API keys should be saved with `smart-search setup` or `smart-search config set`; environment variables remain supported for CI and advanced users.
|
|
54
|
+
- In sandboxed runtimes, set `SMART_SEARCH_CONFIG_DIR` to an absolute writable path when the default config directory is unavailable or must be pinned.
|
|
55
|
+
- The standard minimum profile requires at least one enabled retrieval channel. Jev and a main model are optional; the requested operation still needs a capable channel.
|
|
56
|
+
- Fallback stays within the same capability family; model answers and web search are mutual fallbacks in ordinary search. Do not use Context7 for broad news/web facts or page-extraction providers as documentation search replacements.
|
|
57
|
+
- xAI Responses and OpenAI-compatible are peer `main_search` providers. Do not reuse one provider's URL/key to fabricate the other provider as fallback.
|
|
58
|
+
- For current-news, policy, finance, health, and other high-risk facts, do not answer from broad `search.content` alone. Fetch key pages and summarize only what fetched text supports.
|
|
59
|
+
- Native `web_search` is disabled in this CLI-first workflow unless the user explicitly configures another approved route; do not silently fall back to another web-search route.
|
|
60
|
+
|
|
61
|
+
## References
|
|
62
|
+
|
|
63
|
+
- Command examples, evidence files, timeout retry policy, and guardrails: `references/command-patterns.md`
|
|
64
|
+
- Deep Research planner/executor workflow, plan fields, gap check, and smoke matrix: `references/deep-research-mode.md`
|
|
65
|
+
- CLI entrypoints, command signatures, aliases, output fields, exit codes, and tool policy: `references/cli-core.md`
|
|
66
|
+
- Setup, config storage, skill installation, provider endpoints, and OpenAI-compatible diagnostics: `references/setup-config.md`
|
|
67
|
+
- Intent routing, provider capabilities, source provenance, fallback boundaries, and routing maintenance: `references/provider-routing.md`
|
|
68
|
+
- Regression, packaged install checks, release lanes, and release closeout lessons: `references/regression-release.md`
|
|
69
|
+
- Compatibility reference map for older instructions that mention the original monolithic file: `references/cli-contract.md`
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Smart Search CLI Reference Map
|
|
2
|
+
|
|
3
|
+
This compatibility entrypoint no longer stores the full CLI contract. Read the focused reference that matches the task.
|
|
4
|
+
|
|
5
|
+
## Read These Files
|
|
6
|
+
|
|
7
|
+
- `cli-core.md`: entrypoints, command signatures, aliases, JSON/Markdown/content output expectations, exit codes, and tool policy.
|
|
8
|
+
- `command-patterns.md`: source-directed examples, evidence files, timeout retry policy, and everyday guardrails.
|
|
9
|
+
- `deep-research-mode.md`: Deep Research trigger rules, offline planner, live executor, `research_plan` shape, allowed tools, gap check, provider advantage routing, and smoke matrix.
|
|
10
|
+
- `provider-routing.md`: intent routing diagnostics, provider capabilities, source provenance, same-capability fallback, Zhipu REST/MCP, Jina, AnySearch, Exa, Tavily, Firecrawl, Context7, and maintenance guardrails.
|
|
11
|
+
- `setup-config.md`: config storage, setup/config commands, skill installation, endpoint setup, OpenAI-compatible diagnostics, streaming, and router configuration.
|
|
12
|
+
- `regression-release.md`: regression behavior, packaged-install checks, release lanes, and release closeout lessons.
|
|
13
|
+
|
|
14
|
+
## Selection Hints
|
|
15
|
+
|
|
16
|
+
- Need to choose or explain a search/docs/fetch route: read `provider-routing.md`, then `command-patterns.md`.
|
|
17
|
+
- Need command syntax, aliases, output fields, or exit codes: read `cli-core.md`.
|
|
18
|
+
- Need setup, API keys, config paths, skill update behavior, provider endpoint flags, the `smart-search ui` config page, or per-provider key testing: read `setup-config.md`.
|
|
19
|
+
- Need deep search, deep research, multi-source verification, serious review, or selection/comparison research: read `deep-research-mode.md`.
|
|
20
|
+
- Need timeout recovery, saved evidence files, or source-first fallback examples: read `command-patterns.md`.
|
|
21
|
+
- Need release, npm/mise packaged install, or regression expectations: read `regression-release.md`.
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# CLI Core
|
|
2
|
+
|
|
3
|
+
## Table of Contents
|
|
4
|
+
|
|
5
|
+
- Entrypoints
|
|
6
|
+
- Commands
|
|
7
|
+
- Aliases
|
|
8
|
+
- Output format expectations
|
|
9
|
+
- Exit codes
|
|
10
|
+
- Tool policy
|
|
11
|
+
|
|
12
|
+
## Entrypoints
|
|
13
|
+
|
|
14
|
+
- `smart-search` is the primary CLI and should resolve from the user's PATH.
|
|
15
|
+
- `smart-search --version`, `smart-search --v`, and `smart-search -v` print the installed version and exit with code `0`.
|
|
16
|
+
- This bundled skill is maintained with the `smartsearch` repository.
|
|
17
|
+
- Private API keys should be saved with `smart-search setup` or `smart-search config set`; environment variables remain supported for CI and advanced users.
|
|
18
|
+
- Do not depend on MCP inline `env` values or committed API-key environment variables for CLI use.
|
|
19
|
+
- On Windows with mise, the managed package name is `npm:@konbakuyomu/smart-search`; the executable remains `smart-search`. Diagnose mise managed installs with `mise ls "npm:@konbakuyomu/smart-search"` and `mise which smart-search`.
|
|
20
|
+
|
|
21
|
+
## Commands
|
|
22
|
+
|
|
23
|
+
- `smart-search search QUERY [--platform NAME] [--model ID] [--extra-sources N] [--validation fast|balanced|strict] [--fallback auto|off] [--providers auto|CSV] [--stream|--no-stream] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]` (`--timeout` overrides the persisted `SMART_SEARCH_TIMEOUT_SECONDS` total budget)
|
|
24
|
+
- `smart-search route QUERY [--validation fast|balanced|strict] [--router-mode jev|local] [--remote] [--format json|markdown|content] [--output PATH]`
|
|
25
|
+
- `smart-search fetch URL [--format json|markdown|content] [--output PATH]`
|
|
26
|
+
- `smart-search exa-search QUERY [--num-results N] [--search-type neural|keyword|auto] [--include-text] [--include-highlights] [--start-published-date YYYY-MM-DD] [--include-domains DOMAIN...] [--exclude-domains DOMAIN...] [--category NAME] [--format json|markdown|content] [--output PATH]`
|
|
27
|
+
- `smart-search exa-similar URL [--num-results N] [--format json|markdown|content] [--output PATH]`
|
|
28
|
+
- `smart-search zhipu-search QUERY [--count N] [--search-engine NAME] [--search-recency-filter VALUE] [--search-domain-filter DOMAIN] [--content-size medium|high] [--format json|markdown|content] [--output PATH]`
|
|
29
|
+
- `smart-search zhipu-mcp-search QUERY [--count N] [--format json|markdown|content] [--output PATH]`
|
|
30
|
+
- `smart-search zhipu-mcp-reader URL [--format json|markdown|content] [--output PATH]`
|
|
31
|
+
- `smart-search zhipu-mcp-search-doc REPO QUERY [--max-results N] [--format json|markdown|content] [--output PATH]`
|
|
32
|
+
- `smart-search zhipu-mcp-repo-structure REPO [--ref REF] [--format json|markdown|content] [--output PATH]`
|
|
33
|
+
- `smart-search zhipu-mcp-read-file REPO PATH [--ref REF] [--format json|markdown|content] [--output PATH]`
|
|
34
|
+
- `smart-search anysearch-domains [DOMAIN] [--format json|markdown|content] [--output PATH]`
|
|
35
|
+
- `smart-search anysearch-search QUERY [--domain DOMAIN] [--sub-domain SUB_DOMAIN] [--sub-domain-params JSON_OBJECT] [--param KEY=VALUE] [--max-results N] [--format json|markdown|content] [--output PATH]`
|
|
36
|
+
- `smart-search anysearch-extract URL [--max-length N] [--format json|markdown|content] [--output PATH]`
|
|
37
|
+
- `smart-search anysearch-batch QUERY... [--max-results N] [--format json|markdown|content] [--output PATH]`
|
|
38
|
+
- `smart-search sciverse-catalog [--collection papers] [--include-sample-values] [--include-field-stats] [--format json|markdown|content] [--output PATH]`
|
|
39
|
+
- `smart-search sciverse-search [QUERY] [--collection papers] [--title-contains TEXT] [--abstract-contains TEXT] [--authors CSV] [--journals CSV] [--subjects CSV] [--year-from YEAR] [--year-to YEAR] [--filters-advanced JSON_ARRAY] [--sort-advanced JSON_ARRAY] [--sort-by-year desc|asc|none] [--freshness-boost NONE|MILD|STRONG] [--page N] [--page-size N] [--format json|markdown|content] [--output PATH]`
|
|
40
|
+
- `smart-search sciverse-semantic QUERY [--top-k N] [--retrieval hybrid|milvus|es] [--mode fast|balanced|quality] [--source-types CSV] [--format json|markdown|content] [--output PATH]`
|
|
41
|
+
- `smart-search sciverse-read DOC_ID [--offset N] [--limit N] [--format json|markdown|content] [--output PATH]`
|
|
42
|
+
- `smart-search sciverse-relations UNIQUE_ID [--relation CITATIONS|REFERENCES|RELATED_WORKS] [--page N] [--page-size N] [--format json|markdown|content] [--output PATH]`
|
|
43
|
+
- `smart-search context7-library NAME [QUERY] [--format json|markdown|content] [--output PATH]`
|
|
44
|
+
- `smart-search context7-docs LIBRARY_ID QUERY [--format json|markdown|content] [--output PATH]`
|
|
45
|
+
- `smart-search deep QUERY [--budget quick|standard|deep] [--evidence-dir PATH] [--format json|markdown|content] [--output PATH]`
|
|
46
|
+
- `smart-search research QUERY [--budget quick|standard|deep] [--evidence-dir PATH] [--fallback auto|off] [--format json|markdown|content] [--output PATH]`
|
|
47
|
+
- `smart-search route-calibrate [--models CSV] [--format json|markdown|content] [--output PATH]`
|
|
48
|
+
- `smart-search map URL [--instructions TEXT] [--max-depth N] [--max-breadth N] [--limit N] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]`
|
|
49
|
+
- `smart-search doctor [--format json|markdown|content] [--output PATH]`
|
|
50
|
+
- `smart-search diagnose openai-compatible [--timeout SECONDS] [--format json|markdown] [--output PATH]`
|
|
51
|
+
- `smart-search setup [--lang zh|en] [--advanced] [--non-interactive] [--skip-skills] [--install-skills CSV] [--skills-root PATH] [--xai-api-url URL] [--xai-api-key KEY] [--xai-model ID] [--xai-tools-explicit CSV] [--openai-compatible-api-url URL] [--openai-compatible-api-key KEY] [--openai-compatible-model ID] [--openai-compatible-fallback-models CSV] [--openai-compatible-api-mode chat-completions|responses] [--openai-compatible-stream true|false] [--validation-level fast|balanced|strict] [--fallback-mode auto|off] [--minimum-profile standard|off] [--intent-router jev|local] [--search-timeout SECONDS] [--provider-cooldown SECONDS] [--provider-failure-threshold N] [--exa-key KEY] [--context7-key KEY] [--zhipu-key KEY] [--zhipu-api-url URL] [--zhipu-search-engine ENGINE] [--zhipu-mcp-key KEY] [--zhipu-mcp-search-api-url URL] [--zhipu-mcp-reader-api-url URL] [--zhipu-mcp-zread-api-url URL] [--zhipu-mcp-timeout SECONDS] [--jina-key KEY] [--jina-reader-api-url URL] [--jina-respond-with MODE] [--jina-timeout SECONDS] [--tavily-api-url URL] [--tavily-key KEY] [--firecrawl-api-url URL] [--firecrawl-key KEY] [--tinyfish-key KEY] [--tinyfish-search-api-url URL] [--tinyfish-fetch-api-url URL] [--tinyfish-timeout SECONDS] [--anysearch-api-url URL] [--anysearch-key KEY] [--anysearch-timeout SECONDS] [--sciverse-api-url URL] [--sciverse-token TOKEN] [--sciverse-timeout SECONDS] [--format json|markdown|content] [--output PATH]`
|
|
52
|
+
- `smart-search config path|list|set|unset ... [--format json|markdown|content] [--output PATH]`
|
|
53
|
+
- `smart-search model set MODEL [--format json|markdown|content] [--output PATH]`
|
|
54
|
+
- `smart-search model current [--format json|markdown|content] [--output PATH]`
|
|
55
|
+
- `smart-search providers status [--format json|markdown|content] [--output PATH]`
|
|
56
|
+
- `smart-search providers reset [PROVIDER...] [--format json|markdown|content] [--output PATH]`
|
|
57
|
+
- `smart-search regression`
|
|
58
|
+
- `smart-search smoke [--mode mock|live] [--mock] [--live] [--format json|markdown|content] [--output PATH]`
|
|
59
|
+
|
|
60
|
+
## Aliases
|
|
61
|
+
|
|
62
|
+
Top-level aliases normalize to the same service behavior as their full command: `search`/`s`, `route`/`rt`, `fetch`/`f`, `map`/`m`, `exa-search`/`exa`/`x`, `exa-similar`/`xs`, `zhipu-search`/`z`/`zp`, `zhipu-mcp-search`/`zmcp-search`, `zhipu-mcp-reader`/`zmcp-reader`, `zhipu-mcp-search-doc`/`zmcp-doc`, `zhipu-mcp-repo-structure`/`zmcp-tree`, `zhipu-mcp-read-file`/`zmcp-file`, `anysearch-domains`/`as-domains`, `anysearch-search`/`as-search`/`as`, `anysearch-extract`/`as-extract`, `anysearch-batch`/`as-batch`, `sciverse-catalog`/`sv-catalog`, `sciverse-search`/`sv-search`/`sv`, `sciverse-semantic`/`sv-semantic`, `sciverse-read`/`sv-read`, `sciverse-relations`/`sv-relations`, `context7-library`/`c7`/`ctx7`, `context7-docs`/`c7d`/`c7docs`/`ctx7-docs`, `deep`/`dr`, `research`/`rs`, `route-calibrate`/`route-cal`/`rcal`, `doctor`/`d`, `diagnose`/`diag`, `setup`/`init`, `config`/`cfg`, `model`/`mdl`, `smoke`/`sm`, `providers`/`prov`, and `regression`/`reg`.
|
|
63
|
+
|
|
64
|
+
Nested aliases: `config path`/`cfg p`, `config list`/`cfg ls`/`cfg l`, `config set`/`cfg s`, `config unset`/`cfg rm`/`cfg u`, `model current`/`mdl cur`/`mdl c`, `model set`/`mdl s`, `providers status`/`prov st`/`prov ls`, and `providers reset`/`providers clear`.
|
|
65
|
+
|
|
66
|
+
## Output Format Expectations
|
|
67
|
+
|
|
68
|
+
- `--format json` is the stable machine-readable contract for agents and scripts. JSON output remains parseable and uses readable non-ASCII text when the terminal encoding supports it.
|
|
69
|
+
- `--format markdown` is the human-readable report format. `route --format markdown`, `route-calibrate --format markdown`, `doctor --format markdown`, and `diagnose openai-compatible --format markdown` must render useful reports rather than raw JSON dumps.
|
|
70
|
+
- `--format content` prints only the `content` field for content-bearing commands such as `search`, `fetch`, `context7-docs`, and `research`. Commands without a `content` field, including `route`, `route-calibrate`, `doctor`, `smoke`, `config`, `model`, and `providers`, must print a compact non-empty text summary.
|
|
71
|
+
- Successful search output includes `ok`, `query`, `primary_api_mode`, `content`, `sources`, `sources_count`, `primary_sources`, `primary_sources_count`, `extra_sources`, `extra_sources_count`, `source_warning`, `routing_decision`, `providers_used`, `provider_attempts`, `provider_notices`, `fallback_used`, `validation_level`, `timeout_seconds`, `timeout_phase`, `phase_attempts`, deadline elapsed/remaining milliseconds, `partial_success`, and `elapsed_ms`. Phase telemetry is scheduler-level and additive; provider attempts remain provider-level records.
|
|
72
|
+
- Route diagnostic output includes `ok`, `intent_router_mode`, `required_capabilities`, `available_channels`, `selected_channels`, and `executed_search=false`. Default preview is offline; `--remote` explicitly enables Jev judgment.
|
|
73
|
+
- `route-calibrate` returns `deprecated=true`, `executed_remote=false`, and `error_type=parameter_error`; no model calibration is performed.
|
|
74
|
+
- Fetch output includes `ok`, `url`, `provider`, `content`, `provider_attempts`, `provider_notices`, `fallback_used`, and `elapsed_ms`.
|
|
75
|
+
- Exa search output includes `ok`, `query`, `search_type`, `results`, `total`, and `elapsed_ms`. Exa similar output includes `ok`, `url`, `results`, `total`, and `elapsed_ms`.
|
|
76
|
+
- Zhipu search output includes `ok`, `query`, `provider`, `search_engine`, `results`, `total`, and `elapsed_ms`.
|
|
77
|
+
- Zhipu MCP command output includes `ok`, `provider`, `tool`, `elapsed_ms`, and either `content` for reader/file-like tools or `results` plus `total` for search-like tools.
|
|
78
|
+
- Sciverse command output includes `ok`, `provider=sciverse`, `tool`, `elapsed_ms`, and command-specific fields such as `fields`, `results`, `hits`, `text`, `items`, `unique_id`, `doc_id`, and `relation_direction`. Current catalog and search schemas have no `collection` selector: legacy `--collection papers` is not sent upstream, while `authors` and `sources` return `parameter_error`. `sciverse-semantic --retrieval hybrid|milvus|es` is current; legacy `--mode fast|balanced|quality` warns and maps to `hybrid`, while a conflicting explicit retrieval is a `parameter_error`.
|
|
79
|
+
- AnySearch parses `--sub-domain-params` JSON before repeatable `--param KEY=VALUE` overrides, returning `parameter_error` before a request for invalid values. `anysearch-extract` sends only `url` upstream and locally truncates successful text fields only when `--max-length` is positive.
|
|
80
|
+
- Context7 library output includes `ok`, `query`, `provider`, `results`, `total`, and `elapsed_ms`; Context7 docs output also includes `library_id`, `content`, and result metadata.
|
|
81
|
+
- Map output includes `ok`, `base_url`, `results`, `response_time`, `url`, and `elapsed_ms`.
|
|
82
|
+
- Deep planner output includes `ok`, `mode`, `query_mode`, `question`, `trigger_source`, `difficulty`, `intent_signals`, `decomposition`, `capability_plan`, `evidence_policy`, `preflight`, `steps`, `gap_check`, `final_answer_policy`, `usage_boundary`, `allowed_tools`, `evidence_dir`, and `elapsed_ms`.
|
|
83
|
+
- Research executor output includes `ok`, `mode=deep_research_execution`, `query_mode=research`, `question`, `budget`, `research_plan`, `routing_decision`, `stage_results`, `discovery_sources`, `final_answer`, `content`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `provider_notices`, `providers_used`, `fallback_used`, `degraded`, `route_policy_version`, `evidence_dir`, `minimum_profile_ok`, `capability_status`, and `elapsed_ms`.
|
|
84
|
+
- Diagnostic output masks keys and reports config paths, Windows legacy config metadata, provider timeout values, `capability_status`, `minimum_profile_ok`, `intent_router_status`, `provider_health`, `main_search_connection_tests`, and provider connectivity checks. A successful `doctor` probe also clears that provider's failure cooldown. OpenAI-compatible health must use the endpoint selected by `OPENAI_COMPATIBLE_API_MODE`; `/models` is supplementary metadata.
|
|
85
|
+
- Provider health output includes `ok`, `enabled`, `cooldown_seconds`, `failure_threshold`, `store_path`, `providers`, and `cooldown_providers`; each provider entry carries `provider`, `configured`, `state` (`closed` or `cooldown`), `consecutive_failures`, `error_type`, `error`, `cooldown_remaining_seconds`, and `hard_failure`. `providers reset` output includes `ok`, `cleared`, and `known_providers`, and returns `parameter_error` for an unknown provider id.
|
|
86
|
+
- `provider_notices` is one deduplicated entry per degraded optional provider with `provider`, `capability`, `status` (`failed` or `cooldown`), `error_type`, `error`, `cooldown_remaining_seconds`, and `hint`. Markdown output prints a steady `cooldown` notice only when the command itself failed; JSON always carries it.
|
|
87
|
+
- Smoke output includes `ok`, `mode`, `status` (`healthy`, `degraded`, or `failed`), `failed_cases`, `degraded_cases`, `skipped_cases`, `cases`, `provider_attempts`, and `elapsed_ms`. Healthy and degraded smoke preserve `ok: true` and exit code `0`; failed smoke is non-zero. Live smoke skips unavailable optional checks; overall failure follows the reported critical cases, while optional failures with an available same-capability alternative are degraded.
|
|
88
|
+
|
|
89
|
+
## Exit Codes
|
|
90
|
+
|
|
91
|
+
- `0`: success
|
|
92
|
+
- `2`: parameter error
|
|
93
|
+
- `3`: configuration error
|
|
94
|
+
- `4`: network or upstream error, also used for strict insufficient-evidence search failures
|
|
95
|
+
- `5`: runtime or parse error
|
|
96
|
+
|
|
97
|
+
## Tool Policy
|
|
98
|
+
|
|
99
|
+
Web research through this skill should use `smart-search` CLI. If the CLI is unavailable, report the blocker and recovery steps instead of silently falling back to another web-search route.
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Command Patterns
|
|
2
|
+
|
|
3
|
+
## Table of Contents
|
|
4
|
+
|
|
5
|
+
- Evidence files
|
|
6
|
+
- Common commands
|
|
7
|
+
- Short aliases
|
|
8
|
+
- Timeout retry policy
|
|
9
|
+
- Guardrails
|
|
10
|
+
|
|
11
|
+
## Evidence Files
|
|
12
|
+
|
|
13
|
+
For multi-source research, use `--output` to save 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.
|
|
14
|
+
|
|
15
|
+
For claim-level evidence, prefer this order:
|
|
16
|
+
|
|
17
|
+
1. Discover candidate URLs with source-focused `search`, `zhipu-search` for Chinese/current/domestic topics, Context7 for docs/API/library topics, or `exa-search` for official/trusted domains and papers.
|
|
18
|
+
2. Fetch the exact pages that matter.
|
|
19
|
+
3. Build claim-level conclusions from fetched pages, or use `research` for automatic multi-source work. Ordinary `search` returns one selected channel and performs no post-retrieval synthesis. Unread sources remain unverified; `extra_sources` is an empty compatibility field.
|
|
20
|
+
|
|
21
|
+
Deep Research planner output uses an explicit `--evidence-dir` when supplied, otherwise a generated `smart-search-evidence` directory under `tempfile.gettempdir()`. Preserve the CLI's planned `--output` path and `output_path` match; do not rewrite evidence contracts unless a separate docs/runtime fix is in scope. Hard-coded paths such as `C:\tmp\smart-search-evidence\...` should be treated as user-chosen explicit output locations.
|
|
22
|
+
|
|
23
|
+
## Common Commands
|
|
24
|
+
|
|
25
|
+
```powershell
|
|
26
|
+
smart-search search "query" --extra-sources 5 --timeout 300 --format json --output result.json
|
|
27
|
+
smart-search search "query" --stream --format json
|
|
28
|
+
smart-search diagnose openai-compatible --format markdown
|
|
29
|
+
smart-search search "query" --platform "Reuters" --model "model-id" --extra-sources 3 --timeout 300 --format json
|
|
30
|
+
smart-search search "nba战报" --format content
|
|
31
|
+
smart-search search "query" --validation strict --fallback auto --providers auto --format json
|
|
32
|
+
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
|
|
33
|
+
smart-search exa-similar "https://example.com/article" --num-results 5 --format json
|
|
34
|
+
smart-search context7-library "react" "hooks" --format json
|
|
35
|
+
smart-search context7-docs "/reactjs/react.dev" "useEffect cleanup" --format json
|
|
36
|
+
smart-search zhipu-search "today China AI news" --count 5 --format json
|
|
37
|
+
smart-search anysearch-domains security --format json
|
|
38
|
+
smart-search anysearch-search "CVE-2024-3094" --domain security --sub-domain vuln --param type=cve --param value=CVE-2024-3094 --max-results 3 --format json
|
|
39
|
+
smart-search anysearch-search "CVE-2024-3094" --domain security.cve --sub-domain-params '{"type":"legacy","value":"old"}' --param type=cve --param value=CVE-2024-3094 --format json
|
|
40
|
+
smart-search anysearch-extract "https://example.com/source" --max-length 12000 --format json
|
|
41
|
+
smart-search anysearch-batch "AAPL" "RAG papers" --max-results 2 --format json
|
|
42
|
+
smart-search sciverse-catalog --collection papers --format json
|
|
43
|
+
smart-search sciverse-search "transformer retrieval" --year-from 2020 --page-size 5 --format json
|
|
44
|
+
smart-search sciverse-semantic "attention mechanism" --top-k 3 --retrieval hybrid --source-types web,pdf --format json
|
|
45
|
+
smart-search sciverse-read "doc-id-from-search" --offset 0 --limit 4096 --format json
|
|
46
|
+
smart-search sciverse-relations "unique-id-from-search" --relation CITATIONS --page-size 25 --format json
|
|
47
|
+
smart-search fetch "https://example.com" --format markdown --output page.md
|
|
48
|
+
smart-search map "https://docs.example.com" --instructions "Find API reference pages" --max-depth 1 --max-breadth 20 --limit 50 --format json
|
|
49
|
+
smart-search research "OpenAI Responses API web_search vs Chat Completions search" --budget deep --fallback auto --format json
|
|
50
|
+
smart-search rs "https://example.com/source" --fallback off --format markdown
|
|
51
|
+
smart-search setup
|
|
52
|
+
smart-search setup --lang en
|
|
53
|
+
smart-search setup --advanced
|
|
54
|
+
smart-search setup --non-interactive --install-skills hermes
|
|
55
|
+
smart-search skills status --targets codex --format json
|
|
56
|
+
smart-search skills update --targets codex --format json
|
|
57
|
+
smart-search skills update --all --format json
|
|
58
|
+
smart-search route "React useEffect API docs" --format markdown
|
|
59
|
+
smart-search setup --non-interactive --zhipu-api-url "https://open.bigmodel.cn/api" --zhipu-search-engine "search_std"
|
|
60
|
+
smart-search setup --non-interactive --openai-compatible-api-mode responses
|
|
61
|
+
smart-search setup --non-interactive --openai-compatible-stream true
|
|
62
|
+
smart-search setup --non-interactive --openai-compatible-fallback-models "model-a,model-b"
|
|
63
|
+
smart-search setup --non-interactive --anysearch-api-url "https://api.anysearch.com/mcp" --anysearch-key "key"
|
|
64
|
+
smart-search setup --non-interactive --sciverse-token "key" --sciverse-api-url "https://api.sciverse.space"
|
|
65
|
+
smart-search setup --non-interactive --tavily-api-url "https://api.tavily.com" --tavily-key "key"
|
|
66
|
+
smart-search --version
|
|
67
|
+
smart-search config path --format json
|
|
68
|
+
smart-search config list --format json
|
|
69
|
+
smart-search config list --format markdown
|
|
70
|
+
smart-search config set XAI_API_KEY "key" --format json
|
|
71
|
+
smart-search config set XAI_MODEL "grok-4-fast" --format json
|
|
72
|
+
smart-search config set XAI_TOOLS "web_search,x_search" --format json
|
|
73
|
+
smart-search config set XAI_REASONING_EFFORT "high" --format json
|
|
74
|
+
smart-search search "Latest Grok news" --providers xai-responses --stream --format json
|
|
75
|
+
smart-search config set OPENAI_COMPATIBLE_API_URL "https://api.openai.com/v1" --format json
|
|
76
|
+
smart-search config set OPENAI_COMPATIBLE_API_KEY "key" --format json
|
|
77
|
+
smart-search config set OPENAI_COMPATIBLE_MODEL "model-id" --format json
|
|
78
|
+
smart-search config set OPENAI_COMPATIBLE_API_MODE "responses" --format json
|
|
79
|
+
smart-search config set OPENAI_COMPATIBLE_FALLBACK_MODELS "model-a,model-b" --format json
|
|
80
|
+
smart-search config set OPENAI_COMPATIBLE_STREAM "true" --format json
|
|
81
|
+
smart-search config set SMART_SEARCH_TIMEOUT_SECONDS "180" --format json
|
|
82
|
+
smart-search config set ANYSEARCH_API_URL "https://api.anysearch.com/mcp" --format json
|
|
83
|
+
smart-search config set SCIVERSE_API_TOKEN "key" --format json
|
|
84
|
+
smart-search config set ANYSEARCH_API_KEY "key" --format json
|
|
85
|
+
smart-search config set ANYSEARCH_TIMEOUT_SECONDS "30" --format json
|
|
86
|
+
smart-search config set SMART_SEARCH_INTENT_ROUTER "jev" --format json
|
|
87
|
+
smart-search config set EXA_API_KEY "key" --format json
|
|
88
|
+
smart-search config set CONTEXT7_API_KEY "key" --format json
|
|
89
|
+
smart-search config set ZHIPU_API_KEY "key" --format json
|
|
90
|
+
smart-search config set ZHIPU_API_URL "https://open.bigmodel.cn/api" --format json
|
|
91
|
+
smart-search config set ZHIPU_SEARCH_ENGINE "search_pro" --format json
|
|
92
|
+
smart-search config set TAVILY_API_URL "https://api.tavily.com" --format json
|
|
93
|
+
smart-search config set TAVILY_ENABLED "false" --format json
|
|
94
|
+
smart-search config set TAVILY_TIMEOUT_SECONDS "45" --format json
|
|
95
|
+
smart-search config set FIRECRAWL_API_URL "https://api.firecrawl.dev/v2" --format json
|
|
96
|
+
smart-search config set TINYFISH_API_KEY "key" --format json
|
|
97
|
+
smart-search config set TINYFISH_SEARCH_API_URL "https://api.search.tinyfish.ai" --format json
|
|
98
|
+
smart-search config set TINYFISH_FETCH_API_URL "https://api.fetch.tinyfish.ai" --format json
|
|
99
|
+
smart-search model current --format json
|
|
100
|
+
smart-search doctor --format json
|
|
101
|
+
smart-search doctor --format markdown
|
|
102
|
+
smart-search diagnose openai-compatible --format markdown
|
|
103
|
+
smart-search regression
|
|
104
|
+
smart-search smoke --mock --format json
|
|
105
|
+
smart-search smoke --mock --format markdown
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`TAVILY_ENABLED=false` is a complete Tavily no-network switch even if `TAVILY_API_KEY` is still saved. It removes Tavily from automatic web-search/fetch routes, makes direct Tavily boundaries and `doctor` local-only, and makes `map` return a configuration error; it does not configure Firecrawl.
|
|
109
|
+
|
|
110
|
+
## Short Aliases
|
|
111
|
+
|
|
112
|
+
```powershell
|
|
113
|
+
smart-search --v
|
|
114
|
+
smart-search s "query" --format json
|
|
115
|
+
smart-search rt "React useEffect API docs" --format markdown
|
|
116
|
+
smart-search s "nba战报" --format content
|
|
117
|
+
smart-search rs "query" --format json
|
|
118
|
+
smart-search f "https://example.com" --format markdown
|
|
119
|
+
smart-search exa "OpenAI Responses API documentation" --format json
|
|
120
|
+
smart-search z "today China AI news" --format json
|
|
121
|
+
smart-search c7 "react" "hooks" --format json
|
|
122
|
+
smart-search c7docs "/reactjs/react.dev" "useEffect cleanup" --format json
|
|
123
|
+
smart-search cfg ls --format json
|
|
124
|
+
smart-search d --format markdown
|
|
125
|
+
smart-search mdl cur --format json
|
|
126
|
+
smart-search sm --format json
|
|
127
|
+
smart-search reg
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Degraded Provider Recovery
|
|
131
|
+
|
|
132
|
+
When a search succeeds but `provider_notices` reports a degraded optional provider, or a provider attempt has `status=skipped`, the channel is on a persisted failure cooldown rather than being retried on every call.
|
|
133
|
+
|
|
134
|
+
1. Run `smart-search providers status --format json` to see the remembered `error_type`, `error`, and `cooldown_remaining_seconds`.
|
|
135
|
+
2. For `auth_error` or `config_error`, fix the credential with `smart-search config set` or `smart-search setup`. Re-keying clears the cooldown automatically.
|
|
136
|
+
3. For a transient failure, run `smart-search doctor --format json`; a successful probe clears the record.
|
|
137
|
+
4. Use `smart-search providers reset PROVIDER` to force an immediate retry, or `smart-search providers reset` to clear every cooldown.
|
|
138
|
+
5. Do not work around a cooled-down provider with a different-capability provider; same-capability fallback already covers the query.
|
|
139
|
+
|
|
140
|
+
## Timeout Retry Policy
|
|
141
|
+
|
|
142
|
+
When `smart-search search` returns `ok: false` with `error_type: "timeout"`, inspect `timeout_phase` and `provider_attempts` first. Partial results can remain in `content`; ordinary search has no automatic optional source phase.
|
|
143
|
+
|
|
144
|
+
1. Retry the same search at most once, adding `--extra-sources 1` to limit the selected channel result count.
|
|
145
|
+
2. Use `--format json` and `--output PATH` for each attempt; inspect the saved JSON and stop on `"ok": true`.
|
|
146
|
+
3. Set the agent's command execution timeout at least 30 seconds longer than the smart-search total budget, or run the command in the background. With the default 300-second budget, the agent timeout must be at least 330 seconds; otherwise the agent can kill smart-search before it returns structured results. `SMART_SEARCH_TIMEOUT_SECONDS` supplies the default; `--timeout` overrides one call.
|
|
147
|
+
4. If the retry also times out, switch to source-first evidence:
|
|
148
|
+
- Run `exa-search` with the original query.
|
|
149
|
+
- Run `exa-search --include-domains` when likely official domains are known.
|
|
150
|
+
- `fetch` the top 1-2 relevant URLs before making claim-level statements.
|
|
151
|
+
- Mark the final answer as `source_mode: "fallback"` or state that it was assembled from fetched sources after the original search failed.
|
|
152
|
+
|
|
153
|
+
Agent timeout handling contract: on `error_type: "timeout"`, inspect `timeout_phase` and `provider_attempts`, then retry the same search at most once with `--extra-sources 1`, for example `smart-search search ... --timeout 300 --extra-sources 1 --format json --output PATH`. Set the agent's command execution timeout at least 30 seconds above the smart-search total budget (at least 330 seconds for the default 300 seconds), or run it in the background, so the agent does not kill it before structured results return. If the retry also times out, switch to source-first fallback with `exa-search`, `exa-search --include-domains`, and fetched evidence, and label the evidence mode as `source_mode: "fallback"` or equivalent prose.
|
|
154
|
+
|
|
155
|
+
## Guardrails
|
|
156
|
+
|
|
157
|
+
- Prefer JSON for agent parsing and markdown for fetched page text intended for reading.
|
|
158
|
+
- Use `--output` for multi-source work, long pages, or anything the answer may need to cite later.
|
|
159
|
+
- Keep `--extra-sources` small (`1` to `3`) unless the user asks for broad coverage.
|
|
160
|
+
- Do not cite unread `sources` or model `primary_sources` as proof for a sentence in `content`; fetch the URL first. `extra_sources` remains an empty compatibility list.
|
|
161
|
+
- Prefer `exa-search --include-domains` for official documentation when likely domains are known.
|
|
162
|
+
- Do not expose API keys. Treat `doctor` output as safe only because it is expected to mask secrets.
|
|
163
|
+
- In this CLI-first workflow, native `web_search` is disabled unless the user explicitly configures another approved route.
|
|
164
|
+
- If `doctor` or a command fails, report the failure and recovery steps; do not silently fall back to another web-search route.
|
|
165
|
+
- Do not use legacy MCP tool names in prompts, notes, or generated instructions for this workflow.
|
|
166
|
+
- Treat key rotation as a hard safety gate when previous key values were pasted into chat or logs.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# Deep Research Mode
|
|
2
|
+
|
|
3
|
+
## Deep Research Skill Contract
|
|
4
|
+
|
|
5
|
+
This contract keeps Deep Research capability-based and evidence-first:
|
|
6
|
+
`smart-search deep` only plans, `smart-search research` executes live work, and
|
|
7
|
+
claim-level conclusions require fetched evidence. Evidence paths come from an
|
|
8
|
+
explicit `--evidence-dir` or the CLI's platform temporary directory; the
|
|
9
|
+
omitted-directory runtime default is `tempfile.gettempdir()/smart-search-evidence/<timestamp>-<slug>`.
|
|
10
|
+
Preserve the planned `steps[].command --output` value and matching
|
|
11
|
+
`steps[].output_path`.
|
|
12
|
+
|
|
13
|
+
## Table of Contents
|
|
14
|
+
|
|
15
|
+
- Trigger and boundary
|
|
16
|
+
- Offline planner and live executor
|
|
17
|
+
- Planner shape
|
|
18
|
+
- Required field semantics
|
|
19
|
+
- Step contract
|
|
20
|
+
- Capability boundaries
|
|
21
|
+
- Live executor output
|
|
22
|
+
- Closeout lessons
|
|
23
|
+
- Smoke coverage
|
|
24
|
+
|
|
25
|
+
## Trigger And Boundary
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
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. Deep Research must not require fixed topic recipe ids such as `current_market_research`, `product_comparison_research`, `technical_docs_research`, `news_or_policy_research`, `claim_verification_research`, or `url_first_research`; fixed topic recipe ids are not required schema.
|
|
30
|
+
|
|
31
|
+
Deep Research does not change default `smart-search search` behavior and does not depend on an MCP session.
|
|
32
|
+
|
|
33
|
+
## Offline Planner And Live Executor
|
|
34
|
+
|
|
35
|
+
- `smart-search deep` is the public offline planner command and a public planner entrypoint, not an executor. It does not call providers, run `doctor`, or fetch pages by default.
|
|
36
|
+
- `smart-search research` is the public live executor. It uses the plan's question candidates, then selects and executes actions in a bounded loop with Jev or local routing; it does not execute the offline `steps[].command` list. The default returns evidence; optional model synthesis is controlled separately.
|
|
37
|
+
- Before manual execution, run `smart-search deep "question" --format json` and use the returned `research_plan` as your planning artifact.
|
|
38
|
+
- Use `smart-search research "question" --format json` when the user wants the CLI to run live Deep Research end to end instead of only planning.
|
|
39
|
+
|
|
40
|
+
Optional manual orchestration (use `research` directly for automatic execution):
|
|
41
|
+
|
|
42
|
+
1. Run `smart-search doctor --format json` as preflight when configuration is uncertain.
|
|
43
|
+
2. Call `smart-search deep "question" --format json` to create an offline `research_plan`.
|
|
44
|
+
3. Inspect `intent_signals`, `decomposition`, and `capability_plan`; do not choose fixed topic recipe ids.
|
|
45
|
+
4. Execute planned `smart-search search ... --validation balanced --extra-sources 1..3` steps for broad discovery and read routing metadata.
|
|
46
|
+
5. Execute planned `exa-search`, `exa-similar`, `zhipu-search`, `context7-library`, `context7-docs`, or `map` only when their capability boundary matches the intent.
|
|
47
|
+
6. Use `fetch` on key URLs before making claim-level statements.
|
|
48
|
+
7. Run `gap_check`: if an important claim lacks fetched evidence, fetch another source or mark the claim/source as unverified.
|
|
49
|
+
|
|
50
|
+
Default evidence policy is `fetch_before_claim`: key claims in the final answer must be supported by fetched page text. Treat unread `sources` and model `primary_sources` as discovery candidates until fetched; `extra_sources` is an empty compatibility list. Final answers should include fetched evidence, unverified candidate sources, and key commands used.
|
|
51
|
+
|
|
52
|
+
## Planner Shape
|
|
53
|
+
|
|
54
|
+
Use this shape as the planning artifact:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"mode": "deep_research",
|
|
59
|
+
"query_mode": "deep",
|
|
60
|
+
"question": "user question",
|
|
61
|
+
"trigger_source": "explicit_cli",
|
|
62
|
+
"difficulty": "standard|high",
|
|
63
|
+
"intent_signals": {
|
|
64
|
+
"recency_requirement": "none|recent|current",
|
|
65
|
+
"docs_api_intent": false,
|
|
66
|
+
"locale_domain_scope": "global|china|known_domains|mixed",
|
|
67
|
+
"known_url": false,
|
|
68
|
+
"source_authority_need": "normal|high",
|
|
69
|
+
"claim_risk": "low|medium|high",
|
|
70
|
+
"cross_validation_need": "normal|high",
|
|
71
|
+
"breadth_depth_budget": "quick|standard|deep"
|
|
72
|
+
},
|
|
73
|
+
"decomposition": [
|
|
74
|
+
{
|
|
75
|
+
"id": "sq1",
|
|
76
|
+
"question": "subquestion",
|
|
77
|
+
"reason": "why this subquestion is needed",
|
|
78
|
+
"required_capabilities": ["broad_discovery"]
|
|
79
|
+
}
|
|
80
|
+
],
|
|
81
|
+
"capability_plan": [
|
|
82
|
+
{
|
|
83
|
+
"capability": "broad_discovery",
|
|
84
|
+
"tools": ["search"],
|
|
85
|
+
"reason": "Find the initial answer shape and candidate sources."
|
|
86
|
+
}
|
|
87
|
+
],
|
|
88
|
+
"preflight": {
|
|
89
|
+
"tool": "doctor",
|
|
90
|
+
"command": "smart-search doctor --format json",
|
|
91
|
+
"when": "configuration or availability is uncertain"
|
|
92
|
+
},
|
|
93
|
+
"evidence_policy": "fetch_before_claim",
|
|
94
|
+
"steps": [
|
|
95
|
+
{
|
|
96
|
+
"id": "s1",
|
|
97
|
+
"subquestion_id": "sq1",
|
|
98
|
+
"tool": "search",
|
|
99
|
+
"purpose": "broad discovery",
|
|
100
|
+
"command": "smart-search search \"query\" --validation balanced --extra-sources 1 --format json --output \"<evidence-dir>/YYYYMMDD-HHMM-topic/01-search.json\"",
|
|
101
|
+
"output_path": "<evidence-dir>/YYYYMMDD-HHMM-topic/01-search.json"
|
|
102
|
+
}
|
|
103
|
+
],
|
|
104
|
+
"gap_check": {
|
|
105
|
+
"required": true,
|
|
106
|
+
"rule": "fetch missing evidence for key claims or downgrade them to unverified candidates"
|
|
107
|
+
},
|
|
108
|
+
"final_answer_policy": "cite fetched evidence, list unverified candidates, and include key commands",
|
|
109
|
+
"usage_boundary": {
|
|
110
|
+
"search": "smart-search search runs live fast/broad search immediately.",
|
|
111
|
+
"deep": "smart-search deep is an offline planner; it does not execute provider calls or fetch pages.",
|
|
112
|
+
"execution": "An AI agent or user executes the listed steps with existing CLI commands, then performs gap_check."
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Required Field Semantics
|
|
118
|
+
|
|
119
|
+
- `mode`: always `deep_research`.
|
|
120
|
+
- `query_mode`: always `deep`.
|
|
121
|
+
- `question`: the user's research question.
|
|
122
|
+
- `trigger_source`: usually `explicit_cli`.
|
|
123
|
+
- `difficulty`: `standard` or `high`.
|
|
124
|
+
- `intent_signals`: dimensional signals such as `recency_requirement`, `docs_api_intent`, `locale_domain_scope`, `known_url`, `source_authority_need`, `claim_risk`, `cross_validation_need`, and `breadth_depth_budget`.
|
|
125
|
+
- `decomposition`: subquestions for complex research, each with `id`, `question`, `reason`, and `required_capabilities`.
|
|
126
|
+
- `capability_plan`: the selected capability needs and the CLI tools chosen for each need.
|
|
127
|
+
- `evidence_policy`: default `fetch_before_claim`.
|
|
128
|
+
- `preflight`: `doctor` guidance. `deep` does not execute this by default.
|
|
129
|
+
- `steps`: ordered CLI command steps.
|
|
130
|
+
- `gap_check`: how the agent verifies that key claims have fetched evidence or downgrades unsupported claims to unverified candidates.
|
|
131
|
+
- `final_answer_policy`: how to cite fetched evidence and list unverified candidates.
|
|
132
|
+
- `usage_boundary`: user-facing distinction between fast live `search`, offline `deep` planning, and later step execution.
|
|
133
|
+
- `allowed_tools`, `evidence_dir`, and `elapsed_ms` may appear in planner output and should be preserved when saving evidence.
|
|
134
|
+
- `evidence_dir`: the explicit `--evidence-dir` value, or a generated `smart-search-evidence` directory under `tempfile.gettempdir()` when omitted.
|
|
135
|
+
|
|
136
|
+
`smart-search deep` is offline by default: `preflight.executed_by_deep_command=false`, no provider calls are made, and live research only happens when an AI agent or user executes `steps[].command` or calls `smart-search research`.
|
|
137
|
+
|
|
138
|
+
## Step Contract
|
|
139
|
+
|
|
140
|
+
Allowed `tool` values are `search`, `exa-search`, `exa-similar`, `zhipu-search`, `context7-library`, `context7-docs`, `fetch`, and `map`; these are the only valid `steps[].tool` values and map to existing CLI commands only. `doctor` is a `preflight` action, not a `steps[]` item. Simple plans may have one subquestion; complex plans should use 2-6 subquestions unless the user explicitly asks for exhaustive coverage.
|
|
141
|
+
|
|
142
|
+
Each `steps[]` item must include `id`, `subquestion_id`, `tool`, `purpose`, `command`, and `output_path`. `steps[].command` and `steps[].output_path` are one contract: the `--output` path embedded in the executable command must match `output_path`, otherwise the AI agent cannot reliably find saved evidence.
|
|
143
|
+
|
|
144
|
+
Prefer PowerShell-safe quoted commands in generated plans because Windows users often copy planned steps directly from Markdown or JSON output. Avoid hard-coding operating-system-specific roots in reusable examples; use `--evidence-dir PATH` or the CLI-generated `evidence_dir`. Windows paths such as `C:\tmp\smart-search-evidence\...` are explicit examples only, not the runtime default.
|
|
145
|
+
|
|
146
|
+
## Capability Boundaries
|
|
147
|
+
|
|
148
|
+
- `search`: one selected retrieval channel; use returned `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning` as orchestration signals, not as claim proof.
|
|
149
|
+
- `zhipu-search`: Chinese, domestic, current, policy/regulatory, announcement, and China-local source discovery.
|
|
150
|
+
- `context7-library` and `context7-docs`: library, SDK, API, framework, and documentation intent. Prefer Context7 before Exa for docs/API questions.
|
|
151
|
+
- `exa-search`: low-noise source discovery for official domains, papers, product pages, known domains, and trusted pages. Do not treat Exa as the universal second hop for every high-risk or verification task.
|
|
152
|
+
- `exa-similar`: adjacent-source discovery when a known reliable URL is available.
|
|
153
|
+
- `search --extra-sources N`: result count for the single selected ordinary-search channel (maximum 20); it does not add channels.
|
|
154
|
+
- `anysearch-domains` and `anysearch-search`: experimental vertical search. Inspect domains first, then search a selected domain; do not insert it into the default fallback chain.
|
|
155
|
+
- `sciverse-catalog`, `sciverse-search`, `sciverse-semantic`, `sciverse-read`, and `sciverse-relations`: explicit experimental academic commands. Use them directly when the task needs Sciverse academic fields, semantic paper hits, document chunks, or citation/reference relations; do not insert Sciverse into default Deep Research fallback.
|
|
156
|
+
- `fetch`: page-content evidence. Key claims require fetched page text under `fetch_before_claim`.
|
|
157
|
+
- `map`: site structure exploration before many fetches from one site; not claim evidence by itself.
|
|
158
|
+
|
|
159
|
+
## Live Executor Output
|
|
160
|
+
|
|
161
|
+
Use this form when the user wants the CLI to execute the live workflow directly:
|
|
162
|
+
|
|
163
|
+
```powershell
|
|
164
|
+
smart-search research "question" --budget deep --fallback auto --evidence-dir "<evidence-dir>" --format json --output "research.json"
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`research --fallback auto` permits local outage fallback and follow-up searches. `research --fallback off` disables both, while allowing reads of initially discovered URLs. Jev may choose complementary capabilities, but each provider remains limited to its supported operations. Every attempt records capability, provider, status, error type, latency, and result count.
|
|
168
|
+
|
|
169
|
+
Research output includes `final_answer`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `fallback_used`, `degraded`, `route_policy_version`, and `evidence_dir`. The default report contains evidence excerpts; optional model synthesis uses that same read evidence. Unfetched discovery candidates cannot support citations. If providers are exhausted or evidence cannot close, return the gaps rather than inventing missing claims.
|
|
170
|
+
|
|
171
|
+
Research provider advantage routing:
|
|
172
|
+
|
|
173
|
+
- Context7: library/API/framework docs resolution and docs retrieval.
|
|
174
|
+
- Exa: official domains, papers, product/company pages, date/domain-filtered low-noise discovery, and adjacent-source discovery.
|
|
175
|
+
- Zhipu REST: Chinese, domestic, current, policy, and announcement searches.
|
|
176
|
+
- Zhipu MCP: separate Coding Plan quota route through `web_search_prime` and `webReader`.
|
|
177
|
+
- Tavily: broad source discovery and site map.
|
|
178
|
+
- Jina: known public URL, PDF, and arXiv clean extraction; ReaderLM-v2 requires `JINA_API_KEY`.
|
|
179
|
+
- Firecrawl: robust fetch fallback, JS-heavy/dynamic pages, browser-like extraction, OCR/PDF/structured extraction.
|
|
180
|
+
- AnySearch: explicit vertical intent only, such as CVE, finance, legal, academic, and repository/codebase search.
|
|
181
|
+
- Sciverse: explicit-only academic provider in this release; use direct `sciverse-*` commands rather than `research` fallback.
|
|
182
|
+
|
|
183
|
+
Safe research overrides are `SMART_SEARCH_RESEARCH_PREFERRED_PROVIDERS` and `SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS`. They may reorder or disable providers only inside capabilities the provider already supports; they must not move a provider across capability boundaries.
|
|
184
|
+
|
|
185
|
+
## Closeout Lessons
|
|
186
|
+
|
|
187
|
+
- Budget limits must not break evidence policy. Even `--budget quick` plans must retain at least one `fetch` step when claim-level conclusions are expected, and retained steps must keep valid `subquestion_id` links.
|
|
188
|
+
- If a smoke issue is found, fix the affected docs/code/tests and rerun the affected smoke until it passes or is proven to be an external provider blocker.
|
|
189
|
+
- Final answers assembled from discovery-only output should list unverified candidates rather than presenting them as supported claims.
|
|
190
|
+
|
|
191
|
+
## Smoke Coverage
|
|
192
|
+
|
|
193
|
+
Deep Research smoke matrix for workflow maintenance is mock-full plus live-limited. Mock-full coverage should cover 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, research provider advantage routing, same-capability research fallback, and the rule that fixed topic recipe ids are not required schema.
|
|
194
|
+
|
|
195
|
+
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. Add one small `research` smoke when configured keys make it stable.
|
|
196
|
+
|
|
197
|
+
Standard user-facing Deep Research tests:
|
|
198
|
+
|
|
199
|
+
```powershell
|
|
200
|
+
smart-search deep "深度搜索一下最近的比特币行情" --format json
|
|
201
|
+
smart-search deep "OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选" --budget deep --format json
|
|
202
|
+
smart-search deep "帮我核验这个说法是真是假:某某工具已经完全替代 Tavily 做 AI 搜索了" --format json
|
|
203
|
+
smart-search deep "https://example.com/source" --format json
|
|
204
|
+
```
|