# 奇乐 Skill · 安装说明

> 适用版本：executor 0.2.3 / qile-mcp 1.0.7（2026-11-10）
> 适用环境：macOS（Apple Silicon）+ ZCode 等 Agent 桌面环境
> 安装耗时：约 3-5 分钟（首次含 chromium 下载约 +3 分钟）

---

## 一、安装（你要做的全部：复制 → 粘贴 → 等报告）

1. **复制提示词**：登录控制台
   [安装页](https://agnet8.com/console/install.html)，点
   **「一键复制提示词」**——你的许可码已自动注入。还没有码？页面上可当场
   领免费试用（7 天 · 3 平台 × 3 次）或购买。
2. **粘贴给你的 AI 助手**（ZCode / Claude Code / Cursor 等会跑命令的 Agent），
   发送。
3. **等安装报告**（约 3-5 分钟）：AI 会自动完成环境检查、下载安装、注册、
   激活、自检，最后回你一份报告。
4. **验证一句**：对 AI 说 `奇乐现在什么状态`——返回许可有效 + 各平台状态，
   即装好了。

- 中断 / 失败：**把同一段提示词原样再发一次**即可（全程幂等，从断点续装）
- 已在其他电脑激活过：先到控制台[设备页](https://agnet8.com/console/devices.html)
  解绑，再重发提示词
- 提示词含完整许可码，截图分享前请遮挡

> AI 背后做的事（你不需要看懂，出问题时把 AI 的失败播报发给客服即可）：
> 读取云端安装指引 → 环境探测 → 下载安装器并**先通读再执行** → SHA-256
> 校验 → 解包 → 注册 MCP → 用你的许可码激活 → 自检 → 安装报告。

## 二、前置条件（AI 会自动检查，缺一即终止且零下载）

| 条件 | 要求 | 说明 |
|---|---|---|
| 系统 | macOS + Apple Silicon（arm64） | Windows 版随 M2 提供 install.ps1 |
| 磁盘 | 剩余 ≥ 1GB | chromium 约占 366MB |
| GUI | 有桌面会话 | 平台登录需有头浏览器扫码 |
| Python | ≥ 3.10 | 缺失时装 Xcode CLT：`xcode-select --install` |
| 许可码 | `QLD-XXXX-XXXX-XXXX` | 购买/试用获取；**一机一码**（绑设备指纹） |
| Agent 模型 | 核心发布链无特殊要求 | 完整体验（见下）建议支持图片输入的模型 |

### Agent 与模型要求

**一句话判据：所用模型支持图片输入 → 完整体验；纯文本模型 → 发布全链路照常可用，
仅「平台改版初诊」一步降级为按回执文字分类**（结果照样上报，不影响发布）。

视觉识别分两处，只有一处跟你的模型有关：

- **奇乐侧的视觉（与你无关）**：仅「分享减免」截图核验（你主动发起时，
  奇乐服务器 AI 校验）。执行器自愈是**纯本地降级**（重跑一次/转人工包），
  内容风控扫描是词库比对——都不传图、不用视觉；
- **你的模型的视觉（仅一处）**：极少数情况下平台改版导致发布失败，AI 会打开
  **留在你本机**的失败截图判断原因（元素没了/被弹窗挡了/时序问题）——这一步
  需要模型看得懂图。**截图不出你的电脑**（你明确同意附图上报时除外）。

| Agent | 常用模型 | 图片输入 | 完整体验 |
|---|---|---|---|
| Claude Code | Claude 系列 | ✅ | ✅ |
| Codex | GPT 系列 | ✅ | ✅ |
| Gemini CLI | Gemini 系列 | ✅（原生多模态） | ✅ |
| Cursor | Claude / GPT / Gemini（可选） | 主流档 ✅ | ✅（选多模态模型即可） |
| ZCode | GLM 系列 | ✅ | ✅ |
| Trae | Claude / GPT / 豆包（可选） | 主流档 ✅ | ✅（选多模态模型即可） |
| WorkBuddy | 以所选模型为准 | 见模型档位 | 多数 ✅ |
| ClubCode | 未公开发布 | 待验证 | 待验证 |

纯文本模型（如 DeepSeek 系列文本档）：发布、回执、定时、简报、偏好全部正常；
仅上述初诊一步按回执文字分类，个别情况下分类精度略降——日常使用无感。

## 三、八步详解（想了解背后发生了什么）

AI 代跑最终执行的也是这套安装器流程：

1. **环境探测**——macOS/arm64/磁盘/GUI 检查
2. **下载壳包 + SHA-256 校验**——hash 与安装页/控制台公示值双对（不一致即终止并提示上报）
3. **解包** 到 `~/.qile/`（幂等：重跑先清旧壳，配置与凭证不受影响）
4. **安装 SKILL** 到 `~/.agents/skills/qile/`（Agent 自动发现的编排说明）
5. **运行时检查**（Python ≥3.10）
6. **依赖安装**——playwright + chromium（仅一次；断点可续传，重跑安装器即可）
7. **注册 MCP**——写入 ZCode 用户级配置 `~/.zcode/cli/config.json`
8. **激活许可 + 自检**——码直通激活，产出脱敏诊断包

成功结尾 AI 会告诉你：**「安装完成。对我说：『用奇乐发布一条内容』即可开始。」**

### 安装后自验（可选，AI 报告已含）

```sh
~/.qile/client/qilectl/qilectl.py diagnose --profile full --net   # 环境+网络拨测
~/.qile/client/qilectl/qilectl.py --version                        # 壳版本
```

### 变体参数（环境变量，一般用不到）

```sh
# 指定其他服务端（默认 https://agnet8.com）
QILE_SERVER=https://agnet8.com curl -fsSL ... | sh -s -- QLD-XXXX-XXXX-XXXX

# 跳过 chromium 下载（机器上已有 playwright 缓存时）
QILE_SKIP_BROWSER=1 curl -fsSL ... | sh -s -- QLD-XXXX-XXXX-XXXX
```

## 四、极客通道：一条命令（不用 AI 自己装）

```sh
curl -fsSL https://agnet8.com/dl/install.sh | sh -s -- QLD-XXXX-XXXX-XXXX
```

把 `QLD-XXXX-XXXX-XXXX` 换成你的许可码（控制台可查完整码）。装完在 Agent 里
说 `查一下奇乐的状态` 验证。**先读后跑**：可先
[查看 install.sh 源码](https://agnet8.com/dl/install.sh)。

## 五、常见安装问题

| 现象 | 原因 | 处置 |
|---|---|---|
| `缺少许可码参数` | 命令漏了码 | 补上 `--` 后的许可码 |
| `SHA-256 校验失败` | 下载被劫持/不完整 | **勿继续**，按提示上报客服 |
| `需要 Python ≥3.10` | 无解释器 | `xcode-select --install` 后重跑 |
| chromium 下载失败 | 网络 | 直接重跑安装器（续传）；或 `QILE_SKIP_BROWSER=1` |
| Agent 里看不到 qile 工具 | MCP 注册未生效 | 重启 Agent；仍无则 `qilectl.py repair-mcp` 后再重启 |
| `激活失败：码已绑定其他设备` | 一机一码冲突 | 控制台 https://agnet8.com/auth/console 解绑旧设备后重试 |

## 六、装了什么（目录速览）

```
~/.qile/
├── client/qilectl/        # 命令行（activate/diagnose/repair-mcp/check-update）
├── client/qile-mcp/       # MCP 编排器（Agent 经它调用 11 个工具）
├── executor/              # 本地执行器（浏览器自动化；平台登录态只存这里）
├── credentials            # 激活凭证（设备绑定，root 权限同用户态）
└── receipts/              # 每日发布回执（JSONL，可读）
~/.agents/skills/qile/SKILL.md   # SKILL 编排说明（Agent 自动发现）
~/.zcode/cli/config.json          # MCP 注册条目（用户级）
```

**隐私边界**：平台账号登录态（cookie）只存你本机 `~/.qile/executor/`，运营方
无法接触；云端只接收内容文本的合规审查与哈希校验，素材文件与失败截图
永不上传（你明确同意的除外）。