From abad3a6643fc623c24c1d143edd346ac6c2524b6 Mon Sep 17 00:00:00 2001 From: clh02467605 Date: Wed, 19 Aug 2026 17:12:16 +0800 Subject: [PATCH] feat(skills): add bailian-web-search routing skill --- .vite-hooks/pre-commit | 3 +- AGENTS.md | 2 +- docs/agents/skill-change.md | 10 +-- skills/bailian-cli/README.md | 2 +- skills/bailian-cli/README.zh.md | 2 +- skills/bailian-cli/SKILL.md | 8 +- skills/bailian-cli/reference/search.md | 2 + skills/bailian-protocol/SKILL.md | 3 +- skills/bailian-web-search/SKILL.md | 120 +++++++++++++++++++++++++ tools/generate-reference.ts | 17 ++++ tools/release/check.mjs | 1 + 11 files changed, 157 insertions(+), 13 deletions(-) create mode 100644 skills/bailian-web-search/SKILL.md diff --git a/.vite-hooks/pre-commit b/.vite-hooks/pre-commit index 5e6f2b613..8998194bc 100755 --- a/.vite-hooks/pre-commit +++ b/.vite-hooks/pre-commit @@ -14,6 +14,7 @@ git add \ skills/bailian-finetune/SKILL.md \ skills/bailian-finetune/reference \ skills/bailian-managed-agent/SKILL.md \ - skills/bailian-managed-agent/reference + skills/bailian-managed-agent/reference \ + skills/bailian-web-search/SKILL.md vp staged diff --git a/AGENTS.md b/AGENTS.md index 53172a78d..ac772ed0e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ packages/core/src/auth/ # apiKey / console credential 解析与落盘 packages/core/src/client/ # HTTP client / endpoints / console gateway ``` -Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 registry 中全部 `bailian-*`，含共享协议 `bailian-protocol`）。业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent`）执行前读 `skills/bailian-protocol/`；不要依赖 frontmatter `companions`（安装器不强制）。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills//reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步各 `skills/*/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。hub `bailian-cli` 的路由表不复述领域命令明细；SKILL 文案 / 安装约定 / hand-off 见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。 +Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐 registry 中全部 `bailian-*`，含共享协议 `bailian-protocol`）。业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent` / `bailian-web-search`）执行前读 `skills/bailian-protocol/`；不要依赖 frontmatter `companions`（安装器不强制）。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills//reference/`(纳入 git);`tools/sync-skill-metadata.ts` 从 `packages/cli/package.json` 同步各 `skills/*/SKILL.md` 的 `metadata.version`。两者由根脚本 `pnpm run sync:skill-assets` 和 `.vite-hooks/pre-commit` 执行。hub `bailian-cli` 的路由表不复述领域命令明细；SKILL 文案 / 安装约定 / hand-off 见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。 约定: diff --git a/docs/agents/skill-change.md b/docs/agents/skill-change.md index cddbaa32c..a5b6de8c7 100644 --- a/docs/agents/skill-change.md +++ b/docs/agents/skill-change.md @@ -23,11 +23,11 @@ bailian-protocol ← 共享协议（consent / 鉴权 / 版本 / 错误上报） ▲ 靠 `bl skill init` 与业务 skill 同装；非安装器强制 companions │ -┌───────┴────────┬────────────────┬──────────────────┐ -bailian-gen bailian-finetune bailian-managed-agent -（领域路由表） （领域工作流） （IaC 安全闸） - │ │ │ - └────────────────┼──────────────────┘ +┌───────┴────────┬────────────────┬──────────────────┬───────────────────┐ +bailian-gen bailian-finetune bailian-managed-agent bailian-web-search +（领域路由表） （领域工作流） （IaC 安全闸） （搜索路由+兜底） + │ │ │ │ + └────────────────┼──────────────────┴─────────────────────┘ ▼ 软 hand-off（按 skill 名） bailian-cli（hub） hub 路由表：本职命令 + 领域 hand-off 行 diff --git a/skills/bailian-cli/README.md b/skills/bailian-cli/README.md index 3888131e3..e5077b1f8 100644 --- a/skills/bailian-cli/README.md +++ b/skills/bailian-cli/README.md @@ -5,7 +5,7 @@ Agent skill for **Alibaba Cloud Model Studio CLI** (`bl`) resource hub — apps, memory, RAG, usage/quota, MCP, and hub `reference/`. - Shared protocol: `bailian-protocol` (install via `bl skill init`) -- Soft hand-offs (optional skills): `bailian-gen` · `bailian-finetune` · `bailian-managed-agent` +- Soft hand-offs (optional skills): `bailian-gen` · `bailian-finetune` · `bailian-managed-agent` · `bailian-web-search` ```bash bl skill init diff --git a/skills/bailian-cli/README.zh.md b/skills/bailian-cli/README.zh.md index cd0d015f8..b88f7f88e 100644 --- a/skills/bailian-cli/README.zh.md +++ b/skills/bailian-cli/README.zh.md @@ -5,7 +5,7 @@ **阿里云百炼 CLI**（`bl`）的资源管理 Agent 技能 — 应用、记忆、RAG、用量/额度、MCP，以及 hub `reference/`。 - 共享协议：`bailian-protocol`（通过 `bl skill init` 与整家族同装） -- 软 hand-off（可选）：`bailian-gen` · `bailian-finetune` · `bailian-managed-agent` +- 软 hand-off（可选）：`bailian-gen` · `bailian-finetune` · `bailian-managed-agent` · `bailian-web-search` ```bash bl skill init diff --git a/skills/bailian-cli/SKILL.md b/skills/bailian-cli/SKILL.md index cbef593ec..3c680bfd3 100644 --- a/skills/bailian-cli/SKILL.md +++ b/skills/bailian-cli/SKILL.md @@ -12,7 +12,7 @@ description: >- 用户点名百炼 / DashScope / `bl`，或继续既有 `bl` 工作流时直接使用。 共享协议（consent / 版本预检 / 鉴权 / 错误上报）在 bailian-protocol；官方安装 `bl skill init`。 家族路由：生图/生视频/配音/语音合成/转写 → bailian-gen；精调/微调/训练/数据集 → bailian-finetune； - agents.yaml 托管 Agent → bailian-managed-agent。 + agents.yaml 托管 Agent → bailian-managed-agent；联网搜索的模型路由（Token Plan 自带搜索 vs MCP 搜索 + 兜底）→ bailian-web-search。 不要用于普通问答、编程、写作、翻译、摘要、泛搜索，或图片理解等宿主自己能做的任务（普通问答、编程、写作、翻译、摘要、泛搜索不触发）。 未命名用量/额度问题：先问用户使用哪个产品，再运行 `bl usage` / `bl quota` 查询。 --- @@ -23,7 +23,7 @@ description: >- > **Family hub** — This skill owns Bailian resource commands and the hub `reference/` (apps, knowledge, usage, auth, config, …). > Shared protocol → [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md) (install the full family with `bl skill init`). -> Soft hand-offs by skill name (Read if installed; else `bl … --help` / prompt `bl skill init`): `bailian-gen` (media) · `bailian-finetune` (training) · `bailian-managed-agent` (agents.yaml IaC). +> Soft hand-offs by skill name (Read if installed; else `bl … --help` / prompt `bl skill init`): `bailian-gen` (media) · `bailian-finetune` (training) · `bailian-managed-agent` (agents.yaml IaC) · `bailian-web-search` (web search routing). > Do not invoke it for ordinary reasoning, coding, writing, translation, summarization, generic research, or image understanding the host agent can complete directly. > > **Install (supported):** `bl skill init` @@ -40,6 +40,7 @@ Domain skills own their own generated reference trees (soft hand-off — do not - `bailian-gen` → `image` / `video` / `speech` / `omni` / `vision` (fallback: `bl image\|video\|speech\|omni\|vision --help`) - `bailian-finetune` → `dataset` / `finetune` / `deploy` (fallback: `bl dataset\|finetune\|deploy --help`) - `bailian-managed-agent` → `managed-agent` (fallback: `bl managed-agent --help`) +- `bailian-web-search` → web search **routing** (hub still owns `reference/search.md` flags; **must** route via this skill before `bl search web`) Auto-generated from the CLI source at build time (`pnpm --filter bailian-cli run generate:reference`). Before running an unfamiliar command: @@ -58,7 +59,6 @@ Use this table only after the decision table in [`bailian-protocol`](../bailian- | User intent | Command | Notes | | ------------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- | | Explicit Bailian model chat / text execution | `bl text chat` | Default `qwen3.8-max` | -| Search inside a Bailian-scoped workflow | `bl search web` | DashScope MCP search; not for generic web research | | Bailian agent / workflow | `bl app call` | Needs `--app-id` | | Find app by name | `bl app list` then `bl app call` | Console auth | | Bailian app memory CRUD (not host-agent memory) | `bl memory *` | [`reference/memory.md`](reference/memory.md) | @@ -78,6 +78,7 @@ Use this table only after the decision table in [`bailian-protocol`](../bailian- | Image / video / speech / omni / vision | → skill `bailian-gen` | Fallback: `bl image\|video\|speech\|omni\|vision --help` | | Dataset / fine-tune / deploy | → skill `bailian-finetune` | Fallback: `bl dataset\|finetune\|deploy --help` | | agents.yaml IaC / managed-agent sessions | → skill `bailian-managed-agent` | Fallback: `bl managed-agent --help`; `apply`/`destroy` need `--yes` after `plan` | +| Web search (model-aware routing) | → skill `bailian-web-search` | Token Plan vs MCP path + fallback; fallback: `bl search web --help` | Flags, usage, and examples: see hub [`reference/`](reference/index.md) or `bl --help` — do not guess flags. Domain command details live in the owning skill's `reference/`. @@ -116,6 +117,7 @@ schema-export commands. ## Routing reminders - Image/video/audio generation or editing → skill `bailian-gen` (class 3 consent from `bailian-protocol`). Fine-tuning / datasets / deployments → `bailian-finetune`. agents.yaml IaC → `bailian-managed-agent`. Soft hand-off: Read sibling skill if installed; else `bl … --help` or prompt `bl skill init`. Image understanding the host agent can do → host-first; use `bl vision` / `bl omni` only when the user names a Bailian model or the media (video/audio files) exceeds host capability. +- Web search inside a Bailian workflow → skill `bailian-web-search` (model-aware routing: Token Plan → model-native search; default → `bl search web`; MCP failure → fall back once). Generic web research the host can do stays host-first — do not bounce it through `bl`. - Answer ordinary reasoning, coding, writing, translation, summarization, and generic research with the host agent's native capabilities; do not bounce them through `bl text chat` or `bl search web`. - Usage / quota / credits questions that do not name a product → ask which product (Bailian or another AI service) first; run `bl usage` / `bl quota` only after the user picks Bailian or Bailian context is already established. - "Remember this" and memory requests default to the host agent's own memory; `bl memory *` is only for Bailian app memory resources. diff --git a/skills/bailian-cli/reference/search.md b/skills/bailian-cli/reference/search.md index 1c5342eb4..b311f800b 100644 --- a/skills/bailian-cli/reference/search.md +++ b/skills/bailian-cli/reference/search.md @@ -3,6 +3,8 @@ > Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand. > Regenerate: `pnpm --filter bailian-cli run generate:reference`. +> **Agent routing (mandatory):** Before running any `bl search *` command, Read skill `bailian-web-search` if installed and follow its identity-based routing (Token Plan → model-native web search; default → MCP; eligible MCP failures → fall back once). Do **not** call `bl search web` directly from this reference alone — Token Plan keys cannot authorize Bailian MCP search. If that skill is missing, run `bl skill init` or fall back to `bl search web --help` / `bl text chat --help` after checking `bl config show --output json`. + Index: [index.md](index.md) ## Commands in this group diff --git a/skills/bailian-protocol/SKILL.md b/skills/bailian-protocol/SKILL.md index 55d827e35..e8919a05c 100644 --- a/skills/bailian-protocol/SKILL.md +++ b/skills/bailian-protocol/SKILL.md @@ -7,7 +7,7 @@ metadata: description: >- 阿里云百炼 `bl` 家族共享执行协议（consent 确认、版本预检、鉴权/安装、错误上报、本地文件与输出约定）。 不是面向用户意图的业务入口；当任一 bailian-* 业务 skill（bailian-cli / bailian-gen / - bailian-finetune / bailian-managed-agent）执行前需要公共上下文，或用户首次安装/鉴权/`bl` 报错需上报时读取本 skill。 + bailian-finetune / bailian-managed-agent / bailian-web-search）执行前需要公共上下文，或用户首次安装/鉴权/`bl` 报错需上报时读取本 skill。 官方安装为整包：`bl skill init`（与业务 skill 同装）。 --- @@ -51,6 +51,7 @@ After approval, treat Bailian as selected for the current task. Do not ask again | 生图 / 生视频 / 语音 / 图片理解 / 视频理解 / omni / vision | `bailian-gen` | `bl image\|video\|speech\|omni\|vision --help` | | 精调 / 数据集 / 部署 | `bailian-finetune` | `bl dataset\|finetune\|deploy --help` | | agents.yaml IaC | `bailian-managed-agent` | `bl managed-agent --help` | +| 联网搜索 / web search（模型路由 + 兜底） | `bailian-web-search` | `bl search web --help` | | 应用 / 知识库 / 用量 / 鉴权配置等资源 | `bailian-cli` | `bl app\|knowledge\|usage\|auth\|config --help` | **共享协议** vs **软 hand-off**： diff --git a/skills/bailian-web-search/SKILL.md b/skills/bailian-web-search/SKILL.md new file mode 100644 index 000000000..05880ff82 --- /dev/null +++ b/skills/bailian-web-search/SKILL.md @@ -0,0 +1,120 @@ +--- +name: bailian-web-search +metadata: + version: "1.17.0" + requires: + bins: ["bl"] +description: >- + 阿里云百炼联网搜索（web search）入口：为联网搜索 / 网页搜索 / 查最新资讯做路径分发。 + 先识别当前连接身份：Token Plan（profile `token-plan` 或 base_url host 为 + `token-plan..maas.aliyuncs.com`）→ 模型自带搜索 + （`bl text chat --api responses --tool '{"type":"web_search"}'`）；其他 / 默认 → + Bailian MCP（`bl search web`）；仅在 MCP 鉴权失败、未开通或传输失败时兜底一次到模型自带搜索。 + Token Plan 联网搜索失败、两条路径鉴权混淆的排查也走本技能。 + 反触发：宿主可完成的 普通问答 / 编程 / 写作 → 不触发；知识库 RAG → bailian-cli + （`bl knowledge`）；生图/生视频/语音 → bailian-gen；精调/训练 → bailian-finetune； + agents.yaml → bailian-managed-agent。 + 共享协议（consent / 版本预检 / 鉴权 / 错误上报）在 bailian-protocol；官方安装 `bl skill init`。 +--- + +# 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), 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`. + +## Routing workflow + +### Step 1 — Identify the active model identity + +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..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`) diff --git a/tools/generate-reference.ts b/tools/generate-reference.ts index 25e08c671..98f2c6b94 100644 --- a/tools/generate-reference.ts +++ b/tools/generate-reference.ts @@ -60,6 +60,21 @@ const GENERATED_BANNER = "> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.\n" + "> Regenerate: `pnpm --filter bailian-cli run generate:reference`."; +/** + * Optional agent-facing notice injected at the top of a group's reference file. + * Used when the hub owns the command docs but a domain skill owns the routing + * decision (e.g. web search must go through bailian-web-search first). + */ +const GROUP_AGENT_NOTICE: Readonly> = { + search: + "> **Agent routing (mandatory):** Before running any `bl search *` command, " + + "Read skill `bailian-web-search` if installed and follow its identity-based routing " + + "(Token Plan → model-native web search; default → MCP; eligible MCP failures → fall back once). " + + "Do **not** call `bl search web` directly from this reference alone — Token Plan keys cannot " + + "authorize Bailian MCP search. If that skill is missing, run `bl skill init` or fall back to " + + "`bl search web --help` / `bl text chat --help` after checking `bl config show --output json`.", +}; + const AUTH_LABELS = { apiKey: "API Key", console: "Console", @@ -177,11 +192,13 @@ function ownerSkillForGroup(group: string): string { } function buildGroupFile(group: string, groupEntries: [string, AnyCommand][]): string { + const agentNotice = GROUP_AGENT_NOTICE[group]; const lines: string[] = [ `# \`bl ${group}\` commands`, "", GENERATED_BANNER, "", + ...(agentNotice ? [agentNotice, ""] : []), `Index: [index.md](index.md)`, "", "## Commands in this group", diff --git a/tools/release/check.mjs b/tools/release/check.mjs index 7b9ac1c9d..8e67fa6fd 100644 --- a/tools/release/check.mjs +++ b/tools/release/check.mjs @@ -69,6 +69,7 @@ export async function runCheck(options = {}) { "skills/bailian-gen/SKILL.md", "skills/bailian-finetune/SKILL.md", "skills/bailian-managed-agent/SKILL.md", + "skills/bailian-web-search/SKILL.md", ]), "skills/bailian-cli/reference/", "skills/bailian-gen/reference/",