mirror of
https://github.com/laoxong/nofx.git
synced 2026-06-04 09:58:22 +08:00
lky-spec
3ca95b294d
* feat: integrate NOFXi agent into dev * Enhance NOFXi agent workflow and diagnostics
204 lines
5.6 KiB
Markdown
204 lines
5.6 KiB
Markdown
# 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>`
|