worldquant-alpha-system/docs/ai-chatbot-plan.md

# AI Chatbot 首版开发计划

2026-09-08 范围更新：已按用户确认扩展 REGULAR + FASTEXPR 通用回测、基础页面和 AI 固定运行确认。下文“不回测”描述保留原阶段边界；当前范围以[回测规格](../.scratch/backtest/spec.md)为准，平台检查、属性回写和正式提交仍不包含。

确认日期：2026-09-07。本文件保存实施范围；实际验证结果见 [验收记录](verification.md)。

## 1. 目标与范围

在现有 WorldQuant Alpha 工作空间中增加全局右侧 chatbot，支持展开、收缩、跨页面保留会话，以及基于当前页面上下文查询和操作业务数据。

采用 **React + Semi Design + AI SDK UI，FastAPI + Pydantic AI，PostgreSQL**。模型通过用户自定义的 `baseUrl`、`apiKey` 和 `model` 接入。

首版交付完整的“查询 → 展示结果 → 预览修改 → 用户确认 → 执行并刷新页面”闭环，包含本地研究记录修改和现有同步任务操作。MCP、知识检索、多 Agent、回测及 WorldQuant 平台回写不在本期范围。

保持现有单管理员、单后端进程部署。AI 未配置或服务不可用时，原有业务功能正常使用。

## 2. 产品行为与模型配置

### 模型设置

在“个人信息”页新增独立的“大模型服务”配置区域：

- 提供 Base URL、API Key、模型标识、接口协议和启用开关。
- 接口协议支持 `chat_completions` 与 `responses`，默认前者，用户明确选择；不自动切换协议或供应商。
- 模型标识手动填写，不依赖供应商提供模型列表接口。
- Base URL 按服务端可访问的完整 API 根地址填写，支持 HTTP/HTTPS；界面说明是否需要包含 `/v1`。
- API Key 使用现有 Fernet 加密能力保存在数据库，查询接口仅返回“是否已配置”。编辑时不回填密钥；更换 Base URL 必须重新输入密钥。
- 保存配置不发起模型请求。“测试连接”使用合成文本与无副作用的测试工具，验证回答、流式输出和完整工具调用往返，并分别显示结果。
- 未通过能力测试时，允许保存配置用于修正，但不启用业务聊天。配置变更后需要重新测试。

通过 Pydantic AI 的 OpenAI provider 和对应模型适配器接入两种协议；供应商兼容性最终以测试结果为准。[模型配置文档](https://github.com/pydantic/pydantic-ai/blob/main/docs/models/openai.md)

### 聊天与页面联动

- chatbot 挂载在登录后的工作区根部，默认收缩；展开宽度默认 420px，可在 360–640px 之间调整。
- 页面切换、面板收缩不取消当前执行。提供独立的“停止生成”按钮。
- 桌面端为聊天预留布局空间，Alpha 详情和任务面板使用剩余区域；空间不足时切换显示，保留聊天和编辑草稿。统一焦点、遮罩和 Esc 行为。
- 支持新建会话、查看历史和切换会话。首版不提供消息编辑、会话分叉和历史删除。
- 发送消息时附带当前页面、详情 Alpha ID、选中 ID、筛选和排序的快照；未保存的备注草稿不自动发送。
- 服务端根据引用 ID 重新读取业务数据。切换页面不改变正在执行的请求对象。
- 使用固定组件展示 Alpha 卡片、指标表、PnL、修改预览和任务进度；提供“打开详情”“应用筛选”等按钮。
- 业务修改成功后刷新相关数据；已有未保存草稿保留，并提示数据发生变化。

## 3. 后端模块、工具与执行规则

### 共用业务模块

将现有路由中的 Alpha 查询、研究记录修改、任务创建与控制逻辑提取为共用业务模块。REST 路由和 AI 工具调用同一实现，保留现有校验、事务、任务去重与同步行为。

AI 工具只使用明确的业务接口，不接触 ORM、任意 SQL、任意 HTTP 请求或平台凭据。新增接口沿用现有 Cookie 鉴权、来源校验和请求头要求；执行工具及确认操作时重新校验登录状态。

### 首批工具

| 类别 | 工具 | 执行规则 |
| --- | --- | --- |
| 查询 | `search_alphas`、`get_alpha_facets`、`get_alpha`、`get_alpha_pnl` | 读取本地数据，分页与数量限制沿用业务规则 |
| 任务查询 | `list_jobs`、`get_job_status` | 返回进度、错误及关联对象 |
| 研究记录 | `update_research`、`bulk_update_research` | 展示修改前后差异，用户确认后执行 |
| 任务操作 | `create_sync_job`、`cancel_job`、`retry_job` | 展示操作目标和影响，用户确认后执行 |

- 工具输入输出使用类型化契约，服务端始终校验模型参数。单位、空值、数据时间和来源明确返回。
- 查询结果按需裁剪，不将整个数据库、原始平台响应或完整 PnL 序列直接放入模型上下文。
- 批量修改固定为预览时的 ID 集合，上限 100 条；明确区分“当前选中项”与“全部筛选结果”。
- 确认记录绑定登录用户、工具、参数与目标版本，客户端仅提交确认记录 ID 和同意/拒绝。确认后不能替换目标或参数。
- 为研究记录增加递增版本号。页面保存和 AI 修改均检查读取时的版本；不匹配返回冲突，保留草稿或要求重新预览。
- 使用唯一执行标识防止重复确认、重试和刷新导致重复写入；本地变更、执行结果与审计记录在同一事务提交。
- 同步类工具只创建或控制已有业务任务，返回 `job_id`。任务进度沿用现有轮询，不让模型循环等待上游。

### 对话执行与恢复

- 会话历史以服务端数据库为准；客户端不能提交系统提示、已完成工具结果或伪造确认历史。
- 使用 AI SDK UI Message Stream，通过 SSE 输出文本、工具状态和结构化结果。[协议文档](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol)
- AI 执行由后端独立管理，与现有同步队列分开。关闭面板或网络断开不等于取消。
- 首版断线后通过历史与执行快照恢复显示，活动执行每 3 秒查询一次；不实现逐 token 断点续传。
- 停止操作先请求后端取消，再终止前端接收。已提交的研究记录修改和已创建的同步任务不回滚，结果明确展示。
- 服务重启后，未完成生成标记为中断，不自动重放写操作；持久化的待确认操作可在重新登录后继续处理，但必须重新校验版本。
- 默认每个会话同时执行一轮；每轮最多 6 次模型请求、12 次工具执行、每次模型输出上限 4096 tokens，活动执行总时限 180 秒。等待用户确认不计入时限，以上限额由后端配置。
- 模型上下文使用最近 10 个完整交互轮及本轮上下文，保持工具调用与结果成对。首版不增加额外的自动摘要模型调用。
- 记录模型、耗时、工具结果及供应商返回的 token 用量；供应商未返回用量时标为未知，不推算费用。

## 4. 接口、存储与部署变更

所有新增接口位于 `/api/v1/ai`，使用独立路由模块。

| 接口 | 职责 |
| --- | --- |
| `GET /settings`、`PUT /settings` | 读取脱敏配置、更新模型服务设置 |
| `POST /settings/test` | 测试已保存配置的必要能力 |
| `GET /conversations`、`POST /conversations` | 会话列表与创建 |
| `GET /conversations/{id}` | 获取会话历史、活动执行和待确认操作 |
| `POST /conversations/{id}/runs` | 提交新消息及页面上下文，返回 SSE |
| `GET /runs/{id}` | 获取执行状态与持久化结果快照 |
| `POST /runs/{id}/cancel` | 请求停止执行 |
| `POST /approvals/{id}/decision` | 接受或拒绝已保存的操作，并流式返回后续结果 |

运行创建请求携带客户端生成的请求 ID，用于网络重试去重。运行状态区分执行中、待确认、成功、失败、取消和中断；每个状态均有明确的界面展示。

通过新增 Alembic 迁移建立模型配置、会话、消息、执行及工具调用记录；确认信息保存在工具调用记录中。会话关联当前单管理员。已有研究记录补充版本号，旧数据从初始版本开始。

前端新增聊天传输模块，沿用现有会话失效处理，不复用只支持 `response.json()` 的普通请求函数。Caddy 验证 SSE 实时转发、连接关闭及超时行为。

锁定新增依赖版本，更新前后端锁文件。无需增加 Redis、向量数据库、Node 服务或额外容器。数据库备份覆盖新增配置密文、会话和执行记录。

## 5. 开发顺序与验收

| 阶段 | 主要工作 | 完成标准 |
| --- | --- | --- |
| 1. 业务基础 | 提取共用业务模块，增加研究记录版本校验和 AI 数据迁移 | 原有查询、修改、同步测试通过，页面能正确处理编辑冲突 |
| 2. 模型接入 | 配置界面、密钥加密、两种协议适配、能力测试 | 模拟供应商验证两种协议；错误可定位，密钥不出现在响应和日志 |
| 3. 只读聊天 | 全局面板、会话持久化、SSE、上下文、只读工具和结果卡片 | 能查询当前 Alpha，跨页面保留会话，断线后恢复结果 |
| 4. 操作闭环 | 修改预览、确认、幂等、任务操作和页面刷新 | 确认前无写入，重复确认只执行一次，冲突不覆盖数据 |
| 5. 整体验收 | 自动化回归、浏览器验证、Docker 升级验证和真实模型联调 | 满足以下场景并记录实际验证边界 |

测试覆盖：

- **模型接入：** 两种协议、错误 Key、错误模型、工具能力缺失、流式中断、429、超时，以及错误正文脱敏。
- **上下文与查询：** 选中对象指代准确；切换页面不串对象；换手率 15% 正确转换为 `0.15`；空指标保持为空；PnL 缓存缺失可解释。
- **权限与确认：** 未登录、会话失效、伪造工具结果、拒绝确认、篡改确认目标、重复提交、批量修改中存在无效 ID。
- **并发与恢复：** 页面与 AI 同时编辑产生版本冲突；执行中刷新和断线；取消前后状态一致；服务重启不重复修改或创建任务。
- **界面：** 聊天与详情同时使用、窄屏切换、键盘焦点、收缩后继续执行、未保存草稿保留、退出登录后清理界面状态。
- **回归：** 执行后端 Ruff/Pytest、前端类型检查与构建、Playwright，以及独立 PostgreSQL/Docker 的迁移和持久化验证。

自动化测试使用隔离数据库、合成 Alpha 和模拟模型服务，不调用真实供应商或 WorldQuant。真实模型联调在用户配置完成后进行，分别记录流式回答与业务工具调用是否通过。实际供应商未确定前，兼容性仅能由模拟协议测试覆盖，不能宣称已完成真实服务验证。

## 6. 实施落点

- `backend/app/business.py`：REST 与 AI 共用的业务操作；调用方管理事务，任务提交后才唤醒同步执行器。
- `backend/app/ai/contracts.py`、`provider.py`：输入契约、两种模型协议、合成能力测试和安全错误提示。
- `backend/app/ai/tools.py`：白名单工具，限制参数和返回体；写入分为预览与执行。
- `backend/app/ai/runtime.py`：独立任务、持久化执行、确认事务、调用预算、取消、历史和 SSE 投影。
- `backend/app/ai/routes.py`：沿用 Cookie 和来源检查的 AI API。
- `frontend/src/ai/`：模型设置、AI SDK 传输、全局面板及固定业务卡片。宽度不足 1440px 时切换聊天与详情/任务显示；640px 以下聊天占满屏幕。
- 数据库迁移 `0002` 增加 AI 表与 `research.version`；研究记录的普通 PATCH 必须携带 `version`，批量 PATCH 必须携带完整 `versions` 映射。
- 失败、取消或中断的轮次使用服务端保存的用户消息与工具审计事实补足完整历史，不重放未配对的模型调用，也不增加摘要模型请求。

模型设置变更会使现有待确认轮次失效，需要停止该轮并重新预览。自动化仅验证固定模拟行为与协议；真实模型对自然语言指代和工具选择的效果，需要配置供应商后另行联调。

## 7. 界面基线与本次恢复

个人信息与登录体验以会话“打磨个人信息模块与登录体验”的最终快照 `f781203` 为基线，保留账户权限、会话有效期、提交/模拟用量、本地每日 10,000 次模拟额度和固定底部分页。AI 功能沿用此基线，不另建视觉主题。

- `scope_sketch`：紧凑研究工作空间，个人信息设置、全局聊天、查询结果、修改确认；主要流程为查询、预览、确认和查看业务结果。
- `lark_style_recipe`：白色主区域，侧栏直接使用 `#f9f9f9`、选中项 `#1f23290d`，主操作使用 `#1456f0`；4px 间距基准，按用户的紧凑偏好以 8/12/16px 排布。普通卡片无阴影，边框轻，控件圆角 4–6px、消息与结果容器 8px。
- `emphasis_budget`：页面标题 600，区域标题和选中导航 500，正文、指标、提示、按钮和链接 400。颜色用于操作、焦点和真实状态。
- `layout_signature_usage` / `top_nav_policy`：保留左侧主导航与 56px 工作区顶栏；业务页面独立滚动。页面挂载容器保持可收缩的 flex 高度链，列表仅表体滚动，分页保持底部。
- `right_rail_policy`：聊天默认 420px、可调整 360–640px；桌面端预留空间，按剩余业务宽度调整账户表单；窄屏显示遮罩并隔离背景焦点，640px 以下占满屏幕。收起保留会话、生成任务与草稿，Esc 关闭当前面板。
- `ud_control_coverage`：保留 Semi 的 Button、Input、Select、Tag、Banner、TextArea 与 Pagination 语义及交互状态，统一颜色、字重和间距；自定义部分限布局、业务结果和前后差异。
- `icon_plan` / `media_decision`：本次新增 AI 区域采用文字操作，无自绘图标或插画；侧栏与登录恢复原会话的简洁文字入口。辅助聊天空间优先用于结果和编辑，没有营销 Hero 或装饰媒体。
- `verification_plan`：账户能力与 AI 回归；390/850/1280/1440/1920px 布局，聊天最大宽度、表格滚动、底部分页、窄屏遮罩、键盘操作和跨页草稿。截图均使用合成数据。