[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75469":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":14,"forks30d":14,"starsTrendScore":18,"compositeScore":19,"rankGlobal":8,"rankLanguage":8,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":8,"pushedAt":8,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":28,"discoverSource":29},75469,"smartsearch","konbakuyomu\u002Fsmartsearch","konbakuyomu",null,"Python",522,35,1,2,0,19,47,439,57,95.67,"MIT License",false,"main",true,[],"2026-06-12 04:01:18","# smart-search\n\n[简体中文](README.zh-CN.md) | English\n\nCLI-first, skill-driven web research for AI agents and terminal users. `smart-search` gives AI tools one reproducible command layer for live search, source discovery, page fetching, site mapping, provider diagnostics, and offline Deep Research planning.\n\n\u003Cp>\n  \u003Ca href=\"https:\u002F\u002Flinux.do\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLinuxDo-community-1f6feb\" alt=\"LinuxDo\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@konbakuyomu\u002Fsmart-search\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@konbakuyomu\u002Fsmart-search?label=npm%20latest\" alt=\"npm latest\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\nThanks to the [LinuxDo](https:\u002F\u002Flinux.do) community for the discussions that shaped the CLI + Skills workflow.\n\n![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fsvg?repos=konbakuyomu\u002Fsmartsearch&type=Date)\n\n## What It Is\n\n`smart-search` is not an MCP server. It is a normal CLI that AI agents can call through a skill:\n\n```powershell\nsmart-search search \"latest OpenAI Responses API changes\" --format json\nsmart-search fetch \"https:\u002F\u002Fexample.com\u002Farticle\" --format markdown\nsmart-search deep \"Compare Responses API web_search with Chat Completions search\" --format json\n```\n\nThe current architecture has two layers:\n\n| Layer | Responsibility |\n| --- | --- |\n| CLI executor | Runs deterministic commands, provider routing, fallback, JSON\u002FMarkdown output, local config, smoke\u002Fregression checks |\n| Skill \u002F AI orchestration | Infers user intent, chooses normal search vs Deep Research, executes planned CLI steps, writes final source-backed answers |\n\nDefault `smart-search search` stays fast and live. `smart-search deep` is the explicit offline Deep Research planner. It does not call providers, run `doctor`, or fetch pages by default; it emits a `research_plan` that an AI agent or user can execute step by step.\n\n## Install\n\nStable channel:\n\n```powershell\nnpm install -g @konbakuyomu\u002Fsmart-search@latest\nsmart-search --version\nsmart-search setup\n```\n\nTest channel:\n\n```powershell\nnpm install -g @konbakuyomu\u002Fsmart-search@next\nsmart-search --version\n```\n\nThe npm package creates an isolated Python runtime during install. You still use the single `smart-search` command.\n\nPrerequisites:\n\n- Node.js \u002F npm.\n- Python 3.10 or newer available as `python`, `python3`, or `py -3` on Windows.\n\n## Quick Start\n\n1. Configure providers:\n\n```powershell\nsmart-search setup\nsmart-search doctor --format json\n```\n\n2. Run a normal live search:\n\n```powershell\nsmart-search search \"today's important AI news\" --validation balanced --extra-sources 2 --format json\n```\n\n3. Fetch exact page evidence:\n\n```powershell\nsmart-search fetch \"https:\u002F\u002Fexample.com\u002Fsource\" --format markdown --output evidence.md\n```\n\n4. Plan Deep Research:\n\n```powershell\nsmart-search deep \"Deep research recent Bitcoin market movement\" --budget standard --format json\n```\n\n5. Install the skill for AI tools when setup prompts you, or explicitly:\n\n```powershell\nsmart-search setup --non-interactive --install-skills codex,claude,cursor,hermes\n```\n\nSkill installation writes the bundled `smart-search-cli` skill into user-level tool directories such as\n`~\u002F.codex\u002Fskills`, `~\u002F.claude\u002Fskills`, `~\u002F.cursor\u002Fskills`, and `~\u002F.hermes\u002Fskills`. It does not initialize\nTrellis, hooks, agents, or commands. `--skills-root PATH` is only an advanced override for portable or test installs.\n\n## Current Architecture\n\n| Capability | Main commands | Providers | Role |\n| --- | --- | --- | --- |\n| `main_search` | `search` | xAI Responses, OpenAI-compatible Chat Completions | Broad answer generation and synthesis |\n| `docs_search` | `exa-search`, `context7-library`, `context7-docs` | Exa, Context7 | Official docs, SDKs, APIs, framework\u002Flibrary evidence |\n| `web_search` | `zhipu-search`, intent-routed reinforcement inside `search` | Zhipu, Tavily, Firecrawl | Chinese, domestic, current, domain-filtered, or supplementary web discovery |\n| `web_fetch` | `fetch` | Tavily, Firecrawl | Exact URL content extraction for evidence |\n| `site_map` | `map` | Tavily | Site\u002Fdocumentation structure discovery |\n| `deep_planner` | `deep` \u002F `dr` | Local planner only | Offline plan generation; no provider call by default |\n\nFallback is same-capability only:\n\n| Capability | Fallback chain |\n| --- | --- |\n| `main_search` | xAI Responses -> OpenAI-compatible |\n| `docs_search` | Exa -> Context7 |\n| `web_search` | Zhipu -> Tavily -> Firecrawl |\n| `web_fetch` | Tavily -> Firecrawl |\n\nThe CLI exposes observability fields such as `routing_decision`, `provider_attempts`, `providers_used`, `fallback_used`, `primary_sources`, `extra_sources`, and `source_warning`.\n\n`extra_sources` are discovery candidates. For high-risk claims, news, policy, finance, health, selection decisions, and serious reviews, fetch key pages first and cite fetched text rather than treating a broad search answer as proof.\n\n## Deep Research\n\nUse normal search when you want a fast answer:\n\n```powershell\nsmart-search search \"React useEffect cleanup docs\" --format json\n```\n\nUse Deep Research when you want planning, decomposition, cross-checking, or strict evidence:\n\n```powershell\nsmart-search deep \"OpenAI Responses API web_search vs Chat Completions search: which should I use?\" --budget deep --format json\nsmart-search dr \"https:\u002F\u002Fexample.com\u002Fsource\" --format json\n```\n\nDeep Research output includes:\n\n- `mode=\"deep_research\"` and `query_mode=\"deep\"`;\n- `intent_signals`, such as recency, docs\u002FAPI intent, known URL, claim risk, source authority, and cross-validation need;\n- `decomposition`, with 1-6 subquestions depending on budget and difficulty;\n- `capability_plan`, choosing from existing CLI blocks;\n- `steps[]`, each with `tool`, `purpose`, `command`, `output_path`, and `subquestion_id`;\n- `evidence_policy=\"fetch_before_claim\"`;\n- `gap_check`, which fetches missing evidence or downgrades unsupported claims.\n- `usage_boundary`, which explains that `search` is live, `deep` is offline planning, and execution happens through planned commands.\n\nDeep Research is not a fixed topic recipe system. Market research, product comparison, technical docs, news or policy, claim verification, and URL-first prompts are examples of user language, not required schema enums.\n\nAllowed planned tools are:\n\n```text\nsearch, exa-search, exa-similar, zhipu-search, context7-library, context7-docs, fetch, map\n```\n\n`doctor` is preflight, not a research step. `smart-search deep` itself is offline; live research starts when an agent or user executes `steps[].command`.\n\nGood user-facing smoke prompts:\n\n```powershell\nsmart-search deep \"深度搜索一下最近的比特币行情\" --format json\nsmart-search deep \"OpenAI Responses API web_search 和 Chat Completions 联网搜索怎么选\" --budget deep --format json\nsmart-search deep \"帮我核验这个说法是真是假：某某工具已经完全替代 Tavily 做 AI 搜索了\" --format json\nsmart-search deep \"https:\u002F\u002Fexample.com\u002Fsource\" --format json\n```\n\n## Provider And API Key Guide\n\nUse `smart-search setup` for normal configuration. Environment variables remain supported for CI and advanced users.\n\n| Provider \u002F route | Used for | Main config keys | Official docs | Key \u002F dashboard |\n| --- | --- | --- | --- | --- |\n| xAI Responses API | Primary live search with `web_search,x_search` tools | `XAI_API_KEY`, `XAI_API_URL`, `XAI_MODEL`, `XAI_TOOLS` | [docs.x.ai](https:\u002F\u002Fdocs.x.ai\u002Fdocs) | [xAI API keys](https:\u002F\u002Fconsole.x.ai\u002Fteam\u002Fdefault\u002Fapi-keys) |\n| OpenAI-compatible Chat Completions | Primary search through OpenAI or a compatible relay; no xAI search tools are sent here | `OPENAI_COMPATIBLE_API_URL`, `OPENAI_COMPATIBLE_API_KEY`, `OPENAI_COMPATIBLE_MODEL` | [OpenAI platform docs](https:\u002F\u002Fplatform.openai.com\u002Fdocs) | [OpenAI API keys](https:\u002F\u002Fplatform.openai.com\u002Fapi-keys) or your relay provider |\n| Exa | Low-noise official docs, API, paper, product, trusted-page discovery | `EXA_API_KEY` | [Exa docs](https:\u002F\u002Fdocs.exa.ai\u002F) | [Exa API keys](https:\u002F\u002Fdashboard.exa.ai\u002Fapi-keys) |\n| Context7 | SDK, library, framework, and API documentation fallback | `CONTEXT7_API_KEY`, `CONTEXT7_BASE_URL` | [Context7 docs](https:\u002F\u002Fcontext7.com\u002Fdocs) | [Context7](https:\u002F\u002Fcontext7.com\u002F) |\n| Zhipu Web Search API | Chinese, domestic, current, or domain-filtered web discovery | `ZHIPU_API_KEY`, `ZHIPU_API_URL`, `ZHIPU_SEARCH_ENGINE` | [Zhipu web search docs](https:\u002F\u002Fdocs.bigmodel.cn\u002Fcn\u002Fguide\u002Ftools\u002Fweb-search) | [Zhipu API keys](https:\u002F\u002Fopen.bigmodel.cn\u002Fusercenter\u002Fapikeys) |\n| Tavily | Extra web sources, URL fetch, and site map | `TAVILY_API_URL`, `TAVILY_API_KEY` | [Tavily docs](https:\u002F\u002Fdocs.tavily.com\u002F) | [Tavily app](https:\u002F\u002Fapp.tavily.com\u002Fhome) |\n| Firecrawl | Fetch fallback and supplementary web sources | `FIRECRAWL_API_URL`, `FIRECRAWL_API_KEY` | [Firecrawl docs](https:\u002F\u002Fdocs.firecrawl.dev\u002F) | [Firecrawl API keys](https:\u002F\u002Fwww.firecrawl.dev\u002Fapp\u002Fapi-keys) |\n\nImportant boundaries:\n\n- xAI official live search uses the Responses API `\u002Fresponses` route through `XAI_*`. Compatible relays and gateways use Chat Completions `\u002Fchat\u002Fcompletions` through `OPENAI_COMPATIBLE_*`.\n- Legacy `SMART_SEARCH_API_URL`, `SMART_SEARCH_API_KEY`, `SMART_SEARCH_API_MODE`, `SMART_SEARCH_MODEL`, and `SMART_SEARCH_XAI_TOOLS` are not supported config keys. Use `XAI_*` or `OPENAI_COMPATIBLE_*` explicitly.\n- Do not force xAI `web_search` \u002F `x_search` tools or legacy `search_parameters` into the OpenAI-compatible Chat Completions route.\n- Zhipu support is the Web Search API route, not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.\n- `ZHIPU_SEARCH_ENGINE` defaults to `search_std`. Supported official values include `search_std`, `search_pro`, `search_pro_sogou`, and `search_pro_quark`; custom values remain allowed for future services.\n- `TAVILY_API_URL` affects Tavily only. It does not proxy Zhipu. For Tavily Hikari \u002F pooled endpoints, use `https:\u002F\u002F\u003Chost>\u002Fapi\u002Ftavily`; setup normalizes root-host or `\u002Fmcp` inputs to that REST base.\n- `FIRECRAWL_API_URL` defaults to `https:\u002F\u002Fapi.firecrawl.dev\u002Fv2`.\n\nNon-interactive setup example:\n\n```powershell\nsmart-search setup --non-interactive `\n  --xai-api-key \"your-xai-key\" `\n  --xai-model \"grok-4-fast\" `\n  --openai-compatible-api-url \"https:\u002F\u002Fapi.openai.com\u002Fv1\" `\n  --openai-compatible-api-key \"your-openai-or-relay-key\" `\n  --openai-compatible-model \"gpt-4.1\" `\n  --validation-level \"balanced\" `\n  --fallback-mode \"auto\" `\n  --minimum-profile \"standard\" `\n  --exa-key \"your-exa-key\" `\n  --context7-key \"your-context7-key\" `\n  --zhipu-key \"your-zhipu-key\" `\n  --zhipu-api-url \"https:\u002F\u002Fopen.bigmodel.cn\u002Fapi\" `\n  --zhipu-search-engine \"search_pro_sogou\" `\n  --tavily-api-url \"https:\u002F\u002Fapi.tavily.com\" `\n  --tavily-key \"your-tavily-key\" `\n  --firecrawl-api-url \"https:\u002F\u002Fapi.firecrawl.dev\u002Fv2\" `\n  --firecrawl-key \"your-firecrawl-key\"\n```\n\nMinimum profile defaults to `standard`, requiring at least:\n\n- one `main_search` provider: xAI Responses or OpenAI-compatible;\n- one `docs_search` provider: Exa or Context7;\n- one `web_fetch` provider: Tavily or Firecrawl.\n\nMissing required capabilities fail closed with a configuration error. Use `SMART_SEARCH_MINIMUM_PROFILE=off` only for local experiments.\n\nLocal config path:\n\n- Windows default: `%LOCALAPPDATA%\\smart-search\\config.json`.\n- Linux\u002FmacOS default: `~\u002F.config\u002Fsmart-search\u002Fconfig.json`.\n- `SMART_SEARCH_CONFIG_DIR` is an advanced override for CI, containers, sandboxes, or portable installs.\n- Earlier Windows source builds defaulted to `~\\.config\\smart-search\\config.json`, while some installs were already pinned to `%LOCALAPPDATA%\\smart-search` through `SMART_SEARCH_CONFIG_DIR`. If the new Windows default file is missing but the old home config exists, Smart Search reads the old file as `legacy_windows_home` so upgrades do not lose configuration. `doctor` reports the active path, default path, old home path, `SMART_SEARCH_CONFIG_DIR`, and whether that override merely matches the current default.\n\nProvider timeouts:\n\n- `TAVILY_TIMEOUT_SECONDS` controls the Tavily `doctor` connectivity check timeout and defaults to `30`.\n- Raise it for slower Tavily Hikari \u002F pooled \u002F community endpoints before treating the provider as unhealthy.\n\n## Commands\n\n| Command | Alias | Purpose |\n| --- | --- | --- |\n| `search` | `s` | Fast live search and broad synthesis |\n| `deep` | `dr` | Offline Deep Research plan |\n| `fetch` | `f` | Fetch one URL as JSON, Markdown, or content |\n| `map` | `m` | Map a website structure |\n| `exa-search` | `exa`, `x` | Exa source discovery |\n| `exa-similar` | `xs` | Similar pages from one URL |\n| `zhipu-search` | `z`, `zp` | Zhipu Web Search API |\n| `context7-library` | `c7`, `ctx7` | Resolve Context7 library candidates |\n| `context7-docs` | `c7d`, `c7docs`, `ctx7-docs` | Fetch Context7 docs |\n| `doctor` | `d` | Masked config and connectivity check |\n| `setup` | `init` | Interactive or scripted setup |\n| `config` | `cfg` | Local config read\u002Fwrite |\n| `model` | `mdl` | Show explicit provider model settings; use `config set XAI_MODEL` or `OPENAI_COMPATIBLE_MODEL` to change them |\n| `smoke` | `sm` | Provider routing smoke tests |\n| `regression` | `reg` | Offline regression checks |\n\nUseful examples:\n\n```powershell\nsmart-search search \"query\" --validation balanced --extra-sources 3 --timeout 90 --format json --output result.json\nsmart-search search \"nba report\" --format content\nsmart-search exa-search \"OpenAI Responses API documentation\" --include-domains platform.openai.com developers.openai.com --num-results 5 --include-text --format json\nsmart-search context7-library \"react\" \"hooks\" --format json\nsmart-search context7-docs \"\u002Ffacebook\u002Freact\" \"useEffect cleanup\" --format json\nsmart-search zhipu-search \"today China AI news\" --search-engine search_pro_sogou --count 5 --format json\nsmart-search exa-similar \"https:\u002F\u002Fexample.com\u002Fsource\" --num-results 5 --format json\nsmart-search fetch \"https:\u002F\u002Fexample.com\u002Fsource\" --format markdown --output page.md\nsmart-search map \"https:\u002F\u002Fdocs.example.com\" --instructions \"Find API reference pages\" --max-depth 1 --limit 50 --format json\nsmart-search doctor --format markdown\nsmart-search smoke --mock --format json\nsmart-search regression\n```\n\n## Output And Evidence Policy\n\nUse JSON for agents and scripts:\n\n```powershell\nsmart-search search \"query\" --format json\nsmart-search doctor --format json\n```\n\nUse Markdown for human-readable reports, detailed diagnostics, source lists, and fetched page text:\n\n```powershell\nsmart-search doctor --format markdown\nsmart-search smoke --mock --format markdown\nsmart-search exa-search \"OpenAI Responses API documentation\" --format markdown\nsmart-search fetch \"https:\u002F\u002Fexample.com\" --format markdown\n```\n\nUse `content` for compact terminal reading:\n\n```powershell\nsmart-search search \"nba report\" --format content\nsmart-search doctor --format content\n```\n\n`content` is intentionally brief. Use `doctor --format markdown` for human troubleshooting and `doctor --format json` for the complete machine-readable contract.\n\nSave multi-source evidence under a stable folder:\n\n```powershell\nsmart-search exa-search \"Reuters Iran Hormuz latest\" --format json --output C:\\tmp\\smart-search-evidence\\iran-hormuz\\01-exa.json\nsmart-search fetch \"https:\u002F\u002Fexample.com\u002Fsource\" --format markdown --output C:\\tmp\\smart-search-evidence\\iran-hormuz\\02-fetch.md\n```\n\nFor claim-level evidence:\n\n1. Discover candidate URLs with `search`, `exa-search`, `zhipu-search`, or `exa-similar`.\n2. Fetch exact URLs with `fetch`.\n3. Cite fetched text in the final answer.\n4. Unsupported key claims must be fetched or downgraded to unverified candidates.\n\n## Troubleshooting\n\nIf `doctor` reports `config_error`:\n\n```powershell\nsmart-search setup\nsmart-search config list --format json\nsmart-search doctor --format markdown\n```\n\nIf search is slow:\n\n- reduce `--extra-sources`;\n- split broad questions into smaller queries;\n- use `exa-search` or `zhipu-search` for source discovery, then `fetch` key pages.\n\nIf installed CLI health is uncertain:\n\n```powershell\nsmart-search --help\nsmart-search --version\nsmart-search regression\nsmart-search smoke --mock --format json\n```\n\nOn Windows npm\u002Fmise installs, verify non-ASCII JSON piping:\n\n```powershell\nsmart-search deep \"深度搜索一下最近的比特币行情\" --format json | ConvertFrom-Json\n```\n\n## Development\n\n```powershell\n.\\.venv\\Scripts\\python.exe -m compileall -q src tests\n.\\.venv\\Scripts\\python.exe -m pytest tests -q\n.\\.venv\\Scripts\\python.exe -m smart_search.cli regression\n.\\.venv\\Scripts\\python.exe -m smart_search.cli smoke --mock --format json\nnpm test\nnpm pack --dry-run\n```\n\n## Release lanes\n\nStable releases use Git tags and npm `latest`:\n\n```powershell\ngit tag v0.1.12\ngit push origin v0.1.12\n```\n\nTest releases use npm prereleases and do not move `latest`. A push to `main` publishes the next `\u003Cpackage.json version>-beta.N` version under npm dist-tag `next`; `N` resets for each stable base version. To avoid publishing an unwanted beta for a stable bump, the `chore(release): bump version to X.Y.Z` branch commit is skipped by the workflow and the matching `vX.Y.Z` tag publishes npm `latest`. For example, after `0.1.10-beta.1` and `0.1.10-beta.2`, the next `main` publish is `0.1.10-beta.3`.\n\nGitHub Actions also supports manual backfill for historical test builds through `workflow_dispatch`. Use an explicit `target_ref` plus an exact version such as `0.1.9-beta.1`, and publish it with a non-`latest` tag such as `backfill`. npm versions are immutable: old `*-dev.*` packages cannot be renamed in place, only superseded by new `*-beta.N` packages and optionally deprecated later with npm owner credentials.\n\nRelease closeout checklist:\n\n1. Verify the registry and tags before changing anything: `npm view @konbakuyomu\u002Fsmart-search versions --json`, `npm view @konbakuyomu\u002Fsmart-search dist-tags --json`, and `gh release list --repo konbakuyomu\u002Fsmartsearch --limit 100`.\n2. For historical beta backfill, publish the replacement `*-beta.N` package through Actions with `create_github_release=false` if the workflow token cannot create releases, then create the missing GitHub prerelease locally with `gh release create vX.Y.Z-beta.N --target \u003Ccommit> --prerelease --latest=false`.\n3. Treat npm `E409` during parallel backfills as a registry concurrency failure, not a version-design failure. Re-run the affected version serially after checking whether the package already exists.\n4. Do a machine-readable gap check: expected beta versions minus npm versions must be empty, and expected `v*beta*` releases minus GitHub prereleases must be empty.\n5. Install the selected test build explicitly, for example `mise use -g \"npm:@konbakuyomu\u002Fsmart-search@0.1.10-beta.3\" -y --pin`, then run `mise reshim`, `where.exe smart-search`, `smart-search --version`, `smart-search regression`, `smart-search smoke --mock --format json`, and a non-ASCII JSON pipe such as `smart-search deep \"深度搜索一下最近的比特币行情\" --format json | ConvertFrom-Json`.\n\n## License\n\nMIT\n","`smart-search` 是一个面向命令行的智能搜索工具，专为AI代理和终端用户提供技能驱动的网络研究功能。它支持实时搜索、资源发现、页面抓取、站点映射、服务提供商诊断以及离线深度研究规划等核心功能，并能够通过简单的命令行调用实现这些操作。项目采用Python编写，具有良好的可扩展性和易用性，支持JSON和Markdown格式输出。适用于需要自动化或半自动化网络信息收集与分析的场景，如开发人员进行技术调研、AI助手执行复杂查询任务等。","2026-06-11 03:52:54","CREATED_QUERY"]