zettaranc-skill: Instructions file for Codex

Repository Guidelines

本文件面向 AI 编程 Agent：是功能指南，不是架构全书。架构细节在 docs/，模块树在源码，这里只给入口、命令、约定、关键路径与注意事项。所有事实（版本、命令、路径）均对照仓库核实。

Project Overview

zettaranc-skill = 「Z 哥（zettaranc/万千）思维框架蒸馏包」+「A 股真实数据量化工具」双轨项目。

• 核心交付物：SKILL.md（Skill-Schema-V2 合规的角色扮演协议，被 Claude Code/Cursor 加载）——LLM 用 Z 哥角色生成点评/话术。
• 数据层：Python 包 modules/，只负责数据准备（指标、信号、回测、评分），不做投资话术——这是刻意分层，避免「AI 味」。
• 可选层：api/（FastAPI REST）+ frontend/（React 看板）+ rust/（Rust 加速计算核）。
• 当前版本：v4.13.1（pyproject.toml:7、SKILL.md frontmatter + 版本表、skill.json:3、README.md badge、docs/CHANGELOG.md 顶端、AGENTS.md 本行，共 7 处必须一致；改 pyproject.toml 的 version 时同步这 7 处，docs/INDEX.md 维护规则有同样的清单）。
• 许可证：MIT。

Architecture & Data Flow

双模式

模式	环境变量	说明
JNB / 真实数据	DATA_MODE=jnb	走数据源取真实行情，可算指标/战法
普通小万	DATA_MODE=websearch	纯 LLM 对话，无事可查外部数据

数据源优先级（modules/datasource_resolution.py 统一决议）

「环境变量 → 用哪个 provider」只有一个定义处：modules/datasource_resolution.py::resolve_provider()。读路径（CompositeDataSource）与写路径（DataSyncer）都消费它，因此两边永远选到同一个源。

hithink（HITHINK_FINANCE_API_KEY 配置时最优先，v4.2.0）
  → Indevs（INDEVS_API_KEY，v3.8.1）
  → Tushare Pro（JNB 模式配置 TUSHARE_TOKEN）
  → a-stock-data（免费源，零配置默认，v4.1.0）
  → tushare-data-bridge（HTTP 缓存代理）
  → 本地 SQLite（data/stock_data.db，离线兜底）

读路径（CompositeDataSource）在此基础上按方法链式回退；写路径（DataSyncer）取同一个首选源（单源，保留重试与退避语义）。

改优先级只改 resolve_provider() 一处。modules/data_sync/syncer.py 与 modules/datasource.py 此前各抄了一份环境变量判断且已经漂移（写路径没有 hithink 分支），zt sync 还直接钉死 tushare——在默认 websearch 模式下 tushare 无数据后端，整次同步静默同步 0 行却打印"同步完成"。v4.5.0 起统一。

约定：DB 优先读 K 线（先查 daily_kline 表，没有才调 API 并写回）。K 线读取统一走 modules/indicators/data_layer.py::get_kline_data 或 modules/strategies/core.py::get_kline_data。数据源缺 key 时绝不编造价格/信号，明确报告当前数据状态。

数据流链条

数据源 (CompositeDataSource)
  → indicators/data_layer.py      # get_kline_data + indicator_cache + analyze_stock() 30步管线 → IndicatorResult
  → strategies/__init__.py        # detect_all_strategies(ts_code, days) 折叠每日战法探测器 → 战法信号
  → screener/engine.py            # screen_stocks(criteria, ...) 并行选股
  → backtest/ + simulator/        # 单策略/组合回测/少女少妇模拟器 → 绩效结果
                                    #   ↑ active_market_gate.py 注入闸门 port（TradingGate）控制开仓/强平
  → verify/pipeline.py            # 五项硬指标验收（v1.0）
  → CLI --json / Web API          # 宿主消费结构化数据