一个本地运行、研究优先的 A 股短线工具包：把用户提供的候选池转化为可复现的 BUY、SELL、HOLD 决策，并用同一套核心规则支持实时监控、历史回放、候选池回测和 T+1 模拟交易。
本仓库是从本地研究环境脱敏整理的首个公开快照，因此公开提交历史短于实际本地研发过程。私有候选池、研究输出、真实持仓、凭证和通信内容均未公开。
- 面向研究、复盘和模拟执行，不直接向券商提交实盘订单。
- 使用用户自行提供的候选股票，不宣称是全市场自动选股器。
- 默认按照普通 A 股 T+1 约束维护模拟持仓。
- 免费行情接口可能延迟、缺失或变更，重要信号必须交叉核验。
- 历史结果不代表未来收益，本项目不构成投资建议。
flowchart LR
A[用户候选池] --> B[配置与数据适配]
B --> C[实时快照 / 分钟线 / 日线]
C --> D[市场环境与题材特征]
D --> E[确定性规则引擎]
E --> F[BUY / SELL / HOLD]
F --> G[T+1 模拟持仓与风控]
F --> H[通知与订单意图]
F --> I[决策日志]
I --> J[历史回放与候选池回测]
J --> K[归因、比较与规则迭代]
| 模块 | 公开版实现 |
|---|---|
| 数据接入 | AKShare 免费数据适配，可选 JQData 历史研究支持 |
| 特征与环境 | 开盘区间、VWAP、换手、市场状态、短线情绪与题材层 |
| 决策 | 可配置的入场、退出、风险否决和降级规则 |
| 模拟交易 | 本地现金、持仓和成交记录，默认执行 T+1 |
| 验证 | 历史回放、每日候选池回测和基线比较入口 |
| 运行 | 实时候选池监控、决策日志、桌面/邮件通知 |
| 安全边界 | 凭证只从环境变量读取；真实数据、日志和配置默认忽略 |
需要 Python 3.11 或更高版本。
git clone https://github.com/111aaa327/a-share-trading-agent.git
cd a-share-trading-agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item config\today_watchlist.example.json config\today_watchlist.json将示例股票替换为自己的观察池，然后运行一次安全的监控周期：
python run_agent.py --once也可以先从命令行更新观察池：
python prepare_watchlist.py 600000 000001
python run_agent.py --interval 20 --stop-after-close决策和模拟持仓状态写入 logs/；该目录已从 Git 中排除。
# 在历史数据上回放规则引擎
python run_replay.py --help
# 使用自己的历史候选池运行回测
python run_daily_pool_backtest.py --help
# 查看实时监控参数
python run_agent.py --help如需使用 JQData，将凭证放在当前终端环境变量中，不要写入仓库：
$env:JQDATA_USERNAME = "your-account"
$env:JQDATA_PASSWORD = "your-password"公开版包含无需联网的配置与状态模型测试，可直接运行：
python -m unittest discover -s tests -v
python -m compileall -q src testsGitHub Actions 会在每次提交时执行相同检查。它验证基础工程行为，不代表策略收益验证。
当前重点验证以下边界：
- 股票代码和观察池配置过滤是否稳定；
- 中文配置读写是否保持 UTF-8；
- 持仓和成交状态能否无损序列化、恢复；
- 历史回放与实时监控尽可能复用同一规则引擎；
- 特征必须在决策时点可获得，研究和留出数据按日期隔离。
更多公开范围说明见 docs/RESEARCH_SCOPE.md。
config/ 脱敏的观察池配置示例
docs/ 公开范围与研究说明
src/a_share_agent/ 数据、规则、状态、监控与验证模块
tests/ 无需外部行情的基础回归测试
prepare_watchlist.py 观察池准备入口
run_agent.py 实时监控入口
run_replay.py 历史回放入口
run_daily_pool_backtest.py 候选池回测入口
当前版本属于研究原型，适合展示量化系统工程化、策略形式化和安全模拟执行能力。后续计划包括扩大自动化测试、补充可复现的公开示例报告，并进一步拆分大型研究模块。
MIT，详见 LICENSE。数据仍受各自来源条款约束。