TradingAgents-CN 后端股票代码验证多市场快速失败机制与港股代码规范化实战【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN导读本文围绕 TradingAgents-CN 后端股票代码验证功能的完整实现展开剖析了分析前验证 多市场格式规则 港股代码自动规范化 快速失败四大设计要点。读者将掌握如何让多智能体分析框架在 LLM 调用之前拦截无效股票代码、如何将00700正确规范化为0700.HK以及如何通过统一验证入口在 CLI、Web 与异步后台服务三条调用链中复用同一套验证逻辑。1. 问题背景无效代码为何能绕过检查进入分析流程TradingAgents-CN 是基于多智能体 LLM 的中文金融交易框架。在早期版本中用户输入港股代码00700腾讯控股后后端未识别出该股票不存在或格式错误而是继续执行分析任务。该问题的根源可归纳为三点后端缺少分析前验证任务一旦创建即进入后台执行未在分析开始前检查股票代码是否存在港股代码格式化逻辑有误旧实现使用f{stock_code.zfill(4)}.HK输入00700时输出00700.HK而正确的腾讯控股代码应为0700.HK失败任务未及时终止即使数据获取注定失败分析任务仍会继续执行浪费计算资源与 LLM Token。从调用链来看无效代码可能在分析流程中后期才暴露——此时已经消耗了数据获取、多智能体辩论等环节的资源属于典型的晚失败late failure问题。2. 解决方案总览在分析开始前完成验证 预取数修复后的整体思路是在分析任务真正启动前先完成格式校验、数据预获取与缓存任何一步失败都立即将任务置为 FAILED 并返回绝不进入分析阶段。该流程的核心价值在于提前验证格式校验发生在任何网络请求与 LLM 调用之前快速失败fail fast无效代码立即返回错误不浪费资源数据复用验证阶段获取的基本信息与历史数据会被缓存供后续分析直接使用。3. 后端接入点execute_analysis_background的验证逻辑验证逻辑首先接入 app/services/simple_analysis_service.py 中execute_analysis_background方法的开头这是异步分析任务的统一入口。3.1 核心代码async def execute_analysis_background( self, task_id: str, user_id: str, request: SingleAnalysisRequest ): 在后台执行分析任务 progress_tracker None try: logger.info(f 开始后台执行分析任务: {task_id}) # 验证股票代码是否存在 logger.info(f 开始验证股票代码: {request.stock_code}) from tradingagents.utils.stock_validator import prepare_stock_data # 获取市场类型 market_type request.parameters.market_type if request.parameters else A股 # 获取分析日期并转换为字符串格式 analysis_date request.parameters.analysis_date if request.parameters else None if analysis_date: # 如果是 datetime 对象转换为字符串 if isinstance(analysis_date, datetime): analysis_date analysis_date.strftime(%Y-%m-%d) # 如果是字符串确保格式正确 elif isinstance(analysis_date, str): try: parsed_date datetime.strptime(analysis_date, %Y-%m-%d) analysis_date parsed_date.strftime(%Y-%m-%d) except ValueError: analysis_date datetime.now().strftime(%Y-%m-%d) # 验证股票代码并预获取数据 validation_result await asyncio.to_thread( prepare_stock_data, stock_coderequest.stock_code, market_typemarket_type, period_days30, analysis_dateanalysis_date ) if not validation_result.is_valid: error_msg f❌ 股票代码验证失败: {validation_result.error_message} logger.error(error_msg) logger.error(f 建议: {validation_result.suggestion}) # 更新任务状态为失败 await self.memory_manager.update_task_status( task_idtask_id, statusAnalysisStatus.FAILED, progress0, error_messagevalidation_result.error_message ) # 更新MongoDB状态 await self._update_task_status( task_id, AnalysisStatus.FAILED, 0, error_messagevalidation_result.error_message ) return logger.info(f✅ 股票代码验证通过: {request.stock_code} - {validation_result.stock_name}) logger.info(f 市场类型: {validation_result.market_type}) logger.info(f 历史数据: {有 if validation_result.has_historical_data else 无}) logger.info(f 基本信息: {有 if validation_result.has_basic_info else 无}) # ... 继续执行分析 ...3.2 与文档版本的差异异步版本适配仓库中的实际实现已从文档中的同步版本演进为异步版本当前 simple_analysis_service.py 导入的是prepare_stock_data_async并直接await同时通过request.get_symbol()兼容symbol与stock_code两种字段。这样避免了在 FastAPI 异步事件循环中通过asyncio.to_thread触发attached to a different loop的事件循环冲突。# 使用异步版本直接 await避免事件循环冲突 validation_result await prepare_stock_data_async( stock_codestock_code, market_typemarket_type, period_days30, analysis_dateanalysis_date )失败时错误信息会被包装为面向用户的友好提示后再写入任务状态user_friendly_error ( f❌ 股票代码无效\n\n f{validation_result.error_message}\n\n f {validation_result.suggestion} )随后分别更新内存任务状态memory_manager.update_task_status与 MongoDB 持久化状态_update_task_status并立即return终止任务。4. 核心实现tradingagents/utils/stock_validator.py的验证与预取数验证的底层能力全部封装在 tradingagents/utils/stock_validator.py 中核心类是StockDataPreparer返回结果对象StockDataPreparationResult并保留StockValidationResult别名以向后兼容。4.1 结果对象结构StockDataPreparationResult通过is_valid布尔值标记验证结果同时携带错误消息与用户建议字段类型含义is_validbool验证是否通过stock_codestr股票代码港股为规范化后的0700.HK格式market_typestr市场类型A股 / 港股 / 美股stock_namestr解析出的股票名称error_messagestr错误描述suggestionstr面向用户的修复建议has_historical_databool历史数据是否获取成功has_basic_infobool基本信息是否获取成功data_period_daysint实际数据天数cache_statusstr缓存状态描述4.2 模块级便捷函数模块底部提供了多个可直接调用的便捷入口单例模式get_stock_preparer持有全局实例prepare_stock_data(stock_code, market_type, period_days, analysis_date)同步验证入口prepare_stock_data_async(...)异步验证入口内部调用_prepare_data_by_market_asyncA股走异步数据准备港股/美股复用同步实现is_stock_data_ready(...)仅返回布尔值判断数据是否就绪get_stock_preparation_message(...)返回可读的验证结果消息。同时保留了StockValidator、get_stock_validator、validate_stock_exists、is_stock_valid等别名保证历史调用方不受影响。4.3 统一验证流水线prepare_stock_data的执行顺序为基本格式验证_validate_format空代码、长度超过 10 字符、各市场正则校验自动检测市场类型_detect_market_type当market_typeauto时按 6 位数字 → A股、4-5 位数字或数字.HK→ 港股、1-5 位字母 → 美股 的顺序自动识别按市场预获取数据并验证_prepare_data_by_market分派到 A股 / 港股 / 美股三个具体实现。异常兜底逻辑同样完善数据准备过程中的任何异常都会被捕获并转换为is_validFalse的结果提示请检查网络连接或数据源配置。5. 多市场格式验证规则详解5.1 A股6 位数字 前缀白名单# 必须是6位数字 if not re.match(r^\d{6}$, stock_code): return error(A股代码格式错误应为6位数字) # 验证前缀 prefix stock_code[:2] valid_prefixes [60, 68, 00, 30, 43, 83, 87] if prefix not in valid_prefixes: return error(A股代码前缀不正确)支持的前缀与板块对应关系为60xxxx上海主板、68xxxx科创板、00xxxx深圳主板、30xxxx创业板、43/83/87xxxx北交所。5.2 港股4-5 位数字支持.HK后缀# 4-5位数字.HK 或 纯4-5位数字 hk_format re.match(r^\d{4,5}\.HK$, stock_code.upper()) digit_format re.match(r^\d{4,5}$, stock_code) if not (hk_format or digit_format): return error(港股代码格式错误)5.3 美股1-5 位大写字母# 1-5位字母 if not re.match(r^[A-Z]{1,5}$, stock_code.upper()): return error(美股代码格式错误应为1-5位字母)5.4 通用防御在进入市场分支前_validate_format还会先剔除首尾空白并做两项全局检查if not stock_code: return error(股票代码不能为空, 请输入有效的股票代码) if len(stock_code) 10: return error(股票代码长度不能超过10个字符, 请检查股票代码格式)6. 港股代码规范化修复00700 → 0700.HK这是本方案最关键的细节修复。旧代码在 stock_validator.py 的_prepare_hk_stock_data中使用# ❌ 旧代码 formatted_code f{stock_code.zfill(4)}.HK # 输入: 00700 # 输出: 00700.HK ← 错误应该是 0700.HK修复后的逻辑为先移除前导 0再补齐到 4 位避免前导 0 撑满宽度导致代码变形# ✅ 新代码 # 移除前导0然后补齐到4位 clean_code stock_code.lstrip(0) or 0 # 如果全是0保留一个0 formatted_code f{clean_code.zfill(4)}.HK logger.debug(f [港股数据] 代码格式化: {stock_code} → {formatted_code}) # 输入: 00700 # 处理: 00700 → 700 → 0700 # 输出: 0700.HK ← 正确当输入已带.HK后缀时仅做大小写归一化.upper()不再重复拼接。格式化示例输入处理步骤输出700700→07000700.HK✅0070000700→700→07000700.HK✅99889988→99889988.HK✅0998809988→9988→99889988.HK✅18101810→18101810.HK✅0181001810→1810→18101810.HK✅7. 数据预获取验证三层校验格式验证通过后StockDataPreparer还会通过真实数据源做存在性验证确保代码不是格式合法但股票不存在。7.1 A股验证流程# 1. 获取基本信息 stock_info get_stock_info_unified(stock_code) if not stock_info or ❌ in stock_info: return error(无法获取股票基本信息) # 2. 验证股票名称 stock_name extract_stock_name(stock_info) if stock_name 未知 or stock_name.startswith(f股票{stock_code}): return error(f股票代码 {stock_code} 不存在或信息无效) # 3. 获取历史数据 historical_data get_stock_data_unified(stock_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取股票历史数据) # 4. 验证数据有效性 if len(historical_data) 100: return error(历史数据不足)7.2 港股验证流程# 1. 格式化代码 formatted_code format_hk_code(stock_code) # 00700 → 0700.HK # 2. 获取基本信息 stock_info get_hk_stock_info_unified(formatted_code) if not stock_info or ❌ in stock_info or 未找到 in stock_info: return error(f港股代码 {formatted_code} 不存在或信息无效) # 3. 解析股票名称 stock_name extract_hk_stock_name(stock_info, formatted_code) if not stock_name or stock_name 未知: return error(f港股代码 {formatted_code} 不存在或信息无效) # 4. 获取历史数据 historical_data get_hk_stock_data_unified(formatted_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取港股历史数据)7.3 美股验证流程# 1. 格式化代码转大写 formatted_code stock_code.upper() # 2. 获取基本信息 stock_info get_us_stock_info_unified(formatted_code) if not stock_info or ❌ in stock_info: return error(f美股代码 {formatted_code} 不存在或信息无效) # 3. 获取历史数据 historical_data get_us_stock_data_unified(formatted_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取美股历史数据)7.4 仓库实现细节三层验证的实际差异对照仓库源码可以发现三个市场的实际实现比文档示例更细A股_prepare_china_stock_data在_validate_format之后会先通过_check_database_data检查 MongoDB 缓存中是否有最新数据若缺失或过期则调用_trigger_data_sync_sync同步包装器自动触发历史数据、财务数据、实时行情三条链路的同步再按配置的数据源优先级tushare/akshare依次尝试。股票名称通过get_china_stock_info_unified返回文本中的股票名称:字段解析。港股_prepare_hk_stock_data名称解析走_extract_hk_stock_name支持字典字段name/longName/shortName/companyName/公司名称/股票名称、公司名称:文本格式、Yahoo Finance 日志格式及公司名关键词Limited/Ltd/Holdings/集团/控股/有限公司等多种识别路径。此外专门针对港股 API 的限流特征Too Many Requests、Rate limited、Connection aborted、网络连接、超时、限制做了网络限制误判识别并返回包含等待 5-10 分钟后重试等步骤的详细建议_get_hk_network_limitation_suggestion。美股_prepare_us_stock_data不单独获取基本信息而是直接通过历史数据验证股票是否存在OptimizedUSDataProvider.get_stock_data失败时回退到get_us_stock_data_cached因为美股代码通常可直接作为股票名称。三个市场的历史数据有效性判定采用统一策略内容长度大于 50 且包含开盘价/收盘价/最高价/最低价/成交量或 open/close/high/low/volume等行情字段。8. 错误处理与用户提示8.1 验证失败的处理流程if not validation_result.is_valid: # 1. 记录错误日志 logger.error(f❌ 股票代码验证失败: {validation_result.error_message}) logger.error(f 建议: {validation_result.suggestion}) # 2. 更新内存中的任务状态 await self.memory_manager.update_task_status( task_idtask_id, statusAnalysisStatus.FAILED, progress0, error_messagevalidation_result.error_message ) # 3. 更新MongoDB中的任务状态 await self._update_task_status( task_id, AnalysisStatus.FAILED, 0, error_messagevalidation_result.error_message ) # 4. 立即返回不执行分析 return8.2 错误信息示例验证失败时返回结构化的结果对象便于前端与日志系统直接使用{ is_valid: false, stock_code: 000999, market_type: A股, error_message: 股票代码 000999 不存在或信息无效, suggestion: 请检查股票代码是否正确或确认该股票是否已上市 }{ is_valid: false, stock_code: 0700.HK, market_type: 港股, error_message: 港股代码 0700.HK 不存在或信息无效, suggestion: 请检查港股代码是否正确格式如0700.HK }{ is_valid: false, stock_code: ABCD, market_type: 美股, error_message: 美股代码 ABCD 不存在或无法获取数据, suggestion: 请检查美股代码是否正确如AAPL、MSFT }9. 测试用例覆盖三市场的通过/失败矩阵A股测试股票代码预期结果说明000001✅ 通过平安银行存在600519✅ 通过贵州茅台存在000999❌ 失败不存在的代码999999❌ 失败不存在的代码00001❌ 失败格式错误5位港股测试重点验证规范化输入代码格式化后预期结果说明7000700.HK✅ 通过腾讯控股存在007000700.HK✅ 通过腾讯控股存在99889988.HK✅ 通过阿里巴巴存在099889988.HK✅ 通过阿里巴巴存在9999999999.HK❌ 失败不存在的代码0700.HK0700.HK✅ 通过腾讯控股存在美股测试股票代码预期结果说明AAPL✅ 通过苹果存在MSFT✅ 通过微软存在GOOGL✅ 通过谷歌存在ABCDE❌ 失败不存在的代码ZZZZZ❌ 失败不存在的代码仓库 scripts/test_stock_data_preparation.py、scripts/test_data_preparation.py 与 scripts/test_hk_error_handling.py 提供了针对数据预取与港股错误处理的验证脚本可直接运行以复现上述行为。10. 性能优化缓存复用与超时控制10.1 数据缓存验证阶段获取的数据会被 Redis 缓存分析阶段直接复用避免重复拉取# 1. 基本信息缓存 stock_info get_stock_info_unified(stock_code) # 会缓存到Redis # 2. 历史数据缓存 historical_data get_stock_data_unified(stock_code, start_date, end_date) # 会缓存到Redis # 3. 分析时直接使用缓存 # 不需要重新获取数据提高分析速度对 A股而言缓存链路还延伸到 MongoDB_check_database_data会查询数据库中已有历史数据及其最新日期允许 1 天延迟命中则跳过同步未命中则自动触发同步同步结果同样写入缓存。cache_status字段会记录数据库数据最新 / 基本信息已缓存 / 历史数据已缓存(N天) / 数据已同步等实际状态供日志审计。10.2 超时控制self.timeout_seconds 15 # 数据获取超时时间 # 如果15秒内无法获取数据返回验证失败timeout_seconds是StockDataPreparer的实例属性默认为 15 秒防止外部数据源响应缓慢拖垮整个验证流程。11. 复用范围CLI 与 Web 调用链中的统一验证验证模块并非只服务于 FastAPI 后台任务而是被三条调用链共享形成一次实现、处处验证的效果FastAPI 异步任务execute_analysis_background使用prepare_stock_data_asyncapp/services/simple_analysis_service.pyCLI 交互式分析cli/main.py 在数据验证阶段调用同步prepare_stock_data先根据代码形态推断市场类型6 位数字 → A股、含.HK→ 港股、否则 → 美股验证失败时直接打印错误与建议并终止Web 工具调用web/utils/analysis_runner.py 在进度回调第一步即执行prepare_stock_data失败时返回带suggestion的结构化结果供上层 UI 展示。这三处调用统一以period_days30作为默认历史数据时长与StockDataPreparer(default_period_days30)的默认值保持一致。对于 A股实际数据回溯天数会进一步受 app/core/config.py 中MARKET_ANALYST_LOOKBACK_DAYS默认 365配置控制。12. 总结与后续优化方向修复前后对比用户输入: 00700 ↓ 后端接收: 00700 ↓ 开始分析没有验证 ↓ 分析过程中发现数据获取失败 ↓ 浪费时间和资源 ❌用户输入: 00700 ↓ 后端接收: 00700 ↓ 验证股票代码 ├─ 格式验证: ✅ 通过4-5位数字 ├─ 格式化: 00700 → 0700.HK ├─ 获取基本信息: ✅ 成功腾讯控股 └─ 获取历史数据: ✅ 成功 ↓ 验证通过开始分析 ✅方案优点✅提前验证在分析开始前验证股票代码无效代码零成本拦截✅快速失败无效代码立即返回错误不浪费 LLM 调用与网络资源✅清晰提示提供结构化的错误信息与可执行建议✅数据缓存验证时获取的数据可在分析时复用降低重复请求✅格式标准化自动修正港股代码格式含前导 0 处理✅三端统一FastAPI 后台、CLI、Web 工具共用同一验证模块。后续优化方向添加股票代码白名单/黑名单机制支持批量验证提升多标的场景下的效率添加验证结果缓存避免同一股票的重复验证支持更多市场新加坡、日本等的代码格式与数据源接入。延伸阅读前端侧的格式预校验实现可参考 docs/integration/data-sources/stock_code_validation.mdfrontend/src/utils/stockValidator.ts与 frontend/src/views/Analysis/SingleAnalysis.vue后端与前端共同构成前端即时提示 后端兜底强校验的双层防线。【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TradingAgents-CN 后端股票代码验证：多市场“快速失败“机制与港股代码规范化实战
TradingAgents-CN 后端股票代码验证多市场快速失败机制与港股代码规范化实战【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN导读本文围绕 TradingAgents-CN 后端股票代码验证功能的完整实现展开剖析了分析前验证 多市场格式规则 港股代码自动规范化 快速失败四大设计要点。读者将掌握如何让多智能体分析框架在 LLM 调用之前拦截无效股票代码、如何将00700正确规范化为0700.HK以及如何通过统一验证入口在 CLI、Web 与异步后台服务三条调用链中复用同一套验证逻辑。1. 问题背景无效代码为何能绕过检查进入分析流程TradingAgents-CN 是基于多智能体 LLM 的中文金融交易框架。在早期版本中用户输入港股代码00700腾讯控股后后端未识别出该股票不存在或格式错误而是继续执行分析任务。该问题的根源可归纳为三点后端缺少分析前验证任务一旦创建即进入后台执行未在分析开始前检查股票代码是否存在港股代码格式化逻辑有误旧实现使用f{stock_code.zfill(4)}.HK输入00700时输出00700.HK而正确的腾讯控股代码应为0700.HK失败任务未及时终止即使数据获取注定失败分析任务仍会继续执行浪费计算资源与 LLM Token。从调用链来看无效代码可能在分析流程中后期才暴露——此时已经消耗了数据获取、多智能体辩论等环节的资源属于典型的晚失败late failure问题。2. 解决方案总览在分析开始前完成验证 预取数修复后的整体思路是在分析任务真正启动前先完成格式校验、数据预获取与缓存任何一步失败都立即将任务置为 FAILED 并返回绝不进入分析阶段。该流程的核心价值在于提前验证格式校验发生在任何网络请求与 LLM 调用之前快速失败fail fast无效代码立即返回错误不浪费资源数据复用验证阶段获取的基本信息与历史数据会被缓存供后续分析直接使用。3. 后端接入点execute_analysis_background的验证逻辑验证逻辑首先接入 app/services/simple_analysis_service.py 中execute_analysis_background方法的开头这是异步分析任务的统一入口。3.1 核心代码async def execute_analysis_background( self, task_id: str, user_id: str, request: SingleAnalysisRequest ): 在后台执行分析任务 progress_tracker None try: logger.info(f 开始后台执行分析任务: {task_id}) # 验证股票代码是否存在 logger.info(f 开始验证股票代码: {request.stock_code}) from tradingagents.utils.stock_validator import prepare_stock_data # 获取市场类型 market_type request.parameters.market_type if request.parameters else A股 # 获取分析日期并转换为字符串格式 analysis_date request.parameters.analysis_date if request.parameters else None if analysis_date: # 如果是 datetime 对象转换为字符串 if isinstance(analysis_date, datetime): analysis_date analysis_date.strftime(%Y-%m-%d) # 如果是字符串确保格式正确 elif isinstance(analysis_date, str): try: parsed_date datetime.strptime(analysis_date, %Y-%m-%d) analysis_date parsed_date.strftime(%Y-%m-%d) except ValueError: analysis_date datetime.now().strftime(%Y-%m-%d) # 验证股票代码并预获取数据 validation_result await asyncio.to_thread( prepare_stock_data, stock_coderequest.stock_code, market_typemarket_type, period_days30, analysis_dateanalysis_date ) if not validation_result.is_valid: error_msg f❌ 股票代码验证失败: {validation_result.error_message} logger.error(error_msg) logger.error(f 建议: {validation_result.suggestion}) # 更新任务状态为失败 await self.memory_manager.update_task_status( task_idtask_id, statusAnalysisStatus.FAILED, progress0, error_messagevalidation_result.error_message ) # 更新MongoDB状态 await self._update_task_status( task_id, AnalysisStatus.FAILED, 0, error_messagevalidation_result.error_message ) return logger.info(f✅ 股票代码验证通过: {request.stock_code} - {validation_result.stock_name}) logger.info(f 市场类型: {validation_result.market_type}) logger.info(f 历史数据: {有 if validation_result.has_historical_data else 无}) logger.info(f 基本信息: {有 if validation_result.has_basic_info else 无}) # ... 继续执行分析 ...3.2 与文档版本的差异异步版本适配仓库中的实际实现已从文档中的同步版本演进为异步版本当前 simple_analysis_service.py 导入的是prepare_stock_data_async并直接await同时通过request.get_symbol()兼容symbol与stock_code两种字段。这样避免了在 FastAPI 异步事件循环中通过asyncio.to_thread触发attached to a different loop的事件循环冲突。# 使用异步版本直接 await避免事件循环冲突 validation_result await prepare_stock_data_async( stock_codestock_code, market_typemarket_type, period_days30, analysis_dateanalysis_date )失败时错误信息会被包装为面向用户的友好提示后再写入任务状态user_friendly_error ( f❌ 股票代码无效\n\n f{validation_result.error_message}\n\n f {validation_result.suggestion} )随后分别更新内存任务状态memory_manager.update_task_status与 MongoDB 持久化状态_update_task_status并立即return终止任务。4. 核心实现tradingagents/utils/stock_validator.py的验证与预取数验证的底层能力全部封装在 tradingagents/utils/stock_validator.py 中核心类是StockDataPreparer返回结果对象StockDataPreparationResult并保留StockValidationResult别名以向后兼容。4.1 结果对象结构StockDataPreparationResult通过is_valid布尔值标记验证结果同时携带错误消息与用户建议字段类型含义is_validbool验证是否通过stock_codestr股票代码港股为规范化后的0700.HK格式market_typestr市场类型A股 / 港股 / 美股stock_namestr解析出的股票名称error_messagestr错误描述suggestionstr面向用户的修复建议has_historical_databool历史数据是否获取成功has_basic_infobool基本信息是否获取成功data_period_daysint实际数据天数cache_statusstr缓存状态描述4.2 模块级便捷函数模块底部提供了多个可直接调用的便捷入口单例模式get_stock_preparer持有全局实例prepare_stock_data(stock_code, market_type, period_days, analysis_date)同步验证入口prepare_stock_data_async(...)异步验证入口内部调用_prepare_data_by_market_asyncA股走异步数据准备港股/美股复用同步实现is_stock_data_ready(...)仅返回布尔值判断数据是否就绪get_stock_preparation_message(...)返回可读的验证结果消息。同时保留了StockValidator、get_stock_validator、validate_stock_exists、is_stock_valid等别名保证历史调用方不受影响。4.3 统一验证流水线prepare_stock_data的执行顺序为基本格式验证_validate_format空代码、长度超过 10 字符、各市场正则校验自动检测市场类型_detect_market_type当market_typeauto时按 6 位数字 → A股、4-5 位数字或数字.HK→ 港股、1-5 位字母 → 美股 的顺序自动识别按市场预获取数据并验证_prepare_data_by_market分派到 A股 / 港股 / 美股三个具体实现。异常兜底逻辑同样完善数据准备过程中的任何异常都会被捕获并转换为is_validFalse的结果提示请检查网络连接或数据源配置。5. 多市场格式验证规则详解5.1 A股6 位数字 前缀白名单# 必须是6位数字 if not re.match(r^\d{6}$, stock_code): return error(A股代码格式错误应为6位数字) # 验证前缀 prefix stock_code[:2] valid_prefixes [60, 68, 00, 30, 43, 83, 87] if prefix not in valid_prefixes: return error(A股代码前缀不正确)支持的前缀与板块对应关系为60xxxx上海主板、68xxxx科创板、00xxxx深圳主板、30xxxx创业板、43/83/87xxxx北交所。5.2 港股4-5 位数字支持.HK后缀# 4-5位数字.HK 或 纯4-5位数字 hk_format re.match(r^\d{4,5}\.HK$, stock_code.upper()) digit_format re.match(r^\d{4,5}$, stock_code) if not (hk_format or digit_format): return error(港股代码格式错误)5.3 美股1-5 位大写字母# 1-5位字母 if not re.match(r^[A-Z]{1,5}$, stock_code.upper()): return error(美股代码格式错误应为1-5位字母)5.4 通用防御在进入市场分支前_validate_format还会先剔除首尾空白并做两项全局检查if not stock_code: return error(股票代码不能为空, 请输入有效的股票代码) if len(stock_code) 10: return error(股票代码长度不能超过10个字符, 请检查股票代码格式)6. 港股代码规范化修复00700 → 0700.HK这是本方案最关键的细节修复。旧代码在 stock_validator.py 的_prepare_hk_stock_data中使用# ❌ 旧代码 formatted_code f{stock_code.zfill(4)}.HK # 输入: 00700 # 输出: 00700.HK ← 错误应该是 0700.HK修复后的逻辑为先移除前导 0再补齐到 4 位避免前导 0 撑满宽度导致代码变形# ✅ 新代码 # 移除前导0然后补齐到4位 clean_code stock_code.lstrip(0) or 0 # 如果全是0保留一个0 formatted_code f{clean_code.zfill(4)}.HK logger.debug(f [港股数据] 代码格式化: {stock_code} → {formatted_code}) # 输入: 00700 # 处理: 00700 → 700 → 0700 # 输出: 0700.HK ← 正确当输入已带.HK后缀时仅做大小写归一化.upper()不再重复拼接。格式化示例输入处理步骤输出700700→07000700.HK✅0070000700→700→07000700.HK✅99889988→99889988.HK✅0998809988→9988→99889988.HK✅18101810→18101810.HK✅0181001810→1810→18101810.HK✅7. 数据预获取验证三层校验格式验证通过后StockDataPreparer还会通过真实数据源做存在性验证确保代码不是格式合法但股票不存在。7.1 A股验证流程# 1. 获取基本信息 stock_info get_stock_info_unified(stock_code) if not stock_info or ❌ in stock_info: return error(无法获取股票基本信息) # 2. 验证股票名称 stock_name extract_stock_name(stock_info) if stock_name 未知 or stock_name.startswith(f股票{stock_code}): return error(f股票代码 {stock_code} 不存在或信息无效) # 3. 获取历史数据 historical_data get_stock_data_unified(stock_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取股票历史数据) # 4. 验证数据有效性 if len(historical_data) 100: return error(历史数据不足)7.2 港股验证流程# 1. 格式化代码 formatted_code format_hk_code(stock_code) # 00700 → 0700.HK # 2. 获取基本信息 stock_info get_hk_stock_info_unified(formatted_code) if not stock_info or ❌ in stock_info or 未找到 in stock_info: return error(f港股代码 {formatted_code} 不存在或信息无效) # 3. 解析股票名称 stock_name extract_hk_stock_name(stock_info, formatted_code) if not stock_name or stock_name 未知: return error(f港股代码 {formatted_code} 不存在或信息无效) # 4. 获取历史数据 historical_data get_hk_stock_data_unified(formatted_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取港股历史数据)7.3 美股验证流程# 1. 格式化代码转大写 formatted_code stock_code.upper() # 2. 获取基本信息 stock_info get_us_stock_info_unified(formatted_code) if not stock_info or ❌ in stock_info: return error(f美股代码 {formatted_code} 不存在或信息无效) # 3. 获取历史数据 historical_data get_us_stock_data_unified(formatted_code, start_date, end_date) if not historical_data or ❌ in historical_data: return error(无法获取美股历史数据)7.4 仓库实现细节三层验证的实际差异对照仓库源码可以发现三个市场的实际实现比文档示例更细A股_prepare_china_stock_data在_validate_format之后会先通过_check_database_data检查 MongoDB 缓存中是否有最新数据若缺失或过期则调用_trigger_data_sync_sync同步包装器自动触发历史数据、财务数据、实时行情三条链路的同步再按配置的数据源优先级tushare/akshare依次尝试。股票名称通过get_china_stock_info_unified返回文本中的股票名称:字段解析。港股_prepare_hk_stock_data名称解析走_extract_hk_stock_name支持字典字段name/longName/shortName/companyName/公司名称/股票名称、公司名称:文本格式、Yahoo Finance 日志格式及公司名关键词Limited/Ltd/Holdings/集团/控股/有限公司等多种识别路径。此外专门针对港股 API 的限流特征Too Many Requests、Rate limited、Connection aborted、网络连接、超时、限制做了网络限制误判识别并返回包含等待 5-10 分钟后重试等步骤的详细建议_get_hk_network_limitation_suggestion。美股_prepare_us_stock_data不单独获取基本信息而是直接通过历史数据验证股票是否存在OptimizedUSDataProvider.get_stock_data失败时回退到get_us_stock_data_cached因为美股代码通常可直接作为股票名称。三个市场的历史数据有效性判定采用统一策略内容长度大于 50 且包含开盘价/收盘价/最高价/最低价/成交量或 open/close/high/low/volume等行情字段。8. 错误处理与用户提示8.1 验证失败的处理流程if not validation_result.is_valid: # 1. 记录错误日志 logger.error(f❌ 股票代码验证失败: {validation_result.error_message}) logger.error(f 建议: {validation_result.suggestion}) # 2. 更新内存中的任务状态 await self.memory_manager.update_task_status( task_idtask_id, statusAnalysisStatus.FAILED, progress0, error_messagevalidation_result.error_message ) # 3. 更新MongoDB中的任务状态 await self._update_task_status( task_id, AnalysisStatus.FAILED, 0, error_messagevalidation_result.error_message ) # 4. 立即返回不执行分析 return8.2 错误信息示例验证失败时返回结构化的结果对象便于前端与日志系统直接使用{ is_valid: false, stock_code: 000999, market_type: A股, error_message: 股票代码 000999 不存在或信息无效, suggestion: 请检查股票代码是否正确或确认该股票是否已上市 }{ is_valid: false, stock_code: 0700.HK, market_type: 港股, error_message: 港股代码 0700.HK 不存在或信息无效, suggestion: 请检查港股代码是否正确格式如0700.HK }{ is_valid: false, stock_code: ABCD, market_type: 美股, error_message: 美股代码 ABCD 不存在或无法获取数据, suggestion: 请检查美股代码是否正确如AAPL、MSFT }9. 测试用例覆盖三市场的通过/失败矩阵A股测试股票代码预期结果说明000001✅ 通过平安银行存在600519✅ 通过贵州茅台存在000999❌ 失败不存在的代码999999❌ 失败不存在的代码00001❌ 失败格式错误5位港股测试重点验证规范化输入代码格式化后预期结果说明7000700.HK✅ 通过腾讯控股存在007000700.HK✅ 通过腾讯控股存在99889988.HK✅ 通过阿里巴巴存在099889988.HK✅ 通过阿里巴巴存在9999999999.HK❌ 失败不存在的代码0700.HK0700.HK✅ 通过腾讯控股存在美股测试股票代码预期结果说明AAPL✅ 通过苹果存在MSFT✅ 通过微软存在GOOGL✅ 通过谷歌存在ABCDE❌ 失败不存在的代码ZZZZZ❌ 失败不存在的代码仓库 scripts/test_stock_data_preparation.py、scripts/test_data_preparation.py 与 scripts/test_hk_error_handling.py 提供了针对数据预取与港股错误处理的验证脚本可直接运行以复现上述行为。10. 性能优化缓存复用与超时控制10.1 数据缓存验证阶段获取的数据会被 Redis 缓存分析阶段直接复用避免重复拉取# 1. 基本信息缓存 stock_info get_stock_info_unified(stock_code) # 会缓存到Redis # 2. 历史数据缓存 historical_data get_stock_data_unified(stock_code, start_date, end_date) # 会缓存到Redis # 3. 分析时直接使用缓存 # 不需要重新获取数据提高分析速度对 A股而言缓存链路还延伸到 MongoDB_check_database_data会查询数据库中已有历史数据及其最新日期允许 1 天延迟命中则跳过同步未命中则自动触发同步同步结果同样写入缓存。cache_status字段会记录数据库数据最新 / 基本信息已缓存 / 历史数据已缓存(N天) / 数据已同步等实际状态供日志审计。10.2 超时控制self.timeout_seconds 15 # 数据获取超时时间 # 如果15秒内无法获取数据返回验证失败timeout_seconds是StockDataPreparer的实例属性默认为 15 秒防止外部数据源响应缓慢拖垮整个验证流程。11. 复用范围CLI 与 Web 调用链中的统一验证验证模块并非只服务于 FastAPI 后台任务而是被三条调用链共享形成一次实现、处处验证的效果FastAPI 异步任务execute_analysis_background使用prepare_stock_data_asyncapp/services/simple_analysis_service.pyCLI 交互式分析cli/main.py 在数据验证阶段调用同步prepare_stock_data先根据代码形态推断市场类型6 位数字 → A股、含.HK→ 港股、否则 → 美股验证失败时直接打印错误与建议并终止Web 工具调用web/utils/analysis_runner.py 在进度回调第一步即执行prepare_stock_data失败时返回带suggestion的结构化结果供上层 UI 展示。这三处调用统一以period_days30作为默认历史数据时长与StockDataPreparer(default_period_days30)的默认值保持一致。对于 A股实际数据回溯天数会进一步受 app/core/config.py 中MARKET_ANALYST_LOOKBACK_DAYS默认 365配置控制。12. 总结与后续优化方向修复前后对比用户输入: 00700 ↓ 后端接收: 00700 ↓ 开始分析没有验证 ↓ 分析过程中发现数据获取失败 ↓ 浪费时间和资源 ❌用户输入: 00700 ↓ 后端接收: 00700 ↓ 验证股票代码 ├─ 格式验证: ✅ 通过4-5位数字 ├─ 格式化: 00700 → 0700.HK ├─ 获取基本信息: ✅ 成功腾讯控股 └─ 获取历史数据: ✅ 成功 ↓ 验证通过开始分析 ✅方案优点✅提前验证在分析开始前验证股票代码无效代码零成本拦截✅快速失败无效代码立即返回错误不浪费 LLM 调用与网络资源✅清晰提示提供结构化的错误信息与可执行建议✅数据缓存验证时获取的数据可在分析时复用降低重复请求✅格式标准化自动修正港股代码格式含前导 0 处理✅三端统一FastAPI 后台、CLI、Web 工具共用同一验证模块。后续优化方向添加股票代码白名单/黑名单机制支持批量验证提升多标的场景下的效率添加验证结果缓存避免同一股票的重复验证支持更多市场新加坡、日本等的代码格式与数据源接入。延伸阅读前端侧的格式预校验实现可参考 docs/integration/data-sources/stock_code_validation.mdfrontend/src/utils/stockValidator.ts与 frontend/src/views/Analysis/SingleAnalysis.vue后端与前端共同构成前端即时提示 后端兜底强校验的双层防线。【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
与ICC(C)承保差异、条款写法与理赔实操清单)
