合约实验室 limboinf/dsh-crypto-workbench

dsh-crypto-workbench · 合约实验室

主流币 USDT 永续合约的 AI 辅助交易工作台 · DeepSeek Harness（dsh） 插件

[!WARNING]
本项目是作者为满足个人需求而开发的演示项目，不构成任何投资建议。
USDT 永续合约杠杆交易风险极高，可能在短时间内损失全部保证金。项目内的一切输出——机会雷达、Jev 决策、简报、风险闸门、交易计划——都只是作者自用的纪律与复盘工具，不预测行情、不承诺收益、也不能保证避免损失。参考本项目做出的任何交易决策，后果自负。→ 完整免责声明

这是什么

背景很简单：我想试试用现在的 AI 技术和工具帮我做加密货币投资——往欧易（OKX）账户里投入 ¥1,000，让 AI 负责分析、决策、下单和复盘，看看它最终的能力到底怎么样。

于是有了这个挂在 DeepSeek Harness（dsh）上的插件：一个 30 天、逐仓、默认 10x（最高 50x）的短线 USDT 永续合约投机实验台。系统负责数据汇总、技术面与消息面分析、风险计算、计划编排、受控执行与复盘；不承诺收益，不做价值投资、长期持有或估值判断；下单必须经过你的两句明确指令。

不改动 dsh 核心代码。数字只走本地确定性数据层，模型只负责解读：

OKX MCP（账户/仓位/行情/消息/永续下单）─┐ ├─→ 规范化 → 风险引擎 → CryptoWorkbenchPayload ─→ crypto_* 工具 → 模型解读 / 简报 / 风险审查 OKX 公共 REST（行情兜底）───────────┘ ├─→ 侧边栏面板（七区）金十标准 MCP（Bearer HTTP，只读）────────→ Jin10DashboardPayload ────┘ └─→ 计划 / 成交 / 决策日志

四条贯穿全部代码的设计纪律：

1. 零运行时依赖：不 import 任何 @deepseek-ai/ 运行时符号，dsh 侧类型全部自声明。
2. 数字只算一次：金额、杠杆、张数、回撤、强平距离都在 host 确定性层算完进 DTO；模型与前端只解读、只格式化，不能改。
3. 闸门代码算死：风控等级由 risk.ts 确定性计算，模型与前端只能解释，不能覆盖。
4. 不猜数：缺数据返回 null 或 blocked，「无消息」不是信号，坏记录 fail-closed。

把这个项目发给你的 AI

本仓库的 README 与 AGENTS.md 就是按「AI 可自助照做」写的：把整个项目发给你的 AI 编码助手（Claude Code、ZCode、Codex 等皆可），让它帮你完成所有操作——安装 OKX Agent Trade Kit、克隆并构建 DeepSeek Harness、生成本机挂载 patch、写入金十配置、安装技能、跑 typecheck / test / live-check 验证，以及之后的日常改代码。

唯一需要你亲自去做的是 API Key 的申请（涉及账户注册与实名，AI 代办不了）：

- OKX API Key：OKX 官网「API 管理」创建；单独建 profile，只给「读取 + 交易」权限，不带提币，建议先用 demo 盘跑通。
- 金十 MCP Bearer Token：金十官方渠道申请；不配则金十 tab 不可用，其余功能不受影响。
- OpenRouter API Key（可选）：openrouter.ai 申请，Jev 决策监控用；不配则监控显示 no_key。

Key 拿到手之后，交给 AI 或自己按下文「快速开始」配置即可——Key 只进本机 ~/.okx/config.toml 与 CRYPTO_DATA_DIR/env，不进仓库、不进 patch、不进日志。

界面预览

主界面：对话 + 工作台面板。 左侧向模型提问（回答按事实/推断分段，数字全部来自工具返回），右侧「合约实验室」面板一屏展示实验总览、当前仓位与白名单行情卡片。

主界面：对话与合约实验室面板

风控闸门、消息时间线与计划复盘。 闸门阈值由代码计算，当前状态一屏可见；消息时间线可切换 OKX / 金十双源。

风控闸门与消息时间线

币种详情：Jev 决策监控。 点行情卡片进入：实时走势折线（含决策点）、语义桶输入、决策卡（买入/卖出/观望概率与置信度，置信度 <0.5 一律观望）与决策流水。

币种详情与 Jev 决策卡

核心能力

| 能力 | 入口 | 说明 |
| 完整快照 | 工具 crypto_snapshot | 净值（¥/USDT）、可用/占用保证金、仓位（张数/币数/强平距离）、行情、消息时间线、机会雷达、风险指标与闸门 |
| 机会雷达 | 快照 opportunities + 工具 crypto_radar_config | 扫描主流币白名单（BTC/ETH/SOL/BNB/SUI/DOGE/ZEC/HYPE，对话可增删、上限 8 个观察币种）；24h/3d/7d 三窗趋势必须同向，四因子评分（趋势强度 35 + 动量质量 20 + 资金费健康度 25 + 区间位置 20）≥ 70 才显示；每 60s 独立重扫 |
| 交易计划 | 工具 crypto_create_plan / crypto_update_plan | 按净值 × 风险比例反推张数、名义价值、所需保证金（含手续费与资金费缓冲）；executable 只表示风控通过，不会自动下单 |
| 受控执行 | 工具 crypto_execute_plan / crypto_cancel_plan_order / crypto_close_position | 三道门：引擎按当前快照重算无 blocker → 计划已被你「确认」→ 你明确说「执行」（confirm=true）。逐仓设杠杆 → 限价单附带标记价触发的止损/止盈 → 回执与成交自动落盘。平仓同样要你明说 |
| 成交与复盘 | 工具 crypto_record_fill / crypto_log_decision / crypto_activity | 手工录入成交、决策日志（假设/执行/复盘/备注）、按日活动记录，全部本地 JSONL |
| Jev 决策监控 | 面板币种详情 + 工具 crypto_jev_watch | 经 OpenRouter 调 ~typesafe/jev-latest（choice 原语）：host 把 5s 行情算成语义桶（趋势/区间位/资金费/持仓/闸门/消息窗）喂给它，每个 tick 返回 买入/卖出/观望 + 概率分布 + 校准置信度；置信度 <0.5 一律观望。纯建议层：不生成计划、不触碰执行三道门，调用失败 fail-open |
| 金十财经 | 工具 crypto_jin10_（quote/kline/flash/news/calendar） | 标准 MCP Streamable HTTP；报价、K 线、快讯、资讯、财经日历；独立只读 tab，不进 OKX 快照、闸门或执行链 |
| 实验生命周期 | 工具 crypto_experiment | start / end / status；开始时定格日初净值，30 天后自动结束 |
| 工作台面板 | dsh web 侧边栏 | 实验总览 · 风控闸门 · 当前仓位 · 行情 · 消息时间线（OKX / 金十双 tab） · 计划与复盘；行情卡片可进币种详情（SVG 走势 + Jev 决策卡） |
| 用户偏好 | 工具 crypto_preferences + 面板「配置」 | 回答方式、小白白话模式、分析重点、机会候选条数、主动提醒、消息预览条数、面板刷新间隔；偏好只影响表达与展示，不能覆盖风控和执行硬规则 |
| 简报 / 风险审查 | 技能 crypto-briefing / crypto-risk | 数字只能引用工具返回；事实/推断/行动三分段；行动必须人工确认 |
| 快捷命令 | /crypto /crypto radar /crypto jev <标的|off> /crypto-activity /jin10 | 不经模型，面板取数用 |

风控闸门（代码计算，模型与前端不能覆盖）

| 条件 | 结果 |
| 当日亏损 ≥ 10% | paused_today：今日不出计划 |
| 峰值回撤 ≥ 20% | leverage_cap_10x：杠杆上限 10x |
| 峰值回撤 ≥ 35% | demo_only：仅模拟 |
| 净值 < ¥300 | experiment_ended |
| 连续亏损 ≥ 3 笔 | review_required：禁止加杠杆与摊平，先复盘 |
| 数据过期 / 强平价不可得 / 2h 内高影响宏观事件 | blocked：暂不生成可执行计划 |

单笔风险建议 3–5%；杠杆默认 10x，>10x 需用户明确确认（confirmedHighLeverage），20x 为人工确认上限，50x 是硬上限不是推荐值。执行前还会复核：计划未过期、最新价距入场区间边沿偏离 ≤3% 且未越过止损价、账户持仓模式（hedge 自动带 posSide）。

依赖与前提

本项目零运行时 npm 依赖（devDependencies 仅用于构建与测试），但运行依赖以下外部环境：

| 依赖 | 要求 | 用途 |
| DeepSeek Harness | 本地 clone 并完成 pnpm install + pnpm run build:lib | 宿主框架，本插件以 patch 方式挂载 |
| Node.js | ≥ 18（开发机在 24 上验证） | 构建与测试 |
| OKX Agent Trade Kit | @okx_ai/okx-trade-mcp / @okx_ai/okx-trade-cli ≥ 1.4.6 | 提供 OKX MCP server（行情/账户/消息/永续交易）；安装见下 |
| OKX API Key | 单独建 profile，只给「读取 + 交易」权限，不带提币 | 配置在 ~/.okx/config.toml；本插件经 dsh 工具通道间接调用，从不接触 Key/Secret/Passphrase。建议先用 demo 盘跑通 |
| 金十 MCP（可选） | Bearer Token | 财经快讯/报价/日历 tab；不配置则该 tab 显示未配置 |
| OpenRouter API Key（可选） | — | Jev 决策监控；不配置则监控状态为 no_key（面板会提示） |

OKX Agent Trade Kit 安装：

npm i -g @okx_ai/okx-trade-mcp@1.4.6 @okx_ai/okx-trade-cli@1.4.6

快速开始

1. 挂载 OKX MCP + 本插件（开发模式）

复制 cordis.dev.patch.yml 为 cordis.dev.local.patch.yml（已被 .gitignore 排除，避免把本机路径提交进仓库），把 command 改成本机 which okx-trade-mcp 的路径、--profile 改成你的 profile，然后：

cd /path/to/deepseek-harness
pnpm dsh --profile web --patch /path/to/dsh-crypto-workbench/cordis.dev.local.patch.yml
安装模式：pnpm dsh plugin --profile web add github:limboinf/dsh-crypto-workbench，再把 dev patch 里的 mcp-okx 那段（填好本机路径）复制进 profile 的 cordis.patch.yml。

MCP 纪律：显式写 --profile，--modules 只留最小集 market,account,news,swap。只想观察不想下单时，加回 --read-only，两个执行工具会自动报「通道未启用」。

2. 配置金十 MCP（可选）

金十用插件内置的标准 MCP HTTP 客户端，不需要在 dsh patch 里再挂一个 MCP server。把地址和 Token 写进本机数据目录：

mkdir -p ~/.dsh/crypto-workbench
chmod 700 ~/.dsh/crypto-workbench
cat >> ~/.dsh/crypto-workbench/env <<'EOF'
CRYPTO_JIN10_SERVER_URL=https://mcp.jin10.com/mcp
CRYPTO_JIN10_BEARER_TOKEN=替换为你的_Bearer_Token
EOF
chmod 600 ~/.dsh/crypto-workbench/env

Token 只放 ~/.dsh/crypto-workbench/env 或进程环境变量，不能写进仓库、patch、README 或日志。

3. 验证

pnpm dsh --profile headless --patch <local.patch> --dump-config | grep -E "crypto|okx"

打开 dsh web，对模型说「调用 crypto_snapshot」→ 工具返回快照，侧边栏出现「合约实验室」面板。展开「消息时间线」，切到「金十数据」应看到报价、财经日历、快讯和资讯；也可调用 crypto_jin10_quote { code: "XAUUSD" } 验证。

4. 安装技能（推荐）

mkdir -p ~/.dsh/skills && cp -R skills/crypto-briefing skills/crypto-risk ~/.dsh/skills/

5. 开始实验

对模型说「开始实验」→ 模型调用 crypto_experiment action=start，记录开始时间与起始净值峰值；30 天后自动结束。

一笔交易的完整流程

问「看看行情」「有没有机会」只出文字分析（方向/入场/止损/失效）；进入下面流程要从明确要计划开始。

1. 「起草一个 ETH 做多计划，入场 X，止损 Y」→ crypto_create_plan，返回计划卡与 blockers
2. 「审查一下」→ crypto-risk 技能逐项复核（可否决，不可推翻引擎）
3. 「确认这个计划」 → crypto_update_plan confirmed（有 blocker 会拒绝）
4. 「执行」 → crypto_execute_plan confirm=true：重算引擎 → 设杠杆 → 限价单 + 止损/止盈 → 回执、成交、执行日志落盘
5. 「撤单」→ crypto_cancel_plan_order confirm=true；「平仓」→ crypto_close_position confirm=true；「复盘」→ crypto_activity + crypto_log_decision

confirmed 只表示用户确认了这份计划的参数，不代表当前价格仍在执行窗口。执行前会用最新快照重新复核风险、数据新鲜度、张数和价格；如果行情偏离、最新价不可得或风控条件变化，计划会自动锁定为 needs_review，保证未下单，并拒绝对同一计划重复执行。needs_review 不能原地恢复为 confirmed，必须重新评估并创建新计划。

模型不得替你说第 3、4 步；两个执行工具没有 confirm=true 一律不动。

安全模型

- Key 不经手：OKX 凭证只存在于 ~/.okx/config.toml（OKX Kit 管理），本插件经 dsh 工具通道间接调用，代码里没有 Key/Secret/Passphrase 的读取路径；建议单独建「读取 + 交易」权限、不带提币的 profile，并先用 demo 盘验证。
- 写操作白名单：写工具只有永续的设杠杆/下单/撤单/平仓/查单/查成交；现货、期权、划转、提币在代码里没有入口。模型直连 OKX 写工具会被全局 guard 拒绝，未知形态 fail-closed。
- 三道门：引擎重算 blockers 为空 → 计划 confirmed → 执行 confirm=true，三者缺一不可；用户只说「确认」不等于「执行」。
- 只读退路：OKX MCP 加 --read-only 启动，执行工具自动报「通道未启用」，其余功能（快照/雷达/面板）不受影响。
- Token 纪律：金十 / OpenRouter 的 Key 只放 CRYPTO_DATA_DIR/env（建议 chmod 600）或进程环境，不进仓库、不进日志。

配置

| 变量 | 默认 | 说明 |
| CRYPTO_DATA_DIR | ~/.dsh/crypto-workbench/ | 数据目录 |
| CRYPTO_OKX_SERVER | okx | dsh 里 OKX MCP 的 serverName（工具名前缀 mcp__okx__） |
| CRYPTO_NEWS_TOOL | 未设 | 金十等外部消息源在 dsh 里的工具全名（如 mcp__jin10__get_flash）；不设则只用 OKX news 模块 |
| CRYPTO_OKX_REST_BASE | https://www.okx.com | 行情 REST 兜底基址（MCP 未挂载时行情仍可用，账户永远走 MCP） |
| CRYPTO_JIN10_SERVER_URL | 未设 | 金十标准 MCP HTTP 地址；与 Token 同时配置后启用金十数据线 |
| CRYPTO_JIN10_BEARER_TOKEN | 未设 | 金十 Bearer Token；仅放本机 env 或进程环境 |
| CRYPTO_JIN10_QUOTE_CODES | XAUUSD,USOIL,USDJPY,EURUSD | 金十 tab 默认展示的报价品种，调用前会读取 quote://codes 过滤 |
| CRYPTO_OPENROUTER_API_KEY | 未设 | Jev 决策监控的 OpenRouter API Key；未设时回退进程环境变量 OPENROUTER_API_KEY，都没有则监控状态为 no_key |
| NODE_USE_ENV_PROXY | — | 代理环境下 Node 的 fetch 不认 HTTP_PROXY，REST 兜底需设 1（MCP 自带代理支持，不受影响） |

以上都可写在 CRYPTO_DATA_DIR/env（KEY=VALUE 一行一个）。

可配置（面板「配置」入口或 crypto_preferences）：回答方式（简洁/结论优先/详细）、小白白话模式、分析重点、最多机会候选 0–2 条、主动提醒开关与条数、消息预览条数、面板刷新间隔 5/10/15 秒。雷达观察币种由 crypto_radar_config 独立配置。

不可配置：单笔风险上下限、最大杠杆、持仓限制、风控闸门、数据新鲜度、交易白名单、止损要求、事件黑窗、仓位计算公式、价格偏离检查、计划过期校验、执行三道门和用户确认要求。任何配置都不能把「被风控拦截」改成「允许执行」。

数据存放

~/.dsh/crypto-workbench/
├── experiment.json 实验开始/结束/起始与峰值净值 ├── daily/YYYY-MM-DD.json 日初净值 ├── plans/YYYY-MM-DD/.json 交易计划（一计划一文件） ├── fills/YYYY-MM-DD.jsonl 成交流水 ├── decision-logs/YYYY-MM-DD.jsonl 决策日志 ├── preferences.json 工作台用户偏好 └── env 可选配置

写入全部「校验 → 临时文件 → 原子 rename」；坏行不覆盖、fail-closed。快照只在内存流转、不落盘，复盘依靠 plans / fills / decision-logs。

开发

npm run typecheck # tsc --noEmit
npm test # node:test，覆盖快照、风控、执行、偏好与金十 MCP 链路
npm run live-check # 联网走 OKX 公共 REST：BTC/ETH 行情 + USDT-CNY 汇率
npm run build # tsdown → lib/index.js（host）+ lib/client.js（client）

开发模式注意：host 是常驻进程，改了 src/.ts 必须重启 dsh；client 改完 npm run build:client 后也要重启 dsh（client 包按 rev 缓存，只刷浏览器拿不到新代码）。

- AGENTS.md —— 模块地图与设计纪律（改代码前必读）
- CONTEXT.md —— 术语表与产品决策记录
- docs/ —— 技术实现方案、可行性与 MVP 方案

明确不做

自动加仓 / 自动止损以外的算法单 / 网格 / DCA / 跟单 / 期权 / 白名单外的币种 / 现货 / 划转提币；模型不得自行发起确认或执行；不追加预算；不通过提高杠杆绕过闸门。

⚠️ 免责声明

本项目（dsh-crypto-workbench / 合约实验室）是作者出于个人兴趣与自用需求开发的演示项目，用于验证一套「数据汇总 → 风险闸门 → 人工确认 → 受控执行 → 复盘沉淀」的个人交易流程，仅用于技术交流与学习。

- 不构成任何投资建议。项目内的一切输出——包括但不限于机会雷达、四因子评分、Jev 决策监控、简报、风险闸门、交易计划与执行流程——都只是作者自用的纪律工具与实验记录，不代表对任何行情的判断，不构成对任何人的投资建议、要约或招揽。
- 不承诺收益，不保证安全。USDT 永续合约杠杆交易风险极高，可能在极短时间内损失全部本金。风控闸门与三道门是流程纪律，不是资金安全承诺；任何历史实验结果都不代表未来表现。
- 风险自担。任何人参考、复用或二次开发本项目所产生的交易行为及其全部后果，由行为人自行承担。请先评估自身风险承受能力，必要时咨询持牌专业人士。
- 数据与口径。项目内行情、净值与指标来自 OKX / 金十等第三方接口，可能存在延迟、口径差异（如 USDT 计价与美元口径、UTC+8 涨跌幅）或错误，作者不对其准确性与完整性作任何担保。

本软件以 MIT 协议按「现状」（AS IS）提供，不附带任何形式的担保，详见 LICENSE。

License

MIT