Merge pull request #14 from modelstudioai/fix/docs-p0-utm-noncli-visual

docs: P0 fixes + UTM completion + non-CLI path with visual assets

Author: TreeLin

_config.yml

@@ -10,3 +10,4 @@ plugins: []
 # 阿里云百炼 UTM 链接（全站统一引用）
 bailian_cli_url: "https://bailian.console.aliyun.com/cli?source_channel=cli_github&"
 bailian_apikey_url: "https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key"
+happyhorse_t2v_url: "https://bailian.console.aliyun.com/cn-beijing?tab=demohouse&source_channel=hh_github#/experience/t2v"

cli/index.md

@@ -94,6 +94,13 @@ bl text chat --message "你好"
 | 模型推荐 | `bl advisor recommend` | 描述场景获取最优模型建议、模型对比 |
 | 用量查询 | `bl usage free` | 查询免费额度使用情况 |
 
+> ℹ️ **`bl mcp` 不做什么**
+>
+> `bl mcp` 是 **MCP 客户端**——它让你调用百炼平台已经发布的 MCP 服务。
+> 它**不会**把 `bl` 本身暴露成 MCP server。如果你想让 Claude Desktop / Cursor 等通过 MCP 协议接入 `bl`，
+> 目前推荐做法是直接在 Agent 配置里把 `bl` 当作 shell 命令调用（例如 `claude_desktop_config.json` 中
+> `"command": "bl"`）。原生 `bl mcp serve` 模式在 roadmap 中。
+
 > 每个 URL 参数都接受本地路径，自动上传到免费临时存储（48 小时有效期）。
 
 ---

faq/index.md

@@ -8,7 +8,7 @@ keywords: "百炼 FAQ,bailian-cli 常见问题,OpenWork 安装失败,API Key 配
 
 # 常见问题
 
-> 本页持续更新。遇到新问题？[提 Issue](https://github.com/ModelStudioAI/modelstudioai.github.io/issues) 或直接 [编辑本页](https://github.com/ModelStudioAI/modelstudioai.github.io/edit/main/faq/index.md)。
+> 本页持续更新。遇到新问题？[提 Issue](https://github.com/modelstudioai/modelstudioai.github.io/issues) 或直接 [编辑本页](https://github.com/modelstudioai/modelstudioai.github.io/edit/main/faq/index.md)。
 
 ---
 
@@ -32,7 +32,7 @@ OpenWork 是桌面端应用，已内置阿里云百炼 CLI。你可以选择用
 
 ### 如何获取 API Key？
 
-[前往阿里云百炼平台获取 →](https://bailian.console.aliyun.com/cn-beijing/?source_channel=key_github&tab=app#/api-key)
+[前往阿里云百炼平台获取 →]({{ site.bailian_apikey_url }})
 
 ### API Key 配置后不生效？
 
@@ -70,5 +70,5 @@ OpenWork 是桌面端应用，已内置阿里云百炼 CLI。你可以选择用
 
 ### 如何反馈问题？
 
-- [GitHub Issues](https://github.com/ModelStudioAI/modelstudioai.github.io/issues)
+- [GitHub Issues](https://github.com/modelstudioai/modelstudioai.github.io/issues)
 - 加入社群（微信群二维码见各活动页面）

guide/assets/bailian-cli-card-01-bailian.jpg

@@ -45,6 +45,25 @@ Skills（可复用的 AI 能力模块）
 
 ---
 
+## 五分钟先认识四个词
+
+正式开干前，先用一张图记住四个名词的关系——它们贯穿全教程：
+
+![四个名词的关系图](/guide/assets/bailian-cli-relationship-diagram.jpg)
+
+一句话类比，便于回忆：
+
+| 名词 | 一句话类比 |
+|------|------------|
+| <img src="/guide/assets/bailian-cli-card-01-bailian.jpg" width="100"> **百炼** | 阿里云的「**模型超市**」——Qwen / DeepSeek / Kimi / GLM / MiniMax / 通义万相都在货架上，按需取用 |
+| <img src="/guide/assets/bailian-cli-card-02-apikey.jpg" width="100"> **API Key** | 你的「**身份证 + 充值卡**」——证明你是合法用户，账户里挂着新人免费额度 |
+| <img src="/guide/assets/bailian-cli-card-03-cli.jpg" width="100"> **CLI（`bl`）** | 「**万能遥控器**」——一句话或一行命令，让 Agent 调用模型超市里任何一个模型 |
+| <img src="/guide/assets/bailian-cli-card-04-mcp.jpg" width="100"> **MCP** | 「**通用插头**」——AI 世界的 USB-C，让任意 Agent 一插即用百炼能力 |
+
+> 👶 **小白专属**：如果你看不懂下方任何一条命令，**完全没关系**——本教程支持纯对话路径，所有命令都可以让 Agent 替你跑。继续往下看 Step 2。
+
+---
+
 ## 第一步：注册阿里云百炼并获取 API Key
 
 ### 1.1 注册账号
@@ -69,6 +88,24 @@ Skills（可复用的 AI 能力模块）
 
 ## 第二步：选择你的运行环境
 
+> ✋ **不想敲命令？跳过本节直接看 Step 4。**
+>
+> 如果你**不熟悉终端、不会 npm、看见命令行就头大**——选下面的「方式 C：OpenWork 桌面 Agent」就够了。下载 .dmg/.exe 双击安装，跟微信一样傻瓜。CLI、Skills 在 OpenWork 里全部内置好了，**你只需要在对话框里说人话**：
+>
+> > 帮我安装阿里云百炼，跑一下你内置的 demo
+>
+> Agent 会自动替你完成所有命令行操作并把结果贴回来。后续 Step 5 的「让 Agent 调用 Skill」、Step 6 的「跑通你的第一支视频广告」**全部都是纯对话**，不需要打任何字符的命令。
+
+### 我应该选哪条路径？
+
+| 你的现状 | 推荐路径 | 大概体验 |
+|---------|----------|---------|
+| 完全没装过任何 AI Agent，看见黑色终端就紧张 | 方式 C（OpenWork） | 像装微信一样，下载即用，全程对话 |
+| 已经在用 Cursor / Qoder / Claude Desktop | 方式 B | 零额外配置，把命令交给你已有的 Agent |
+| 习惯命令行，想要最轻量 | 方式 A | 一行 npm install，全靠肌肉记忆 |
+
+拿不准？**默认选方式 C**。
+
 阿里云百炼 CLI 是为 AI Agent 而生的——任何支持 shell 命令或 MCP 工具的 Agent 都能直接使用它。挑选适合你的方式：
 
 ### 方式 A：终端直接安装（最轻量）
@@ -78,7 +115,11 @@ npm install -g bailian-cli
 bl --version
 ```
 
-> 需要 Node.js >= 22.12
+> ⚙️ **环境前置说明**
+> - `bailian-cli` 本体（`bl` 命令）：**Node.js ≥ 22.12**（package.json engines 字段硬要求，低于此版本 `npm install` 会直接报错）
+> - `skills` CLI（`npx skills add ...`，第四步用到）：Node.js ≥ 18 即可
+>
+> 没装 Node 或版本低于 22.12？建议直接装最新 LTS（v22 或更高）一劳永逸，推荐使用 [nvm](https://github.com/nvm-sh/nvm) / [fnm](https://github.com/Schniz/fnm) 管理版本。
 
 ### 方式 B：在主流 AI Agent 框架中使用
 
@@ -88,7 +129,7 @@ bl --version
 |------|----------|
 | Cursor | 终端 / Composer 调用 `bl ...` 命令 |
 | Qwen Code | 作为结构化工具调用，参考 [showcase](/showcase/) |
-| Claude Desktop / Claude Code | 直接 shell 调用，或通过 `bl mcp` 暴露为 MCP 工具 |
+| Claude Desktop / Claude Code | 直接 shell 调用即可（在 `claude_desktop_config.json` 里把 `command` 设为 `bl`）。若要让 Agent 调用百炼平台托管的 MCP 服务（如官方天气、日历等），用 `bl mcp list` / `bl mcp call` |
 | Windsurf / Cline / Trae | 同上，支持任意能跑 shell 的 Agent |
 
 ### 方式 C：使用 OpenWork（开源桌面 Agent）
@@ -145,7 +186,7 @@ Skills 是阿里云百炼团队验证过的 AI 能力模块，让 Agent 能完
 
 ```
 请帮我安装阿里云百炼的 AI Skills：
-1. 检查 Node.js 是否已安装（>= 18），未安装则自动安装
+1. 检查 Node.js 是否已安装且版本 >= 22.12（bailian-cli 硬要求），未达到则升级到最新 LTS
 2. 执行：npx skills add modelstudioai/skills
 3. 安装完成后告诉我"Bailian Skills installed"，并列出已安装的 Skills 与可用功能
 ```
@@ -166,6 +207,16 @@ npx skills add modelstudioai/skills
 
 ## 第五步：试一试
 
+> 💬 **不必打命令——对 Agent 说人话就行**
+>
+> 下面给的命令是「**最底层操作**」，方便高级用户做精细控制。如果你在 OpenWork / Cursor / Qoder / Claude Desktop 里，**完全可以不打任何命令**，直接对 Agent 说：
+>
+> > 帮我用 bailian-cli 生成一张图，主题是"穿宇航服的猫，赛博朋克风格"
+>
+> Agent 会自动选择正确的 `bl image generate` 命令、补齐参数、跑完后把结果路径告诉你。
+>
+> **判断你是不是在对话流里**：你能否用中文一句话提需求、Agent 直接给结果？是→你已经在对话流里，下面的命令直接当作"原理科普"读就行。
+
 现在你已经具备完整的 CLI + Skills 环境。挑一个场景试试：
 
 ### 文本对话
@@ -228,6 +279,42 @@ bl advisor recommend --message "我需要做一个能看图回答的对话机器
 
 ---
 
+## 第六步（可选）：跑通你的第一支视频广告
+
+前面五步都偏「**单个能力点**」。这一步用一条对话指令，让 Agent 自己 clone 仓库、读故事板、调百炼，**端到端跑出一支日系青春汽水广告片**——和我们 5 分钟视频教学里展示的是同一个 demo。
+
+### 你需要做什么？
+
+**只需要一句话。** 在你的 Agent 对话框（OpenWork / Cursor / Qoder / Claude Desktop 任一）里粘贴：
+
+> 帮我从 GitHub clone modelstudioai 的 awesome-happyhorse-prompts 仓库，
+> 按 `cases/r2v-1.1.md` 第 3 个 case「Happy Run Citrus」的 prompt 和 `assets/` 里的故事板图，
+> 给我跑一支 720P 的视频。完成后把视频路径告诉我。
+
+### 幕后发生了什么？
+
+Agent 会**按顺序自动**：
+
+1. `git clone https://github.com/modelstudioai/awesome-happyhorse-prompts`
+2. 读 `cases/r2v-1.1.md` 第 3 个 case 的完整 prompt（9 镜头日剧 CM 分镜）
+3. 加载 `assets/` 目录下的 3×3 故事板图（**这就是为什么必须 clone**——R2V 模型必须吃故事板图）
+4. 调用 `bl video ref`（HappyHorse 1.1 R2V 模型）
+5. 等 3–5 分钟出片
+
+### 想直接在浏览器里试？
+
+不想 clone 也想感受一下？打开 [HappyHorse 1.1 文生视频体验页]({{ site.happyhorse_t2v_url }})，直接在网页上输入 prompt 就能出片。但**只有 clone 仓库**才能拿到 Happy Run Citrus 这一套完整的故事板图，跑出和示例一模一样的成片。
+
+### 跑通了？
+
+- 给 [`modelstudioai/awesome-happyhorse-prompts`](https://github.com/modelstudioai/awesome-happyhorse-prompts) 点个 ⭐ Star
+- 把你的成片提交到 [Showcase](/showcase/)
+- 改 prompt 换品牌，做属于你自己的产品广告
+
+> 💸 **关于费用**：HappyHorse 1.1 R2V 模型 720P 价格 ¥0.9/秒，30 秒约 ¥27；新用户有 10 秒免费额度，第一次跑可零成本。2026-07-06 前还有 6 折优惠。
+
+---
+
 ## 进阶
 
 ### 探索更多