核心功能与架构
A-stock-report 是一套面向A股市场的数据驱动型报告自动化系统，采用三层架构设计：dispatcher 调度层 + send 推送层 + templates 模板层。系统支持6类报告场景：晨报、收盘小结、晚报、盘中预警、IPO周报、财经周末版，覆盖交易日全时段信息需求。
核心特性：
- 投资者情绪量化模型：6维度打分体系（涨停家数、涨跌停比、炸板率、主力净流入占比、换手率、IF基差），满分100分，自动映射为5级操作建议
- 双执行模式：LLM驱动型（晨报/晚报/周末版，需模板+生成+推送两段式）与独立脚本型（收盘小结/盘中预警/IPO周报，纯bash直接执行）
- 4端一致性护栏：v3.1.5+引入机械检查脚本
check_consistency.py，强制保障 templates/、cron_mirror.json、jobs.json、SKILL.md 四方配置同步，杜绝"改一处忘三处"
显著优点
1. 工程化成熟度极高：v3.2.5历经50+次迭代，沉淀13条核心教训（lessons-learned.md），锁机制、残留自愈、推送共用库、退出码语义等基础设施完善
2. 数据源多元交叉：腾讯实时指数、akshare全量行情、同花顺问财API、东方财富资金流、新浪/AKShare期货基差等7+来源，关键指标互验
3. 安全设计审慎：密钥白名单原则（每脚本仅加载必需env）、问财API进程内直连（防IENV泄露）、文件锁防并发、残留锁被动自愈机制
4. 可观测性完备：cron任务状态追踪、推送失败分级通知（notify_failure）、护栏脚本exit 0/1/2语义明确
潜在局限与风险
| 类别 | 具体表现 |
|------|---------|
| 数据延迟 | 两融数据T-1滞后（收盘后1-2小时更新），周末版需跨文件合并历史数据，日期对齐逻辑复杂 |
| 外部依赖脆弱性 | 腾讯/qt.gtimg.cn、同花顺问财、东方财富RPT接口任一变更即可能中断；v2.0.4大小写兼容、v2.0.1字段名兼容等补丁反映API不稳定历史 |
| 高频任务成本 | 盘中预警每5分钟触发（日48次），v3.2.5前误配LLM调度导致每日浪费48次context，虽已修复但同类设计风险需警惕 |
| 回溯限制 | IPO周报历史回溯≤4周（API限速），超量触发服务降级 |
| 情绪模型黑箱 | 6因子等权平均的映射公式（如`_sc(exp_rate, 40, 10)`）未在SKILL.md完整披露，调参需读源码 |
适合人群
- 个人量化投资者：需自动化盘后复盘、早盘前瞻、周末聚合分析的A股交易者
- 小资管/私募运营：替代人工盯盘生成标准化日报，降低运营人力成本
- 数据分析师：需结构化历史报告（MD格式）进行情绪指标回测验证
常规风险
- 误配cron导致内容空洞：晚报"财经要闻"和"明日操作建议"区块必须由cron LLM步骤生成，若未配置或dispatcher失败则永久为空（设计预期，非bug）
- 锁残留阻塞：推送阶段网络超时/信号中断可能导致锁文件残留，需手动介入（
rm /tmp/*.lock）或等待下次lock()触发自愈 - 数据源漂移：问财API字段名同义词翻译不稳定性需消费侧兼容多字段名（如
炸板家数/涨停开板家数） - 情绪打分误读：分值区间映射为操作建议是统计参考，非交易信号，文档已强制标注"仅供参考，不构成投资建议"
版本演进关键节点
- v3.0.0：模板外置重构，SKILL.md从40KB瘦身至31KB，确立"双职责正交"原则
- v3.1.5：4端一致性护栏脚本上线，机械防漂移成为核心工程能力
- v3.2.0-3.2.5：Changelog瘦身（-38%行数）、config.json索引化、IPO周报共用库迁移、盘中预警纯bash化，持续优化token效率与运维可观测性