核心用法
VNStock Free Expert 是一套端到端的越南股票分析工作流，基于 vnstock Python 包构建，专为免费用户设计。其核心流程包括：环境验证 → 构建股票池 → 采集市场数据 → 采集基本面数据 → 综合评分排名 → 生成分析师风格报告。支持通过 build_universe.py 按指数组（如 VN30）、交易所或自定义代码列表构建分析范围，使用 kbs 为主要数据源、vci 作为备选，明确禁用 tcbs。
显著优点
1. 免费级安全设计：内置严格的速率限制（无 API 键≤20请求/分钟，免费键≤60请求/分钟），默认 3.2 秒/请求的安全 pacing，避免触发供应商限流
2. 标准化置信度体系：强制要求报告 High/Medium/Low 三级置信度，基于覆盖率（≥95%/80%）、关键指标完整度（≥80%/60%）和硬错误率（≤5%/15%）量化评估
3. 模块化脚本架构：7 个专用脚本覆盖发现、采集、评分、报告全流程，支持单脚本调用或 run_pipeline.py 一键执行
4. 下游技能兼容：单票深度分析时输出标准化 JSON bundle，可直接喂给 equity-valuation-framework 和 portfolio-risk-manager
5. 弹性错误处理：符号级失败记录并继续，关键步骤失败时中断并报告重试范围
潜在缺点与局限性
- 数据源约束：
tcbs完全禁用，Screener API默认可用性受限，需用户确认版本恢复 - 免费级吞吐量瓶颈：即使优化 pacing，大规模全市场扫描仍耗时显著
- 越南市场专属性：无法扩展至其他新兴市场，代码硬耦合 vnstock 生态
- 缓存依赖：跨步骤复用缓存 artifacts 是性能关键，但缓存失效机制未详细说明
适合人群
- 个人投资者和量化研究员，需低成本越南股市分析
- 免费 tier 预算受限的开发者，需遵守 API 供应商速率限制
- 需要将 vnstock 数据接入下游估值/风险管理框架的技术用户
常规风险
- 数据新鲜度风险：基本面数据可能存在滞后，需通过
as_of_date字段追踪 - 排名结论敏感性：
Low置信度场景下缺失字段可能翻转排名结果 - 供应商依赖：KBS/VCI 服务可用性变化直接影响数据覆盖
- 配置泄露风险：
.env文件存储VNSTOCK_API_KEY，需确保版本控制排除
技术亮点
catalog_vnstock.py + invoke_vnstock.py 提供动态反射能力，可探测运行时 vnstock 版本能力并泛化调用任意类方法，显著提升前向兼容性。