dsh-btc-dashboard

dsh plugin --profile web add dsh-btc-dashboard

btc_dashboard

OKX BTC / ETH 合约价格看板的 DSH 插件工程。

.env                                    # OKX 密钥（生产 + 模拟/调试），仅用于确认「配了哪把钥匙」
.env.example                            # 密钥模板（只有占位符；行情接口本身不需要密钥）
.dashboard/state.json                   # 插件持久化的选择（环境 + 周期），已被 .gitignore 忽略
package.json                            # 包清单：dsh.bundle.patch + dsh.client（npm / GitHub 安装的入口）
cordis.patch.yml                        # bundle 层：把 Host 半（plugin/dsh-btc-dashboard/index.js）挂进 profile
plugin/dsh-btc-dashboard/               # 插件代码（包根在仓库根；安装后位于包内）
  ├─ index.js                           # Host 半：取数、代理隧道、EMA、路由、回测 job
  ├─ client.js                          # 浏览器半：canvas 看图 + 周期/环境切换 + 画线
  └─ README.md                          # 实现细节、参数、路由、环境语义
backtest/                               # 回测框架（随 npm 包一起发布；CLI 与看板共用同一份）
  ├─ run.mjs                            # CLI 入口（--strategy/--start/--end/--bar/--leverage/--maker/--taker…）
  ├─ lib/                               # config / data / transport / engine / metrics / report / strategy
  ├─ strategies/                        # 内置策略：buy-hold（基线）、sma-cross（示例）、
  │                                     #           multi-tf-dual（4h 多空主策略）、adaptive-dual（1D 多空备选）、
  │                                     #           breakout-hold（只做多主策略）、donchian-trend、ema-regime、ma-hysteresis
  ├─ tools/sweep.mjs                    # 参数扫描（训练/验证切分，研究用）
  ├─ SPEC.md                            # 内部契约（接口/数据结构/撮合口径）
  ├─ README.md                          # 使用与设计文档（参数表、ctx API、局限）
  ├─ data/                              # 历史 K 线缓存（运行时生成，gitignore）
  └─ reports/                           # 回测报告产物（运行时生成，gitignore）
tests/                                  # 离线自检脚本（含 backtest-*.mjs 九个）
screenshots.json                        # 市场截图清单（dsh-market 详情页用）
assets/icon-180.png                     # 插件市场卡片图标（awesome-dsh-plugin 条目的 icon）
assets/screenshots/                     # 市场截图：dashboard / alert / backtest
docs/awesome-entry.yml                  # 提交到 awesome-dsh-plugin 的条目 YAML（复制进 data/plugins/）

画线数据（直线/斐波那契）存在浏览器 localStorage，不写这个目录。

它是什么

一个 DSH 插件：侧边栏底部多一个 📊 按钮（显示实时价与涨跌幅），点开是全屏看板 ——

支持两个合约：BTC-USDT-SWAP / ETH-USDT-SWAP（面板顶部 BTC / ETH 分段按钮切换，

选择记在浏览器 localStorage；切换后 K 线、价格、均线、画线、预警判定与回测默认标的都跟着走），

最新价格、1m/3m/15m/1h/4h/1D 六个周期的 K 线、默认 EMA20/EMA480 双均线（周期可在面板上改），

周期可切换、生产/模拟环境可切换，图表可拖动平移 / 滚轮缩放 / 双击复位 / 按住轴拖动缩放，

并支持画直线、斐波那契与尺子（默认 0/0.5/1/1.5/2；尺子量价格差/涨跌比例/时长，端点可吸附到 OHLC，

画完能点选、拖端点、隐藏、单条删除）。

跟随最新时有当前价水平线 + 收盘倒计时，未收盘那根 K 线单独描边；时间刻度对齐整点并带纵向网格线；

键盘可用（←/→ 平移、Ctrl+↑/↓ 缩放、Alt+R 回最新、1–6 切周期）。

均线在浏览器里按整条序列（1800 根，含预热）现算，所以拖到哪个窗口，均线就画到哪儿，改周期也是即时重算（见[插件 README](plugin/dsh-btc-dashboard/README.md#均线ema怎么算的窗口外为什么也有)）。

只读公开行情：插件不发任何私有请求，账户/持仓那部分代码已移除（见[插件 README](plugin/dsh-btc-dashboard/README.md)）。

细节见 [插件 README](plugin/dsh-btc-dashboard/README.md)。

同一仓库里还有一个独立的回测框架 backtest/（见下节）：同样的 OKX 永续（BTC / ETH 都在白名单里）、

同样只读公开行情，用来在历史 K 线上验证策略想法 —— 默认 1 倍杠杆、挂单 0.0200% / 吃单 0.0500%，可指定回测区间。

安装

发布到 npm 后：

dsh plugin --profile web add dsh-btc-dashboard
# --profile 换成你的 profile 名（如 web）；装完重启该 profile，浏览器刷新页面即可

也可以直接从 GitHub 源码装（仓库根就是包根，backtest/ 会一起带上）：

dsh plugin --profile web add "github:altmanWang/dsh_plugin_btc_dashboard"

• 只读 OKX 公开行情（ticker / candles），不需要 API key，不读账户与持仓；
• 回测框架 backtest/ 随包发布，装完就能在面板里跑回测；K 线缓存与报告写到 <工作区>/.dashboard/backtest/（首次跑会联网抓数据）；
• 可选：把 .env.example 复制成 .env 填上密钥，面板才会显示当前环境「配了哪把钥匙」的掩码（不填也能正常看行情）；
• 邮件提醒是可选通道：依赖 dsh-qq-email 插件（已上架 DSH 插件市场，插件 → 发现 / Discover 可搜到）。

不装它插件照常启动，看板/均线/画线/回测都不受影响；要用邮件时预警面板会直接提示去安装，装完重启宿主即可；

• 零第三方 npm 依赖，Node 版本跟随宿主；卸载：dsh plugin --profile web remove dsh-btc-dashboard。

本地开发安装 / 卸载

在本仓库里开发时，用 plugin_manager 的 install_bundle（或 dsh plugin add）把仓库根链接进 profile

（包根在仓库根；不要只指到 plugin/dsh-btc-dashboard，否则 backtest/ 不会跟着走）。

profile 里的依赖是链接形式，所以这个目录就是线上代码：改客户端半刷新页面即可，改 Host 半需要重启宿主。

当前磁盘上是 1.8.1。1.8.1 只改了邮件通道的可选依赖提示：没装 dsh-qq-email 时插件照常启动，

预警面板会提示去「插件 → 发现 / Discover」安装；Host 半（提示文案）有改动，需要重启宿主。

Host 半有改动，需要重启宿主 —— 1.8.0 增加了 ETH-USDT-SWAP：

看板顶部 BTC / ETH 切换、侧边栏价格跟随、回测面板「标的」下拉（Host 半新增

SUPPORTED_INSTS 白名单，board/price/backtest/health 都按白名单走）。

1.7.1 给回测周期加了 5m

（backtest/lib/config.mjs 是 Host 动态 import 的模块，宿主不重启不会出现新周期；

超短线实测结论见 backtest/README.md）。1.7.0 把资金费率（funding）计入了回测：

引擎按 8 小时结算从现金扣款，OKX 历史只保留最近约 3 个月、更早区间按估算费率补并在报告里标注；

报告格式升到 v3（K 线 + 资金费率 + 交易标记）。1.6.0 把回测框架接进了看板：

新增 5 条 /dsh-btc/backtest/* 路由（策略列表 / 启动回测 / 进度轮询 / 报告 / 取消），

Host 侧用异步 job 跑回测、按需动态 import 仓库里的 backtest/ 框架；看板工具条多一个「回测」面板。

1.5.0 新增了预警邮件的三条路由

（/dsh-btc/email 读 / 写、/dsh-btc/notify-email 发信）并在发信时取宿主侧服务 ctx.qqEmail。

1.4.1 给 candles 补上了第 7 位 done（0/1）；1.4.0 的说明里曾写着"这一位早就在发，

只是客户端以前没用"，那是错的：宿主当时只发了 6 位，于是「收线预警」从来没跑过，

而控制台一句报错都没有。

1.4.0/1.4.1 是客户端半的一轮 UI/UX 改造：最新价线 + 收盘倒计时 + 未收盘 K 线描边、

时间刻度对齐整点并带纵向网格、悬浮改成「压中 K 线才弹数据框」、滚轮缩放连续化 + 按住轴拖动缩放、

指针事件化（触摸可用）、键盘与焦点管理、直线 / 斐波那契 / 尺子（尺子量价格差与涨跌比例、

端点吸附 OHLC、画完一条自动回到平移）、画线可选中/拖动/隐藏/单条删除、

均线支持任意条数、可增删改（默认 EMA20 + EMA480：工具条上就一个 均线管理（N） 按钮，

点开是均线看板 —— 新增 / 删除 / 改周期 / 换颜色 / 显隐 / 恢复默认全在里面，Esc 收起；

逐条显隐也可以直接点画布左上角的图例；配置存 localStorage）、

EMA 图例移到画布左上角且可点击开关、

收线预警（K 线收线后收盘价上穿/下穿指定均线时提示：规则可增删改、绑周期、只在收线那刻判一次；

提示走面板 toast + 价格行常驻条 + 桌面通知（需授权）+ 提示音（WebAudio，需先与页面交互）

+ 邮件（走 dsh-qq-email 的宿主服务 ctx.qqEmail；填地址时确认一次，之后自动发往该地址，

内容含规则/周期/收线时间/触发那根 K 线的 OHLCV）；

预警记录持久化到 localStorage、可一键清空；判据日志记下每次判定"为什么中/为什么没中"

（带前收/今收/前均/今均，看板里可「复制自检」整段导出排障）；

判定常驻执行（引擎挂在 shell.overlay，关掉看板也在跑））、

可视区间统计（高/低/量/涨跌幅）接了出来、

刷新计时自走 + 数据陈旧标记、画布光标统一为黑色十字、工具条标签行内对齐。

期间修掉一批真 bug：所有 K 线实体串成一个颜色（bodyOf 漏设 fillStyle）、

切周期 / 点画线抛 ReferenceError 导致面板自己关闭（函数定义被删、只剩 ref 上的副本）、

一个会把浏览器转死的死循环（时间刻度起点算错）、

「关掉均线后在图例上点不回来」（图例只列可见的那些 → 行号错位，修了两次）、

以及均线整条画不出来却不报错（新加的 lines 与网格的 var lines 同名，被 var 提升覆盖）。

那个"点不回来"第二次的成因很像：

…(truncated)