基金投资AI客户经理

口语化对话 | 有温度的辅助 | 专业投顾建议 | 量化分析支持 | Web UI 仪表盘 | 文件上传持仓识别

桌面客户端（v5.1.3）

跨平台原生窗口应用 — Win / Mac / Linux 一键启动，无须开浏览器。

核心特性

| 特性 | 说明 | |------|------| | 原生窗口 | 基于 PyWebView 套壳 — Win=Edge WebView2, Mac=WKWebView, Linux=GTK WebView | | 深色玻璃拟态 | 全新视觉设计：毛玻璃 + 渐变 + 动画，比 Web 版更好看 | | 多模型切换 | 内置 9 大国产大模型 + 自定义 OpenAI 兼容端点 | | 本地配置 | API Key 保存在 %APPDATA%\FundAdvisor\，不外传 | | 一键测试 | 配置后立即测试连通性 + 响应延迟 | | 一键打包 | PyInstaller 一键产出 Win .exe / Mac .app / Linux 二进制 |

快速启动

# 1. 安装桌面端依赖（pywebview）
pip install pywebview

# 2. 启动桌面客户端（自动开窗）
python scripts/desktop_app.py

# 或在 Mac/Linux 上：
python3 scripts/desktop_app.py

启动后会自动：

分配空闲端口（5002-5021）
启动 Flask 后台
打开原生窗口（1280×820）
顶栏出现「模型状态指示器」

切换大模型（顶栏设置按钮）

点击顶栏的「设置」按钮 → 弹出模型配置模态框：

| 步骤 | 操作 | |------|------| | 1 | 选择「提供商」卡片（DeepSeek / MiniMax / 小米 / 通义 / 智谱 / Kimi / 豆包 / 混元 / 星火 / 自定义） | | 2 | 填入 API Key + 调整 Base URL + 选 Model | | 3 | 「连接测试」验证 → 「保存」 | | 4 | 顶栏「模型状态」实时显示当前激活模型（绿点=已配置，黄点=未配置） | | 5 | 在「智能对话」页使用 — 消息会发送到当前激活模型 |

支持 9 大国产模型 + 1 个 OpenAI 兼容自定义入口：

| 厂商 | 默认 base_url | 代表模型 | |------|---------------|---------| | DeepSeek（深度求索） | https://api.deepseek.com/v1 | deepseek-chat, deepseek-reasoner | | MiniMax | https://api.MiniMax.chat/v1 | MiniMax-Text-01, MiniMax-VL-01 | | 小米 MiMo | https://api.xiaomimimo.com/v1 | mimo-v2-flash, mimo-v2-pro | | 通义千问（阿里） | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-turbo/plus/max/long | | 智谱 GLM | https://open.bigmodel.cn/api/paas/v4 | glm-4-flash/plus/long/air | | 月之暗面 Kimi | https://api.moonshot.cn/v1 | moonshot-v1-8k/32k/128k | | 豆包（字节） | https://ark.cn-beijing.volces.com/api/v3 | doubao-lite/pro-32k/pro-256k | | 混元（腾讯） | https://api.hunyuan.cloud.tencent.com/v1 | hunyuan-standard/pro/turbo | | 讯飞星火 | https://spark-api-open.xf-yun.com/v1 | generalv3/v3.5/4.0Ultra | | 自定义 OpenAI 兼容 | 任意 URL | 任意模型名 — Ollama/vLLM/LM Studio/OneAPI |

注：所有模型都走 OpenAI 兼容协议（/v1/chat/completions），统一适配器 llm_providers.py。

打包成独立应用

| 平台 | 脚本 | 输出 | |------|------|------| | Windows | 双击 scripts\build_desktop.bat | dist\FundAdvisor\FundAdvisor.exe | | macOS | bash scripts/build_desktop.sh mac | dist/FundAdvisor.app | | Linux | bash scripts/build_desktop.sh linux | dist/FundAdvisor/FundAdvisor |

打包后用户无需安装 Python — 双击 exe 即可运行，配置自动落到 %APPDATA%\FundAdvisor\。

配置文件位置（跨平台标准）

| 平台 | 路径 | |------|------| | Windows | %APPDATA%\FundAdvisor\llm_config.json | | macOS | ~/Library/Application Support/FundAdvisor/llm_config.json | | Linux | ~/.config/FundAdvisor/llm_config.json |

桌面端新增 API 端点

| 端点 | 方法 | 用途 | |------|------|------| | /api/llm/providers | GET | 列出所有 provider + 元信息 + 是否已配 Key | | /api/llm/config | GET / POST | 读取 / 更新 LLM 配置（active、provider、生成参数） | | /api/llm/chat | POST | 非流式对话 {provider, messages, ...} | | /api/llm/stream | POST | 流式对话（SSE，实时打字机效果） | | /api/llm/ping | POST | 连通性测试 {provider} → 返回延迟+回显 |

视觉升级（桌面版相比 Web 版）

| 维度 | Web 版 | 桌面版 v5.1 | |------|--------|-------------| | 主题 | 浅色 | 深色玻璃拟态 | | 主色 | 蓝灰 | 蓝→紫→青三色渐变 | | 背景 | 纯色 | 径向渐变 + 网格光晕 | | 卡片 | 白色实心 | 半透明 + backdrop-filter 毛玻璃 | | 按钮 | 实心 | 渐变 + 发光阴影 | | 数字 | 普通 | tabular-nums 等宽对齐 | | 顶栏 | 静态 | 粘性 + 毛玻璃 | | Tab | 下划线 | 渐变下划线 + 发光 | | 动效 | 几乎无 | fadeIn/msgIn/spin/pulse |

文件清单（桌面端新增）

| 文件 | 用途 | |------|------| | scripts/desktop_app.py | PyWebView 启动器 | | scripts/llm_providers.py | 统一大模型适配层 | | scripts/build_desktop.bat | Windows 打包脚本 | | scripts/build_desktop.sh | Mac/Linux 打包脚本 | | templates/index.html | 深色玻璃拟态 UI + LLM 配置模态框 |

快速启动（Web 浏览器版）

# 安装依赖
pip install requests beautifulsoup4 akshare pandas python-dateutil openpyxl flask flask-cors

使用方式：

| 方式 | 操作 | 适用场景 | |------|------|---------| | Web UI | 调用 launch_web_ui 或 python scripts/web_server.py → 浏览器打开 http://localhost:5002 | 可视化交互、文件上传、图表展示 |

Web UI 交互仪表盘（v5.1.3）

浏览器访问 http://localhost:5002，6大功能模块一站式交互。

启动方式

| 方式 | 操作 | 说明 | |------|------|------| | MCP 工具 | 调用 launch_web_ui | 通过 Claude 启动 Flask，端口 5002 | | 命令行 | python scripts/web_server.py | 独立启动，后台运行 |

仪表盘功能模块

| 模块 | 功能 | 数据源 | |------|------|--------| | 市场概览 | 沪深300/创业板/上证50/深证成指/红利指数/中证500 实时行情 + 30日走势折线图 | akshare / 腾讯财经 | | 持仓分析 | 客户持仓明细 + 盈亏汇总卡片 + 饼图 + 持仓净值走势 | 本地JSON + akshare实时净值 | | 基金查询 | 基金/经理/公司搜索 + 净值走势图 + 同类归一化对比 | 本地JSON + akshare | | 量化分析 | 7维量化信号 + 净值预测（线性回归+置信区间） | fund_quant_analyzer | | 资讯 | 财经新闻聚合（新浪财经/腾讯财经/和讯网/东财股吧） | 多渠道实时抓取 | | 智能对话 | 自然语言对话 + 文件上传持仓识别 | conversation_engine + HoldingsImporter |

文件上传（对话框内）

客户可在对话框直接上传持仓文件，系统自动识别并分析：

| 文件类型 | 格式 | 说明 | |---------|------|------| | 截图 | .png .jpg .jpeg .bmp | OCR识别截图中的基金代码、名称、份额 | | Word | .docx | 解析文档表格中的持仓数据 | | PDF | .pdf | 解析对账单/持仓报告 | | Excel | .xlsx .xls | 自动识别列名（中英文），保留基金代码前导零 | | CSV | .csv | 同Excel，支持UTF-8编码 |

上传流程：

输入客户名称（可选）
点击「上传文件」或拖拽文件到上传区
系统自动解析 → 聊天中展示持仓明细表格
自动送入对话引擎进行持仓分析

API 端点

| 端点 | 方法 | 说明 | |------|------|------| | / | GET | 仪表盘主页面 | | /api/search | GET | 基金/经理/公司搜索（?q=关键词&type=fund\|manager\|company） | | /api/market/overview | GET | 六大市场指数行情 | | /api/nav/chart | GET | 基金历史净值走势（?code=001924&period=1y\|6m\|3m\|1m） | | /api/holdings | GET | 客户持仓概览（?client_id=张先生） | | /api/news | GET | 财经新闻资讯（?limit=20） | | /api/quant/forecast | POST | 量化预估分析（{code, forecast_days}） | | /api/compare | POST | 同类基金对比（{codes: [...]}） | | /api/chat | POST | 智能对话（{query}） | | /api/upload | POST | 文件上传（multipart/form-data: file + client_id） | | /api/llm/* | GET/POST | LLM 模型配置与对话（桌面版） | | /api/health | GET | 健康检查 |

数据源覆盖

| 数据源 | 用途 | 接口 | |--------|------|------| | akshare | 指数行情、基金净值、实时估值 | ak.stock_zh_index_daily_em / ak.fund_open_fund_info_em | | 东方财富 | 实时估值、基金概况 | JSONP接口 / 详情页JS | | 新浪基金 | 净值数据fallback | Sina Fund API | | 腾讯财经 | 指数数据fallback | web.ifzq.gtimg.cn | | 和讯网 | 新闻fallback | HTML抓取 | | 新浪财经 | 新闻聚合 | HTML抓取 | | 腾讯财经新闻 | 新闻聚合 | HTML抓取 |

客户持仓导入

支持7种方式导入客户持仓：Web上传、截图OCR、Word、PDF、Excel、CSV、链接爬取。

导入方式总览

| 导入方式 | 触发示例 | 适用场景 | |---------|---------|---------| | Web上传 | 对话框拖拽文件 / 点击上传按钮 | 客户直接在Web界面上传 | | 截图OCR | "导入截图" / 发送图片路径 | 客户发送持仓页面截图 | | Word导入 | "导入Word" / 发送.docx路径 | 客户提供Word版持仓清单 | | PDF导入 | "导入PDF" / 发送.pdf路径 | 客户提供PDF对账单/报告 | | Excel导入 | "导入Excel" / 发送.xlsx路径 | 客户提供Excel持仓表 | | CSV导入 | "导入CSV" / 发送.csv路径 | 其他系统导出的CSV文件 | | 链接爬取 | "导入链接" / 提供URL | 登录后的基金平台链接 |

编程接口

from client_manager.holdings_importer import HoldingsImporter

importer = HoldingsImporter()

# 截图OCR
result = importer.import_from_screenshot("/path/to/持仓截图.png", client_id="张先生")

# Word/PDF
result = importer.import_from_docx("/path/to/持仓表.docx", client_id="张先生")
result = importer.import_from_pdf("/path/to/对账单.pdf", client_id="张先生")

# 链接爬取
result = importer.import_from_url("https://fund.eastmoney.com/001924.html", client_id="张先生")

# 查看持仓
holdings = importer.load_client_holdings("张先生")

# 导出
importer.export_to_excel(holdings, client_id="张先生")
importer.export_to_csv(holdings, client_id="张先生")

客户持仓仓库

data/clients/
├── _index.json                        # 仓库索引
├── {客户ID}/
│   ├── holdings.json                  # 当前持仓（按基金代码合并去重）
│   ├── history/holdings_{时间戳}.json  # 历史快照
│   ├── imports/import_{时间戳}.json   # 导入记录
│   └── reports/                       # 导出报告

对话引擎

支持的意图

| 意图 | 触发示例 | |------|---------| | 情绪安抚 | "亏了15%怎么办" "心态崩了" "好焦虑" | | 持仓分析 | "帮我看看持仓" "我的基金怎样了" | | 基金推荐 | "推荐个基金" "我35岁想买基金" | | 基金经理 | "张坤经理怎么样" "萧楠介绍" | | 基金公司 | "华夏基金怎么样" | | 板块预测 | "科技板块后面怎么走" | | 股票分析 | "帮我分析茅台" "600519怎么样" | | 宏观分析 | "宏观经济怎么样" "CPI走势" | | 报告生成 | "给我一份周报" "生成月报" | | PPT报告 | "生成PPT报告" "可视化演示" | | 止盈止损 | "设置止损10%" "止盈20%" | | 量化评估 | "我能承受多大亏损" "适合什么基金" | | 心态跟踪 | "记录心情" "心态分析" | | 费率查询 | "管理费多少" "申购费率" | | 持仓导入 | "导入截图" "导入Word" "上传持仓" | | 表格导出 | "导出Excel" "导出CSV" | | 客户管理 | "查看客户列表" |

使用示例

from client_manager.conversation_engine import ClientManager

cm = ClientManager()

# 基金查询
print(cm.chat("user_001", "001924怎么样"))

# 持仓分析
print(cm.chat("user_001", "我买了000858，亏了15%怎么办"))

# 推荐基金
print(cm.chat("user_001", "我35岁，能承受15%亏损，推荐基金"))

# 生成报告
print(cm.chat("user_001", "生成PPT报告"))

量化分析

7维信号模型

| 信号 | 权重 | 说明 | |------|------|------| | 均线偏离 | 15% | 净值与MA5/MA10/MA20/MA60偏离程度 | | RSI | 15% | 超买超卖判断（>70超买 / <30超卖） | | 布林带 | 10% | 净值在布林带中的位置 | | 动量 | 15% | N日累计涨幅 | | 波动率 | 10% | 年化波动率评估 | | 趋势 | 20% | 均线多空排列判断 | | 持仓集中度 | 15% | 基金经理持仓分散度 + 风格匹配 |

使用示例

from analysis.fund_quant_analyzer import FundQuantAnalyzer

analyzer = FundQuantAnalyzer()

# 单基金分析
result = analyzer.analyze_fund('001924', client_risk='积极型')
print(analyzer.format_analysis_report(result))

# 组合分析
holdings = [{'fund_code': '001924', 'shares': 10000, 'cost': 1.5}]
portfolio = analyzer.analyze_portfolio(holdings, client_risk='稳健型')
print(analyzer.format_portfolio_analysis_report(portfolio))

基金对比与可视化

from analysis.comparison_engine import ComparisonEngine

engine = ComparisonEngine()
result = engine.compare_managers(['张坤', '萧楠', '葛兰'])

Web UI 中：搜索基金后输入对比代码，自动生成归一化走势对比图。

其他能力

投资组合推荐

from analysis.portfolio_recommender_v2 import PortfolioRecommenderV2

rec = PortfolioRecommenderV2()
result = rec.recommend_portfolio_v2(
    age=35, risk_tolerance='积极型', target_return=15,
    investment_period=5, max_loss=20, investment_amount=20
)
print(rec.format_portfolio_report_v2(result))

止盈止损告警

from client_manager.alert_system import AlertSystem

alert = AlertSystem()
alert.set_user_alert_settings('user_001', stop_loss=10, stop_profit=20)
alerts = alert.daily_check('user_001', holdings)

基金经理话术

from analysis.fund_advisor_speech import FundAdvisorSpeech

gen = FundAdvisorSpeech()
print(gen.ask("张明经理怎么样？", manager_name="张明"))

基金经理互动

from client_manager.invitation_engine import InvitationEngine

engine = InvitationEngine()
result = engine.invite_managers_for_products(holdings, 'user_001')
print(engine.get_manager_self_introduction(manager_name='萧楠'))

用户量化评估

from client_manager.user_profile_manager import UserQuantitativeAssessment

assessment = UserQuantitativeAssessment()
result = assessment.assess_investment_profile(
    age=35, risk_tolerance='积极型', investment_amount=20,
    investment_horizon=5, target_companies=['华夏基金'], target_managers=['张坤']
)
print(assessment.format_assessment_report(result))

投资心态跟踪

from client_manager.emotional_tracker import EmotionalTracker

tracker = EmotionalTracker()
tracker.record_emotion('user_001', {
    'emotion': '焦虑', 'cause': '亏损15%', 'intensity': 7, 'profit_pct': -15
})
print(tracker.get_emotion_analysis('user_001'))

报告导出

from client_manager.report_generator import ReportGenerator
from client_manager.ppt_report_generator import PPTReportGenerator

# 文本报告
gen = ReportGenerator()
report = gen.generate_portfolio_report(user_id='user_001', holdings=holdings)

# PPT报告
ppt = PPTReportGenerator()
ppt.generate_report(holdings, output_path='report.pptx')

数据文件

| 文件 | 内容 | 数量 | |------|------|------| | fund_managers_distilled.json | 基金经理档案 | 4,220 人 | | fund_companies_distilled.json | 基金公司档案 | 164 家 | | holdings_database.json | 经理持仓明细 | 1,794 条 | | manager_views.json | 经理观点（季报/年报） | 3,000 条 | | style_profiles.json | 风格画像 | 成长/均衡/价值 | | external_data.json | 基金评级 + 分析 + 盈利概率 | 1,599 条 | | user_holdings.json | 用户持仓 | 自定义 | | alert_settings.json | 告警设置 | 用户配置 | | emotional_records.json | 心态记录 | 情绪追踪 | | alert_history.json | 告警历史 | 自动累积 | | feedback_settings_v2.json | 反馈设置 | 偏好配置 | | clients/ | 客户持仓仓库 | 按客户ID组织 |

数据时效

| 数据类型 | 滞后 | 说明 | |---------|------|------| | 基金净值 | T+1~T+2 | 估算值，非实时 | | 持仓明细 | 季度末后4-8周 | 半年报/年报披露延迟 | | 经理档案 | 实时更新 | 任职/离职状态 | | 指数行情 | 实时（交易时段） | akshare/东财/腾讯 | | 新闻资讯 | 实时抓取 | 多渠道聚合 |

月度更新：每月第1工作日自动执行 monthly_updater.py，更新全量经理名单和管理产品。

核心原则：所有数据仅供辅助参考，不构成投资建议。

脚本结构

fund-advisor/
├── mcp_server.py                          # MCP Server 入口（含 launch_web_ui 工具）
├── FundAdvisor.spec                       # PyInstaller 打包配置
├── pyproject.toml                         # Python 打包配置
├── requirements.txt                       # 依赖列表
├── .skillhub.json                         # SkillHub 发布清单
├── .claude-plugin/plugin.json             # Claude Code 插件清单
├── _meta.json                             # Skill 元数据
├── SKILL.md                               # 本文件
├── scripts/
│   ├── web_server.py                      # Flask Web 服务
│   ├── desktop_app.py                     # PyWebView 桌面启动器
│   ├── llm_providers.py                   # 统一大模型适配层
│   ├── build_desktop.bat                  # Windows 打包脚本
│   ├── build_desktop.sh                   # Mac/Linux 打包脚本
│   ├── client_manager/                    # 客户端/对话/持仓 (11 个)
│   │   ├── __init__.py
│   │   ├── conversation_engine.py         # 对话引擎（总入口）
│   │   ├── holdings_importer.py           # 持仓导入（截图OCR/文档/Excel/CSV/链接）
│   │   ├── client_portfolio_evaluator.py  # 持仓评测
│   │   ├── alert_system.py                # 止盈止损告警
│   │   ├── sector_predictor.py            # 板块预测
│   │   ├── invitation_engine.py           # 经理邀约
│   │   ├── user_profile_manager.py        # 用户画像 + 8 维量化评估
│   │   ├── emotional_tracker.py           # 心态跟踪
│   │   ├── report_generator.py            # 报告生成
│   │   ├── ppt_report_generator.py        # PPT 报告
│   │   └── emotional_templates.json       # 情绪安抚话术模板
│   ├── analysis/                          # 量化分析 (25 个)
│   │   ├── config.py
│   │   ├── fund_quant_analyzer.py         # 7 维信号量化分析
│   │   ├── comparison_engine.py           # 横向对比引擎
│   │   ├── portfolio_recommender_v1_DEPRECATED.py
│   │   ├── portfolio_recommender_v2.py    # 组合推荐 v2
│   │   ├── portfolio_analyzer.py          # 组合分析
│   │   ├── portfolio_scheduler.py         # 组合调度
│   │   ├── performance_tracker.py         # 业绩跟踪 + 量化调仓
│   │   ├── fund_advisor_speech.py         # 基金经理话术引擎 v4.0
│   │   ├── speech_generator.py            # 话术生成
│   │   ├── speech_humanizer_v3.py         # 拟人化话术
│   │   ├── humanized_speech_generator.py
│   │   ├── batch_speech_generator.py
│   │   ├── batch_speech_generator_v2.py
│   │   ├── realtime_manager_talk.py
│   │   ├── news_advisor.py                # 新闻顾问
│   │   ├── macro_analyzer.py              # 宏观分析
│   │   ├── stock_quant_analyzer.py        # 股票量化分析
│   │   ├── style_analyzer.py              # 风格分析
│   │   ├── distiller.py                   # 经理数据蒸馏
│   │   ├── company_distiller.py           # 公司数据蒸馏
│   │   ├── comprehensive_analyzer.py      # 综合分析
│   │   ├── enhanced_company_report.py     # 公司增强报告
│   │   ├── batch_company_report.py        # 批量公司报告
│   │   ├── manager_portfolio_builder.py   # 经理组合构建
│   │   └── config.py                      # 共享配置
│   ├── data_collection/                   # 数据采集 (22 个)
│   │   ├── README.md
│   │   ├── eastmoney_collector.py         # 东方财富采集
│   │   ├── news_collector.py              # 新闻采集
│   │   ├── manager_full_collector.py      # 全量经理采集
│   │   ├── enhanced_collector.py
│   │   ├── enhanced_manager_updater.py
│   │   ├── extended_collector.py
│   │   ├── extended_holdings_collector.py
│   │   ├── external_data_collector.py
│   │   ├── fee_collector.py
│   │   ├── view_collector.py              # 经理观点采集
│   │   ├── view_generator.py              # 经理观点生成
│   │   ├── report_opinion_collector.py
│   │   ├── report_parser.py
│   │   ├── full_collector.py
│   │   ├── amac_collector.py             # 基金业协会数据
│   │   ├── company_product_collector.py
│   │   ├── database_builder.py
│   │   ├── media_collector.py
│   │   ├── guba_comment_scraper.py        # 东方财富股吧
│   │   ├── fill_style.py
│   │   ├── fix_data.py
│   │   └── update_humanized_speech.py
│   └── maintenance/                       # 维护
│       ├── monthly_updater.py             # 月度数据更新
│       └── update_scheduler.py            # 更新调度
├── templates/                             # Web UI 前端
│   ├── index.html
│   └── assets/
├── data/                                  # 本地 JSON 数据库
├── assets/                                # 图标资源（多尺寸）
├── build/                                 # PyInstaller 产物
└── references/                            # API 文档
    ├── amac_api.md
    ├── database_schema.md
    ├── eastmoney_api.md
    └── style_classification.md

依赖安装

# 全量安装
pip install requests beautifulsoup4 akshare pandas python-dateutil \
    flask flask-cors mcp openpyxl python-docx pdfplumber Pillow

# 按需追加
pip install pytesseract   # 截图OCR（还需安装Tesseract系统包）
pip install selenium      # 浏览器爬取（还需ChromeDriver）
pip install PyPDF2        # PDF导入
pip install python-pptx   # PPT报告
pip install pywebview     # 桌面客户端

依赖检查脚本：

from importlib import util as _u
for name, spec in {
    "akshare": _u.find_spec("akshare"),
    "flask": _u.find_spec("flask"),
    "pytesseract": _u.find_spec("pytesseract"),
    "python-docx": _u.find_spec("docx"),
    "pdfplumber": _u.find_spec("pdfplumber"),
    "selenium": _u.find_spec("selenium"),
    "openpyxl": _u.find_spec("openpyxl"),
    "python-pptx": _u.find_spec("pptx"),
    "pywebview": _u.find_spec("webview"),
}.items():
    print(f"  {'OK' if spec else 'MISSING'} {name}")

v5.1 更新摘要

| 模块 | 改动 | |------|------| | 桌面客户端 | 跨平台 PyWebView 套壳 + 深色玻璃拟态 UI + 9 大国产模型配置中心 | | LLM 适配层 | 新增 scripts/llm_providers.py — 统一 OpenAI 兼容协议，支持 401/403/429/5xx 错误归一化 + 流式 SSE + 连通性 ping | | Web UI | /api/llm/* 5 个新端点（providers/config/chat/stream/ping） | | 配置持久化 | 桌面端 LLM 配置落到 %APPDATA%\FundAdvisor\llm_config.json（跨平台标准） | | 端口自适应 | 自动寻找 5002-5021 空闲端口 | | 健康检查 | 桌面端启动时轮询 /api/health 等待 Flask 就绪 | | 数据修复 | 修复 3 个 SyntaxError：style_analyzer.py / portfolio_analyzer.py / speech_generator.py | | 版本统一 | SKILL.md / _meta.json / .skillhub.json / .claude-plugin/plugin.json / pyproject.toml 全部 5.1.0 | | 健壮性 | web_server._load_* 加 try/except 防止 JSON 损坏 500 | | 健壮性 | /api/llm/* 5 端点抽公共 helper web_server._llm_helpers()，解耦 desktop_app | | 健壮性 | 25 处 bare except 替换为具体异常类 (JSONDecodeError/OSError/ValueError/KeyError/TypeError) | | MCP 工具 | auto_import_file 补齐 .xlsx/.xls/.csv 支持 — 与 SKILL.md 描述对齐 | | 包结构 | scripts/ 下 4 个目录补齐 __init__.py，可作为正常 Python 包导入与打包 | | 测试 | 新增 tests/ 目录 — 61 个 smoke / 单元 / 元数据测试 |

v5.1.1 更新摘要（本轮）

| 类别 | 改动 | |------|------| | 路径 | 新增 scripts/fund_advisor_paths.py 统一模块 — web_server / desktop_app 改用 | | 路径 | 兼容 pip install 与源码运行两种模式，env FUND_ADVISOR_BASE_DIR 可覆盖 | | 可观测性 | web_server / desktop_app 改用 logging 模块（带时间戳、等级、模块名） | | 可观测性 | web_server 加 access log（before/after_request 拦截，输出 method/path/状态/耗时） | | 修复 | web_server 启动入口 app.run 重复调用的 bug（两行相邻，第一行被覆盖） | | 配置 | analysis/config.py 默认值 "***" → "OFFLINE_PLACEHOLDER"，避免被密钥扫描器误报 | | 配置 | 新增 is_offline_mode() 辅助函数 | | 打包 | pyproject.toml 加 [tool.setuptools.package-data]，pip install 后 data/ 与 templates/ 一同打包 | | 文档 | 新增 README.md（项目总览 + 快速开始 + 故障排查） | | 文档 | 新增 CHANGELOG.md（按 Keep a Changelog 格式） | | 文档 | 新增 LICENSE（MIT） | | 测试 | 新增 pytest.ini（testpaths / strict-markers / markers 声明） | | 测试 | 新增 tests/test_logging.py — 验证 logger 配置正确 |

v5.1.3 更新摘要（本轮）

| 类别 | 改动 | |------|------| | 路径 | 移除全部 D 盘硬编码路径，替换为跨平台通用路径示例 | | 文档 | SKILL.md / README.md / mcp_server.py / conversation_engine.py 路径去个人化 | | 文档 | README.md 删除重复段落（去重 ~100 行） | | 元数据 | 版本号统一为 5.1.3（_meta.json / .skillhub.json / plugin.json / CHANGELOG.md） | | 其他 | author 字段统一为「社区开发者」 |

v5.1.2 更新摘要（独立部署版）

目标：任意独立电脑、任意 agent，3 行命令即可启动

| 类别 | 改动 | |------|------| | 入口 | 新增 fund_advisor/__main__.py — 任何 agent 都能用 python -m fund_advisor 启动 | | 入口 | __main__ 暴露 7 个子命令：web / desktop / mcp / check / install / test / version | | 入口 | pyproject.toml 加 [project.scripts]，装好直接 fund-advisor 命令 | | 自检 | 新增 fund_advisor/fund_advisor_bootstrap.py — 16 个依赖 + 6 个数据文件 + 1 个模板自动检查 | | 自检 | 区分 required / optional：核心缺失报错，可选缺失降级（不阻塞） | | 自检 | python -m fund_advisor check 输出一目了然的诊断报告 | | 安装 | install.sh（macOS/Linux）+ install.bat（Windows） — 跨平台一键安装脚本 | | 安装 | 支持 4 种模式：web（默认）/ desktop / mcp / all | | 容器 | 新增 Dockerfile（python:3.11-slim 基础镜像 + 健康检查） | | 容器 | 新增 docker-compose.yml（端口 5002 + 持久化卷 + 可选 DEEPSEEK_API_KEY） | | CI | 新增 .github/workflows/test.yml — 3 OS × 5 Python 版本矩阵 | | 元 | 新增 .gitignore（排除用户私有数据/桌面端 LLM 配置/打包产物） | | 修复 | 修复 mcp_server.py 阻塞 bug：老 SDK API @server.tool() 不存在 → 改用 FastMCP | | 修复 | mcp_server.py 11 个工具全部用 FastMCP 重新注册（实测 11/11 可调用） | | 降级 | docx / pdfplumber / openpyxl 从 required 降为 optional，缺时自动降级 | | 测试 | 新增 tests/test_bootstrap.py (6 个) — 自检与安装逻辑 | | 测试 | 新增 tests/test_mcp_server.py (5 个) — MCP 工具注册与可调用 | | 测试 | 总测试数 92 个（81 → 92，+11），全 PASS |

测试

# 安装 pytest
pip install pytest

# 跑全部测试
cd fund-advisor
python -m pytest tests/ -v

测试覆盖：

test_smoke_imports.py — 19 个核心模块 import 烟囱测试
test_data_loaders.py — 6 个 JSON 损坏防御测试
test_llm_providers.py — 13 个 LLMClient 单元测试
test_holdings_importer.py — 10 个 HoldingsImporter 单元测试
test_skill_metadata.py — 13 个 SKILL.md / _meta.json / 版本号 / emoji / init.py 元数据测试

FAQ

Q: 净值和实际看到的不一致？ A: 正常。净值数据滞后1-2天，是估算值。如需实时估值请查看天天基金或支付宝。

Q: 截图识别结果不对？ A: 截图尽量高清、包含基金代码列、背景干净无水印。也可以直接用Excel/CSV导入。

Q: Web UI 打不开？ A: 确认端口5002未被占用，检查 python scripts/web_server.py 启动日志。

Q: 上传Excel没识别到数据？ A: 确认第一列为基金代码（6位数字），常见列名：基金代码/代码、基金名称/名称、持有份额/份额、成本净值/成本。支持中英文列名。

Q: 数据安全吗？ A: 所有数据存储在本地，不会上传至任何服务器。Web UI 仅监听 localhost / 127.0.0.1。

Q: 桌面端 PyWebView 安装失败？ A: Windows 上 pip install pywebview 会自动装好 WebView2 Runtime；Mac 自带 WKWebView；Linux 需要 apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0。

量化基金投资顾问

基金投资AI客户经理

桌面客户端（v5.1.3）

核心特性

快速启动

切换大模型（顶栏 设置 按钮）

打包成独立应用

配置文件位置（跨平台标准）

桌面端新增 API 端点

视觉升级（桌面版相比 Web 版）

文件清单（桌面端新增）

快速启动（Web 浏览器版）

Web UI 交互仪表盘（v5.1.3）

启动方式

仪表盘功能模块

文件上传（对话框内）

API 端点

数据源覆盖

客户持仓导入

导入方式总览

编程接口

客户持仓仓库

对话引擎

支持的意图

使用示例

量化分析

7维信号模型

使用示例

基金对比与可视化

其他能力

投资组合推荐

止盈止损告警

基金经理话术

基金经理互动

用户量化评估

投资心态跟踪

报告导出

数据文件

数据时效

脚本结构

依赖安装

v5.1 更新摘要

v5.1.1 更新摘要（本轮）

v5.1.3 更新摘要（本轮）

v5.1.2 更新摘要（独立部署版）

测试

FAQ

切换大模型（顶栏设置按钮）