TradingAgents-CN 报告导出功能详解Markdown / Word / PDF 多格式输出的架构、配置与实战【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN导读本文围绕 TradingAgents-CN 内置的多智能体分析报告导出体系展开系统讲解其支持的 Markdown、Word.docx、PDF 三种导出格式的适用场景、Web 界面与命令行两种使用方式、报告内容结构与技术实现原理并结合仓库源码深入剖析 Pandoc / pdfkit / python-docx 等工具链的调用链、Docker 环境预置依赖、YAML 冲突防护与 PDF 引擎降级策略帮助读者在本地或 Docker 环境中快速启用并排障导出功能。一、功能概述与支持格式TradingAgents-CN 在 v0.1.7 起引入了专业级报告导出能力详见 版本发布说明允许把多智能体分析师、研究员、交易员、风险经理协作生成的分析结果一键导出为多种专业格式方便保存、分享与二次加工。格式扩展名用途特点适用场景Markdown.md在线查看、版本控制、技术文档轻量级、可编辑、Git 友好技术团队内部分享、在线文档平台、进一步编辑加工Word.docx商业报告、正式文档、打印输出专业格式、易于编辑、广泛兼容投资报告、客户交付、团队协作编辑、演示汇报PDF.pdf正式发布、打印、长期保存格式固定、跨平台一致、专业外观正式发布、监管提交、打印存档、客户演示JSON.json程序处理、数据交换保留完整原始数据二次开发、数据归档、接口对接说明原文档主要介绍 Markdown / Word / PDF 三种格式而 app/routers/reports.py 中的下载接口同时支持json格式用于输出包含完整字段的原始数据方便程序化处理。二、使用方法Web 界面与命令行2.1 Web 界面导出流程完成股票分析在 Web 界面输入股票代码如000001、AAPL选择分析深度与 LLM 模型配置等待多智能体分析完成。选择导出格式在分析结果页面底部找到报告导出区域勾选目标格式 导出 Markdown 导出 Word 导出 PDF下载文件系统自动生成文件并触发浏览器下载文件名格式为{股票代码}_analysis_{时间戳}.{格式}。在后端架构中前端通过带认证的 API 请求触发下载见 frontend/src/views/Reports/index.vuedownloadReport调用/api/reports/{report_id}/download?format{format}携带 Bearer Token接收 Blob 后按格式扩展名保存本地文件。Web 端旧版Streamlit 实现通过 web/utils/report_exporter.py 中的render_export_buttons渲染三个导出按钮并同步执行分模块报告保存与汇总报告生成。2.2 命令行导出原文档给出的 CLI 导出命令python main.py --symbol 000001 --export-format word,pdf格式选择建议批量分析场景优先使用 CLI 模式日常查看用 Markdown商业报告用 Word正式发布用 PDF。2.3 REST API 下载接口当前 FastAPI 后端提供统一的报告下载端点见 app/routers/reports.pyGET /api/reports/{report_id}/download?format{format}report_id报告 ID支持 ObjectId / analysis_id / task_id 三种标识_build_report_query统一构建查询条件formatmarkdown默认、json、docx、pdf。示例# 下载 Markdown curl -H Authorization: Bearer $TOKEN \ http://localhost:8000/api/reports/abc123/download?formatmarkdown -o report.md # 下载 Word curl -H Authorization: Bearer $TOKEN \ http://localhost:8000/api/reports/abc123/download?formatdocx -o report.docx # 下载 PDF curl -H Authorization: Bearer $TOKEN \ http://localhost:8000/api/reports/abc123/download?formatpdf -o report.pdf接口内部逻辑json直接序列化 MongoDB 中的完整报告文档media_typeapplication/jsonmarkdown由reports字段的各模块内容拼装为# {stock_symbol} 分析报告结构docx/pdf调用 app/utils/report_exporter.py 中的report_exporter全局实例生成若 Pandoc 不可用则返回 400 提示安装依赖。三、报告内容结构标准导出的分析报告包含以下章节对应导出器在 app/utils/report_exporter.py 中定义的module_order与module_titles 股票基本信息股票代码与名称、当前价格与涨跌幅、市场板块信息、分析时间戳。 投资决策摘要投资建议买入/卖出/持有、置信度评分、风险评分、目标价位。 详细分析报告市场技术分析、基本面分析、情绪分析如启用、新闻分析如启用。 专家辩论记录看涨/看跌分析师观点、辩论过程记录、研究经理综合决策。⚠️ 风险提示市场风险警告、投资建议免责声明、数据来源说明。 技术信息使用的 LLM 模型、分析师配置、数据源信息、生成时间。Web 端导出器在此基础上扩展了多智能体团队决策章节见 web/utils/report_exporter.py研究团队决策多头/空头研究员分析、研究经理综合决策交易团队计划专业交易员制定的具体交易执行计划风险管理团队决策激进/保守/中性分析师评估、投资组合经理最终决策最终交易决策综合所有团队分析后的最终投资结论。这些章节与 TradingAgents 多智能体辩论框架一一对应确保导出报告完整保留各智能体的推理过程。四、技术实现与源码级原理4.1 导出引擎与依赖组件职责依赖包Pandoc通用文档转换核心pypandoc1.11markdownMarkdown → HTMLPDF 路径markdown3.4.0python-docxWord 文档后处理修复文本方向python-docx0.8.11pdfkit wkhtmltopdfHTML → PDF 渲染pdfkit1.0.0 系统工具依赖版本约束见 pyproject.toml。启动时 app/utils/report_exporter.py 会进行三项探测并记录日志EXPORT_AVAILABLEmarkdown、pypandoc是否可导入PANDOC_AVAILABLEpypandoc.get_pandoc_version()是否成功失败则 Word/PDF 不可用仅保留 MarkdownPDFKIT_AVAILABLEpdfkit.configuration()是否成功失败则 PDF 不可用。4.2 Word 导出实现generate_docx_reportapp/utils/report_exporter.py的关键链路extra_args [ --frommarkdown-yaml_metadata_block, # 禁用 YAML 元数据块解析 --standalone, # 生成独立文档 --wrappreserve, # 保留换行 --columns120, # 设置列宽 -M, langzh-CN, # 明确简体中文语言 -M, dirltr, # 明确从左到右文本方向 ] pypandoc.convert_text(cleaned_content, docx, formatmarkdown, outputfileoutput_file, extra_argsextra_args)转换完成后还会用python-docx做文本方向后处理遍历所有段落与表格单元格移除可能存在的textDirection/bidi属性防止中文文档出现竖排问题。4.3 PDF 导出实现PDF 生成分两条路径后端 FastAPI 路径app/utils/report_exporter.py以 pdfkit wkhtmltopdf 为主——generate_markdown_report生成 Markdown_markdown_to_html使用tables、fenced_code、nl2br扩展转为 HTML并注入完整 CSS 模板A4 页面、20mm 页边距、表头跨页重复display: table-header-group、page-break-inside: avoid、writing-mode: horizontal-tb !important强制横排_generate_pdf_with_pdfkit以 UTF-8 编码渲染 PDF。Web/CLI 路径web/utils/report_exporter.py使用 pypandoc 的多引擎降级策略按[wkhtmltopdf, weasyprint, None(默认)]顺序尝试pdf_engines [ (wkhtmltopdf, HTML转PDF引擎推荐安装), (weasyprint, 现代HTML转PDF引擎), (None, 使用pandoc默认引擎) ]每个引擎失败后自动清理临时文件并尝试下一个全部失败时抛出包含安装指引的错误信息Windowschoco install wkhtmltopdf/ macOSbrew install wkhtmltopdf/ Linuxapt-get install wkhtmltopdf以及 LaTeX 备选方案。4.4 错误处理与降级机制YAML 解析保护Pandoc 默认会把开头形似---的内容当作 YAML 元数据块解析导致转换异常。仓库采用双重防护转换参数层面强制--frommarkdown-yaml_metadata_block禁用 YAML 解析app/utils/report_exporter.py内容清理层面_clean_markdown_for_pandoc将---替换为—、...替换为…同时先用|TABLESEP|占位符保护 Markdown 表格分隔线清理完成后再恢复web/utils/report_exporter.py。HTML 标签清理正则移除writing-mode/text-orientation相关样式、style块及div/span中的内联 style规避中文竖排渲染问题app/utils/report_exporter.py。PDF 引擎降级engines [wkhtmltopdf, weasyprint, default]顺序降级见上文。Docker 适配Web 端通过docker_pdf_adapter检测容器环境并调用setup_xvfb_display()配置虚拟显示wkhtmltopdf 在无头环境需要 Xvfb详见 web/utils/report_exporter.py。4.5 测试验证仓库提供了独立的转换验证脚本 tests/test_conversion.py无需重新跑分析即可测试导出链路生成模拟分析结果的 Markdown 内容含投资决策摘要、技术/基本面分析、风险提示等真实结构依次测试三种 Word 转换参数基础转换、带目录--toc --number-sections、禁用 YAML 转换依次测试三种 PDF 引擎wkhtmltopdf / weasyprint / 默认验证文件生成且非空。可在 Docker 中直接执行docker exec TradingAgents-web python test_conversion.py。五、环境变量与高级配置5.1 基础配置.env# .env 文件配置 EXPORT_ENABLEDtrue # 启用导出功能 EXPORT_DEFAULT_FORMATword,pdf # 默认导出格式 EXPORT_INCLUDE_DEBUGfalse # 是否包含调试信息 EXPORT_WATERMARKfalse # 是否添加水印 EXPORT_OUTPUT_PATH./exports # 导出文件输出目录 EXPORT_FILENAME_FORMAT{symbol}_analysis_{timestamp} # 文件名模板5.2 高级配置# 格式转换配置 PANDOC_PATH/usr/bin/pandoc # pandoc 可执行文件路径 WKHTMLTOPDF_PATH/usr/bin/wkhtmltopdf # wkhtmltopdf 可执行文件路径 # 质量配置 EXPORT_COMPRESS_PDFtrue # 压缩 PDF 输出 EXPORT_OPTIMIZE_IMAGEStrue # 优化图片体积 # Word 导出配置 WORD_TEMPLATE_PATH./templates/report_template.docx # 自定义 Word 模板 WORD_REFERENCE_DOC./templates/reference.docx # pandoc 参考文档 # PDF 导出配置 PDF_PAGE_SIZEA4 # 页面尺寸 PDF_MARGIN_TOP2cm # 上边距 PDF_MARGIN_BOTTOM2cm # 下边距 PDF_MARGIN_LEFT2cm # 左边距 PDF_MARGIN_RIGHT2cm # 右边距 # 性能配置 EXPORT_PARALLELtrue # 并行导出 EXPORT_MAX_WORKERS3 # 最大并行数 EXPORT_CACHE_ENABLEDtrue # 启用缓存 EXPORT_CACHE_TTL3600 # 缓存有效期秒5.3 Web 界面配置导出格式选择用户可选择单个或多个格式文件命名自动生成带时间戳的文件名前端下载文件名形如${stock_code}_分析报告_${analysis_date}.${ext}下载管理自动触发浏览器下载Blob URL a.download触发。六、Docker 环境优化Dockerfile.backend 已预装导出功能全部依赖支持 amd64 / arm64 双架构# 系统级依赖 apt-get install -y --no-install-recommends \ ca-certificates curl fontconfig fonts-noto-cjk wget xvfb # 按架构下载安装 pandoc 3.8.2.1避免 Debian 仓库版本问题 wget -q https://github.com/jgm/pandoc/releases/download/3.8.2.1/pandoc-3.8.2.1-1-${PANDOC_ARCH}.deb \ dpkg -i pandoc-3.8.2.1-1-${PANDOC_ARCH}.deb # 下载安装 wkhtmltopdf 0.12.6.1-3PDF 生成引擎 wget -q https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_${WKHTMLTOPDF_ARCH}.deb # 更新字体缓存中文字体支持 fc-cache -fvPython 侧额外安装pdfkit。构建部署后可通过以下命令验证依赖# 检查 pandoc 版本 docker exec -it tradingagents-backend pandoc --version # 检查 wkhtmltopdf 版本 docker exec -it tradingagents-backend wkhtmltopdf --version # 检查中文字体 docker exec -it tradingagents-backend fc-list :langzh # 预期输出包含 fonts-noto-cjk 提供的字体如 WenQuanYi 或 Noto Sans CJK文件存储方面Web 导出使用临时文件、下载后自动清理CLI 导出保存到./exports/目录Docker 环境可通过 Volume 映射到主机目录持久化。七、故障排除7.1 常见问题对照表问题错误信息解决方案Word 导出失败YAML parse exception系统已通过--frommarkdown-yaml_metadata_block与字符清理自动修复重试即可Word 导出失败Pandoc 不可用Docker 环境预装本地需apt install pandoc/brew install pandoc/ 下载安装包PDF 生成失败wkhtmltopdf not foundDocker 已预装本地安装 wkhtmltopdf 或改用 weasyprint / MarkdownPDF 生成失败PDF 引擎不可用检查wkhtmltopdf --version缺失则重新构建镜像中文显示问题中文字符显示为方块/乱码Docker 已配置fonts-noto-cjk本地安装中文字体如fonts-wqy-zenhei后执行fc-cache -fv导出按钮不显示—检查EXPORT_ENABLEDtrue并重启应用文件下载失败浏览器阻止下载检查浏览器下载设置与exports/目录写权限7.2 调试方法# 查看实时日志 docker logs TradingAgents-web --follow # 测试文档转换功能无需重新分析 docker exec TradingAgents-web python test_conversion.py # 检查依赖 docker exec TradingAgents-web pandoc --version docker exec TradingAgents-web wkhtmltopdf --version后端日志路径docker exec tradingagents-backend cat /app/logs/tradingagents.log。7.3 性能参考格式文件大小生成时间说明Markdown~50KB100ms最快无转换开销JSON~100KB100ms直接序列化Word~200KB~2s中等Pandoc 转换PDF~300KB~5s较慢需要完整渲染以上数据来源于 docs/docker-report-export.md 中 2 核 4G 内存测试环境的记录实际表现随报告篇幅与机器性能波动。性能优化建议大批量导出使用 CLI 模式、避免同时导出多种格式、定期清理导出文件、大型报告优先用 Word 而非 PDF。八、最佳实践格式选择日常使用 Markdown轻量、可编辑、Git 友好商业报告用 Word专业、可编辑正式发布用 PDF格式固定、专业外观。文件命名规范推荐{股票代码}_{分析类型}_{日期}.{格式}如000001_comprehensive_20250713.pdf、AAPL_technical_20250713.docx。存储管理# 清理 30 天前的旧文件 find exports/ -name *.pdf -mtime 30 -delete find exports/ -name *.docx -mtime 30 -delete # 按月压缩归档 tar -czf exports_archive_$(date %Y%m).tar.gz exports/质量保证导出前检查分析结果完整性、验证关键数据价格、建议、置信度、确认时间戳与股票代码正确导出后验证文件生成成功、大小合理、中文显示正常。九、相关文件索引app/utils/report_exporter.py后端报告导出核心实现Markdown 组装、Word/PDF 生成、YAML 防护、PDF 样式web/utils/report_exporter.pyWeb/CLI 端导出器与导出按钮渲染、Docker PDF 适配app/routers/reports.py报告列表 / 详情 / 下载 REST APItests/test_conversion.py文档转换独立测试脚本Dockerfile.backendDocker 镜像依赖预装pandoc / wkhtmltopdf / 中文字体pyproject.toml导出相关 Python 依赖版本约束docs/guides/report-export-guide.md导出功能详细使用指南含批量导出与定时任务docs/docker-report-export.mdDocker 环境导出配置与排障说明报告导出功能由社区贡献者baiyuxiong设计并实现包括多格式导出系统架构设计、Pandoc 集成与格式转换实现、Word/PDF 导出开发、错误处理与降级策略设计及完整测试验证流程原文档记录于 2025-07-13版本 cn-0.1.7。【免费下载链接】TradingAgents-CN基于多智能体LLM的中文金融交易框架 - TradingAgents中文增强版项目地址: https://gitcode.com/GitHub_Trending/tr/TradingAgents-CN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考