Skip to content

CLI_GUIDE.md

Latest commit

 

History

History
197 lines (148 loc) · 4.93 KB

CLI_GUIDE.md

File metadata and controls

197 lines (148 loc) · 4.93 KB

CLI 命令行使用指南

本文档介绍 A股赛博操盘手 的命令行工具使用方法。

前置要求

  • Python 3.11+
  • ClickHouse 服务器
  • TuShare API Token
  • uv 包管理工具

安装步骤

  1. 克隆仓库
git clone <repository-url>
cd stock_datasource
  1. 安装依赖
uv sync
  1. 配置环境
cp .env.example .env
# 编辑 .env 文件，填入 TuShare Token 和 ClickHouse 配置
  1. 初始化数据库
uv run cli.py init-db

常用命令

数据库初始化

# 初始化所有表
uv run cli.py init-db

# 初始化特定表
uv run cli.py init-db --table ods_daily

插件管理

# 发现所有插件
uv run python -m stock_datasource.cli_plugins discover

# 列出所有插件
uv run python -m stock_datasource.cli_plugins list

# 查看插件详情
uv run python -m stock_datasource.cli_plugins info tushare_daily

# 测试插件数据提取
uv run python -m stock_datasource.cli_plugins test --date 20251024

数据采集

# 获取特定日期数据
uv run cli.py ingest-daily --date 20251024

# 批量回填数据
uv run cli.py backfill --start-date 20250101 --end-date 20251024

# 加载股票基础信息
uv run cli.py load-stock-basic

# 加载交易日历
uv run cli.py load-trade-calendar --start-date 20250101 --end-date 20251231

数据质量

# 查看摄入状态
uv run cli.py status --date 20251024

# 运行质量检查
uv run cli.py quality-check --date 20251024

# 生成日报告
uv run cli.py report --date 20251024

# 检查数据覆盖率
uv run cli.py coverage --table ods_daily

数据优化

# 优化表去除重复数据
uv run python -c "from src.stock_datasource.models.database import db_client; db_client.execute('OPTIMIZE TABLE ods_daily FINAL')"

# 检查重复数据情况
uv run python -c "
from src.stock_datasource.models.database import db_client
total = db_client.execute('SELECT COUNT(*) FROM ods_daily')[0][0]
unique = db_client.execute('SELECT COUNT(DISTINCT (ts_code, trade_date)) FROM ods_daily')[0][0]
print(f'总记录: {total:,}, 唯一: {unique:,}, 重复: {total-unique:,}')
"

# 使用专用优化脚本
uv run python scripts/optimize_tables.py --check
uv run python scripts/optimize_tables.py --all

环境变量

变量 说明 默认值
TUSHARE_TOKEN TuShare API Token 必需
CLICKHOUSE_HOST ClickHouse 服务器地址 localhost
CLICKHOUSE_PORT ClickHouse 服务器端口 9000
CLICKHOUSE_DATABASE ClickHouse 数据库名 stock_datasource
LOG_LEVEL 日志级别 INFO
OPENAI_API_KEY OpenAI API Key（AI 功能必需） -
OPENAI_BASE_URL OpenAI API 地址 https://api.openai.com/v1
OPENAI_MODEL 使用的模型 gpt-4

7 个现成插件

插件 表名 说明 参数
tushare_daily ods_daily 日线数据 trade_date
tushare_adj_factor ods_adj_factor 复权因子 trade_date
tushare_daily_basic ods_daily_basic 日线基础指标 trade_date
tushare_stock_basic ods_stock_basic 股票基础信息 无
tushare_stk_limit ods_stk_limit 涨跌停数据 trade_date
tushare_suspend_d ods_suspend_d 停复牌数据 trade_date
tushare_trade_calendar ods_trade_calendar 交易日历 start_date, end_date

重复数据处理

由于使用 ClickHouse 的 ReplacingMergeTree 引擎，系统采用延迟去重机制：

立即去重

# 手动优化单个表
uv run python -c "
from src.stock_datasource.models.database import db_client
db_client.execute('OPTIMIZE TABLE ods_daily FINAL')
print('✅ ods_daily 表优化完成')
"

# 批量优化所有 ODS 表
uv run python -c "
from src.stock_datasource.models.database import db_client
tables = ['ods_daily', 'ods_adj_factor', 'ods_daily_basic', 
          'ods_stk_limit', 'ods_suspend_d', 'ods_trade_calendar']
for table in tables:
    db_client.execute(f'OPTIMIZE TABLE {table} FINAL')
    print(f'✅ {table} 优化完成')
"

查询时确保无重复

-- 查询时自动去重
SELECT * FROM ods_daily FINAL 
WHERE trade_date = '20251025'
AND ts_code = '000001.SZ'

-- 聚合查询（推荐，性能更好）
SELECT ts_code, trade_date, 
       argMax(close, version) as close,
       argMax(vol, version) as vol
FROM ods_daily 
WHERE trade_date = '20251025'
GROUP BY ts_code, trade_date

常见问题

Q: 插件未被发现

A: 检查 __init__.py 是否导出了插件类

Q: Schema 加载失败

A: 检查 schema.json 是否存在且格式正确

Q: 参数定义为空

A: 检查 config.json 中是否有 parameters_schema 字段

Q: 导入错误

A: 确保使用 uv run 而不是直接 python

Q: 数据库中存在重复数据

A: 这是 ReplacingMergeTree 引擎的正常行为，使用 OPTIMIZE TABLE ... FINAL 命令去重