核心功能与工作流程
VNStock Free Expert 是一套专为越南股市（HOSE/HNX/UPCoM）设计的量化分析技能，基于 vnstock 开源库构建，完整覆盖从股票池构建到投研备忘录生成的端到端流程。其核心执行链路包括：
1. 环境校验与密钥管理：自动检测 Python 环境、依赖库，并支持从 .env 文件加载 VNSTOCK_API_KEY 进行认证升级；
2. 股票池构建（build_universe.py）：支持按指数成分（如 VN30）、交易所或自定义代码列表构建分析标的；
3. 市场数据采集（collect_market_data.py）：获取 OHLCV 及动量指标（3M/6M/12M 收益率），严格遵循 3.2 秒/请求的安全 pacing；
4. 基本面采集（collect_fundamentals.py）：提取估值与质量指标；
5. 综合评分排名（score_stocks.py）：多因子复合打分；
6. 报告生成（generate_report.py）：输出分析师风格的 Markdown 投研备忘录。
显著优势
- 免费级安全设计：内置双层速率控制——无 API Key 时≤20 请求/分钟，有 Key 时≤60 请求/分钟，默认 3.2 秒/请求间隔，有效规避封禁风险；
- 标准化置信度框架：强制输出
High/Medium/Low三级数据置信度评估，要求披露股票覆盖率、关键指标缺失率及硬性错误比例，避免"黑箱"结论； - 灵活的数据源策略：优先使用 KBS（Kết nối Bán lẻ & Sở）数据，VCI（Vietnam Capital Intelligence）作为 fallback，明确禁用 TCBS 以规避稳定性问题；
- 模块化脚本架构：7 个独立脚本支持原子化调用或管道串行，同时提供
catalog_vnstock.py和invoke_vnstock.py用于动态探索 vnstock 全部能力； - 健壮的错误处理：符号级失败隔离、缺失值标记（非零填充）、关键步骤中断机制，确保批量运行不崩溃。
潜在局限与风险
- Screener API 可用性：明确将 Screener 功能视为不可用，除非用户确认其本地版本已恢复，限制了快速筛选能力；
- 数据覆盖边界：越南中小盘股及 UPCoM 板块可能存在财报披露延迟或字段缺失，可能导致
Low置信度输出； - 单市场局限：仅支持越南市场，无法扩展至东南亚其他交易所；
- 动量计算依赖：3M/6M/12M 收益率需完整交易日数据，若遇长假或停牌可能导致指标失真。
适用人群
- 量化散户投资者：希望低成本获取越南龙头股（VN30）的系统性评分；
- 财经内容创作者：需要结构化数据支撑越南市场分析文章；
- 初级投研人员：学习多因子选股框架，理解数据质量与模型置信度的关系。
常规风险提示
- 数据源稳定性：KBS/VCI 均为第三方聚合接口，非交易所直连，存在延迟或格式变更风险；
- 免费 tier 硬限制：即使遵循 pacing，高频调用仍可能触发 IP 级限流，建议配合缓存复用；
- 估值模型简化：内置评分逻辑未公开权重细节，不适合作为唯一决策依据；
- 汇率与政策风险：越南盾波动、外资持股比例限制等宏观因素未纳入模型。