半小时跑通一条交易建议:day-trader-skill 的最小可用上手路径
半小时跑通一条交易建议:day-trader-skill 的最小可用上手路径
“AI 交易代理”在 2026 年已经不是新鲜词,但多数项目在演示之后留给用户的是一条很长的工程化鸿沟:接数据、写回测、连券商、搭风控。而 day-trader-skill 想验证的恰恰是反面:把“从几千张图表里找出一个形态,到给出一带止损、止盈和仓位大小的完整交易建议”压缩成一条可以在本地离线复现的命令链。
这个仓库是 MIT 协议的 11 个 Claude skills 合集,全部是纯 Python 标准库代码,不要求 pip 安装任何第三方包,不需要 API key,默认 paper trading,且整个链路里没有任何一个工具能替你下单。更关键的是它的 tests/ 目录自带一套从真实数据裁切的离线 fixture,TSLA 在 2026-10-19 的那笔“reel”交易——从 scanner 到 risk 的每一个数字——都能用 --offline 参数在断网状态下逐步重放。
这就给了它一条非常少见的“最小可用上手路径”:不等你接好自己的行情源,就能在半小时内把整条链跑一遍,确认链路无断点,再决定要不要接真实数据。本文按这个路径走:环境准备、第一次离线运行、读懂输出、以及换数据源前要改的三处配置。
一、环境准备:一个 30 秒就能完成的依赖检查
这个套件的运行环境要求几乎为零,先对照清单确认:
| 依赖 | 要求 | 说明 |
|---|---|---|
| Python | 3.8+ | 所有脚本只用标准库,Nothing to pip install |
| Claude 宿主 | Claude Desktop / Claude Code / 任意能贴 SKILL.md 的聊天 | 没有 Claude Code 也可以,把单个 SKILL.md 贴在聊天开头当作一种模式运行(失去 Python 工具,但方法仍在) |
| Alpaca MCP server | 仅当要真正下 paper 单时 | 通过 uvx alpaca-mcp-server 挂载,paper 账户默认 |
sec_user_agent |
仅 news/analyst 类 SEC 工具需要 | 写进 trader/config.json 的 "sec_user_agent": "Your Name you@example.com" 或环境变量 SEC_USER_AGENT |
安装方式在 README.md 里给了四条路,任选其一:
- 在 Claude 里粘贴仓库地址加一句
install skill; - Claude Code 插件:
/plugin marketplace add Jakeschincariol/day-trader-skill然后/plugin install day-trader-skill@day-trader-skill(插件模式下命令名带命名空间,如/day-trader-skill:trader-scanner); git clone后把trader-*目录拷进~/.claude/skills/;- 项目级安装:拷进你仓库的
.claude/skills/。
目录结构本身就是文档:每个 trader-*/ 文件夹里只有两样东西——一份 SKILL.md(给 LLM 看的操作手册)和一个同名的 Python 脚本(真正干活的工具),再加上一个所有技能共用的状态目录 trader/:
trader-scanner/ SKILL.md, scan.py # 扫图
trader-entry/ SKILL.md, entry.py # 盯进场时机
trader-exit/ SKILL.md, exit.py # 定止损止盈
trader-timemachine/ SKILL.md, timemachine.py # 10,000 次重放
trader-budget/ SKILL.md, size.py # 仓位
trader-risk/ SKILL.md, check.py # 风控检查
trader-broker/ SKILL.md, ticket.py # 订单票(唯一能下单的入口)
trader/ config.json, entry.json, plan.json, orders.json, state/ # 链路共享的"黑板"
tests/ unittest 套件 + 离线 fixtures
README 里的链路图值得直接背下来,因为它是后文所有命令的排布依据:
scanner -> news -> entry -> exit -> timemachine -> budget -> risk -> broker (一笔交易)
alerts: stop, target, flat by the close (持仓期间)
news / analyst / pelosi (定时)
每个技能只读上一个技能写的 JSON,只写自己那一份。依赖检查到此为止——如果你连 pip 都没装,环境也已经“就绪”。
二、第一次运行:用离线样例数据把建议链跑通
仓库 tests/fixtures/ 里藏着一套从真实数据裁切的离线样例,这正是“最小可用路径”的载体。下面这条链路复现的是仓库 README 里的完整案例:2026 年 10 月 19 日(周一)的 TSLA,开盘区间突破(opening-range breakout,下称 ORB)。
第 1 步:验证仓库本身没坏(约 30 秒)。 测试套件完全离线,跑一遍就是对整条链的冒烟测试:
python3 -m unittest discover -s tests -v
它能复现 README 里引用的每一个数字,失败则说明环境或文件有问题,先修这个。
第 2 步:scanner——在 234 张真实图表里找突破。 fixture tests/fixtures/trader-scanner/wall5m-2026-10-19.json.gz 是当天 10:15 AM(美东)截面的 5 分钟 K 线墙:
python3 trader-scanner/scan.py orb --offline tests/fixtures/trader-scanner/wall5m-2026-10-19.json.gz \
--now "2026-10-19 10:15" --min-price 0
--now 把时钟钉在纽约时间 10:15,--offline 让 trader-scanner/scan.py 的 load_offline() 读本地文件而不是打 Yahoo。输出与当天实况一致:231 张可用图表,42 张在 10:15 前收在开盘区间高点上方,其中 TSLA 区间 354.47–362.18,10:10 那根 5 分钟 K 线收于 364.18,高出区间高点 0.55%。结果写入 trader/watchlist.json,供下游读取。
第 3 步:entry——把“突破”变成一个精确的时刻。 fixture tests/fixtures/trader-entry/TSLA-2026-10-19-5m.json 是 TSLA 当天的 5 分钟 K 线(含 Yahoo 的 live tick 这种脏数据,正好用来验证清洗逻辑)。离线文件不带 --now 时会以自己的 meta.regularMarketTime 为“当前时刻”:
python3 trader-entry/entry.py check TSLA --offline tests/fixtures/trader-entry/TSLA-2026-10-19-5m.json --write
trader-entry/entry.py 的核心是一条纯函数 evaluate(),规则苛刻到值得注意:只有收盘突破才算——一根 K 线中插上去再掉回来的上影线不算,恰好收在区间高点的价位也不算;K 线只有走完自己的 5 分钟才计入(now >= start + interval),不在 5 分钟网格上的 live tick(如 10:49:45)直接丢弃。它给出的是四态状态机:waiting(还差多少)、triggered(时间和价格)、expired(过了 no_entries_after 默认 15:30 仍未触发)、no-data。本例输出 triggered:10:15 AM,364.18,10:10 那根(bar 8)收盘突破区间高点 362.18。结果写入 trader/entry.json。
第 4 步:exit——进场之前先定退场。
python3 trader-exit/exit.py plan --from trader/entry.json --stop or-mid --target 1R --write
trader-exit/exit.py 用 Decimal 做到美分级的精确运算。orb 形态的默认止损是开盘区间中点:(362.18 + 354.47) / 2 = 358.325,多头止损向远离入场价方向取整(向下到美分),得 358.32;目标价 1R,即入场价加一倍风险距离:364.18 + 5.86 = 370.04。它还内置了几种拒绝逻辑:止损高于入场、风险小于入场价 0.05%(紧到撑不过点差)、entry.json 未触发时不给计划,都会给出人话理由。产物是 trader/plan.json。
第 5 步:timemachine——花一分钱之前先看概率。
python3 trader-timemachine/timemachine.py run --offline tests/fixtures/trader-timemachine/TSLA-60d5m.json.gz \
--now "2026-10-19 10:15"
trader-timemachine/timemachine.py 把该股此前 59 个完整交易日、每个交易日 78 根 5 分钟 K 线换算成“相对前收的比值池”,从入场价出发重放当天剩余时段 10,000 次(seed 默认 19,同一份数据在任何机器上可复现),每根 K 线从同一时段 ±2 根窗口里随机抽取。规则保守:一根 K 线同时碰到止损和止盈时,算止损。本例重放结果:先碰目标 29.4%、先碰止损 25.5%、收盘仍未了结 45.1%;再把同一规则跑回那 59 个真实交易日——触发 33 次,13 次先到目标、15 次先到止损、5 次都没到——结论一句:“close to a coin flip”(接近抛硬币)。这正是这个技能存在的意义:在风险暴露之前告诉你,这一单并不比抛硬币好多少。
第 6 步:budget + risk——仓位和风控关卡。
python3 trader-budget/size.py --write --now "2026-10-19 10:15"
python3 trader-risk/check.py --now "2026-10-19 10:15"
trader-budget/size.py 读 trader/plan.json 和 trader/config.json,按四个上限取最小值算整股数量:单笔最大亏损 50 / 每股风险 5.86 ≈ 8.53 → 8 股(约 $2,913.44),并在 why 字段写明是哪条上限起决定作用:“8 shares, bound by your $50 max loss per trade (8 x 5.86 = $46.88 at the stop)”。它只写一笔 bracket 订单提案到 trader/orders.json(buy 8 TSLA,stop-loss 358.32,take-profit 370.04),不下任何单。
trader-risk/check.py 逐单对照 config 里的十几条规则(单笔亏损、日亏损上限、每日笔数、盈亏比、入场时间窗、重复单、必须带止损……),每单 PASS 或 BLOCK 并附理由。仓库里留存的 trader/state/risk.json 是个很好的反面教材:在周末(2026-10-25,周日)检查同一笔订单,所有其他规则都过了,仍被 BLOCK,理由是一行话——window: the market is closed today (weekend, Sun 2026-10-25 02:02 New York)。裁决还带订单指纹(fingerprint),trader-broker 只对“今天、且逐字节相同”的那笔 PASS 放行。
到这里,半小时的预算基本用完,但产出是完整的:一条从图表形态到“买 8 股、止损 358.32、止盈 370.04、15:55 前必须了结”的建议,以及一条可复现的证据链。
三、读懂输出:价位、仓位、失效条件各对应什么
建议链的“黑箱”其实全在 trader/ 目录的三个 JSON 里,读懂它们就读懂了整个系统。
价位(entry.json)。 关键字段不是“买”,而是“什么时候才算买”:
{
"symbol": "TSLA", "setup": "orb", "status": "triggered",
"time": "10:15 AM", "bar_start": "10:10", "bar_index": 8,
"price": 364.18, "level": 362.18,
"opening_range": { "high": 362.18, "low": 354.47, "minutes": 15 },
"reason": "the 10:10 bar closed above the range high"
}
price 是触发 K 线的收盘价(即建议入场价),level 是被突破的价位(区间高点),bar_index 记下这是开盘后第几根 K 线——下游的 ATR 止损和 timemachine 的历史回放都依赖它。entry 脚本甚至会在触发超过一根 K 线后提醒你“late entry is a different trade”:价格、止损距离和概率都变了,旧建议作废。
仓位(orders.json)。 仓位不是按“想买多少”算的,而是按“最多亏多少”倒推的。risk_per_share = entry - stop = 5.86 决定一切:止损设得越远,股数越少。四个上限取最小:
| 上限 | 计算 |
|---|---|
| 单笔最大亏损 | max_loss_per_trade_usd / (entry - stop) = 50 / 5.86 |
| 仓位占比 | budget × max_position_pct / entry = 5000×75% / 364.18 |
| 单笔金额 | max_order_usd / entry = 4000 / 364.18 |
| 可用现金 | (budget × (1 - cash_buffer_pct)) / entry |
另外两条隐性的保命规则:市价单若 trader/prices.json 里有 15 分钟内的更新鲜价格且更高,会用新价格重新算风险(同止损下价涨 = 亏更多 = 股数减);算出 0 股或盈亏比低于 min_reward_risk 时是拒绝写单,而不是写一笔更小的单。
失效条件(plan.json + config.json)。 一笔建议的“死亡方式”被提前写死了三份:
- 价格失效:
stop: 358.32(区间中点,stop_detail字段甚至保留了指纹级的推导过程($362.18 + $354.47) / 2 = $358.325, rounded down)。README 里的原话值得抄在显眼处:A stop is a plan, not a guarantee——跳空或快市中止损单可能以远差于该价成交。 - 时间失效:
flat_by: "15:55",无论盈亏,收盘前必须了结,不隔夜;no_entries_after: "15:30"之后触发的 ORB 直接判expired。感恩节次日这类 13:00 提前收盘的日子,这两个时限会自动上移(12:30 / 12:55)。 - 账户失效:risk 层的
max_daily_loss_usd(默认 150)、max_trades_per_day(默认 3)按“今天已下单”累计,今天的每一笔新单都会和之前的单模拟成交后再一起校验,防止单笔都合规、合起来超限。
四、接自己的行情源:要改的三处
所有脚本默认读 Yahoo Finance 的免费非官方端点(query2 优先、429/5xx 时切 query1、429 退避一次)和 Nasdaq Trader 的符号目录。换成自己的数据源前,实际要动的地方只有三处——这也是这个代码库“标准库 + 单脚本 + 纯函数”设计的红利,没有抽象层要绕。
第一处:端点地址与抓取函数。 每个脚本顶部都挂着同一组常量,例如 trader-scanner/scan.py 里的 YAHOO_HOSTS、spark_path() / chart_path() 的 URL 模板、SPARK_MAX = 20(spark 端点每次最多 20 个符号)、PAUSE(礼貌间隔)和 BACKOFF(429 退避秒数)。trader-entry/entry.py、trader-exit/exit.py、trader-timemachine/timemachine.py 里是各自的副本。换源时把 yahoo_get() 换成你的抓取实现即可——注意所有业务逻辑都只依赖它返回的 JSON 文本,不依赖传输细节。
第二处:K 线的 JSON 结构(或干脆不改代码)。 解析集中在 parse_chart() / parse_spark() / series_from_result() 三个函数里,期望的是 Yahoo v8 chart(chart.result[0] 下的 timestamp + indicators.quote[0] 的 open/high/low/close/volume 列)和 spark 批量应答两种形状。如果你的数据源能直接产出这两种 JSON,最省事的接法是零代码改动:把数据按 <TICKER>.json(或 .json.gz)存盘,走各脚本原生的 --offline PATH 入口——这是仓库官方认可的数据接入点,测试套件全程就用它跑。若你的源是别的结构,就只改这几个解析函数,把列对齐成 {t, o, h, l, c, v, meta} 的纯列表,下游的 evaluate()、compute()、重放逻辑完全不用碰。顺带一提,时间处理是自研的:to_eastern() 用规则算美东 DST(2007 年后的美国规则),不依赖系统时区,--now 参数统一接受纽约墙钟时间——换成其他市场前,这套日历逻辑(NYSE_HOLIDAYS、提前收盘表、9:30–16:00 会话定义)是第二处需要审视的地方。
第三处:trader/config.json 的风险参数。 这是全链路唯一的“用户侧”配置,trader-budget/size.py 和 trader-risk/check.py 都从这里取规则(缺失键回落到各自的 DEFAULTS)。接实盘前建议逐项过一遍:budget(只放亏得起的钱)、max_loss_per_trade_usd / max_daily_loss_usd(决定仓位算式的分母)、no_entries_before / no_entries_after / flat_by(时间窗,纽约时间)、min_reward_risk、blocked(永碰名单)、sec_user_agent。以及最关键的两个开关:"paper": true 保持不动(Alpaca MCP server 默认也是 paper 账户),"pdt_guard": true 按你的券商是否仍执行旧的 25,000 美元 pattern-day-trader 规则来定——FINRA 已于 2026-06-04 取消该最低资金要求(Regulatory Notice 26-10),但券商可以一直过渡到 2027-10-20,你的账户可能仍按旧规执行。
五、边界:它不做什么,同样重要
上手路径之外,这个仓库最有价值的部分可能反而是它反复拒绝做的事,这些约束写进了每个 SKILL.md 的 Rules 段,值得作为使用惯例内化:
- 扫描结果是“匹配了规则的图表列表”,不是买入名单。 scanner 的输出措辞被规范为 “matched a setup”,禁止 “a buy / a winner”;部分成功会明说 “Fetched 4,980 of 5,259”,禁止把部分结果夸大成全市场。
- 没有任何工具能下单。 唯一通向订单的入口是 trader-broker,且三道闸门缺一不可:trader-risk 今天 PASS 了这笔指纹相同的订单、你在聊天里对这笔单明确说了 yes、Claude 自身的 “Allow once / Deny” 权限卡再点一次——README 明确要求把券商工具设成 “Needs approval” 而非 “Always allow”。
- 重放不是预测。 timemachine 只用该股最近 60 天的 5 分钟 K 线,财报、停牌、突发新闻都可以做出这 60 天没做过的事,它的概率输出应视为“现实检查”,不是承诺。
- 数据是免费且非官方的。 Yahoo 的 chart 端点不在官方 API 之列,会延迟、会改版、会限流;scanner 和 entry 读的是 1/5 分钟 K 线而非逐笔成交,“行动前拿券商数据核一遍重要结论”被写进了 fine print。
社区里对 AI 交易代理的讨论,过去一年明显从“模型能预测价格吗”转向了工程问题——风控分层、订单熔断、模拟盘优先。这个仓库是后者里一个极端的样本:它不解决“预测”,只解决“在你愿意承担风险之前,把每一步的算术做对、把每一步写下来、让你能随时复现和推翻它”。半小时跑通这条离线链路,验证的正是这套基础设施本身——而这恰好是大多数“AI 交易代理”演示里最先被跳过的部分。