一、升级概览
2025 年 11 月 1 日至 4 日，TradingAgents-CN 完成了一次重要的 跨平台部署 和 基本面分析功能增强 工作。
本次更新通过 22 个提交，实现了 Windows 绿色版便携打包、Windows 安装器、基本面分析总市值数据补充、端口冲突自动检测、LLM 配置热更新、多平台打包支持 等关键功能。
这些改进显著降低了系统使用门槛，也提升了 跨平台兼容性、数据完整性和用户部署体验。
核心改进
- Windows 绿色版打包：一键启动，无需安装，开箱即用。
- Windows 安装器：提供标准化安装流程，支持快捷方式和卸载。
- 基本面分析增强：添加 总市值数据，完善估值指标体系。
- 端口冲突检测：自动检测并清理占用端口的进程。
- LLM 配置优化：修复 API Key 更新后不生效 的问题。
- 多平台打包支持：支持 Windows、Linux、macOS、ARM 等多平台。
- 数据说明文档完善：补充基本面分析数据结构说明和快速参考。
二、Windows 绿色版便携打包
2.1 问题背景
相关提交：
97201de：添加 Windows 绿色版便携打包 支持。d67167c：打包优化，支持多平台打包。e0ce2bf：排除部分调试目录。928e108：更新.gitignore，排除构建产物和临时文件。
许多 Windows 用户希望有一个 免安装、开箱即用 的版本，避免手动安装 Python、MongoDB、Redis 等依赖。
此前存在几个痛点：
- 安装复杂：需要安装 Python、MongoDB、Redis，并配置环境变量。
- 环境污染：依赖安装到系统目录，卸载不干净。
- 便携性差：无法放在 U 盘运行，也不方便迁移到其他电脑。
- 多版本共存困难：不同版本之间容易互相影响。
2.2 解决方案
本次新增 Windows 绿色版打包脚本，用于自动打包完整运行环境。
# scripts/package_windows_portable.py
class WindowsPortablePackager:
def package(self):
"""执行打包流程"""
self._create_directory_structure()
self._package_python_runtime()
self._package_dependencies()
self._package_mongodb()
self._package_redis()
self._package_application()
self._package_frontend()
self._create_startup_scripts()
self._generate_config_files()
self._create_zip_archive()打包内容包括：
- Python 嵌入式运行时
- MongoDB 便携版
- Redis 便携版
- 后端应用代码
- 前端构建产物
- 启动脚本
- 停止脚本
- 默认配置文件
- 日志与数据目录
2.3 启动脚本
绿色版会生成 start.bat，用于一键启动所有服务。
启动流程包括：
- 检查端口占用。
- 启动 MongoDB。
- 启动 Redis。
- 启动后端 FastAPI。
- 启动前端服务。
- 自动打开浏览器访问系统。
同时生成 stop.bat，用于停止 Python、MongoDB、Redis 等进程。
2.4 .gitignore 优化
为了避免构建产物和运行时数据进入仓库，本次同步优化了 .gitignore。
# 构建产物
dist/
build/
*.egg-info/
# 运行时数据
runtime/
data/mongodb/
data/redis/
# 调试目录
__pycache__/
*.pyc
.pytest_cache/
.coverage
# 临时文件
*.tmp
*.log
*.pid2.5 实现效果
- 一键启动，无需安装。
- 所有依赖打包在一起。
- 支持 U 盘运行。
- 多版本可以共存。
- 卸载只需删除文件夹。
- 更适合普通 Windows 用户快速体验。
三、Windows 安装器
3.1 问题背景
相关提交：
6c841fa：添加 Windows 安装器脚本。
除了绿色版，部分用户也希望有标准安装程序，提供更接近桌面软件的使用体验。
典型需求包括：
- 标准安装向导。
- 注册到系统程序列表。
- 支持完整卸载。
- 创建桌面快捷方式。
- 添加到开始菜单。
- 后续支持开机自启和系统集成。
3.2 NSIS 安装脚本
本次新增基于 NSIS 的 Windows 安装器脚本。
Name "TradingAgents-CN"
OutFile "TradingAgents-CN-Setup.exe"
InstallDir "$PROGRAMFILES64\TradingAgents-CN"
RequestExecutionLevel admin安装器会完成：
- 复制绿色版文件到安装目录。
- 创建开始菜单快捷方式。
- 创建桌面快捷方式。
- 写入卸载程序。
- 注册到 Windows 程序列表。
卸载时会：
- 执行停止服务脚本。
- 删除安装目录。
- 删除桌面和开始菜单快捷方式。
- 清理注册表卸载信息。
3.3 安装器构建脚本
新增 scripts/build_installer.py，用于自动构建安装包。
def build_installer():
"""构建 Windows 安装器"""
nsis_path = Path(r"C:\Program Files (x86)\NSIS\makensis.exe")
if not nsis_path.exists():
print("未找到 NSIS，请先安装 NSIS")
sys.exit(1)
portable_dir = Path("dist/windows-portable")
if not portable_dir.exists():
print("未找到便携版，请先运行 package_windows_portable.py")
sys.exit(1)
subprocess.run([str(nsis_path), "scripts/windows_installer.nsi"])3.4 实现效果
- 提供标准 Windows 安装程序。
- 自动创建快捷方式。
- 注册到系统程序列表。
- 支持完整卸载。
- 用户体验更加专业。
四、基本面分析总市值数据补充
4.1 问题背景
相关提交：
564b1d6：在 基本面分析 中添加总市值数据。39205bc：添加combined_data日志，提升调试可见性。e67d839：补充基本面数据说明。
此前基本面分析报告中缺少 总市值 这一关键估值指标。
这会带来几个问题：
- 估值分析不完整，只包含 PE、PB、PS 等相对估值指标。
- 缺少绝对估值指标，无法判断公司规模。
- LLM 无法基于市值判断大盘股、中盘股或小盘股。
- 提交给大模型的数据不够透明，调试困难。
4.2 总市值数据获取策略
系统新增多层降级策略，优先从实时指标中获取总市值。
# 从 realtime_metrics 提取总市值
if realtime_metrics:
market_cap = realtime_metrics.get('market_cap')
if market_cap is not None and market_cap > 0:
is_realtime = realtime_metrics.get('is_realtime', False)
realtime_tag = " (实时)" if is_realtime else ""
metrics["total_mv"] = f"{market_cap:.2f}亿元{realtime_tag}"如果实时数据不可用，则从 stock_basic_info 获取。
if "total_mv" not in metrics:
total_mv_static = latest_indicators.get('total_mv')
if total_mv_static is not None and total_mv_static > 0:
metrics["total_mv"] = f"{total_mv_static:.2f}亿元"如果仍不可用，则从 money_cap 换算。
money_cap = latest_indicators.get('money_cap')
if money_cap is not None and money_cap > 0:
total_mv_yi = money_cap / 10000
metrics["total_mv"] = f"{total_mv_yi:.2f}亿元"4.3 报告模板补充总市值
基本面报告模板中新增 总市值 字段。
report_basic = f"""
## 核心财务指标
- **总市值**: {financial_estimates.get('total_mv','N/A')}
- **市盈率(PE)**: {financial_estimates.get('pe','N/A')}
- **市盈率TTM(PE_TTM)**: {financial_estimates.get('pe_ttm','N/A')}
- **市净率(PB)**: {financial_estimates.get('pb','N/A')}
- **净资产收益率(ROE)**: {financial_estimates.get('roe','N/A')}
- **资产负债率**: {financial_estimates.get('debt_ratio','N/A')}
"""标准版和详细版报告中，也将总市值纳入估值指标。
report_standard = f"""
### 估值指标
- **总市值**: {financial_estimates.get('total_mv','N/A')}
- **市盈率(PE)**: {financial_estimates.get('pe','N/A')}
- **市盈率TTM(PE_TTM)**: {financial_estimates.get('pe_ttm','N/A')}
- **市净率(PB)**: {financial_estimates.get('pb','N/A')}
- **市销率(PS)**: {financial_estimates.get('ps','N/A')}
- **股息收益率**: {financial_estimates.get('dividend_yield','N/A')}
"""4.4 combined_data 日志
为提升调试可见性，基本面分析师新增完整数据日志。
logger.info(f"[基本面分析师] 统一工具返回完整数据:\n{combined_data}")这样可以清楚看到提交给大模型的完整基本面数据，便于排查字段缺失或数据异常。
4.5 文档补充
新增两份数据说明文档：
docs/analysis/combined_data_structure_analysis.md：详细数据结构分析。docs/analysis/combined_data_quick_reference.md：快速参考指南。
4.6 实现效果
- 基本面报告包含总市值数据。
- 大模型可以基于市值进行公司规模分析。
- 支持多层降级策略，数据获取更可靠。
- 日志更完整，调试更方便。
- 基本面数据结构文档更清晰。
五、端口冲突自动检测
5.1 问题背景
相关提交：
e047d57：添加 端口冲突检测和自动清理功能。
用户启动服务时，经常遇到端口被占用问题。
常见冲突端口包括：
8000：后端服务。3000：前端服务。27017：MongoDB。6379：Redis。
此前用户需要手动查找占用进程并结束，操作复杂，也容易误操作。
5.2 端口检测脚本
新增 scripts/check_ports.py，用于检测端口占用并显示占用进程。
def check_port(port: int) -> tuple[bool, str]:
"""检查端口是否被占用"""
for conn in psutil.net_connections():
if conn.laddr.port == port and conn.status == 'LISTEN':
process = psutil.Process(conn.pid)
process_info = f"{process.name()} (PID: {conn.pid})"
return True, process_info
return False, ""同时支持自动结束占用端口的进程。
def kill_process_on_port(port: int) -> bool:
"""结束占用指定端口的进程"""
for conn in psutil.net_connections():
if conn.laddr.port == port and conn.status == 'LISTEN':
process = psutil.Process(conn.pid)
process.terminate()
process.wait(timeout=5)
return True
return False5.3 集成到启动脚本
启动脚本中会先执行端口检查。
echo [1/5] 检查端口占用...
python scripts/check_ports.py
if errorlevel 1 (
echo 端口检查失败，请解决端口占用问题后重试
pause
exit /b 1
)5.4 实现效果
- 自动检测端口占用。
- 显示占用进程信息。
- 支持一键清理占用进程。
- 提供友好提示。
- 提升启动成功率。
六、LLM 配置优化
6.1 问题背景
相关提交：
3ddfb80：修复大模型 API Key 更新后不生效 的问题。49d238f：改进错误提示用户友好性。
此前用户在 Web 后台更新 LLM API Key 后，系统仍然可能使用旧配置，需要重启服务才能生效。
同时，错误提示偏技术化，用户不容易理解如何解决。
6.2 API Key 热更新
系统新增 API Key 缓存与定时刷新机制。
class LLMAdapter:
def __init__(self):
self._api_key_cache = None
self._cache_time = None
self._cache_ttl = 60
def get_api_key(self) -> str:
"""获取 API Key，支持热更新"""
now = time.time()
if self._api_key_cache and self._cache_time:
if now - self._cache_time < self._cache_ttl:
return self._api_key_cache
api_key = self._load_api_key_from_db()
self._api_key_cache = api_key
self._cache_time = now
return api_key6.3 用户友好错误提示
新增用户友好异常类。
class UserFriendlyException(Exception):
"""用户友好的异常类"""
def __init__(self, message: str, suggestion: str = None):
self.message = message
self.suggestion = suggestion
super().__init__(message)
def to_dict(self) -> dict:
result = {"error": self.message}
if self.suggestion:
result["suggestion"] = self.suggestion
return result使用示例：
raise UserFriendlyException(
message="API Key 无效或已过期",
suggestion="请在系统设置中更新您的 API Key"
)6.4 实现效果
- API Key 更新后 60 秒内自动生效。
- 无需重启服务。
- 错误提示更友好。
- 提供明确解决建议。
七、其他优化
7.1 数据源禁用修复
相关提交：
4e849df：修复某些情况下数据源禁用后的问题。bd842fc：修复数据源优先级和股票筛选功能。
改进内容：
- 修复数据源禁用后仍然被使用的问题。
- 优化数据源优先级逻辑。
- 改进股票筛选功能。
7.2 时区和性能优化
相关提交：
b1dde42：修复时区标识和数据同步性能问题。
改进内容：
- 修复时区标识不一致问题。
- 优化数据同步性能。
- 减少不必要的数据库查询。
7.3 前端优化
相关提交：
fcd1b59：修复前端 API 调用和界面优化。
改进内容：
- 修复前端 API 调用问题。
- 优化界面交互。
- 改进错误处理。
7.4 多平台打包
相关提交：
8777623：ARM 镜像配置调整。d67167c：打包优化，支持多平台打包。
改进内容：
- 支持 ARM 架构。
- 优化 Docker 镜像。
- 支持 Windows、Linux、macOS 等多平台打包。
7.5 依赖管理
相关提交：
1162072：更新依赖锁定文件和测试代码。4a78396：添加runtime/到.gitignore。860879c：添加venv/到.gitignore。d5c0773：添加vendors/到.gitignore。
改进内容：
- 更新依赖版本。
- 优化
.gitignore。 - 排除运行时数据和构建产物。
八、影响范围
8.1 打包脚本
| 文件 | 说明 |
|---|---|
scripts/package_windows_portable.py | Windows 绿色版打包 |
scripts/build_installer.py | Windows 安装器构建 |
scripts/windows_installer.nsi | NSIS 安装脚本 |
scripts/check_ports.py | 端口冲突检测 |
scripts/check_ports.bat | Windows 批处理版本 |
8.2 核心代码
| 文件 | 说明 |
|---|---|
tradingagents/dataflows/optimized_china_data.py | 添加总市值数据 |
tradingagents/agents/analysts/fundamentals_analyst.py | 添加 combined_data 日志 |
tradingagents/llm/llm_adapter.py | API Key 热更新 |
app/core/exceptions.py | 用户友好异常 |
app/services/data_sources/base.py | 数据源禁用修复 |
app/routers/stocks.py | 前端 API 优化 |
app/core/config.py | 时区配置 |
app/services/historical_data_service.py | 性能优化 |
8.3 文档
| 文件 | 说明 |
|---|---|
docs/analysis/combined_data_structure_analysis.md | 数据结构分析 |
docs/analysis/combined_data_quick_reference.md | 快速参考 |
docs/blog/2025-11-01-to-11-04-windows-installer-and-fundamental-analysis-enhancements.md | 本次更新文档 |
8.4 配置文件
| 文件 | 说明 |
|---|---|
.gitignore | 排除构建产物和运行时数据 |
requirements.txt | 更新依赖 |
Dockerfile | 多平台支持 |
九、验证方法
9.1 Windows 绿色版验证
# 1. 运行打包脚本
python scripts/package_windows_portable.py
# 2. 检查输出目录
dir dist\windows-portable
# 3. 测试启动
cd dist\windows-portable
start.bat
# 4. 访问前端
# http://localhost:30009.2 Windows 安装器验证
# 1. 构建安装器
python scripts/build_installer.py
# 2. 运行安装程序
TradingAgents-CN-Setup.exe验证内容：
- 桌面快捷方式是否创建。
- 开始菜单是否创建。
- 程序列表是否注册。
- 控制面板卸载是否正常。
9.3 总市值数据验证
curl -X POST http://localhost:8000/api/analysis/fundamental \
-H "Content-Type: application/json" \
-d '{"symbol": "000001"}'检查返回结果中是否包含 总市值 字段。
查看日志：
tail -f logs/app.log | grep "总市值"9.4 端口冲突检测验证
# 1. 占用测试端口
python -m http.server 8000
# 2. 运行检测脚本
python scripts/check_ports.py
# 3. 选择自动清理
# 输入 y 确认
# 4. 验证端口已释放
netstat -ano | findstr "8000"9.5 LLM 配置热更新验证
# 1. 在 Web 后台更新 API Key
# 2. 等待 60 秒
# 3. 触发 LLM 调用
curl -X POST http://localhost:8000/api/analysis/news \
-H "Content-Type: application/json" \
-d '{"symbol": "000001"}'
# 4. 检查日志
tail -f logs/app.log | grep "API Key"十、升级指引
10.1 更新代码
git pull origin v1.0.0-preview
pip install -r requirements.txt10.2 重启服务
Docker 部署：
docker-compose down
docker-compose up -d本地部署：
停止当前服务后重新启动。10.3 验证升级
curl http://localhost:8000/health
curl -X POST http://localhost:8000/api/analysis/fundamental \
-H "Content-Type: application/json" \
-d '{"symbol": "000001"}'十一、相关提交
完整 22 个提交记录如下：
| 提交 | 说明 | 日期 |
|---|---|---|
d67167c | 打包优化，支持多平台打包 | 2025-10-31 |
8777623 | ARM 镜像配置调整 | 2025-10-31 |
49d238f | 改进错误提示用户友好性 | 2025-11-01 |
3ddfb80 | 修复大模型 API Key 更新后不生效问题 | 2025-11-01 |
d5c0773 | 添加 vendors 到 .gitignore | 2025-11-01 |
860879c | 添加 venv 到 .gitignore | 2025-11-01 |
4a78396 | 添加 runtime 到 .gitignore | 2025-11-01 |
4e849df | 修复数据源禁用后的问题 | 2025-11-01 |
5dd32c9 | 合并远程预览分支 | 2025-11-02 |
928e108 | 更新 .gitignore，排除构建产物和临时文件 | 2025-11-03 |
3018b04 | 修复 LLM 适配器 API Key 验证和传递问题 | 2025-11-03 |
b1dde42 | 修复时区标识和数据同步性能问题 | 2025-11-03 |
bd842fc | 修复数据源优先级和股票筛选功能 | 2025-11-03 |
fcd1b59 | 前端 API 调用和界面优化 | 2025-11-03 |
97201de | 添加 Windows 绿色版打包支持 | 2025-11-03 |
1162072 | 更新依赖锁定文件和测试代码 | 2025-11-03 |
6c841fa | 添加 Windows 安装器脚本 | 2025-11-03 |
e0ce2bf | 排除部分调试目录 | 2025-11-03 |
e047d57 | 添加端口冲突检测和自动清理功能 | 2025-11-03 |
39205bc | 添加 combined_data 日志 | 2025-11-04 |
564b1d6 | 在基本面分析中添加总市值数据 | 2025-11-04 |
e67d839 | 基本面数据说明 | 2025-11-04 |
十二、总结
本次更新通过 22 个提交，完成了 跨平台部署 和 基本面分析功能 的重要增强。
主要成果包括：
- Windows 绿色版：一键启动、无需安装、开箱即用，支持 U 盘运行。
- Windows 安装器：提供标准化安装流程和更专业的用户体验。
- 基本面分析增强：添加 总市值数据，完善估值指标体系。
- 端口冲突检测：自动检测并清理占用端口，提升启动成功率。
- LLM 配置优化：API Key 更新后可在 60 秒内自动生效。
- 多平台支持：支持 Windows、Linux、macOS 和 ARM 架构。
- 文档完善：补充基本面数据结构说明和快速参考指南。
这些改进显著降低了 TradingAgents-CN 的使用门槛，提升了 跨平台兼容性、数据完整性和部署便利性，也为更多用户提供了更便捷、更稳定的股票分析平台体验。
✅ 官方唯一渠道：📦 GitHub 仓库：https://github.com/hsliuping/TradingAgents-CN
Aekor AI-API 中转站，让全球顶尖 AI 大模型“触手可及”！你是否曾为这些烦恼头疼？
🔹 人在国内，却总被海外官网 API 的高延迟、掉线、甚至无法访问困扰？
🔹 想用最强的 GPT、Claude 等模型，却卡在海外信用卡、支付审核等重重阻碍？
🔹 官方 API 太贵？Aekor 为你打通“网络-支付-成本”的任督二脉！
💡 Aekor 核心价值：好用、便宜、快 💡
🚀 高速稳定，告别掉线国内专线加速，API 响应低延迟，告别「转圈圈」的焦虑，开发效率瞬间拉满！
🧠 顶尖模型，随需而调涵盖 GPT 系列、Claude 系列等全球主流大厂模型，一次接入，轻松调用！
🎁 免费白嫖，诚意拉满！
注册即送 20 美元体验额度，够你狠狠测试一轮模型质量与线路稳定性了！
⚠️ 温馨提示：API 中转市场虽多但良莠不齐（甚至有些会偷工减料换小模型糊弄事儿）。Aekor 坚持提供正版稳定的服务，但还是建议：先用免费的 20 刀测试是否契合自身需求，满意了再小额充值上车，理性消费不盲目。
文章评论