# Orange Hitick 主观信号 Skill

## 1. 服务概览

- 当前服务编码：`subjective_signal`
- 当前模型标识：查询时按 `factorKey` 计费
- 当前对外暴露统一入口：`POST /api/v1/subjective-signal/evaluate`
- 补充元信息接口：`GET /api/v1/subjective-signal/factors`

说明：

- 当前支持的主观因子已经固定写在本文档里，调用方可以直接按因子调用
- `factors` 适合做控制台展示、参数元信息同步或调试

## 2. 当前支持的主观因子

当前线上已支持 7 个主观因子：

1. `AtmVolDivergence`
2. `SkewDivergence`
3. `OptionFlowAnomaly`
4. `ShortOption`
5. `SeatAnalysis`
6. `FuturesTermStructure`
7. `SqrtTimeRule`

### 2.1 `AtmVolDivergence`

- 中文名称：`ATM 波动率背离`
- 因子作用：识别价格与 ATM 隐波变化方向不一致，或价格变化较小但隐波显著变化的信号
- 数据来源：后台按分钟获取最新有效数据点，以该点为结束时间向前扫描 12 小时数据，并基于 30 分钟滚动窗口缓存结果
- 返回形式：返回最近一次命中的信号；可按标的列表过滤

适合场景：

- “最近哪些品种有波动率背离信号？”
- “这几个标的有没有偏看涨 / 偏看跌的背离？”
- “价格横盘但隐波上涨的品种有哪些？”

请求参数：

- `underlyings`：可选，标的代码数组，例如 `["au2607", "cu2607"]`

返回重点字段：

- `signal`：通常为 `BULLISH` 或 `BEARISH`
- `score`：信号强度分数
- `summary`：简要中文结论
- `generatedAt`：当前这条背离信号的生成时间，整理结果时必须明确提示，不能省略
- `details.underlying`：标的代码
- `details.instrument_name`：基础数据 catalog 返回的标的名称（已清理首尾空白）
- `details.expire`：到期日
- `details.multiplier`：合约乘数
- `details.windowMinutes`：窗口分钟数
- `details.priceChgPct30m`：30 分钟价格变化百分比
- `details.div30m`：30 分钟 ATM 隐波变化值
- `details.strength`：强 / 中 等标签

### 2.2 `SkewDivergence`

- 中文名称：`偏度背离`
- 因子作用：比较当日与上一收盘同一行权价上的 20D Call/Put 理论波动率变化，识别偏多或偏空的偏度结构背离
- 数据来源：优先实时 VolData，失败或无效时回退最新快照；上一收盘使用同标的、同到期日、同乘数的 15:00 快照
- 返回形式：仅返回方向、强度、定性变化标签、数据时点和插值质量，不返回具体价格/波动率变化值、行权价或阈值

请求参数：

- `underlyings`：可选，标的代码数组；为空表示不过滤

返回重点字段：

- `details.targetDelta`：固定为 `20D`
- `details.dominantWing`：`CALL` 或 `PUT`
- `details.currentDataMode`：`REALTIME` 或 `SNAPSHOT`
- `details.comparisonBasis`：固定为 `PREVIOUS_CLOSE_SAME_STRIKE`
- `details.currentDataTime` / `previousCloseTime`：两侧数据时点
- `details.interpolationQuality`：`EXACT`、`INTERPOLATED` 或 `EXTRAPOLATED`

### 2.3 `OptionFlowAnomaly`

- 中文名称：`期权持仓异动`
- 返回形式：每条结果对应一个品种，提供异动标签、分数、Call/Put 观测值、数量统计和最多 3 个代表合约，不推断多空方向

请求参数：

- `underlyings`：可选，品种或完整期货合约代码数组，例如 `["AU", "CU", "IM2608"]`；完整合约按品种前缀匹配

返回重点字段：

- `signal`：固定为 `ANOMALY`
- `score`：信号分数
- `details.productCode` / `productName`：品种代码及名称
- `details.callOiChangeValue` / `putOiChangeValue`：Call、Put 两侧持仓变化金额观测值
- `details.triggeredCount` / `sampledContractCount`：触发数量与参与结果生成的合约数量
- `details.topContracts`：最多 3 个代表合约及其期权类型、变化金额和变化方向
- `details.sourceFetchedAt`：结果采集时间，不代表交易所行情时间
- `details.sourceTimestampAvailable`：是否具有可用于解释的原始行情时间

该结果属于品种级证据，不代表某一个精确期货合约。

### 2.4 `ShortOption`

- 中文名称：`期权卖方`
- 因子作用：围绕目标胜率，筛选虚值 call / put 中卖方年化回报率较高的机会
- 数据来源：遍历可用分组，结合期权链、delta、卖方保证金、剩余天数等字段计算
- 返回形式：按年化回报率排序，默认返回前 20 条机会

适合场景：

- “找一些 70% 胜率附近的卖方机会”
- “哪些合约当前卖方静态回报率更高？”
- “给我一组虚值保护空间较好的卖方候选”

请求参数：

- `winRate`：可选，范围 `(0,1)`，默认 `0.7`

返回重点字段：

- `signal`：固定返回 `ShortOption`
- `score`：按年化回报率换算的评分
- `summary`：简要描述胜率和年化回报率
- `details.underlying`：标的代码
- `details.optionType`：`CALL` 或 `PUT`
- `details.symbol`：期权合约代码
- `details.expire`：到期日
- `details.multiplier`：合约乘数
- `details.strike`：行权价
- `details.underlyingPrice`：标的价格
- `details.bid` / `details.ask`：盘口价格
- `details.winRate`：参考胜率
- `details.otmPct`：虚值保护空间百分比
- `details.shortMargin`：参考保证金
- `details.remainingDays`：剩余自然日
- `details.returnRate`：静态回报率
- `details.annualizedReturnRate`：参考年化回报率

### 2.5 `SeatAnalysis`

- 中文名称：`席位分析`
- 因子作用：抓取最新席位分析图片并解析表格，返回当前缓存中的全部席位方向结果
- 数据来源：后台定时从上游接口拉取图片 URL，再通过视觉模型提取表格
- 返回形式：返回当前缓存中的全量结果，不支持过滤参数

适合场景：

- “最新席位分析怎么看？”
- “当前哪些品种席位偏多 / 偏空？”
- “把最新席位分析结果全拉出来”

基本原则：

- 一般以 `机构` 方向作为最终方向
- `家人` 指散户，经常逆市扛单，回本就跑，更适合作为反向参考
- `杭州帮` 指游资，期货大佬集中地，更适合作为短线资金风格参考
- `外资`、`杭州帮`、`家人` 都是辅助维度，最终结论优先看机构变化

请求参数：

- 无

返回重点字段：

- `signal`：`BULLISH` / `BEARISH` / `NEUTRAL`
- `score`：当前固定为 `70.0`
- `summary`：席位分析中文摘要
- `details.productName`：表格中的品种名称
- `details.matchedKey`：归一化匹配键
- `details.holdInstitutionChange`：机构持仓变化，解释方向时优先看这个字段
- `details.holdForeignChange`：外资变化
- `details.holdHangzhouChange`：杭州帮变化
- `details.holdFamilyChange`：家人变化
- `details.row`：原始表格行
- `details.parsedAt`：表格解析时间

### 2.6 `FuturesTermStructure`

- 中文名称：`期货期限结构`
- 因子作用：按品种判断当前期货期限结构
- 返回形式：每条结果对应一个品种，返回结构分类和品种名称

请求参数：

- `underlyings`：可选，品种或完整期货合约代码数组，例如 `["AU", "CU", "IM2608"]`；完整合约按品种前缀匹配

返回重点字段：

- `signal`：`backwardation`、`contango` 或 `unknow`
- 该因子不返回 `score`
- `details.productCode` / `productName`：品种代码及名称
- `details.subjectLevel`：固定为 `PRODUCT`
- `summary`：当前期限结构的简要中文结论
- `generatedAt`：结果生成时间

### 2.7 `SqrtTimeRule`

- 因子名称：`根号 T 原则`
- 对外结论：仅说明该因子是否命中
- 披露限制：不得公开计算方法、输入数据、阈值、比例、分数、明细字段或异常子类型

## 3. HTTP 接口

### 3.1 获取当前已注册因子元信息

```http
GET /api/v1/subjective-signal/factors
```

请求头：

- `X-API-Token: <your-token>`

用途：

- 返回因子 descriptor 列表
- 适合做管理后台展示和自动化同步
- 也适合在需要参数元信息时辅助调用

### 3.2 执行主观信号计算

```http
POST /api/v1/subjective-signal/evaluate
```

请求头：

- `X-API-Token: <your-token>`

请求体通用结构：

```json
{
  "factorKey": "AtmVolDivergence | SkewDivergence | FuturesTermStructure | SqrtTimeRule | OptionFlowAnomaly | ShortOption | SeatAnalysis",
  "params": {}
}
```

## 4. 直接调用示例

### 4.1 `AtmVolDivergence` 请求示例

```json
{
  "factorKey": "AtmVolDivergence",
  "params": {
    "underlyings": ["au2607", "cu2607"]
  }
}
```

### 4.2 `SkewDivergence` 请求示例

```json
{
  "factorKey": "SkewDivergence",
  "params": {
    "underlyings": ["au2607", "cu2607"]
  }
}
```

### 4.3 `OptionFlowAnomaly` 请求示例

```json
{
  "factorKey": "OptionFlowAnomaly",
  "params": {
    "underlyings": ["AU", "CU", "IM2608"]
  }
}
```

### 4.4 `ShortOption` 请求示例

```json
{
  "factorKey": "ShortOption",
  "params": {
    "winRate": 0.7
  }
}
```

### 4.5 `SeatAnalysis` 请求示例

```json
{
  "factorKey": "SeatAnalysis",
  "params": {}
}
```

### 4.6 `FuturesTermStructure` 请求示例

```json
{
  "factorKey": "FuturesTermStructure",
  "params": {
    "underlyings": ["AU", "CU", "IM2608"]
  }
}
```

## 5. 返回示例

### 5.1 `AtmVolDivergence` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "AtmVolDivergence",
      "signal": "BULLISH",
      "score": 70.0,
      "summary": "波动率背离看涨（中）：价格横盘，隐波上涨",
      "details": {
        "underlying": "au2607",
        "expire": "20260624",
        "multiplier": "1000",
        "windowMinutes": 30,
        "priceChgPct30m": 0.02,
        "div30m": 0.045,
        "strength": "中"
      },
      "generatedAt": "2026-06-11T10:30:00+08:00"
    }
  ]
}
```

### 5.2 `SkewDivergence` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "SkewDivergence",
      "signal": "BULLISH",
      "score": 85.0,
      "summary": "偏度背离偏多（强）：价格横盘，Call端升波显著强于Put端",
      "details": {
        "underlying": "au2608",
        "instrument_name": "沪金",
        "expire": "20260727",
        "multiplier": "1000",
        "factorName": "偏度背离",
        "targetDelta": "20D",
        "priceMoveTag": "横盘",
        "callVolMoveTag": "上升",
        "putVolMoveTag": "基本稳定",
        "dominantWing": "CALL",
        "strength": "强",
        "comparisonBasis": "PREVIOUS_CLOSE_SAME_STRIKE",
        "currentDataMode": "SNAPSHOT",
        "currentDataTime": "2026-07-17T15:00:00+08:00",
        "previousCloseTime": "2026-07-16T15:00:00+08:00",
        "interpolationQuality": "INTERPOLATED"
      },
      "generatedAt": "2026-07-17T15:00:00+08:00"
    }
  ]
}
```

### 5.3 `OptionFlowAnomaly` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "OptionFlowAnomaly",
      "signal": "ANOMALY",
      "score": 80.0,
      "summary": "期权持仓异动：Call合计3500.00万，Put合计-1800.00万，触发3个大额持仓变化合约",
      "details": {
        "underlying": "AU",
        "productCode": "AU",
        "productName": "黄金",
        "subjectLevel": "PRODUCT",
        "callOiChangeValue": 35000000,
        "putOiChangeValue": -18000000,
        "triggeredCount": 3,
        "sampledContractCount": 5,
        "sourceFetchedAt": "2026-07-20T13:00:00+08:00",
        "sourceTimestampAvailable": false,
        "topContracts": [
          {
            "contractCode": "AU2608-C-800",
            "optionType": "CALL",
            "oiChangeVal": 21000000,
            "changeDirection": "INCREASE"
          }
        ]
      },
      "generatedAt": "2026-07-20T13:00:00+08:00"
    }
  ]
}
```

### 5.4 `ShortOption` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "ShortOption",
      "signal": "ShortOption",
      "score": 51.1,
      "summary": "au2607 PUT 胜率 0.720 年化回报率 51.10%",
      "details": {
        "underlying": "au2607",
        "optionType": "PUT",
        "symbol": "au2607P92",
        "expire": "20260624",
        "multiplier": "1000",
        "winRate": 0.72,
        "otmPct": 8.0,
        "annualizedReturnRate": 0.511
      },
      "generatedAt": "2026-06-12T10:00:00+08:00"
    }
  ]
}
```

### 5.5 `SeatAnalysis` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "SeatAnalysis",
      "signal": "BULLISH",
      "score": 70.0,
      "summary": "席位分析看多：杭州帮减空，外资加多，机构加多，家人-",
      "details": {
        "productName": "沪金",
        "matchedKey": "沪金",
        "holdHangzhouChange": "减空",
        "holdForeignChange": "加多",
        "holdInstitutionChange": "加多",
        "holdFamilyChange": "-",
        "row": {
          "品种": "沪金",
          "持仓变化-机构": "加多"
        },
        "parsedAt": "2026-06-17T10:30:00+08:00"
      },
      "generatedAt": "2026-06-17T10:30:00+08:00"
    }
  ]
}
```

### 5.6 `FuturesTermStructure` 返回示例

```json
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "factorKey": "FuturesTermStructure",
      "signal": "contango",
      "summary": "黄金 当前为 contango 结构",
      "details": {
        "productCode": "AU",
        "productName": "黄金",
        "subjectLevel": "PRODUCT"
      },
      "generatedAt": "2026-08-15T10:30:00+08:00"
    }
  ]
}
```

### 5.7 `SqrtTimeRule` 返回示例

```json
{
  "factorName": "根号 T 原则",
  "conclusion": "命中"
}
```

## 6. Agent 调用建议

如果问题可以直接映射到已知因子，建议直接调用：

- 问“有没有背离信号 / 隐波和价格背离 / 偏看涨偏看跌信号”：
  - 直接用 `AtmVolDivergence`
- 问“偏度背离 / Call 与 Put 两翼谁更强 / 相对上一收盘的偏度变化”：
  - 直接用 `SkewDivergence`
  - 解释时说明 `currentDataMode`、两个数据时间和 `interpolationQuality`，不要推测未返回的具体变化值
- 问“根号 T 原则是否命中”：
  - 直接用 `SqrtTimeRule`
  - 对外只回答因子名称和命中结论，不展示或解释其他返回字段
- 问“期权大额增减仓 / 哪些品种出现持仓异动 / Call 与 Put 持仓变化”：
  - 直接用 `OptionFlowAnomaly`
  - `sourceFetchedAt` 只代表结果采集时间；需要继续查询行情时先将品种代码解析为标准合约
- 问“找卖方机会 / 找 70% 胜率附近的合约 / 哪些卖方年化高”：
  - 直接用 `ShortOption`
- 问“最新席位分析 / 当前席位偏多偏空 / 拉全部席位数据”：
  - 直接用 `SeatAnalysis`
  - 解释时优先按 `holdInstitutionChange` 给结论
  - `家人` 作为散户信号通常偏反向观察
  - `杭州帮` 作为游资信号通常偏短线风格观察
- 问“当前是 backwardation 还是 contango / 期货期限结构是什么”：
  - 直接用 `FuturesTermStructure`
  - `unknow` 表示当前无法明确归类，不应推断为其中任一种结构
- 问“支持哪些主观因子”：
  - 直接回答当前支持 `AtmVolDivergence`、`SkewDivergence`、`FuturesTermStructure`、`SqrtTimeRule`、`OptionFlowAnomaly`、`ShortOption` 和 `SeatAnalysis`

补充说明：

- 如果你已经明确要调用哪个因子，可以直接请求 `evaluate`
- 如果你需要展示因子目录、参数结构或状态信息，可以请求 `factors`
- 对 `AtmVolDivergence` 做结果整理时，必须显式提示每条信号的 `generatedAt`，明确告诉用户“当前背离信号时间”；信号时间非常重要，不能只给方向和强度

## 7. 风险提示

- `AtmVolDivergence` 更适合做观察和辅助判断，不应单独作为交易依据
- `SkewDivergence` 是结构性观察因子，插值或外推结果需要结合流动性和期限背景理解
- `OptionFlowAnomaly` 是品种级观察信号，不应单独作为交易决策
- `ShortOption` 属于卖方机会筛选工具，理论风险极高，不能只看胜率和年化回报率
- 使用 `ShortOption` 时应同时考虑仓位、保证金、流动性、波动率冲击和对冲方案
- `SeatAnalysis` 属于主观解释型因子，席位关系复杂，不应脱离行情背景孤立使用
- `FuturesTermStructure` 仅反映当前期限结构分类，不应脱离供需、库存、流动性和合约规则单独作为交易依据

## 8. 当前约定

- 获取因子列表不计费
- `evaluate` 成功返回后按 `factorKey` 计费
- 主观信号内部如果组合基础数据和波动率数据，不重复扣底层服务费用