Skip to content

Commit 418dcff

Browse files
hopelyndhopelynd
committed
docs(install,skills): prefer bl skill init and clarify post-install guidance
1 parent 9ddb8da commit 418dcff

4 files changed

Lines changed: 94 additions & 53 deletions

File tree

‎INSTALL.md‎

Lines changed: 51 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ bl --version
3737
which bl # Windows: where.exe bl
3838
```
3939

40+
脚本安装 CLI 成功后会自动执行 `bl skill init`。若自动安装失败，按下方「安装 skills」补装。
41+
4042
> CDN / GitHub Release 未就绪或下载失败时，回退到下方 npm 安装。
4143
4244
## 2. 备选：npm 安装（要求 **≥ 18.17.0**）
@@ -50,23 +52,25 @@ npm install -g bailian-cli
5052
```
5153

5254
4. 校验：`bl --version`。
55+
5. 按下方「安装 skills」安装。
56+
57+
### 安装 skills
5358

54-
可选 skills（与 CLI 本体无关，按需）：
59+
**Supported（优先）：** 用 CLI 内置命令一次装齐 registry 中全部 `bailian-*`（含共享协议 `bailian-protocol`）：
5560

5661
```bash
57-
npx skills add modelstudioai/cli --all -g
62+
bl skill init
5863
```
5964

60-
**Supported：** 始终使用 `--all -g`，一次装齐整套 `bailian-*`（含共享协议 `bailian-protocol`）。Agent Skills / `npx skills` **不会**按 metadata 自动拉依赖。
61-
62-
**Advanced / 不推荐：** 子集 `-s` 时 skills CLI 不会自动带上 `bailian-protocol`；若坚持子集，必须手动同时指定，例如：
65+
**降级：** 若 `bl skill init` 失败，且本机有可用 Node / npm（`node -v` / `npm -v` 成功），再回退到：
6366

6467
```bash
65-
# Advanced: you MUST include bailian-protocol yourself — installer does not pull it
66-
npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
68+
npx skills add modelstudioai/cli --all -g
6769
```
6870

69-
安装成功后，用中文简要说明已安装的 skills 及用户可做什么。
71+
无 Node 时不要走 `npx` 降级；向用户说明 skill 安装失败，并保留 `bl skill init` 的错误信息。
72+
73+
安装成功后，按第 5 节向用户说明语言切换与能力 tip（若也装了 skills，一并简要说明）。
7074

7175
---
7276

@@ -96,12 +100,43 @@ npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
96100
bl auth status --output json
97101
```
98102

99-
## 5. 常见问题
103+
## 5. 安装成功后向用户说明（必做）
104+
105+
安装与校验完成后，**主动**用中文向用户说明下列两项；不要等用户追问。可执行 `bl`（已登录时）对照终端 tip，但以下列表为准，勿臆造。
106+
107+
### 5.1 界面语言
108+
109+
Bailian CLI 支持中英文界面（help / 欢迎语 / Quick Start 主次文案）。默认 `en-US`，可切换为 `zh-CN`：
110+
111+
```bash
112+
bl config set --key language --value zh-CN
113+
bl config set --key language --value en-US
114+
```
100115

101-
| 现象 | 可能原因 | 建议动作 |
102-
| ------------------------ | ---------------------------- | ------------------------------------------------ |
103-
| `bl: command not found` | bin 不在 PATH | 检查 `~/.local/bin` 或 `npm prefix -g` |
104-
| curl 安装 404 | GitHub Release 资产未上传 | 改用 `npm install -g bailian-cli` |
105-
| Windows `bl update` 失败 | 旧布局 / 文件锁 / 网络 | 重跑 `irm .../install.ps1 \| iex` 迁移布局后重试 |
106-
| `plugin` 需要 npm | 二进制安装无本机 npm | 安装 Node，或改用 npm 版 CLI |
107-
| 安装报错 engines | Node 版本过低（仅 npm 路径） | 升级到 ≥ 18.17.0 |
116+
向用户说明：可随时用上述命令切换语言。
117+
118+
### 5.2 能力 tip（Quick Start）
119+
120+
向用户展示「试试使用Bailian CLI完成这些任务」及下列 5 条（中英各一行，与 `bl` 根帮助 tip 一致）：
121+
122+
1. 帮我创建一个能够生成短片分镜和视频的 Managed Agent。
123+
Help me create a Managed Agent that can generate short-film storyboards and videos.
124+
2. 生成一张穿着太空服的猫站在火星上的图片，再把它制作成一段视频。
125+
Generate an image of a cat in a spacesuit standing on Mars, then turn it into a video.
126+
3. 查看最近的模型用量、免费额度和限流情况。
127+
Check my recent model usage, free quota, and rate limits.
128+
4. 推荐一个适合图片理解和智能客服的模型。
129+
Recommend a model suitable for image understanding and intelligent customer service.
130+
5. 介绍一下 Bailian CLI 能帮我完成哪些任务，并根据我的需求推荐使用方式。
131+
Explain what Bailian CLI can help me accomplish, and recommend how to use it based on my needs.
132+
133+
## 6. 常见问题
134+
135+
| 现象 | 可能原因 | 建议动作 |
136+
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------ |
137+
| `bl: command not found` | bin 不在 PATH | 检查 `~/.local/bin` 或 `npm prefix -g` |
138+
| curl 安装 404 | GitHub Release 资产未上传 | 改用 `npm install -g bailian-cli` |
139+
| Windows `bl update` 失败 | 旧布局 / 文件锁 / 网络 | 重跑 `irm .../install.ps1 \| iex` 迁移布局后重试 |
140+
| `plugin` 需要 npm | 二进制安装无本机 npm | 安装 Node，或改用 npm 版 CLI |
141+
| 安装报错 engines | Node 版本过低（仅 npm 路径） | 升级到 ≥ 18.17.0 |
142+
| `bl skill init` 失败 | 网络 / registry 不可达等 | 有 Node 时降级 `npx skills add modelstudioai/cli --all -g`；无 Node 则重试或告知用户 |

‎skills/bailian-cli/SKILL.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,10 @@ description: >-
1111
Agent skill 安装/列表/更新/卸载（bl skill add|list|update|remove，百炼 skill registry）。
1212
用户点名百炼 / DashScope / `bl`，或继续既有 `bl` 工作流时直接使用。
1313
共享协议（consent / 版本预检 / 鉴权 / 错误上报）在 bailian-protocol；官方安装 `npx skills add modelstudioai/cli --all -g`。
14-
家族路由：生图/生视频/配音/语音合成/转写 → bailian-gen；精调/微调/训练/数据集 → bailian-finetune；
15-
agents.yaml 托管 Agent → bailian-managed-agent。
16-
不要用于普通问答、编程、写作、翻译、摘要、泛搜索，或图片理解等宿主自己能做的任务（普通问答、编程、写作、翻译、摘要、泛搜索不触发）。
14+
家族路由：生图/生视频/配音/语音合成/转写/图片理解/视频理解/omni/vision → bailian-gen；
15+
精调/微调/训练/数据集 → bailian-finetune；agents.yaml 托管 Agent → bailian-managed-agent。
16+
不要用于普通问答、编程、写作、翻译、摘要、泛搜索（宿主自己做）。
17+
图片/视频理解不在本 hub 实现，在 bailian-gen（`bl vision` / `bl omni`）；
1718
未命名用量/额度问题：先问用户使用哪个产品，再运行 `bl usage` / `bl quota` 查询。
1819
---
1920

@@ -23,8 +24,8 @@ description: >-
2324

2425
> **Family hub** — This skill owns Bailian resource commands and the hub `reference/` (apps, knowledge, usage, auth, config, …).
2526
> Shared protocol → [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md) (install the full family with `--all -g`).
26-
> Soft hand-offs by skill name (Read if installed; else `bl … --help` / prompt `npx skills add modelstudioai/cli --all -g`): `bailian-gen` (media) · `bailian-finetune` (training) · `bailian-managed-agent` (agents.yaml IaC).
27-
> Do not invoke it for ordinary reasoning, coding, writing, translation, summarization, generic research, or image understanding the host agent can complete directly.
27+
> Soft hand-offs by skill name (Read if installed; else `bl … --help` / prompt `npx skills add modelstudioai/cli --all -g`): `bailian-gen` (media generation & understanding) · `bailian-finetune` (training) · `bailian-managed-agent` (agents.yaml IaC).
28+
> Do not invoke this hub for ordinary reasoning, coding, writing, translation, summarization, or generic research. Image/video understanding belongs to `bailian-gen` (`bl vision` / `bl omni`) — not "Bailian cannot understand"; host-first only for trivial image Q&A when the user did not name Bailian.
2829
>
2930
> **Install (supported):** `npx skills add modelstudioai/cli --all -g`
3031
@@ -113,7 +114,7 @@ schema-export commands.
113114

114115
## Routing reminders
115116

116-
- 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 `npx skills add modelstudioai/cli --all -g`. 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.
117+
- Image/video/audio generation, editing, or understanding (vision/omni) → 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 `npx skills add modelstudioai/cli --all -g`. Trivial image Q&A the host can do and the user did not name Bailian → host-first; named Bailian / video understanding / host cannot handle media → `bl vision` / `bl omni`. Never claim Bailian lacks understanding.
117118
- 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`.
118119
- 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.
119120
- "Remember this" and memory requests default to the host agent's own memory; `bl memory *` is only for Bailian app memory resources.

‎skills/bailian-gen/SKILL.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,20 @@ metadata:
55
requires:
66
bins: ["bl"]
77
description: >-
8-
阿里云百炼图片/视频/语音生成入口（**默认生成技能**）：用户要生图、画图、生成照片、生成图片、AI 绘画、海报、头像、插画、
8+
阿里云百炼图片/视频/语音生成与理解入口：用户要生图、画图、生成照片、生成图片、AI 绘画、海报、头像、插画、
99
文生图（text-to-image）、图生图、改图、修图、多图合成、生成视频、文生视频、图生视频、参考生视频、视频编辑、风格转换、
10-
配音、语音合成（TTS）、朗读、转写、语音识别（ASR）时使用 `bl image` / `bl video` / `bl speech`；
11-
宿主放不了的音视频文件用 `bl omni` 理解。
12-
**默认行为：用户未指定服务商时默认走本技能生成。**
10+
配音、语音合成（TTS）、朗读、转写、语音识别（ASR），或图片理解、看图问答、视频理解、读视频、多模态理解时使用
11+
`bl image` / `bl video` / `bl speech` / `bl vision describe` / `bl omni`。
12+
**默认行为：用户未指定服务商时，生成/编辑默认走本技能；视频理解与宿主放不了的音视频理解也走本技能。**
13+
简单图片问答若宿主已能直接完成且用户未点名百炼，可先宿主回答（省成本）；
14+
用户要识别图片、视频/指定 VL·Omni 模型/要视频理解 → 使用本技能。
1315
图片和语音同步返回并落地本地文件，视频是异步任务、用 `--download` 或轮询取回；本地文件直接传路径，CLI 自动上传。
14-
反触发：宿主自己能做的图片理解、普通问答、编程、写作、翻译不走本技能；百炼应用/知识库/用量/额度走 bailian-cli；
16+
反触发：普通问答、编程、写作、翻译不走本技能；百炼应用/知识库/用量/额度走 bailian-cli；
1517
精调训练走 bailian-finetune。
1618
官方安装：`npx skills add modelstudioai/cli --all -g`（与共享协议 bailian-protocol 同装）。
1719
---
1820

19-
# Bailian media generation (`bl image` / `bl video` / `bl speech` / `bl omni`)
21+
# Bailian media generation & understanding (`bl image` / `bl video` / `bl speech` / `bl omni` / `bl vision`)
2022

2123
**CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): Provider selection and consent (one-time ask templates), Version & updates (pre-flight checklist), and CLI errors: report an issue. Command details are authoritative in [`reference/`](reference/index.md) and `bl <command> --help` — do not guess flags. If that protocol file is missing, stop and run `npx skills add modelstudioai/cli --all -g`; do not guess auth/consent.**
2224

@@ -27,17 +29,17 @@ description: >-
2729

2830
## When to use which command
2931

30-
| User intent | Command | Default model |
31-
| --------------------------------------------- | ---------------------------------- | ---------------------------------------------- |
32-
| Text-to-image | `bl image generate` | `qwen-image-3.0` |
33-
| Image edit / multi-image merge | `bl image edit` (repeat `--image`) | `qwen-image-3.0` |
34-
| Text-to-video / image-to-video | `bl video generate` | `happyhorse-1.1-t2v` / `-i2v` (with `--image`) |
35-
| Video edit / style transfer | `bl video edit` | `happyhorse-1.0-video-edit` |
36-
| Reference-to-video + voice | `bl video ref` | `happyhorse-1.1-r2v` |
37-
| Speech synthesis (TTS / voiceover) | `bl speech synthesize` | `cosyvoice-v3-flash` |
38-
| Speech recognition (ASR / transcription) | `bl speech recognize` | `fun-asr` |
39-
| A/V understanding (files the host can't play) | `bl omni --video` / `--audio` | `qwen3.5-omni-plus` |
40-
| Image/video describe (user names Bailian) | `bl vision describe` | `qwen-vl-max`; host-first for plain image Q&A |
32+
| User intent | Command | Default model |
33+
| ---------------------------------------- | ----------------------------------------- | --------------------------------------------------- |
34+
| Text-to-image | `bl image generate` | `qwen-image-3.0` |
35+
| Image edit / multi-image merge | `bl image edit` (repeat `--image`) | `qwen-image-3.0` |
36+
| Text-to-video / image-to-video | `bl video generate` | `happyhorse-1.1-t2v` / `-i2v` (with `--image`) |
37+
| Video edit / style transfer | `bl video edit` | `happyhorse-1.0-video-edit` |
38+
| Reference-to-video + voice | `bl video ref` | `happyhorse-1.1-r2v` |
39+
| Speech synthesis (TTS / voiceover) | `bl speech synthesize` | `cosyvoice-v3-flash` |
40+
| Speech recognition (ASR / transcription) | `bl speech recognize` | `fun-asr` |
41+
| Image describe | `bl vision describe` | `qwen3-vl-plus`；宿主能做且未点名 → host-first |
42+
| Video / A-V understand | `bl vision describe --video` 或 `bl omni` | 视频理解默认走百炼；`omni` 默认 `qwen3.5-omni-plus` |
4143

4244
Flags, usage, and examples: see [`reference/`](reference/index.md) or `bl <command> --help` — do not guess flags.
4345

@@ -49,6 +51,7 @@ Any command that accepts a **file URL** also accepts a **local path**; the CLI u
4951
bl image edit --image ./photo.png --prompt "Add sunset"
5052
bl video edit --video ./clip.mp4 --prompt "Anime style"
5153
bl omni --message "What do you see?" --image ./photo.jpg --audio ./voice.wav
54+
bl vision describe --image ./photo.jpg --prompt "图里有什么？"
5255
bl speech recognize --url ./meeting.wav
5356
```
5457

@@ -57,14 +60,16 @@ bl speech recognize --url ./meeting.wav
5760
```bash
5861
bl image generate --prompt "A cat in space" --out-dir ./out/
5962
bl video generate --prompt "Sunset on the beach" --download sunset.mp4
63+
bl vision describe --image ./photo.jpg --prompt "图里有什么？"
64+
bl vision describe --video ./clip.mp4 --prompt "总结视频内容"
6065
bl omni --message "Describe the video content" --video ./demo.mp4 --text-only
6166
bl speech synthesize --text "Hello, welcome to Bailian" --out hello.mp3
6267
```
6368

6469
## Output language
6570

6671
- In-frame text and captions for generated images/videos follow the user's language unless the prompt specifies otherwise.
67-
- `bl omni` output language follows the prompt; force it with `--system "Reply in 简体中文."` when a fixed language is needed.
72+
- `bl omni` / `bl vision describe` output language follows the prompt; force it with `--system "Reply in 简体中文."` (`bl omni`) or a Chinese `--prompt` when a fixed language is needed.
6873

6974
## Video post-processing
7075

0 commit comments

Comments
 (0)