A股估值偏离捕捉 v3.1

收盘后扫描全 A 股，捕捉 6 类估值偏离机会，自动生成 Excel + Word + PPT + HTML 四件套报告
（--report-format all 出三件套，加 --html-report 才是完整四件套）；
附热门板块估值、底部异动与主力资金监控；扫描结果自动入库（SQLite 扫描历史）并可一键写入 11 类知识库，
形成「筛选 → 入库 → 知识沉淀 → 命中跟踪验证」的研究闭环。

本工具输出的是"机会提示"，不是买入推荐。 详见下方重要限制与 references/disclaimer.md。

重要限制（先读）

> 💡 定位：辅助研究分析的估值偏离扫描器，帮用户快速筛出值得关注的标的，
> 不替代深度研究和专业判断。任何对外输出必须附免责声明。

> ⚖️ 合规底线：本工具输出的一切内容仅供学习与研究参考，不构成任何投资建议或买卖推荐。
> 不出现"必须买""全仓""稳赚""建议买入"等指令性措辞；必须标注数据模式与数据质量等级；
> 报告文件须包含 references/disclaimer.md 全文。

Step 1：检测运行环境（必做，决定后续路径）

不要跳过这一步。 不同环境的可用路径不同，跳过会导致命令失败或静默降级。

1.1 确认解释器（sys.executable 不是预期解释器时，如指向 LibreOffice 自带的
C:\Program Files\LibreOffice\program\python.exe 或没有装依赖的虚拟环境，
改用 py -3.11 或完整路径调用）：

python -c "import sys; print(sys.executable); print(sys.version.split()[0])"

Python < 3.9 → 停止，工具不兼容。

1.2 检测依赖：

python -c "import sys,importlib.util as u;n=['akshare','docx','pptx','matplotlib','yaml','openpyxl'];print('python',sys.version.split()[0]);[print(x,'OK' if u.find_spec(x) else 'MISSING') for x in n]"

1.3 检测结果 → 路径决策：

退出条件：拿到依赖表，并据此确定 Step 2 的 --report-format / --no-charts / 运行模式。

> 不确定时优先 --demo：demo 离线、秒级完成、结果可复现，适合验证链路；
> 确认流程通再切真实模式。

Step 2：确定运行参数

参数默认值表（完整参数表见 references/cli-reference.md）：

策略取值：absolute relative historical event dividend etf nav
（别名 absolute_value / relative_value / historical_low / event_drive / dividend_yield /
etf_discount / nav_sector 同样有效；未知名称会打印 WARNING 并被忽略。）

默认组合（用户未给任何细节时）：--report-format all --html-report --save-json --workers 4。
真实模式耗时较长，若无明确要求，先跑 --demo 验证链路。

退出条件：确定运行模式（demo/真实）+ 完整命令串。

Step 3：执行扫描

在 skill 根目录下执行：

python scripts/daily_scan.py --demo --report-format all --save-json

• 必须带 --save-json：Step 6 的知识库写入、Step 7 的跟踪对比都依赖扫描 JSON。
• 命令耗时较长（真实模式全市场），用后台任务执行并轮询，不要前台长阻塞。
• 日志出现 WARNING 未知策略名被忽略 → 用户指定的策略名有误，修正后重跑。

退出条件：进程退出码为 0，且产出 JSON（~/.stock-valuation-screener/outputs/valuation_screen_<date>.json）。

Step 4：校验扫描结果（不要只看"完成"）

从日志逐行确认这四项，任一不达标就要在最终输出中如实说明：

其它必看项：底部异动: 检出 N 只、组合摘要: HHI=... 健康度=...、命中跟踪: 回看 N 只历史命中。

降级判定：日志出现 source=sample / mock / 使用内置数据 → 本次是 demo/mock 数据，
最终输出必须标注"数据非实时，离线 mock 兜底"。

退出条件：四项校验完成，知道本次结果能支撑到什么结论强度。

Step 5：生成报告

--report-format all = Excel + Word + PPT 三件套；要 HTML 看板需另加 --html-report
（那才是完整四件套）。只有 Excel（默认）时可从已有 JSON 补生成：

# 从已有 JSON 补生成其它格式（不重扫）
python scripts/reports_cli.py --input outputs/valuation_screen_<date>.json --format all

退出条件：拿到报告文件路径（Excel/Word/PPT/HTML），能报给用户。
sheet 清单与图表说明见 references/report-structure.md。

Step 6：写入知识库与扫描历史（可选，用户要求时）

6.1 扫描历史（默认自动） — 结果自动入库 ~/.stock-valuation-screener/db/scan_history.db
（--no-db 可关），同日重跑幂等替换。kb_cli.py query --code 600519（单股命中历史）/
compare（与上一期对比：新增/消失/连续命中）/ stats（数据库总览）。

6.2 知识库（需先登记目标） — 完整参数见 references/cli-reference.md。

# 登记（类型：markdown/obsidian/sqlite/json/csv/ima/dify/notion/yuque/siyuan/flomo）
python scripts/kb_cli.py add-target --name 本地库 --type markdown --path "D:/kb/估值扫描"
python scripts/kb_cli.py add-target --name ima笔记 --type ima

# 写入（扫描时加 --kb 可一步完成）/ 读回 / 搜索
python scripts/kb_cli.py write --json outputs/valuation_screen_<date>.json --target 本地库
python scripts/kb_cli.py read --code 600519      # 股票卡
python scripts/kb_cli.py search --query 茅台      # 全类型搜索

• 凭证一律走环境变量，不写入 config.yaml、不入库。变量清单见 references/knowledge-base.md。
• 单目标失败会被隔离，不影响其它目标；要如实报告哪些目标写成功、哪些失败。
• 不重扫、直接补投：python scripts/daily_scan.py --kb-only outputs/valuation_screen_<date>.json
• 退出条件：知道写入了哪些目标、哪些笔记类型（股票卡/扫描日报/板块/异动/MOC）、哪些失败。

Step 7：命中跟踪与策略验证（可选）

回答"这个策略到底灵不灵"时使用：

python scripts/kb_cli.py track

• 区间收益 + 验证结论三态：达标 / 失败 / 观察
• 距上次命中 ≥5 个交易日才下"达标/失败"结论，否则记为"观察中"
• 输出策略通过率横向对比（哪种策略有效、哪种常年空转）

退出条件：拿到策略通过率结论；若样本不足（多为"观察中"），如实说明样本不足而非强行下结论。

Step 8：输出结论给用户

按需裁剪以下结构，报告文件路径必须以可点击形式给出：

1. 📊 扫描概览 — 标的数 / 命中数 / 命中率 / 扫描日期 / 数据模式（demo 或真实）
2. 🎯 估值偏离机会 — 代码 / 名称 / 现价 / 综合偏离度 / 风险评分 / 确定性评分 / 触发逻辑链
3. 📈 热门板块（本次有数据时）— 板块 / 热度评分 / 资金流向 / 龙头股 / 估值便宜股
4. 🔔 底部异动（本次有数据时）— 异动股 / 异动分 / 量比 / 换手率 / 底部得分
5. 💰 资金监控（本次有数据时）— 主力净流入 / 连续天数 / 方向反转 / 大额流入
6. 📄 报告路径 — Excel / Word / PPT / HTML 的实际文件路径
7. 📚 知识库与跟踪（本次执行了才写）— 同步目标 / 写入状态 / 命中跟踪结论
8. ⚠️ 风险提示 — 数据质量等级 / demo 模式标注 / 估值模型局限 / 样本不足说明
9. ⚠️ 免责声明（强制，不可省略）
   "以上为估值偏离机会筛选结果，基于公开数据与量化模型，非投资建议。数据可能滞后，筛选仅供参考，投资有风险。"

合规底线（每次给投资相关结论都要满足）：

• 不出现"必须买""全仓""稳赚""建议买入"等指令性措辞
• 一定标注数据模式（demo/真实）与数据质量等级
• 一定附免责声明；报告文件须包含 references/disclaimer.md 内容

六类筛选策略

扩展分析模块（随主扫描自动产出，模块明细见 references/report-structure.md）：
热门板块（热度评分 + 资金流持续性 + 估值象限 + 偏离股）、净值便宜板块（ETF 折价按板块聚合 + 双重信号）、
底部异动（底部得分 + 量比/换手率 robust z-score 双确认）、资金监控（连续净流入天数 + 方向反转 + 大额流入）、
组合聚合（HHI + 加权偏离/风险 + 健康度）、数据质量（A/B/C/D 等级）、轻量回测（命中率 + 胜率 + 回撤）。

评分读法

综合偏离度是相对值：≥70 高度关注、50-70 适度关注、<50 暂时观望，但必须结合风险评分判断。

场景 → 命令速查

时间预算（真实模式）

15:30 拉数据 → 15:35 策略扫描（--workers 可并行）→ 15:40 量化分析 →
15:42 热门板块 → 15:43 净值板块 → 15:44 组合聚合与数据质量 →
15:45 四件套报告 → 15:50 落盘 + 入库 + 跟踪回看。

参考文件