financial-analysis AGENTS.md

AGENTS.md

本文件适用于仓库根目录及所有子目录，供后续编码 agent 和维护者使用。开始修改前先读 README.md 与 ARCHITECTURE.md。如果未来某个子目录增加更具体的 AGENTS.md，以离目标文件最近的规则为准。

1. 工作原则

1. 先确认真实实现，再改文档或代码。入口、CLI、数据源和产物经常一起演进，不要只根据文件名或旧注释推断。
2. 把当前工作区视为用户现场。先运行 git status --short 和相关 git diff；已有修改、未跟踪研究结果和本地数据库都属于用户，不能顺手清理、覆盖或回滚。
3. 保持改动聚焦。不要把文档任务扩成模型调参，不要把诊断任务扩成生产修复，也不要为通过测试而改变未被请求的策略口径。
4. 用最小但足够的验证证明改动。优先跑直接相关测试，再根据风险决定是否跑完整套件。
5. 所有金融输出都是研究信号。新增页面文案、导出或报告时，不得暗示确定收益或自动交易能力。

2. 仓库事实

• 运行环境：Python 3.10+；当前代码使用 X | None、argparse.BooleanOptionalAction 和内置泛型等语法，文档编写时在 Python 3.12.12 验证。
• Web：Flask + Jinja + 原生 JavaScript/CSS，无前端构建步骤。
• 测试：标准库 unittest；没有 pytest.ini、pyproject.toml、tox 或项目级 lint/format 配置。
• 依赖：requirements.txt 没有锁定精确版本，也没有单独的开发依赖文件。
• 主存储：本地 SQLite；运行产物为 JSON/SVG。
• 工作目录很重要：多个存储模块使用相对路径 Path("data")，命令必须从仓库根目录执行。
• 网络抓取依赖公开接口，可能受代理、限流、字段变化和非交易日影响。

3. 环境与常用命令

macOS、Linux 及基于 Linux/Unix 的国产系统从仓库根目录执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Windows PowerShell：

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

启动本地工作台：

python run.py --port 8765

跑单个测试文件：

PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -p 'test_hot_money_radar.py' -v

跑完整测试：

PYTHONDONTWRITEBYTECODE=1 python -m unittest discover -s tests -v

Windows PowerShell 对应写法：

$env:PYTHONDONTWRITEBYTECODE = "1"
python -m unittest discover -s tests -v

交付前至少运行：

git diff --check
git status --short

不要用联网刷新命令充当普通单元测试。测试外部数据适配时注入 fetcher、mock HTTP/AkShare 响应，并用临时目录或 :memory: SQLite。

4. 写入与副作用分级

明确会联网并写本地状态

• python fund_data_refresh.py
• python stock_radar_fresh_data.py
• stock_crawl_*.py、plate_crawl_history.py 等抓取器
• stock_data_refresh.py
• stock_hot_money_radar.py 的生产/实验模式
• stock_crawl_news.py、mf_pilot.py crawl

除非任务明确要求刷新真实数据，否则不要在验证阶段运行这些命令。

两个 .py 刷新入口都会复用当前解释器，并在 Windows 与 POSIX 系统上通过参数列表启动子进程。fund_data_refresh.py 保持为根目录基金刷新入口，内部子步骤通过 python -m fund... 运行。