Skip to content

Commit a149218

Browse files
Activer007季成健
Activer007
authored and
季成健
committed
feat: [issue ZhuLinsen#1199 PR1] add settings field help dialog infrastructure (ZhuLinsen#1204)
* feat: add settings field help infrastructure * fix: avoid online fallback in bot name routing test Resolve natural-language stock-name candidates through deterministic local partial matches before invoking the broader name resolver. This keeps common aliases like 茅台 on the fast local path and prevents offline CI from waiting on AkShare network fallback. Guard the async dispatcher test with an assertion that AkShare fallback is not called for the local alias case. * test: isolate schedule time provider failure case The schedule-time provider failure test could fail when SCHEDULE_TIME was present in the process environment before importing main. In that case _INITIAL_PROCESS_ENV marks it as an explicit override, the provider returns the env value, and ConfigManager.read_config_map is never called, so the expected RuntimeError is not raised. Patch _INITIAL_PROCESS_ENV in the test to model the intended no-process-override scenario and keep the assertion independent of the shell environment used by scripts/ci_gate.sh. * fix: improve settings help dialog accessibility Trap keyboard focus inside the settings help dialog while it is open and return focus to the trigger on close. Keep the backdrop click target out of the tab order and cover the focus loop behavior in the settings field test. * feat: add help entry and multilingual support for system settings page * feat: add maintenance guidelines for settings help documentation * fix: clarify WebUI bind settings and toast visibility * chore: remove trailing blank line from settings help
1 parent 30fdb59 commit a149218

40 files changed

Lines changed: 9329 additions & 17 deletions

‎.qoder/repowiki/zh/content/API参考文档/API参考文档.md‎

Lines changed: 467 additions & 0 deletions
Large diffs are not rendered by default.

‎.qoder/repowiki/zh/content/Web界面系统/Web界面系统.md‎

Lines changed: 469 additions & 0 deletions
Large diffs are not rendered by default.

‎.qoder/repowiki/zh/content/安全考虑/安全考虑.md‎

Lines changed: 364 additions & 0 deletions
Large diffs are not rendered by default.

‎.qoder/repowiki/zh/content/开发者指南.md‎

Lines changed: 358 additions & 0 deletions
Large diffs are not rendered by default.

‎.qoder/repowiki/zh/content/快速开始.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
# 快速开始
2+
3+
<cite>
4+
**本文引用的文件**
5+
- [README.md](file://README.md)
6+
- [docs/DEPLOY.md](file://docs/DEPLOY.md)
7+
- [docs/full-guide.md](file://docs/full-guide.md)
8+
- [docs/FAQ.md](file://docs/FAQ.md)
9+
- [.github/workflows/daily_analysis.yml](file://.github/workflows/daily_analysis.yml)
10+
- [docker/Dockerfile](file://docker/Dockerfile)
11+
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
12+
- [requirements.txt](file://requirements.txt)
13+
- [main.py](file://main.py)
14+
- [scripts/check_env.py](file://scripts/check_env.py)
15+
- [src/config.py](file://src/config.py)
16+
</cite>
17+
18+
## 目录
19+
1. [简介](#简介)
20+
2. [项目结构](#项目结构)
21+
3. [核心组件](#核心组件)
22+
4. [架构总览](#架构总览)
23+
5. [详细组件分析](#详细组件分析)
24+
6. [依赖关系分析](#依赖关系分析)
25+
7. [性能考虑](#性能考虑)
26+
8. [故障排查指南](#故障排查指南)
27+
9. [结论](#结论)
28+
10. [附录](#附录)
29+
30+
## 简介
31+
本指南面向首次部署与使用“股票智能分析系统”的用户，提供三种部署方式的完整步骤：GitHub Actions 一键部署、本地部署、Docker 部署。文档将详细说明环境变量配置、AI 模型 API 密钥设置、通知渠道配置与自选股列表设置，并给出命令示例与配置要点。同时包含常见问题排查与最佳实践，帮助新手在最短时间内完成首次部署与基本配置。
32+
33+
## 项目结构
34+
系统采用前后端分离与模块化设计，核心入口为 Python 主程序，提供命令行模式、定时任务模式与 Web 服务模式；Docker 镜像内置前端静态资源，支持一键部署；GitHub Actions 提供零服务器的自动化执行。
35+
36+
```mermaid
37+
graph TB
38+
subgraph "本地/服务器"
39+
A["main.py<br/>主程序入口"]
40+
B["src/config.py<br/>配置管理"]
41+
C["requirements.txt<br/>依赖清单"]
42+
D["docker/Dockerfile<br/>镜像构建"]
43+
E["docker/docker-compose.yml<br/>编排"]
44+
end
45+
subgraph "GitHub Actions"
46+
F[".github/workflows/daily_analysis.yml<br/>工作流"]
47+
end
48+
subgraph "外部服务"
49+
G["AI 模型提供商<br/>Anspire/AIHubMix/Gemini/OpenAI 等"]
50+
H["数据源<br/>AkShare/Tushare/YFinance/Longbridge 等"]
51+
I["通知渠道<br/>企业微信/飞书/Telegram/Discord/Slack/邮件等"]
52+
end
53+
A --> B
54+
A --> C
55+
D --> A
56+
E --> A
57+
F --> A
58+
A --> G
59+
A --> H
60+
A --> I
61+
```
62+
63+
图表来源
64+
- [main.py:1-120](file://main.py#L1-L120)
65+
- [src/config.py:1-120](file://src/config.py#L1-L120)
66+
- [requirements.txt:1-68](file://requirements.txt#L1-L68)
67+
- [docker/Dockerfile:1-85](file://docker/Dockerfile#L1-L85)
68+
- [docker/docker-compose.yml:1-69](file://docker/docker-compose.yml#L1-L69)
69+
- [.github/workflows/daily_analysis.yml:1-120](file://.github/workflows/daily_analysis.yml#L1-L120)
70+
71+
章节来源
72+
- [README.md:63-168](file://README.md#L63-L168)
73+
- [docs/DEPLOY.md:1-150](file://docs/DEPLOY.md#L1-L150)
74+
75+
## 核心组件
76+
- 主程序入口：负责解析命令行参数、加载配置、执行分析流程、启动 Web/FastAPI 服务、调度定时任务与通知推送。
77+
- 配置管理：统一从 .env/.env 文件或 GitHub Actions Secrets/Variables 读取配置，提供类型安全与校验。
78+
- 数据源适配：多数据源优先级与自动切换，支持 A/H/US 多市场。
79+
- 通知通道：支持多种渠道与路由策略，具备长消息分块与 Markdown 图片转换能力。
80+
- Docker 镜像与编排：多阶段构建前端与后端，暴露 Web 端口，支持数据持久化与健康检查。
81+
- GitHub Actions 工作流：定时触发与手动触发，自动注入 Secrets/Variables，上传报告产物。
82+
83+
章节来源
84+
- [main.py:205-368](file://main.py#L205-L368)
85+
- [src/config.py:32-120](file://src/config.py#L32-L120)
86+
- [docker/Dockerfile:61-85](file://docker/Dockerfile#L61-L85)
87+
- [.github/workflows/daily_analysis.yml:356-442](file://.github/workflows/daily_analysis.yml#L356-L442)
88+
89+
## 架构总览
90+
系统支持三种部署形态，核心流程一致：加载配置 → 读取自选股 → 获取数据 → AI 分析 → 生成报告 → 推送通知 → 可选：创建飞书云文档与自动回测。
91+
92+
```mermaid
93+
sequenceDiagram
94+
participant U as "用户/系统"
95+
participant M as "main.py"
96+
participant CFG as "配置管理"
97+
participant PIPE as "分析流水线"
98+
participant DS as "数据源"
99+
participant LLM as "AI 模型"
100+
participant NOTI as "通知通道"
101+
participant DOC as "飞书云文档"
102+
U->>M : 启动/定时触发/手动触发
103+
M->>CFG : 加载 .env/Secrets/Variables
104+
M->>PIPE : 初始化流水线
105+
PIPE->>DS : 拉取日线/实时/新闻/资金流
106+
DS-->>PIPE : 原始数据
107+
PIPE->>LLM : 结构化分析请求
108+
LLM-->>PIPE : 分析结果
109+
PIPE-->>M : 汇总结果
110+
M->>NOTI : 推送通知/合并推送
111+
M->>DOC : 可选：生成飞书云文档
112+
M-->>U : 日志/报告/产物
113+
```
114+
115+
图表来源
116+
- [main.py:434-629](file://main.py#L434-L629)
117+
- [src/config.py:193-200](file://src/config.py#L193-L200)
118+
- [.github/workflows/daily_analysis.yml:356-442](file://.github/workflows/daily_analysis.yml#L356-L442)
119+
120+
## 详细组件分析
121+
122+
### GitHub Actions 一键部署（推荐）
123+
- 适用场景：零服务器、自动定时、无需运维。
124+
- 优点：免费额度高、自动执行、无需维护。
125+
- 缺点：无状态、定时可能有延迟、无法提供 HTTP API。
126+
- 关键步骤：
127+
1) Fork 仓库并在 Settings → Secrets and variables → Actions 添加必要的 Secrets/Variables。
128+
2) 启用 Actions 工作流。
129+
3) 手动触发或等待定时执行。
130+
- 常用配置要点：
131+
- 至少配置一项 AI 模型密钥（如 ANSPIRE_API_KEYS、AIHUBMIX_KEY、GEMINI_API_KEY、OPENAI_API_KEY）。
132+
- 至少配置一个通知渠道（如 WECHAT_WEBHOOK_URL、TELEGRAM、EMAIL 等）。
133+
- 设置 STOCK_LIST（自选股列表，逗号分隔）。
134+
- 可选：配置搜索服务（ANSPIRE_API_KEYS、SERPAPI_API_KEYS、TAVILY_API_KEYS 等）。
135+
- 可选：REPORT_TYPE、REPORT_LANGUAGE、SINGLE_STOCK_NOTIFY、MERGE_EMAIL_NOTIFICATION 等推送行为配置。
136+
- 定时时间：默认每周一至周五 18:00（北京时间），可通过 cron 修改。
137+
- 手动测试：Actions 页面选择工作流 → Run workflow → 选择模式（full/market-only/stocks-only）。
138+
139+
章节来源
140+
- [README.md:65-139](file://README.md#L65-L139)
141+
- [.github/workflows/daily_analysis.yml:1-472](file://.github/workflows/daily_analysis.yml#L1-L472)
142+
- [docs/full-guide.md:42-191](file://docs/full-guide.md#L42-L191)
143+
144+
### 本地部署与 Docker 部署
145+
- 本地部署（直接部署）：
146+
- 安装 Python 3.10+，创建虚拟环境，安装依赖。
147+
- 复制 .env.example 为 .env，按需填写 AI 模型、通知渠道、自选股、搜索服务等。
148+
- 运行 python main.py，或使用 --schedule 启用定时任务模式，--webui/--webui-only 启动 Web 界面。
149+
- Docker 部署（推荐）：
150+
- 安装 Docker，准备 .env，一键 docker-compose up -d。
151+
- 默认暴露 8000 端口，支持数据持久化（data/logs/reports）。
152+
- 可选：挂载本地 static 目录覆盖前端静态资源，或通过 .env 指定 API_PORT。
153+
- 常用管理命令：logs、restart、build --no-cache、exec bash、手动执行一次分析。
154+
- 代理配置：Docker 方式在 compose 中设置 http_proxy/https_proxy；本地方式在 .env 中设置 USE_PROXY/PROXY_HOST/PROXY_PORT。
155+
156+
章节来源
157+
- [docs/DEPLOY.md:18-99](file://docs/DEPLOY.md#L18-L99)
158+
- [docs/DEPLOY.md:101-150](file://docs/DEPLOY.md#L101-L150)
159+
- [docker/Dockerfile:22-85](file://docker/Dockerfile#L22-L85)
160+
- [docker/docker-compose.yml:13-69](file://docker/docker-compose.yml#L13-L69)
161+
- [docs/DEPLOY.md:227-247](file://docs/DEPLOY.md#L227-L247)
162+
163+
### 环境变量与配置要点
164+
- 必填项（至少满足其一）：
165+
- AI 模型：ANSPIRE_API_KEYS、AIHUBMIX_KEY、GEMINI_API_KEY、ANTHROPIC_API_KEY、OPENAI_API_KEY。
166+
- 通知渠道：至少配置一个（如 WECHAT_WEBHOOK_URL、FEISHU_WEBHOOK_URL、TELEGRAM、EMAIL、DISCORD、SLACK、自定义 Webhook 等）。
167+
- 自选股：STOCK_LIST（逗号分隔的股票代码）。
168+
- 搜索服务：ANSPIRE_API_KEYS、SERPAPI_API_KEYS、TAVILY_API_KEYS、BOCHA_API_KEYS、BRAVE_API_KEYS、MINIMAX_API_KEYS、SEARXNG_BASE_URLS。
169+
- 可选项（提升体验）：
170+
- SCHEDULE_ENABLED、SCHEDULE_TIME、MARKET_REVIEW_ENABLED、REPORT_TYPE、REPORT_LANGUAGE、SINGLE_STOCK_NOTIFY、MERGE_EMAIL_NOTIFICATION、ANALYSIS_DELAY、MAX_WORKERS、ENABLE_CHIP_DISTRIBUTION、REALTIME_SOURCE_PRIORITY 等。
171+
- GitHub Actions 特有：
172+
- LITELLM_CONFIG/LITELLM_CONFIG_YAML、LLM_CHANNELS、LLM_PRIMARY_*、LLM_SECONDARY_*、LLM_GEMINI_*、LLM_AIHUBMIX_*、LLM_OPENAI_*、LLM_ANTHROPIC_*、LLM_DEEPSEEK_*、LLM_ANSPIRE_*、LLM_MOONSHOT_*、LLM_DASHSCOPE_*、LLM_ZHIPU_*、LLM_MINIMAX_*、LLM_VOLCENGINE_*、LLM_SILICONFLOW_*、LLM_OPENROUTER_*、LLM_OLLAMA_*。
173+
- 数据源：TUSHARE_TOKEN、LONGBRIDGE_*。
174+
- 通知路由：NOTIFICATION_REPORT_CHANNELS、NOTIFICATION_ALERT_CHANNELS、NOTIFICATION_SYSTEM_ERROR_CHANNELS。
175+
- 其他：REPORT_SUMMARY_ONLY、REPORT_TEMPLATES_DIR、REPORT_RENDERER_ENABLED、REPORT_INTEGRITY_ENABLED、REPORT_HISTORY_COMPARE_N、MARKDOWN_TO_IMAGE_CHANNELS、MD2IMG_ENGINE、PREFETCH_REALTIME_QUOTES。
176+
177+
章节来源
178+
- [docs/full-guide.md:193-200](file://docs/full-guide.md#L193-L200)
179+
- [.github/workflows/daily_analysis.yml:60-355](file://.github/workflows/daily_analysis.yml#L60-L355)
180+
181+
### 命令行与运行模式
182+
- 常用命令：
183+
- python main.py：正常运行（按配置执行分析与推送）。
184+
- python main.py --debug：调试模式，输出详细日志。
185+
- python main.py --dry-run：仅获取数据，不进行 AI 分析。
186+
- python main.py --stocks 600519,hk00700,AAPL：指定分析特定股票。
187+
- python main.py --no-notify：不发送推送通知。
188+
- python main.py --check-notify：仅检查通知配置，不发送。
189+
- python main.py --single-notify：启用单股推送模式。
190+
- python main.py --schedule：启用定时任务模式。
191+
- python main.py --market-review：仅运行大盘复盘。
192+
- python main.py --serve-only：仅启动 FastAPI 服务（不自动分析）。
193+
- python main.py --webui/--webui-only：启动 Web 管理界面。
194+
- Web 界面：默认监听 0.0.0.0:8000，云服务器需设置 WEBUI_HOST=0.0.0.0 并放行安全组端口。
195+
196+
章节来源
197+
- [main.py:205-368](file://main.py#L205-L368)
198+
- [docs/DEPLOY.md:131-146](file://docs/DEPLOY.md#L131-L146)
199+
200+
### 配置验证与环境检查
201+
- 使用 scripts/check_env.py 进行配置加载、数据库、数据源、LLM、通知的验证与测试。
202+
- 常用参数：--config、--db、--fetch、--llm、--notify、--stock、--all。
203+
- 该脚本可辅助定位配置错误、网络连通性与通知通道可用性问题。
204+
205+
章节来源
206+
- [scripts/check_env.py:1-494](file://scripts/check_env.py#L1-L494)
207+
208+
## 依赖关系分析
209+
- Python 依赖：dotenv、schedule、SQLAlchemy、litellm、requests、fastapi/uvicorn、通知渠道 SDK 等。
210+
- Docker 镜像：多阶段构建，前端在镜像构建阶段打包，后端运行阶段安装依赖，暴露 8000 端口，设置健康检查。
211+
- GitHub Actions：工作流中注入 Secrets/Variables，按 mode 执行不同分析模式，上传 reports/logs 产物。
212+
213+
```mermaid
214+
graph LR
215+
R["requirements.txt"] --> IMG["Docker 镜像构建"]
216+
IMG --> RUN["容器运行"]
217+
W["daily_analysis.yml"] --> RUN
218+
RUN --> OUT["分析报告/日志产物"]
219+
```
220+
221+
图表来源
222+
- [requirements.txt:1-68](file://requirements.txt#L1-L68)
223+
- [docker/Dockerfile:10-55](file://docker/Dockerfile#L10-L55)
224+
- [.github/workflows/daily_analysis.yml:356-442](file://.github/workflows/daily_analysis.yml#L356-L442)
225+
226+
章节来源
227+
- [requirements.txt:1-68](file://requirements.txt#L1-L68)
228+
- [docker/Dockerfile:16-85](file://docker/Dockerfile#L16-L85)
229+
- [.github/workflows/daily_analysis.yml:356-442](file://.github/workflows/daily_analysis.yml#L356-L442)
230+
231+
## 性能考虑
232+
- 并发与限流：合理设置 MAX_WORKERS，避免免费数据源限流；必要时启用 ANALYSIS_DELAY 减少 API 压力。
233+
- 数据源优先级：根据稳定性与字段完整性调整 REALTIME_SOURCE_PRIORITY。
234+
- 代理与网络：国内服务器访问 Gemini/OpenAI 需要代理时，本地设置 USE_PROXY/PROXY_HOST/PROXY_PORT；Docker 在 compose 中设置 http_proxy/https_proxy。
235+
- 资源限制：Docker 可通过 deploy.resources 限制内存，避免资源争用。
236+
- WebUI 静态资源：Docker 部署需确保前端已打包进镜像，否则会出现 UI 元素异常或布局错乱。
237+
238+
章节来源
239+
- [docs/DEPLOY.md:227-247](file://docs/DEPLOY.md#L227-L247)
240+
- [docs/DEPLOY.md:306-313](file://docs/DEPLOY.md#L306-L313)
241+
- [docs/DEPLOY.md:320-343](file://docs/DEPLOY.md#L320-L343)
242+
243+
## 故障排查指南
244+
- GitHub Actions 未触发或延迟：
245+
- 确认仓库已启用 Actions；工作流可能有 5-15 分钟延迟；长时间无提交可能导致 workflow 被禁用。
246+
- API 访问超时/429 限流：
247+
- 检查代理配置；减少并发与请求频率；适当增加 ANALYSIS_DELAY。
248+
- 数据获取失败/被限流：
249+
- 减少自选股数量；启用熔断保护与自动切换；必要时启用东财补丁或串行获取。
250+
- 通知通道失败：
251+
- 使用 --check-notify 或 scripts/check_env.py --notify 检查；确认渠道密钥、URL、签名与关键词配置；Telegram 需确认 Chat ID 与网络可达。
252+
- WebUI 页面异常：
253+
- Docker 需重新构建镜像；本地需先构建前端再启动服务；检查 static/assets 是否存在。
254+
- 配置未生效：
255+
- Docker 部署需重启容器；GitHub Actions 仅读取 Secrets/Variables；本地检查 .env 路径与覆盖顺序。
256+
- 美股/港股识别问题：
257+
- 系统已修复自动识别；如仍异常，可调整数据源优先级或相关开关。
258+
259+
章节来源
260+
- [.github/workflows/daily_analysis.yml:490-500](file://.github/workflows/daily_analysis.yml#L490-L500)
261+
- [docs/FAQ.md:71-125](file://docs/FAQ.md#L71-L125)
262+
- [docs/FAQ.md:149-200](file://docs/FAQ.md#L149-L200)
263+
- [docs/DEPLOY.md:314-343](file://docs/DEPLOY.md#L314-L343)
264+
265+
## 结论
266+
通过本快速开始指南，您可以在 5 分钟内完成 GitHub Actions 一键部署，或在本地/Docker 环境中完成部署与配置。建议先从最小配置（AI 模型密钥、通知渠道、自选股、搜索服务）开始，逐步启用高级功能（多模型路由、合并推送、Markdown 图片、飞书云文档等）。遇到问题时，优先使用 --check-notify 与 scripts/check_env.py 进行诊断，并结合 FAQ 与工作流日志定位原因。
267+
268+
## 附录
269+
- 快速命令清单（本地/Docker）
270+
- 安装依赖：pip install -r requirements.txt
271+
- 复制并编辑 .env：cp .env.example .env && vim .env
272+
- 运行分析：python main.py
273+
- 定时任务：python main.py --schedule
274+
- Web 界面：python main.py --webui 或 --webui-only
275+
- Docker 启动：docker-compose -f ./docker/docker-compose.yml up -d
276+
- Docker 日志：docker-compose -f ./docker/docker-compose.yml logs -f
277+
- GitHub Actions 最小配置清单
278+
- 至少配置：ANSPIRE_API_KEYS 或 AIHUBMIX_KEY 或 GEMINI_API_KEY 或 OPENAI_API_KEY
279+
- 至少配置一个通知渠道：WECHAT_WEBHOOK_URL/TELEGRAM/EMAIL/DISCORD/SLACK/CUSTOM_WEBHOOK_URLS
280+
- STOCK_LIST（自选股）
281+
- 可选：REPORT_TYPE、REPORT_LANGUAGE、SINGLE_STOCK_NOTIFY、MERGE_EMAIL_NOTIFICATION、ANALYSIS_DELAY、MAX_WORKERS、ENABLE_CHIP_DISTRIBUTION、REALTIME_SOURCE_PRIORITY
282+
283+
章节来源
284+
- [README.md:140-168](file://README.md#L140-L168)
285+
- [.github/workflows/daily_analysis.yml:331-355](file://.github/workflows/daily_analysis.yml#L331-L355)

0 commit comments

Comments
 (0)