千问AI平台技能市场安装

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

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

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

一、CLI 就绪

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

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

• 已安装且版本 >= 1.4.0 → 就绪，直接进入「三、搜索 → 确认 → 安装」，不重复安装。

  • 但 CLI 可能是手动安装的，未随之落地默认技能。就绪后顺带检测一次（<skills 目录> 见「四、推荐安装目录」）：

    已复制

    ls <skills 目录>/qianwen-find-skills/SKILL.md   # 存在即已就位
    

    若缺失，直接按「二、安装 / 更新」末尾的命令补装 qianwen-find-skills，无需向用户确认，补装完成后继续原任务。

• 未安装或版本过低 → 进入「二、安装 / 更新」。

二、安装 / 更新

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

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

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

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

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

三、搜索 → 确认 → 安装

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

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）明确指定其他目标目录。用户确认后再安装。

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

1. 检查目标目录是否存在。

2. 若不存在，先通过命令行创建完整路径：

   已复制

   mkdir -p "<目标 skills 目录>"
   

3. 确认目录已创建且可写，再使用 --dir 安装 Skill。

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

五、安装结果汇报

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

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

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