> 口语化对话 | 有温度的辅助 | 专业投顾建议 | 量化分析支持 | Web UI 仪表盘 | 文件上传持仓识别
> 跨平台原生窗口应用 — 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
启动后会自动：
点击顶栏的「设置」按钮 → 弹出模型配置模态框：
| 步骤 | 操作 |
|------|------|
| 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/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 版 | 桌面版 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 配置模态框 |
# 安装依赖
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 | 可视化交互、文件上传、图表展示 |
> 浏览器访问 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编码 |
上传流程：
| 端点 | 方法 | 说明 |
|------|------|------|
| / | 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报告"))
| 信号 | 权重 | 说明 |
|------|------|------|
| 均线偏离 | 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}")
| 模块 | 改动 |
|------|------|
| 桌面客户端 | 跨平台 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 / 单元 / 元数据测试 |
| 类别 | 改动 |
|------|------|
| 路径 | 新增 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 配置正确 |
| 类别 | 改动 |
|------|------|
| 路径 | 移除全部 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 字段统一为「社区开发者」 |
目标：任意独立电脑、任意 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 元数据测试
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。
共 21 个版本