docs(skills): remove companions claim; make --all -g the supported install path

Author: hopelynd

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-*/` 经 `npx skills add modelstudioai/cli` 安装。共享协议在 `skills/bailian-protocol/`；业务 skill（`bailian-cli` / `bailian-gen` / `bailian-finetune` / `bailian-managed-agent`）依赖它作为 companion。`tools/generate-reference.ts` 从 **`packages/cli/src/commands.ts`** 按一级命令归属表分流写入各 `skills/<skill>/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 文案 / companion / hand-off 约定见 [docs/agents/skill-change.md](docs/agents/skill-change.md)。
+Skill / 命令手册随 `skills/bailian-*/` 经 `npx skills add modelstudioai/cli --all -g` 安装（整包装齐，含共享协议 `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/<skill>/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)。
 
 约定:
 
@@ -56,24 +56,24 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `npx skills add modelstudioai/cl
 
 按当前任务从下表挑一条进入对应文档:
 
-| 场景              | 何时进入                                         | 详见                                                                         |
-| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
-| 命令增删改        | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径     | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md)       |
-| E2E 测试维护      | 新增/改命令或 e2e 用例、补 help/缺参/dry-run     | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
-| 批量压测          | 改/跑多能力并发压测、`test:stress`、fixtures     | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md)       |
-| 选项变更          | 给已有命令加 `--flag` 或改默认值                 | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md)     |
-| 模型上下架        | 增加新模型 / 改默认模型 / 废弃旧模型             | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md)           |
-| Skill 文案 / 路由 | 改 SKILL 路由、companion、hand-off、hub/领域边界 | [docs/agents/skill-change.md](docs/agents/skill-change.md)                   |
-| 错误文案变更      | 改 `BailianError` 的 message 或 hint             | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md)         |
-| URL / 渠道变更    | 控制台域名 / 文档站 / 追踪参数                   | [docs/agents/url-change.md](docs/agents/url-change.md)                       |
-| 鉴权扩展          | 加 OAuth / SSO / 换 token 来源                   | [docs/agents/auth-change.md](docs/agents/auth-change.md)                     |
-| 配置项扩展        | 新 env var 或 `~/.bailian/config.json` 字段      | [docs/agents/config-add.md](docs/agents/config-add.md)                       |
-| Profile / 激活    | 改命名 Profile、预设或 `active_config`           | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) |
-| 安装文档          | 改安装、鉴权、验证流程或线上 install 页面        | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md)       |
-| 发布              | channel / stable 发布到 npm（CI 驱动）           | [docs/agents/publish.md](docs/agents/publish.md)                             |
-| Change Log        | 发版说明 / 历史版本说明                          | [docs/agents/changelog-write.md](docs/agents/changelog-write.md)             |
-| 工具链调整        | lint 规则 / 构建配置 / 依赖升级                  | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md)               |
-| Command Pack      | 扩展包 / 白名单 / plugin 管理命令                | [docs/agents/command-pack.md](docs/agents/command-pack.md)                   |
+| 场景              | 何时进入                                        | 详见                                                                         |
+| ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| 命令增删改        | 增加 / 删除 / 重命名 `bl xxx` 或入口命令路径    | [docs/agents/command-add-remove.md](docs/agents/command-add-remove.md)       |
+| E2E 测试维护      | 新增/改命令或 e2e 用例、补 help/缺参/dry-run    | [docs/agents/cli-e2e-tests.md](docs/agents/cli-e2e-tests.md)                 |
+| 批量压测          | 改/跑多能力并发压测、`test:stress`、fixtures    | [docs/agents/stress-batch-tests.md](docs/agents/stress-batch-tests.md)       |
+| 选项变更          | 给已有命令加 `--flag` 或改默认值                | [docs/agents/command-flag-change.md](docs/agents/command-flag-change.md)     |
+| 模型上下架        | 增加新模型 / 改默认模型 / 废弃旧模型            | [docs/agents/model-add-remove.md](docs/agents/model-add-remove.md)           |
+| Skill 文案 / 路由 | 改 SKILL 路由、安装约定、hand-off、hub/领域边界 | [docs/agents/skill-change.md](docs/agents/skill-change.md)                   |
+| 错误文案变更      | 改 `BailianError` 的 message 或 hint            | [docs/agents/error-hint-change.md](docs/agents/error-hint-change.md)         |
+| URL / 渠道变更    | 控制台域名 / 文档站 / 追踪参数                  | [docs/agents/url-change.md](docs/agents/url-change.md)                       |
+| 鉴权扩展          | 加 OAuth / SSO / 换 token 来源                  | [docs/agents/auth-change.md](docs/agents/auth-change.md)                     |
+| 配置项扩展        | 新 env var 或 `~/.bailian/config.json` 字段     | [docs/agents/config-add.md](docs/agents/config-add.md)                       |
+| Profile / 激活    | 改命名 Profile、预设或 `active_config`          | [docs/agents/config-profile-change.md](docs/agents/config-profile-change.md) |
+| 安装文档          | 改安装、鉴权、验证流程或线上 install 页面       | [docs/agents/install-doc-change.md](docs/agents/install-doc-change.md)       |
+| 发布              | channel / stable 发布到 npm（CI 驱动）          | [docs/agents/publish.md](docs/agents/publish.md)                             |
+| Change Log        | 发版说明 / 历史版本说明                         | [docs/agents/changelog-write.md](docs/agents/changelog-write.md)             |
+| 工具链调整        | lint 规则 / 构建配置 / 依赖升级                 | [docs/agents/lint-toolchain.md](docs/agents/lint-toolchain.md)               |
+| Command Pack      | 扩展包 / 白名单 / plugin 管理命令               | [docs/agents/command-pack.md](docs/agents/command-pack.md)                   |
 
 如果当前任务无法对应任何场景,先按经验完成,然后**回来评估这是不是一类新场景** —— 是就新增 `docs/agents/<scenario>.md`,把清单沉淀下来。
 

INSTALL.md

@@ -53,9 +53,12 @@ CLI 校验通过后，在本机终端执行：
 npx skills add modelstudioai/cli --all -g
 ```
 
-推荐 `--all`（含 companion `bailian-protocol`）。若只装单个业务 skill，必须同时带上 `bailian-protocol`，例如：
+**Supported：** 始终使用 `--all -g`，一次装齐整套 `bailian-*`（含共享协议 `bailian-protocol`）。Agent Skills / `npx skills` **不会**按 metadata 自动拉依赖。
+
+**Advanced / 不推荐：** 子集 `-s` 时 skills CLI 不会自动带上 `bailian-protocol`；若坚持子集，必须手动同时指定，例如：
 
 ```bash
+# Advanced: you MUST include bailian-protocol yourself — installer does not pull it
 npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
 ```
 

README.md

@@ -78,16 +78,11 @@ No timeline scrubbing. No frame-by-frame editing. Just one sentence → one vide
 
 ```bash
 npm install -g bailian-cli
-# Recommended: full bailian-* skill family (includes companion bailian-protocol)
+# Recommended: full bailian-* skill family (includes bailian-protocol)
 npx skills add modelstudioai/cli --all -g
 ```
 
-Subset install — always include companion `bailian-protocol` with any business skill:
-
-```bash
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
-```
+> Supported install is `--all -g`. The skills CLI does **not** auto-install skill dependencies. Subset `-s` installs are advanced / not recommended; if you use them, you must include `bailian-protocol` yourself (e.g. `-s bailian-protocol -s bailian-gen`).
 
 > Requires Node.js >= 18.17.
 

README.zh.md

@@ -76,16 +76,11 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 ```bash
 npm install -g bailian-cli
-# 推荐：安装完整 bailian-* skill 家族（含 companion bailian-protocol）
+# 推荐：安装完整 bailian-* skill 家族（含 bailian-protocol）
 npx skills add modelstudioai/cli --all -g
 ```
 
-子集安装时，业务 skill 必须同时带上 companion `bailian-protocol`：
-
-```bash
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
-```
+> 官方支持路径为 `--all -g`。`npx skills` **不会**按 metadata 自动安装依赖。子集 `-s` 为高级用法 / 不推荐；若坚持子集，须自行带上 `bailian-protocol`（例如 `-s bailian-protocol -s bailian-gen`）。
 
 > 需要预先安装 Node.js >= 18.17。
 

docs/agents/skill-change.md

@@ -1,20 +1,27 @@
-# Skill 文案 / 路由 / companion
+# Skill 文案 / 路由 / 安装约定
 
 ## 触发条件
 
 - 改 `skills/*/SKILL.md` 的 description、路由表、consent、安全闸、hand-off、references 落款
-- 调整 companion（`bailian-protocol`）或业务 skill 之间的软 hand-off 约定
+- 调整 `bailian-protocol` 与业务 skill 的关系，或业务 skill 之间的软 hand-off 约定
 - 新增 / 拆分 / 合并 `bailian-*` 业务 skill，或改 `tools/generate-reference.ts` 的 `GROUP_OWNER_SKILL` 归属（与命令增删改交叉时两边都看）
 - 给业务 skill 补安装说明、README，或统一「勿猜 flag → `reference/`」类约定
 
 纯改生成物 `skills/*/reference/*.md`（由命令 metadata 驱动）→ 走 [command-add-remove.md](command-add-remove.md) / [command-flag-change.md](command-flag-change.md)，**不要手改 reference**。
 
+## 统一口径（安装）
+
+1. **Supported install：** `npx skills add modelstudioai/cli --all -g`（整包装齐，含 `bailian-protocol`）
+2. **`bailian-protocol` 是共享协议 skill**，业务 skill 执行前应 Read 它；Agent Skills / `npx skills` **不会**按 frontmatter 自动拉依赖
+3. **不要**在 frontmatter 写 `companions`，也不要对外说「companions = 安装器硬依赖」
+4. 子集安装（`-s`）为 **advanced / 不推荐**：skills CLI 不会自动带上 protocol；漏装会导致相对路径 Read 失败
+
 ## 概念图
 
 ```text
-bailian-protocol          ← companion（硬依赖；consent / 鉴权 / 版本 / 错误上报）
-        ▲
-        │ companions: ["bailian-protocol"]
+bailian-protocol          ← 共享协议（consent / 鉴权 / 版本 / 错误上报）
+        ▲                   靠 --all -g 与业务 skill 同装；非安装器强制 companions
+        │
 ┌───────┴────────┬────────────────┬──────────────────┐
 bailian-gen      bailian-finetune  bailian-managed-agent
 （领域路由表）    （领域工作流）     （IaC 安全闸）
@@ -30,17 +37,18 @@ bailian-gen      bailian-finetune  bailian-managed-agent
 
 ### A. 分层边界
 
-- [ ] **Companion（硬依赖）**：业务 skill frontmatter 保留 `companions: ["bailian-protocol"]`；CRITICAL / references 可链 `../bailian-protocol/…`
-- [ ] **软 hand-off**：兄弟业务 skill **只写 skill 名**；已安装则 Read，未安装则 `bl … --help` 或提示 `-s bailian-protocol -s <skill>`；**不要**把 `../bailian-gen/…` 等写成执行前提
+- [ ] **整包装齐**：安装/升级文案主推 `--all -g`；业务 skill **不**声明 `companions`
+- [ ] **协议读取**：CRITICAL / references 可链 `../bailian-protocol/…`；若读不到 → 停止执行 `bl`，提示 `npx skills add modelstudioai/cli --all -g`
+- [ ] **软 hand-off**：兄弟业务 skill **只写 skill 名**；已安装则 Read，未安装则 `bl … --help` 或提示整包安装；**不要**把 `../bailian-gen/…` 等写成执行前提
 - [ ] **Hub vs 领域**：`bailian-cli` 的「When to use which command」只列 hub 拥有的意图；媒体 / 精调 / managed-agent 各留 hand-off 行，**不抄**领域默认模型与子命令明细
 - [ ] **渐进披露**：SKILL 写意图路由与领域硬规则；flags / usage / examples 以 `reference/` 或 `bl <command> --help` 为准，表后保留「勿猜 flag」指向句
 
 ### B. 文案与落款一致性
 
 - [ ] 领域 skill（gen / finetune / managed-agent）路由或命令表后有指向 `reference/` 的句；文末 `## references`（protocol + reference）与家族对齐
-- [ ] description 含 WHAT + WHEN + 反触发 + companion 必装说明；与正文路由不打架
+- [ ] description 含 WHAT + WHEN + 反触发；安装说明指向 `--all -g`，不写 companions 必装
 - [ ] Quick examples 只演示本 skill 职责（hub 不示范 `bl image` / `bl video` 等）
-- [ ] 若改了安装方式：同步 `README.md` / `README.zh.md` / `INSTALL.md` / `skills/*/README*` 中的 `npx skills add …` 示例
+- [ ] 若改了安装方式：同步 `README.md` / `README.zh.md` / `INSTALL.md` / `skills/*/README*` / `skills/bailian-protocol/assets/setup.md` 中的 `npx skills add …` 示例（改 `INSTALL.md` 时按 [install-doc-change.md](install-doc-change.md) 同步静态页）
 
 ### C. 归属与生成
 
@@ -56,11 +64,12 @@ pnpm run sync:skill-assets
 npx skills add "$(pwd)" --all -g -y
 ```
 
-抽查：打开 `skills/bailian-cli/SKILL.md` 确认无领域子命令明细表；打开对应领域 skill 确认有「勿猜 flag」与 hand-off。
+抽查：打开 `skills/bailian-cli/SKILL.md` 确认无领域子命令明细表、无 `companions`；打开对应领域 skill 确认有「勿猜 flag」与 hand-off。
 
 ## 常见漏点
 
 - ✗ hub 路由表再次抄回 image / video / finetune / managed-agent 明细 → token 膨胀且与领域 skill 双份漂移
+- ✗ 重新加回 `companions` 并宣称安装器硬依赖 → 与 Agent Skills / `npx skills` 合同不符
 - ✗ 软 hand-off 写成硬路径 `../bailian-*/SKILL.md` 当执行前提 → 子集安装断链
 - ✗ 只改 SKILL、忘改 `GROUP_OWNER_SKILL` → reference 落错 skill
 - ✗ 手改 `skills/*/reference/*.md` → 下次 generate 被覆盖

packages/cli/README.md

@@ -78,16 +78,11 @@ No timeline scrubbing. No frame-by-frame editing. Just one sentence → one vide
 
 ```bash
 npm install -g bailian-cli
-# Recommended: full bailian-* skill family (includes companion bailian-protocol)
+# Recommended: full bailian-* skill family (includes bailian-protocol)
 npx skills add modelstudioai/cli --all -g
 ```
 
-Subset install — always include companion `bailian-protocol` with any business skill:
-
-```bash
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
-```
+> Supported install is `--all -g`. The skills CLI does **not** auto-install skill dependencies. Subset `-s` installs are advanced / not recommended; if you use them, you must include `bailian-protocol` yourself (e.g. `-s bailian-protocol -s bailian-gen`).
 
 > Requires Node.js >= 18.17.
 

packages/cli/README.zh.md

@@ -76,16 +76,11 @@ _专为 AI Agent 打造，每个命令均可作为结构化工具调用。_
 
 ```bash
 npm install -g bailian-cli
-# 推荐：安装完整 bailian-* skill 家族（含 companion bailian-protocol）
+# 推荐：安装完整 bailian-* skill 家族（含 bailian-protocol）
 npx skills add modelstudioai/cli --all -g
 ```
 
-子集安装时，业务 skill 必须同时带上 companion `bailian-protocol`：
-
-```bash
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-gen
-npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
-```
+> 官方支持路径为 `--all -g`。`npx skills` **不会**按 metadata 自动安装依赖。子集 `-s` 为高级用法 / 不推荐；若坚持子集，须自行带上 `bailian-protocol`（例如 `-s bailian-protocol -s bailian-gen`）。
 
 > 需要预先安装 Node.js >= 18.17。
 

skills/bailian-cli/README.md

@@ -4,12 +4,11 @@
 
 Agent skill for **Alibaba Cloud Model Studio CLI** (`bl`) resource hub — apps, memory, RAG, usage/quota, MCP, and hub `reference/`.
 
-- Companion (required): `bailian-protocol` (`requires.bins: ["bl"]`, `companions: ["bailian-protocol"]`)
+- Shared protocol: `bailian-protocol` (install via `--all -g`)
 - Soft hand-offs (optional skills): `bailian-gen` · `bailian-finetune` · `bailian-managed-agent`
 
 ```bash
 npx skills add modelstudioai/cli --all -g
-# or: npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
 ```
 
 For CLI installation, authentication, and examples, see the [main README](../../README.md).

skills/bailian-cli/README.zh.md

@@ -4,12 +4,11 @@
 
 **阿里云百炼 CLI**（`bl`）的资源管理 Agent 技能 — 应用、记忆、RAG、用量/额度、MCP，以及 hub `reference/`。
 
-- Companion（必装）：`bailian-protocol`（`requires.bins: ["bl"]`，`companions: ["bailian-protocol"]`）
+- 共享协议：`bailian-protocol`（通过 `--all -g` 与整家族同装）
 - 软 hand-off（可选）：`bailian-gen` · `bailian-finetune` · `bailian-managed-agent`
 
 ```bash
 npx skills add modelstudioai/cli --all -g
-# 或：npx skills add modelstudioai/cli -g -s bailian-protocol -s bailian-cli
 ```
 
 CLI 的安装、认证和使用示例请查看[主 README](../../README.zh.md)。