bailian-web-search

# Bailian web search routing (`bailian-web-search`) **CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): Provider selection and consent, Version & updates (pre-flight checklist), Call attribution (every Agent `bl` command), Setup & auth, and CLI errors: report an issue. If that protocol file is missing, stop and run `bl skill init`; do not guess auth/consent.** **Call attribution:** Examples below and in `reference/` stay bare `bl …`. When running a command, wrap it with [`bailian-protocol` → Call attribution](../bailian-protocol/SKILL.md#call-attribution-mandatory-for-every-agent-bl-command) (bash or PowerShell). One sample for this skill (`BAILIAN_SKILL_NAME=bailian-web-search`; replace `codex` with this host). `bl config` / `bl text chat` are owned by `bailian-cli`. ```bash BAILIAN_CALLER_TYPE=agent BAILIAN_CALLER_NAME=codex BAILIAN_SKILL_NAME=bailian-web-search BAILIAN_SKILL_VERSION=2.5.0 bl search web --query "阿里云百炼最新功能" ``` > **Scope:** model-aware routing for web search inside Agent-driven `bl` workflows — this skill owns the routing decision only. > Command flags / usage / examples: Read skill `bailian-cli` reference if installed; else `bl search web --help` / `bl text chat --help` — do not guess flags. > > **Install (supported):** `bl skill init` Token Plan keys do not authorize Bailian MCP search — never route them to `bl search web`. ## Routing workflow ### Step 1 — Identify the active model identity Wrap with Call attribution (`BAILIAN_SKILL_NAME=bailian-cli`). No auth needed: ```bash bl config show --output json ``` Treat the connection as **Token Plan** when **either** condition holds — this mirrors the CLI's own endpoint detection (`usesTokenPlanEndpoint`), so routing stays consistent with command behavior: - `config` (active profile name) is `token-plan`, **or** - the hostname of `base_url` matches `token-plan.<region>.maas.aliyuncs.com` (e.g. `https://token-plan.cn-beijing.maas.aliyuncs.com`). Do not rely on the profile name alone: users can create additional Token Plan profiles under custom names, and only the Base URL host check catches those. Anything else → **default** identity. ### Step 2 — Route by identity | Condition | Route | Notes | | ------------------------- | ------------------------------- | --------------------------------------------------- | | Token Plan model identity | Model-native path | Preferred — the only path Token Plan keys authorize | | Any other model / default | MCP path | Default for regular DashScope API keys | | MCP path (eligible fail) | Model-native path, exactly once | Fallback — only for the failure classes below | **User override:** if the user names a specific path or command, follow it **except** under Token Plan identity: do not call `bl search web` even if the user asks for MCP — explain that Token Plan keys cannot authorize Bailian MCP search, then use the model-native path (or ask once whether to switch profile / key). ### Model-native path (Token Plan preferred / fallback target) ```bash bl text chat --api responses --tool '{"type":"web_search"}' --message "搜索近期的阿里云新闻" ``` - The Responses API enables native web search via the tool definition `{"type":"web_search"}`. - Requires a model with native web search support (Qwen3.7+). **Do not hardcode `--model`:** omit it so the CLI uses `default_text_model` / built-in default; only pass `--model` when the user named one. - Write `--message` in the user's language; the reply language follows the prompt (see `bailian-protocol` → Respond in the user's language). - Flags / usage: Read skill `bailian-cli` if installed, else `bl text chat --help`. ### MCP path (default) ```bash bl search web --query "阿里云百炼最新功能" ``` - Requires the WebSearch MCP to be activated for the current key; on the not-activated error the CLI appends an activation hint with the marketplace URL — relay it to the user. - Flags / usage: Read skill `bailian-cli` if installed, else `bl search web --help`. ### Fallback (MCP → model-native, exactly once) **Do not** fall back on every non-zero exit. Fall back **only** when `bl search web` fails for one of these classes (match stderr / message): - **auth / permission** — key not valid for the MCP service (e.g. Token Plan key misrouted by identity detection), - **MCP not activated** — `MCP request failed: 404` with `未开通` / `MCP不存在` / `MCP_IS_INVALID` (CLI may append an activation hint), - **MCP transport** — 405 / Streamable-HTTP unsupported, or clear network / timeout / DNS failures reaching the MCP endpoint. **Do not fall back** for: missing `--query` / USAGE errors, rate limits, content-policy / business errors from a successful MCP session, or empty-but-successful result sets. Report those verbatim and stop (or ask the user); do not burn a Responses call. Fallback discipline: 1. Re-issue the same query via the model-native path (omit `--model` unless the user named one). 2. If the fallback succeeds, tell the user the MCP path failed and — when the not-activated hint appeared — that activating the WebSearch MCP restores the default path. 3. If the fallback also fails, stop and report both errors verbatim; follow the issue-reporting flow in `bailian-protocol` (ask once). Never loop retries. ## Quick examples ```bash # Step 1: identify the active model identity bl config show --output json # Token Plan identity → model-native web search (no --model unless user named one) bl text chat --api responses --tool '{"type":"web_search"}' --message "搜索近期的阿里云新闻" # Default identity → Bailian MCP search bl search web --query "阿里云百炼最新功能" # Eligible MCP failure → fall back once (same rule: no hardcoded --model) bl text chat --api responses --tool '{"type":"web_search"}' --message "阿里云百炼最新功能" ``` ## Routing reminders - Generic web research the host can do, ordinary Q&A, coding, writing → host-first; do not invoke `bl` (class 1 in `bailian-protocol`). Route only when the user names Bailian / DashScope / `bl` or continues an existing `bl` workflow (class 4). - Knowledge-base / RAG over Bailian corpora → hub skill `bailian-cli` (`bl knowledge`), not this skill. - Summarize search results in the user's language; on the model-native path the CLI injects no default language — if a fixed language is required, pass `--system` in that language (do not hardcode 简体中文). - Other Bailian workflows (apps / usage / config) → hub skill `bailian-cli`; media generation → `bailian-gen`; fine-tuning → `bailian-finetune`; agents.yaml → `bailian-managed-agent`. Soft hand-off by skill name: Read if installed, else `bl … --help` or prompt `bl skill init`. ## references - [bailian-protocol](../bailian-protocol/SKILL.md) — shared protocol (install via `bl skill init`) - skill `bailian-cli` — hub command reference for `bl search web` / `bl text chat` (soft hand-off; fallback: `--help`)