中文 · English · PRD v8.7

StockResearch 不是准备上线运营的股票服务，也不是传统终端再加一个聊天框。它是一个本地联网运行的产品原型，用来展示 AI 如何把持仓、行情、新闻、风险和多 Agent 研究组织成易理解、可追问的完整体验。

核心入口是「今天与我有关的变化」和自然语言任务，而不是密集菜单、指标矩阵与全市场扫描器。

┌──────────────────────────────────────────────────────────┐
│ 上证  沪深300  深证  创业板       模式 / 数据 / 设置       │
├──────────────────────────────────────────────────────────┤
│ [持仓] [风控] [市场] [新闻·研报]              [AI 对话] │
├───────────────────────────────────────┬──────────────────┤
│               单一主画布               │ AI 对话          │
│                                       │ （横/竖排可切换） │
└───────────────────────────────────────┴──────────────────┘

AI 对话在所有工作区共用，但不会把所有内容混成一锅：

• 持仓、风险偏好和模式属于全局用户上下文；
• 连续问答与研究对象属于当前线程；
• 当前股票、新闻、组合或报告作为可见、可移除的临时页面上下文；
• 切换页面保留线程，但不会偷偷替换当前研究对象。

个人（默认）考虑你的现金流和风险承受能力，用大白话解释；专家专注四维深度分析，术语直出，不结合个人财务。顶栏一键切换，同一份数据，两种视角。

┌──────────────────────────────────────────────────────┐
│ StockResearch   [个人] [专家]      中/EN  数据  ⚙️   │
├──────────────────────────────────────────────────────┤
│      [持仓] [风控] [市场] [新闻·研报]  [AI 对话]     │
└──────────────────────────────────────────────────────┘

两个核心差异（其他差异都派生自这两点）：

模式持久化，可随时切换；模式内单项可微调（Settings）。首次访问引导选模式 + 个人模式填风险分级/现金流 + 加载示例持仓。

截图由 scripts/capture_screenshots.mjs 通过 Playwright 在 1440×900 视口下自动捕获，覆盖四个主视角 + AI 对话面板 + 设置面板。

成本与手数、实时盈亏、行业集中度、一键分析与 AI 快捷动作。

Sharpe、VaR、集中度、规则告警与 AI 解读；个人模式先人话，专家模式先指标。

指数走势、市场宽度、强弱行业、AI 市场摘要。

三层规则过滤快讯，按持仓 / 板块 / 市场分组；可一键追问 AI。

SSE 流式四维投研、多空辩论与裁判；支持横/竖排布局切换与可调宽度。

BYOK 大模型、博查 AI 搜索、可选 Tushare、辩论开关、报告导出、模式微调。

面向 A 股个人投资者的 双模式本机 AI 投资助手。个人模式帮你看懂「今天发生了什么、为什么与我有关」，专家模式提供可展开的四维研究。项目只在本机运行，单用户、SQLite、BYOK，不注册、不上线、不连接交易。

免责声明：所有 AI 输出仅供学习与研究参考，不构成任何投资建议。

StockResearch 是长期开源 MVP：跑在你自己电脑上的投资助手，不是公网 SaaS。

┌─────────────────────────────────────────────────────┐
│  模式层  个人 ←→ 专家  顶栏切换 · 持久化             │
├─────────────────────────────────────────────────────┤
│  呈现层（前端，按模式差异化）                          │
├─────────────────────────────────────────────────────┤
│  推理层（后端，模式无关）LangGraph + 四维 ReAct + 辩论 │
├─────────────────────────────────────────────────────┤
│  数据层（后端，模式无关）行情 · 新闻 · 财报 · 持仓     │
└─────────────────────────────────────────────────────┘

浏览器 (:5174)  ──REST/SSE──▶  FastAPI (:8000) + SQLite

环境：Python 3.12+、uv、Node.js 18+

git clone https://github.com/Miles128/StockResearch.git
cd StockResearch

# 后端（uv 管理虚拟环境与依赖，见 uv.lock）
uv sync
cp .env.example .env   # 编辑 .env 填写 LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
uv run uvicorn stockresearch.api.app:app --reload --host 127.0.0.1 --port 8000 --app-dir src

# 前端（新终端）
cd web && npm install && npm run dev

打开 **http://localhost:5174**。首次进入触发引导：选模式（个人/专家）→ 示例持仓已加载 → 配置 LLM（或 Mock 模式先体验）。也可随时按 F5 打开设置页。保存后自动写入项目根 .env（已 gitignore）。支持 DeepSeek、DashScope 兼容模式 等 OpenAI 兼容接口。

pytest          # 246 tests
cd web && npm run lint && npm run build && npm test   # 22 vitest tests

# 显式验证真实新浪 / 东方财富等外网 Provider
RUN_LIVE_TESTS=1 pytest -m live

# 重新生成界面截图（需先启动前后端）
SCREENSHOT_BASE_URL=http://127.0.0.1:5174 node scripts/capture_screenshots.mjs

见 .env.example。

在设置页保存后，后端从 .env 读取；无需每次在浏览器重复填 Key。

• PRD v8.7（单画布 + AI 对话 + 分层数据源 + 健康监控）
• 历史 docs/DEVELOPMENT_PLAN.md 已废弃，请以 PRD 为准
• 欢迎 Issue 与 PR；开发前请阅读 PRD 路线图

MIT — 见 LICENSE。本产品 AI 内容仅供学习与研究，不构成投资建议。

A dual-mode local AI investment assistant for China A-share investors. Advisor mode considers your cash flow and risk tolerance, explaining in plain language; Research mode focuses on four-dimensional deep analysis with direct terminology, not tied to personal finances. LangGraph orchestration, SQLite on your machine, BYOK in the browser — no sign-up, no hosted SaaS, no paywall.

Disclaimer: All AI output is for learning and research only. Not investment advice.

StockResearch is a long-term open-source MVP: a personal investment assistant on your PC, not a multi-tenant cloud product.

┌─────────────────────────────────────────────────────┐
│  Mode layer  Advisor ←→ Research  top-bar · persist  │
├─────────────────────────────────────────────────────┤
│  Presentation (frontend, mode-differentiated)        │
├─────────────────────────────────────────────────────┤
│  Reasoning (backend, mode-agnostic) LangGraph + 4D  │
├─────────────────────────────────────────────────────┤
│  Data (backend, mode-agnostic) quotes·news·reports  │
└─────────────────────────────────────────────────────┘

Browser (:5174)  ──REST/SSE──▶  FastAPI (:8000) + SQLite

Requires Python 3.12+, uv, Node.js 18+

git clone https://github.com/Miles128/StockResearch.git
cd StockResearch

# Backend (uv manages the venv; see uv.lock)
uv sync
cp .env.example .env   # set LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
uv run uvicorn stockresearch.api.app:app --reload --host 127.0.0.1 --port 8000 --app-dir src

# Frontend (new terminal)
cd web && npm install && npm run dev

Open http://localhost:5174. First visit triggers onboarding: pick mode (Advisor/Research) → demo holdings loaded → configure LLM (or Mock mode). Press F5 anytime for Settings. Saving writes to the project root .env (gitignored) automatically. Works with DeepSeek, DashScope compatible mode, and other OpenAI-compatible APIs.

pytest          # 246 tests
cd web && npm run lint && npm run build && npm test   # 22 vitest tests

# Regenerate screenshots (start backend + frontend first)
SCREENSHOT_BASE_URL=http://127.0.0.1:5174 node scripts/capture_screenshots.mjs

See .env.example.

Saving in Settings writes .env; the backend reads it on the next request.

• PRD v8.7 (single canvas + AI Chat + layered data sources + health monitoring)
• Legacy docs/DEVELOPMENT_PLAN.md is deprecated; refer to PRD
• Issues and PRs welcome; read the PRD roadmap before large features

MIT — see LICENSE. AI output is for learning and research only. Not investment advice.