# NOFXi 诊断与配置 Skills（第一批）

这份文档用于沉淀交易智能助手的第一批高频诊断与配置 skill。

目标不是让模型“更会想”，而是让它面对常见问题时，优先走稳定、可复用的排查路径。

## 设计原则

- 优先按 skill 回答，不要对高频问题重复自由规划
- 先归类问题，再给出原因、检查项和修复建议
- 能通过工具验证当前状态时，先查再下结论
- 敏感信息只指导填写，不完整回显
- 对结论不确定时，要明确标注为“更可能”或“优先怀疑”

## skill_model_api_setup

### 适用场景

- 用户问某个大模型的 API key 去哪里申请
- 用户问 base URL 怎么填
- 用户问 model name 怎么填
- 用户问 OpenAI / Claude / Gemini / DeepSeek / Qwen / Kimi / Grok / MiniMax 怎么接入

### 处理策略

1. 先确认用户要配置哪个 provider
2. 告诉用户需要准备的最少字段：
   - provider
   - API key
   - custom_api_url
   - custom_model_name
3. 如果系统已有默认地址和默认模型名，优先给推荐值
4. 回答按步骤组织，不要泛泛解释概念

### 已知实现事实

- 系统内置 provider 默认运行配置，见 `agent.resolveModelRuntimeConfig(...)`
- 常见 provider 已有默认 URL 和默认 model name

## skill_model_config_diagnosis

### 适用场景

- 模型保存成功但 agent 仍然不可用
- 提示 AI unavailable
- 提示模型没启用
- 提示 custom_api_url 不合法
- 配置后 trader 不生效

### 优先排查

1. 是否存在已启用模型
2. API key 是否为空
3. custom_api_url 是否为合法 HTTPS 地址
4. custom_model_name 是否为空或不匹配
5. 当前 trader 是否绑定了这个模型
6. 更新模型后是否已触发 trader reload

### 已知实现事实

- 非 HTTPS 的 `custom_api_url` 会被后端拒绝，见 `api/handler_ai_model.go`
- 已启用模型如果缺少 API Key 或 URL，会导致 agent 无法就绪，见 `agent.ensureAIClientForStoreUser(...)`
- 更新模型配置后，系统会尝试移除并重载相关 trader，使新配置立即生效

### 输出格式

- 现象
- 更可能原因
- 先检查什么
- 下一步怎么修复

## skill_exchange_api_setup

### 适用场景

- 用户要新建交易所 API
- 用户不知道交易所需要哪些权限
- 用户问 API key / secret / passphrase 分别填什么

### 通用处理策略

1. 先确认交易所类型
2. 告知必须权限与禁止权限
3. 告知是否需要额外字段
4. 强调 IP 白名单与权限配置
5. 引导用户回到系统内完成绑定

### 特殊规则

- OKX 除 API Key 和 Secret 外，还需要 passphrase
- Bybit 永续/合约交易需要合约权限
- 不建议开启提现权限

### 参考文档

- `docs/getting-started/okx-api.md`
- `docs/getting-started/bybit-api.md`

## skill_exchange_api_diagnosis

### 适用场景

- `invalid signature`
- `timestamp` 错误
- `IP not allowed`
- `permission denied`
- 交易所连接不上

### 优先排查

1. 系统时间是否同步
2. API Key / Secret 是否正确
3. 是否遗漏额外字段，如 OKX passphrase
4. IP 白名单是否包含当前服务器
5. 是否启用了交易或合约权限
6. 密钥是否过期或已重建

### 已知实现事实

- 时间不同步是 `invalid signature` / `timestamp` 的高频根因，见 `docs/guides/TROUBLESHOOTING.zh-CN.md`
- OKX 的 passphrase 缺失会导致签名相关问题，见 `docs/getting-started/okx-api.md`

### 输出格式

- 报错现象
- 最常见根因
- 优先检查顺序
- 修复步骤

## skill_trader_start_diagnosis

### 适用场景

- trader 启动不了
- trader 启动了但没开始交易
- 页面显示已启动但一直没有动作
- 用户怀疑 strategy / model / exchange 绑定有问题

### 优先排查

1. 是否有已启用的模型配置
2. 是否有已启用的交易所配置
3. trader 是否绑定了 exchange_id / strategy_id / ai_model_id
4. 交易所余额和权限是否满足下单条件
5. AI 最近的决策到底是 wait、hold 还是下单失败

### 回答原则

- 要区分“没启动”“启动了但 AI 选择不交易”“尝试下单但失败”这三类
- 不要把“没开仓”直接等同于“系统故障”

## skill_order_execution_diagnosis

### 适用场景

- 下单失败
- 只开空不开户 / 只开单边
- 杠杆报错
- position side mismatch

### 优先排查

1. 账户模式是否匹配，例如 Binance 是否为 Hedge Mode
2. 是否为子账户杠杆限制
3. 合约权限是否开启
4. 余额、保证金、可交易 symbol 是否满足条件

### 已知实现事实

- Binance 在 One-way Mode 下，可能出现 `position side mismatch` 或单边行为
- 某些子账户杠杆上限较低，超过限制会直接失败
- 这些问题在 `docs/guides/TROUBLESHOOTING.md` 已有明确说明

## skill_strategy_diagnosis

### 适用场景

- 用户说策略没生效
- 用户说 prompt 预览和实际不一致
- 用户说修改策略后 trader 行为没有变化

### 优先排查

1. 当前编辑的是策略模板，还是 trader 的 custom prompt
2. 策略是否真的保存成功
3. 是否需要重新读取当前配置做对比
4. 用户说的“没生效”是指未保存、未绑定，还是运行结果与预期不一致

### 回答原则

- 先明确“对象”再排查：strategy template / trader / prompt override
- 如果能读取当前保存值，就不要凭印象判断

## 后续扩展方向

下一批可以继续补：

- `skill_balance_and_position_diagnosis`
- `skill_market_data_diagnosis`
- `skill_prompt_generation_diagnosis`
- `skill_strategy_test_run_diagnosis`
- `skill_exchange_specific_setup_<exchange>`
- `skill_model_provider_setup_<provider>`