maddogfinance/dsh-trading

dsh-trading

一个交易研究工作台，以 DeepSeek Harness（dsh）插件的形式构建。无需 fork，无需修改核心——只需在原生 web 或 headless 配置上叠加一个 bundle。

状态：早期脚手架。 dsh 本身处于开发者预览阶段，迭代很快；双方都可能出现破坏性变更。

工作台

在 dsh web 下启用可选的 shell 框架后，应用变为图表优先：左侧是持久、实时的图表列，右侧是对话。

┌──┬────────────────────────────────────┬─────────────────────────┐
│  │  CC.BTCUSDT   1m 5m [15m] 1h 1d    │  ⌄ Market Analyst       │
│▸ │  ┌──────────────────────────────┐  │                         │
│  │  │        ╱╲    ╱╲              │  │  MU is coiling under    │
│s │  │  ╱╲   ╱  ╲__╱  ╲_ ── 118,400 │  │  118.4k; the 15m ADX …  │
│e │  │ ╱  ╲_╱          ╲ ── 116,900 │  │                         │
│s │  │▁▂▃▁▂▄▃▁▂▃▅▂▁▃▂▁▄▃▁▂▃         │  │  ▸ annotate_chart       │
│s │  └──────────────────────────────┘  │    ✎ 6 marks — Show     │
│  │  ● live · 15m · 5:05:10 PM   📌    │                         │
└──┴────────────────────────────────────┴─────────────────────────┘
rail        the chart you drive          the agent you talk to

这一列是你的：输入一个代码，选择一个时间周期，它就会通过回环通道获取数据，完全不经过模型。它还会跟随对话——当 agent 绘制某个图表时，这一列会实时加载该标的，而不是镜像 agent 冻结的快照。只要触碰图表——无论是代码还是时间周期——就会将其固定，并显示一个 📌 标记；从那时起，agent 的绘图会以 pill 上的 Show 提议形式出现，而不会把图表从你脚下抽走。点击该标记即可重新开始跟随。

绘图在两个方向上以相同方式工作。annotate_chart 的水平线、区域和路径落在实时列上；同一分析中的文字部分——水平线表格、看涨/看跌情景卡片——留在聊天中，因为文本就该在那里阅读。循环就此闭合：面板会将它正在显示的内容发布回宿主，因此 agent 可以读取你的图表（get_chart_view，外加每轮一行上下文注入），而无需让你截图。

演示

图表列被固定到 Micron，而 agent 的标记是针对 Bitcoin 的，因此没有任何内容落地；一个 pill 提供这些标记，点击一次即可加载该图表及其六个标记

这一列被固定到 Micron。agent 的六个标记是针对 Bitcoin 的——不同的标的，因此谓词拒绝合并，没有任何内容落到错误的图表上。它们改为在 pill 上提供；点击一次即可加载该图表及其标记。右上角的时钟是来自本地 OpenD 的实时数据流，在整个片段中持续跳动。

▶ 观看完整的 90 秒带解说演示 ——
上面那个循环只是其中的一个节拍。完整剪辑还会走一遍外壳、代码框和时间周期行、智能体在实时列上绘制，以及每轮上下文行——让它无需索要截图就能读取你的图表。

这些都不是模拟：画面是 1920x1080 的 Playwright 录屏，来自针对实时 Futu OpenD 的真实会话，图表在每一个镜头中都在持续跳动。

更早的 v0.2 演示——聊天流中的图表卡片

▶ YouTube 上带解说的 80 秒演示

录制于图表优先外壳出现之前，至今仍准确展示了 web 界面在没有 @dsh-trading/client-frame 时的行为：智能体用交互式图表卡片作答，chip 会根据模型读取的逐根 K 线序列绘制指标面板，而 annotate_chart 通过信任门控在图表上放置价位——强制来源标注，价格会对照真实 K 线窗口进行校验。

dsh web 中的交互式图表卡片：chip 切换根据模型自身数字绘制的指标面板；annotate_chart 绘制经来源门控的价位

设计

八个包，一个依赖方向：

@dsh-trading/tool-market      面向模型的工具（list_symbols、get_ohlcv、
market_snapshot、annotate_chart、render_chart）
+ 指标库
│  消费
▼
@dsh-trading/market-data      接缝：ctx.marketData —— 类型化的 K 线/代码接口
▲  实现
│
@dsh-trading/provider-csv     参考提供方：本地 CSV 文件
@dsh-trading/provider-futu    实时提供方：港股 / 美股 / A 股股票以及
7x24 加密货币交易对，来自本地 Futu OpenD

@dsh-trading/risk-guard       独立模块：在 dsh 的 tools/pre-execute 门控处
拒绝来自任何插件的执行形态工具名

@dsh-trading/verdict          评估测试框架：audit_backtest 会对照真实 K 线
校验成交，运行带种子的随机基线和样本量功效
检验；lint_strategy_code 会搜寻前视泄漏。
判定结果可能诚实地是 NOT PROVEN。

@dsh-trading/client-chart     仅 web：卡片 + 持久图表列以及为其供数的
回环通道；宿主侧则是 get_chart_view 工具
和每轮上下文行，让智能体读取该列
│  填充图表席位
▼
@dsh-trading/client-frame     仅 web：外壳框架。将 dsh 自带的三列布局行
替换为图表优先的布局——
侧边栏 | 图表 | 对话 | 详情，
默认 70/30，侧边栏收起——并
声明 trading.chart 席位

- market-data 只定义接缝，别无其他（它唯一的对等依赖是 cordis）。每个消费者都与 ctx.marketData 对话；每个数据源都隐藏在 MarketDataProvider 之后。
- provider-csv 是自带数据模板：约 100 行，本地 //.csv 文件。把它复制一份，就能把 ClickHouse、券商 API 或 CCXT 放到同一接口之后——上游工具永远不用改。
- provider-futu 就是那个模板对着真实券商网关填好的版本：港股 / 美股 / A 股股票以及加密货币对（CC.BTCUSDT），最后这个是唯一在凌晨三点还在动的标的，这使它成为检验“实时”是否真的实时的诚实方式。它有意读取 Qot_GetKL 而不是 Qot_RequestHistoryKL：GetKL 走订阅配额并提供最近的 K 线（≤1000），而 RequestHistoryKL 消耗的是 OpenD 按账户资产配给的稀缺历史配额。这个取舍写在 provider 自己的 description 里，并在其行为中得到遵守——start / end 是过滤已获取的窗口，而不是去查找，所以查询更早的区间会诚实地返回空，而不是悄悄返回错误数据。设置见 实时数据；注意 OpenD 是绑定账户的个人网关，这是许可事实，不是配置问题。

futu-api 是一个对等依赖，故意不锁定版本。SDK 的版本与你安装的 OpenD 绑定，而不是与本包绑定，并且 Futu 明确表示其包版本遵循自己的方案而非 semver——所以没有任何范围能表达“兼容”，两者必须手动对齐。安装与你的 OpenD 匹配的 futu-api（10.9.x 的 OpenD 配 10.9.x 的 SDK）。provider 会在连接时通过 GetGlobalState 自行检查这一点，如果协议行不一致，就记录一条同时列出两个版本的警告——否则这种偏差会表现为握手被拒或解码为空，且无从指向。
- tool-market 在 ctx.tools 上注册只读分析工具。market_snapshot 一次调用就返回整个多时间框架指标状态（RSI、慢速随机指标、ADX/DI、MACD、MFI、ATR、SMA/EMA 姿态、布林带），并带有粗粒度状态标签；当结构重要时，get_ohlcv 提供原始 K 线。指标数学是纯函数且确定性的——教科书定义，在 Wilder 定义之处使用 Wilder 平滑——所以数值能与任何图表平台对账，会话日志回放也会重新计算出与模型所见完全相同的数字。
- client-chart 负责绘制图表，并从两个独立的入口驱动它们。模型的 market_snapshot / annotate_chart 结果通过 tool.call.toolview 接缝渲染为卡片。USER 直接驱动持久列：一个代码输入框和时间周期行通过该包宿主部分发布的回环 RPC 通道与 ctx.marketData 通信。第二条路径才是关键——一个唯一输入是“希望智能体调用正确工具”的工作台，在智能体更愿意聊天的那一刻就会停止工作，而这正是实践中会发生的情况。该通道暴露了 MarketDataProvider 的两个读取动词，外加一个仅记录面板正在显示内容的写入；它从不触及工具层，因此 risk-guard 的执行门禁既未被削弱，也未被绕过。

该列跟随对话，而不是镜像对话。当智能体绘制某个品种的图表时，面板会自行加载该代码和时间周期——逐字采用智能体的载荷会把一个冻结的 ≤200 根 K 线快照钉在屏幕上，而这正是它所取代的那个“为什么不动？”的 bug。它拒绝重新获取已经持有的序列（一次分析会在同一张图上调用 annotate_chart 几十次），而固定的列会完全停止跟随：智能体的图表变成药丸上的 Show 提议，而不是在阅读中途接管。该决策是一个带有自己测试套件的纯函数，因为埋在 useEffect 里的策略是没人能钉住的策略。

标记与 K 线分开呈现。智能体的绘图通过严格谓词与面板的序列匹配——相同品种、相同时间周期、价格位于可见范围内——因此在 1 小时图上绘制的水平线绝不会悄悄出现在 5 分钟图上，而落在范围外的标记会被报告为已丢弃，而不是被钳制。它们通过每个标签页的 sessionStorage 在重新加载后存活，因为当页面恢复时，发布它们的卡片可能已被虚拟化移除。标题以三条泳道布局，并设有最小间距，因此窄带内的十个水平线会读作十个水平线，而不是一团模糊；超过三次碰撞后，线仍会绘制，但标题会被丢弃。

该面板还会发布它正在显示的内容回宿主，宿主以两种方式将这些内容提供给模型：每轮一行上下文注入，以及一个 get_chart_view 工具，用于按需获取相同事实。这闭合了一个明显敞开的循环——面板的数据路径按设计绕过了工具层，因此用户图表的相关信息不会自行到达智能体，而智能体会要求用户对它正在两个列之外渲染的图表截图。当面板空闲时，注入不产生任何成本（空文本不构成贡献），发布的值在到达时会经过验证（它会进入模型的上下文，这使其既是正确性问题，也是提示注入面），并且它会在 30 秒后过期，因此一个被遗弃的第二个标签页无法让模型自信地说出错误的代码。
图表保持实时：它每秒重新读取最后几根 K 线，并按开盘时间合并它们，因此正在形成的 K 线会被原地替换，而新的 K 线会被追加——如果盲目追加，实时图表每轮询一次就会多出一根重复的蜡烛。更新通过现有绘图上的 updateData 进行，而不是重建，因此画布永远不会闪烁。刻意选择轮询而非推送：宿主通道是一元的，而一个只差几秒的图表，其价值远不值得投入流式传输那样的工程成本。当行情停止变动——连续八次轮询都没有带来任何新信息——面板会退避到每五秒一次，并在某根 K 线变动的瞬间立即恢复，这比发布一份市场日历更便宜，也更诚实。隐藏的标签页也会以同样的方式退避，而不是停止：一些嵌入式浏览器会在用户明明正在观看时报告 hidden，而在那里设置一个终止开关，与它所表现出的 bug 无法区分。
- client-frame 是同一个行交换思路在布局方面的一半。dsh 的 shell 是一个插件行（ui-layout），它占据内置的 root 槽位，并在其中声明 sidebar / conversation / details / shell.overlay 席位。槽位核心规定每个席位只能有一个声明者，因此一个框架无法与原有框架并排存在——该 bundle 会禁用那一行并插入我们的行，后者以相同的名称重新声明这四个席位。ui-sidebar 和 ui-conversation 按名称注册，因此 dsh 真正的侧边栏及其真正的对话界面会原封不动地挂载到第三方框架中；我们只决定列的顺序。在它们之上，它又增加了第五个席位 trading.chart，用于持久化的图表列。

它的默认值有意与原有 shell 不同。图表占据可用宽度的 70%，对话占 30——以比例而非像素宽度存储，因为“图表占 70%”必须在窗口大小改变后仍然有意义。对话的最小宽度从 dsh 的 640px 降到 420，因为在这里它是侧列，而不是整个应用；保持 640 会让分屏在笔记本电脑上无法实现。侧边栏初始折叠为图标栏：一个常驻的会话历史列相对于图表宽度来说是一笔糟糕的交易，因此该框架改为向 conversation.session.header.utilities 提供一个会话切换器——通往你会话的路径就在对话自己的右上角，紧挨着它所切换的对象。没有 fork，没有修补核心——与替换 market-data-provider 是同一套机制。

可选启用，而非捆绑。 这一行有意不出现在 @dsh-trading/bundle 中：替换整个 shell 太过主观，不能强加给每个安装该 bundle 的人。当你需要时，从你自己的 profile 补丁中添加它：

yaml
- id: ui-layout
disabled: true

- insert:
- id: trading-frame
name: '@dsh-trading/client-frame'
- bundle/trading 通过 cordis.patch.yml 将六行接入一个 dsh 配置文件：market-data、market-data-provider、tool-market、verdict、risk-guard、client-chart。用户从自己的配置文件补丁中重新指向或替换 market-data-provider 行——那次行替换就是 BYO 机制。shell 框架和 Futu 提供程序有意不在这些行之中；有关启用各自的代码行，请参见上文。

为什么选这个而不是另一个金融插件？

数据插件硬编码单一数据源；dsh-trading 定义了它们都可以接入的接缝。量化工具包为每个指标提供一个工具；market_snapshot 在一次调用中返回整个多时间框架状态，其状态标签根据四舍五入后的报告值计算，因此图表和数字永远不会不一致。而其他所有人的“仅供研究”只是 README 里的一句话——我们的是一个你可以测试的 tools/pre-execute 门禁。

硬性边界：仅供研究

本项目有意不包含订单执行能力，也不包含执行接缝。工具读取数据并进行计算；没有任何东西会下单、路由订单，或先模拟再转发订单。添加实盘交易执行功能的贡献不在范围内。此处内容均不构成投资建议。

@dsh-trading/risk-guard 将这一立场扩展到本项目未发布的插件之上：它在 dsh 的 tools/pre-execute 门禁处拒绝订单执行和资金转移类的工具名称，因此在 trading 配置文件中挂载券商插件不会悄悄获得交易能力。名称匹配是一种启发式方法，不可能完备——该防护是纵深防御，而非保证。保证是结构性的：不存在可触及的执行接缝。

数据格式（CSV 提供程序）

data/
AAPL/
1d.csv        # header: time,open,high,low,close,volume
BTC-USDT/
1h.csv        # ISO-8601 UTC bar-open times, ascending

用 dsh 试一试

一条命令——已发布的 bundle 从 npm 拉取其六个插件行
（client-frame 和 provider-futu 是可选的，见下文）：
sh
dsh plugin --profile trading add @dsh-trading/bundle

或者从代码检出开始（用于折腾这些包）

先构建，然后从本地路径组合配置文件。dsh 从配置文件目录解析插件行，
因此bundle 补丁所命名的每个包都必须与它一起被链接——漏掉一个，
该行就会在启动时解析失败：
sh
pnpm install && pnpm build
node examples/generate-sample-data.mjs

dsh plugin --profile trading add ./bundle/trading \
./packages/market-data ./packages/provider-csv ./packages/tool-market \
./packages/verdict ./packages/risk-guard ./packages/client-chart

如果你打算启用图表优先的 shell 或实时 Futu 数据，请将
./packages/client-frame 和 ./packages/provider-futu 添加到该列表中。

在配置文件的 dsh.profile.bundles 列表
（$DSH_HOME/profiles/trading/package.json）中，将 "@deepseek-ai/dsh-headless"（或 "@deepseek-ai/dsh-web-app"）添加到
@deepseek-ai/dsh-base 之后，以选择一个界面，配置一个模型
密钥（环境变量 DEEPSEEK_API_KEY，或 dsh web 下的 Models 页面），并在任意目录下运行，只要其 ./data 按上述布局存放 K 线数据：
sh
cd examples && dsh --profile trading "pull DEMO-EQ daily candles with sma20/sma50 and describe the trend"

随时用 dsh --profile trading --dump-config 验证组合后的各层配置。

实时数据：Futu OpenD

安装并运行 Futu OpenD，启用其 websocket 监听器——它与 api_port 是不同的端口，且 websocket_key_md5 对 JavaScript 客户端是必需的（没有它，OpenD 会以裸的 retType: -1 回应握手，且不带任何消息）。在 OpenD.xml / OpenD.ini 中：
ini
websocket_port = 33333
websocket_key_md5 =

然后安装匹配的 SDK，并从你配置文件的 cordis.patch.yml 中重新指向 provider 行：
sh
npm i futu-api@10.9   # must match your OpenD's version line
yaml
- id: market-data-provider
name: '@dsh-trading/provider-futu'
config:
host: 127.0.0.1
port: 33333       # the websocket port — NOT api_port (11111)
symbols:
- CC.BTCUSDT    # crypto: the one that moves 24/7
- HK.00700
- US.MU

symbols 是 list_symbols 报告的目录；任何 OpenD 知道的 symbol 仍可直接输入到图表列中。

Market Analyst 预设

presets/analyst/ 是一个 agent 预设，将原始工具转化为结构化的分析工作流：它先界定请求范围（时间跨度、关注点、时间周期），然后报告更高时间周期的背景、关键价位表、多时间周期指标状态（冲突之处明确指出而非平均掉）、带触发条件和失效条件的看涨与看跌情景，以及消解歧义的价位。安装它并在会话的预设菜单中选择 Market Analyst：
sh
DSH="${DSH_HOME:-$HOME/.dsh}"
mkdir -p "$DSH/.agent-presets" && cp -r presets/analyst "$DSH/.agent-presets/"

该 persona 以文字方式守住研究边界，就像 risk-guard 以代码方式守住它一样：报告数据所显示的内容，绝不推荐仓位或入场点。它还决定分析结果落在哪里——annotate_chart 绘制在读者的实时列上，而 render_chart 保留用于导出图像文件。把这一段写错，就会让绘图出现在聊天流中而不是图表上。

dsh web 中的图表卡片

在 web 界面下，market_snapshot 和 get_ohlcv 的结果会渲染为交互式 K 线卡片（@dsh-trading/client-chart）：K 线 + 成交量 + SMA20/50/200、时间周期标签页，以及一条 chip 条，既显示模型读取的确切指标值，又可切换对应的面板（RSI、慢速随机指标、ADX/DI、MACD、MFI，以及作为价格叠加层的布林带）。每个面板都绘制自模型所获得的同一逐 bar 序列，而非在浏览器中重新计算——这正是该卡片永远不会与分析文本相矛盾的原因
此外。图表数据搭载在持久化的 tool/result 事件的呈现元数据上：它从不进入模型的上下文（零 token 成本），并随会话日志一起重放。

卡片渲染器仅限 Web 端；在无头配置下，dsh 回退到通用文本卡片，回环通道永远不会出现。不过，宿主端在那里并非惰性——只要 ctx.tools 和 ctx.systemPrompt 存在，get_chart_view 和每轮上下文行就会注册，并仅报告一个已关闭的面板。

开发
sh
pnpm install
pnpm typecheck
pnpm build
pnpm test

路线图

- [x] 用于叠加到 dsh --profile web 的配置模板 + 文档
- [x] dsh web 中的图表卡片（@dsh-trading/client-chart）：market_snapshot / get_ohlcv 渲染为交互式 K 线图，并带有芯片切换的指标面板
- [x] annotate_chart：由模型编写的价位/区域/路径，带有强制来源和硬性价格区间门控，外加基准/备选情景——在卡片上渲染并附带价位表
- [x] 面向生态构建者的开放契约（CONTRACTS.md）：图表载荷、开放标注信封、纯渲染器注册表
- [x] 图表优先外壳（@dsh-trading/client-frame）以及由用户驱动的持久实时列，代理的绘图会落在其上
- [ ] 图表面板深化：用户绘图反馈给代理，用于平移回看数据的 @Remote 宿主服务
- [ ] 监视/告警契约（仅通知）、@dsh-trading/contracts 包、一致性测试夹具
- [ ] 研究日志会话事件（假设、信号——可重放）
- [ ] 作为 ctx.commands CLI 命令的确定性回测运行器（从不由模型执行）
- [ ] 更多提供方：Parquet、ClickHouse、CCXT

许可证

MIT