my-home/worldquant-alpha-system
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add AI research chatbot with confirmed business tools

Browse Source
This commit is contained in:
yuxuanhui
2026-09-07 23:02:55 +08:00
parent 3cd280d068
commit 79ab20b4ea
44 changed files with 4647 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+33 -8
View File
@@ -2,7 +2,7 @@
个人单账户系统。首期实现平台资料、Alpha 同步与查询、PnL 缓存、本地备注/标签/收藏/研究状态。平台接口只读，认证除外；不会回测、触发检查、回写属性或提交 Alpha。
需求与后续路线图见 [项目方案](docs/project-plan.md)。前端 React 19 + TypeScript + Semi Design，后端 Python 3.12 + FastAPI + HTTPX + SQLAlchemy，PostgreSQL 保存数据，Caddy 提供 Web 入口。前后端独立依赖、独立构建，所有部署文件位于根目录。
需求与后续路线图见 [项目方案](docs/project-plan.md)，AI 助手范围见 [开发计划](docs/ai-chatbot-plan.md)。前端 React 19 + TypeScript + Semi Design，后端 Python 3.12 + FastAPI + HTTPX + SQLAlchemy，PostgreSQL 保存数据，Caddy 提供 Web 入口。前后端独立依赖、独立构建，所有部署文件位于根目录。
## 本机启动
@@ -27,6 +27,22 @@ docker compose ps
平台未返回的资料与指标保留为空。数值筛选采用平台原始单位，例如 Turnover `0.15` 表示 15%。日期筛选边界为 UTC；时间显示采用个人页的时区偏好。
## AI 研究助手
1. 在“个人信息 → 大模型服务”填写 Base URL、API Key、模型标识，明确选择 Chat Completions 或 Responses。
2. Base URL 是后端能够访问的 API 根地址，例如 `https://供应商域名/v1`，是否带 `/v1` 以供应商说明为准；无需拼接 `/chat/completions` 或 `/responses`。容器中的 `localhost` 指容器自身。
3. 保存配置不会发起模型请求。点击“测试连接”后，系统用少量合成文本和无副作用工具分别测试回答、流式输出、工具往返；测试可能按供应商规则计费。
4. 全部通过后勾选“启用研究助手”并保存。更换地址、模型、协议或密钥后必须重新测试；更换地址必须重填密钥。
5. 点击右下角“AI 研究助手”或顶部“AI 助手”，新建会话开始使用。可以询问当前 Alpha、筛选换手率不超过 15% 的记录、查看缓存 PnL，或提出研究记录修改和同步任务操作。
聊天默认收起，展开宽度为 420px，左边缘可拖动或用左右方向键调整到 360–640px。宽屏聊天与详情并排；窄屏打开聊天时暂时隐藏详情和任务面板，收起后恢复。页面切换保留当前聊天、筛选和研究草稿，草稿内容不会自动发送给模型。
本地研究修改、批量标签/状态、创建/取消/重试同步任务均先显示预览。只有点击“确认执行”才会写入；文字中的同意不能替代按钮。预览固定目标及版本，批量最多 100 条。页面与 AI 同时编辑出现冲突时不会覆盖新版本；复制需要保留的草稿后载入最新记录再编辑。任务进度沿用业务轮询；停止聊天不会取消已创建的同步任务。
面板收起、切换会话和网络断开不会停止后端执行。刷新后从服务端历史与快照恢复，活动执行每 3 秒更新；不提供逐 token 续传。“停止生成”请求后端取消，再关闭前端接收。服务重启会将生成中的轮次标记为中断，不自动重放；待确认记录在重新登录后仍可处理，但重新检查版本。模型配置变更后，旧的待确认轮次需停止并重新预览。
模型不可用或未配置时，原有业务功能继续使用。API Key 仅加密存储于数据库，不返回浏览器；发送聊天时，相关本地业务结果会发送至你指定的模型服务。首版没有 MCP、知识检索、回测、多 Agent 或平台回写。
## 公网 HTTPS 部署
`compose.public.yaml` 是独立配置，不与本机配置叠加。先在服务器完成上面的密钥初始化，将 `.env` 中 `DOMAIN` 改为自己的域名（无协议、路径、端口）。DNS 指向服务器，允许入站 TCP 80/443，UDP 443 可选。
@@ -46,11 +62,15 @@ docker compose -f compose.public.yaml logs --tail=100 web
| --- | --- |
| `ADMIN_USERNAME` / `ADMIN_PASSWORD` | 仅首次空库初始化管理员，重启不会重置现有密码 |
| `POSTGRES_PASSWORD` | 数据库密码；初始化脚本使用随机十六进制，避免连接 URL 转义问题 |
| `ENCRYPTION_KEY` | 独立 Fernet 密钥，加密数据库中的 WorldQuant 密码 |
| `ENCRYPTION_KEY` | 独立 Fernet 密钥，加密数据库中的 WorldQuant 密码和模型 API Key |
| `LOCAL_PORT` | 本机入口端口，默认 8080 |
| `DOMAIN` | 公网域名 |
| `AI_REQUEST_LIMIT` | 每轮模型请求上限，默认 6 |
| `AI_TOOL_LIMIT` | 每轮工具执行上限，默认 12 |
| `AI_OUTPUT_TOKENS` | 每次模型输出上限，默认 4096 |
| `AI_TIMEOUT` | 每轮累计活动执行时限（秒），默认 180，等待确认不计入 |
WorldQuant 密码仅在后端解密。平台 Cookie 仅保存在后端内存，进程重启后重新认证。前端不保存密码或 Cookie 副本；日志与响应不输出平台认证正文。`.env` 不进入 Docker 构建上下文，应与数据库备份分别安全保管。丢失 `ENCRYPTION_KEY` 后须重新输入平台密码；切勿在正常升级时重新生成它。
WorldQuant 密码仅在后端解密。平台 Cookie 仅保存在后端内存，进程重启后重新认证。前端不保存密码或 Cookie 副本；日志与响应不输出平台认证正文。`.env` 不进入 Docker 构建上下文，应与数据库备份分别安全保管。丢失 `ENCRYPTION_KEY` 后须重新输入平台密码和模型 API Key；切勿在正常升级时重新生成它。
修改系统密码（同时撤销所有系统会话）：
@@ -76,7 +96,7 @@ docker compose logs --tail=100 backend
## 备份与恢复
以下为本机配置命令；公网统一补上 `-f compose.public.yaml`，自定义项目名时保持相同 `-p`。数据库备份包括平台快照、研究记录、账户密文和任务。备份文件仍属于私有数据。
以下为本机配置命令；公网统一补上 `-f compose.public.yaml`，自定义项目名时保持相同 `-p`。数据库备份包括平台快照、研究记录及版本、账户密文、模型配置密文、AI 会话/消息/执行/工具确认记录和同步任务。备份文件仍属于私有数据。
```bash
mkdir -p backups
@@ -100,7 +120,7 @@ docker compose exec -T db pg_restore -U wq -d wq --clean --if-exists --no-owner
docker compose up -d --wait
```
跨机器恢复时同时使用原来的 `ENCRYPTION_KEY`。恢复后运行中的任务自动回到队列，按已提交检查点继续；平台会话可能要求重新连接或人工验证。
跨机器恢复时同时使用原来的 `ENCRYPTION_KEY`。恢复后运行中的同步任务自动回到队列，按已提交检查点继续；平台会话可能要求重新连接或人工验证。
## 本地开发与验证
@@ -124,9 +144,9 @@ pnpm exec playwright install chromium
pnpm test
```
浏览器测试自动启动临时数据库、模拟平台 API 和 Vite，使用 620 条明确标记 `TEST` 的合成 Alpha。不会向正式数据库写入样例。测试验证系统登录、账户连接、多页同步、SUPER 详情、备注与收藏在刷新后保留、PnL、超过 500 条 CSV 及退出。截图写入忽略目录 `output/playwright/`。
浏览器测试自动启动临时数据库、模拟平台 API 和 Vite，使用 620 条明确标记 `TEST` 的合成 Alpha。不会向正式数据库写入样例。测试验证模型配置、查询卡片、修改预览及确认、草稿冲突、收起及刷新恢复、取消，以及系统登录、账户连接、多页同步、SUPER 详情、备注与收藏在刷新后保留、PnL、超过 500 条 CSV 及退出。截图写入忽略目录 `output/playwright/`。
需要重跑 Docker 持久化和备份验收时，先停止占用 8080 的本机实例（不删除卷），创建独立测试环境。以下脚本只接受 `wq-alpha-acceptance*` 项目名：
需要重跑 Docker 持久化和备份验收时，创建独立测试环境，并在测试 env 文件中选择空闲 `LOCAL_PORT`（例如 18089），无需停止正式实例。以下脚本只接受 `wq-alpha-acceptance*` 项目名：
```bash
mkdir -p .local
@@ -146,7 +166,7 @@ uv run uvicorn tests.browser_server:create_test_app --factory --host 127.0.0.1 -
WQ_DEV_API=http://127.0.0.1:18000 pnpm dev --port 5179
```
访问 `http://127.0.0.1:5179`，系统测试密码 `browser-test-password`，平台邮箱 `test@example.com`、密码任意。每次停止服务即丢弃临时测试数据。
访问 `http://127.0.0.1:5179`，系统测试密码 `browser-test-password`，平台邮箱 `test@example.com`、密码任意。模型 Base URL 可填 `https://model.test/v1`、模型标识 `test-model`、API Key 任意；该测试服务始终使用确定性的内存模拟模型，不发起模型网络请求。每次停止服务即丢弃临时测试数据。
开发真实后端时显式配置 `DATABASE_URL` 指向自己的开发 PostgreSQL，设置 `ADMIN_PASSWORD`、`ENCRYPTION_KEY`、`PUBLIC_ORIGIN=http://localhost:5173`，执行迁移后用 `uv run uvicorn app.main:create_app --factory --host 127.0.0.1 --port 8000` 启动。`pnpm dev` 默认代理到此地址。生产 Compose 不开放开发数据库端口。
@@ -159,6 +179,9 @@ FastAPI 的 `/openapi.json` 与 `/docs` 可在后端开发端口访问；生产
- `/api/v1/alphas`：服务端筛选与排序、详情、本地研究记录、批量编辑、流式 CSV。
- `/api/v1/alphas/{id}/pnl`：只读缓存；刷新通过 `pnl_refresh` 任务。
- `/api/v1/sync-jobs`：创建任务立即返回 202 和 ID，查询、取消与重试。
- `/api/v1/ai`：脱敏模型配置与测试、会话历史、SSE 执行、执行快照、取消及确认。新执行只接收 `request_id`、`message`、`context`；同一会话重复请求 ID 返回原运行，参数变化返回 409。
研究记录 PATCH 现在必须提供读取时的 `version`；批量编辑必须提供每个目标 ID 的 `versions` 映射。`0002` 迁移给旧研究记录设置初始版本 1，不修改其内容。版本冲突返回 409。
写请求需 `X-WQ-Request: 1`；浏览器跨站写入被拒绝。Alpha 平台快照、`research` 本地研究、`pnl_cache` 分开存储。研究状态固定为 `inbox/candidate/optimizing/archived`；平台类型、语言、状态按原值显示。
@@ -176,4 +199,6 @@ curl -f http://localhost:8080/api/v1/health
平台任务失败时先查看任务面板的错误及失败 ID。401 登录失效需重新登录系统；平台人工验证需回个人页；429 会按平台等待时间自动重试。密钥损坏/丢失时重新配置平台凭据。不要为排错把密码、认证响应或 Cookie 加入日志。
AI 模型兼容性由模拟 Chat Completions/Responses HTTP 流与真实 SDK 适配器验证；未配置真实供应商前，不能保证其工具选择质量、模型权限或网关兼容性。真实联调请分别记录流式回答与业务工具调用是否成功。
实现使用旧项目已知请求形态并对模拟上游做自动化验证。WorldQuant 当前真实账号权限、人工验证页面行为、实际数据 schema、真实账户全量同步及公网证书签发，均需要在自己的账户/域名完成只读联调；未取得该证据前不宣称已验证。验收实测结果见 [验收记录](docs/verification.md)。