Back to Details

bailian-web-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bailian web search routing (
bailian-web-search
)

Bailian web search routing (
bailian-web-search
)

CRITICAL — Before executing, MUST read the shared protocol in 
../bailian-protocol/SKILL.md
: Provider selection and consent, Version & updates (pre-flight checklist), 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.
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
.
重要提示 — 执行前必须阅读
../bailian-protocol/SKILL.md
中的共享协议：包括服务商选择与授权同意、版本与更新（预检清单）、设置与鉴权，以及CLI错误上报流程。若该协议文件缺失，请停止操作并执行
bl skill init
；请勿自行猜测鉴权/授权方式。
适用范围： 由Agent驱动的
bl
工作流中，针对联网搜索的模型感知路由 — 本技能仅负责路由决策。 命令参数/用法/示例：若已安装，请查看
bailian-cli
技能参考文档；否则执行
bl search web --help
/ 
bl text chat --help
— 请勿自行猜测参数。
安装（支持方式）： 
bl skill init
Token Plan密钥无法授权Bailian MCP搜索 — 切勿将其路由至
bl search web
。

Routing workflow

路由工作流

Step 1 — Identify the active model identity

步骤1 — 识别当前模型身份

Run (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.
执行以下命令（无需鉴权）：
bash
bl config show --output json
当满足以下任一条件时，判定当前连接为Token Plan身份 — 这与CLI自身的端点检测逻辑（
usesTokenPlanEndpoint
）保持一致，确保路由与命令行为一致：
  • config
    （当前激活的配置文件名称）为
    token-plan
    ，或
  • base_url
    的主机名匹配
    token-plan.<region>.maas.aliyuncs.com
    （例如
    https://token-plan.cn-beijing.maas.aliyuncs.com
    ）。
请勿仅依赖配置文件名称：用户可能在自定义名称下创建额外的Token Plan配置文件，只有Base URL主机检查才能识别此类情况。其他所有情况→默认身份。

Step 2 — Route by identity

步骤2 — 根据身份路由

ConditionRouteNotes
Token Plan model identityModel-native pathPreferred — the only path Token Plan keys authorize
Any other model / defaultMCP pathDefault for regular DashScope API keys
MCP path (eligible fail)Model-native path, exactly onceFallback — 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).
条件路由路径说明
Token Plan模型身份模型原生路径优先选择 — 这是Token Plan密钥唯一授权的路径
其他任何模型/默认身份MCP路径常规DashScope API密钥的默认路径
MCP路径（符合失败条件）模型原生路径，仅执行一次兜底方案 — 仅适用于以下指定的失败类型
用户覆盖规则： 若用户指定了具体路径或命令，需遵循用户要求但Token Plan身份除外：即使用户要求使用MCP，也不得调用
bl search web
— 需向用户说明Token Plan密钥无法授权Bailian MCP搜索，然后使用模型原生路径（或询问用户是否切换配置文件/密钥）。

Model-native path (Token Plan preferred / fallback target)

模型原生路径（Token Plan优先选择/兜底目标）

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
    .
bash
bl text chat --api responses --tool '{"type":"web_search"}' --message "搜索近期的阿里云新闻"
  • Responses API通过工具定义
    {"type":"web_search"}
    实现原生联网搜索。
  • 需要支持原生联网搜索的模型（Qwen3.7+）。请勿硬编码
    --model
    参数：     省略该参数，让CLI使用
    default_text_model
    /内置默认模型；仅当用户指定模型时才传递
    --model
    。
  • --message
    需使用用户的语言编写；回复语言将遵循提示语言（请参考
    bailian-protocol
    →使用用户的语言回复）。
  • 参数/用法：若已安装，请查看
    bailian-cli
    技能文档；否则执行
    bl text chat --help
    。

MCP path (default)

MCP路径（默认）

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
    .
bash
bl search web --query "阿里云百炼最新功能"
  • 当前密钥需已激活WebSearch MCP；若出现未激活错误，CLI会附加包含市场URL的激活提示 — 需将该提示转发给用户。
  • 参数/用法：若已安装，请查看
    bailian-cli
    技能文档；否则执行
    bl search web --help
    。

Fallback (MCP → model-native, exactly once)

兜底方案（MCP→模型原生，仅执行一次）

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.
请勿在所有非零退出码时都触发兜底。仅当
bl search web
因以下类型失败时（匹配标准错误输出/消息），才触发兜底：
  • 鉴权/权限问题 — 密钥对MCP服务无效（例如身份检测错误导致Token Plan密钥被错误路由），
  • MCP未激活 — 
    MCP request failed: 404
    且包含
    未开通
    /
    MCP不存在
    /
    MCP_IS_INVALID
    （CLI可能附加激活提示），
  • MCP传输问题 — 405错误/不支持Streamable-HTTP，或连接MCP端点时出现明确的网络/超时/DNS故障。
请勿触发兜底的情况：缺失
--query
参数/用法错误、速率限制、MCP会话成功但返回内容策略/业务错误，或返回空结果但会话成功。需直接上报这些错误并停止操作（或询问用户）；请勿消耗Responses调用次数。
兜底执行规范：
  1. 通过模型原生路径重新发起相同查询（除非用户指定模型，否则省略
    --model
    参数）。
  2. 若兜底成功，需告知用户MCP路径失败，且当出现未激活提示时，说明激活WebSearch MCP可恢复默认路径。
  3. 若兜底也失败，需停止操作并如实上报两个错误；遵循
    bailian-protocol
    中的错误上报流程（询问用户一次）。切勿循环重试。

Quick examples

快速示例

bash
undefined
bash
undefined

Step 1: identify the active model identity

步骤1：识别当前模型身份

bl config show --output json
bl config show --output json

Token Plan identity → model-native web search (no --model unless user named one)

Token Plan身份 → 模型原生联网搜索（除非用户指定模型，否则不添加--model）

bl text chat --api responses --tool '{"type":"web_search"}' --message "搜索近期的阿里云新闻"
bl text chat --api responses --tool '{"type":"web_search"}' --message "搜索近期的阿里云新闻"

Default identity → Bailian MCP search

默认身份 → Bailian MCP搜索

bl search web --query "阿里云百炼最新功能"
bl search web --query "阿里云百炼最新功能"

Eligible MCP failure → fall back once (same rule: no hardcoded --model)

符合条件的MCP失败 → 兜底一次（规则相同：不硬编码--model）

bl text chat --api responses --tool '{"type":"web_search"}' --message "阿里云百炼最新功能"
undefined
bl text chat --api responses --tool '{"type":"web_search"}' --message "阿里云百炼最新功能"
undefined

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
    .
  • 宿主可完成的通用网络调研、普通问答、编程、写作→优先由宿主处理；请勿调用
    bl
    （
    bailian-protocol
    中的第1类情况）。仅当用户提及Bailian/DashScope/
    bl
    或延续现有
    bl
    工作流时，才进行路由（第4类情况）。
  • 基于Bailian语料库的知识库/RAG→使用核心技能
    bailian-cli
    （
    bl knowledge
    ），而非本技能。
  • 使用用户的语言总结搜索结果；在模型原生路径下，CLI不会注入默认语言 — 若需要固定语言，需传递
    --system
    参数并指定该语言（请勿硬编码简体中文）。
  • 其他Bailian工作流（应用/使用/配置）→使用核心技能
    bailian-cli
    ；媒体生成→使用
    bailian-gen
    ；模型精调→使用
    bailian-finetune
    ；agents.yaml→使用
    bailian-managed-agent
    。通过技能名称进行软切换：若已安装则查看文档，否则执行
    bl … --help
    或提示用户执行
    bl skill init
    。

references

参考文档

  • bailian-protocol — 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
    )
  • bailian-protocol — 共享协议（通过
    bl skill init
    安装）
  • 技能
    bailian-cli
    — 
    bl search web
    /
    bl text chat
    的核心命令参考文档（软切换；兜底方案：执行
    --help
    ）