3 首页智能入口深化、全局壳体升级与分析师耗时治理

3 首页智能入口深化、全局壳体升级与分析师耗时治理

阶段时间：约 2026-05-01～2026-05-06
项目：FinAgent

摘要

本阶段把工作重心放到三条并行主线：一是首页功能的扩展——公司名称查代码与实时新闻同源的词云摘要，把 LLM 约束在契约与行情简称表校验之内，并打通查码后进入单股分析与走势看板的预填跳转；二是登录后主壳的体验统一——顶栏品牌与主题切换、侧栏收窄与图标化导航、暗色模式补全与报告弹层粘性头部，使多页面信息架构在视觉与操作上更像同一款产品；三是账户与性能侧的工程化——个人中心（/profile）落地资料编辑、两步改密与 Canvas 圆形头像上传，解决 Bearer 头像与<img>原生不兼容等问题；分析链路上则围绕「墙钟 vs 体感」拆分优化——Market 多指标批量拉取与 OHLCV LRU、四专科并行、analyst_progress与轮询签名缓解误退避，并延续 Dataflow 多供应商回退与FINAGENT_*可调开关，便于在 AkShare 抖动或本地 Ollama 队列压力下稳定演示与排障。整体上，本阶段目标是在不大改对外 API 契约的前提下，提升首页可信度、全局一致性、账户完整度与分析任务的可感知进度，为后续阶段扩展预留样式与配置入口。

一、阶段目标与主线叙事

1. 首页产品叙事：从「展示资讯」升级为「查码 → 决策 → 跳转分析/看图」的闭环；词云与摘要共享_build_live_news_response一类单一数据源，控制成本与漂移。
2. 全局壳体与主题：页眉固定全宽、侧栏与主内容区对齐；light/dark持久化并驱动data-theme，补齐首页/单股/标签等在暗色下的对比度。
3. 账户与安全体验：个人中心集中承载展示资料与凭证操作；头像走需鉴权的GET /api/auth/me/avatar，前端以 fetch + blob URL 呈现。
4. 分析耗时与可运维：区分真实墙钟与轮询体感；batch 指标、并行分析师、细粒度进度字段与环境变量裁剪专科/阶段，配合掘金/TuShare 等route_to_vendor回退，降低数据源单点故障对任务的影响。

二、首页：公司名称查代码、快捷跳转与新闻词云

查代码链路强调「一行一件」：提示词约束单代码输出，解析侧只取首个合法片段；中文查询优先 AkShare 代码–简称表高分匹配，LLM 给出的 A 股再由个股简称一致性校验，降低张冠李戴。港股、美股解析规范化（如 HK 代码位数变体）与少量俗称别名兜底，减少「英伟达」「腾讯」等高频查询在无表数据时的失败率。产品文案上，对暂不支持港股/美股单股分析的跳转给出明确预期，避免用户误以为链路失效。

跳转：查询结果为 A 股时，支持进入单股分析、查看走势图，通过路由state预填代码并在进入后replace清理，避免后退粘连；走势页统一「无代码先看上证总览 / 有代码看个股」的加载顺序，减少预填与默认总览竞态。

词云与摘要：GET /api/news/word-cloud与/api/news/live/top同源聚合标题，LLM 产出短摘要与主题级关键词（带权重）；服务端TTL 缓存（如 30 分钟级）减轻重复打开首页的模型压力；前端echarts-wordcloud与echarts@6存在 peer 差异时，团队约定legacy-peer-deps或frontend/.npmrc固化安装策略。

（组员技术展开见 组员博客。）

三、全局主题与导航体验

本轮前端升级将品牌logo / favicon与顶栏统一；页眉贴顶全宽，侧栏置于页眉下方并与主内容偏移对齐。侧栏去除冗余字样、缩窄宽度，导航项采用图标 + 文案，日间白底 / 夜间深底随主题联动。主题切换写入localStorage（如theme-mode），通过document.documentElement[data-theme]驱动 CSS 变量，并对背景、边框、阴影等增加transition，减轻切换闪变。

阅读体验：报告查看弹层顶部改为粘性头部，关闭按钮在长正文滚动时仍可达。标题图案（titleWithIcon等）覆盖首页、单股、走势、报告等主要模块，提升模块扫读性。已知后续可向图表暗色主题、统一 SVG 图标集与页眉右侧扩展入口（搜索、通知等）演进。

（组员技术展开见 组员博客。）

四、个人中心：路由、头像与 REST 契约

个人中心挂载/profile，侧栏底部入口与顶栏主题解耦。页面包含个人信息（昵称、简介、头像）、两步改密、只读账号信息（用户名、用户 id、注册时间）及简要使用说明。

头像：选图后经Canvas 圆形裁剪导出固定尺寸再multipart上传；后端限制2MB、校验类型并FileResponse下载。关键点：avatar_url指向需 Bearer 的 API 路径时，不能依赖原生<img src>；采用useAuthAvatarUrl一类 hook：fetch +Authorization→ blob →createObjectURL，卸载时revokeObjectURL。上传后若路径字符串不变，通过avatarEpoch（或查询参数 bump）打碎缓存，保证侧栏与详情页头像同源刷新。

REST 一览：GET/PATCH /api/auth/me、POST /api/auth/me/password、POST/DELETE /api/auth/me/avatar、GET /api/auth/me/avatar。

（组员技术展开见 组员博客。）

五、分析师耗时、数据回退与可调开关

度量二分：墙钟由 LLM 往返、工具 I/O、专科是否并行等决定；体感则受stage_log签名与轮询退避影响——二者不宜混为一谈对外表述。

Market：get_indicators支持逗号分隔批量指标，底层单次fetch_stock_ohlcv再格式化多段 Markdown，减少同一步骤内重复拉网；窗口钳制限制过长历史请求；OHLCV LRU扩容提高进程内重复命中概率（不改变行情语义）。

分析师子图：四专科ThreadPoolExecutor并行（实际并发受FINAGENT_ANALYST_PARALLEL_WORKERS等约束），墙钟由「四段相加」近似变为「取最慢段」（受云厂商限流与本机 Ollama 队列影响）。analyst_progress在子专科完成时落盘，与stage_log一并纳入前端轮询签名，避免并行阶段长时间「签名不变」触发过度退避。

数据回退：route_to_vendor按配置链尝试 vendor，异常继续回退；行情侧可配置AkShare → 掘金 GM → TuShare等顺序（掘金需 token，未配置则跳过），将数据源抖动尽量关在 dataflows 层。

联调常用开关（节选）：FINAGENT_ENABLED_STAGES、FINAGENT_SELECTED_ANALYSTS、FINAGENT_ANALYST_REACT_ENABLED、FINAGENT_ANALYST_MAX_TOOL_ROUNDS、FINAGENT_LANGGRAPH_RECURSION_LIMIT、FINAGENT_ANALYST_PARALLEL_WORKERS、FINAGENT_ANALYST_LLM_TIMEOUT_SECONDS、FINAGENT_NEWS_LOOKBACK_DAYS等，详见backend/app/core/config.py与.env。

（Market 批量指标、四专科并行、analyst_progress与轮询等见 组员博客；route_to_vendor回退与FINAGENT_*调参见 组员博客。）

六、界面与演示说明（本地开发环境）

本阶段视觉改动分散在首页查码区、词云区块、顶栏侧栏与/profile。建议在127.0.0.1:5173下逐项验收：主题切换、报告弹层滚动时关闭按钮、个人中心头像裁剪上传、首页查码 → 单股/走势预填。

七、阶段成果与如何复现

复现路径：

1. 根目录虚拟环境安装后端依赖；配置 LLM（本机 Ollama 或兼容 OpenAI API）；按需配置FINAGENT_GM_TOKEN、TuShare 与 dataflow vendor 链。
2. backend启动uvicorn；frontend执行npm install（若 peer 冲突使用仓库frontend/.npmrc或--legacy-peer-deps），再npm run dev，或使用根目录start-dev.bat。
3. 注册 / 登录后验证：首页查码与词云、主题切换与个人中心头像、单股分析进度与子专科进度展示、可选裁剪FINAGENT_ENABLED_STAGES做快速冒烟。

八、小结与下阶段展望

本阶段 FinAgent 在首页可信度（契约 + 表校验 + 缓存）、全局壳体一致性（主题与导航）、账户闭环（鉴权头像与资料）以及分析链路可感知与可压缩（batch / 并行 / 进度 / 回退 / 开关）上做了集中补强。已知限制包括：港股/美股查码后的产品引导仍可细化；词云关键词黑名单与小样本测试可持续加强；图表组件与暗色主题的像素级统一仍可迭代；并行分析师在云/API 限流场景下需结合实际调整 workers 与超时。

下阶段展望：开启研究辩论阶段以及后续阶段的工作

九、组员个人博客与仓库周报索引