# QuantDinger 功能使用项目日志（2026-05-15）

> 本文档记录一次本地 QuantDinger 平台的功能配置、视觉伴随使用、AI 分析、策略生成与回测演示过程，并整理使用中发现的不完善点与后续二次开发建议。

## 1. 背景

本次使用目标：

1. 启动并验证 QuantDinger 本地服务。
2. 配置平台可用的 LLM 服务，使 AI 分析、指标代码生成等能力可用。
3. 通过浏览器伴随方式演示平台主要功能。
4. 重点演示：
   - AI 资产分析
   - 从分析报告生成策略
   - 指标 IDE 回测
5. 记录使用过程、验证结果、不完善点和后续优化建议。

## 2. 本地服务与访问地址

### 2.1 实际运行服务

本次使用时，Docker 容器已经由用户手动启动，实际运行服务如下：

| 服务 | 说明 | 实际访问/端口 |
|---|---|---|
| `quantdinger-frontend` | 前端页面 | `http://localhost:8889` |
| `quantdinger-backend` | Flask API | `http://127.0.0.1:5001` |
| `quantdinger-db` | PostgreSQL | `127.0.0.1:5433` |
| `quantdinger-redis` | Redis | `127.0.0.1:6380` |

后端健康检查地址：

```text
http://127.0.0.1:5001/api/health
```

### 2.2 登录信息

本次登录使用：

```text
用户名：quantdinger
密码：用户已改为自定义密码
```

> 注意：项目日志中不记录真实密码和 API Key。

## 3. LLM 配置过程

### 3.1 目标

将 QuantDinger 的 LLM provider 配置为用户提供的 cliproxy OpenAI-compatible 服务。

最终配置方向：

```text
LLM_PROVIDER=custom
CUSTOM_API_URL=http://172.130.2.23:8317/v1
CUSTOM_MODEL=gpt-5.4-mini
AI_CODE_GEN_MODEL=gpt-5.4-mini
```

其中：

| 配置项 | 用途 |
|---|---|
| `LLM_PROVIDER=custom` | 使用自定义 OpenAI-compatible provider |
| `CUSTOM_API_URL` | cliproxy 的 OpenAI-compatible `/v1` 地址 |
| `CUSTOM_API_KEY` | cliproxy 鉴权 Key，日志中不记录明文 |
| `CUSTOM_MODEL` | 通用 AI 分析、AI 决策等默认模型 |
| `AI_CODE_GEN_MODEL` | 指标 IDE 的 AI 代码生成模型 |

### 3.2 模型选择验证

测试过多个模型后，选择 `gpt-5.4-mini` 作为默认模型，原因是它对 OpenAI-compatible JSON mode 返回较稳定。

验证要点：

- `/v1/models` 可返回模型列表。
- `/v1/chat/completions` 可正常响应。
- 后端 `LLMService.call_llm_api(...)` 实际调用成功。
- 使用 JSON mode 时，`gpt-5.4-mini` 能稳定返回类似 `{"ok": true}` 的结构。

### 3.3 注意事项

1. 如果 cliproxy 部署在宿主机本地，而后端运行在 Docker 容器内，不能直接在容器内使用 `localhost` 指向宿主机服务。
2. 本次最终使用远程地址 `http://172.130.2.23:8317/v1`，避免了容器访问宿主机的问题。
3. 设置页可能会显示 API Key 明文，截图和日志中应避免泄露。
4. 设置页曾出现 OpenRouter API Key 无效提示，但当前 provider 为 `custom`，该提示不影响本次 custom LLM 调用。

## 4. 平台主要功能导览

本次浏览器伴随使用中观察到左侧主要模块：

| 模块 | 说明 |
|---|---|
| AI 资产分析 | 对股票、加密货币、宏观数据进行 AI 分析 |
| 指标市场 | 查看/购买/使用已有指标 |
| 指标 IDE | 编写指标代码、AI 生成指标、图表验证、回测 |
| 策略与实盘 | 创建策略、设置信号/实盘执行、查看策略列表 |
| 交易机器人 | 管理自动交易机器人相关功能 |
| 我的资料 | 用户资料、交易所配置、通知配置等 |
| 设置 | 系统设置、LLM provider 配置等 |

## 5. AI 资产分析演示

### 5.1 标的

本次重点分析：

```text
BTC/USDT · 比特币
```

### 5.2 AI 分析结论摘要

分析报告给出的核心判断：

| 项目 | 结果 |
|---|---|
| 决策 | SELL / 卖出 |
| 信心 | 61% |
| 当前价格 | 约 80,388 - 80,630 美元 |
| 多时间框架共识 | 卖出 |
| 综合评分 | -34.2 |
| 时间框架一致性 | 50% |
| 24 小时展望 | 看跌（适度） |
| 3 天展望 | 看跌（轻微） |
| 1 周展望 | 中性/区间 |
| 1 个月展望 | 中性/区间 |

技术与市场结构要点：

- RSI 约 56-57，偏中性。
- MACD 死叉，看跌。
- MA 趋势仍为上升趋势。
- 当前价格接近阻力位。
- 24h 成交活跃度大幅下降。
- OI 上升约 8.26%。
- 资金费率接近 0 或略负。
- 多空比偏空。
- 挤压风险为中等。

### 5.3 对分析结论的评估

分析报告有一定参考价值，但 `SELL` 标签偏激进。

合理之处：

1. MACD 死叉、价格靠近阻力、成交活跃度下降，确实支持短线谨慎。
2. 报告没有高置信度看空，而是给出 61% 信心，和“轻微/适度短线偏空”较匹配。
3. 报告承认趋势仍向上、宏观略支持、存在 short squeeze 风险。

不完善之处：

1. 文本中说“证据不足以支撑高信心买入或卖出”，但标签直接给 `SELL`，结论比正文更激进。
2. 风险回报比约 `1:0.72` 或 `1:0.77`，做空收益空间小于止损风险，不适合机械执行。
3. 时间框架一致性仅 50%，1 周和 1 个月仍是中性/区间，不支持趋势级别强空。
4. `交易量活动变化 -90%+` 数据较极端，需要核查定义、数据源和计算口径。
5. 负资金费率 + OI 上升 + 多空比偏空，可能表示空头拥挤，若上破阻力存在 short squeeze 风险。

建议解读：

> 该分析更适合作为“短线不要盲目追多/偏谨慎”的风险提示，而不宜直接理解为“当前价无脑做空”。

## 6. 生成策略功能演示

### 6.1 入口

在 BTC/USDT AI 分析报告中的“下一步”区域，点击：

```text
生成策略
```

点击后跳转到：

```text
策略与实盘 → Create Strategy
```

URL 中携带了分析上下文，例如：

```text
mode=create
market=Crypto
symbol=BTC/USDT
from_analysis=1
decision=SELL
entry_price=...
stop_loss=...
take_profit=...
```

说明“生成策略”会将 AI 分析报告中的标的、方向、入场价、止损、止盈等作为创建策略的上下文。

### 6.2 创建策略配置

本次演示策略配置：

| 字段 | 配置 |
|---|---|
| 指标 | `[示例] MACD 柱穿零轴` |
| 交易对 | `BTC/USDT` |
| 市场类型 | 期货 |
| 杠杆 | 默认 5x |
| 交易方向 | 仅做空 |
| K 线周期 | 15 分钟 |
| 执行模式 | 仅信号（推送通知） |

### 6.3 交易对含义

策略创建页中的“交易对”指策略运行的市场标的。

例如：

```text
BTC/USDT
```

表示策略会读取 BTC/USDT 的 K 线、价格、成交量等数据，并在该标的上产生信号。

它不是交易所账户，也不是资金账户，而是策略应用对象。

与其他字段关系：

| 字段 | 作用 |
|---|---|
| 指标 | 决定何时出信号 |
| 交易对 | 决定信号作用在哪个资产上 |
| 周期 | 决定用哪个 K 线周期计算指标 |
| 市场类型 | 决定现货/期货规则 |
| 交易方向 | 决定允许做多、做空还是双向 |

交易对支持多选，理论上可将同一策略模板应用到多个标的。

### 6.4 AI 决策过滤器含义

创建策略时有一个开关：

```text
启用 AI 智能决策过滤器
```

该功能可理解为在指标信号之后增加一层 LLM 判断：

```text
指标代码产生原始信号
        ↓
AI 决策过滤器结合当前市场环境进行二次判断
        ↓
通过：推送或执行信号
拦截：不推送或不执行
```

本次 LLM 配置下，该功能如果调用统一 `LLMService`，理论上会使用：

```text
CUSTOM_MODEL=gpt-5.4-mini
```

即通过：

```text
http://172.130.2.23:8317/v1
```

调用 cliproxy 后面的模型。

注意：

- `CUSTOM_MODEL` 更可能用于通用 AI 分析和 AI 决策过滤。
- `AI_CODE_GEN_MODEL` 更可能用于指标 IDE 的 AI 代码生成。
- 本次两者均配置为 `gpt-5.4-mini`，所以效果上是同一模型。

使用建议：

| 场景 | 建议 |
|---|---|
| 演示/观察/仅信号模式 | 可以开启，作为信号质量过滤 |
| 自动实盘交易 | 谨慎开启，需先做模拟验证 |

风险：

1. LLM 判断可能不稳定。
2. 模型延迟可能影响信号时效。
3. 模型输出格式异常可能影响执行链路。
4. 回测环境和实盘环境可能无法完全复现 AI 过滤器行为。

### 6.5 策略创建结果

本次保存成功，策略列表中出现：

```text
[示例] MACD 柱穿零轴 Strategy-BTC/USDT
```

状态：

```text
Stopped
```

说明策略已创建，但未启动。

## 7. 回测功能演示

### 7.1 入口

在 BTC/USDT AI 分析报告的“下一步”区域点击：

```text
回测
```

跳转到：

```text
指标 IDE
```

URL 携带：

```text
market=Crypto&symbol=BTC/USDT
```

说明回测入口会继承分析报告中的市场和标的上下文。

### 7.2 回测页面观察

进入指标 IDE 后，右侧工作区包含两个页签：

| 页签 | 说明 |
|---|---|
| 图表 & 交易 | 查看图表、指标、快速交易等 |
| 回测 & 结果 | 设置回测参数并运行回测 |

本次进入“回测 & 结果”后，页面加载的是默认示例指标：

```text
[示例] 布林带触及
```

代码中的策略参数：

```python
# @strategy stopLossPct 0.02
# @strategy takeProfitPct 0.04
# @strategy entryPct 0.3
# @strategy tradeDirection long
```

即：

| 参数 | 值 |
|---|---|
| 止损 | 2% |
| 止盈 | 4% |
| 单笔仓位 | 30% |
| 方向 | Long |

### 7.3 回测结果

在 BTC/USDT 上运行默认布林带 Long 示例策略，回测结果：

| 指标 | 结果 |
|---|---|
| Total Return | -1.30% |
| 最大回撤 | -2.45% |
| 夏普比率 | -2.16 |
| 胜率 | 20.00% |
| 盈亏比率 | 0.48 |
| 交易次数 | 5 |

交易明细：

| # | 类型 | 退出原因 | 入场时间 | 出场时间 | 结果 |
|---|---|---|---|---|---|
| 1 | LONG | Take profit | 2025-12-16 | 2025-12-17 | +$118.75 |
| 2 | LONG | Stop loss | 2026-02-01 | 2026-02-01 | -$61.90 |
| 3 | LONG | Stop loss | 2026-02-02 | 2026-02-02 | -$61.52 |
| 4 | LONG | Stop loss | 2026-02-05 | 2026-02-05 | -$61.14 |
| 5 | LONG | Stop loss | 2026-02-06 | 2026-02-06 | -$60.76 |

最终余额约：

```text
$9,870.44
```

### 7.4 回测结论

默认布林带 Long 示例策略在当前 BTC/USDT 回测区间表现不佳：

- 总收益为负。
- 夏普比率为负。
- 胜率仅 20%。
- 盈亏比低于 1。
- 5 笔交易中 4 笔止损。

但该结果不能直接代表 AI 分析中 `SELL` 结论无效，因为当前回测策略是默认布林带 Long 示例，并不是 AI 分析生成的空头策略。

## 8. 使用中发现的不完善点

### 8.1 AI 分析结论标签偏硬

问题：

AI 分析正文承认“方向不够清晰、证据不足以支持高信心买入或卖出”，但最终标签显示为 `SELL`。

影响：

用户可能将风险提示误读为明确交易指令。

建议：

1. 增加信号等级，例如：
   - Strong Buy
   - Buy
   - Watch / Neutral
   - Reduce / Defensive
   - Sell
   - Strong Sell
2. 对低置信度或低一致性信号，显示为“偏空观察”而非直接 `SELL`。
3. 在 UI 中突出显示置信度和风险回报比，不让单一标签主导判断。

### 8.2 风险回报比不佳时仍给 SELL

问题：

BTC/USDT 报告中的风险回报比约 `1:0.72` 或 `1:0.77`，收益空间小于止损风险，但仍给出卖出建议。

建议：

1. 当风险回报比小于 1 时，策略建议应降级为“观察/等待更好入场”。
2. 增加规则：如果风险回报不达标，则禁止输出强交易建议。
3. UI 可提示：

```text
当前风险回报比不足，不建议按该止损止盈机械执行。
```

### 8.3 多时间框架一致性较低仍给方向性结论

问题：

时间框架一致性只有 50%，中期仍为中性/区间，但报告给出 `SELL`。

建议：

1. 当一致性低于阈值时，标签应显示“Mixed / 分歧”。
2. 单独展示短线、中线、长线建议，避免合并成单个方向。
3. 生成策略时应询问用户采用哪个周期的观点，而不是默认继承总标签。

### 8.4 成交量活动变化数据口径不清

问题：

报告显示交易量活动变化约 `-90%`，数值极端，但 UI 未解释计算口径。

建议：

1. 增加 tooltip，解释该指标来源和计算方式。
2. 显示该指标所用时间窗口、交易所范围、采样方式。
3. 对异常值增加数据质量提示。

### 8.5 生成策略和回测存在语义断层

问题：

- “生成策略”会继承 AI 分析中的决策、标的、止损止盈等上下文。
- “回测”只继承市场和标的，进入指标 IDE 默认示例策略。

这会导致用户误以为回测是在验证刚才的 AI 分析结论，但实际跑的是默认指标策略。

建议：

1. 从 AI 分析页点击回测时，应提供选项：
   - 回测当前 AI 分析逻辑
   - 回测已创建策略
   - 打开指标 IDE 自定义回测
2. 如果进入默认示例策略，应明确提示：

```text
当前回测使用默认示例指标，并非 AI 分析报告中的 SELL 逻辑。
```

3. 支持将 AI 分析结论自动转为临时回测策略，例如：
   - MACD 死叉过滤
   - ATR 止损止盈
   - 阻力突破止损
   - 支撑附近止盈

### 8.6 创建策略时交易对选择体验不够直观

问题：

策略创建表单中的交易对选择是多选控件，但 BTC/USDT 需要通过添加到观察列表弹窗后才被选中，交互路径较绕。

建议：

1. 如果从 AI 分析报告进入策略创建页，自动预填当前标的。
2. 若标的不在观察列表，应弹出轻量确认：

```text
BTC/USDT 尚未在策略交易对列表中，是否添加并选择？
```

3. 交易对多选框应支持直接搜索并选择，而不是绕到观察列表管理体验。

### 8.7 AI 决策过滤器模型来源不够透明

问题：

页面只显示“启用 AI 智能决策过滤器”，但没有说明调用哪个 provider、哪个模型、使用什么输入和决策标准。

建议：

1. 在开关旁显示当前模型，例如：

```text
当前 AI 决策模型：custom / gpt-5.4-mini
```

2. 提供“查看决策提示词/输入字段”的开发者模式。
3. 在策略运行日志中记录每次 AI 过滤器的判断：
   - 原始指标信号
   - AI 是否放行
   - AI 理由
   - 模型名
   - 响应耗时
   - 错误/超时状态

### 8.8 默认实盘模式风险较高

问题：

创建策略第二步默认或显著展示“实时交易”，容易让新用户直接进入自动下单路径。

建议：

1. 默认选择“仅信号”。
2. 用户首次切换到实盘时要求二次确认。
3. 如果没有交易所凭证，则自动降级到仅信号模式。
4. 在实盘前强制展示：
   - 最大仓位
   - 杠杆
   - 止损是否配置
   - 单笔风险占账户百分比

### 8.9 回测默认策略与 AI 分析方向不一致

问题：

AI 分析为 SELL，但回测默认加载的是 Long 布林带示例。

建议：

1. 回测页应读取 `decision=SELL` 或上一页上下文，默认选择短线/做空方向。
2. 或提示当前回测策略方向与 AI 分析方向不一致。
3. 在回测结果标题中显示策略来源：

```text
当前回测：默认示例策略 / 非 AI 分析策略
```

### 8.10 API Key 与通知 Token 有明文暴露风险

问题：

设置页和用户资料页可能直接显示 API Key、Telegram Bot Token 等敏感字段。

建议：

1. 默认隐藏敏感字段，仅允许点击临时显示。
2. 截图模式自动遮罩密钥。
3. 日志与前端错误提示不得回显密钥。
4. 支持一键轮换/撤销密钥。

## 9. 后续二次开发建议

### 9.1 AI 分析到策略的一体化闭环

建议形成闭环：

```text
AI 分析 → 生成候选策略 → 自动回测 → AI 总结回测结果 → 用户决定保存/优化/放弃
```

关键能力：

1. AI 分析报告结构化输出。
2. 自动生成策略代码或策略参数。
3. 一键回测该策略。
4. 回测结果反向反馈给 AI。
5. AI 提出优化建议，但不自动实盘。

### 9.2 AI 分析报告结构化 schema

建议后端输出稳定 JSON schema：

```json
{
  "symbol": "BTC/USDT",
  "decision": "SELL",
  "confidence": 0.61,
  "timeframe_consensus": 0.5,
  "entry_price": 80388,
  "stop_loss": 84530,
  "take_profit": 77164,
  "risk_reward": 0.77,
  "reasons": [],
  "risks": [],
  "strategy_candidate": {
    "direction": "short",
    "filters": ["macd_death_cross", "near_resistance", "volume_weakness"],
    "risk_model": "atr"
  }
}
```

好处：

- 生成策略更稳定。
- 回测可直接使用结构化字段。
- UI 可单独展示冲突信号。

### 9.3 回测入口增加策略来源选择

建议点击“回测”后弹窗：

```text
请选择回测对象：
1. 当前 AI 分析结论生成的临时策略
2. 已创建策略：[示例] MACD 柱穿零轴 Strategy-BTC/USDT
3. 默认指标 IDE 示例策略
4. 自定义指标代码
```

### 9.4 AI 决策过滤器可观测性

建议增加运行日志表：

| 字段 | 说明 |
|---|---|
| 时间 | 信号产生时间 |
| 标的 | BTC/USDT |
| 原始信号 | BUY / SELL / CLOSE |
| 指标来源 | MACD / RSI / 自定义指标 |
| AI 决策 | PASS / BLOCK |
| 模型 | gpt-5.4-mini |
| 原因 | 模型解释 |
| 耗时 | 毫秒 |
| 错误 | 超时/格式错误等 |

### 9.5 策略回测支持 AI Filter 模拟

当前 AI 过滤器更像实盘/信号侧功能。建议回测支持：

1. 不启用 AI Filter 的基准回测。
2. 启用 AI Filter 的模拟回测。
3. 对比两者差异：
   - 信号减少数量
   - 胜率变化
   - 收益变化
   - 回撤变化
4. 缓存模型判断，避免重复调用 LLM。

### 9.6 风险闸门

建议在策略保存和实盘启动前加风险闸门：

```text
- 风险回报比是否 >= 1.2
- 最大单笔亏损是否 <= 账户 1%-2%
- 是否配置止损
- 是否使用过高杠杆
- 回测交易数是否足够
- 最大回撤是否超过阈值
```

若不满足，提示用户风险并要求确认。

## 10. 本次验证结论

本次已验证：

1. QuantDinger 本地服务可访问。
2. 自定义 cliproxy LLM 配置可用于 AI 分析。
3. BTC/USDT AI 分析功能可正常运行。
4. 从 AI 分析报告点击“生成策略”可进入策略创建流程，并成功创建 BTC/USDT 策略。
5. 策略支持仅信号模式，避免演示时误触实盘下单。
6. 从 AI 分析报告点击“回测”可跳转到指标 IDE，并继承 BTC/USDT 标的上下文。
7. 指标 IDE 的回测功能可运行并输出结果表、收益指标和交易明细。

同时发现：

1. AI 分析结论和交易标签之间存在激进程度不一致。
2. 生成策略与回测之间尚未形成真正闭环。
3. 回测默认策略不一定对应 AI 分析策略。
4. AI 决策过滤器模型来源和决策过程不够透明。
5. 交易对选择、敏感信息遮罩、风险闸门等方面仍有优化空间。

## 11. 推荐下一步开发优先级

| 优先级 | 建议 |
|---|---|
| P0 | 明确回测入口使用的策略来源，避免用户误解 |
| P0 | 敏感信息默认遮罩 |
| P1 | 生成策略时自动预填 AI 分析标的和方向 |
| P1 | AI 决策过滤器显示模型和记录判断日志 |
| P1 | 风险回报比不足时降级交易建议 |
| P2 | AI 分析报告输出稳定 JSON schema |
| P2 | 支持 AI 分析 → 临时策略 → 自动回测闭环 |
| P3 | AI Filter 参与回测模拟与对比 |

---

记录日期：2026-05-15  
记录目的：作为 QuantDinger 功能使用日志和二次开发参考。