> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 信号结构 | Signal Structure

> signals.json 信号结构定义（全系统核心协议）

# 📌 signals.json 信号结构定义 | Signal Structure Definition

本文档定义了 Situation Monitor 系统的核心协议：**信号结构**。这是全系统统一的数据格式，所有模块都必须遵循此规范。

<Danger>
  这是系统的**核心协议**，任何修改都需要经过团队审核和版本控制。
</Danger>

## 🎯 信号设计目标 | Signal Design Goals

信号不是行情播报，而是：

> **提醒用户「是否值得关注或行动」**

<Info>
  信号是决策前过滤系统的输出，帮助用户快速判断是否需要进一步操作。
</Info>

## 🧱 信号顶层结构 | Top-level Structure

```json theme={null}
{
  "signal_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-23T09:32:00Z",
  "signal_type": "opportunity",
  "priority": "high",
  "confidence": 0.82,
  "risk_level": "medium",
  "title": "AI 板块出现集中放量",
  "summary": "多个AI相关代币在5分钟内成交量激增，同时Twitter上相关话题提及量增长230%",
  "suggested_action": "关注板块内龙头币种，注意风险控制",
  "sources": ["market", "twitter", "gmgn"],
  "evidence": {
    "market": {
      "symbols": ["AI1", "AI2", "AI3"],
      "avg_volume_increase": "320%",
      "price_change_range": "5-12%"
    },
    "twitter": {
      "topic": "AI Meme",
      "tweet_growth": 500,
      "key_accounts": ["@influencer1", "@influencer2"]
    }
  },
  "expire_at": "2026-01-23T10:00:00Z"
}
```

## 📋 字段说明 | Field Specification

<CodeGroup>
  ```json 信号类型 (signal_type) theme={null}
  "opportunity"  // 机会信号：发现潜在机会
  "risk"        // 风险信号：检测到风险因素
  "info"        // 信息信号：一般性信息更新
  ```

  ```json 优先级 (priority) theme={null}
  "high"    // 高优先级：需要立即关注
  "medium"  // 中优先级：值得关注
  "low"     // 低优先级：仅供参考
  ```

  ```json 风险等级 (risk_level) theme={null}
  "low"     // 低风险
  "medium"  // 中等风险
  "high"    // 高风险
  ```
</CodeGroup>

### 完整字段表

| 字段                 | 类型              | 必填 | 说明                        |
| ------------------ | --------------- | -- | ------------------------- |
| `signal_id`        | UUID            | ✅  | 信号唯一标识符                   |
| `timestamp`        | ISO 8601        | ✅  | 信号生成时间（UTC）               |
| `signal_type`      | Enum            | ✅  | opportunity / risk / info |
| `priority`         | Enum            | ✅  | high / medium / low       |
| `confidence`       | Float (0.0-1.0) | ✅  | 系统判断可信度                   |
| `risk_level`       | Enum            | ✅  | low / medium / high       |
| `title`            | String          | ✅  | 推送标题（≤50 字符）              |
| `summary`          | String          | ✅  | 给用户看的解释（≤200 字符）          |
| `suggested_action` | String          | ⚠️ | 非强制建议（≤100 字符）            |
| `sources`          | Array\[String]  | ✅  | 触发的数据来源列表                 |
| `evidence`         | Object          | ✅  | 证据数据（见下方）                 |
| `expire_at`        | ISO 8601        | ✅  | 过期时间（UTC）                 |

## 🧠 evidence 结构示例 | Evidence Structure Examples

### 行情触发 | Market Trigger

```json theme={null}
{
  "market": {
    "symbols": ["AI1", "AI2", "AI3"],
    "avg_volume_increase": "320%",
    "price_change_range": "5-12%",
    "time_window": "5m"
  }
}
```

### 新币触发 | Token Trigger

```json theme={null}
{
  "gmgn": {
    "token": "ABC",
    "launch_minutes": 45,
    "holder_growth": 400,
    "whale_wallets": 3,
    "risk_flags": []
  }
}
```

### 舆情触发 | Sentiment Trigger

```json theme={null}
{
  "sentiment": {
    "topic": "AI Meme",
    "tweet_growth": 500,
    "mention_growth": "230%",
    "key_accounts": ["@user1", "@user2"],
    "sentiment_score": 0.75
  }
}
```

### 复合触发 | Composite Trigger

```json theme={null}
{
  "market": {
    "symbols": ["BTC", "ETH"],
    "volume_spike": true
  },
  "twitter": {
    "topic": "Bitcoin",
    "tweet_growth": 300
  },
  "gmgn": {
    "whale_activity": true,
    "large_transfers": 2
  }
}
```

## 🎯 信号触发原则 | Signal Triggering Rules

### 必须满足的条件

<Warning>
  **交叉验证原则**: 至少两个不同数据源交叉验证才能生成 `high` 或 `medium` 优先级信号。
</Warning>

**示例**:

* ✅ 行情 + 舆情 → 可生成 `high` 优先级信号
* ✅ 新币 + 大户行为 → 可生成 `medium` 优先级信号
* ❌ 单一数据源 → 仅可生成 `info` 级别信号

### 优先级判断逻辑

<AccordionGroup>
  <Accordion title="High Priority" icon="exclamation">
    * 至少 3 个数据源交叉验证
    * confidence ≥ 0.8
    * 涉及多个关键指标异常
  </Accordion>

  <Accordion title="Medium Priority" icon="circle-exclamation">
    * 至少 2 个数据源交叉验证
    * confidence ≥ 0.6
    * 单一关键指标显著异常
  </Accordion>

  <Accordion title="Low Priority / Info" icon="circle-info">
    * 单一数据源
    * confidence \< 0.6
    * 一般性信息更新
  </Accordion>
</AccordionGroup>

## 🚦 推送策略建议 | Push Strategy

| Priority   | 推送方式         | 频率限制      |
| ---------- | ------------ | --------- |
| **High**   | 即时推送         | 无限制       |
| **Medium** | 合并推送（5 分钟窗口） | 最多 3 条/小时 |
| **Low**    | 仅展示在面板       | 不推送       |

<Tip>
  推送层应根据用户偏好和频率限制进行智能推送，避免信息轰炸。
</Tip>

## 🔥 非目标范围 | Out of Scope

系统明确**不提供**以下功能：

<CardGroup cols={2}>
  <Card title="自动下单" icon="ban">
    不执行任何交易操作
  </Card>

  <Card title="盈利保证" icon="ban">
    不承诺任何收益
  </Card>

  <Card title="明确买卖点位" icon="ban">
    不提供具体交易建议
  </Card>
</CardGroup>

**系统定位**: 情报与决策辅助，而非交易执行。

## 📊 信号生命周期与流转 | Signal Lifecycle & Data Flow

### 全局数据流架构 | System-wide Data Flow

信号在系统中从“杂乱噪声”到“精准情报”的转化过程如下：

```mermaid theme={null}
graph TD
    subgraph "数据采集层 "
    
        
        A1["市场行情 API"] --> B1["原始信号池"]
        A2["Twitter/X 爬虫"] --> B1
        A3["GMGN 链上扫描"] --> B1
        A4["RSS 宏观新闻"] --> B1
    end

    subgraph "AI 审计与分析引擎 (Brain)"
        B1 --> C1{"证据提取与验证"}
        C1 -->|通过| C2["AI 语义评分"]
        C1 -->|通过| C3["跨源关联分析"]
        C2 & C3 --> D1["信号评分 / 评级"]
    end

    subgraph "API 网关与推送 (Delivery)"
        D1 --> E1["FastAPI Gateway"]
        E1 --> F1["Telegram 群组"]
        E1 --> F2["WhatsApp 频道"]
        E1 --> F3["Twitter 矩阵"]
        E1 --> F4["Rocket.Chat (内部通报)"]
        E1 --> F5["Dashboard 面板"]
    end

    style D1 fill:#f96,stroke:#333,stroke-width:2px
    style B1 fill:#bbf,stroke:#333,stroke-width:1px
```

### 详细生命周期 | Lifecycle Steps

<Steps>
  <Step title="1. 原始捕获 (Capture)">
    各探测器（Probe）独立工作，实时监测异常点，将发现录入原始信号池。
  </Step>

  <Step title="2. AI 审计 (Audit)">
    AI 根据 `signals_schema` 进行逻辑审计，过滤虚假信号并填充 `confidence` (可信度)。
  </Step>

  <Step title="3. 信号分发 (Distribute)">
    API 网关接收已通过审计的信号，并根据 `priority` (优先级) 寻找推送目标。
  </Step>

  <Step title="4. 终端触达 (Notify)">
    通过 **Rocket.Chat (内部)** 或 **Telegram/WhatsApp/Twitter (外部矩阵)** 即时打断用户，或在低优先级时静默更新看板。
  </Step>

  <Step title="5. 过期归档 (Archive)">
    到达 `expire_at` 后，信号从活跃池移除并存档入 PostgreSQL 以供后验。
  </Step>
</Steps>

## ✅ 信号验证规则 | Validation Rules

部署前请确认信号符合以下规则：

* [ ] `signal_id` 是有效的 UUID
* [ ] `timestamp` 和 `expire_at` 使用 ISO 8601 格式
* [ ] `confidence` 在 0.0-1.0 范围内
* [ ] `sources` 数组至少包含 1 个元素
* [ ] `evidence` 对象包含至少 1 个数据源证据
* [ ] `title` 和 `summary` 长度符合限制
* [ ] `expire_at` 晚于 `timestamp`

<Note>
  建议使用 JSON Schema 验证信号结构，确保数据一致性。
</Note>