# 奇乐 Agent 安装指引（agent-install.md）

> 本文件部署于 `https://agnet8.com/dl/agent-install.md`，**云端热更**——
> Agent 平台配置格式变化只需改本文件，零发版。用户会从控制台安装页复制
> 一段注入许可码的提示词粘贴给你，你按本指引执行。
>
> 版本：2026-11-09（M1）· 适用：macOS Apple Silicon + 支持 MCP stdio 的
> AI 助手（ZCode 首发；Claude Code / Cursor 后续）

## 环境矩阵（三轴，首屏即判）

| 轴 | 要求 | 不满足时 |
|---|---|---|
| 本页浏览器 | 无要求（手机可读；命令须在电脑执行） | — |
| 电脑（运行 Skill） | macOS arm64 · GUI 桌面会话 · 磁盘 ≥1GB | **终止且零下载**，告知用户不满足项 |
| AI 助手 | 支持 MCP stdio + 可启动桌面会话 | 退化为「一页粘贴提示词」模式 |

## 执行步骤（每步先播报再执行；全程幂等，中断重跑）

1. **环境探测**：`uname -s` = Darwin 且 `uname -m` = arm64；`df -m $HOME`
   剩余 ≥1024；存在 GUI 会话。任一不满足 → **立即终止，不下载任何东西**。
2. **先读安装器再执行**：`curl -fsSL https://agnet8.com/dl/install.sh -o /tmp/qile-install.sh`
   然后**通读脚本**确认无危险操作（set -eu / 只写 ~/.qile / curl+shasum），
   再把用户提示词里的许可码作为唯一参数执行：
   `sh /tmp/qile-install.sh QLD-XXXX-XXXX-XXXX`
   安装器内建：壳包下载 + SHA-256 校验（内嵌公示值）+ 解包 + 运行时 +
   MCP 注册 + 激活 + 自检。
3. **观察输出**：八步（①环境 ②下载+校验 ③解包 ④运行时 ⑤依赖 ⑥MCP
   ⑦激活 ⑧自检）逐步 ✓；任何 ✗ 即停，把失败行原样播报给用户——
   不要绕过失败步骤继续。
4. **GUI 有头冒烟**：`python3 ~/.qile/client/qilectl/qilectl.py diagnose --gui`
   ——会弹出一个 3 秒的空白 chromium 窗口后自动关闭；这是扫码登录的
   前置验证，属预期行为，提前告知用户。
5. **播报安装报告**：把 ⑧ 自检输出（或 `--report` 生成的
   `~/.qile/diagnose-report.txt`，脱敏无凭证）总结给用户，并提示：
   首次使用每个平台需扫码登录（对助手说「qile login bili」等）。

## 护栏（红线）

- **先校验后执行**：SHA-256 不匹配立即终止并上报，绝不继续解包。
- **码只来自用户提示词**：不从环境/历史消息猜测；格式 `QLD-XXXX-XXXX-XXXX`。
- **幂等**：所有步骤可重复执行；重复激活同码同指纹幂等（不占换绑次数）。
- **透明**：每步动作与结果都播报；诊断包脱敏（无凭证无内容）。
- **不做对抗**：不修改平台客户端、不绕过平台风控、不碰用户其他浏览器数据。

## 常见失败

| 现象 | 处置 |
|---|---|
| SHA-256 校验失败 | 上报客服；不要重试下载超过一次 |
| Python ≥3.10 缺失 | 提示 `xcode-select --install`；仍失败建议用户等待冻结单文件版（随公开发售） |
| chromium 下载慢/失败 | 重跑安装器续传；或 `QILE_SKIP_BROWSER=1` 先装后补 |
| 激活 403 DEVICE_LIMIT | 引导用户控制台「设备管理」解绑后重试 |
| 诊断 `网络 qile.ai` ✗ | 兜底域名按需解析，非阻断项（主域 agnet8.com 通即可） |