@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.
Files changed (81) hide show
  1. package/LICENSE +21 -0
  2. package/package.json +18 -3
  3. package/runtime/smart-search/_internal/base_library.zip +0 -0
  4. package/runtime/smart-search/_internal/certifi/cacert.pem +3959 -0
  5. package/runtime/smart-search/_internal/certifi/py.typed +0 -0
  6. package/runtime/smart-search/_internal/libpython3.13.so.1.0 +0 -0
  7. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/INSTALLER +1 -0
  8. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/METADATA +171 -0
  9. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/RECORD +298 -0
  10. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/WHEEL +5 -0
  11. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/licenses/AUTHORS.rst +11 -0
  12. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/licenses/LICENSE +27 -0
  13. package/runtime/smart-search/_internal/prompt_toolkit-3.0.53.dist-info/top_level.txt +1 -0
  14. package/runtime/smart-search/_internal/smart_search/__init__.py +1 -0
  15. package/runtime/smart-search/_internal/smart_search/activity.py +279 -0
  16. package/runtime/smart-search/_internal/smart_search/assets/i18n/messages.json +17858 -0
  17. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/SKILL.md +69 -0
  18. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/agents/openai.yaml +3 -0
  19. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/cli-contract.md +21 -0
  20. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/cli-core.md +99 -0
  21. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/command-patterns.md +166 -0
  22. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/deep-research-mode.md +204 -0
  23. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/provider-routing.md +178 -0
  24. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/regression-release.md +46 -0
  25. package/runtime/smart-search/_internal/smart_search/assets/skills/smart-search-cli/references/setup-config.md +133 -0
  26. package/runtime/smart-search/_internal/smart_search/assets/ui/index.html +955 -0
  27. package/runtime/smart-search/_internal/smart_search/cli.py +3651 -0
  28. package/runtime/smart-search/_internal/smart_search/config.py +1302 -0
  29. package/runtime/smart-search/_internal/smart_search/desktop_backend.py +709 -0
  30. package/runtime/smart-search/_internal/smart_search/desktop_catalog.py +166 -0
  31. package/runtime/smart-search/_internal/smart_search/desktop_cli.py +209 -0
  32. package/runtime/smart-search/_internal/smart_search/desktop_entry.py +19 -0
  33. package/runtime/smart-search/_internal/smart_search/desktop_environment.py +629 -0
  34. package/runtime/smart-search/_internal/smart_search/desktop_skills.py +129 -0
  35. package/runtime/smart-search/_internal/smart_search/desktop_updates.py +160 -0
  36. package/runtime/smart-search/_internal/smart_search/desktop_worker.py +117 -0
  37. package/runtime/smart-search/_internal/smart_search/i18n.py +135 -0
  38. package/runtime/smart-search/_internal/smart_search/intent_router.py +253 -0
  39. package/runtime/smart-search/_internal/smart_search/jev.py +473 -0
  40. package/runtime/smart-search/_internal/smart_search/jev_search.py +719 -0
  41. package/runtime/smart-search/_internal/smart_search/logger.py +43 -0
  42. package/runtime/smart-search/_internal/smart_search/provider_descriptions.py +140 -0
  43. package/runtime/smart-search/_internal/smart_search/provider_errors.py +137 -0
  44. package/runtime/smart-search/_internal/smart_search/provider_health.py +277 -0
  45. package/runtime/smart-search/_internal/smart_search/providers/__init__.py +27 -0
  46. package/runtime/smart-search/_internal/smart_search/providers/anysearch.py +336 -0
  47. package/runtime/smart-search/_internal/smart_search/providers/base.py +41 -0
  48. package/runtime/smart-search/_internal/smart_search/providers/context7.py +153 -0
  49. package/runtime/smart-search/_internal/smart_search/providers/exa.py +191 -0
  50. package/runtime/smart-search/_internal/smart_search/providers/jina.py +124 -0
  51. package/runtime/smart-search/_internal/smart_search/providers/openai_compatible.py +977 -0
  52. package/runtime/smart-search/_internal/smart_search/providers/sciverse.py +351 -0
  53. package/runtime/smart-search/_internal/smart_search/providers/tinyfish.py +213 -0
  54. package/runtime/smart-search/_internal/smart_search/providers/xai_responses.py +242 -0
  55. package/runtime/smart-search/_internal/smart_search/providers/zhipu.py +172 -0
  56. package/runtime/smart-search/_internal/smart_search/providers/zhipu_mcp.py +287 -0
  57. package/runtime/smart-search/_internal/smart_search/sciverse_schema.py +437 -0
  58. package/runtime/smart-search/_internal/smart_search/service.py +4302 -0
  59. package/runtime/smart-search/_internal/smart_search/skill_installer.py +549 -0
  60. package/runtime/smart-search/_internal/smart_search/skill_maintenance.py +181 -0
  61. package/runtime/smart-search/_internal/smart_search/sources.py +429 -0
  62. package/runtime/smart-search/_internal/smart_search/state_files.py +53 -0
  63. package/runtime/smart-search/_internal/smart_search/ui_api.py +246 -0
  64. package/runtime/smart-search/_internal/smart_search/ui_metadata.py +698 -0
  65. package/runtime/smart-search/_internal/smart_search/ui_server.py +506 -0
  66. package/runtime/smart-search/_internal/smart_search/utils.py +220 -0
  67. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/INSTALLER +1 -0
  68. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/METADATA +97 -0
  69. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/RECORD +105 -0
  70. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/REQUESTED +0 -0
  71. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/WHEEL +5 -0
  72. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/direct_url.json +1 -0
  73. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/entry_points.txt +2 -0
  74. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/licenses/LICENSE +21 -0
  75. package/runtime/smart-search/_internal/smart_search-0.1.26.dist-info/top_level.txt +1 -0
  76. package/runtime/smart-search/_internal/wcwidth/_wcwidth_c.abi3.so +0 -0
  77. package/runtime/smart-search/_internal/wcwidth/_wcwidth_c.pyi +77 -0
  78. package/runtime/smart-search/_internal/wcwidth/py.typed +0 -0
  79. package/runtime/smart-search/package.json +49 -0
  80. package/runtime/smart-search/smart-search +0 -0
  81. 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,3 @@
1
+ display_name: Smart Search CLI
2
+ short_description: Source-backed web research via CLI
3
+ default_prompt: Use $smart-search-cli to research this current web question.
@@ -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
+ ```