setup

setup

识别 upbit-strategy-toolkit 的使用模式，并诊断 CLI 是否能在当前环境中运行。此技能是模式检测和诊断工具，不负责自动安装。create-strategy 和 backtest 用于创建策略和进行回测。

如果缺少 uv，请参阅 references/ 中对应操作系统的安装说明：

• uv 安装参考：references/uv-install.md

---

触发条件

• “首次使用”
• “如何设置环境？”
• “uv 是什么？/ 提示说缺少 uv”
• 其他技能（create-strategy/backtest）检测到环境要求未满足（缺少 uv、uv sync 失败、CLI 执行失败等），并建议转到此处

自动路由建议：如果 create-strategy / backtest 首次调用时无法运行包装脚本，建议使用 setup。

路由约定

• 角色：环境诊断和恢复入口
• 下一步：create-strategy
• 恢复入口：当 create-strategy 或 backtest 检测到缺少 uv、uv sync 失败或 CLI 执行失败时，引导至此技能
• 不在范围内：此技能不负责策略设计、回测解读或市场规则相关工作

请勿执行

• 请勿随意更改用户的系统 Python——uv 会在虚拟环境中隔离所需版本。不要引导用户升级或降级系统 Python。
• 不要建议使用 pip install -g——克隆模式的依赖通过 uv sync 保留在虚拟环境中。
• 不要连接实盘交易——请参阅实盘交易防护措施。

---

工作流

逐项检查通过或失败后，再进行下一项。遇到失败时，准确说明失败的命令和发生的错误。

setup

[ ] 1. Identify usage mode
[ ] 2. Check uv installation
[ ] 3. Run mode-specific CLI diagnostics

1. 识别使用模式

检查当前工作区是否为 upbit-strategy-toolkit 仓库。

模式	检测方式	默认数据根目录（除非运行过 config set data-dir）
克隆模式	当前工作目录或某个上级目录的 pyproject.toml 中包含 name = "upbit-strategy-toolkit"，且存在 upbit_strategy_toolkit/	运行时的当前工作目录
Agent 技能模式（全局）	使用 npx skills add ... -g 安装技能；包装脚本自身的路径直接位于 $HOME/.claude/skills、$HOME/.agents/skills 或 $HOME/.cursor/skills 下	运行时的当前工作目录
Agent 技能模式（项目级）	使用 npx skills add ...（不带 -g）安装技能；包装脚本自身的路径不位于上述主目录下的技能路径中，且当前工作区不包含 upbit-strategy-toolkit 仓库	运行时的当前工作目录

如果既没有 UPBIT_TOOLKIT_DATA_DIR，也没有已保存的 config set data-dir 值，CLI 会在运行时将当前工作目录解析为数据根目录，无论使用哪种模式。如果用户运行过 config set data-dir，则使用保存的值。请使用 config get data-dir 报告解析后的值，不要根据上表中的模式推断。

2. 检查 uv 是否已安装

uv --version

如果正常输出，则此项通过。如果缺少 uv，请指向 references/uv-install.md，并在安装后再次检查 uv --version。

3-A. 克隆模式诊断

从仓库工作区/当前工作目录运行。

uv sync
uv run upbit-strategy-toolkit --help

uv sync 会创建 .venv/，并准备所需的 Python 和依赖。克隆模式诊断通过的标准是 uv run upbit-strategy-toolkit --help 能输出帮助信息。

如果失败，请准确说明失败的软件包和发生的错误。不要用随意执行 pip install 的方式绕过问题。

3-B. Agent Skills 模式（全局或项目级）诊断

如果尚未克隆仓库，请直接从 GitHub 源运行 CLI 进行检查。全局安装和项目级安装的此步骤相同。

uvx --from git+https://github.com/upbit-official/upbit-strategy-toolkit.git upbit-strategy-toolkit --help

如果打印出了帮助信息，则表示 Agent skills 模式诊断通过。如果失败，请根据原始错误报告是缺少 uv、GitHub 访问失败，还是获取 Python 3.12 失败。

---

双向交接

设置完成后 -> create-strategy

诊断通过后，使用以下语句自然地交接给下一个技能：

upbit-strategy-toolkit CLI diagnostics complete. You can now create a strategy.

Next step: create-strategy skill
- Start with natural language such as "Create a golden cross strategy".
- The generated {data_root}/strategies/{slug}.json can be validated with the backtest skill.

设置期间受阻 -> 如实报告

不要评判好坏，准确说明哪个步骤产生了哪条错误：

[Step 2 blocked] `uv --version` returned "command not found"
-> Shell restart or PATH check is required (see references/uv-install.md)

[clone mode Step 3 blocked] pandas wheel build failed during `uv sync`
Original error: ...
-> Recheck Python 3.12+ availability. If system Python is 3.11 or lower, run `uv python install 3.12` and retry.

[agent skills mode Step 3 blocked] GitHub access failed during `uvx --from ... upbit-strategy-toolkit --help`
Original error: ...
-> Network or GitHub access permissions need to be checked.

---

实盘交易防护规则

与 create-strategy / backtest 的政策相同。即使在设置期间，也要拒绝实盘交易集成请求。

回复模板：如果用户的消息使用韩语，请使用韩语版本；否则使用英语版本。

韩语：

이 도구는 백테스트(과거 데이터 시뮬레이션) 전용입니다.
실전 매매가 필요하다면 [upbit-agent-skills](https://github.com/upbit-official/upbit-agent-skills)를 이용해주세요.

setup 스킬은 백테스트 환경 설정만 지원합니다.

英语：

This tool is for backtesting (historical data simulation) only.
Use the separate [upbit-agent-skills](https://github.com/upbit-official/upbit-agent-skills) tool for live trading.

The setup skill only supports backtest environment setup.

---

执行规则摘要

• 先识别模式，然后只运行该模式对应的诊断命令
• clone 模式：uv --version、uv sync、uv run upbit-strategy-toolkit --help
• Agent skills 模式（全局或项目级）：uv --version、uvx --from git+https://github.com/upbit-official/upbit-strategy-toolkit.git upbit-strategy-toolkit --help
• 不要引导用户更改系统 Python——uv 会在虚拟环境中隔离它
• 仅以事实陈述的方式报告失败（步骤 + 命令 + 原始错误）
• 设置完成后，自然地交接给 create-strategy
• 拒绝实盘交易请求，并引导至 upbit-agent-skills