# 千问AI平台技能市场安装

## 适用场景（先判断，避免打扰用户）

先归类用户意图，再决定从哪一步开始，不要每次都从头跑一遍：

场景

用户意图

入口

A

安装 / 更新千问AI平台技能市场 CLI，或首次接入技能市场

从「一、CLI 就绪」开始：检测 CLI → 缺失或过低则走「二、安装 / 更新」→ 补齐默认技能 `qianwen-find-skills`

B

找 / 装某个具体技能

先用「一、CLI 就绪」做一次快速检测；已就绪则直接跳到「三、搜索 → 确认 → 安装」，不要重复安装 CLI，也不要额外向用户确认

仅在检测结果确实不满足前置条件时才回退到「二、安装 / 更新」，避免无谓打扰用户。

## 一、CLI 就绪

执行技能操作前，先检测本地 CLI：

已复制

```bash
command -v qianwen && qianwen --version   # 要求 >= 1.4.0
```

*   已安装且版本 `>= 1.4.0` → 就绪，直接进入「三、搜索 → 确认 → 安装」，不重复安装。
    *   但 CLI 可能是手动安装的，未随之落地默认技能。就绪后顺带检测一次（`<skills 目录>` 见「四、推荐安装目录」）：
        
        已复制
        
        ```bash
        ls <skills 目录>/qianwen-find-skills/SKILL.md   # 存在即已就位
        ```
        
        若缺失，直接按「二、安装 / 更新」末尾的命令补装 `qianwen-find-skills`，无需向用户确认，补装完成后继续原任务。
        
*   未安装或版本过低 → 进入「二、安装 / 更新」。

## 二、安装 / 更新

`@latest` 拉取最新版，等同于更新：

已复制

```bash
npm install -g @qianwenai/qianwen-cli@latest
```

安装后以 `qianwen --version` 校验版本 `>= 1.4.0`。命令未生效时新开终端或刷新 `PATH`；沙箱限网环境需以允许联网的权限执行。

`qianwen-find-skills` 为默认技能，首次安装 CLI 时随之安装，无需向用户确认；手动安装 CLI 而未落地该技能时，同样用这条命令补装：

已复制

```bash
qianwen skills install qianwen-find-skills --dir <skills 目录> --format json
```

## 三、搜索 → 确认 → 安装

⚠️ 安装时 **必须**用 `--dir` 指向当前 Agent 的 skills 目录，否则会默认安装到当前工作目录（cwd），Agent 可能不会识别。目录按「四、推荐安装目录」确定。

已复制

```bash
qianwen skills search [关键词] --format json                      # 搜索
qianwen skills install <slug> --dir <skills 目录> --format json   # 装到当前 Agent 的 skills 目录
```

*   **先搜后装**：搜索后等用户确认再安装，禁止跳过搜索直接 install。
*   outcome 三态：`installed`\=新装；`updated`\=升级（含 `downgrade` 降级时附带 `{from,to}`）；`noop`\=已最新。
*   冲突：目标目录存在同名非托管目录时报 `UNMANAGED_CONFLICT` exit 1 零变更， **无 `--force`，不得绕过**，建议用户移走或换 `--dir`。
*   退出码：`0`\=成功；非零=失败（详见 stderr）。
*   搜索无结果时用中文告知未找到现成技能。
*   安装结束后必须按「五、安装结果汇报」向用户交代结果。

## 四、推荐安装目录

全局目录可跨项目复用；项目级目录仅供当前项目使用或随仓库共享。下表是推荐目录，不是唯一可用目录。

按以下顺序确定 `--dir`，命中即停：

1.  **用户明确指定目录**：使用该目录。若当前 Agent 无法自动识别，仍按要求安装，同时提醒用户配置加载路径。
2.  **当前 Agent 已配置或正在使用其他有效的 skills 目录**：沿用该目录。
3.  **当前 Agent 在下表中**：默认使用全局目录；用户要求随仓库共享或项目级目录已存在时，使用项目级目录。
4.  **当前 Agent 不在下表中**：探测 `~` 和 cwd 下已经存在的 `.<agent>/skills/` 或 `.agents/skills/`并确定是否可以沿用；无法确定时查询官方约定。
5.  **仍无法确定**： 暂停安装说明原因并让用户二选一：（1）使用 cwd 作为目标目录；（2）明确指定其他目标目录。用户确认后再安装。

编号

Agent

全局目录

项目级目录

1

Claude Code

`~/.claude/skills/`

`./.claude/skills/`

2

Codex

`~/.agents/skills/`

`./.agents/skills/`

3

Cursor

`~/.cursor/skills/`

`./.cursor/skills/`

4

Qoder

`~/.qoder/skills`

`./.qoder/skills/`

5

Qoder CN

`~/.qoder-cn/skills`

`./.qoder-cn/skills/`

6

QoderWork

`~/.qoderwork/skills`

`./.qoder/skills/`

7

QoderWork CN

`~/.qoderworkcn/skills/`

`./.qoder/skills/`

8

QwenWork

`~/.qwenworkcn/skills/`

`./.qoder/skills/`

9

Qwen Code

`~/.qwen/skills/`

`./.qwen/skills/`

10

OpenCode

`~/.agents/skills/`

`./.agents/skills/`

11

Trae

`~/.trae/skills/`

`./.trae/skills/`

12

Trae CN

`~/.trae-cn/skills/`

`./.trae/skills/`

确定目标目录后，必须按以下顺序执行：

1.  检查目标目录是否存在。
    
2.  若不存在，先通过命令行创建完整路径：
    
    已复制
    
    ```bash
    mkdir -p "<目标 skills 目录>"
    ```
    
3.  确认目录已创建且可写，再使用 `--dir` 安装 Skill。
    

`--dir` 不会创建目标目录。创建或安装失败时必须停止并说明原因，不得省略 `--dir`、改用其他目录或静默回退到 cwd。

## 五、安装结果汇报

每次安装（含补装默认技能）结束后，先确认 Skill 位于目标目录，再用中文交代以下三件事，不要只回复“装好了”：

*   **怎么下的**：实际执行的命令（包括本次使用的 `mkdir -p`）及安装结果（`installed` / `updated` / `noop`）。
*   **下到哪里**：`--dir` 的绝对路径，说明是全局、项目级还是用户自定义目录；同时说明目录原本已存在，还是本次新建。
*   **下的什么**：技能 slug、名称和版本；升级时给出 `{from, to}`，多个技能逐个列出。

需要重启 Agent 才能生效时一并提示。失败时说明失败阶段（创建目录、安装或校验）、退出码、stderr 要点及下一步建议。