# 万应skill 安装说明

万应skill 是一个面向量化投资的 AI agent 技能包（skill），让 agent 具备量化投资所需数据的获取与基础量化研究框架的搭建能力（日频 + 竞价辅助口径）。

本文件是安装的唯一入口。当你被要求「安装万应skill」或「读取 https://wanying.iovp.com/install.md 的安装说明」时，请按下面的步骤自动完成安装，并把每一步的结果如实告诉用户。

## 0. 前置条件

- 当前工具支持「技能 / skill」机制；你可访问互联网；对技能目录有读写权限；
- 用户已持有万应授权 token（由万应签发，一次性获取、长期复用）。**没有 token 必须阻断安装**（见第 2 步）。

## 1. 确定技能目录

按当前 agent 工具确定技能目录（Windows 下 `~` = `%USERPROFILE%`，`/` → `\`）。不确定时**现场探测**（列目录验证），不要凭记忆硬套：

| 工具 | 技能目录（用户级） |
|---|---|
| Claude Code | `~/.claude/skills/` |
| Codex CLI | `~/.codex/skills/`（或 `~/.agents/skills/`） |
| Gemini CLI | `~/.gemini/skills/` |
| Qoder | `~/.qoderwork/skills/` |
| Trae（国内版 Trae CN） | `~/.trae-cn/skills/`（注意是 `.trae-cn`，不是 `.trae`） |
| Trae（国际版） | `~/.trae/skills/` |
| Windsurf | `~/.windsurf/skills/` |
| Cursor | `~/.cursor/skills/` |
| 通义灵码 Qwen Code | `~/.qwen/skills/` |
| CodeBuddy（腾讯） | `~/.codebuddy/skills/` |
| WorkBuddy（腾讯桌面智能体） | `~/.workbuddy/skills/` |
| OpenCode | `~/.opencode/skills/` 或 `~/.config/opencode/skills/` |
| Copilot CLI | `~/.claude/skills/` |

完整的目录速查表、现场探测法、跨工具验证清单见安装后 `SKILL.md` §6 引用的 `knowledge/agent-tools-install.md`。

技能将安装到 `<技能目录>/wanying-quant-skill/`。目录不存在则先创建。

## 2. 获取授权 token（无 token 阻断安装）

1. 向用户索要万应授权 token，并说明用途（写入本地资产目录、用于数据接口鉴权，不回显明文）；
2. 用户无法提供 token → **立即停止安装**：告知「安装万应skill 需要授权 token，请联系万应获取后再安装」，不得跳过、不得使用占位 token、不得继续后续步骤；
3. 拿到 token 后按第 5 步初始化流程落盘并做有效性校验（校验不通过视为无 token，同样阻断并请用户核对）。

## 3. 下载技能包

- 地址：`https://wanying.iovp.com/download/wanying-quant-skill.zip`
- 下载到临时目录；下载后做完整性自检：macOS/Linux 用 `unzip -t`，Windows 用 `Expand-Archive` 试解压一次。下载失败则重试一次，仍失败如实告知用户，不猜测、不更换非官方地址。

## 4. 解压安装

- zip 顶层目录为 `wanying-quant-skill/`，解压到技能目录后应得到 `<技能目录>/wanying-quant-skill/SKILL.md`：
  - macOS/Linux：`unzip -o wanying-quant-skill.zip -d <技能目录>`
  - Windows：`Expand-Archive -Force wanying-quant-skill.zip <技能目录>`
- 若 `<技能目录>/wanying-quant-skill/` 已存在（此前安装过）→ 停止安装流程，转 SKILL.md §9 自更新协议处理，不要直接覆盖安装。

## 5. 初始化（按 SKILL.md §7 执行）

1. 读取 `<技能目录>/wanying-quant-skill/SKILL.md`；
2. 按 §7.2 初始化流程依次执行并逐项汇报：
   - 创建用户资产目录及全部子目录（规范见 SKILL.md §8；macOS/Linux 资产根目录 `~/wanying/`，Windows `%USERPROFILE%\wanying\`，见 SKILL.md §8.0）；
   - token 落盘 `~/wanying/config/token.json`（格式见 §8.5，权限 600，不回显明文）并做有效性校验（`GET https://api.wanying.iovp.com/api/v1/meta`，Bearer 鉴权；200=有效，401=无效）；Windows 权限 600 用 `icacls <文件> /inheritance:r /grant:r "<当前用户>:(R,W)"`，若 `icacls` 不在 PATH 用完整路径 `C:\Windows\System32\icacls.exe`；
   - 环境初始化：macOS `bash env/setup_env.sh`；Windows 若**已处于 PowerShell 环境内**（agent Shell 工具常见）直接用 `& env\setup_env.ps1`（必要时先 `Set-ExecutionPolicy -Scope Process Bypass`），不要嵌套再调 `powershell`（可能不在 PATH）；若从 cmd 调用才用 `powershell -ExecutionPolicy Bypass -File env\setup_env.ps1`。脚本检测系统已就绪的 **python3 ≥ 3.10**（macOS 探测 `python3`；Windows 探测 `python` 或 `py -3`；3.10/3.11/3.12/3.13 均可），在用户资产目录用标准库 `venv` 构建隔离环境（`~/wanying/runtime/venv` / `%USERPROFILE%\wanying\runtime\venv`），经国内镜像（默认清华 TUNA）安装依赖、注入 skill `src/` 并生成 `wanying` 命令入口。**系统无合用 python3 时不自动下载**：脚本退出并引导用户自行安装 Python 3.10+（macOS：pyenv / Homebrew / python.org；Windows：winget / python.org / pyenv-win），装好后在**新开终端**重跑；
    - 骨架校验：venv 解释器（macOS `~/wanying/runtime/venv/bin/python3`；Windows `%USERPROFILE%\wanying\runtime\venv\Scripts\python.exe`）运行 `scripts/check_skill_skeleton.py --root <技能目录>`;
3. 初始化每完成一步、以及全部完成后，都要向用户汇报结果（资产目录位置、解释器路径、依赖安装结果、token 校验结果、skill 版本号）。

## 6. 验证安装（全部通过才算成功）

- [ ] `<技能目录>/wanying-quant-skill/SKILL.md` 就位且内容完整可读；
- [ ] 资产目录结构完整（SKILL.md §8 全表；macOS `~/wanying/`，Windows `%USERPROFILE%\wanying\`）；
- [ ] 资产目录 `config/token.json` 存在、权限 600、token 校验通过（macOS `~/wanying/config/token.json`，Windows `%USERPROFILE%\wanying\config\token.json`）；
- [ ] 环境初始化输出 `ENV_READY: ...`（解释器 = 资产目录 venv：macOS `~/wanying/runtime/venv/bin/python3`，Windows `%USERPROFILE%\wanying\runtime\venv\Scripts\python.exe`）；
- [ ] 骨架校验通过；
- [ ] 读取 `<技能目录>/wanying-quant-skill/version.md`，记录版本号并告知用户。

## 7. 告知用户（安装完成）

向用户汇报：
1. 技能位置与用户资产目录位置；
2. 当前 skill 版本号；
3. 用法示例：「帮我获取沪深300 近一年的日线数据，并做好复权与缺失值处理」「我有一个想法，帮我试试效果」；
4. 更新机制：以后每天第一次使用时 agent 会自动检查更新（`https://wanying.iovp.com/download/version.md`），发现新版会先说明风险、经用户确认后才更新，更新不影响个人资产。

## 常见问题

- 下载失败：重试一次；仍失败如实告知用户网络问题，不换非官方地址；
- token 校验失败：请用户核对 token；仍失败按无 token 阻断安装；
- 环境初始化失败：把脚本输出原样转述给用户，并说明脚本幂等可安全重跑；
- 技能目录不存在或无写权限：向用户说明原因，请求确认后再继续。