天枢 (Tiānshū) 是北斗七星之首，自古便是定位和导航的核心。这寓意着本项目是整个量化交易体系的核心枢纽 (Central Hub)，为所有策略提供稳定、可靠、可信的方向指引和数据基石。

Argus 在希腊神话中是拥有百眼的巨人，一个完美的守望者。这完美契合了项目全链路、多维度、自动化的质量监控体系 (Observability)，象征着系统拥有无数双眼睛，时刻守护着数据质量。

本项目旨在构建一个工业级、全自动、高韧性的A股数据管道系统，通过智能融合多源数据（miniQMT, Tushare Pro），为 NautilusTrader 量化交易系统提供可信赖的“黄金标准”数据。

• 事件驱动与彻底解耦 (Event-Driven & Decoupled): 以 Apache Kafka 为中央神经系统，实现极致的系统弹性和可扩展性。
• 事务性数据湖仓 (Transactional Data Lakehouse): 采用 Delta Lake 存储Gold层数据，提供ACID事务、时间旅行和Schema强制，从根本上保障数据一致性。
• 智能多源融合 (Intelligent Multi-Source Fusion): 遵循明确的治理规则，以miniQMT为主、Tushare为辅，智能融合行情、财务、公司行动等多维度数据，并提供完整的数据血缘。
• 内建质量保障 (Quality Built-in): 贯穿全链路的五级质量监控架构和智能质量决策引擎 (QDE)，由 Great Expectations 提供超过128条自动化规则支撑。
• 全链路可观测性 (Comprehensive Observability): 基于 Prometheus, Grafana, ELK 技术栈，提供覆盖数据源、管道、存储到应用的全方位监控与告警。
• 自动化与高韧性 (Automation & High-Resilience): 由 Airflow 实现自动化调度，具备Tushare配额熔断、自动故障转移等工业级韧性。

本系统采用分层解耦的现代化数据平台架构，分为数据平面、控制平面和质量与监控平面，确保了系统的高内聚、低耦合和清晰的职责划分。

graph TD
    subgraph "Windows 环境 (Windows Environment)"
        direction LR
        WIN_QMT["miniQMT Client"]
        WIN_AGENT["Windows QMT Data Agent - Python HTTP Service"]
        WIN_QMT --> WIN_AGENT
    end

    subgraph "Docker 环境 (Docker Environment - Project Argus Core)"
        subgraph "数据平面 (Data Plane)"
            subgraph "A. 数据源 (Sources)"
                DS_AGENT["QMT Data via Agent"]
                style DS_AGENT fill:#D2B4DE,stroke:#8E44AD
                DS2["Tushare Pro"]
            end

            subgraph "B. 统一接入与采集 (Ingestion)"
                DC["智能数据采集器 (qmt_collector.py calls Agent)"]
            end

            subgraph "C. 消息总线 (Message Bus)"
                KAFKA["Kafka - raw_data_topic"]
            end

            subgraph "D. 数据处理引擎 (Processing Engine)"
                BP["Bronze Processor - 格式化/标准化"]
                SP["Silver Processor - 融合/清洗/填补"]
                GP["Gold Publisher - 发布到 Delta Lake"]
            end

            subgraph "E. 事务性数据湖仓 (Transactional Lakehouse)"
                DL["Delta Lake - Gold Layer"]
                PART["Partitioned Storage - /gold/date=.../symbol=..."]
            end

            subgraph "F. 数据消费 (Consumption)"
                NT["NautilusTrader"]
            end
        end

        subgraph "控制平面 (Control Plane)"
            AIRFLOW["Apache Airflow"]
            CONFIG["配置中心"]
            ALERT["Alertmanager"]
            USER["Data Analyst / Operator"]
        end

        subgraph "质量与监控平面 (Quality & Observability Plane)"
            QDE["质量决策引擎"]
            GE["Great Expectations"]
            PROM["Prometheus"]
            GRA["Grafana"]
            ELK["ELK Stack"]
        end
    end

    %% Data Flow
    WIN_AGENT -->|HTTP Request/Response| DC
    DS2 --> DC
    DC --> KAFKA
    KAFKA --> BP
    BP --> SP
    SP --> QDE
    QDE -->|Pass| GP
    GP --> DL
    DL --> PART
    PART --> NT

    %% Control Flow
    AIRFLOW -->|调度| DC
    AIRFLOW -->|调度| BP
    CONFIG -->|提供规则| DC
    CONFIG -->|提供规则| SP
    CONFIG -->|提供规则| QDE
    CONFIG -->|Agent URL| DC
    QDE -->|Fail| ALERT
    ALERT -->|告警| USER

    %% Quality & Observability Flow
    SP -->|待验数据| GE
    GE -->|验证结果| QDE
    DC --> PROM
    DC --> ELK
    BP --> PROM
    BP --> ELK
    SP --> PROM
    SP --> ELK
    GE --> PROM
    GE --> ELK
    WIN_AGENT -->|Logs & Metrics| ELK
    WIN_AGENT -->|Logs & Metrics| PROM
    PROM --> GRA
    ELK --> GRA
    GRA -->|看板| USER

    %% Styling
    class WIN_QMT,WIN_AGENT fill:#EAEFF3,stroke:#5D6D7E

我们坚信数据质量是量化交易的生命线。Project Argus 将“质量内建”原则贯穿于数据生命周期的每个环节。

1. **数据源优先级原则 (Source Priority):miniQMT 为行情主源，Tushare 为补充和备份源。
2. 黄金标准层原则 (Golden Record): 只有 Gold 层数据对外发布，严禁消费中间层。
3. 完整数据血缘原则 (Data Lineage): 所有融合字段必须记录其来源 (_source)。
4. 质量内建原则 (Quality Built-in): 每个字段都关联明确的质量校验规则。
5. Schema不可变与演进原则 (Schema Immutability): Schema变更受严格的版本控制。

系统所有服务均被容器化，并通过docker-compose.yml进行编排，实现了开发的便捷性和部署的一致性。

graph LR
    subgraph Docker Host
        subgraph "Docker Compose Services"
            A["Airflow<br>(Scheduler, Webserver)"]
            C["Data Collector<br>(as Airflow Task)"]
            P["Data Processor<br>(as Airflow Task)"]
            K[Kafka & Zookeeper]
            R["Redis<br>(Quota Manager)"]
            M["Monitoring Stack<br>(Prometheus, Grafana)"]
            S["Storage<br>(MinIO for Delta Lake)"]
        end
    end
    
    A -- "Schedules" --> C
    A -- "Schedules" --> P
    C -- "Raw Data" --> K
    K -- "Raw Data" --> P
    P -- "Fused Data" --> S
    C & P -- "Use" --> R
    subgraph Internet
        DS1[miniQMT]
        DS2[Tushare Pro]
    end
    C --> DS1 & DS2

• Python 3.12 (for Project Argus core)
• uv (Python package manager)
• Docker
• Docker Compose
• Windows QMT Data Agent 已成功部署和运行:
  • Project Argus 通过HTTP(S)依赖一个独立部署的 Windows QMT Data Agent 服务来接入 miniQMT 数据。
  • 请参照 project-argus-qmt-agent 项目的文档进行安装、配置和启动：https://github.com/jiaenyue/project-argus-qmt-agent
  • 确保该Agent服务正在运行，并且Project Argus环境可以网络访问到它。
• (可选，未来AI集成) 如果您计划探索 xtquantai 的MCP特性，可能需要Node.js 和 npx (请参考project-argus-qmt-agent或xtquantai的文档)。

Windows QMT Data Agent 是一个独立的项目，负责提供对 Windows 端 miniQMT 服务的HTTP访问接口。Project Argus 的数据采集器 (qmt_collector.py) 将通过网络调用此代理服务。

请访问并遵循其专用仓库中的说明进行设置和启动： ➡️ https://github.com/jiaenyue/project-argus-qmt-agent

该仓库的 README.md 包含了详细的安装、配置（包括通过环境变量 QMT_DATA_AGENT_PORT 设置端口）、运行说明以及如何将其注册为Windows服务以实现持久化运行。

Project Argus 与 Agent 的交互:

• Project Argus 的 qmt_collector.py 通过配置的环境变量 QMT_DATA_AGENT_HOST 和 QMT_DATA_AGENT_PORT 来定位并连接到已运行的 Windows QMT Data Agent 实例。
• Windows QMT Data Agent 项目本身基于 xtquantai，也保留了其作为MCP服务器的潜力，可供未来AI集成探索。

如果您希望在本地（非 Dockerized）环境中运行或开发 Project Argus 核心组件（例如，测试qmt_collector.py与已运行的Windows QMT Data Agent的通信），可以按以下步骤操作：

1. 克隆仓库

   git clone https://github.com/your-org/project-argus.git
   cd project-argus

2. 安装 uv 如果尚未安装 uv, 请参照其官方文档进行安装。例如：

   # Piped install (macOS, Linux)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   # Or using pip (if you have a global Python with pip)
   # pip install uv

3. 创建并激活虚拟环境 (使用 uv)

   uv venv .venv  # 创建虚拟环境到 .venv 目录
   source .venv/bin/activate  # 激活 (Linux/macOS)
   # .venv\Scripts\activate  # 激活 (Windows)

   项目使用 Python 3.12。请确保您的 uv 配置或系统 Python 指向 3.12 版本，或者在创建虚拟环境时指定：

   uv venv .venv -p 3.12

4. 安装依赖 (使用 uv)

   uv pip install -r requirements.txt

   或者，如果您的 uv 版本支持直接从 pyproject.toml 安装：

   # uv pip install .  # This would install the project and its dependencies

   注意: xtquant 库是 miniQMT 的一部分，通常需要从 QMT 客户端的安装目录中获取或通过特定方式安装到您的 Python 环境中。它不会通过 requirements.txt 从 PyPI 安装。确保 xtquant 在您的 Python 环境中可用才能运行数据采集脚本。

5. 配置环境变量 复制示例环境文件，并填入您的 API Token 等敏感信息。

   cp .env.example .env
   # 编辑 .env 文件，例如:
   # TUSHARE_TOKEN=your_tushare_pro_api_token
   # QMT_CLIENT_PATH=/path/to/your/qmt/installation (if needed by scripts)

6. 运行特定脚本 (示例) 此时，您可以直接运行项目中的 Python 脚本，例如测试数据采集器：

   python src/collectors/qmt_collector.py

对于完整的系统部署（包括 Airflow, Kafka, MinIO 等），请遵循以下 Docker Compose 流程：

1. 克隆仓库 (如果尚未操作)

   git clone https://github.com/your-org/project-argus.git
   cd project-argus

2. 配置环境变量 (同上, 主要是 .env 文件中的 TUSHARE_TOKEN)

   cp .env.example .env
   # 编辑 .env 文件

   Docker Compose 构建过程将使用 requirements.txt (通过 uv 安装) 和 Python 3.12 基础镜像。

3. 启动系统 使用 Docker Compose 一键启动所有服务。

   docker-compose up -d

4. 访问服务

   • Airflow UI: http://localhost:8080 (用于查看和管理DAGs)
   • Grafana: http://localhost:3000 (用于查看数据质量和系统监控看板)
   • MinIO Console: http://localhost:9001 (用于浏览Delta Lake数据)

本项目采用全面的文档驱动开发模式。所有核心设计、规范和计划都有详细的文档支持，它们是理解本项目细节的单一可信源 (Single Source of Truth)。

我们欢迎任何形式的贡献！如果您想为 Project Argus 做出贡献，请遵循以下步骤：

1. Fork 本仓库。
2. 创建一个新的功能分支 (git checkout -b feature/your-feature-name)。
3. 提交您的更改 (git commit -am 'Add some feature')。
4. 将分支推送到您的Fork (git push origin feature/your-feature-name)。
5. 创建一个新的 Pull Request。

请确保您的代码遵循现有的编码风格，并通过所有测试。

本项目采用 MIT License 授权。