把 A 股行情、策略研究、持仓与每日复盘，放进一个本地工作台。
AStockAI 是一个基于 Python 与 Streamlit 的开源 A 股研究工具：从下载行情、核对证据，到查看个股、整理持仓和生成日报，把日常研究流程串起来。无需 AI API Key 即可开始使用；需要时再接入自己的大模型服务，辅助解读研究材料。
| 你想做的事 | AStockAI 提供的支持 |
|---|---|
| 每天更快进入复盘状态 | 行情更新、量化快照、日报与系统状态集中查看 |
| 研究一只 A 股 | 按代码或名称查找，按需下载日线，查看技术指标与研究证据 |
| 按不同思路核对机会 | 策略筛选、周期分类，以及 30 位投资大师公开理念的研究清单 |
| 管理自己的观察与持仓 | 本地关注列表、手动持仓管理、独立模拟仓与交易流水 |
| 检查研究结论是否可靠 | 来源记录、数据日期校验、样本外研究与历史输入审计 |
投资研究常常分散在行情软件、表格和笔记里。AStockAI 希望把这些步骤连接起来，让每次复盘都能回答：数据来自哪里、更新到哪天、结论依据是什么、还有哪些证据缺失。
- 先有数据，再做解读：核心流程可独立于 AI 运行，AI 分析按需启用。
- 研究过程可以追溯：行情记录来源和复权方式；下载失败保留旧文件，明确显示问题。
- 回测有明确的输入门槛：核对历史成分、原始成交价格、交易状态和公司行为；证据不足时输出拒绝原因。
- 个人工作台留在本机：持仓、关注列表和研究产物默认在本地保存，不连接券商，也不自动交易。手动启用 AI 或邮件时，相关请求内容会发送到你配置的服务。
Local A-share research workspace with traceable market data, portfolio tracking, daily reports, and optional AI analysis.
仅供研究与学习，不构成投资建议、收益承诺或目标价。
需要 Python 3.10+（推荐 3.12），支持 macOS、Linux 和 Windows。核心功能无需 API Key，也无需邮箱配置。首次安装依赖和下载行情需要联网。
git clone https://github.com/baek0418/AStockAI.git
cd AStockAI
python3 start.pyWindows 在终端使用 py -3 start.py。不使用 Git 也可以从 GitHub 的 Code → Download ZIP 下载解压，在项目文件夹打开终端运行启动命令。
- 启动器自动创建
.venv、安装依赖并启动网页，无需手动激活虚拟环境。 - 打开终端显示的地址，默认 http://127.0.0.1:8501。
- 在欢迎页点击 初始化本地数据，下载内置 10 只示例股票的日线，生成量化快照和日报。通常需要数分钟，可查看后台任务日志。
- 初始化结束后页面自动进入工作台；部分下载失败时查看日志并重试，旧文件会保留。也可点击“刷新页面”查看已生成的内容。
启动网页不会自动下载行情、调用 AI 或发送邮件。首次打开只创建本地空关注列表；下载必须点击按钮。内置股票池仅为功能示例，不是推荐名单。
以后仍运行同一条启动命令；按 Ctrl+C 停止。启动器在依赖清单变化时重新安装依赖；手动修复环境可运行 python3 start.py --reinstall。端口被占用时使用 python3 start.py --port 8502。
手动安装或无界面初始化
macOS / Linux：
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python setup_local.py
.venv/bin/python -m streamlit run app.pyWindows PowerShell（不需要修改执行策略）：
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe setup_local.py
.\.venv\Scripts\python.exe -m streamlit run app.pysetup_local.py 可以重复运行，不清空已有关注列表或数据，不调用 AI、不发送邮件。只想提前安装依赖可运行 python3 start.py --install-only。
| 情况 | 处理方法 |
|---|---|
找不到 python3 或 py |
安装 Python，Windows 安装时勾选 Add Python to PATH，然后重新打开终端 |
Linux 提示缺少 venv / ensurepip |
安装发行版对应的 python3-venv 包后重试 |
| 安装依赖失败 | 检查终端中的 pip 错误和网络配置，修复后重新运行启动命令；不会标记失败安装为完成 |
| 初始化失败或数据较旧 | 查看欢迎页任务日志或系统状态；检查公开行情服务和本机代理配置，恢复后重试 |
| 未配置某年的交易日历 | 根据交易所公布的安排更新 config/a_share_market_holidays.json；系统不会自行猜测休市日期 |
| 想更新项目 | 备份本地数据后执行 git pull --ff-only，再次运行启动命令；ZIP 用户将新代码解压到新目录，按下文迁移数据 |
备份或迁移时，按需复制 watchlist.json、data/（含持仓与模拟仓）、output/、models/ 和个人 .env 到新项目目录；不要复制旧 .venv，在新目录重新运行启动命令。不要将这些个人文件上传 GitHub。
根目录只保留直接使用的入口：
start.py：跨平台安装依赖并启动网页（推荐入口）。app.py：Streamlit 网页。setup_local.py：首次初始化本地数据。pipeline.py：手动执行完整的数据、研究和日报流程。background_task_runner.py：网页后台任务入口，无需手动运行。
业务代码集中在 astock_core/，按职责分为 analysis/（分析）、data/（行情与股票池）、portfolio/（持仓）、simulator/（模拟仓）、strategies/（策略执行）、reporting/（日报）、research/（研究）和 runtime/（后台任务与日志）。tests/ 用于开发验证，config/ 存放公开配置；数据、模型、日报和持仓默认保存在本机，不随代码提交到 GitHub。
这是刻意的隐私设计。GitHub 不包含任何人的行情快照、日报、模型、持仓、关注列表或邮箱配置。下载项目后，在欢迎页点击初始化或运行 setup_local.py，才会在你自己的电脑生成这些内容。持仓管理中的账户、成本和数量也只保存在 data/portfolio.json，不会上传 GitHub。
- 投资总览：先看持仓数据是否齐全，以及当天要核对什么。
- 持仓管理：手动录入、预览并确认保存本地持仓；没有券商连接，不是实时盘中行情。
- 策略中心：选择并手动运行策略。首个“A股午后强势筛选”会在交易日 14:30 后核验公开实时行情、日线和分时证据，保存带时间戳的结果；数据不足或无完全符合条件的股票时会明确说明。
- 策略周期与研究框架：策略卡会标注短线、中长线或长线。用户可按周期筛选，并将内置框架或“30 位投资大师公开理念参考”设为单股研究框架；每项均记录第三方 skill 来源，但只使用公开方法论主题，不加载角色扮演规则。周期表示本项目的研究复核频率，不是作者承诺的持有期。这些框架只改变证据核对清单，不是任何个人或金融机构的官方观点或自动交易策略。
- 模拟仓：独立于真实持仓的本地模拟现金、持仓和流水。用户确认后可按策略快照价格建立模拟仓，不能向券商发送任何指令，也不把快照价描述为下一交易日实际成交价。
- 单股票查询：输入股票代码或名称。已生成本地快照的股票可直接查看；其他股票需要你点击“下载并分析”。
- 未来 5 日风险范围：只在单股票页、原始日线和研究验证都齐全时显示。它表示按最近波动估算的常见价格范围，不是目标价或买卖建议。
- 系统状态：只有出现数据问题或你想手动刷新时再查看。
页面只绑定本机 127.0.0.1，不会部署到公网。数据写入后刷新浏览器即可看到最新内容。
默认不需要配置 .env。如果你希望手动使用 AI 分析或发送日报邮件，再复制并填写模板：
cp .env.example .env.env、邮件地址、授权码和 API Key 都不会被提交。即使不配置，它也能正常使用本地数据、规则分析与网页查询。
运行测试（不会下载行情、调用 AI 或发送邮件）：
.venv/bin/python -m unittest discover -s tests -v收益区间的研究口径与边界见 说明文档。历史股票池、原始成交价格、公司行为和交易状态的严格回放契约见 研究与回测数据契约。输入证据不完整时研究入口会生成拒绝记录，不再输出未经核验的策略收益。
“单股票查询”会先复用已有 quant_snapshot 中的股票，避免重复下载。对于其他 A 股：
- 输入六位代码，或先点击“更新本地代码目录（可选）”后按名称、模糊名称查找；目录只保存代码与名称。更新优先使用上交所、深交所公开 HTTPS 股票列表，无需配置 BaoStock 直连；仅在该来源临时不可用时自动尝试 BaoStock 兜底。
- 选择候选股票后，点击“下载并分析”才会请求这一只股票的历史日线。
- 临时日线与分析快照分别保存在
data/on_demand/、output/on_demand/，不参与日报、研究股票池或回测。 - 页面会标注最近日线数据日期；它不是实时盘中行情。AI 分析仍须手动点击触发。
- “加入关注列表”是唯一会修改
watchlist.json的显式操作，新增股票将在下一次股票池更新时生效。
六位代码直查不依赖名称目录：点击下载后会由腾讯接口识别股票并获取日线。名称和模糊名称仅使用已有本地目录；目录刷新失败（包括代理错误）时，页面会提示可继续输入六位股票代码。按需快照会记录行情来源与名称目录来源；不会修改用户代理配置或尝试绕过代理。
单股票页可查看已有本地基本面事实快照，包括来源、报告期和可核对指标。基本面在线下载与研究池自动刷新暂时停用，等待替代数据源验证，界面会明确提示。系统状态中的高级信息保留了数据审计与样本外研究，供需要时展开查看。收益区间的口径、验证方式与边界见 说明文档。
仓库不会包含 API 密钥、SMTP 密码、邮箱地址、个人关注列表、本地行情数据、模型文件、日志、日报或打包产物；它们均由 .gitignore 排除。本项目以 MIT License 发布。
正式日线使用腾讯前复权，失败后尝试 BaoStock 0.9.3 前复权；均失败则保留旧文件并记录失败。禁止请求任何东方财富接口，包括包装库和备用源。 原始价格研究使用隔离目录，不覆盖正式行情。基本面在线下载与研究池自动刷新暂时停用。
数据来源与故障检查 包含生产日期校验、日志位置、离线审计和历史文件恢复说明。开发与贡献指南 包含目录职责、验证和提交要求。
欢迎通过 Issues 分享使用体验、复现问题或提出需求，也欢迎提交 PR。当前尤其需要可验证的数据源适配、历史交易状态与公司行为证据，以及更清晰的研究展示。
报告问题时请附上运行步骤与脱敏后的错误信息，避免提交持仓、邮箱配置或密钥。如果这个项目对你的研究流程有帮助，欢迎 Star，持续关注迭代。