# Technical Documentation: hsliuping/TradingAgents-CN

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/hsliuping/TradingAgents-CN)

### Overview (`README.md`)

# TradingAgents-CN 社区版（Community Edition）

**English**: TradingAgents-CN Community Edition is a hybrid-licensed (Apache-2.0 core engine + proprietary source-available application layer) multi-agent stock research assistant for the Chinese A-share market. It orchestrates LLM-based analyst agents for debate-style research, natural-language stock screening, paper trading and study courses. For learning and research only — **not investment advice**.

[-blue.svg)](./LICENSE)
[](https://www.python.org/)
[](https://vuejs.org/)

基于多智能体协作的 A 股研究辅助系统。由多个扮演不同角色（大盘/板块/市场/基本面/新闻分析师，乐观/审慎研究员等）的 AI 智能体协作完成研究流程，帮助你系统化学习多智能体框架与 AI 大模型在股票研究中的应用。

> 本项目是研究辅助工具，所有 AI 生成内容仅供学习参考，**不构成投资建议**。

## 核心功能

- **单股研究**：多智能体辩论式分析（5 级深度），多情景观点呈现
- **通用研究**：自然语言提问，研究任意市场主题
- **股票筛选**：自然语言 + 条件筛选，从 6000+ 只股票中发现标的
- **选股助手**：按研究需求描述匹配候选股票池
- **智能助手**：联网搜索 + 工具调用 + 事实记忆
- **AI 记忆**：项目级记忆与事实沉淀
- **Skill 中心**：创建和管理自定义数据获取技能
- **学习中心**：免费系统课程（发现阶段 5 课）+ 8 篇学习指南
- **模拟交易**：纸面交易与复盘

## 版本演进

| 版本 | 定位 | 核心变化 |
|------|------|---------|
| v1.0 | 多智能体分析工具 | 单股研究 + 批量分析，多个分析师智能体协作完成 A 股研究流程 |
| v2.0 | 分析融入研究闭环 | 统一分析引擎 + 可视化工作流，新增持仓分析、操作复盘与阶段性复盘 |
| v2.1 | 研究辅助合规化 | 报告表达、提示词模板、界面文案全面对齐"研究辅助"定位；新模型接入与稳定性提升 |
| v3.0 | 从分析工具到 AI 助手 | 统一 AI 助手入口、自然语言选股、Agent 自主规划分析、Skill 能力扩展；架构升级为 FastAPI + Vue 3 + MongoDB/Redis |

## 社区版与 Pro 版的差异

| 能力 | 社区版 | Pro 版 |
|------|:------:|:------:|
| 单股研究 / 通用研究 / 股票筛选 | ✅ | ✅ |
| 学习中心（免费课程） / 模拟交易 / Skill 中心 | ✅ | ✅ |
| Agent 工作坊（创建、发布、管理自定义 Agent） | — | ✅ |
| 交易系统（策略创建 / 优化 / 模板调试） | — | ✅ |
| 定时分析 / 批量分析 | — | ✅ |
| 专业报告导出（Word / PDF 多格式） | — | ✅ |
| 高级课程（进阶 8 阶段） | — | ✅ |
| 许可 | 混合授权（核心引擎开源 + 应用层专有） | 商业许可 |

Pro 版面向有更高阶研究工作流需求的用户，获取方式见项目主页或联系作者。

## 快速开始

### 环境要求

- Python 3.11
- Node.js 18+
- MongoDB 7.0+（推荐 8.0）与 Redis 6+（推荐 7）—— 需自行安装，见下方「安装 MongoDB / Redis」

### 安装 MongoDB / Redis

本项目不自带数据库，请先自行安装并启动 MongoDB 与 Redis（版本要求见上）。任意一种安装方式都可以，只要**账号密码与端口和下一步的 `.env` 保持一致**。

| 系统 | MongoDB | Redis |
|------|---------|-------|
| Windows | 官网安装包 https://www.mongodb.com/try/download/community （安装后作为服务自启） | WSL 里运行 `redis-server`，或使用 Memurai 等兼容实现 |
| macOS | `brew tap mongodb/brew && brew install mongodb-community && brew services start mongodb-community` | `brew install redis && brew services start redis` |
| Ubuntu / Debian | 参考 https://www.mongodb.com/docs/manual/installation/ | `sudo apt install redis-server && sudo systemctl enable --now redis-server` |

也可以用 Docker 只跑这两个数据库（需要本机已装 Docker）：

```bash
docker run -d --name ta-mongo -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin -e MONGO_INITDB_ROOT_PASSWORD=<你的密码> mongo:8.0
docker run -d --name ta-redis -p 6379:6379 \
  redis:7-alpine redis-server --requirepass <你的密码>
```

MongoDB 需开启认证（`authSource=admin`），并自行创建管理员账号；把用户名/密码、主机与端口写入下一步的 `.env`（本地默认 `localhost:27017` / `localhost:6379`）。

### 启动步骤

```bash
# 1. 克隆
git clone <本仓库地址>
cd TradingAgents-CN

# 2. 后端环境（Python 3.11）
python -m venv env
env\Scripts\activate            # Windows
source env/bin/activate         # Linux / macOS
pip install -r requirements.txt

# 3. 配置（必填 MongoDB / Redis / JWT_SECRET，详见 .env.example 注释）
copy .env.example .env          # Windows
cp .env.example .env            # Linux / macOS

# 4. 启动已安装好的 MongoDB / Redis（账号密码与 .env 保持一致）

# 5. 启动后端（默认 8000 端口，与前端默认代理一致）
uvicorn app.main:app

# 6. 启动前端
cd frontend
npm install
npm run dev                     # 默认 http://localhost:3000
```

### 首次登录

后端首次启动时会自动完成初始化（无需手动执行任何导入脚本）：

1. 导入系统级配置（模型目录、提示词模板、Agent 配置、工作流等）
2. 用户表为空时，用 `.env` 中的 `ADMIN_DEFAULT_PASSWORD` 创建管理员账号 `admin`

| 账号 | 密码 |
|------|------|
| `admin` | `.env` 中的 `ADMIN_DEFAULT_PASSWORD` |

登录后请先在系统设置中配置大模型 API Key（OpenAI / DeepSeek / 通义千问等），并按需配置行情数据 Token。

## 文档

- 用户手册：[docs/02-user-guide/user-manual-v3.0.md](docs/02-user-guide/user-manual-v3.0.md)
- 学习指南：[docs/02-user-guide/](docs/02-user-guide/)（learning-01 ~ 08）
- 免费课程：[docs/07-courses/v3.0/phase-01-discover/](docs/07-courses/v3.0/phase-01-discover/)

## 数据来源

行情与财务数据来自 [Tushare](https://tushare.pro/) / [AKShare](https://github.com/akfamily/akshare) / [BaoStock](https://www.baostock.com/) 等公开接口，需自行注册获取 token。

## 参与共建（招募中）

我们正在寻找**志同道合的开源人才**，一起把 TradingAgents-CN 做得更好。

**怎么加入**：直接提交 Pull Request。不看简历、不面试——**PR 是唯一的考察方式**，我们根据 PR 质量判断是否合适：

1. **解决真问题**：修复实际存在的 Bug 或补齐真实缺口，而非为改而改
2. **说明修改原因**：讲清楚"为什么改"，而不只是"改了什么"
3. **响应 review 意见**：积极回应评审意见并跟进修改

持续贡献高质量 PR 的伙伴将参与版本规划与关键模块开发。

**当前欢迎的方向**：

- 数据源适配：行情/财务公开接口的接入与维护
- 前端开发：Vue 3 + TypeScript 功能开发与体验优化
- Agent 编排与提示词工程：分析链路优化
- 文档与课程：用户手册、学习课程建设

**你能得到**：公开署名与流量（版本发布/公众号点名致谢）、多智能体系统的工程实战经验、项目商业化优先权。项目目前收入尚不足以覆盖基础成本，暂为志愿参与；收入覆盖成本后的分配原则（社区贡献基金 / 顾问费 / 分成路径）已提前写明。

**怎么联系**：初始沟通请发邮件至 hsliup@163.com；具体技术问题建议直接提 Issue / PR 公开讨论；协作顺畅后会邀请加入项目微信群与知识星球。

提交流程、分配框架与贡献者协议（CLA）详见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 免责声明

- 本系统仅支持 A 股市场研究，输出为 AI 生成的研究参考，不构成投资建议
- 不提供目标价、止损止盈、买卖时机等交易指令
- 投资有风险，决策需独立判断

## License

本项目采用**混合授权**，详见 [LICENSE](LICENSE)：

- **Apache-2.0 开源组件**：`tradingagents/`（交易智能体库）、`cli/`、`docs/`、`tests/` 等——可自由使用、修改、分发
- **专有组件（Source Available）**：`app/`（后端应用）、`frontend/`（前端应用）、`core/`（核心功能层）——源码可见，允许个人使用、评估与教育用途，**禁止再分发与商业使用**（商业许可请联系作者）

提交贡献即表示同意签署[贡献者许可协议（CLA）](CONTRIBUTING.md)。

## 致谢

- [Tauric Research / TradingAgents](https://github.com/TauricResearch/TradingAgents) — 多智能体交易框架原版项目
- 所有通过 PR 参与共建的贡献者

完整致谢（含授权说明与数据源致谢）见 [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md)。

---

### Overview (`config/README.md`)

# Config 目录

此目录用于存储TradingAgents的配置文件和使用统计数据。

## 文件说明

- `usage.json` - Token使用统计数据（自动生成）
- `models.json` - 模型配置文件（自动生成）
- `pricing.json` - 定价配置文件（自动生成）
- `settings.json` - 系统设置文件（自动生成）

## 重要说明

⚠️ **数据持久化**：此目录已在Docker Compose中配置为卷挂载，确保容器重启后配置和统计数据不会丢失。

🔒 **安全提醒**：此目录可能包含敏感的使用统计信息，请勿将其提交到公共代码仓库。

## 备份建议

建议定期备份此目录中的重要配置文件，特别是：
- `usage.json` - 包含完整的Token使用历史
- `settings.json` - 包含个人化设置

## 故障排除

如果遇到配置问题：
1. 检查文件权限是否正确
2. 确认Docker卷挂载是否正常
3. 查看应用日志获取详细错误信息

---

### Overview (`docs/README.md`)

# TradingAgents-CN 文档中心

> 本文档体系按"产品发展、迭代、开发"三层规划，服务于不同角色的读者。
>
> **当前版本：v3.0** | [版本号管理规范](#版本号管理规范)

## 文档体系总览

| 层级 | 目录 | 面向角色 | 说明 |
|------|------|---------|------|
| 产品层 | [01-product](./01-product/) | 所有人 | 产品定位、路线图、发布说明、版本对比 |
| 用户层 | [02-user-guide](./02-user-guide/) | 最终用户 | 安装、配置、功能使用、进阶指南 |
| 开发层 | [03-development](./03-development/) | 开发者 | 架构设计、API 文档、开发指南、开发流程 |
| 运维层 | [04-operations](./04-operations/) | 运维人员 | 部署、数据库、监控、故障排查 |
| 设计层 | [05-design](./05-design/) | 产品/架构师 | **按版本号管理**：v3.0/v4.0/v5.0 |
| 知识层 | [06-knowledge](./06-knowledge/) | 全体成员 | 经验教训、Bug 编年史、合规要求 |
| 课程层 | [07-courses](./07-courses/) | 用户/学员 | 高级交易课程（24 课） |
| 博客层 | [08-blog](./08-blog/) | 所有人 | 技术博客、版本发布博客 |
| 归档区 | [99-archive](./99-archive/) | 历史参考 | **按版本号归档**：v0.1.x/v1.0.x/v2.0/v2.1 |

## 快速导航

### 完整使用手册

- [v3.0 完整使用手册（标准版）](./02-user-guide/user-manual-v3.0.md)
- [v3.0 京东云合作版使用手册](./02-user-guide/jdyun-user-manual-v3.0.md) ⭐ 京东云版用户专用

### 新用户入门
0. [v3.0 系统介绍（技术文档版）](./01-product/v3.0-system-introduction.md)
   - [v3.0 系统介绍（公众号传播版）](./01-product/v3.0-system-introduction-for-wechat.md)
1. [快速开始](./02-user-guide/getting-started/quick-start.md)
2. [安装指南](./02-user-guide/getting-started/installation.md)
3. [Docker 安装使用指南](./02-user-guide/getting-started/docker-installation-guide.md)
4. [数据库配置](./02-user-guide/getting-started/database-setup.md)
5. [LLM 配置](./02-user-guide/configuration/llm-config.md)
6. [数据源配置](./02-user-guide/configuration/config-guide.md)

### 功能使用
- [个股分析](./02-user-guide/features/stock-analysis.md)
- [模拟交易（虚拟学习环境）](./02-user-guide/features/paper-trading.md)
- [持仓分析](./02-user-guide/features/portfolio-analysis.md)
- [定时分析](./02-user-guide/features/scheduled-analysis.md)
- [报告导出](./02-user-guide/features/report-export.md)

### 进阶功能
- [Agent 工坊](./02-user-guide/advanced/prompt-management.md)
- [提示词管理](./02-user-guide/advanced/prompt-management.md)
- [QMT 对接](./02-user-guide/advanced/qmt-usage.md)

### 开发者
- [开发环境搭建](./03-development/getting-started/setup.md)
- [项目结构](./03-development/getting-started/project-structure.md)
- [系统架构](./03-development/architecture/system-overview.md)
- [API 文档](./03-development/api/)
- [开发流程](./03-development/workflow/development-workflow.md)
- [分支策略](./03-development/workflow/branch-guide.md)
- [京东云对接指南](./03-development/guides/jdyun-integration-guide.md) ⭐ 京东云工程师专用

### 运维部署
- [Docker 部署](./04-operations/deployment/docker-deployment-guide.md)
- [Windows 便携版](./04-operations/deployment/windows-portable.md)
- [数据库运维](./04-operations/database/)
- [故障排查](./04-operations/troubleshooting/)

### 产品演进（按版本号管理）
- **[v3.0（当前版本）](./05-design/v3.0/)** - 当前发布版本的设计文档
  - [京东云合作版定制设计](./05-design/v3.0/jdyun-edition-design.md)
  - [京东云登录认证设计](./05-design/v3.0/jdyun-auth-design.md)
  - [v3.6.0 社区版开源分离方案](./05-design/v3.0/v3.6.0-community-edition-separation-plan.md)
  - [估值测算 Excel 交付物设计（声明式交付物）](./05-design/v3.0/valuation-excel-deliverable-design.md)
  - [智能助手质量架构重构设计（A11）](./05-design/v3.0/assistant-quality-architecture-refactor.md) ⭐ 统一质量出口/证据集/路径注册表，终结"发现一个修一个"模式
- **[v4.0（下一版本）](./05-design/v4.0/)** - 下一版本规划
  - [现状与远期目标映射（基准文档）](./05-design/v4.0/current-state-and-vision-mapping.md) ⭐ 三层架构定位、代码现状盘点、目标修订记录（R1-R8）与四泳道统一路线图
- **[v5.0（远期愿景）](./05-design/v5.0/)** - 远期愿景
- [前沿探索](./05-design/research/) - 不绑定版本的前沿研究

## 版本号管理规范

### 核心原则

**设计文档（05-design）和归档文档（99-archive）必须使用明确版本号目录**，禁止使用 `current`、`latest`、`new` 等相对概念命名。

### 05-design 版本号目录规则

```
05-design/
├── v3.0/              # 当前发布版本（v3.0.x 系列）的设计文档
├── v4.0/              # 下一版本规划
├── v5.0/              # 远期愿景
└── research/          # 前沿探索（不绑定版本）
```

**版本号命名规则**：
- 主版本号目录：`v3.0`、`v4.0`、`v5.0`（对应 major.minor 中的 major）
- 同一主版本号下的小版本迭代不新建目录，直接在原目录内更新文件
- 例如 v3.0.1、v3.0.2、v3.1.0 的设计文档都放在 `v3.0/` 目录下

### 99-archive 版本号目录规则

```
99-archive/
├── v0.1.x/            # v0.1.x 时代所有文档
├── v1.0.x/            # v1.0.x 时代所有文档
├── v2.0/              # v2.0 设计文档
├── v2.1/              # v2.1 设计文档
├── deprecated-features/ # 已废弃功能（跨版本）
└── historical-fixes/    # 历史修复记录（跨版本）
```

### 版本迭代流程

当发布新主版本（如 v3.0 → v4.0）时：

1. **设计文档迁移**：
   - `05-design/v3.0/` → `99-archive/v3.0/`（当前版本归档）
   - `05-design/v4.0/` → `05-design/v4.0/`（保持不变，成为新的当前版本）
   - 新建 `05-design/v5.0/`（开始下一版本规划）

2. **发布说明**：
   - 在 `01-product/release-notes/` 新建 `v4.0.0.md`

3. **知识沉淀**：
   - 将本版本周期内的重大 Bug 整理到 `06-knowledge/bug-chronicle/`

4. **禁止的操作**：
   - ❌ 禁止在 `05-design/` 下使用 `current/`、`next/`、`future/` 等相对命名
   - ❌ 禁止把旧版本文档留在 `05-design/v3.0/` 中不归档
   - ❌ 禁止跨版本修改已归档的文档（如需修改，复制到当前版本目录）

### 其他层的版本管理

| 层级 | 版本管理方式 | 说明 |
|------|-------------|------|
| 01-product | 按版本号命名文件 | `release-notes/v3.0.0.md`、`comparison/v2.1-vs-v3.0.md` |
| 02-user-guide | 跟随当前版本 | 文档内容随当前版本更新，不保留历史版本 |
| 03-development | 跟随当前版本 | 文档内容随当前版本更新，不保留历史版本 |
| 04-operations | 跟随当前版本 | 文档内容随当前版本更新，不保留历史版本 |
| 05-design | **按版本号目录** | 每个主版本一个目录，版本迭代时归档 |
| 06-knowledge | 跨版本积累 | 按季度/主题组织，不绑定版本 |
| 99-archive | **按版本号目录** | 每个主版本一个目录 |

## 文档命名规范

- 统一使用小写 kebab-case（如 `quick-start.md`）
- 版本相关文件加版本后缀（如 `docker-deployment-v1.md`）
- 临时文件加日期前缀（如 `2025-10-26-bugfix.md`）

## ADR（架构决策记录）

重要架构决策记录在 [03-development/decisions/](./03-development/decisions/)，每个 ADR 包含：
- 背景：面临什么问题
- 决策：选择了什么方案
- 原因：为什么选这个方案
- 后果：带来了什么影响

---

### Overview (`frontend/README.md`)

# TradingAgents-CN 前端应用

现代化的Vue3前端界面，为TradingAgents-CN提供优秀的用户体验。

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 8.0.0

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000

### 构建生产版本

```bash
npm run build
```

### 预览生产版本

```bash
npm run preview
```

## 📁 项目结构

```
frontend/
├── public/                 # 静态资源
├── src/
│   ├── api/               # API接口
│   ├── components/        # 组件
│   │   ├── Global/       # 全局组件
│   │   └── Layout/       # 布局组件
│   ├── layouts/          # 页面布局
│   ├── router/           # 路由配置
│   ├── stores/           # 状态管理
│   ├── styles/           # 样式文件
│   ├── types/            # 类型定义
│   ├── utils/            # 工具函数
│   ├── views/            # 页面组件
│   ├── App.vue           # 根组件
│   └── main.ts           # 应用入口
├── index.html            # HTML模板
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
├── vite.config.ts        # Vite配置
└── README.md             # 说明文档
```

## 🎨 主要功能

### 📊 仪表板
- 数据概览和统计
- 快速操作入口
- 系统状态监控
- 最近分析记录

### 🔍 股票筛选
- 多维度筛选条件
- 实时结果展示
- 批量操作支持
- 筛选结果导出

### 📈 股票分析
- 单股深度分析
- 批量分析处理
- 分析历史查看
- 进度实时跟踪

### 📋 队列管理
- 任务队列监控
- 实时状态更新
- 任务优先级管理
- 批量操作支持

### 📄 分析报告
- 报告生成和管理
- 多格式导出支持
- 报告分享功能
- 历史报告查看

### ⚙️ 系统设置
- 个人偏好配置
- 主题和外观设置
- 分析参数配置
- 安全设置管理

## 🛠️ 技术栈

### 核心框架
- **Vue 3** - 渐进式JavaScript框架
- **TypeScript** - 类型安全的JavaScript
- **Vite** - 现代化构建工具

### UI组件库
- **Element Plus** - 企业级Vue组件库
- **@element-plus/icons-vue** - 图标组件

### 状态管理
- **Pinia** - Vue官方状态管理库
- **@vueuse/core** - Vue组合式API工具集

### 路由和网络
- **Vue Router 4** - 官方路由管理器
- **Axios** - HTTP客户端

### 开发工具
- **ESLint** - 代码质量检查
- **Prettier** - 代码格式化
- **unplugin-auto-import** - 自动导入
- **unplugin-vue-components** - 组件自动导入

## 🎯 特色功能

### 🌈 现代化设计
- 响应式布局设计
- 明暗主题切换
- 流畅的动画效果
- 移动端适配

### 🔧 开发体验
- TypeScript类型安全
- 组件自动导入
- 热模块替换
- 代码分割优化

### 🚀 性能优化
- 路由懒加载
- 组件按需加载
- 图片懒加载
- 缓存策略优化

### 🔒 安全特性
- JWT认证集成
- 权限路由守卫
- XSS防护
- CSRF保护

## 📱 响应式设计

支持多种设备尺寸：

- **桌面端**: >= 1200px
- **平板端**: 768px - 1199px  
- **手机端**: < 768px

## 🎨 主题定制

支持多种主题模式：

- **浅色主题**: 适合白天使用
- **深色主题**: 适合夜间使用
- **自动模式**: 跟随系统设置

## 🔧 配置说明

### 环境变量

创建 `.env.local` 文件：

```env
# API基础URL
VITE_API_BASE_URL=http://localhost:8000/api

# 应用标题
VITE_APP_TITLE=TradingAgents-CN
```

### 代理配置

开发环境自动代理API请求到后端服务：

```typescript
// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true
    }
  }
}
```

## 🚀 部署指南

### 构建应用

```bash
npm run build
```

### 部署到Nginx

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 🤝 开发指南

### 添加新页面

1. 在 `src/views/` 创建页面组件
2. 在 `src/router/index.ts` 添加路由
3. 在侧边栏菜单中添加导航

### 添加新API

1. 在 `src/types/` 定义类型
2. 在 `src/api/` 创建API模块
3. 在组件中使用API

### 状态管理

使用Pinia进行状态管理：

```typescript
// 定义store
export const useExampleStore = defineStore('example', {
  state: () => ({
    data: []
  }),
  actions: {
    async fetchData() {
      // 获取数据逻辑
    }
  }
})

// 在组件中使用
const exampleStore = useExampleStore()
```

## 📝 代码规范

### 命名规范
- 组件名：PascalCase
- 文件名：kebab-case
- 变量名：camelCase
- 常量名：UPPER_SNAKE_CASE

### 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建过程或辅助工具的变动

## 🐛 问题排查

### 常见问题

1. **依赖安装失败**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

2. **端口被占用**
   ```bash
   # 修改端口
   npm run dev -- --port 3001
   ```

3. **类型错误**
   ```bash
   # 重新生成类型文件
   npm run type-check
   ```

## 📞 技术支持

如有问题，请通过以下方式联系：

- 📧 邮箱: hsliup@163.com
- 💬 微信群: 扫描README中的二维码
- 🐛 问题反馈: GitHub Issues

---

**TradingAgents-CN Frontend v3.0.0** - 面向 AI 助手与智能投研工作流的现代化前端

---

### Overview (`tests/README.md`)

# TradingAgents-CN 测试目录

这个目录包含了TradingAgents-CN项目的所有测试文件，用于验证功能正确性、API集成和模型测试。

## 目录结构

```
tests/
├── README.md                           # 本文件
├── __init__.py                         # Python包初始化
├── integration/                        # 集成测试
│   ├── __init__.py
│   └── test_dashscope_integration.py   # 阿里百炼集成测试
├── test_*.py                          # 各种功能测试
└── debug_*.py                         # 调试和诊断工具
```

## 测试分类

### 🔧 API和集成测试
- `test_all_apis.py` - 所有API密钥测试
- `test_correct_apis.py` - Google和Reddit API测试
- `test_analysis_with_apis.py` - API集成分析测试
- `test_toolkit_tools.py` - 工具包测试
- `integration/test_dashscope_integration.py` - 阿里百炼集成测试

### 📊 数据源测试
- `fast_tdx_test.py` - Tushare数据接口快速连接测试
- `test_tdx_integration.py` - Tushare数据接口完整集成测试

### ⚡ 性能测试
- `test_redis_performance.py` - Redis性能基准测试
- `quick_redis_test.py` - Redis快速连接测试

### 🤖 AI模型测试
- `test_chinese_output.py` - 中文输出测试
- `test_gemini*.py` - Google Gemini模型系列测试
- `test_embedding_models.py` - 嵌入模型测试
- `test_google_memory_fix.py` - Google AI内存功能测试

### 🌐 Web界面测试
- `test_web_interface.py` - Web界面功能测试

### 🔍 调试和诊断工具
- `debug_imports.py` - 导入问题诊断
- `diagnose_gemini_25.py` - Gemini 2.5模型诊断
- `check_gemini_models.py` - Gemini模型可用性检查

### 🧪 功能测试
- `test_analysis.py` - 基础分析功能测试
- `test_format_fix.py` - 格式化修复测试
- `test_progress.py` - 进度跟踪测试

## 运行测试

### 运行所有测试
```bash
# 从项目根目录运行
python -m pytest tests/

# 或者直接运行特定测试
cd tests
python test_chinese_output.py
```

### 运行 CI smoke 测试
```bash
python -m pytest tests/config/test_settings.py tests/config/test_logging_config.py tests/middleware/test_trace_id.py
```

说明：仓库默认的 pytest 配置只收集 tests/ 目录，用于避免根目录下的临时调试脚本被误纳入标准回归。

### 运行特定类别的测试
```bash
# API测试
python tests/test_all_apis.py

# Gemini模型测试
python tests/test_gemini_correct.py

# Web界面测试
python tests/test_web_interface.py

# 阿里百炼集成测试
python tests/integration/test_dashscope_integration.py

# Tushare数据接口测试
python tests/fast_tdx_test.py
python tests/test_tdx_integration.py

# Redis性能测试
python tests/quick_redis_test.py
python tests/test_redis_performance.py
```

### 诊断工具
```bash
# 诊断Gemini模型问题
python tests/diagnose_gemini_25.py

# 检查导入问题
python tests/debug_imports.py

# 检查所有可用的Gemini模型
python tests/check_gemini_models.py
```

## 测试环境要求

### 必需的环境变量
在运行测试前，请确保在`.env`文件中配置了以下API密钥：

```env
# 阿里百炼API（必需）
DASHSCOPE_API_KEY=your_dashscope_key

# Google AI API（可选，用于Gemini测试）
GOOGLE_API_KEY=your_google_key

# 金融数据API（可选）
FINNHUB_API_KEY=your_finnhub_key

# Reddit API（可选）
REDDIT_CLIENT_ID=your_reddit_id
REDDIT_CLIENT_SECRET=your_reddit_secret
REDDIT_USER_AGENT=your_user_agent
```

### Python依赖
```bash
pip install -r requirements.txt
```

### 测试结果解读
- **所有测试通过**：功能完全正常，可以使用完整功能
- **部分测试通过**：基本功能正常，可能需要检查配置
- **大部分测试失败**：存在问题，需要排查API密钥和环境配置

## 贡献指南

添加新测试时，请遵循以下规范：

1. **测试文件命名**: `test_功能名称.py`
2. **调试工具命名**: `debug_问题描述.py` 或 `diagnose_问题描述.py`
3. **测试函数命名**: `test_具体功能()`
4. **文档**: 在函数开头添加清晰的文档字符串
5. **分类**: 根据功能将测试放在适当的类别中

### 测试模板

```python
#!/usr/bin/env python3
"""
新功能测试
"""

import os
import sys
from pathlib import Path
from dotenv import load_dotenv

# 添加项目根目录到Python路径
project_root = Path(__file__).parent.parent
sys.path.insert(0, str(project_root))

# 加载环境变量
load_dotenv(project_root / ".env", override=True)

def test_new_feature():
    """测试新功能"""
    try:
        print("🧪 测试新功能")
        print("=" * 50)

        # 测试代码

        print("✅ 测试成功")
        return True
    except Exception as e:
        print(f"❌ 测试失败: {e}")
        return False

def main():
    """主测试函数"""
    print("🧪 新功能测试")
    print("=" * 60)

    success = test_new_feature()

    if success:
        print("🎉 所有测试通过！")
    else:
        print("❌ 测试失败")

if __name__ == "__main__":
    main()
```

## 最近更新

- ✅ 添加了Google Gemini模型系列测试
- ✅ 添加了Web界面Google模型选择测试
- ✅ 添加了API集成测试（Google、Reddit）
- ✅ 添加了中文输出功能测试
- ✅ 添加了内存系统和嵌入模型测试
- ✅ 整理了所有测试文件到tests目录
- ✅ 添加了调试和诊断工具

## 测试最佳实践

1. **测试隔离**：每个测试应该独立运行
2. **清晰命名**：测试函数名应该清楚描述测试内容
3. **错误处理**：测试应该能够处理各种错误情况
4. **文档化**：为复杂的测试添加详细注释
5. **快速反馈**：测试应该尽快给出结果

## 故障排除

### 常见问题
1. **API密钥问题** - 检查.env文件配置
2. **网络连接问题** - 确认网络和防火墙设置
3. **依赖包问题** - 确保所有依赖已安装
4. **模型兼容性** - 检查模型名称和版本

### 调试技巧
1. 启用详细输出查看错误信息
2. 单独运行测试函数定位问题
3. 使用诊断工具检查配置
4. 查看Web应用日志了解运行状态

## 许可证

本项目遵循Apache 2.0许可证。


## 新增的测试文件

### 集成测试
- `quick_test.py` - 快速集成测试，验证基本功能
- `test_smart_system.py` - 智能系统完整测试
- `demo_fallback_system.py` - 降级系统演示和测试

### 运行方法
```bash
# 快速测试
python tests/quick_test.py

# 智能系统测试
python tests/test_smart_system.py

# 降级系统演示
python tests/demo_fallback_system.py
```

---

### Overview (`docs/images/README.md`)

# Web界面截图目录

此目录用于存放TradingAgents-CN Web界面的截图文件。

## 📸 需要的截图文件

为了完善README.md中的Web界面展示，请添加以下截图：

### 🏠 主界面截图
- **文件名**: `web-interface-main.png`
- **内容**: 主分析配置界面
- **要求**: 
  - 显示股票代码输入框
  - 显示市场选择（美股/A股/港股）
  - 显示研究深度选择（1-5级）
  - 显示智能体选择选项
  - 显示"开始分析"按钮

### 📊 实时分析进度截图
- **文件名**: `web-interface-progress.png`
- **内容**: 分析进行中的进度显示
- **要求**:
  - 显示进度条和百分比
  - 显示当前分析步骤
  - 显示预计剩余时间
  - 显示已完成的分析阶段

### 📈 分析结果展示截图
- **文件名**: `web-interface-results.png`
- **内容**: 完整的分析结果页面
- **要求**:
  - 显示研究结论倾向（乐观/审慎/中性）
  - 显示置信度和风险评分
  - 显示详细分析报告
  - 显示导出按钮

### ⚙️ 模型配置管理截图
- **文件名**: `web-interface-models.png`
- **内容**: 侧边栏的模型配置界面
- **要求**:
  - 显示LLM提供商选择
  - 显示模型选择下拉框
  - 显示快速选择按钮
  - 显示API密钥配置状态

## 📋 截图规范

### 🖼️ 技术要求
- **格式**: PNG格式（推荐）
- **分辨率**: 至少1920x1080
- **质量**: 高清，文字清晰可读
- **大小**: 单个文件不超过2MB

### 🎨 内容要求
- **界面完整**: 显示完整的功能区域
- **数据真实**: 使用真实的股票代码和分析结果
- **状态清晰**: 确保界面状态清晰可见
- **无敏感信息**: 不包含真实的API密钥

### 📱 建议的截图场景
1. **主界面**: 输入"AAPL"或"000001"，选择标准分析
2. **进度界面**: 分析进行到50%左右的状态
3. **结果界面**: 完整的分析报告，包含图表
4. **配置界面**: 显示多个LLM提供商和模型选项

## 🚀 如何获取截图

### 方法1: 启动Web应用
```bash
# 启动Web界面
python start_web.py

# 访问 http://localhost:8501
# 进行股票分析并截图
```

### 方法2: Docker环境
```bash
# 启动Docker服务
docker-compose up -d

# 访问 http://localhost:8501
# 进行分析并截图
```

## 📝 添加截图后的操作

1. 将截图文件放入此目录
2. 确保文件名与README.md中引用的名称一致
3. 检查图片是否正常显示
4. 提交到Git仓库

## 🔄 更新说明

当Web界面有重大更新时，请及时更新对应的截图，确保文档与实际界面保持一致。

---

**注意**: 此目录中的截图将在README.md中展示，代表项目的专业形象，请确保截图质量和内容的专业性。

---

### Overview (`tradingagents/dataflows/README.md`)

# Dataflows 模块架构说明

## 📁 目录结构

```
/* Detailed source-code truncated for AI context efficiency. */
```

---

## 🎯 核心文件说明

### 1. interface.py (60.25 KB) ⭐⭐⭐
**职责**: 公共接口层，提供所有数据获取的统一入口

**主要功能**:
- 中国市场接口（6个函数）
  - `get_china_stock_data_unified()` - 统一的A股数据获取
  - `get_china_stock_info_unified()` - 统一的A股信息获取
  - `get_china_stock_data_tushare()` - Tushare数据获取
  - `get_china_stock_fundamentals_tushare()` - Tushare基本面数据
  - `switch_china_data_source()` - 切换数据源
  - `get_current_china_data_source()` - 获取当前数据源

- 香港市场接口（2个函数）
  - `get_hk_stock_data_unified()` - 统一的港股数据获取
  - `get_hk_stock_info_unified()` - 统一的港股信息获取

- 美国市场接口（7个函数）
  - `get_finnhub_news()` - Finnhub新闻
  - `get_YFin_data()` - Yahoo Finance数据
  - `get_fundamentals_finnhub()` - Finnhub基本面数据
  - 等

- 新闻接口（5个函数）
  - `get_google_news()` - Google新闻
  - `get_reddit_global_news()` - Reddit全球新闻
  - `get_stock_news_openai()` - OpenAI新闻分析
  - 等

- 技术分析接口（2个函数）
  - `get_stockstats_indicator()` - 技术指标计算

**使用场景**: Agent工具函数、API路由、业务逻辑

**依赖**: data_source_manager, providers, news, technical

---

### 2. data_source_manager.py (67.81 KB) ⭐⭐⭐
**职责**: 数据源管理器，负责多数据源的统一管理和自动降级

**主要功能**:
- 数据源管理
  - 支持多数据源：MongoDB, Tushare, AKShare, Baostock, TDX
  - 自动降级机制
  - 数据源切换

- 缓存管理
  - 统一缓存接口
  - 自动缓存数据
  - 缓存失效处理

- 数据获取
  - `get_china_stock_data_unified()` - 统一的A股数据获取
  - `get_china_stock_info_unified()` - 统一的A股信息获取
  - `get_fundamentals_data()` - 基本面数据获取

**使用场景**: interface.py 的底层实现

**依赖**: providers, cache

---

### 3. optimized_china_data.py (67.68 KB) ⭐⭐⭐
**职责**: 优化的A股数据提供器，提供缓存和基本面分析功能

**主要功能**:
- 优化的数据获取
  - `get_china_stock_data_cached()` - 缓存的股票数据获取
  - `get_china_fundamentals_cached()` - 缓存的基本面数据获取

- 基本面分析
  - `_generate_fundamentals_report()` - 生成基本面分析报告
  - 财务指标计算
  - 估值分析

**使用场景**: 
- Agent工具函数（agent_utils.py）
- 市场分析师（market_analyst.py）
- Web缓存管理（cache_management.py）

**依赖**: cache, providers

---

## 📊 辅助文件说明

### 4. stock_data_service.py (12.14 KB)
**职责**: 股票数据服务，实现 MongoDB → TDX 的降级机制

**主要功能**:
- `StockDataService` 类
- `get_stock_basic_info()` - 获取股票基本信息
- MongoDB → TDX 降级

**使用场景**:
- `tradingagents/api/stock_api.py`
- `tradingagents/dataflows/stock_api.py`
- `app/routers/stock_data.py`
- `app/worker/` 服务

**与 data_source_manager 的区别**:
- `stock_data_service`: 专注于 MongoDB → TDX 降级
- `data_source_manager`: 支持更多数据源（Tushare/AKShare/Baostock）

---

### 5. stock_api.py (3.91 KB)
**职责**: 简化的股票API接口

**主要功能**:
- `get_stock_info()` - 获取单个股票信息
- `get_all_stocks()` - 获取所有股票列表

**使用场景**: `app/services/simple_analysis_service.py`

**与 interface.py 的区别**:
- `stock_api`: 简化接口，适合简单场景
- `interface.py`: 完整接口，支持所有功能

---

### 6. unified_dataframe.py (5.77 KB)
**职责**: 统一DataFrame格式，支持多数据源降级

**主要功能**:
- `get_china_daily_df_unified()` - 统一的A股日线数据获取
- 多数据源降级：Tushare → AKShare → Baostock
- DataFrame格式标准化

**使用场景**: `app/services/screening_service.py`

**与 data_source_manager 的区别**:
- `unified_dataframe`: 返回 DataFrame，适合数据分析
- `data_source_manager`: 返回格式化字符串，适合Agent使用

---

### 7. providers_config.py (9.29 KB)
**职责**: 数据源提供器配置管理

**主要功能**:
- `DataSourceConfig` 类
- 管理所有数据源的配置（Tushare/AKShare/Baostock/TDX/Finnhub等）
- 环境变量读取
- 配置验证

**使用场景**: 
- `app/core/unified_config.py`
- `app/models/config.py`
- `app/routers/config.py`
- `app/services/config_service.py`

**与 config.py 的区别**:
- `providers_config`: 数据源提供器配置
- `config.py`: Dataflows模块通用配置

---

### 8. config.py (2.32 KB)
**职责**: Dataflows模块的通用配置管理

**主要功能**:
- `initialize_config()` - 初始化配置
- `set_config()` - 设置配置
- `get_config()` - 获取配置
- `DATA_DIR` - 数据目录

**使用场景**: `optimized_china_data.py`

---

### 9. utils.py (1.17 KB)
**职责**: 通用工具函数

**主要功能**:
- `save_output()` - 保存DataFrame到CSV
- `get_current_date()` - 获取当前日期
- `decorate_all_methods()` - 装饰器
- `get_next_weekday()` - 获取下一个工作日

**使用场景**: `tradingagents/utils/news_filter_integration.py`

---

## 🔄 使用建议

### 对于新功能开发

1. **获取股票数据**:
   - 推荐使用: `interface.get_china_stock_data_unified()`
   - 备选: `data_source_manager.get_china_stock_data_unified()`

2. **获取基本面数据**:
   - 推荐使用: `optimized_china_data.get_china_fundamentals_cached()`
   - 备选: `interface.get_china_stock_fundamentals_tushare()`

3. **数据分析场景**:
   - 推荐使用: `unified_dataframe.get_china_daily_df_unified()`
   - 返回 DataFrame，适合 pandas 操作

4. **简单查询场景**:
   - 推荐使用: `stock_api.get_stock_info()`
   - 简化接口，快速获取基本信息

### 对于维护和重构

1. **大文件问题**:
   - `interface.py`, `data_source_manager.py`, `optimized_china_data.py` 都是核心文件
   - 建议保持现状，避免大规模重构带来的风险
   - 如需优化，采用渐进式重构

2. **功能重叠**:
   - 不同文件服务不同场景，重叠是合理的
   - `data_source_manager`: Agent场景（返回字符串）
   - `unified_dataframe`: 数据分析场景（返回DataFrame）
   - `stock_data_service`: MongoDB → TDX 降级场景

3. **配置管理**:
   - `providers_config.py`: 数据源配置（被广泛使用，保留）
   - `config.py`: Dataflows通用配置（保留）

---

## 📚 相关文档

- `docs/CACHE_CONFIGURATION.md` - 缓存配置指南
- `docs/CACHE_REFACTORING_SUMMARY.md` - 缓存系统重构总结
- `docs/UTILS_CLEANUP_SUMMARY.md` - Utils文件清理总结
- `docs/TUSHARE_ADAPTER_REFACTORING.md` - Tushare Adapter重构总结
- `docs/ADAPTER_PROVIDER_REORGANIZATION.md` - Adapter和Provider文件重组总结
- `docs/DATAFLOWS_ARCHITECTURE_ANALYSIS.md` - Dataflows架构分析
- `docs/DATAFLOWS_CONSERVATIVE_REFACTORING.md` - Dataflows保守优化总结

---

## 🎯 设计原则

1. **向后兼容**: 保持现有接口不变
2. **渐进式重构**: 避免大规模改动
3. **职责分离**: 不同场景使用不同文件
4. **文档优先**: 通过文档说明架构，而不是强制重构

---

**最后更新**: 2025-10-01

---

### Overview (`docs/07-courses/v3.0/README.md`)

# 高级实战课程 v3.0:从散户到系统交易者

> **版本**: v3.0 | **更新时间**: 2026-07-31 | **适用平台**: TradingAgents-CN v3.0
>
> **重要**:本课程**仅适用于 A 股和 ETF 基金分析**。港股、美股的前端入口已下线(2026-07-31),后端代码暂未清理但用户不可见,本课程不涉及。
>
> 本课程是**高级实战课程 v2.x(advanced/)的升级版**,按"炒股全生命周期"视角重新组织,覆盖 v3.0 平台全部新增能力。
> 老学员迁移指引见 [附录 C](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/appendices/C-from-v2-migration-guide.md)。

---

## 🎯 课程定位

**这不是"功能手册",而是"炒股全生命周期视角下,使用 TradingAgents-CN 平台做分析的能力培养"。**

学完本课程,你将能够:
- 在每个炒股阶段(发现→跟踪→持仓→复盘→扩展)熟练使用平台功能
- 理解"短线"与"中长线"两种风格的真实差异
- 平台功能不够用时,自己用 AI 工作流架构师、Agent 工坊、Skill 中心扩展
- 形成自己的个人交易计划,持续迭代

## 🗺️ 课程地图(必看)

**核心视角**: 一次完整的炒股决策,会经历 5 个阶段。本课程按这 5 个阶段组织:

```text
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   1.发现 ──→ 2.跟踪 ──→ 3.持仓 ──→ 4.复盘 ──→ 5.扩展(平台)   │
│    │           │           │           │            │           │
│   5 课        4 课        6 课        4 课         3 课         │
│  22 课时     16 课时     24 课时     16 课时      12 课时       │
│                                                                 │
│   + 短线风格专章(3 课) + 中长线风格专章(3 课) + 个人计划(2 课) │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## 📚 课程结构(30 课,8 阶段 + 1 导读)

### [阶段 0:课程导读](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/README.md#导读)
- **第 0 课**: 全课程地图与学习路径(必读,5 分钟)

### [阶段 1:发现(5 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/README.md) — 怎么从 6000 只股票里找到值得研究的?
- 第 1 课: 股票筛选(从 6000 → 500)
- 第 2 课: 批量分析(从 500 → 50)
- 第 3 课: 单股研究入门(从 50 → 10)
- 第 4 课: 单股研究进阶·多情景辩论
- 第 5 课: 发现阶段的常见错误

### [阶段 2:跟踪(4 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-02-track/README.md) — 用 AI 助手持续跟进
- 第 6 课: AI 助手功能全景
- 第 7 课: 用 AI 助手做行业研究
- 第 8 课: AI 助手驱动日常研究闭环
- 第 9 课: 定时分析与跟踪节奏

### [阶段 3:持仓(6 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-03-position/README.md) — 买了之后怎么管?
- 第 10 课: 模拟交易:先练手再真金白银
- 第 11 课: 持仓研究:AI 帮我监控我的持仓
- 第 12 课: 加减仓决策:看 AI 研究输出做判断
- 第 13 课: 风险跟踪:用交易计划设置止盈止损规则
- 第 14 课: 持仓阶段的常见错误
- 第 15 课: AI 智能助手在持仓阶段的应用

### [阶段 4:复盘(4 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-04-review/README.md) — 卖完了怎么回顾?
- 第 16 课: 操作复盘:这笔交易做对了吗
- 第 17 课: 案例库沉淀:把经验变成可复用的资产
- 第 18 课: 复盘结果怎么指导下次交易
- 第 19 课: 持续优化:基于复盘迭代交易计划

### [阶段 5:短线风格应用(3 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-05-short-term/README.md) — 短线用户专章
- 第 20 课: 短线研究的平台工具链
- 第 21 课: 短线研究实战(上)·发现与跟踪
- 第 22 课: 短线研究实战(下)·跟踪与复盘

### [阶段 6:中长线风格应用(3 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-06-long-term/README.md) — 中长线用户专章
- 第 23 课: 中长线研究的平台工具链
- 第 24 课: 中长线实战(上)·价值股估值修复
- 第 25 课: 中长线实战(下)·成长股业绩跟踪

### [阶段 7:平台扩展(3 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-07-extension/README.md) — 功能不够用,自己造!
- 第 26 课: AI 工作流架构师:用自然语言生成工作流
- 第 27 课: Agent 工坊 + Skill 中心:自定义分析师
- 第 28 课: 实战:以巴菲特工作流为例,端到端造一个

### [阶段 8:个人交易计划(2 课)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-08-personal-plan/README.md) — 把方法论变成自己的
- 第 29 课: 个人交易计划模板
- 第 30 课: 持续优化与成长

### [附录](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/appendices/README.md)
- 附录 A: v3.0 平台能力速查表
- 附录 B: 学习路径建议(短线 vs 中长线用户怎么选课)
- 附录 C: 从 v2.x 课程迁移指引(给老学员)

---

## 📊 课时统计

| 阶段 | 课数 | 课时(分钟) | 重要程度 |
|------|------|------------|----------|
| 0.导读 | 1 | 5 | ⭐⭐⭐ 必读 |
| 1.发现 | 5 | 100 | ⭐⭐⭐ 核心 |
| 2.跟踪 | 4 | 80 | ⭐⭐⭐ 核心 |
| 3.持仓 | 6 | 120 | ⭐⭐⭐ 核心 |
| 4.复盘 | 4 | 80 | ⭐⭐⭐ 核心 |
| 5.短线 | 3 | 60 | ⭐⭐ 选读(短线用户) |
| 6.中长线 | 3 | 60 | ⭐⭐ 选读(中长线用户) |
| 7.平台扩展 | 3 | 60 | ⭐⭐ 进阶 |
| 8.个人计划 | 2 | 40 | ⭐⭐ 收尾 |
| **合计** | **30 课** | **约 600 分钟(10 小时)** | — |

## 🛤️ 学习路径建议

### 🆕 新学员(没学过 v2.x 课程)
**完整学完所有 30 课**,预计 10-12 小时。

### 🎯 短线用户
**必学** 1→2→3→4→5→6→7→8→9→10→11→12→13→14→15→16→17→18→19→20→21→22
**跳过** 23→24→25(中长线专章)
**选学** 26→27→28→29→30(平台扩展 + 个人计划)
预计 7-8 小时。

### 📈 中长线用户
**必学** 1→2→3→4→5→6→7→8→9→10→11→12→13→14→15→16→17→18→19→23→24→25
**跳过** 20→21→22(短线专章)
**选学** 26→27→28→29→30
预计 7-8 小时。

### 👴 老学员(学过 advanced/ v2.x)
**先读** [附录 C 迁移指引](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/appendices/C-from-v2-migration-guide.md),了解与 v2.x 的差异
**重点学 v3.0 新增/重写的 9 课**(第 5、6、8、14、15、18、26、27、28)
**复习** 你之前跳过的部分
预计 3-4 小时。

---

## 🔄 与 v2.x(advanced/)课程的关系

| 项目 | v2.x 课程(advanced/) | v3.0 课程(本目录) |
|------|------------------|----------------|
| 组织方式 | 按"功能模块"(选股/择时/执行/...) | 按"炒股生命周期"(发现/跟踪/持仓/复盘/扩展) |
| 课时 | 25 课 | 30 课(更细颗粒度) |
| v3.0 平台能力 | ❌ 完全没提 | ✅ 完整覆盖(AI 助手/京东云/MCP/渠道推送) |
| 港美股内容 | ⚠️ 含已暂停功能 | ✅ 仅 A 股(已清理) |
| 平台扩展 | 1 课(Buffett) | 3 课(AI 架构师 + Agent + Skill) |
| 角色 | **保留作为历史** | **推荐学习** |

**重要**: v2.x 课程**不会删除**,作为历史参考保留。老学员不必重学全部,可参考迁移指引选择性学习。

---

## 💡 课程特色

1. **视角化组织**:不是"功能怎么用",而是"这个阶段怎么用"
2. **真实场景驱动**:每课都有"实际跑一次"的实操作业
3. **v3.0 完整覆盖**:AI 助手、京东云、平台扩展等新能力都讲透
4. **风格专章独立**:短线 vs 中长线用户各自有专章
5. **平台扩展专章**:教你自己造工作流(巴菲特案例)

---

## 📚 配套资源

- **用户手册**: [v3.0 完整使用手册](file:///c:/TradingAgentsCN/docs/02-user-guide/user-manual-v3.0.md) | [京东云合作版手册](file:///c:/TradingAgentsCN/docs/02-user-guide/jdyun-user-manual-v3.0.md)
- **使用问答助手**: 平台右下角"使用问答"浮窗(任何系统使用问题都可问)
- **AI 对话助手**: 主菜单"智能助手"(任何分析/查报告问题都可问)
- **用户学习中心**: 侧边栏「学习中心」菜单(在线学习路径)

---

## 🚀 立即开始

- **第一次来?** 从 [第 0 课:全课程地图](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/README.md#导读) 开始
- **急用?** 选你的学习路径(短线/中长线/老学员),跳过选读章节
- **碰到问题?** 随时点右下角"使用问答"浮窗

---

> **最后更新**: 2026-07-31 | **版本**: v3.0
> **配套文档**: [用户手册 v3.0](file:///c:/TradingAgentsCN/docs/02-user-guide/user-manual-v3.0.md) | [京东云手册 v3.0](file:///c:/TradingAgentsCN/docs/02-user-guide/jdyun-user-manual-v3.0.md)
> **历史版本**: [v2.x 课程(advanced/)](file:///c:/TradingAgentsCN/docs/07-courses/advanced/README.md)

---

### Overview (`docs/07-courses/v3.0/phase-01-discover/README.md`)

# 阶段 1:发现——从 6000 只股票里找到值得研究的

> **5 课** | **总课时**: 约 2 小时 | **难度**: ⭐ 入门

## 🎯 阶段目标

完成本阶段后,你能从 6000 只 A 股里,**系统化**地筛出 10 只值得深度研究的股票。

## 📍 阶段路线图

```
6000 只 A 股
   │
   │  第 1 课: 自然语言筛选 / 条件筛选
   ↓
500-1000 只
   │
   │  第 2 课: 批量分析(单次 ≤ 10 只,分批跑)
   ↓
50-100 只
   │
   │  第 3 课: 单股研究(3 级标准深度)
   ↓
10-20 只
   │
   │  第 4 课: 多情景辩论(所有深度都跑)
   ↓
2-3 只核心标的
   │
   │  第 5 课: 避雷清单(经验沉淀)
   ↓
[阶段 2:跟踪] 或 [阶段 3:建仓]
```

## 📚 课程列表

| 课 | 主题 | 时长 | 关键产出 |
|----|------|------|---------|
| [第 1 课](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-01-stock-screening.md) | 股票筛选(自然语言 + 条件) | 20 分钟 | 500-1000 只股票池 |
| [第 2 课](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-02-batch-analysis.md) | 批量分析(单次 ≤ 10 只) | 25 分钟 | 50 只窄选 |
| [第 3 课](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md) | 单股研究入门(5 级深度) | 30 分钟 | 10-20 只深度研究 |
| [第 4 课](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-04-single-analysis-multi-scenario.md) | 多情景辩论(2 角色 + 1 整合员) | 30 分钟 | 2-3 只核心标的 |
| [第 5 课](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-05-discover-pitfalls.md) | 发现阶段常见错误 | 25 分钟 | 个人避雷清单 |

## 🔑 阶段关键概念(基于真实功能)

- **自然语言筛选**: 「股票筛选」菜单默认 Tab,基于 LLM 意图理解,支持多轮对话
- **条件筛选**: 「股票筛选」菜单里的"高级模式" Tab,精确字段构建
- **批量分析**: 侧边栏「批量分析」菜单,单次最多 10 只,5 级深度
- **单股研究**: 侧边栏「单股研究」菜单,5 级深度,12 个子报告
- **2 角色辩论 + 1 整合员**: bull_researcher / bear_researcher / research_team_decision(所有深度,区别在轮数)
- **3 风险视角**: risky_analyst / safe_analyst / neutral_analyst(所有深度)
- **合规术语**: 决策 action ∈ {乐观, 审慎, 中性}(不是 买入/卖出/持有)

## ⚠️ 阶段限制(基于实际代码)

- ⚠️ **平台仅支持 A 股和 ETF 基金**(港美股前端入口已下线)
- ⚠️ **批量分析单次 ≤ 10 只**(后端硬限制)
- ⚠️ **京东云版单并发**,批量任务串行执行
- ⚠️ 所有深度都跑辩论角色(1-3 级 1 轮、4 级 2 轮、5 级 3 轮)

## 🎓 学完后能做什么

完成本阶段后,你可以:
- 用一句话告诉 AI"我要什么股票"
- 一次性分析 10 只股票
- 读懂 12 个子报告的含义
- 识别 AI 报告的合规术语
- 避开新手最常见的 7 个错误

## ⏭️ 下一步

完成本阶段后,进入 [**阶段 2:跟踪**](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-02-track/README.md)——研究完后,怎么持续跟踪?

也可以根据实际情况**提前进入阶段 3**(持仓)或**阶段 4**(复盘)。

---

### 02 User Guide Learning 06 Resources Tradingagents Intro (`docs/02-user-guide/learning-06-resources/tradingagents-intro.md`)

# TradingAgents项目介绍

**分类**: 源项目与论文
**难度**: 进阶
**阅读时间**: 15分钟
**更新日期**: 2025-11-15

---

## 📋 引言

TradingAgents-CN是基于**TradingAgents**项目开发的中文本地化版本。TradingAgents是一个开源的AI驱动的多智能体股票分析平台，由Tauric Research团队开发。本文将介绍TradingAgents项目的背景、核心理念和技术架构。

---

## 🎯 项目背景

### TradingAgents的诞生

TradingAgents项目起源于学术研究，旨在探索如何利用大语言模型（LLM）和多智能体系统来提升股票分析的质量和效率。

**研究团队**：
- Tauric Research团队
- 多位AI和金融科技领域的专家

**发表论文**：
- 📄 论文标题：*"TradingAgents: TradingAgents: Multi-Agents LLM Financial Trading
Framework"*
- 📅 发表时间：2024年
- 🔗 论文链接：[arXiv](https://arxiv.org/pdf/2412.20138)

---

## 🏗️ 核心架构

### 1. 多层架构设计

TradingAgents采用分层架构，将复杂的股票分析任务分解为多个层次：

```
┌─────────────────────────────────────────┐
│         应用层（Application Layer）        │
│  股票研究分析、持仓跟踪、风险审阅等          │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         智能体层（Agent Layer）            │
│  分析师、研究员、研究整合员等多个智能体          │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         工具层（Tool Layer）               │
│  数据获取、技术分析、基本面分析等工具        │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│         数据层（Data Layer）               │
│  市场数据、财务数据、新闻数据等             │
└─────────────────────────────────────────┘
```

### 2. 多智能体协作机制

TradingAgents的核心创新是**多智能体辩论机制**：

**智能体角色**：
- 🔍 **研究员（Researcher）**：收集和整理信息
- 📊 **分析师（Analyst）**：进行深度分析
- 💼 **研究整合员（Research Integrator）**：汇总研究结论
- 🎯 **风险评估师（Risk Assessor）**：评估风险
- 👨‍💼 **研究审阅员（Research Reviewer）**：综合审阅研究结论

**协作流程**：
1. 研究员收集数据和信息
2. 分析师从不同角度分析
3. 智能体之间进行辩论
4. 达成共识或保留分歧
5. 生成综合分析报告

---

## 🔬 核心技术

### 1. LLM集成

TradingAgents支持多种大语言模型：

- **OpenAI系列**：GPT-3.5、GPT-4、GPT-4-Turbo
- **开源模型**：LLaMA、Mistral、Qwen等
- **API服务**：支持自定义LLM API

### 2. 工具系统

TradingAgents提供丰富的股票分析工具：

**数据获取工具**：
- Yahoo Finance API
- Alpha Vantage API
- Finnhub API
- 自定义数据源

**分析工具**：
- 技术指标计算（MA、MACD、RSI等）
- 基本面分析（PE、PB、ROE等）
- 情感分析（新闻、社交媒体）
- 风险评估（VaR、夏普比率等）

### 3. 提示词工程

TradingAgents使用精心设计的提示词模板：

```python
# 分析师提示词示例
ANALYST_PROMPT = """
你是一位资深的股票分析师，擅长从多个维度分析股票。

任务：分析以下股票的投资价值

股票信息：
{stock_info}

市场数据：
{market_data}

请从以下角度进行分析：
1. 基本面分析
2. 技术面分析
3. 行业地位
4. 风险因素

最后给出研究结论倾向（乐观/审慎/中性）和理由，不输出买入/卖出等交易指令。本系统定位为研究辅助工具，所有输出仅供研究参考，不构成投资建议。
"""
```

---

## 🌟 核心特性

### 1. 开源与可扩展

- ✅ 开源核心组件（Apache License 2.0）
- 🔒 专有组件遵循项目根目录许可证说明（见 LICENSE 与 LICENSING.md）
- ✅ 模块化设计，易于扩展
- ✅ 支持自定义智能体和工具
- ✅ 活跃的社区支持

### 2. 多市场支持

- 🇺🇸 美股市场
- 🇨🇳 A股市场（TradingAgents-CN增强）
- 🇭🇰 港股市场

### 3. 灵活的部署方式

- 💻 本地部署
- ☁️ 云端部署
- 🐳 Docker容器化
- 🌐 Web界面

---

## 📊 TradingAgents-CN的改进

TradingAgents-CN在TradingAgents的基础上进行了大量本地化改进：

### 1. 中国市场适配

- ✅ 支持A股、港股数据源
- ✅ 集成Tushare、AKShare等国内数据接口
- ✅ 适配中国市场交易规则
- ✅ 中文提示词优化

### 2. 用户体验优化

- ✅ 现代化的Web界面
- ✅ 实时数据同步
- ✅ 模拟交易功能
- ✅ 股票筛选工具

### 3. 部署简化

- ✅ 一键安装脚本
- ✅ 绿色版（Windows便携版）
- ✅ Docker镜像
- ✅ 详细的中文文档

### 4. 功能增强

- ✅ 多数据源支持
- ✅ 定时任务调度
- ✅ 缓存优化
- ✅ 日志管理
- ✅ 用户权限系统

---

## 📖 学术论文

### 论文摘要

TradingAgents论文提出了一个开源的AI智能体平台，用于股票分析和交易。该平台利用大语言模型的能力，通过多智能体协作机制，实现了高质量的股票分析。

**主要贡献**：

1. **多智能体框架**：提出了基于角色的多智能体协作框架
2. **工具系统**：设计了可扩展的股票分析工具系统
3. **实验验证**：通过实验证明了多智能体辩论的有效性
4. **开源平台**：提供了完整的开源实现

### 论文下载

- 📄 [英文原版PDF](/research-papers/TradingAgents_paper.pdf)
- 📄 [中文翻译版](../../paper/TradingAgents_论文中文版.md)
- 📄 [arXiv在线版](https://arxiv.org/pdf/2412.20138)
- 📄 [论文解读](./paper-guide.md)

---

## 🔗 相关资源

### 官方资源

- 🌐 [TradingAgents（源项目）](https://github.com/TauricResearch/TradingAgents)
- 📚 [TradingAgents文档](https://github.com/TauricResearch/TradingAgents)

### TradingAgents-CN资源

- 🌐 [GitHub仓库](https://github.com/hsliuping/TradingAgents-CN)
- 📚 [中文文档](../../README.md)
- 💬 [问题反馈](https://github.com/hsliuping/TradingAgents-CN/issues)

### 学习资源

- 📖 [多智能体系统详解](../04-analysis-principles/multi-agent-system.md)

---

## 💡 总结

TradingAgents是一个创新的开源股票分析平台，通过多智能体协作和大语言模型，为股票分析提供了新的解决方案。TradingAgents-CN在此基础上进行了深度本地化，使其更适合中国市场和中文用户。

**核心价值**：
- 🎯 学术研究与实际应用的结合
- 🎯 开源社区的力量
- 🎯 AI技术在股票分析领域的创新应用
- 🎯 降低股票分析的门槛

---

## ❓ 常见问题

**Q: TradingAgents和TradingAgents-CN有什么区别？**

A: TradingAgents-CN是TradingAgents的中文本地化版本，增加了对中国市场的支持，优化了用户体验，并提供了更完善的中文文档。

**Q: 可以商业使用吗？**

A: 可以。TradingAgents和TradingAgents-CN都采用开源许可证，允许商业使用。但请注意遵守相关金融法规。

**Q: 如何贡献代码？**

A: 欢迎贡献！请访问GitHub仓库，提交Pull Request或Issue。

---

**下一步阅读**：
- 📖 [论文中文版](../../paper/TradingAgents_论文中文版.md)
- 📖 [多智能体系统](../04-analysis-principles/multi-agent-system.md)
- 📖 [快速开始](../07-tutorials/getting-started.md)

---

### 02 User Guide User Manual V3.0 (`docs/02-user-guide/user-manual-v3.0.md`)

# TradingAgents-CN v3.0 完整使用手册

> 版本：v3.0 | 更新日期：2026-07-25 | 适用对象：新用户与进阶用户
>
> TradingAgents-CN Pro 是一款多智能体（Multi-Agent）投资研究平台，通过自然语言对话、可编排的分析工作流与可扩展的 Agent/Skill 工坊，把投资研究全流程串联起来。

---

## 目录

- [v3.0 分析能力全景](#v30-分析能力全景)
- [快速了解（30秒入门）](#快速了解30秒入门)
- [学习路径（从入门到精通）](#学习路径从入门到精通)
- [系统能为您做什么](#系统能为您做什么)
  - [v3.0 治理能力（让 AI 不再是黑盒）](#v30-治理能力让-ai-不再是非黑盒)
- [第一章 安装部署](#第一章-安装部署)
  - [1.1 Windows 安装包部署](#11-windows-安装包部署)
  - [1.2 Docker 部署](#12-docker-部署)
  - [1.3 部署验证](#13-部署验证)
  - [1.4 京东云合作版部署（可选）](#14-京东云合作版部署可选)
- [第二章 首次配置](#第二章-首次配置)
  - [2.1 API 密钥配置](#21-api-密钥配置)
  - [2.2 系统初始化](#22-系统初始化)
  - [2.4 使用指南](#24-使用指南-guide)
- [第三章 基础功能](#第三章-基础功能)
  - [3.1 仪表板](#31-仪表板-dashboard)
  - [3.2 单股研究](#32-单股研究-analysissingle)
  - [3.3 研究报告](#33-研究报告-reports)
  - [3.4 股票筛选](#34-股票筛选-screening)
  - [3.5 股票关注列表](#35-股票关注列表-favorites)
  - [3.6 任务中心](#36-任务中心-tasksunified)
  - [3.7 股票详情页](#37-股票详情页-stockscode)
- [第四章 交易功能](#第四章-交易功能)
  - [4.1 模拟交易](#41-模拟交易-paper)
  - [4.2 持仓研究](#42-持仓研究-portfolio)
  - [4.3 操作复盘](#43-操作复盘-review)
  - [4.4 交易计划](#44-交易计划-trading-system)
- [第五章 智能助手](#第五章-智能助手)
  - [5.1 AI 对话助手](#51-ai-对话助手-assistant)
  - [5.2 AI 记忆](#52-ai-记忆-memory)
- [第六章 高级功能](#第六章-高级功能)
  - [6.1 分析流](#61-分析流-workflow)
  - [6.1.1 流程管理](#611-流程管理)
  - [6.1.2 AI 工作流架构师](#612-ai-工作流架构师)
  - [6.1.3 工具配置](#613-工具配置)
  - [6.1.4 Agent 工坊](#614-agent-工坊)
  - [6.1.5 Skill 中心](#615-skill-中心)
  - [6.1.6 MCP 服务器](#616-mcp-服务器)
  - [6.2 Agent 工坊（独立入口）](#62-agent-工坊独立入口)
  - [6.3 Skill 中心（独立入口）](#63-skill-中心独立入口)
  - [6.4 批量分析](#64-批量分析-analysisbatch)
  - [6.5 定时分析](#65-定时分析)
    - [6.5.1 定时分析分组](#651-定时分析分组-settingswatchlist-groups)
    - [6.5.2 定时分析配置](#652-定时分析配置-settingsscheduled-analysis)
  - [6.6 通用研究（/analysis/general）](#66-通用研究analysisgeneral)
- [第七章 学习中心](#第七章-学习中心-learning)
- [第八章 系统管理](#第八章-系统管理)
  - [8.1 配置管理](#81-配置管理)
  - [8.2 数据库管理](#82-数据库管理)
  - [8.3 数据同步](#83-数据同步)
  - [8.4 定时任务](#84-定时任务)
  - [8.5 日志管理](#85-日志管理)
  - [8.6 能力索引](#86-能力索引)
  - [8.7 缓存管理](#87-缓存管理)
  - [8.8 数据导入管理](#88-数据导入管理-settingsdata-import)
  - [8.9 社媒消息管理](#89-社媒消息管理-settingssocial-media)
  - [8.10 系统更新](#810-系统更新-settingsupdate)
  - [8.11 提示词模板](#811-提示词模板-settingstemplates)
  - [8.12 注入策略管理](#812-注入策略管理-settingsprompt-policies)
  - [8.13 Prompt 设计助手](#813-prompt-设计助手-settingsprompt-design)
  - [8.14 行业/个股配置](#814-行业个股配置-settingsanalysis-profiles)
  - [8.15 使用统计](#815-使用统计-settingsusage)
- [第九章 个人设置](#第九章-个人设置-settings)
- [第十章 常见问题（FAQ）](#第十章-常见问题faq)
  - [Q13：京东云合作版与标准版有什么区别？](#q13京东云合作版与标准版有什么区别)
  - [Q14：京东云版分析任务报 429 限速错误怎么办？](#q14京东云版分析任务报-429-限速错误怎么办)
- [第十一章 最佳实践](#第十一章-最佳实践)
  - [11.1 从安装到首次分析](#111-从安装到首次分析)
  - [11.2 日常研究工作流](#112-日常研究工作流)
  - [11.3 成本控制实践](#113-成本控制实践)
  - [11.4 深度使用：自定义工作流、Agent 和 Skill](#114-深度使用自定义工作流agent-和-skill)
  - [11.5 数据管理实践](#115-数据管理实践)
  - [11.6 安全实践](#116-安全实践)
  - [11.7 版本升级实践](#117-版本升级实践)
  - [11.8 京东云合作版使用建议](#118-京东云合作版使用建议)
- [第十二章 关于（/about）](#第十二章-关于-about)
- [新手常见错误与避免方法](#新手常见错误与避免方法)
- [附录](#附录)

---

## 关于本手册

### 阅读对象

本手册面向首次使用 TradingAgents-CN Pro v3.0 的用户，从安装部署开始，逐步介绍所有功能模块的使用方法。无论您是普通投资者还是进阶用户，都可以按照章节顺序学习，或通过目录直接跳转到感兴趣的功能。

### 高级功能标识

本手册中出现的 **（高级功能）** 标识，表示该功能需要"高级学员"权限才能使用。普通用户可浏览相关界面，但执行操作时会被提示权限不足。

### v3.0 版本说明

v3.0 是一次平台化升级，核心变化包括：

- 智能助手从"分析触发器"升级为"投资研究协同入口"，支持 20+ 操作工具、多主题会话。
- 新增 MCP Server 开放接口，可被 Claude Desktop、Cursor 等外部客户端调用。
- 新增 AI 工作流架构师，自然语言描述需求即可自动规划工作流。
- 新增 Skill 自动生成系统，AI 自主编写并验证新工具。
- 新增选股助手、统一通知系统（邮件/飞书/钉钉/企业微信多渠道推送）、QQ Bot 接入等能力。

---

## v3.0 分析能力全景

v3.0 内置 **80+ 个分析工具**，覆盖 **10 大类**，把传统需要付费第三方工具才能完成的事，全部内置到平台里。下面这张表是您升级 v3.0 后**能直接用**的能力清单（数字为各类工具的概数，完整列表见 8.6 工具能力索引）。

### 一张表看懂 80+ 分析工具

| 大类 | 数量 | 典型能力 | 解决什么问题 |
|------|------|---------|-------------|
| **基本面** | 20+ | PE/PB/ROE、毛利率、营收、现金流、DCF 估值、WACC、杜邦分析 | 这家公司赚不赚钱、值不值钱 |
| **技术面** | 9 | MA、RSI、KDJ、MACD、K 线形态、图表形态、斐波那契、支撑压力 | 这只股票该不该买、什么时候买 |
| **风险检测** | 5 | Altman Z（破产预警）、Beneish M（财报造假）、Piotroski F（财务健康）、Ohlson O（破产预测）、财报造假信号 | 这家公司有没有爆雷风险 |
| **市场行情** | 9 | 大盘、板块、筹码分布（获利比例/平均成本）、个股行情、QMT 接入 | 现在是什么市场环境、哪些板块在涨 |
| **组合分析** | 9 | 夏普比率、信息比率、最大回撤、收益归因、VaR、压力测试 | 我的持仓风险大不大、哪里贡献了收益 |
| **新闻情绪** | 2 | 新闻拉取（标题+明细双阶段）、雪球/股吧情绪 | 市场在讨论什么、情绪偏多还是偏空 |
| **复盘分析** | 4 | 交易记录、账户信息、行情快照、归因分析 | 上次为什么赚/亏，下次怎么改 |
| **选股估值** | 5 | 多因子选股、价值选股、PEG、Graham 估值、期权定价 | 哪些股票值得进一步研究 |
| **智能助手操作** | 20+ | 触发分析、查报告、管关注、管定时、看 Token 统计、看系统状态 | 不用找菜单，对话就能操作 |
| **自构建工具** | 2 | Agent 工坊、Skill 中心 | 您自己也能造新分析师和新工具 |

### 5 个最值得立刻体验的能力

> 这 5 个能力很多是 v2.x 已有、v3.0 加强的实用工具，**v3.0 的真正升级在治理能力（可追溯/可验证/可纠错）**，分析工具只是基础。

| 能力 | 工具名 | 用法 | 适用场景 |
|------|--------|------|---------|
| **1. 财报造假检测** | `get_beneish_mscore` | 输入股票代码，5 分钟出 8 维度评分（> -1.78 提示造假可能） | 重仓股/关注标的必查 |
| **2. 破产风险评估** | `get_altman_zscore` | 5 因子模型，< 1.81 提示破产风险 | ST 候选/财务异常股 |
| **3. DCF 现金流折现估值** | `get_dcf_valuation` | 预测期 + 永续期，自动算公司值多少钱 | 长期价值投资决策 |
| **4. K 线形态识别** | `get_candlestick_patterns` | 自动识别 25+ 种 K 线形态（锤子/吞没/十字星/晨星/三兵） | 短线择时、找拐点 |
| **5. 经典图表形态** | `get_chart_patterns` | 头肩顶底、双顶双底、三角、旗形、楔形 | 中长线趋势判断 |

### 数据有出处，不是"AI 猜的"

每个数据点都能查到来源：

- **PE/PB/ROE** → 来自 Tushare 财报数据
- **行情数据** → 来自 Tushare / QMT / AKShare 实时接口
- **新闻** → 来自 Tushare / AKShare 公开来源新闻接口
- **情绪** → 优先基于新闻内容和用户提交的社交媒体记录进行分析
- **AI 推论** → 来自 LLM，**系统会标记哪些是 AI 推论哪些是真实数据**

报告里如果出现"AI 推论"标签，说明这个结论是 AI 推理的（不是直接拿到的数据），请结合其他信息判断。

### 完整工具索引

> 💡 **提示**：本节只是**能力全景**。具体怎么用，在第五章智能助手、第六章分析流、以及 11.4 最佳实践中按场景讲解。

如果您想了解某个具体工具的详细参数和计算方法：
- 估值类（DCF/WACC/PEG/Graham）→ 系统管理 → 工具能力索引（8.6 节）
- 技术类（MA/RSI/形态/支撑压力）→ 系统管理 → 工具能力索引（8.6 节）
- 风险类（Altman/Beneish/Piotroski）→ 系统管理 → 工具能力索引（8.6 节）

---

## 快速了解（30秒入门）

**TradingAgents-CN Pro 是什么？**

一款 AI 驱动的投资研究平台，通过多个智能体（Agent）协同工作，帮您完成从数据收集、基本面分析、技术面分析到风险评估的全流程研究。

**能帮我做什么？**

| 场景 | 功能 | 耗时 |
|------|------|------|
| 快速了解一只股票 | 单股研究（快速分析） | 5-10分钟 |
| 深度研究持仓标的 | 单股研究（深度分析） | 10-15 分钟 |
| 同时分析多只股票 | 批量分析 | 每只 5-15 分钟 |
| 定时跟踪股票关注列表 | 定时分析 | 自动执行 |
| 自然语言对话研究 | 智能助手 | 实时 |
| 自定义分析流程 | 分析流（工作流编辑器） | 一次性配置 |
| 模拟交易验证策略 | 模拟交易 | 实时 |

**我该怎么开始？**

1. 按第一章安装部署系统
2. 按第二章完成首次配置（API密钥 + 数据源）
3. 跟随"使用指南"（左侧导航栏）完成引导配置
4. 在"单股研究"中输入股票代码，开始第一次分析

> 💡 **提示**：新手建议先使用"3级-标准分析"深度，选中"市场分析师"和"基本面分析师"两个角色，4-8分钟即可获得一份完整的研究报告。

---

## 学习路径（从入门到精通）

本手册按5个阶段组织，每个阶段有明确的学习目标和完成标志。建议按顺序学习，循序渐进。

### 阶段 1：入门（第 1 天）— 跑通第一次分析

**目标**：完成系统安装和配置，生成第一份分析报告。

| 序号 | 学习内容 | 手册章节 | 预计耗时 |
|------|---------|---------|---------|
| 1 | 安装系统 | 第一章 安装部署 | 30 分钟 |
| 2 | 配置 API 密钥和数据源 | 第二章 首次配置 | 20 分钟 |
| 4 | 跟随使用指南完成引导配置 | 2.4 使用指南 | 15 分钟 |
| 5 | 完成第一次单股研究 | 3.2 单股研究 | 10 分钟 |

**✅ 完成标志**：成功生成一份完整的分析报告，能看到综合评级和各维度分析。

**📋 推荐练习**：选择一只熟悉的股票（如贵州茅台 600519），使用"标准分析"深度，选中全部分析师，观察报告结构。

---

### 阶段 2：基础（第 1 周）— 熟练使用核心功能

**目标**：理解报告内容，熟练使用核心研究功能。

| 序号 | 学习内容 | 手册章节 | 预计耗时 |
|------|---------|---------|---------|
| 1 | 了解仪表板布局 | 3.1 仪表板 | 10 分钟 |
| 2 | 学习报告解读方法 | 3.2 分析报告解读指南 | 15 分钟 |
| 3 | 管理历史研究报告 | 3.3 研究报告 | 10 分钟 |
| 4 | 使用股票筛选发现标的 | 3.4 股票筛选 | 15 分钟 |
| 5 | 建立股票关注列表关注列表 | 3.5 股票关注列表 | 10 分钟 |
| 6 | 查看任务执行状态 | 3.6 任务中心 | 5 分钟 |

**✅ 完成标志**：能独立完成"筛选股票 → 加入关注 → 单股研究 → 解读报告"全流程。

**📋 推荐练习**：用股票筛选找出 3 只不同行业的标的，分别分析后对比报告差异。

---

### 阶段 3：进阶（第 2-4 周）— 交易功能与高级分析

**目标**：使用模拟交易验证策略，掌握批量分析和定时分析。

| 序号 | 学习内容 | 手册章节 | 预计耗时 |
|------|---------|---------|---------|
| 1 | 模拟交易操作 | 4.1 模拟交易 | 20 分钟 |
| 2 | 持仓研究与跟踪 | 4.2 持仓研究 | 15 分钟 |
| 3 | 操作复盘改进策略 | 4.3 操作复盘 | 15 分钟 |
| 4 | 制定交易计划 | 4.4 交易计划 | 20 分钟 |
| 5 | 使用智能助手对话研究 | 5.1 AI 对话助手 | 15 分钟 |
| 6 | 管理 AI 记忆 | 5.2 AI 记忆 | 10 分钟 |
| 7 | 批量分析多只股票 | 6.4 批量分析 | 15 分钟 |
| 8 | 配置定时自动分析 | 6.5 定时分析 | 20 分钟 |

**✅ 完成标志**：能使用模拟交易验证策略，配置定时分析自动跟踪股票关注列表。

**📋 推荐练习**：建立一个 5 只股票的关注分组，配置每日盘后定时分析，观察一周的报告变化。

---

### 阶段 4：高级（第 1-2 月）— 自定义工作流与 Agent

**目标**：创建自定义工作流、Agent 和 Skill，实现个性化分析。

| 序号 | 学习内容 | 手册章节 | 预计耗时 |
|------|---------|---------|---------|
| 1 | 理解工作流概念 | 6.1 分析流 | 20 分钟 |
| 2 | 使用 AI 工作流架构师生成流程 | 6.1.2 AI 工作流架构师 | 30 分钟 |
| 3 | 配置工具能力 | 6.1.3 工具配置 | 15 分钟 |
| 4 | 在 Agent 工坊创建自定义 Agent | 6.1.4 Agent 工坊 | 40 分钟 |
| 5 | 在 Skill 中心创建自定义 Skill | 6.1.5 Skill 中心 | 40 分钟 |
| 6 | 使用通用研究探索非个股主题 | 6.6 通用研究 | 20 分钟 |
| 7 | 学习中心进阶课程 | 第七章 学习中心 | 持续 |

**✅ 完成标志**：能使用 AI 工作流架构师生成自定义流程，或手动创建一个包含自定义 Agent 的工作流。

**📋 推荐练习**：用自然语言描述"我需要一个重点关注 ESG 评分的分析流程"，让 AI 工作流架构师生成，然后在单股研究中使用该流程。

---

### 阶段 5：专家（持续）— 系统优化与最佳实践

**目标**：优化系统配置、控制成本、保障数据质量。

| 序号 | 学习内容 | 手册章节 | 预计耗时 |
|------|---------|---------|---------|
| 1 | 系统配置优化 | 第八章 系统管理 | 按需 |
| 2 | 个人偏好设置 | 第九章 个人设置 | 15 分钟 |
| 3 | 成本控制实践 | 11.3 成本控制实践 | 15 分钟 |
| 4 | 数据管理实践 | 11.5 数据管理实践 | 15 分钟 |
| 5 | 安全实践 | 11.6 安全实践 | 10 分钟 |
| 6 | 提示词模板优化 | 8.11 提示词模板 | 30 分钟 |
| 7 | MCP 服务器集成 | 6.1.6 MCP 服务器 | 按需 |
| 8 | 渠道推送配置 | 9.8 渠道推送 | 20 分钟 |

**✅ 完成标志**：能根据自身需求优化系统配置，建立稳定高效的研究工作流。

**📋 推荐练习**：配置飞书/钉钉渠道推送，让定时分析结果自动推送到工作群。

---

### 学习路径总结

| 阶段 | 时长 | 核心能力 | 关键章节 |
|------|------|---------|---------|
| 🟢 入门 | 第1天 | 跑通第一次分析 | 第一、二章 + 3.2 |
| 🔵 基础 | 第1周 | 熟练核心功能 | 第三章 + 报告解读 |
| 🟡 进阶 | 第2-4周 | 交易+高级分析 | 第四、五、六章（部分） |
| 🟠 高级 | 第1-2月 | 自定义工作流 | 6.1-6.6 + 第七章 |
| 🔴 专家 | 持续 | 系统优化 | 第八、九章 + 第十一章 |

> 💡 **提示**：不必严格按照阶段顺序学习。如果您有特定需求（如只想用定时分析），可以直接跳到对应章节。但建议至少完成阶段1和阶段2，确保理解基础概念。

---

## 系统能为您做什么

本系统是一个**投资研究辅助工具**，通过 AI 多智能体协同，帮您整理信息、提供多维度分析参考。以下客观说明各功能能提供的具体帮助。

### 功能与实际帮助对照

| 功能 | 能帮您做什么 | 不能做什么 |
|------|------------|-----------|
| **单股研究** | 整理一只股票的技术面、基本面、新闻事件、市场情绪等多维度信息，生成结构化报告，帮您节省自行搜集整理信息的时间 | 不能预测股价涨跌，不能给出必涨必跌的结论，分析结果可能存在偏差 |
| **批量分析** | 同时对多只单只股票分别执行分析，为您节省逐只操作的时间，不生成股票之间的横向比较 | 不能替代人工判断，分析结果需要您逐只核实关键数据 |
| **定时分析** | 按设定时间自动执行分析，帮您定期跟踪股票关注列表，无需每天手动操作 | 不能自动交易，不能在盘中实时预警（定时执行有延迟） |
| **模拟交易** | 提供虚拟资金环境，帮您在学习研究中验证策略假设、记录模拟操作点、统计盈亏 | 模拟环境不考虑滑点、流动性不足等真实市场因素，结果仅供学习研究参考，不构成投资建议 |
| **持仓研究** | 对已持仓股票进行深度分析，帮您梳理是否继续跟踪的参考依据 | 不能保证分析结论正确，投资决策需您自行承担 |
| **操作复盘** | 回顾历史交易记录，帮您总结操作模式中的规律性问题 | 过去的操作经验不能保证未来收益，复盘结论仅供参考 |
| **智能助手** | 通过自然语言快速查询股票信息、触发分析任务，减少操作步骤 | AI 回答可能出错，关键数据（如财务数字）请以官方公告为准 |
| **股票筛选** | 按市盈率、市净率、涨幅等条件批量筛选股票，缩小研究范围 | 筛选条件较粗，筛选结果仍需逐只深入研究 |
| **自定义工作流** | 根据自身关注点定制分析维度（如重点看 ESG、现金流等） | 需要一定学习成本，自定义 Agent 的分析质量取决于提示词设计 |
| **渠道推送** | 分析完成后自动推送到飞书/钉钉/邮件，帮您及时获知结果 | 只是通知工具，不改变分析结果本身 |

### 实际使用场景

**场景1：准备研究一只股票前**

1. 用"单股研究"生成一份标准分析报告，了解该股的基本面、技术面、风险点
2. 重点阅读"风险情景研究"部分，了解审慎情景，避免单边乐观
3. 用"模拟交易"记录假设仓位，观察一段时间以验证研究假设

**场景2：跟踪已持有的股票**

1. 将持仓股票加入"关注列表"分组
2. 配置"定时分析"，每周盘后自动分析一次
3. 开启"渠道推送"，分析完成后自动推送到手机
4. 定期查看"持仓研究"，跟踪基本面变化

**场景3：从行业中发现标的**

1. 用"股票筛选"按行业和财务指标（如 ROE>15%）缩小范围
2. 用"批量分析"对筛选结果做快速分析
3. 对有潜力的标的再用"单股研究"做深度分析

### 重要提醒

- **系统提供的是信息整理和多维度分析参考，不构成投资建议**
- AI 模型可能存在数据偏差或逻辑错误，关键信息请以上市公司公告和监管披露为准
- 投资决策的风险由您自行承担，系统无法保证任何投资收益
- 建议将系统分析作为研究参考之一，结合多方信息独立判断

### v3.0 治理能力（让 AI 不再是黑盒）

v3.0 在"让 AI 跑得动"的基础上，重点解决了"**让 AI 出错能查、能改**"：

- **可追溯**：报告里每个结论都能回溯到具体哪个 Agent 看了什么数据、用什么工具、返回了什么结果
- **可验证**：Agent 输出不符合格式时系统会标记，而不是悄悄放过
- **可纠错**：踩过的坑会被系统记住，下次自动拦截类似错误
- **可审计**：所有 LLM 调用都被记录，方便复盘

具体怎么用，详见：
- **执行轨迹查看** → 3.6 任务中心
- **断言管理（高级）** → 8.1 配置管理

---

## 第一章 安装部署

TradingAgents-CN Pro v3.0 提供两种主要部署方式：**Windows 安装包**（适合普通用户）和 **Docker 部署**（适合进阶用户与服务器环境）。

### v3.0 环境端口约定

| 服务 | 端口 | 说明 |
|------|------|------|
| MongoDB | 27019 | v3.0 专用数据库端口 |
| Redis | 6381 | v3.0 专用缓存端口 |
| 后端服务 | 8002 | API 服务端口 |
| 前端界面 | 8082 | Web 访问端口 |
| Docker 项目名 | `ta-v3` | v3.0 容器编排项目名 |

> 注意：v3.0 与 v2.1.0、v2.0.1 使用独立目录、独立端口、独立数据卷，可在同一台机器上共存互不干扰。

### 1.1 Windows 安装包部署

#### 功能说明

Windows 安装包是面向普通用户的最简部署方式，无需手动安装 Python 环境和依赖，双击安装即可使用。安装包含嵌入式 Python 运行时，不污染系统环境。

#### 操作步骤

1. **获取安装包**
   - 主渠道：百度网盘 + QQ 群下载
   - 备用渠道：阿里云 OSS / 腾讯云 COS 加速下载
   - 归档渠道：GitHub Releases（历史版本）

2. **系统要求**
   - 操作系统：Windows 10 64 位及以上（推荐 Windows 11）
   - 内存：8GB 及以上
   - 磁盘空间：至少 5GB 可用空间
   - 需安装 .NET Framework 4.7.2 及以上（系统通常已自带）

3. **安装过程**
   - 双击 `TradingAgentsCN-Pro-v3.0-setup.exe` 启动安装向导
   - 选择安装目录（建议使用默认路径，避免中文和空格）
   - 勾选"创建桌面快捷方式"
   - 点击"安装"等待安装完成
   - 安装完成后可选择"立即启动"

4. **首次启动**
   - 双击桌面快捷方式启动服务
   - 系统会自动启动后端服务（端口 8002）和前端服务（端口 8082）
   - 浏览器自动打开 `http://localhost:8082` 即可进入系统

5. **服务管理**
   - 系统托盘有 TradingAgents 图标，右键可停止/重启服务
   - 也可通过"开始菜单 → TradingAgentsCN Pro → 服务管理"操作

#### 注意事项

- 安装路径不要包含中文、空格或特殊字符，否则可能导致服务启动失败。
- 如果 8002 或 8082 端口被占用，安装程序会提示，请在防火墙或服务管理中释放端口。
- 首次启动需要初始化数据库，可能耗时 1-2 分钟，请耐心等待。
- 杀毒软件可能误报，请将安装目录加入白名单。

### 1.2 Docker 部署

#### 功能说明

Docker 部署适合进阶用户和服务器环境，提供环境隔离、一键启停、便于升级维护等优势。v3.0 使用独立的 Docker 项目名 `ta-v3`，与 v2.x 完全隔离。

#### 操作步骤

1. **前置要求**

   | 组件 | 最低版本 | 推荐版本 |
   |------|---------|----------|
   | Docker | 20.0+ | 最新版 |
   | Docker Compose | 2.0+ | 最新版 |
   | 内存 | 4GB | 8GB+ |
   | 磁盘空间 | 10GB | 20GB+ |

2. **安装 Docker**
   - Windows：下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop)，启动后确保状态为运行中。
   - Linux：参考 [Docker 官方安装指南](https://docs.docker.com/engine/install/)。

3. **获取项目文件**
   ```bash
   git clone https://github.com/hsliuping/TradingAgents-CN.git
   cd TradingAgents-CN
   ```

4. **配置环境变量**
   ```bash
   cp .env.example .env
   ```
   编辑 `.env` 文件，填入您的 API 密钥（详见 [第二章 首次配置](#第二章-首次配置)）。

5. **使用预构建镜像启动（推荐）**
   ```bash
   # 拉取 v3.0 镜像
   docker pull hsliuping/tradingagents-backend:3-latest
   docker pull hsliuping/tradingagents-frontend:3-latest

   # 启动服务（使用 ta-v3 项目名）
   docker-compose -p ta-v3 up -d
   ```

6. **本地构建镜像（可选）**
   ```bash
   # AMD64 架构（Intel/AMD）
   ./scripts/build-amd64.sh

   # ARM64 架构（Apple Silicon / ARM 服务器）
   ./scripts/build-arm64.sh
   ```

7. **访问应用**
   - 浏览器打开：`http://localhost:8082`

8. **常用 Docker 命令**
   ```bash
   # 查看服务状态
   docker-compose -p ta-v3 ps

   # 查看日志
   docker-compose -p ta-v3 logs -f backend
   docker-compose -p ta-v3 logs -f frontend

   # 停止服务
   docker-compose -p ta-v3 down

   # 重启服务
   docker-compose -p ta-v3 restart

   # 升级镜像
   docker-compose -p ta-v3 pull
   docker-compose -p ta-v3 up -d
   ```

#### 注意事项

- Docker 镜像标签使用 `3-latest`（滚动更新）或精确版本号（如 `3.0.0`，不可变）。生产环境建议使用精确版本号。
- 数据持久化通过 Docker Volume 实现，升级镜像不会丢失数据。
- v3.0 与 v2.x 的 Docker 项目名不同（`ta-v3` vs `ta-v210` vs `ta-v201`），互不影响。
- 在 Windows 上使用 Docker Desktop 时，请确保 WSL 2 后端已启用。
- 如遇 MongoDB 连接问题，请检查端口 27019 是否被其他服务占用。

### 1.3 部署验证

#### 功能说明

部署完成后，通过以下步骤验证系统是否正常运行。

#### 操作步骤

1. **检查服务端口**
   - 打开浏览器访问 `http://localhost:8082`，应看到登录页面。
   - 访问 `http://localhost:8002/docs`，应看到后端 API 文档（Swagger）。

2. **检查数据库连接**
   - 登录系统后进入"设置 → 系统管理 → 数据库"，查看连接状态是否为"已连接"。

3. **完成首次配置**
   - 按照引导完成 API 密钥配置（详见下一章）。

4. **运行测试分析**
   - 在"单股研究"中输入一只常见股票代码（如 `600519`），执行一次分析，确认全流程通畅。

#### 注意事项

- 如果前端可访问但 API 报错，通常是后端服务未完全启动，请等待 30 秒后重试。
- 首次运行分析时需要下载数据依赖，耗时较长属正常现象。

### 1.4 京东云合作版部署（可选）

#### 功能说明

京东云合作版是 TradingAgents-CN Pro 与京东云模型服务合作的定制版本。与标准版相比，京东云版通过环境变量注入大模型和数据源配置，用户无需在界面手动配置，开箱即用。

**京东云版与标准版的核心差异：**

| 对比项 | 标准版 | 京东云版 |
|--------|--------|---------|
| 大模型配置 | 用户在界面手动配置 Provider 和 API Key | 通过环境变量注入，界面隐藏配置入口 |
| 可用模型 | 支持多家供应商（通义千问、DeepSeek、智谱等） | 仅京东云提供的模型（GLM-5 / GLM-5.1 / GLM-5.2 / DeepSeek-V4-Flash） |
| 数据源 | 支持 Tushare / AKShare / BaoStock | 仅 Tushare（Token 由京东云提供） |
| Embedding | 用户选择 Embedding 模型 | 固定使用 Qwen3-Embedding-8B |
| 首次启动 | 需手动配置 API 密钥 | 自动从环境变量初始化数据库 |
| LLM 限速 | 无特殊限制 | 内置 429 重试 + 降并发机制 |

#### 环境变量配置

京东云版通过以下环境变量驱动所有配置，部署时在 `.env` 文件中设置：

| 环境变量 | 必填 | 说明 | 示例值 |
|---------|------|------|--------|
| `JDYUN_MODE` | 是 | 京东云模式开关，必须为 `true` | `true` |
| `OPENAI_API_BASE` | 是 | 京东云模型服务地址 | `https://modelservice.jdcloud.com/v1` |
| `OPENAI_API_KEY` | 是 | 京东云提供的 API Key | `your_jdyun_api_key` |
| `OPENAI_MODEL` | 是 | 默认对话模型 | `GLM-5` |
| `EMBEDDING_MODEL` | 是 | Embedding 模型 | `Qwen3-Embedding-8B` |
| `TUSHARE_TOKEN` | 是 | Tushare 数据源 Token | `your_tushare_token` |

**LLM 限速配置（可选，默认值已优化，通常无需修改）：**

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `JDYUN_LLM_MAX_RETRIES` | 8 | LLM 调用遇到 429 限速时的最大重试次数（指数退避：1s→2s→4s→...→128s） |
| `JDYUN_LLM_MAX_RPM` | 30 | LLM 每分钟最大请求数 |
| `JDYUN_BATCH_MAX_CONCURRENT` | 1 | 批量分析最大并发数（降为 1 避免限速） |
| `JDYUN_WORKER_MAX_CONCURRENT` | 1 | Worker 最大并发任务数 |
| `JDYUN_STOCK_INTERVAL_SECONDS` | 10 | 定时分析股票间的间隔秒数 |

#### Docker 部署步骤

1. **准备配置文件**
   - 复制 `.env.jdyun.example` 为 `.env`，填入京东云提供的凭据：
     ```
     JDYUN_MODE=true
     OPENAI_API_BASE=https://modelservice.jdcloud.com/v1
     OPENAI_API_KEY=your_jdyun_api_key
     OPENAI_MODEL=GLM-5
     EMBEDDING_MODEL=Qwen3-Embedding-8B
     TUSHARE_TOKEN=your_tushare_token
     ```

2. **启动服务**
   ```bash
   docker-compose -f docker-compose.jdyun.yml up -d
   ```
   - 服务端口：前端 `8082`，后端 `8002`，MongoDB `27019`，Redis `6381`

3. **访问系统**
   - 浏览器打开 `http://your-server:8082`
   - 首次启动时系统自动从环境变量初始化数据库（写入京东云 Provider、模型配置、Tushare 数据源）
   - 无需手动配置 API 密钥，直接开始使用

#### 便携版部署步骤

1. **打包京东云版**
   ```powershell
   .\scripts\deployment\build_pro_package.ps1 -Edition jdyun
   ```
   - 打包脚本会自动使用 `--mode jdyun` 构建前端，注入 `VITE_JDYUN_MODE=true`
   - 生成 `.env.jdyun.example` 配置模板

2. **部署到目标机器**
   - 将打包好的便携版目录复制到目标机器
   - 编辑 `.env` 文件，填入京东云提供的凭据
   - 运行启动脚本

#### 开发环境启动

开发环境下使用 `start_dev.ps1` 脚本启动京东云模式：

```powershell
.\start_dev.ps1 docker 3.0      # 启动 MongoDB + Redis
.\start_dev.ps1 backend 3.0 -jdyun   # 以京东云模式启动后端
.\start_dev.ps1 frontend 3.0 -jdyun  # 以京东云模式启动前端
```

#### 注意事项

- 京东云版**隐藏了大模型和数据源的配置界面**，用户无法在界面修改这些配置，只能通过环境变量调整。
- 京东云版**禁用了 Provider 和数据源的增删改 API**，防止误操作覆盖环境变量配置。
- 京东云版内置 **LLM 限速应对机制**：批量分析和定时分析的并发数自动降为 1，任务间间隔 10 秒，遇到 429 限速时指数退避重试最多 8 次。
- 可用模型仅限京东云提供的 4 个：`GLM-5`、`GLM-5.1`、`GLM-5.2`、`DeepSeek-V4-Flash`，用户可在分析时切换。
- 如遇 LLM 限速频繁，可适当调大 `JDYUN_STOCK_INTERVAL_SECONDS`（如 20 或 30 秒）。

---

## 第二章 首次配置

### 2.1 API 密钥配置

#### 功能说明

TradingAgents-CN Pro 需要配置大语言模型（LLM）API 密钥来驱动智能分析。系统支持多家模型提供商，您可以选择其中一家或多家组合使用。

> **京东云合作版用户**：无需执行本节操作。京东云版通过环境变量自动配置大模型和数据源，首次启动时自动初始化，可直接跳到 [2.2 系统初始化](#22-系统初始化)。

#### 操作步骤

1. **进入配置页面**
   - 登录系统后，点击左侧导航栏"设置 → 系统配置"，或按引导提示进入。

2. **选择 LLM 提供商**（推荐任选其一）

   **DeepSeek（推荐，性价比最高）**
   - 注册地址：https://platform.deepseek.com/
   - 费用：约 ¥1/万 tokens，新用户有免费额度
   - 配置项：`DEEPSEEK_API_KEY`

   **通义千问 / DashScope（国产稳定）**
   - 注册地址：https://dashscope.aliyun.com/
   - 费用：按量计费，有免费额度
   - 配置项：`DASHSCOPE_API_KEY`

   **OpenAI（功能强大）**
   - 注册地址：https://platform.openai.com/
   - 费用：按使用量计费，需美元支付
   - 配置项：`OPENAI_API_KEY`

   **Google AI / Gemini**
   - 注册地址：https://aistudio.google.com/
   - 配置项：`GOOGLE_API_KEY`

   **SiliconFlow（聚合平台）**
   - 注册地址：https://siliconflow.cn/
   - 配置项：`SILICONFLOW_API_KEY`

3. **配置数据源 API**（可选但推荐）
   - **Tushare**（A 股数据推荐）：https://tushare.pro/ 注册获取 token，配置 `TUSHARE_TOKEN`

4. **在界面中配置**
   - "设置 → 系统配置"中找到对应配置项，填入密钥。
   - 点击"测试连接"按钮验证密钥有效性。
   - 保存配置。

> **注意**：直接修改 `.env` 文件仅为旧版兼容方式，v3.0 推荐通过“设置 → 系统配置”界面完成配置。

5. **设置模型优先级**
   - 在"设置 → 系统配置"中可设置默认模型和分析偏好。
   - 支持为不同分析师（如基本面、新闻、风险）指定不同模型，以平衡成本与效果。

#### 注意事项

- API 密钥以加密方式存储在数据库中，不会明文展示。
- 建议同时配置两个 LLM 提供商作为主备，当主模型不可用时自动切换。
- DeepSeek 和通义千问对中文金融语境支持较好，推荐作为主力模型。
- Tushare 根据积分等级有不同的接口权限，新用户积分较低可能部分数据无法获取。
- 密钥配置后请点击"测试连接"确认有效，否则分析任务会因模型调用失败而中断。

### 2.2 系统初始化

#### 功能说明

首次部署后，系统已自动创建默认管理员账号并完成数据库初始化。用户只需使用默认账号登录，完成基础数据同步和数据源配置即可开始使用。

#### 操作步骤

1. **使用默认账号登录**
   - 系统已预置默认管理员账号。
   - 用户名：`admin`
   - 密码：`admin123`
   - 首次登录后请立即在"设置 → 个人中心"修改默认密码。

2. **初始化数据库**
   - 系统会自动创建必要的集合和索引。
   - 可在"设置 → 系统管理 → 数据库"查看初始化状态。

3. **同步基础数据**
   - 进入"设置 → 系统管理 → 数据同步"。
   - 点击"初始化股票基础数据"，同步 A 股的股票列表。
   - 该过程可能耗时 10-30 分钟，取决于网络状况。

4. **配置数据源**
   - 在"设置 → 系统配置 → 数据源"中选择主力数据源。
   - A 股推荐 Tushare，可配置多数据源互为备份。

5. **检查系统状态**
   - 进入"仪表板"，查看系统状态卡片是否全部为绿色。

#### 注意事项

- 默认密码仅用于首次登录，请务必尽快修改。
- 基础数据同步是后续分析功能正常运作的前提，必须完成。
- 如果同步失败，可点击"重试"或检查网络与 API 配额。

### 2.4 使用指南（/guide）

#### 功能说明

使用指南是系统内置的引导式初始设置向导，位于左侧导航栏"使用指南"菜单。通过分步骤引导帮助新用户完成从 API 密钥配置到完成首次 AI 研究的全流程，适合首次使用的用户跟随操作。

#### 引导步骤

使用指南采用步骤条形式，逐步引导完成初始配置：

1. **获取大模型 API 密钥**
   - 说明如何获取 DeepSeek / 通义千问 / OpenAI 等 LLM 的 API 密钥。
   - 提供各平台注册链接和注意事项。
   - 点击"前往配置"跳转到系统配置页面。

2. **获取数据源 API 密钥**
   - 说明如何注册 Tushare 账号并获取 Token。
   - 提示不同积分等级的权限差异。
   - 点击"前往配置"跳转到数据源配置。

3. **填写 Token 配置**
   - 引导将获取的 API 密钥填入系统配置。
   - 配置完成后可点击"测试连接"验证。

5. **同步股票数据**
   - 引导执行股票基础数据初始化同步。
   - 说明同步范围和预计耗时。
   - 点击"前往同步"跳转到数据同步页面。

6. **搜索并添加股票关注列表**
   - 引导在关注列表中添加感兴趣的股票。
   - 提供搜索和分组操作指引。

7. **完成第一次研究**
   - 引导进入单股研究，选择分析维度并启动分析。
   - 完成后查看研究报告。

#### 操作步骤

1. 登录系统后，点击左侧导航栏"使用指南"。
2. 按步骤条顺序依次操作，每步完成后自动标记为已完成。
3. 每个步骤提供"前往操作"按钮，直接跳转到对应功能页面。
4. 可随时返回使用指南查看进度，已完成的步骤会保留标记。

#### 注意事项

- 使用指南仅为引导，不影响系统功能使用，可随时跳过。
- 已完成初始配置的老用户无需再跟随此指南。
- 步骤进度存储在本地浏览器中，清除浏览器数据后进度会重置。

---

## 第三章 基础功能

本章介绍日常使用频率最高的基础功能模块，包括仪表板、单股研究、研究报告、股票筛选、关注列表和任务中心。

### 3.1 仪表板（/dashboard）

#### 功能说明

仪表板是登录后的默认首页，提供系统就绪度引导、快捷功能入口、最近分析记录和股票关注列表概览，帮助用户快速了解系统配置状态并一键进入常用功能。

#### 界面组成

- **系统就绪度引导卡片**：以步骤形式展示系统配置进度（配置数据源 → 配置大模型 → 同步数据），未完成的步骤可点击"前往设置"跳转到对应配置页面。
- **快速操作区**：单股研究、批量分析、股票筛选、任务中心、持仓研究、复盘分析、交易计划等常用功能的快速跳转入口。
- **最近分析区**：以表格形式展示最近的分析任务，包含股票代码、名称、状态、创建时间，支持"查看"和"下载"操作。
- **股票关注列表概览**：展示关注列表中的股票，支持"添加到研究列表"快速发起分析。

#### 操作步骤

1. 登录系统后自动进入仪表板。
2. 首次使用时，根据"系统就绪度引导卡片"完成数据源配置、大模型配置和数据同步。
3. 点击"快速操作区"的功能卡片，可直接跳转到对应功能页面。
4. 在"最近分析"表格中点击"查看"按钮，可查看完整报告；点击"下载"可导出报告。
5. 在"股票关注列表概览"中点击"添加到研究列表"，可快速发起单股分析。

#### 注意事项

- 系统就绪度引导卡片在所有配置步骤完成后会显示完成状态。
- 首次使用建议先按照引导卡片完成基础配置，再进行股票分析。

### 3.2 单股研究（/analysis/single）

#### 功能说明

单股研究是系统的核心功能，输入一只股票代码，选择需要的分析维度和分析深度，系统将调用多个 AI 分析师协同完成深度分析，生成结构化研究报告。

#### 支持的市场

- **A 股市场**：沪深主板、创业板、科创板、北交所（6 位数字代码，如 `000001`）
- **ETF 基金**：如 `510050`、`159919` 等

> 注意：v3.0 暂不支持美股和港股市场分析，相关功能已暂停，后续版本将重新开放。

#### 操作步骤

1. **进入单股研究**
   - 左侧导航栏"单股研究"，或仪表板快捷入口。

2. **输入股票信息**
   - 在"股票代码"输入框中直接输入股票代码（如 `000001`、`512400`）。
   - 在"市场类型"下拉框选择对应市场：A 股市场、ETF 基金。
   - 各市场代码格式提示：A 股（6 位数字）、ETF（510050、159919 等）。

3. **选择分析日期（可选）**
   - 默认为当天，可手动选择历史日期作为分析基准日。
   - 点击"数据检验"按钮可预先验证该股票的数据完整性。

4. **选择分析深度**
   - 系统提供 5 个分析深度级别：
     - **1 级 - 快速分析**：基础数据概览，快速决策（2-5 分钟）
     - **2 级 - 基础分析**：常规投资决策（3-6 分钟）
     - **3 级 - 标准分析**：技术 + 基本面，推荐（4-8 分钟）
     - **4 级 - 深度分析**：多轮辩论，深度研究（6-11 分钟）
     - **5 级 - 全面分析**：最全面的分析报告（8-16 分钟）

5. **选择分析师团队**
   - 系统提供多个分析师角色，以卡片形式展示，点击卡片切换选中/取消：
     - **市场分析师**：分析个股价格走势与技术指标（均线/MACD/RSI/布林带）
     - **基本面分析师**：分析公司财务状况、业务模式和竞争优势
     - **新闻分析师**：分析相关新闻、公告和市场事件的影响
     - **社媒分析师**：分析社交媒体情绪、投资者心理和舆论导向
     - **大盘分析师**：分析大盘指数走势、市场环境和系统性风险（仅 A 股可选）
     - **板块分析师**：分析行业趋势、板块轮动和同业对比（仅 A 股可选）
     - **ETF 分析师**：分析 ETF 净值、跟踪误差和持仓结构（仅 ETF 市场可选）
   - 默认选中"市场分析师"和"基本面分析师"。
   - 非对应市场的分析师会显示"仅 A 股"标签并不可选。

#### 一份完整的报告覆盖哪些维度

下面这张表是**每次分析实际会跑的分析维度**，让您知道报告里的每个结论是怎么来的：

| 维度 | 由谁负责 | 用了什么数据/工具 | 在报告里能看到什么 |
|------|---------|----------------|------------------|
| **价格走势** | 市场分析师 | 历史 K 线、实时行情 | 当前价、涨跌幅、成交量、换手率 |
| **技术指标** | 市场分析师 | MA/RSI/KDJ/MACD、布林带 | 方向信号、超买超卖、趋势方向 |
| **K线形态** | 市场分析师 | 25+ 形态自动识别 | 锤子线、吞没、晨星/黄昏之星等 |
| **图表形态** | 市场分析师 | 头肩顶底、双顶双底、三角 | 中长线趋势判断 |
| **支撑压力** | 市场分析师 | Pivot + 历史极值聚类 | 3 档支撑位、3 档压力位 |
| **财务表数据** | 基本面分析师 | Tushare 财报数据（资产负债表/利润表/现金流量表/所有者权益表） | 营收、利润、毛利率、现金流 |
| **盈利质量** | 基本面分析师 | 应计/现金流/盈利持续性 | 5 维度 0-100 分 |
| **财务健康** | 基本面分析师 | Altman Z、Piotroski F | 是否存在破产风险、财务健康度 |
| **财报造假检测** | 基本面分析师 | Beneish M（8 维度） | 是否有造假嫌疑（> -1.78 提示） |
| **估值水平** | 基本面分析师 | PE/PB/PS/PEG | 相对估值高还是低 |
| **DCF 估值** | 基本面分析师 | 现金流折现 + WACC | 公司值多少钱 |
| **行业对比** | 板块分析师 | 同行业上市公司数据 | 在行业内的位置、市值排名 |
| **大盘环境** | 大盘分析师 | 指数 + 涨跌家数 | 牛市/熊市/震荡市判断 |
| **新闻事件** | 新闻分析师 | 东方财富/新浪/同花顺 | 近期重要新闻、催化、风险事件 |
| **市场情绪** | 社媒分析师 | 雪球/股吧讨论 | 情绪倾向、讨论热度 |
| **筹码分布** | 内置工具 | AkShare/Tushare | 获利比例、平均成本、90%/70% 集中度 |
| **多情景研究** | 高弹性/防御/基准情景分析师 | 综合上述报告 | 三种情景视角并列的研究观察（不构成投资建议） |
| **研究观察汇总** | 研究整合员 | 上述全部 | 平衡的多情景研究观察汇总（无方向性结论） |

**重点说明**：
- 报告里所有数据点都能查到出处（详见 v3.0 分析能力全景章节）
- "AI 推论"标签说明是 LLM 推理的，不是直接拿到的数据
- 多情景研究是 v3.0 新能力，3 级标准分析会自动启用
- 4 级深度分析会增加多轮辩论环节

6. **启动分析**
   - 点击"开始智能分析"按钮。
   - 系统进入分析进度页面，实时显示已用时间、预计剩余时间、进度条和当前任务描述。
   - 分析过程中按钮显示为"分析进行中..."（不可重复点击）。

7. **查看报告**
   - 分析完成后按钮变为"查看结果"和"重新分析"。
   - 点击"查看结果"展开分析报告，包含：综合研究观察、各维度分析、风险提示、后续观察事项。
   - 可导出为 PDF、Word、Markdown 等格式。

#### 注意事项

- 单次分析会消耗 LLM Token，深度分析消耗较大，请根据授权配额合理安排。
- 分析过程中请勿关闭浏览器标签页，否则可能中断任务（任务可在"任务中心"恢复查看）。
- 首次分析某只股票时，数据下载耗时较长；后续分析会使用缓存，速度更快。
- 分析结果仅供参考，不构成投资建议，请结合自身判断决策。
- 大盘分析师和板块分析师仅支持 A 股市场；ETF 市场仅显示 ETF 分析师、市场分析师和新闻分析师。

#### 分析报告解读指南

分析完成后，报告按以下结构展示，帮助您快速获取关键信息：

| 报告章节 | 内容说明 | 关注重点 |
|---------|---------|---------|
| **综合评级** | AI 给出的整体研究观察（无方向性结论） | 把握度与不确定性说明 |
| **市场分析** | 技术指标解读（均线、MACD、RSI、布林带）、价格走势 | 当前处于技术性多头还是空头 |
| **基本面分析** | 财务数据、估值水平、行业地位、竞争优势 | PE/PB 是否合理，营收利润趋势 |
| **新闻分析** | 近期重要新闻、公告事件影响 | 是否有重大利好或利空事件 |
| **社媒分析** | 社交媒体情绪、投资者讨论热度 | 市场情绪偏乐观还是悲观 |
| **大盘分析** | 大盘指数走势、市场环境、系统性风险 | 当前市场环境是否适合操作 |
| **板块分析** | 行业趋势、板块轮动、同业对比 | 该股所在行业是否处于景气周期 |
| **多情景研究** | 三种情景视角并列研究观察 | 主要风险点和潜在下行空间 |
| **研究观察汇总** | 平衡的多情景研究观察 | 汇总性的研究观察，无投资建议 |

> 💡 **阅读建议**：
> - **时间紧张时**：只看"综合评级"和"研究观察汇总"两节。
> - **决策前**：重点阅读"多情景研究"，了解不同视角的研究观察，避免确认偏误。
> - **长期跟踪**：关注"基本面分析"的趋势变化，判断公司经营是否改善。

### 3.3 研究报告（/reports）

#### 功能说明

研究报告模块管理所有历史分析报告，支持按条件搜索、查看详情、批量导出。

#### 操作步骤

1. **查看报告列表**
   - "研究报告"页面展示所有历史报告。
   - 每条报告显示：报告标题、类型、格式、状态、分析模型、分析深度、创建时间。
   - 支持按股票代码/名称搜索、按市场（A 股/ETF）筛选、按日期范围筛选。

2. **查看报告详情**
   - 点击报告行中的"查看"按钮，进入报告详情页。
   - 详情页包含：综合研究观察、各分析师详细分析、数据图表、风险提示、后续观察事项。
   - 报告支持在线阅读，支持目录跳转。

3. **下载报告**
   - 点击报告行中的"下载"按钮，可下载单个报告。
   - 也支持勾选多份报告后点击"批量导出"，选择格式：Markdown / Word / PDF。

4. **删除报告**
   - 点击报告行中的"删除"按钮，可删除不需要的报告。

5. **Token 消耗查看**
   - 在"系统管理 → 使用统计"页面可查看各功能的 Token 消耗情况，包括单股研究、批量分析、Agent 工坊、Skill 生成、AI 对话助手、持仓分析、操作复盘等。
   - 也可在研究报告页面点击"Token 统计"按钮，进入 Token 使用统计页面，按时间范围（今天/7天/30天/90天/全部）和供应商筛选查看详细的 Token 使用情况和成本分析，支持导出统计数据。

#### 注意事项

- 导出 PDF 时如遇中文字体问题，请确保系统已安装中文字体（Docker 镜像已内置）。
- Word 格式导出需要系统配置 pandoc（Docker 部署默认包含）。

### 3.4 股票筛选（/screening）

#### 功能说明

股票筛选模块支持多条件组合筛选股票，帮助用户从全市场中快速找到符合特定条件的标的。v3.0 新增"选股助手"模式，支持自然语言对话式筛选。

#### 操作步骤

1. **传统条件筛选**
   - 进入"股票筛选"页面。
   - 选择市场范围：A 股全市场 / 沪深 300 / 创业板 / 股票关注列表等。
   - 添加筛选条件：
     - 基本面：市盈率、市净率、ROE、营收增长率、净利润增长率
     - 技术面：涨跌幅、换手率、量比、均线位置
     - 规模：总市值、流通市值
     - 行业：按申万行业分类筛选
   - 设置条件逻辑（大于/小于/介于/等于）。
   - 点击"开始筛选"，查看结果列表。

2. **选股助手（对话式）** 
   - 点击"选股助手"标签页。
   - 用自然语言描述筛选需求，例如：
     - "帮我找 ROE 大于 15%、市盈率低于 20 的消费股"
     - "最近一周涨幅超过 10% 且换手率活跃的创业板股票"
   - 系统会经过三阶段处理：
     1. **需求确认**：AI 与您确认筛选意图。
     2. **策略规划**：AI 规划筛选工具调用方案。
     3. **执行筛选**：调用工具执行筛选，返回结果。
   - 筛选结果支持一键加入股票关注列表。

3. **结果操作**
   - 点击股票名称进入详情。
   - 勾选股票后可"加入股票关注列表"或"批量分析"。
   - 支持导出筛选结果为 Excel。

#### 注意事项

- 选股助手为高级功能，需要高级版授权。
- 筛选结果数据依赖基础数据同步，如果同步未完成，结果可能不完整。
- 选股助手在超时或无结果时，会自动 fallback 到历史成功结果或数据库快速粗筛，确保总有候选输出。

### 3.5 股票关注列表（/favorites）

#### 功能说明

关注列表（股票关注列表）用于管理您关注的股票，支持分组管理、实时行情、快速分析。

#### 操作步骤

1. **创建分组**
   - "股票关注列表"页面，点击"新建分组"。
   - 输入分组名称（如"白酒板块"、"长期观察"、"止损线"）。
   - 可设置分组颜色标识。

2. **添加股票**
   - 方式一：在分组内点击"添加股票"，搜索股票后加入。
   - 方式二：在筛选结果、报告详情页点击"加入股票关注列表"。
   - 方式三：在智能助手中说"把 600519 加入我的白酒板块"。

3. **管理关注股**
   - 拖拽股票调整顺序。
   - 支持跨分组移动。
   - 点击股票代码进入**股票详情页**（详见 [3.7 股票详情页](#37-股票详情页-stockscode)），查看实时行情、K线图、核心指标、单股分析、持仓与复盘，并可使用智能助手全景解读。
   - 股票详情页支持的操作：发起 AI 研究、持仓分析、同步最新数据、清除缓存、跳转模拟交易、加入/移出关注列表。

4. **批量操作**
   - 勾选多只股票，可"批量分析"（跳转到批量分析）。
   - 可"批量导出"为 Excel。

#### 注意事项

- 每个分组建议不超过 50 只股票，过多会影响页面加载速度。
- 关注列表的行情数据为延迟行情，不作为交易依据。
- 股票详情页的行情数据可能延迟，如需最新数据可点击"同步"按钮手动拉取。

### 3.6 任务中心（/tasks/unified）

#### 功能说明

任务中心统一展示所有类型的分析任务状态，包括单股分析、批量分析、定时分析等，方便追踪任务进度。

#### 操作步骤

1. **查看任务列表**
   - "任务中心"页面展示所有任务的统一视图。
   - 每条任务显示：任务类型、目标股票/分析目标、状态、创建时间、耗时。
   - 状态包括：排队中、运行中、已完成、已失败、已取消。
   - 通用研究类型的任务目标显示为分析目标文本（而非股票代码）。

2. **筛选任务**
   - 按任务类型筛选。
   - 按状态筛选。
   - 按时间范围筛选。

3. **任务操作**
   - **运行中任务**：可查看实时进度、取消任务。
   - **已完成任务**：可查看报告、重新分析、导出报告。
   - **已失败任务**：可查看错误日志、重试任务。

4. **任务详情**
   - 点击任务进入详情页，查看每个分析师的执行步骤和耗时。

#### 执行轨迹（v3.0 核心能力 — 让 AI 跑哪里都能查到）

**这是 v3.0 最重要的可追溯能力。** 任务详情页的"执行轨迹"标签页会把这次分析**每一步**都记录下来，AI 不是黑盒了。

**怎么开**（两种方式）：

- **方式 1（推荐）— 全局开关**："系统设置 → 高级设置 → 执行轨迹" → 启用。开启后所有新分析任务都会记录。
- **方式 2（单次）— 任务级开关**：在任务详情页右上角点击"开启记录"按钮，只针对当前任务。

> 💡 默认**关闭**（避免给数据库造成压力）。建议在排查问题时开启，正常分析时关闭。

**开启后能看到什么**：

| 字段 | 含义 | 排查问题时的用途 |
|------|------|----------------|
| **Agent 列表** | 这次分析跑了哪些 Agent（市场、基本面、新闻…） | 确认每个 Agent 是不是都跑到了 |
| **每个 Agent 的输入** | 它看到了什么（上游报告、数据） | 排查"为什么这个 Agent 结论这么奇怪" |
| **系统提示词 + 用户提示词** | LLM 实际收到的 prompt | 排查"是不是 prompt 没传对" |
| **LLM 原始返回** | LLM 实际说了什么 | 排查"是不是 LLM 答非所问" |
| **工具调用记录** | 调用了哪些工具、传了什么参数、返回了什么 | 排查"是不是工具拿错数据了" |
| **校验结果** | 输出是否符合格式（passed/failed/warning） | 排查"为什么这次报告格式不对" |
| **Token 用量** | 这次分析消耗多少 Token | 排查"为什么 Token 涨这么多" |
| **耗时** | 每个 Agent 用了多少秒 | 排查"为什么这么慢" |

**一个真实的排查场景**：

> 问：为什么这次新闻分析说"该公司近期无重大事件"？
>
> 答：打开执行轨迹 → 找到"新闻分析师" → 看它的"工具调用" → 发现它只调了"标题"工具，没调"明细"工具 → 知道是工具选错了

**怎么用最划算**：

- ✅ 排查问题时开（分析结果不对、Token 异常、报告格式奇怪）
- ✅ 学习时开（看 AI 是怎么工作的）
- ❌ 日常分析时关（增加数据库存储）
- ❌ 批量分析时关（除非排查某只具体股票）

> 💡 **Token 影响**：开启执行轨迹**几乎不影响 Token 消耗**（只记录不增加新调用），但会增加数据库存储。默认 7 天后归档。

#### 注意事项

- 任务并发数受授权等级限制，标准版同时运行 1 个任务，高级版支持并发。
- 排队中的任务可以随时取消。
- 失败任务重试时，会重新消耗 Token。
- 开启执行轨迹对 Token 消耗几乎无影响（只记录不增加新 LLM 调用），但会增加数据库存储。

---

### 3.7 股票详情页（/stocks/:code）

#### 功能说明

股票详情页是 v3.0 重新设计的个股研究工作台，将行情、研究、持仓、复盘、智能助手整合到一个页面，提供"全景解读"体验。页面采用模块化布局，从上到下分为 8 个区域，并配有 sticky 研究路径导航，帮助用户快速定位所需信息。

#### 页面布局

| 区域 | 模块 | 说明 |
|------|------|------|
| 1 | 股票概览 + 操作入口 | 当前价/涨跌、今开/最高/最低/成交量，右侧 6 个快捷操作按钮 |
| 2 | 智能助手主入口 | 紫色渐变大卡片，显示已加载模块状态，提供 4 个快捷问题按钮 |
| 3 | 研究路径（sticky） | 5 步研究路径导航，滚动时固定在顶部 |
| 4 | K线图 + 核心指标 | K线（含 MA5/MA20/成交量）+ 核心财务指标卡片 |
| 5 | 单股分析结果 | 最近一次 AI 分析报告，含一句话结论和重新分析入口 |
| 6 | 持仓与复盘 | 标签页切换持仓分析和交易复盘 |
| 7 | 智能助手对话区 | 全景解读对话窗口，限定在当前股票主题内 |
| 8 | 基本面 + 财务明细 + 新闻 | 基本面数据、财务明细快照、近期新闻与公告（支持 ETF 模式） |
| — | 回到顶部按钮 | 右下角紫色悬浮按钮，滚动超过 600px 时出现 |

页面整体适配宽屏布局，模块 4、6、8 采用双栏网格排列；屏幕宽度小于 1024px 时自动切换为单栏。

#### 智能助手主入口

页面顶部紧接股票概览的位置，有一个紫色渐变的醒目卡片，这是智能助手的主入口区域。卡片左侧显示：

- 助手头像和"智能研究助手"标题
- 当前正在解读的股票代码、名称
- 已加载的模块状态（动态显示，如"已加载 K线·单股分析·持仓·复盘·基本面"）
- 说明文字："我已整合该股票的单股分析、持仓分析、交易复盘、基本面和 K线走势，可以为你全景解读"

卡片右侧提供 4 个快捷问题按钮（2×2 网格），点击后会自动填入下方对话区并发送：

| 快捷按钮 | 触发的问题 |
|----------|-----------|
| 🔗 全景解读 | 帮我全景分析这只股票，从分析结果、持仓、复盘整体怎么看？ |
| 📋 分析结论 | 最近一次单股分析的核心结论是什么？ |
| 💼 持仓视角 | 结合我的持仓和复盘，下一步重点跟踪什么？ |
| ⚠️ 风险评估 | 当前估值和基本面是否匹配？有哪些风险？ |

> 快捷按钮会根据已加载的模块动态展示状态。如果某模块数据未加载，助手会在回答中说明数据缺失情况。

#### 智能助手全景解读（核心功能）

详情页内的智能助手与独立的智能助手模块（[5.1 AI 对话助手](#51-ai-对话助手-assistant)）打通，但做了主题限定，提供"全景解读"体验：

**1. 一个股票一个主题**

进入详情页时，系统会自动创建或获取该股票的研究主题（标题为"股票研究 · {代码} {名称}"）。同一只股票反复进入页面会复用同一主题，历史对话自动加载回来，不会丢失上下文。

**2. 聚合解读三份报告**

智能助手同时拿到单股分析报告、持仓分析报告、复盘报告的摘要一起解读，无需用户手动切换。例如用户问"结合分析和持仓，我下一步应该重点跟踪什么？"，助手会综合三份报告给出判断，而不是只看其中一份。

**3. 主题边界限定**

对话限定在当前股票范围内。聊天区头部会显示"当前主题限定于：XX 股票"提示条。如果用户询问其他股票，助手会回复：

> 当前在 XX 股票详情页，无法切换到其他股票。如需咨询其他标的，请前往「智能助手」主页面创建新主题。

**4. 过期报告主动提醒**

如果关联的报告超过 24 小时未更新，助手会：

- 进入页面时主动推送一条提醒消息，列出哪些报告已过期
- 拒绝基于旧报告给出结论，并询问是否需要重新发起分析
- 用户确认后，可点击对应模块（单股分析、持仓、复盘）的"重新分析"按钮生成新报告

#### 研究路径导航

页面顶部有一条 sticky 导航条，展示研究路径的 5 个步骤及完成状态：

| 步骤 | 说明 | 完成条件 |
|------|------|----------|
| 行情走势 | K线 + 核心指标 | 已有日线数据 |
| 单股分析 | AI 研究报告 | 有已完成的单股分析任务 |
| 持仓与复盘 | 持仓状态 + 交易回顾 | 有持仓分析或复盘记录 |
| 基本面 | 财务数据 + 新闻 | 有财务数据 |
| 智能助手解读 | 全景涵盖以上所有模块 | 始终为"待使用"状态 |

点击任一步骤可快速滚动到对应区域；滚动时当前所在区域会自动高亮，导航条阴影随滚动增强。

#### K线图

- 支持日K/周K/月K切换
- MA5（5 日均线，橙色）和 MA20（20 日均线，紫色）叠加显示
- 底部显示成交量柱状图，配有图例
- 支持数据缩放（鼠标滚轮）和拖动查看历史区间
- 数据来源：`stock_daily_quotes` 集合的 `volume` 字段

#### 核心指标

核心指标区域以 4 张分类卡片（2×2 网格）展示财务全貌，每张卡片配有状态标签和进度条，便于快速判断：

**1. 估值卡片**
- 指标：PE(TTM)、PB、PS
- 状态标签：低估（PE < 15）/ 中性（PE 15~30）/ 偏高（PE > 30）/ 亏损 / 无数据
- PE 为实时数据时显示"实时"小标签
- 进度条颜色：蓝色（低估）/ 橙色（中性）/ 红色（偏高）

**2. 盈利能力卡片**
- 指标：ROE、毛利率、净利率
- 状态标签：优秀（ROE ≥ 15%）/ 良好（ROE 8~15%）/ 偏弱（ROE < 8%）/ 亏损 / 无数据

**3. 财务健康卡片**
- 指标：负债率、流动比率、股息率
- 状态标签：健康（负债率 < 40%）/ 中性（40~60%）/ 偏高（> 60%）/ 无数据

**4. 经营规模卡片**
- 指标：总市值、营收、净利润
- 底部显示财报公告日期

**因子提示信息**

卡片下方可能显示因子警告和因子诊断标签（hover 查看详情）：
- **因子警告标签**：显示该股票触发的风险条件（如"高估值风险"），hover 查看具体触发条件
- **因子诊断标签**：显示因子状态、原因、缺失输入（如某因子因数据不足无法计算）

> 数据来源优先级：财务指标（ROE、负债率等）优先从 `stock_financial_data` 集合获取，降级使用 `stock_basic_info`；估值数据（PE/PB/PS）来自 `stock_basic_info`。字段缺失时显示为 `-`。

#### 单股分析结果

展示最近一次单股分析报告，标题旁标注"深度研究"徽章。根据分析状态显示不同内容：

**运行中状态**
- 分析任务进行中时显示进度条（百分比）和提示信息（如"正在生成分析报告…"）

**空状态**
- 无分析记录时显示"暂无单股分析结果"，提供"发起单股分析"按钮

**有结果时展示**
- **研究结论**：紫色渐变背景卡片，展示一句话结论（基于研究整合员研究简报提炼）
- **分析元信息**：分析时间（完整时间 + 相对时间标签，如"3 小时前""2 天前""1 个月前"）、报告数量
- **数据过期提醒**：报告超过 1 天时显示橙色"🔄 数据已过期，重新分析"按钮
- **报告标签预览**：各子报告以可点击标签形式排列（如"市场分析""基本面分析""风险测评"），点击直接跳转对应报告；另有"查看完整报告"按钮打开多标签页对话框
- **详细报告内容（可折叠）**：点击"展开详情"后，以双栏网格展示 6 类子报告：
  - 📈 市场分析、💰 基本面分析、📰 新闻分析、⚠️ 风险测评（红色边框）、💬 社会情绪、🎯 研究整合员研究简报
- **历史记录**：右上角"📜 历史记录"按钮（带计数徽章），点击跳转任务中心查看该股票的所有历史分析
- **合规免责声明**：底部标注"本分析由 AI 多智能体系统基于公开信息生成，仅供研究参考，不构成任何交易建议"

> 合规说明：本区域不展示信心度和操作建议标签，仅保留研究性元数据。

#### 持仓与复盘

通过标签页切换两个模块，标签上显示状态徽章：

**持仓分析标签页**（徽章显示"浮盈 X%"/"浮亏 X%"/"已分析"）

- **持仓快照摘要**：成本价、现价、浮动盈亏（金额 + 百分比）、持有天数、仓位占比
- **研究观察**：紫色背景卡片，展示 AI 持仓研究观察（最多 3 条，仅供参考）
- **实盘/模拟持仓信息**：分别展示持仓数量、成本价、现价、市值、浮动盈亏（实盘红色标签、模拟橙色标签）
- **过期提醒**：分析超过 1 天时显示"🔄 数据已过期，重新分析"按钮
- **操作按钮**：重新分析、查看详情（跳转任务详情页）
- **持仓历史**：右上角"📜 持仓历史"按钮（带计数徽章）

**交易复盘标签页**（徽章显示"X 次"/"已复盘"）

- **复盘摘要**：交易次数、风险等级、完成时间（含相对时间）
- **过期横幅**：复盘超过 1 天时显示橙色横幅"⚠ 本次复盘距今较久，市场环境可能已变化"+ 重新复盘按钮
- **复盘结论**：Markdown 渲染的结论正文
- **研究观察**：原"操作建议"改为研究性表述（合规调整）
- **操作按钮**：重新复盘、查看详情（跳转复盘详情对话框）
- **复盘历史切换**：多条复盘记录时，右上角下拉框可切换查看不同历史复盘；另有"📜 复盘历史"按钮（带计数徽章）

> 合规说明：持仓分析不展示操作建议和信心度，交易复盘的"操作建议"已改为"研究观察"表述。两个标签页底部均有免责声明。

#### 操作入口

右上角提供 6 个快捷操作按钮（3×2 网格布局）：

| 按钮 | 功能 |
|------|------|
| 发起研究 | 启动 AI 多智能体深度分析（数分钟完成） |
| 持仓分析 | 对当前持仓发起 AI 分析 |
| 同步数据 | 手动拉取最新行情/财务数据（可选数据源和同步内容） |
| 模拟交易 | 跳转模拟交易页面，预填当前股票 |
| 加入/移出关注列表 | 快速管理关注状态 |
| 清除缓存 | 清除该股票的本地缓存，强制重新拉取 |

#### 基本面数据与新闻

页面底部的第 8 区域包含三张卡片（双栏网格排列），根据股票/ETF 类型自动切换显示内容：

**1. 基本面数据卡片（股票模式）**

展示基础估值与财务指标：

| 指标 | 说明 |
|------|------|
| 行业、板块 | 所属行业和市场板块（主板/创业板/科创板等） |
| 总市值 | 以"亿"为单位显示 |
| PE(TTM) | 滚动市盈率，实时数据时显示"实时"标签 |
| PB(市净率)、PS(TTM) | 市净率、市销率 |
| ROE | 净资产收益率 |
| 负债率 | 资产负债率 |
| 股息率 | 年化股息率 |
| 流动比率 | 流动资产/流动负债 |

**ETF 基础数据卡片（ETF 模式）**

当查看 ETF 时，自动切换为 ETF 专属字段：基金类型、跟踪指数、基金规模、基金份额、单位净值、累计净值、折溢价率、净值增长率、管理人、托管人。

**2. 财务明细快照卡片（仅股票）**

展示最新一期财报的明细数据：

| 指标 | 说明 |
|------|------|
| 毛利率、净利率 | 盈利能力指标 |
| 营收、净利润 | 经营规模（以"亿"为单位） |
| 经营现金流 | 经营活动产生的现金流 |
| 总资产、总负债 | 资产负债表摘要 |
| 数据源 | 财务数据来源（如 tushare） |

- 卡片头部显示报告期（如 `20250630`）
- 底部显示 `raw_data` 分组标签，列出可下钻的原始数据分组及条数（如"利润表 12 条"），这些分组已通过主股票接口暴露，后续可下钻调用

**3. 近期新闻与公告卡片**

| 功能 | 说明 |
|------|------|
| 筛选下拉框 | 支持"全部 / 新闻 / 公告"三种筛选 |
| 新闻列表 | 每条显示：类型标签（蓝色"新闻" / 橙色"公告"）、标题（可点击跳转原文）、相对时间（如"2 小时前""3 天前"）、来源 |
| 加载状态 | 数据加载中显示 loading 动画 |
| 空状态 | 无新闻时显示"暂无新闻"占位 |

> 新闻数据来源（如 tushare / akshare）显示在每条新闻的来源行。

#### 操作步骤

1. **进入详情页**
   - 从股票关注列表点击股票代码
   - 从研究报告点击股票代码
   - 从智能助手对话中点击股票链接
   - 直接访问 `/stocks/{股票代码}`

2. **快速研究流程**
   - 查看行情走势和核心指标，了解基本面
   - 点击"发起研究"启动 AI 多智能体分析（数分钟后完成）
   - 分析完成后，在智能助手对话区问"结合分析和持仓给我解读"
   - 助手会聚合单股分析、持仓、复盘给出综合判断

3. **数据同步**
   - 点击"同步数据"按钮
   - 勾选同步内容（实时行情 / 历史行情 / 财务数据 / 基础数据）
   - 选择数据源（Tushare / AKShare / QMT）
   - 可指定历史数据天数（最多 3650 天，约 10 年）
   - 同步完成后刷新页面查看最新数据

#### 注意事项

- 详情页内的智能助手对话限定在当前股票主题内，无法切换到其他股票；如需咨询其他标的，请前往独立的智能助手页面（`/assistant`）
- 报告超过 24 小时会被标记为过期，智能助手不会基于过期报告给出结论，需重新发起分析
- K线图和核心指标依赖已同步的数据，如数据为空请先点击"同步数据"
- 行情数据为延迟行情，不作为交易依据
- 智能助手回答基于已加载的研究数据生成，仅供研究参考，不构成投资建议

---

## 第四章 学习研究与模拟功能

本章介绍用于学习研究和策略验证的功能模块，包括模拟交易、持仓研究、操作复盘和交易计划。这些功能帮助您在虚拟环境中验证研究假设、复盘操作行为、制定系统化跟踪计划，不构成任何投资建议。

### 4.1 模拟交易（/paper）

#### 功能说明

模拟交易系统提供虚拟资金环境，支持模拟买入、模拟卖出、模拟持仓管理，帮助您在不投入真实资金的情况下学习市场操作流程、验证研究假设。v3.0 支持 A 股和 ETF 模拟交易。模拟交易仅用于学习研究，不构成任何投资建议。

#### 操作步骤

1. **初始化模拟账户**
   - 首次进入"模拟交易"，系统会提示创建模拟账户。
   - 设置初始资金（默认 100 万人民币）。
   - 选择账户类型：A股账户。

2. **模拟买入（虚拟建仓）**
   - 点击"买入"按钮。
   - 输入股票代码、模拟买入价格、数量。
   - 可选择"市价"（以最新价成交）或"限价"（按指定价格挂单）。
   - 系统自动计算手续费、印花税等成本。
   - 确认后提交，成交后更新持仓和可用资金。

3. **模拟卖出（虚拟平仓）**
   - 在持仓列表中选择要卖出的股票。
   - 点击"卖出"，输入模拟卖出价格和数量。
   - 系统自动计算盈亏。

4. **持仓查看**
   - "持仓"页签显示当前所有持仓。
   - 每只股票显示：持仓数量、成本价、现价、浮动盈亏、盈亏比例。
   - 支持按盈亏排序。

5. **交易记录**
   - "记录"页签显示所有历史交易明细。
   - 支持按时间、股票筛选。

6. **账户统计**
   - "统计"页签显示账户总览：总资产、总市值、可用资金、总盈亏、收益率。
   - 提供收益曲线图。

#### 注意事项

- 模拟交易数据不影响真实账户，仅用于学习研究和策略验证，不构成投资建议。
- 模拟交易不模拟涨跌停限制和停牌，与真实交易存在差异。
- 手续费按真实费率计算（A股约万分之 2.5 + 印花税千分之 1），便于真实评估策略。
- 模拟账户资金可重置，重置后清空所有持仓和记录。

### 4.2 持仓研究（/portfolio）

#### 功能说明

持仓研究模块对您当前的模拟持仓进行深度分析，评估组合的风险暴露、行业集中度、相关性和优化建议。

#### 操作步骤

1. **进入持仓研究**
   - "持仓研究"页面自动读取模拟交易中的持仓数据。
   - 也可手动导入持仓（支持 Excel 模板上传）。

2. **组合概览**
   - 显示组合总市值、行业分布、仓位分布。
   - 饼图展示各行业占比、各股票占比。

3. **风险评估**
   - **行业集中度**：分析是否过度集中于某行业。
   - **个股集中度**：分析单只股票占比是否过高。
   - **相关性分析**：计算持仓间相关系数，评估分散度。
   - **Beta 暴露**：计算组合相对大盘的 Beta 值。

4. **优化建议**
   - 系统基于现代投资组合理论给出配置参考。
   - 标注过度集中的持仓，提示仓位集中风险。
   - 推荐可补充的行业或标的以提升分散度。

5. **一键分析**
   - 可对单只持仓发起"单股研究"，快速获取深度分析报告。

#### 注意事项

- 持仓研究依赖模拟交易数据，请先在模拟交易中建立持仓。
- 相关性分析需要历史数据，新股或数据不足的股票可能无法计算。
- 优化观察仅供参考，不构成投资建议。

### 4.3 操作复盘（/review）

#### 功能说明

操作复盘模块帮助您回顾历史交易行为，分析盈亏原因，总结交易经验，持续改进交易策略。v3.0 引入 **5 个专项复盘 Agent**，把复盘从"凭感觉写总结"升级为"结构化归因分析"。

#### 5 类复盘 Agent

每次创建复盘时，**5 个 Agent 会各管一摊**，从不同角度帮您分析这笔交易：

| 复盘 Agent | 关注什么 | 会问您什么 |
|-----------|---------|----------|
| **时机复盘**（timing） | 交易时点 | 当时是不是好时机？是不是追高了？是不是杀跌了？ |
| **仓位复盘**（position） | 仓位大小 | 仓位是不是太重？调仓节奏是否合理？ |
| **情绪复盘**（emotion） | 决策心态 | 当时是不是被情绪左右？有没有 FOMO、恐惧、贪婪？ |
| **归因复盘**（attribution） | 盈亏来源 | 这次赚/亏是来自行业 β、个股 α、还是运气？ |
| **复盘经理**（review_manager） | 综合归因 | 综合上述 4 个角度，给出最终结论 |

#### 操作步骤

1. **创建复盘记录**
   - "操作复盘"页面，点击"新建复盘"。
   - 选择要复盘的交易（从模拟交易记录中选取）。
   - 或手动录入一笔交易进行复盘。

2. **5 类复盘自动触发**
   - 选择交易后，系统自动调用 5 个 Agent 并行分析
   - 每个 Agent 独立生成报告（3-5 分钟）
   - 复盘经理综合 4 个角度给出最终结论

3. **复盘内容**
   - **交易背景**：当时为什么做这笔交易？（可从对应日期的分析报告中自动带入）
   - **决策依据**：基于什么信息或信号？
   - **实际结果**：盈亏情况、持有时间。
   - **5 类 Agent 报告**：时机、仓位、情绪、归因、综合
   - **经验总结**：做对了什么？做错了什么？
   - **改进点**：下次类似情况如何操作？

4. **复盘分类**
   - 可为复盘打标签：顺势交易、逆势抄底、止损、止盈、错误操作等。
   - 支持按标签统计胜率和盈亏。

5. **复盘统计**
   - 统计页面展示：总交易次数、胜率、平均盈亏、盈亏比。
   - 按标签维度分析哪些类型的交易表现更好。
   - 按 Agent 维度看：您的"时机判断"准确率 vs "仓位控制"准确率

6. **关联分析报告**
   - 复盘时可关联当时的研究报告，对比"分析结论"与"实际走势"的偏差。

#### 反思自动沉淀

每次复盘完成后，**复盘反思**（trade_lesson）会被自动写入 AI 记忆。Agent 在下次分析时会引用您之前的教训：

- 之前复盘发现"我经常在涨停次日追高" → 下次分析时，Agent 会主动提醒
- 之前复盘发现"白酒股我总拿不住" → 下次分析白酒股时，Agent 会提到您这个习惯

#### 注意事项

- 复盘是提升交易能力的关键环节，建议对每笔重要交易都进行复盘。
- 复盘记录会自动关联到 AI 记忆系统，智能助手可在后续分析中参考您的交易偏好。
- 5 类复盘 Agent 每次都会跑（不可单独关闭），但您可以只看"复盘经理"的综合结论。

### 4.4 交易计划（/trading-system）

#### 功能说明

交易计划模块帮助您制定系统化的交易计划，包括入场条件、仓位管理、止盈止损规则，并可关联分析报告自动生成计划。

#### 操作步骤

1. **创建交易计划**
   - "交易计划"页面，点击"新建计划"。
   - 选择目标股票。
   - 可选择"从分析报告生成"（系统根据最新报告自动填充建议参数）。

2. **设置计划要素**
   - **入场条件**：价格触发条件、技术指标条件、基本面条件。
   - **计划仓位**：初始仓位、追加观察规则、最大仓位。
   - **收益关注规则**：收益关注价位、分批跟踪、移动跟踪。
   - **风险关注规则**：风险关注价位、风险比例、时间观察。
   - **跟踪周期**：短线（数日）/ 波段（数周）/ 中线（数月）/ 长线（数年）。

3. **计划模板**
   - 系统内置多种研究跟踪计划模板（趋势跟踪、价值投资、事件驱动等）。
   - 可基于模板快速创建，再根据实际情况调整。
   - 支持保存自定义模板。

4. **计划执行跟踪**
   - 计划创建后进入"待执行"状态。
   - 当市场价格触发入场条件时，系统会发出通知。
   - 可手动标记"已入场"、"已触及收益关注位"、"已触及风险关注位"。
   - 系统自动计算计划执行情况与计划目标的偏差。

5. **计划与复盘联动**
   - 计划完成后可一键生成"操作复盘"记录，形成闭环。

#### 注意事项

- 交易计划不会自动下单，仅作为学习研究和纪律约束工具，不构成投资建议。
- 收益/风险价格条件触发时系统会推送通知，但不会自动执行交易。
- 建议在模拟交易中验证计划假设后再作为个人决策参考。

---

## 第五章 智能助手

### 5.1 AI 对话助手（/assistant）

#### 功能说明

智能助手是 v3.0 的核心升级模块，从"分析触发器"进化为"投资研究协同入口"。支持自然语言对话，可调用 20+ 操作工具，跨模块完成任务，支持多主题会话。

#### 核心能力

- **分析触发**：自然语言发起单股/批量分析。
- **报告查询**：搜索、查看、解读历史报告。
- **任务管理**：查询任务状态、管理定时任务。
- **股票关注列表管理**：添加、删除、查询关注股。
- **持仓分析**：查询持仓、分析组合。
- **交易复盘**：查询历史交易、辅助复盘。
- **投资计划**：创建、查询交易计划。
- **价格下限提醒**：设置价格下限提醒。
- **复杂任务拆解**：自动将复杂需求拆解为多步骤执行。
- **RAG 金融知识检索**：内置金融知识库，减少幻觉。

#### 操作步骤

1. **进入智能助手**
   - 左侧导航栏"智能助手"，或按 `Ctrl+/` 快捷键。

2. **创建会话**
   - 点击"新建会话"，可选择会话主题（如"贵州茅台研究"、"消费板块跟踪"）。
   - 每个主题独立维护消息历史与上下文。

3. **对话交互**
   - 直接输入问题或指令，例如：
     - "帮我分析一下贵州茅台最近的基本面"
     - "我最近关注的股票表现怎么样？"
     - "帮我把 ROE 大于 20% 的股票筛出来"
     - "查一下我上个月买的宁德时代现在赚了多少"
     - "解释一下什么是 PEG 估值"
   - 助手会理解意图、调用工具、返回结构化结果。

4. **多轮对话**
   - 助手会记住最近 10 条对话上下文，支持追问。
   - 例如先问"分析贵州茅台"，再问"它的风险点有哪些"，助手能理解"它"指代贵州茅台。

5. **会话管理**
   - 可创建多个会话主题，切换时上下文独立。
   - 支持手动"总结会话"生成结构化摘要。
   - 可重命名、删除、归档会话。

6. **IM 格式适配**
   - 当通过 QQ 等即时通讯渠道使用助手时，输出会自动转为精简纯文本格式。

#### 注意事项

- 助手调用工具时会消耗 Token，复杂任务消耗较大。
- 滑动窗口记忆保留最近 10 条对话，更早的对话不会进入上下文。如需长期记忆，请使用"总结会话"功能或依赖 AI 记忆系统。
- 助手会自动注入用户画像信息（近期分析、关注领域），以提供更精准的回答。
- 助手回答仅供参考，重要决策请结合研究报告独立判断。
- **股票详情页内的智能助手**：在股票详情页（[3.7 股票详情页](#37-股票详情页-stockscode)）中使用助手时，对话会自动限定在该股票的主题内，并聚合解读单股分析、持仓、复盘三份报告。超出该股票的问题会被引导前往独立的智能助手主页面继续。

### 5.2 AI 记忆（/memory）

#### 功能说明

AI 记忆是 v3.0 的股票对象记忆系统，系统会自动记忆每次分析的关键结论、用户的交易偏好和关注重点，在后续分析中作为上下文注入，实现"越用越懂你"。

#### 记忆类型

v3.0 提供 **7 种记忆类型**，覆盖对话、用户、Agent 经验、Skill 教训、交易模式等所有层面：

| 记忆类型 | 范围 | 记忆什么 | 谁能看到 |
|---------|------|---------|---------|
| **对话记忆**（CONVERSATION） | 单次会话 | 您和智能助手最近的对话（默认滑动窗口 10 条） | 您 |
| **用户偏好**（USER_PREFERENCE） | 跨会话 | 投资风格、风险偏好、持仓周期、行业偏好 | 您 + 系统 |
| **分析洞见**（ANALYSIS_INSIGHT） | 跨次分析 | 每次分析的结论、关键判断、风险点（按股票） | 您 + 该股票的下次分析 |
| **Agent 经验**（AGENT_EXPERIENCE） | 跨次分析 | Agent 自我反思的教训（辩论后提炼的复用框架） | 您 + 所有 Agent |
| **技能教训**（SKILL_LESSON） | 跨次生成 | Skill 生成失败的模式（避免下次重犯） | 系统 + Skill 工坊 |
| **交易模式**（TRADE_PATTERN） | 跨次交易 | 您的交易行为画像（习惯、偏好、容易犯的错） | 您 + 智能助手 |
| **Agent 构建教训**（AGENT_BUILDER_LESSON） | 跨次构建 | Agent 工坊创建时踩过的坑 | 系统 + Agent 工坊 |

**对您来说最重要的 3 种记忆**：

1. **用户偏好**（USER_PREFERENCE）：告诉系统"我关心什么"。比如"我偏好低估值、高分红"，下次分析时智能助手会主动找这类股票。
2. **分析洞见**（ANALYSIS_INSIGHT）：每只股票的历史分析会自动积累。下次分析同一只股票时，系统会引用之前的结论。
3. **交易模式**（TRADE_PATTERN）：基于您的历史交易，归类出"您是左侧还是右侧交易者""经常止损在哪"。复盘时智能助手会引用。

**其他 4 种是给"系统自己"用的**，普通用户不需要关注。

#### 操作步骤

1. **查看记忆**
   - "AI 记忆"页面分三个标签页：股票记忆、用户画像、交易行为。
   - 股票记忆按股票代码组织，点击可查看该股票的所有历史记忆条目。

2. **记忆详情**
   - 每条记忆显示：内容摘要、来源（哪次分析/对话产生）、创建时间、优先级。
   - 支持编辑记忆内容（修正错误信息）。

3. **记忆管理**
   - **删除记忆**：过期或错误的记忆可删除。
   - **调整优先级**：高优先级记忆会优先注入到分析上下文。
   - **手动添加**：可手动录入一条记忆（如"该股有大股东减持计划"）。

4. **记忆注入**
   - 系统在执行分析时，会自动检索相关记忆并注入到分析师的上下文中。
   - 在智能助手对话中，用户画像记忆会自动注入，使助手更懂您。

#### 注意事项

- 记忆系统是 AI 能力的"放大器"，但记忆条目过多可能增加 Token 消耗。
- 建议定期清理过期记忆（如半年以上未更新的股票记忆）。
- 记忆内容会被加密存储，不会泄露给第三方。
- 记忆系统为高级功能，记忆条目数量上限受授权等级影响。

---

## 第六章 高级功能

> **本章功能均为高级功能，需要高级版权限。** 标准版用户可浏览界面，但执行操作时会提示权限不足。

### 6.1 分析流（/workflow）

#### 功能说明

分析流是 v3.0 的核心高级功能，提供可视化的工作流编辑器，支持拖拽式编排分析流程。v3.0 采用 v2.0 分析引擎，在 v1.0 基础上新增条件分支、多轮辩论、并行/合并、后处理器等控制节点，支持 6 种流程类型和 AI 智能创建。包含五大子模块：流程管理、工具配置、Agent 工坊、Skill 中心、MCP 服务器。

#### 6.1.1 流程管理

##### 功能说明

流程管理支持创建自定义分析工作流，通过拖拽节点和连线编排分析流程，每个节点可绑定不同的 Agent 和工具集。v3.0 默认使用 v2.0 引擎，提供更丰富的节点类型和更灵活的流程编排能力。

##### v2.0 分析引擎

v3.0 的分析流全面升级为 v2.0 引擎，相比 v1.0 的改进：

| 特性 | v1.0 引擎 | v2.0 引擎 |
|------|-----------|-----------|
| 分析师 | 基础分析师 | 专业 v2.0 分析师（大盘、板块、市场、基本面、新闻、社媒） |
| 辩论机制 | 简单多情景研究 | 多轮多情景研究 + 三方风险情景研究 |
| 条件分支 | 不支持 | 支持 |
| 并行/合并 | 不支持 | 支持 |
| 后处理器 | 不支持 | 支持（报告生成等） |
| 风险评估 | 单一风险分析 | 高弹性/防御/基准三方风险情景研究 + 风险评估师审阅 |
| 研究整合 | 研究整合员 | 研究整合员（风险审阅后生成用户版结论） |
| 维护状态 | 已停止维护 | 持续维护 |

> 提示：打开 v1.0 遗留流程时，编辑器会显示"当前工作流属于 v1.0 遗留流程，已停止维护"的警告，建议迁移到 v2.0 工作流。

##### 流程类型

创建工作流时需要选择流程类型，不同类型对应不同的分析场景：

| 流程类型 | 说明 | 适用场景 |
|----------|------|----------|
| 单股研究流程 | 完整的单股分析流程 | 分析单只股票，结果在"研究报告"中查看 |
| ETF 分析流程 | ETF 专用分析流程 | 分析 ETF 基金（净值、规模、跟踪误差） |
| 持仓分析流程 | 持仓健康度分析 | 分析持仓股票的技术面、基本面和风险 |
| 操作复盘流程 | 交易复盘流程 | 复盘时机、仓位、情绪和归因 |
| 组合健康度流程 | 组合整体诊断 | 评估组合分散度、集中度 |
| 通用研究流程 | 自由探索 | 结果在"流程中心"查看 |

##### 操作步骤

1. **创建工作流**
   - "分析流 → 流程管理"，点击"新建分析流程"。
   - 选择流程类型（必选）和模板（可选）。
   - 输入名称和描述。
   - 点击"创建并进入编辑"。

2. **从模板创建**
   - 页面展示系统预置的 v2.0 模板，每个模板显示流程预览图和节点数量。
   - 点击"预览"查看模板的详细节点结构和流程说明。
   - 点击"使用此模板"，命名后创建副本，可在此基础上修改。

3. **可用模板**

   | 模板名称 | 说明 | 节点数 |
   |----------|------|--------|
   | v2.0 完整分析流 | 6 个分析师并行 → 多情景研究 → 研究整合员 → 风险多情景研究 → 风险评估师 → 研究整合员 | 16 |
   | v2.0 ETF 分析流 | ETF 分析师 + 市场分析师 + 新闻分析师，无多情景研究 | 8 |
   | 持仓研究流程 v2.0 | 技术面 + 基本面并行 → 风险复核 → 研究整合 | 7 |
   | 交易复盘流程 v2.0 | 时机/仓位/情绪/归因并行复盘 → 复盘总结 | 7 |
   | 空白流程 | 仅含开始和结束节点，从零构建 | 2 |

4. **编辑工作流**
   - 从左侧节点面板拖拽节点到画布。
   - 连接节点：点击节点的输出端口，再点击目标节点的输入端口。
   - 配置节点：点击节点，在右侧面板设置参数。

5. **节点类型**

   工作流编辑器提供两类节点：

   **智能体节点**（按类别分组）：
   - 分析师（analyst）：大盘分析师、板块分析师、市场分析师、基本面分析师、新闻分析师、社媒分析师
   - 研究员（researcher）：乐观情景研究员、审慎情景研究员
   - 风险分析（risk）：高弹性情景分析师、防御情景分析师、基准情景分析师
   - 经理（manager）：研究整合员、风险评估师
   - 研究整合员（trader）：研究整合员
   - 后处理器（post_processor）：报告生成器等

   **控制节点**：
   - 开始（start）：工作流入口
   - 结束（end）：工作流出口
   - 条件分支（condition）：根据条件表达式选择不同执行路径
   - 并行开始（parallel）：多个分支同时执行
   - 并行合并（merge）：等待所有并行分支完成后继续
   - 辩论节点（debate）：多轮对抗式辩论

6. **条件分支**
   - 条件分支节点支持根据条件表达式动态选择执行路径。
   - 从条件分支节点出发的边可以设置条件标签（如"true"/"false"）。
   - 适用于根据分析深度、市场类型等条件动态调整流程的场景。

7. **辩论节点**
   - 辩论节点是 v2.0 的核心创新，支持多轮对抗式辩论。
   - 配置辩论参与者（如乐观研究员 vs 审慎研究员，或三方风险分析师）。
   - 辩论轮次根据分析深度自动调整：
     - 1 级快速：多情景 1 轮 + 风险 1 轮
     - 2 级基础：多情景 1 轮 + 风险 1 轮
     - 3 级标准：多情景 1 轮 + 风险 2 轮
     - 4 级深度：多情景 2 轮 + 风险 2 轮
     - 5 级全面：多情景 3 轮 + 风险 3 轮

8. **三层配置优先级**
   - **Node 级**：单个节点的配置，优先级最高。
   - **Workflow 级**：工作流全局配置，作为节点默认值。
   - **Agent 级**：Agent 自身的默认配置，优先级最低。

9. **工具栏操作**
   - **编辑/预览**：切换编辑模式和预览模式。
   - **验证**：检查工作流的结构完整性（节点连接、必填配置等）。
   - **保存**：保存当前工作流配置。
   - **设为默认**：将当前工作流设为默认分析流程，后续分析任务自动使用。
   - **执行**：仅单股研究流程和 ETF 分析流程支持直接执行。

10. **管理已有工作流**
    - 在"我的分析流"区域查看已创建的工作流，按流程类型分组展示。
    - 支持操作：编辑、执行、复制、设为默认、删除。
    - 可修改流程类型：在编辑器工具栏点击"修改"切换流程类型。

##### 注意事项

- 工作流编辑器支持撤销/重做（Ctrl+Z / Ctrl+Y）。
- 复杂工作流建议先在小范围股票上试运行验证。
- v1.0 遗留流程已停止维护，建议迁移到 v2.0 工作流。
- Agent 工坊中创建的自定义 Agent 可在编辑器的智能体节点面板中使用。
- 设为默认的工作流会被单股研究、批量分析、定时分析自动选用。
- 持仓分析和操作复盘流程暂不支持从编辑器直接执行，需通过对应功能入口触发。

#### 6.1.2 AI 工作流架构师

##### 功能说明

AI 工作流架构师是 v3.0 的智能建流功能，通过自然语言对话自动规划和生成自定义工作流。系统会自动识别缺失的 Skill 并创建，最终生成可发布的工作流。

##### 操作步骤

1. **进入 AI 建流**
   - "分析流 → 流程管理"，点击"AI 智能创建"。
   - 或在分析流列表页点击"AI 智能创建"按钮。

2. **选择流程类型**（步骤一）
   - 选择要创建的分析流程类型（单股研究 / ETF 分析 / 持仓分析 / 操作复盘 / 通用研究）。

3. **需求沟通**（步骤二）
   - 用自然语言描述需求，例如："我需要一个专门分析白酒行业景气度的流程，关注批价、库存和动销数据"。
   - AI 会与您多轮对话，澄清需求细节。

4. **方案确认**（步骤三）
   - AI 生成工作流规划方案，包含节点拓扑和 Agent 配置。
   - 确认方案后进入下一步。

5. **自动补全**（步骤四）
   - 系统自动创建缺失的 Skill 和 Agent。
   - 补全节点配置、绑定工具集。
   - 可查看自动创建的 Skill 详情。

6. **完成发布**（步骤五）
   - 检查生成的工作流，确认后发布。
   - AI 建流生成的 Skill 会自动注册到 ToolRegistry，可在 Skill 中心查看。

##### 注意事项

- AI 建流过程消耗 LLM Token，建议需求描述清晰以减少迭代次数。
- 生成的 Skill 代码建议人工 review 后再使用。
- 如果对话中断，可返回列表页保存草稿。

#### 6.1.3 工具配置

##### 功能说明

工具配置用于管理分析工具的参数，包括数据源、缓存策略、调用频率等。

##### 操作步骤

1. "分析流 → 工具配置"查看所有已注册工具。
2. 点击工具进入参数配置页面。
3. 可调整：超时时间、重试次数、缓存时长、并发限制。
4. 配置保存后立即生效。

#### 6.1.4 Agent 工坊

##### 功能说明

Agent 工坊支持创建自定义 Agent，通过下拉选择 Agent 类型（如基本面分析师、新闻分析师）和名称，配置其使用的工具集和系统提示词。

##### 你能用什么工具

在创建自定义 Agent 时，可以从 **78 个内置工具**中选择绑定。常见分类：

| 您想做的分析 | 可绑定的工具（示例） |
|------------|------------------|
| **想算公司值多少钱** | `get_dcf_valuation`（DCF 估值）、`get_wacc_calculation`（WACC）、`get_peg_valuation`（PEG） |
| **想看有没有造假** | `get_beneish_mscore`（Beneish M 8 维度评分）、`get_financial_fraud_signals`（造假信号） |
| **想看会不会破产** | `get_altman_zscore`（Altman Z）、`get_ohlson_oscore`（Ohlson O） |
| **想看财务健不健康** | `get_piotroski_fscore`（Piotroski F 0-9 分）、`get_earnings_quality_score`（盈利质量 0-100） |
| **想看技术形态** | `get_candlestick_patterns`（K线 25+ 形态）、`get_chart_patterns`（图表形态）、`get_fibonacci_retracement`（斐波那契） |
| **想看支撑压力** | `get_support_resistance_levels`（支撑压力）、`get_pivot_points`（枢轴点） |
| **想看估值水平** | `get_comparable_company_valuation`（可比公司）、`get_industry_valuation_distribution`（行业分布） |
| **想看组合风险** | `get_var_calculation`（VaR）、`get_sharpe_ratio`（夏普）、`get_max_drawdown`（最大回撤） |
| **想选股票** | `get_multi_factor_screening`（多因子）、`get_graham_screen`（Graham 式）、`get_dividend_stock_screen`（红利股） |
| **想看市场情绪** | `get_stock_sentiment`（雪球/股吧）、`get_stock_news_*`（新闻） |

> 💡 **提示**：完整的 78 个工具列表在 v3.0 分析能力全景章节有详细说明，绑定时可以按关键词搜索。

##### 操作步骤

1. **创建 Agent**
   - "分析流 → Agent 工坊"，点击"新建 Agent"。
   - **下拉选择 Agent 类型**：从系统预设类型中选择（分析师、数据处理、决策、通用等）。
   - **下拉选择 Agent 名称**：命名 Agent（如"白酒行业专家"、"风险预警专员"）。
   - 配置系统提示词（定义 Agent 的行为和角色）。
   - 选择绑定的工具集。

2. **配置 Agent**
   - 设置默认 LLM 模型。
   - 设置温度（Temperature）、最大 Token 等参数。
   - 配置工具白名单（限制 Agent 只能调用指定工具）。

3. **测试 Agent**
   - 在工坊中可直接测试 Agent，输入消息查看响应。
   - 工坊严格暴露 LLM 错误，不做规则兜底，便于定位问题。

4. **发布 Agent**
   - 测试通过后发布，Agent 可在工作流中被引用。

##### 注意事项

- Agent 类型决定其可用的工具范围，选择时请参考说明。
- UniversalAgent 作为兜底：未注册的 Agent 会从 `agent_configs` 自动创建 UniversalAgent 实例。
- 修改已发布的 Agent 会影响所有引用它的工作流，请谨慎操作。
- 一个 Agent 建议绑定 3-7 个工具，工具太多会让 LLM 选择困难、Token 消耗高。

#### 6.1.5 Skill 中心

##### 功能说明

Skill 中心支持通过对话式交互生成和管理 Skill（分析工具）。v3.0 的 Skill 自动生成系统采用 6 阶段管线，AI 自主编写并验证新工具。

##### 操作步骤

1. **对话式生成 Skill**
   - "分析流 → Skill 中心"，点击"生成新 Skill"。
   - 通过对话描述需求，例如："我需要一个能获取北向资金流入流出的工具"。
   - AI 会多轮对话澄清：输入输出、边界条件、异常处理。

2. **6 阶段管线**（工程师视角）
   - **需求分析**（RequirementAnalyzer）：明确 Skill 功能规格。
   - **代码生成**（CodeGenerator）：AI 编写 Skill 代码。
   - **静态验证**（StaticValidator）：语法检查、安全检查。
   - **沙箱运行**（SandboxRunner）：在隔离环境中运行测试。
   - **输出评估**（OutputEvaluator）：评估输出质量。
   - **迭代优化**（IterationController）：根据评估结果迭代改进。

3. **查看生成过程**
   - 每个阶段的结果都可查看，包括 AI 生成的代码、测试输出、评估报告。
   - 失败阶段会标注原因，可手动干预修正。

4. **注册入库**
   - 生成的 Skill 自动保存到 `external_skills` 集合。
   - 自动注册到 ToolRegistry，可在 Agent 工坊中被引用。

5. **管理 Skill**
   - 查看所有已生成的 Skill。
   - 可禁用、编辑、删除 Skill。
   - 支持版本管理，保留历史版本。

##### 您看到的 4 步流程

对普通用户来说，**生成一个 Skill 只要 4 步**：

| 步骤 | 您做什么 | 系统做什么 |
|------|---------|----------|
| **1. 提需求** | 用自然语言说"我想要一个能 ______ 的工具" | 系统多轮对话确认细节（输入输出格式、数据源） |
| **2. 自动生成 + 测试** | 等待（一般 5-15 分钟） | 内部完成需求分析 → 代码生成 → 静态验证 → 沙箱运行 → 评估 → 迭代 |
| **3. 看效果** | 看生成的代码 + 测试结果，满意就发布 | 列出所有版本、测试得分、是否通过验证 |
| **4. 绑定到 Agent** | 选一个 Agent，把 Skill 绑上去 | 自动注册到工具表，下次分析时 Agent 就能调用 |

**什么时候需要看 6 阶段管线？**
- Skill 没跑通时，定位"是需求没说明白、还是代码有问题、还是测试数据有问题"
- 想优化 Skill 时，看哪个阶段可以改
- 普通用户**不需要懂** 6 阶段，只需要按 4 步走

##### 注意事项

- Skill 生成会消耗较多 Token，建议需求描述清晰以减少迭代次数。
- 沙箱运行有超时限制，复杂 Skill 可能需要多次迭代。
- 生成的 Skill 在正式使用前建议人工 review 代码。
- 已绑定的旧版 Skill 不会被新版本覆盖，升级不破坏已有 Agent。

#### 6.1.6 MCP 服务器

##### 功能说明

MCP（Model Context Protocol）服务器将系统的 6 个标准工具通过 MCP 协议暴露，支持被 Claude Desktop、Cursor 等外部客户端直接调用。

##### 暴露的工具

- `analyze_stock`：触发股票分析（支持阻塞/非阻塞模式）
- `get_report`：获取分析报告
- `chat_with_assistant`：与智能助手对话
- `list_workflows`：列出可用工作流
- `screen_stocks`：股票筛选
- `get_market_overview`：获取市场概览

##### 操作步骤

1. **配置 MCP API Key**
   - "分析流 → MCP 服务器"，点击"生成 API Key"。
   - 系统在 `system_configs` 中管理 MCP API Key，支持多 Key 分发。

2. **设置每日配额**
   - 为每个 API Key 设置每日调用配额。
   - 系统按"用户 + 日期"统计调用量，超额自动拒绝。

3. **在 Claude Desktop 中接入**
   - 在 Claude Desktop 配置文件中添加 MCP 服务器地址和 API Key。
   - 即可在 Claude Desktop 中直接调用 TradingAgents 的分析能力。

4. **查看调用统计**
   - MCP 服务器页面展示各 API Key 的调用量、成功率、错误日志。

##### 注意事项

- MCP 功能基于 FastMCP 框架实现，符合 Anthropic MCP 规范。
- API Key 请妥善保管，泄露后请立即重置。
- 每日配额按北京时间 0 点重置。

### 6.2 Agent 工坊（独立入口）

> 本节为导航说明。Agent 工坊的完整使用指南详见 [6.1.4 Agent 工坊](#614-agent-工坊)。

Agent 工坊是创建和管理自定义 Agent 的可视化工具。当系统内置的分析师、研究员无法满足您的研究需求时，可在工坊中创建专属 Agent。

**快速入口**："分析流 → Agent 工坊"，详细操作请参考 6.1.4 节。

### 6.3 Skill 中心（独立入口）

> 本节为导航说明。Skill 中心的完整使用指南详见 [6.1.5 Skill 中心](#615-skill-中心)。

Skill 中心管理分析流中可调用的 Skill（技能），包括系统内置 Skill 和自定义 Skill。当需要为 Agent 添加新的数据查询或分析能力时，可在 Skill 中心创建。

**快速入口**："分析流 → Skill 中心"，详细操作请参考 6.1.5 节。

### 6.4 批量分析（/analysis/batch）

#### 功能说明

批量分析支持同时分析多只股票，适合需要横向比较或大范围筛选后深度分析的场景。

#### 操作步骤

1. **进入批量分析**
   - "批量分析"页面。

2. **添加股票**
   - 方式一：逐个输入股票代码添加。
   - 方式二：从关注列表导入（选择一个分组）。
   - 方式三：从筛选结果导入。
   - 方式四：批量粘贴股票代码（每行一个或逗号分隔）。

3. **设置分析参数**
   - 选择分析维度（与单股研究一致）。
   - 选择分析深度（建议批量分析使用"快速"或"标准"深度）。
   - 设置并发数（高级版支持并发，标准版串行执行）。

4. **启动批量分析**
   - 点击"开始批量分析"。
   - 系统显示总体进度和每只股票的子任务状态。
   - 可在任务中心查看完整进度。

5. **查看批量结果**
   - 完成后生成批量分析报告汇总表。
   - 表格展示每只股票的综合评级、关键指标、风险等级。
   - 支持按指标排序，快速找出最优标的。
   - 可导出为 Excel。

#### 注意事项

- 批量分析消耗 Token 较大，建议每次不超过 20 只股票。
- 并发数受授权等级和 API 速率限制双重约束。
- 批量分析中途可取消，已完成的子任务报告会保留。
- 建议先用股票筛选缩小范围，再对候选股批量分析，效率更高。

### 6.5 定时分析

#### 功能说明

定时分析支持按 CRON 表达式定时执行分析任务，适合需要持续跟踪某些股票的场景。分为"定时分析分组"和"定时分析配置"两个子模块，均位于"设置 → 个人设置"下。

#### 6.5.1 定时分析分组（/settings/watchlist-groups）

##### 功能说明

定时分析分组用于为定时分析任务准备股票集合，支持创建/编辑分组并配置分组的名称、描述、颜色标识、图标、默认分析深度，可从股票列表或标签导入股票。

##### 操作步骤

1. **创建分组**
   - "设置 → 个人设置 → 定时分析分组"，点击"新建分组"。
   - 填写分组名称（如"每日早报"、"每周复盘"、"白酒板块跟踪"）。
   - 填写分组描述（可选）。
   - 选择颜色标识（便于在列表中快速识别）。
   - 选择图标。
   - 设置默认分析深度（快速 / 标准 / 深度）。

2. **导入股票**
   - 方式一：从股票列表中逐个添加。
   - 方式二：从已有标签批量导入。
   - 方式三：从关注列表分组导入。

3. **管理分组**
   - 编辑分组信息或调整股票列表。
   - 删除分组（分组下的定时任务需先迁移或删除）。

##### 注意事项

- 分组是定时分析配置的基础，创建定时任务前需先准备好分组。
- 每个分组建议不超过 20 只股票，避免单次定时执行耗时过长。

#### 6.5.2 定时分析配置（/settings/scheduled-analysis）

##### 功能说明

定时分析配置用于创建和管理定时执行的分析任务，支持简单模式和高级模式（Cron 表达式），可配置执行时间段、默认分组、分析深度、邮件通知等。

##### 操作步骤

1. **创建定时分析配置**
   - "设置 → 个人设置 → 定时分析配置"，点击"新建配置"。
   - 选择默认分析分组（从 6.5.1 创建的分组中选择）。
   - 选择分析深度（快速 / 标准 / 深度）。
   - 配置邮件通知（可选，需先在通知设置中配置 SMTP）。

2. **设置执行时间**
   - **简单模式**：选择每日/每周/每月 + 执行时间，系统自动生成 CRON 表达式。
   - **高级模式**：直接输入 CRON 表达式，适合复杂调度需求。
   - **快速 Preset**：系统预设常用时间模板（如"每个交易日盘后"、"每周一早报"），一键应用。

3. **执行测试**
   - 配置完成后可点击"执行测试"立即运行一次，验证配置是否正确。
   - 测试结果会显示在执行历史中。

4. **查看执行历史**
   - 每次定时执行后自动记录到历史列表。
   - 可查看每次执行的状态、耗时、报告链接、错误信息。

5. **管理定时任务**
   - 列表页可启用/禁用、编辑、删除定时配置。
   - 支持批量操作。

##### 注意事项

- CRON 表达式使用 5 段格式（分 时 日 月 周），时区为 Asia/Shanghai。
- 定时分析在非交易日也会执行，如需仅交易日执行，请在工作流中配置过滤逻辑。
- 定时任务执行失败会自动重试 3 次，仍失败则发送通知。
- 定时分析消耗的 Token 计入账户配额，请注意成本控制。
- 建议将定时分析安排在盘后（如 16:00 之后），确保当日数据已同步。

#### 6.5.3 通过智能助手管理

可对智能助手说：
- "帮我创建一个每天早上 9 点分析贵州茅台的定时任务"
- "查看我所有的定时分析任务"
- "禁用每日早报定时任务"

### 6.6 通用研究（/analysis/general）

#### 功能说明

通用研究是一个基于通用流程的灵活研究工作台，与单股研究不同，它不限定分析目标为股票代码，而是支持任意自定义分析目标（如行业趋势、宏观事件、主题概念等），配合通用类型的工作流完成自由探索式研究。

**与单股研究的核心差异：**

| 对比项 | 单股研究 | 通用研究 |
|--------|---------|---------|
| 分析目标 | 股票代码（如 600519） | 任意文本（如"新能源车产业链"） |
| 工作流类型 | 单股研究流程 / ETF 分析流程 | 通用研究流程 |
| 表单参数 | 固定（股票代码、分析日期、深度等） | 动态（由所选流程的配置决定） |
| 结果查看位置 | 研究报告页面 | 任务中心 |
| 历史记录 | 研究报告页面 | 通用研究页面的"历史结果"标签页 |

#### 操作步骤

1. **进入通用研究**
   - 左侧导航栏"通用研究"，进入通用研究页面。
   - 页面分为"新分析"和"历史结果"两个标签页。

2. **选择分析流程**
   - 在"新分析"标签页的"流程选择"下拉框中，选择一个通用研究流程。
   - 下拉框仅显示通用类型（general）的工作流，带"默认"标签的为系统默认流程。
   - 选中后下方会显示流程描述。

3. **配置执行参数**
   - 选中流程后，页面动态展示该流程配置的参数表单。
   - 参数表单根据流程的 `input_config` 自动生成，不同流程的参数可能不同。
   - 常见参数类型：
     - **文本输入**：单行或多行文本（如分析目标、研究方向）
     - **数字输入**：数值型参数（如回看天数）
     - **下拉选择**：单选或多选（如模型选择、分析师选择）
     - **日期选择**：日期型参数
     - **开关**：布尔型参数（如是否启用记忆）
   - 必填项会有红色 `*` 标识。

4. **启动分析**
   - 点击"开始分析"按钮。
   - 系统创建分析任务并进入执行状态，页面展示：
     - 任务 ID（可复制）
     - 分析目标
     - 开始时间和已用时间
     - 实时进度条和当前执行步骤
   - 分析过程中按钮显示为加载状态，不可重复点击。

5. **查看结果**
   - 分析完成后，页面显示成功提示。
   - 点击"查看结果"按钮跳转到**任务中心**查看完整分析报告。
   - 通用研究的结果**不会出现在研究报告页面**，仅在任务中心可查。
   - 点击"重新分析"可回到表单重新提交。

6. **查看历史结果**
   - 切换到"历史结果"标签页。
   - 支持按以下条件筛选：
     - 流程：选择特定通用研究流程
     - 时间范围：按日期范围筛选
     - 关键字：搜索分析目标或摘要
     - 状态：全部 / 成功 / 失败
   - 点击历史记录可查看详情，包含：基本信息、错误信息、分析摘要、完整工作流输出、决策信息、原始数据。

#### 注意事项

- 通用研究必须选择一个通用类型的工作流，若没有可用流程，请联系管理员在"分析流 → 流程管理"中创建。
- 通用研究的分析目标由流程定义决定，部分流程可能要求输入股票代码作为分析目标，请参考流程描述。
- 通用研究结果仅在任务中心查看，不会出现在研究报告页面。
- 定时分析也支持通用研究流程，可在"定时分析配置"中选择通用流程并配置参数。
- 单次分析会消耗 LLM Token，请根据授权配额合理安排。

---

## 第七章 学习中心（/learning）

### 功能说明

学习中心提供丰富的学习资料，包括 AI 基础知识、提示词工程、模型选择指南、分析原理、风险提示、论文资源和高级课程。帮助用户从零开始理解 AI 投资分析的原理和方法。

### 内容分类

1. **AI 基础知识**：什么是大语言模型（LLM）、LLM 的工作原理、能力与局限。
2. **提示词工程**：Prompt 基础、最佳实践、如何写出有效的分析指令。
3. **模型选择**：不同 LLM 的特点对比、适用场景、成本考量。
4. **分析原理**：多智能体系统原理、TradingAgents 框架设计思路。
5. **风险与局限**：AI 分析的局限性、投资风险提示、如何理性使用 AI 建议。
6. **资源**：TradingAgents 论文解读、相关学术资源。
7. **高级课程**：（高级功能）系统化投资课程，涵盖策略构建、风控体系、组合管理等。

### 操作步骤

1. **浏览学习资料**
   - "学习中心"页面按分类展示所有资料。
   - 点击文章标题进入阅读。
   - 支持搜索功能。

2. **高级课程**（高级功能）
   - 高级课程为付费内容，需要高级版授权。
   - 课程以章节形式组织，支持学习进度跟踪。
   - 每章配有练习和案例。

3. **使用指南**
   - "使用指南"（/guide）是内置的快速上手教程。
   - 适合首次使用时浏览。

### 注意事项

- 学习中心内容会持续更新，建议定期浏览。
- 高级课程内容仅供学习，不构成投资建议。

---

## 第八章 系统管理

本章介绍系统管理相关的功能，位于"设置 → 系统管理"下。这些功能主要由管理员使用。

### 8.1 配置管理

#### 功能说明

配置管理是系统的核心配置入口，统一管理所有配置项，包括 LLM 密钥、数据源、分析参数、通知设置等。

#### 操作步骤

1. **进入配置管理**
   - "设置 → 系统配置 → 配置管理"。

2. **配置分类**
   - **LLM 配置**：API 密钥、模型选择、模型优先级、温度等参数。
   - **数据源配置**：Tushare、FinnHub、通联数据等数据源密钥和优先级。
   - **分析配置**：默认分析深度、缓存策略、并发数。
   - **通知配置**：邮件 SMTP、Webhook 地址、QQ Bot 配置。
   - **系统配置**：时区、语言、日志级别。

3. **QQ Bot 配置**
   - QQ Bot 接入允许通过 QQ 即时通讯与智能助手交互。
   - 配置项：QQ Bot 账号、密码、 WebSocket 连接地址。
   - 配置后可在 QQ 中直接与智能助手对话，输出会自动转为精简纯文本格式（适配 IM 场景）。
   - 详见 [5.1 AI 对话助手](#51-ai-对话助手-assistant) 中的"IM 格式适配"。

4. **配置导入导出**
   - 支持导出当前配置为 JSON 文件（密钥会脱敏）。
   - 支持从 JSON 文件导入配置（便于迁移或备份）。

5. **配置验证**
   - 修改配置后点击"验证"检查配置项有效性。
   - 系统内置配置校验器，会提示不合理的配置组合。

#### 注意事项

- 配置修改后部分项需要重启服务生效，系统会提示。
- 切勿在生产环境随意修改数据库连接等核心配置。
- 配置导出文件不含明文密钥，可安全分享。

### 8.2 数据库管理

#### 功能说明

数据库管理提供 MongoDB 数据库的状态查看、备份恢复、集合管理功能。

#### 操作步骤

1. **查看数据库状态**
   - "设置 → 系统管理 → 数据库"。
   - 显示连接状态、数据库大小、各集合大小、索引状态。

2. **数据备份**
   - 点击"备份数据库"，选择导出范围（全部集合或指定集合）。
   - 系统生成备份文件（.archive 格式），可下载保存。

3. **数据恢复**
   - 上传备份文件，点击"恢复"。
   - 恢复前系统会提示确认，避免误操作。

4. **集合管理**
   - 查看所有集合（如 `analysis_reports`、`paper_trades`、`favorites`、`external_skills` 等）。
   - 可查看集合的文档数量、占用空间。
   - 支持清空指定集合（危险操作，需二次确认）。

5. **索引管理**
   - 查看各集合的索引。
   - 可创建、删除索引。

#### 注意事项

- 数据库备份建议定期执行，可配合定时任务自动化。
- 恢复操作会覆盖现有数据，请谨慎。
- 清空集合不可恢复，操作前务必备份。
- v3.0 使用 MongoDB 端口 27019，与 v2.x 隔离。

### 8.3 多数据源同步

#### 功能说明

多数据源同步负责从外部数据源同步股票基础数据、行情数据、财务数据等，是分析功能正常运作的基础。支持多数据源状态查看、使用建议和同步控制。

#### 操作步骤

1. **查看数据源状态**
   - "设置 → 系统管理 → 多数据源同步"。
   - 页面展示各数据源（Tushare、AKShare 等）的连接状态和可用性。

2. **同步控制**
   - 可手动触发数据同步。
   - 查看同步历史记录，了解同步进度和失败原因。

3. **数据源使用建议**
   - 页面提供各数据源的使用建议，帮助选择合适的数据源。

#### 注意事项

- 数据同步依赖数据源 API 配额，Tushare 不同积分等级有不同调用限制。
- 首次同步耗时较长（30 分钟以上），建议在非高峰期执行。
- 同步失败时可查看日志定位原因，常见原因包括 API 配额耗尽、网络超时。

### 8.4 定时任务

#### 功能说明

定时任务管理系统的所有后台调度任务，包括数据同步、报告清理、缓存刷新等系统级任务，以及用户创建的定时分析任务。

#### 操作步骤

1. **查看定时任务列表**
   - "设置 → 系统管理 → 定时任务"。
   - 显示任务名称、CRON 表达式、上次执行时间、下次执行时间、状态。

2. **系统内置任务**
   - 数据同步任务（每日盘后）
   - 通知清理任务（90 天过期清理）
   - 缓存刷新任务

3. **任务操作**
   - 启用/禁用任务。
   - 手动触发执行。
   - 查看执行历史和日志。

#### 注意事项

- 系统内置任务请勿随意禁用，否则可能影响系统正常运行。
- 定时分析任务的配置入口在"设置 → 定时分析配置"，不在此处。
- 定时任务基于 APScheduler 实现，服务重启后任务会自动恢复。

### 8.5 操作日志与系统日志

#### 功能说明

系统提供两个独立的日志查看页面："操作日志"记录用户业务操作，"系统日志"记录系统运行事件，便于排障和审计。

#### 操作步骤

1. **查看操作日志**
   - "设置 → 系统管理 → 操作日志"。
   - 记录用户的业务操作（分析任务、交易操作、配置变更等）。
   - 支持按时间范围、操作类型筛选。

2. **查看系统日志**
   - "设置 → 系统管理 → 系统日志"。
   - 记录系统运行事件（服务启动、配置加载、定时任务、错误信息等）。
   - 支持按级别筛选（DEBUG / INFO / WARNING / ERROR）。
   - 支持按关键字搜索。

3. **下载日志**
   - 可按日期下载日志文件。
   - Docker 部署可通过 `docker-compose -p ta-v3 logs` 查看实时日志。

#### 注意事项

- 日志默认保存 30 天，可在配置中调整。
- DEBUG 级别日志量大，生产环境建议使用 INFO 级别。
- 日志中不含 API 密钥等敏感信息（已脱敏处理）。

### 8.6 工具能力索引

#### 功能说明

工具能力索引为系统中所有 Agent、Tool、Skill 建立统一的索引，支持语义搜索，便于在工作流编排和智能助手中快速定位可用能力。

#### 操作步骤

1. **查看能力索引**
   - "设置 → 系统管理 → 工具能力索引"。
   - 展示所有已注册的 Agent、Tool、Skill 清单。

2. **语义搜索**
   - 输入自然语言描述需要的能力，例如"获取北向资金数据"。
   - 系统返回匹配的 Tool/Skill 列表。

3. **索引管理**
   - 可手动重建索引（新增 Tool/Skill 后建议重建）。
   - 查看索引状态和统计信息。

#### 注意事项

- 能力索引是 AI 工作流架构师和智能助手调用工具的基础，保持索引最新很重要。
- 新增 Tool 或 Skill 后，系统会自动更新索引，但建议定期手动重建以确保一致性。

### 8.7 缓存管理

#### 功能说明

缓存管理用于查看和管理 Redis 缓存，包括行情数据缓存、分析结果缓存、会话缓存等。

#### 操作步骤

1. **查看缓存状态**
   - "设置 → 系统配置 → 缓存管理"。
   - 显示 Redis 连接状态、内存使用、各缓存类别命中率。

2. **缓存操作**
   - 清空指定类别缓存（行情、分析结果、会话）。
   - 清空全部缓存（需二次确认）。

3. **缓存策略配置**
   - 行情数据缓存时长（默认 1 小时）。
   - 分析结果缓存时长（默认 24 小时）。

#### 注意事项

- 清空缓存会导致后续请求重新获取数据，短暂变慢。
- v3.0 使用 Redis 端口 6381，与 v2.x 隔离。

### 8.8 数据导入管理（/settings/data-import）

#### 功能说明

数据导入管理提供股票数据和社媒消息的批量导入入口，支持通过 API 接口将外部数据导入系统数据库。此功能为高级功能，需要高级版授权。

#### 操作步骤

1. **进入数据导入管理**
   - "设置 → 系统管理 → 数据导入管理"。

2. **股票数据导入**
   - 点击"股票数据导入"，查看支持的导入数据类型和 API 文档。
   - 支持导入：行情数据、财务数据、自定义指标等。
   - 提供 JSON/CSV 模板下载，按模板格式准备数据后通过 API 上传。

3. **社媒消息导入**
   - 点击"社媒消息导入"，查看社媒消息导入 API 指南。
   - 支持 JSON 和 CSV 格式批量上传。
   - 导入的社媒消息可在"社媒消息管理"中查看和使用。

4. **查看 API 指南**
   - 页面提供详细的 API 接入文档链接。
   - 包含认证方式、请求格式、字段说明、示例代码。

#### 注意事项

- 数据导入需高级版授权，标准版用户仅可查看文档不可执行导入。
- 导入前请确认数据格式正确，错误格式会导致导入失败。
- 大批量导入建议分批执行，避免单次请求过大超时。

### 8.9 社媒消息管理（/settings/social-media）

#### 功能说明

社媒消息管理用于查看和管理导入的社交媒体舆情数据，支持按股票代码、市场、平台、情绪等多维度筛选，为新闻分析师提供额外的舆情信息源。

#### 操作步骤

1. **查看社媒消息**
   - "设置 → 系统管理 → 社媒消息管理"。
   - 列表展示所有已导入的社媒消息，包含来源平台、发布时间、内容摘要、情绪标签。

2. **筛选消息**
   - 按股票代码筛选：查看与特定股票相关的舆情。
   - 按市场筛选：A 股 / ETF。
   - 按平台筛选：东方财富股吧、雪球、微博等。
   - 按情绪筛选：利好 / 利空 / 中性。

3. **查看消息详情**
   - 点击消息查看完整内容、原始链接、关联股票。
   - 可查看该消息被哪些分析报告引用。

4. **上传社媒数据**
   - 点击"上传数据"按钮。
   - 选择文件格式（JSON / CSV）。
   - 必填字段：股票代码、平台、内容、发布时间。
   - 选择编码（UTF-8 / GBK）。

5. **查看 API 指南**
   - 点击"API 接入指南"查看详细的 API 文档。
   - 包含认证方式、请求格式、字段说明。

#### 注意事项

- 社媒数据由用户自行导入，系统不主动采集。
- 情绪标签由导入时指定或系统自动判断。
- 社媒消息保留 90 天，过期自动清理。

### 8.10 系统更新（/settings/update）

#### 功能说明

系统更新用于检查和安装系统版本更新，根据部署方式（Docker / Windows 便携版 / Windows 安装版）提供不同的更新方式。

#### 操作步骤

1. **查看当前版本**
   - "设置 → 系统管理 → 系统更新"。
   - 显示当前版本号、构建号、发布日期。

2. **检查更新**
   - 点击"检查更新"，系统连接更新服务器查询最新版本。
   - 如有新版本，显示版本号、更新内容摘要、更新包大小。

3. **Docker 部署更新**
   - Docker 部署不通过此页面更新。
   - 使用命令行拉取新镜像并重启：
     ```bash
     docker-compose -p ta-v3 pull
     docker-compose -p ta-v3 up -d
     ```

4. **Windows 便携版/安装版更新**
   - 点击"下载更新包"，下载最新版本安装包。
   - 下载完成后点击"应用更新"，系统自动停止服务、替换文件、重启。
   - 更新过程中请勿关闭程序或断电。

5. **查看更新历史**
   - 页面展示已安装的版本历史记录。

#### 注意事项

- 更新前建议备份配置和数据。
- Docker 部署请通过拉取新镜像方式更新，不使用此页面。
- 更新失败可查看日志定位原因，通常为网络问题或文件占用。
- 大版本升级（如 v2.x → v3.0）不支持在线更新，需全新安装。

### 8.11 提示词模板（/settings/templates）

#### 功能说明

提示词模板管理用于管理各 Agent 的系统提示词模板，支持按 Agent 类型、Agent 名称、模板名称、偏好、来源、状态筛选，提供查看、克隆、编辑、删除、设为当前、调试等操作。此功能为高级功能。

#### 操作步骤

1. **查看模板列表**
   - "设置 → 分析配置 → 提示词模板"。
   - 支持多维度筛选：Agent 类型、Agent 名称、模板名称、偏好标签、来源（系统内置/自定义）、状态（启用/禁用）。

2. **编辑模板**
   - 点击模板进入编辑页面。
   - 编辑区展示可用变量（如 `{stock_name}`、`{industry}`、`{financial_data}` 等）。
   - 提示词字段说明帮助理解每个字段的用途。
   - 保存时系统会进行基本语法检查。

3. **克隆模板**
   - 克隆现有模板作为基础，修改后另存为新模板。
   - 适合基于系统内置模板进行定制化。

4. **设为当前模板**
   - 每个 Agent 可设置一个"当前模板"，分析时使用该模板。
   - 切换当前模板会立即生效。

5. **调试模板**
   - 在编辑页面可点击"调试"，用测试数据渲染模板。
   - 查看实际注入给 LLM 的完整提示词，便于优化。

6. **Prompt 实时预览（/settings/prompt-preview）**
   - 在"设置 → 分析配置"中点击"Prompt 预览"，进入 Prompt 实时预览页面。
   - 选择 Agent 类型和 Agent 名称，预览分层组装后的最终 Prompt。
   - 查看各段来源（系统模板、自定义模板、注入策略等）和能力缺口分析。
   - 便于理解 Prompt 组装流程和排查提示词问题。

#### 注意事项

- 系统内置模板不可删除，但可克隆后修改。
- 修改模板会影响使用该模板的所有分析任务，请先调试验证。
- 模板中使用的变量必须与 Agent 上下文匹配，否则渲染时会留空。
- Prompt 预览为只读查看，修改 Prompt 请到提示词模板或注入策略管理。

### 8.12 注入策略管理（/settings/prompt-policies）

#### 功能说明

注入策略管理用于按 Agent + 场景控制上下文注入规则，精细化管理每个 Agent 在不同场景下接收的上下文信息。此功能为高级功能。

#### 配置项说明

1. **注入模式**：控制上下文注入的整体策略。
2. **行业/个股画像继承**：是否将行业和个股的画像信息注入到 Agent 上下文。
3. **能力块注入**：是否注入可用工具/能力的描述，让 Agent 知道可以调用哪些工具。
4. **外部缺口提醒**：当数据缺失时是否提醒 Agent 注意数据局限性。
5. **可比公司注入**：是否注入同行业可比公司信息供 Agent 参考。
6. **注入位置**：控制注入内容在提示词中的位置（前置/后置/内联）。

#### 操作步骤

1. **创建注入策略**
   - "设置 → 分析配置 → 注入策略管理"，点击"新建策略"。
   - 选择目标 Agent 和场景。
   - 配置各项注入规则。
   - 保存并启用。

2. **管理策略**
   - 支持启用/禁用、编辑、删除策略。
   - 每个 Agent + 场景组合可配置独立策略。

#### 注意事项

- 注入策略影响 Agent 的分析质量和 Token 消耗，配置越详细 Token 消耗越大。
- 建议先使用默认策略，仅在分析效果不理想时调整。
- 策略变更后需重新执行分析才能生效。

### 8.13 Prompt 设计助手（/settings/prompt-design）

#### 功能说明

Prompt 设计助手是一个引导式工具，通过四步流程帮助用户设计高质量的分析提示词，适合不熟悉提示词工程的用户快速上手。此功能为高级功能。

#### 设计流程（四步）

1. **选择分析目标**
   - 选择本次分析的核心目标（如估值分析、风险评估、行业对比等）。

2. **选择股票与行业**
   - 指定目标股票和所属行业。
   - 系统会据此推荐相关变量和数据。

3. **行业配置**
   - 查询行业是否已有配置。
   - 如已有配置可直接使用，如无则可创建新的行业配置。
   - 行业配置包含行业特征、关键指标、可比公司等。

4. **流程与节点**
   - 选择分析流程（对应工作流）。
   - 优化各节点的提示词。
   - 系统根据行业配置自动推荐优化建议。

#### 操作步骤

1. "设置 → 分析配置 → Prompt 设计助手"。
2. 按四步流程依次配置。
3. 完成后可预览生成的提示词。
4. 一键保存为提示词模板，或直接应用到指定 Agent。

#### 注意事项

- Prompt 设计助手生成的提示词建议人工 review 后再应用。
- 行业配置是 Prompt 设计的基础，建议先完善行业配置。
- 不同分析目标适合不同的提示词结构，不要一概而论。

### 8.14 行业/个股配置（/settings/analysis-profiles）

#### 功能说明

行业/个股配置通过聊天式协作生成行业分析草案，帮助系统理解特定行业和个股的特征，从而提升分析质量。配置内容包括行业特征、分析维度、关键指标、可比公司等。此功能为智能配置功能。

#### 操作步骤

1. **进入配置页面**
   - "设置 → 分析配置 → 行业/个股配置"。

2. **选择行业**
   - 从预设行业列表中选择目标行业，或输入自定义行业名称。

3. **生成行业草案**
   - 点击"生成草案"，AI 会根据行业信息生成首版配置草案。
   - 草案包含：行业特征描述、推荐分析维度、关键指标、可比公司列表。

4. **手动精修**
   - 在右侧面板查看当前草案。
   - 可手动编辑各字段，补充或修正 AI 生成的内容。
   - 数据覆盖评估显示配置的数据完整度。

5. **保存配置**
   - 精修完成后保存配置。
   - 配置生效后，分析该行业的股票时会自动应用。

6. **下一步建议**
   - 系统根据当前配置给出下一步优化建议（如补充可比公司、增加关键指标等）。

#### 注意事项

- 行业配置越完善，分析质量越高，但配置时间也越长。
- 可比公司建议选择同行业、相近市值的 3-5 只股票。
- 配置可随时修改，修改后新执行的分析会使用最新配置。
- 系统预设了部分常见行业的配置模板，可直接使用或在此基础上修改。

### 8.15 使用统计（/settings/usage）

#### 功能说明

使用统计页面展示系统各功能模块的 LLM 调用记录和 Token 消耗情况，帮助用户了解资源使用趋势和成本估算。

#### 统计范围说明

使用统计覆盖以下功能的 LLM 调用：
- 单股研究（analysis_type: stock_analysis）
- 批量分析（analysis_type: stock_analysis）
- 定时分析（走分析服务链路）
- Agent 工坊（analysis_type: agent_workshop）
- Skill 生成（analysis_type: skill_generation）
- Skill 参数提取/测试（analysis_type: skill_test）
- AI 对话助手（analysis_type: assistant）
- Prompt 设计助手（analysis_type: prompt_design）
- 持仓分析（analysis_type: portfolio）
- 操作复盘（analysis_type: trade_review）

#### 统计概览

页面顶部展示四个核心指标：

| 指标 | 说明 |
|------|------|
| 总请求数 | 统计周期内股票分析的 LLM API 请求总次数 |
| 总输入 Token | 统计周期内股票分析请求的输入 Token 总量 |
| 总输出 Token | 统计周期内股票分析请求的输出 Token 总量 |
| 总成本 | 按系统配置的 Token 单价估算的成本（仅供参考） |

#### 关于成本估算

- 成本是按系统配置中各模型的 Token 单价**估算**得出，并非实际账单金额。
- 各 LLM 供应商的计费规则不同（如订阅制、Coding Plan、包月套餐等），估算成本与实际账单可能存在较大偏差。
- 建议将此成本数据作为**相对趋势参考**（观察消耗增减趋势），而非绝对费用依据。
- 实际费用请以 LLM 供应商官方账单为准。

#### 图表区域

1. **按供应商统计**：饼图展示各 LLM 供应商（DeepSeek、通义千问、OpenAI 等）的 Token 占比。
2. **按模型统计**：饼图展示各模型（如 deepseek-chat、deepseek-reasoner、qwen-plus 等）的 Token 占比。
3. **每日成本趋势**：折线图展示统计周期内每日的估算成本变化趋势。

#### 使用记录

底部表格展示详细的使用记录，包含：
- 时间：请求时间。
- 供应商：LLM 供应商名称。
- 模型：使用的模型名称。
- 输入/输出 Token：本次请求的 Token 消耗。
- 成本：本次请求的估算费用。
- 功能：调用的功能模块（如单股分析、批量分析等）。

#### 操作步骤

1. "设置 → 系统管理 → 使用统计"。
2. 选择统计周期（最近 7 天 / 30 天 / 90 天）。
3. 查看统计概览和图表。
4. 如需最新数据，点击"刷新"按钮。
5. 可清理旧记录释放存储空间。

#### 注意事项

- 使用统计覆盖系统主要功能的 LLM 调用，包括股票分析、Agent 工坊、Skill 生成、AI 对话助手、持仓分析、操作复盘等。
- 估算成本仅供参考，实际费用以 LLM 供应商账单为准。
- 建议关注 Token 消耗的**相对趋势**，而非绝对金额。
- 如发现 Token 消耗异常突增，可排查是否有异常的分析任务或密钥泄露。

---

## 第九章 个人设置（/settings）

个人设置模块管理当前用户的个人偏好和账户安全配置，位于"设置 → 个人设置"下。包含以下子模块：通用设置、外观设置、分析偏好、通知设置、安全设置、助理设置、邮件通知（高级功能）、渠道推送（高级功能）、定时分析分组、定时分析配置、授权管理。其中定时分析分组和定时分析配置详见 [6.5 定时分析](#65-定时分析)。

### 9.1 通用设置

#### 功能说明

配置用户的基本信息偏好。

#### 操作步骤

- **用户名**：显示当前登录用户名（只读，不可修改）。
- **邮箱**：设置或修改个人邮箱地址。
- **语言**：简体中文 / English。
- **时区**：北京时间 (UTC+8) / 纽约时间 (UTC-5) / 伦敦时间 (UTC+0)。
- 点击"保存设置"按钮生效。

### 9.2 外观设置

#### 功能说明

配置界面显示偏好。

#### 操作步骤

- **主题模式**：浅色主题 / 深色主题 / 跟随系统。
- **侧边栏宽度**：通过滑块调整侧边栏宽度（200-400px，步进 20px）。
- 点击"保存设置"按钮生效。

### 9.3 分析偏好

#### 功能说明

配置单股分析时的默认行为，减少每次分析时的重复设置。

#### 操作步骤

- **默认市场**：A 股 / ETF，影响进入单股研究时的默认市场选择。
- **默认分析深度**：1 级 - 快速分析 / 2 级 - 基础分析 / 3 级 - 标准分析（推荐）/ 4 级 - 深度分析 / 5 级 - 全面分析。
- **默认分析师**：勾选每次分析默认选中的分析师（大盘分析师、板块分析师、市场分析师、基本面分析师、新闻分析师、社媒分析师）。
- **风险偏好**：防御 / 中性 / 高弹性（仅影响情景研究视角的呈现风格，不构成投资建议）。
- **自动刷新**：开启后自动刷新分析结果。
- **刷新间隔**：设置自动刷新间隔（10-300 秒）。
- 点击"保存设置"按钮生效。

### 9.4 通知设置

#### 功能说明

配置系统通知的接收方式。

#### 操作步骤

- **桌面通知**：开启/关闭浏览器桌面通知。
- **研究完成通知**：开启/关闭分析任务完成时的通知。
- **系统维护通知**：开启/关闭系统维护相关通知。
- 点击"保存设置"按钮生效。

### 9.5 安全设置

#### 功能说明

账户安全相关配置。

#### 操作步骤

- **修改密码**：点击"修改密码"按钮，在弹出的对话框中设置新密码。

### 9.6 助理设置

#### 功能说明

配置智能助手的行为偏好和回复风格。

#### 操作步骤

- **助理名字**：设置智能助手的名称（如"小财"、"投研助手"），可在对话中直接称呼。
- **语气风格**：专业严谨 / 轻松友好 / 简洁高效。
- **自定义指令**：输入自定义指令（如"回答尽量简短、多用表格、回复时带上数据来源"），助理会参考这些指令调整回答风格。
- 点击"保存设置"按钮生效。

### 9.7 邮件通知（/settings/email，高级功能）

#### 功能说明

邮件通知是一个独立的高级功能页面，用于配置 SMTP 邮件服务器并管理各类分析任务的邮件通知规则。与 9.4 通知设置中的桌面通知不同，邮件通知支持将分析报告和执行结果通过邮件推送到指定邮箱。

#### 操作步骤

1. **配置 SMTP 服务器**
   - "设置 → 个人设置 → 邮件通知"。
   - 填写 SMTP 服务器地址、端口、发送方邮箱、SMTP 用户名和密码。
   - 选择加密方式（SSL / TLS / 无加密）。
   - 点击"发送测试邮件"验证配置是否正确。

2. **配置通知规则**
   - 选择需要邮件通知的事件类型：
     - **单股研究完成**：单股分析任务完成后发送报告摘要。
     - **批量分析完成**：批量分析全部完成后发送汇总结果。
     - **定时分析完成**：定时分析任务完成后发送报告。
     - **分析失败通知**：任务失败时发送错误通知。
   - 设置收件人邮箱（支持多个，逗号分隔）。

3. **查看发送历史**
   - 页面下方展示邮件发送历史记录。
   - 可查看每封邮件的发送状态、发送时间、收件人、主题。
   - 发送失败的邮件可点击"重发"。

#### 注意事项

- 邮件通知为高级功能，需要高级版授权。
- SMTP 密码以加密方式存储，不会明文展示。
- 建议使用专用邮箱发送通知，避免主邮箱被限流。
- 定时分析的邮件通知建议配合 6.5 定时分析配置使用。

### 9.8 渠道推送（/settings/channel-configs，高级功能）

#### 功能说明

渠道推送是一个独立的高级功能页面，支持将系统事件推送到多种即时通讯渠道（飞书、钉钉、企业微信、邮件），实现多渠道消息触达。与 9.7 邮件通知不同，渠道推送支持多种 IM 平台和更灵活的事件订阅。

#### 支持的推送渠道

| 渠道 | 说明 | 配置项 |
|------|------|--------|
| **飞书** | 推送到飞书群或个人 | Webhook URL、签名密钥 |
| **钉钉** | 推送到钉钉群 | Webhook URL、加签密钥 |
| **企业微信** | 推送到企业微信群 | Webhook URL |
| **邮件** | 推送到指定邮箱 | SMTP 配置（与 9.7 共享） |

#### 支持的事件订阅

| 事件 | 说明 |
|------|------|
| **分析完成** | 单股/批量/定时分析完成后推送报告摘要 |
| **预警通知** | 价格预警、止盈止损触发时推送 |
| **工具缺口** | AI 工作流架构师发现 Skill 缺口时推送 |
| **系统通知** | 系统更新、授权到期等系统事件推送 |

#### 操作步骤

1. **进入渠道推送页面**
   - "设置 → 个人设置 → 渠道推送"。

2. **添加推送渠道**
   - 点击"新增渠道"。
   - 选择渠道类型（飞书 / 钉钉 / 企业微信 / 邮件）。
   - 填写渠道配置（Webhook URL、密钥等）。
   - 点击"测试连接"验证渠道可用性。

3. **配置事件订阅**
   - 在渠道详情中选择要订阅的事件类型。
   - 可为不同渠道订阅不同的事件组合。

4. **管理渠道**
   - 支持启用/禁用、编辑、删除渠道。
   - 可查看每个渠道的推送历史和成功率。

#### 注意事项

- 渠道推送为高级功能，需要高级版授权。
- Webhook URL 和密钥以加密方式存储。
- 各 IM 平台对消息频率有限制，建议只订阅重要事件。
- 飞书和钉钉的加签密钥请妥善保管，泄露后请立即重置。

---

## 第十章 常见问题（FAQ）

### Q1：安装时提示端口被占用怎么办？

**A：** v3.0 默认使用端口 8002（后端）和 8082（前端）。如果端口被占用：

1. Windows 安装包：安装程序会提示，可选择其他端口或释放占用端口。
2. Docker 部署：修改 `docker-compose.yml` 中的端口映射。
3. 查看端口占用：Windows 使用 `netstat -ano | findstr :8002`，Linux 使用 `lsof -i:8002`。

### Q2：API 密钥配置后分析任务报错？

**A：** 请按以下步骤排查：

1. 在"设置 → 系统配置"中点击"测试连接"验证密钥有效性。
2. 检查密钥是否有足够余额/配额。
3. 检查网络是否能访问对应的 API 端点（特别是 OpenAI 需要代理）。
4. 查看"日志管理"中的错误日志获取详细信息。
5. 如果使用代理，请在配置中设置 `HTTP_PROXY` / `HTTPS_PROXY`。

### Q3：分析任务一直排队中无法执行？

**A：** 可能原因：

1. 授权等级限制并发数，标准版同时只能运行 1 个任务，请等待当前任务完成。
2. 检查是否有"僵尸"任务占用并发槽，可在任务中心取消。
3. 系统资源不足（CPU/内存），请检查服务资源占用。

### Q4：分析报告显示数据不完整或为空？

**A：** 可能原因：

1. 数据源 API 配额耗尽，请在数据同步页面检查同步状态。
2. 该股票为新股或次新股，历史数据不足。
3. 股票代码输入有误，请核对代码格式。
4. 基础数据未同步完成，请先执行"初始化股票基础数据"。

### Q5：如何降低 Token 消耗？

**A：** 建议：

1. 日常分析使用低深度（1-2 级），重要标的再用高深度（3-4 级）。
2. 选择性价比高的模型（如 DeepSeek）作为主力。
3. 按需选择分析师，不需要的分析维度不要勾选。
4. 善用缓存，对相同股票的重复分析会命中缓存。
5. 在"系统管理 → 使用统计"中查看各功能的 Token 消耗趋势，及时调整策略（注意估算成本仅供参考，实际费用以供应商账单为准）。

### Q6：Docker 部署后如何升级版本？

**A：** 升级步骤：

```bash
# 1. 拉取新版本镜像
docker-compose -p ta-v3 pull

# 2. 重启服务（数据不会丢失）
docker-compose -p ta-v3 up -d

# 3. 查看日志确认启动正常
docker-compose -p ta-v3 logs -f backend
```

如需回退，将镜像标签改为之前的精确版本号即可。

### Q7：智能助手总是不理解我的问题怎么办？

**A：** 建议：

1. 尽量明确股票代码或名称，避免使用代词（如"那只股票"）。
2. 一次只问一个问题，复杂需求可分步描述。
3. 利用多主题会话，每个主题聚焦一个研究目标。
4. 如果助手调用了错误的工具，可反馈"不对，我想要的是..."进行纠正。
5. 定期清理不相关的会话历史，避免上下文干扰。

### Q9：v3.0 能否与 v2.x 同时使用？

**A：** 可以。v3.0 与 v2.1.0、v2.0.1 使用完全独立的端口和数据卷：

| 版本 | MongoDB | Redis | Backend | 前端 | Docker 项目名 |
|------|---------|-------|---------|------|--------------|
| v3.0 | 27019 | 6381 | 8002 | 8082 | `ta-v3` |
| v2.1.0 | 27018 | 6380 | 8001 | 8081 | `ta-v210` |
| v2.0.1 | 27017 | 6379 | 8000 | 8080 | `ta-v201` |

三者可在同一台机器上共存，互不干扰。

### Q10：生成的 Skill 代码有安全问题吗？

**A：** Skill 自动生成系统采取以下安全措施：

1. 静态验证阶段会进行安全检查，识别危险代码模式。
2. 沙箱运行在隔离环境中，限制文件系统和网络访问。
3. 生成的 Skill 建议在正式使用前人工 review 代码。
4. Skill 的权限受工具白名单约束，仅能调用授权的工具。

### Q11：MCP 服务器如何被 Claude Desktop 调用？

**A：** 配置步骤：

1. 在"分析流 → MCP 服务器"生成 API Key。
2. 在 Claude Desktop 配置文件（`claude_desktop_config.json`）中添加：
   ```json
   {
     "mcpServers": {
       "tradingagents": {
         "command": "npx",
         "args": ["-y", "fastmcp-client"],
         "env": {
           "MCP_SERVER_URL": "http://localhost:8002/mcp",
           "MCP_API_KEY": "your-api-key"
         }
       }
     }
   }
   ```
3. 重启 Claude Desktop，即可在对话中调用 TradingAgents 的分析能力。

### Q12：如何备份和迁移数据？

**A：**

1. **备份**：在"设置 → 系统管理 → 数据库"点击"备份数据库"，下载备份文件。
2. **迁移**：在新环境部署系统后，通过"恢复"功能上传备份文件。
3. **Docker 数据卷备份**：
   ```bash
   # 备份 MongoDB 数据卷
   docker run --rm -v ta-v3_mongodb_data:/data -v $(pwd):/backup ubuntu tar czf /backup/mongodb-backup.tar.gz /data
   ```
4. 建议定期自动备份，可配合定时任务实现。

### Q13：京东云合作版与标准版有什么区别？

**A：** 京东云合作版是专为京东云用户定制的版本，主要区别：

1. **配置方式**：京东云版通过环境变量注入大模型和数据源配置，无需在界面手动配置；标准版需在界面配置。
2. **可用模型**：京东云版仅支持京东云提供的 4 个模型（GLM-5 / GLM-5.1 / GLM-5.2 / DeepSeek-V4-Flash）；标准版支持多家供应商。
3. **数据源**：京东云版仅支持 Tushare；标准版支持 Tushare / AKShare / BaoStock。
4. **界面差异**：京东云版隐藏了大模型和数据源配置界面，禁用了相关 API。
5. **LLM 限速**：京东云版内置 429 重试 + 降并发机制，确保在京东云 API 限速下稳定运行。

详见 [1.4 京东云合作版部署](#14-京东云合作版部署可选)。

### Q14：京东云版分析任务报 429 限速错误怎么办？

**A：** 京东云版已内置限速应对机制，通常无需干预。如仍频繁报错：

1. **调大任务间隔**：在 `.env` 中设置 `JDYUN_STOCK_INTERVAL_SECONDS=30`（默认 10 秒）。
2. **避免高峰时段**：将定时分析安排在非高峰时段（如凌晨）。
3. **降低分析深度**：使用较低的分析深度减少 LLM 调用次数。
4. **检查并发数**：确保 `JDYUN_BATCH_MAX_CONCURRENT=1` 和 `JDYUN_WORKER_MAX_CONCURRENT=1`。
5. **查看重试日志**：系统会自动指数退避重试最多 8 次，检查日志确认重试是否生效。

---

## 第十一章 最佳实践

本章基于一个典型个人投资者的实际使用场景，串联系统各功能模块，帮助您高效使用系统。

**典型场景**：您是一位个人投资者，希望通过 AI 辅助分析提升研究效率。以下是从零开始到日常使用的完整路径。

### 11.1 从安装到首次分析

#### 第一步：安装与基础配置

1. **安装系统**：Windows 用户运行安装包，按向导完成安装；进阶用户使用 Docker 部署。
2. **登录系统**：使用默认账号 `admin / admin123` 登录，首次登录后到"个人设置 → 安全设置"修改密码。
3. **跟随使用指南**：点击左侧"使用指南"，按引导依次完成配置：
   - 配置 LLM 密钥和数据源密钥，填写 Token 配置
   - 同步股票基础数据
   - 搜索并添加股票关注列表
   - 完成第一次研究
4. **关键配置建议**：
   - LLM 密钥：推荐 DeepSeek（性价比高），配置后到"个人设置 → 分析偏好"设置默认分析深度和分析师。
   - 数据源密钥：推荐 Tushare，积分建议 2000+ 以解锁完整接口。
   - 修改默认密码：到"个人设置 → 安全设置"修改。

#### 第二步：首次分析验证

1. 进入"单股研究"，输入一只熟悉的股票代码（如 `000001` 平安银行）。
2. 选择"3 级 - 标准分析"深度（推荐入门使用，4-8 分钟）。
3. 默认选中"市场分析师"和"基本面分析师"，可按需添加"新闻分析师"。
4. 点击"开始智能分析"，等待分析完成。
5. 查看报告，确认各分析师的输出是否符合预期。

**避免的坑**：
- 不要在基础数据同步未完成时就开始分析，会导致数据不完整。
- 不要首次分析就使用 5 级全面分析，先用 3 级标准分析验证配置正确。

### 11.2 日常研究工作流

#### 建立关注列表

1. **添加股票关注列表**：在"股票关注列表"中添加关注的股票，按板块或策略分组管理。
2. **分组管理**：可创建多个分组（如"长线持仓"、"短线观察"、"打新标的"），每个分组可设置颜色和图标便于区分。
3. **快速分析**：在关注列表中可直接选择股票发起单股研究，无需重复输入代码。

#### 定时分析配置

对于需要定期跟踪的股票，使用定时分析功能自动化：

1. **创建分析分组**：到"个人设置 → 定时分析分组"创建分组（如"每日早报组"），添加需要定期分析的股票。
2. **创建定时配置**：到"个人设置 → 定时分析配置"创建配置：
   - 选择默认分析分组和分析深度（建议 3 级标准分析）。
   - 设置执行时间段（建议 16:30 盘后，确保当日数据已同步）。
   - 开启邮件通知，执行完成后自动接收报告摘要。
3. **查看执行历史**：在配置列表中点击"历史"查看每次执行的结果和报告。

#### 批量分析

需要一次性分析多只股票时使用批量分析：

1. 进入"批量分析"，添加多只股票代码。
2. 建议使用 2 级基础分析深度，平衡耗时和 Token 消耗。
3. 分析完成后可在"研究报告"中对比查看。

### 11.3 成本控制实践

#### Token 消耗管理

1. **查看 Token 统计**：到"系统管理 → 使用统计"查看各功能的 Token 消耗趋势，包括单股研究、Agent 工坊、Skill 生成、AI 对话助手、持仓分析等。注意：估算成本仅供参考，实际费用以 LLM 供应商账单为准。
2. **按需选择分析师**：每次分析只勾选必要的分析师，每个分析师独立消耗 Token。
3. **善用缓存**：相同股票的重复分析会命中缓存，24 小时内不重复消耗 Token。可到"系统配置 → 缓存管理"查看缓存状态。
4. **深度选择策略**：
   - 日常快速筛选：1 级快速分析（2-5 分钟，Token 消耗低）
   - 常规研究：3 级标准分析（4-8 分钟，推荐）
   - 重要标的决策：4 级深度分析（6-11 分钟，多轮辩论）
   - 批量分析：2 级基础分析（3-6 分钟，平衡成本）

#### 关于估算成本

使用统计中的"总成本"是按系统配置的 Token 单价估算的，仅供参考。各 LLM 供应商的计费规则不同（如订阅制、Coding Plan、包月套餐等），估算成本与实际账单可能存在较大偏差。建议关注 Token 消耗的相对趋势，而非绝对金额。

#### 缓存管理

1. 到"系统配置 → 缓存管理"定期查看缓存占用。
2. 可清理过期缓存释放空间，或清空所有缓存强制重新分析。

### 11.4 深度使用：自定义工作流、Agent 和 Skill

当默认分析师无法满足特定需求时，可通过自定义工作流、Agent 工坊和 Skill 中心扩展能力。

#### 自定义工作流

1. **选择创建方式**：
   - **从模板创建**（推荐）：在"分析流"页面选择一个系统模板（如 v2.0 完整分析流），创建副本后修改。
   - **AI 智能创建**：点击"AI 智能创建"，通过自然语言对话让 AI 自动规划工作流。
   - **空白流程**：选择"空白流程"模板，从零构建自定义流程。

2. **编排流程**：
   - 使用并行节点让多个分析师同时工作，提升效率。
   - 使用辩论节点实现多情景对抗，获得更全面的分析视角。
   - 使用条件分支根据分析深度或市场类型动态调整流程。
   - 自定义 Agent 需先在"Agent 工坊"中创建并发布，才能在编辑器中使用。

3. **验证与发布**：
   - 使用编辑器的"验证"功能检查工作流结构完整性。
   - 发布前在 2-3 只股票上试运行验证输出质量。
   - 使用"设为默认"让后续分析任务自动使用该工作流。

#### Agent 工坊：创建自定义分析师

Agent 工坊通过对话式流程创建自定义 Agent，不支持克隆系统 Agent。

1. **进入 Agent 工坊**：到"分析流 → Agent 工坊"，点击"新建 Agent"。
2. **描述需求**：用自然语言描述你想要的 Agent（如"我需要一个专门分析白酒行业景气度的分析师，关注批价、库存、动销数据"）。可使用"快速填充示例"参考格式。
3. **讨论需求**：系统会与你对话确认需求细节，可补充说明分析维度、输出格式等。
4. **确认规格**：讨论完成后，系统生成 Agent 规格说明，确认无误后点击"生成可测试版本"。
5. **测试验证**：在测试页面验证 Agent 输出是否符合预期。
6. **迭代优化**：如不满意，可提意见继续讨论，系统会迭代生成新版本（每次迭代生成独立版本，不影响已绑定的 Agent）。
7. **发布使用**：测试通过后发布，可在工作流编排中引用该 Agent。

#### Skill 中心：创建自定义工具

当 Agent 需要调用系统未提供的工具时，通过 Skill 中心生成：

1. **进入 Skill 中心**：到"分析流 → Skill 中心"。
2. **描述需求**：描述需要的工具功能（如"获取港股实时分笔数据"）。
3. **生成与验证**：系统生成 Skill 代码，经过静态检查、沙箱执行、质量评估和边缘测试后可用。
4. **迭代优化**：如不满意可迭代，每次迭代生成独立版本（如 original_v2、original_v3），不影响已绑定的 Agent。
5. **人工审查**：AI 生成的代码务必人工审查，确认无安全风险后使用。

#### 工作流编排最佳实践

1. 善用并行节点：分析师之间通常互不依赖，并行执行可显著缩短分析耗时。
2. 辩论轮次与深度匹配：日常分析使用 1 轮辩论即可，重要标的决策使用 2-3 轮。
3. 条件分支用例：可根据 `analysis_depth` 或 `market_type` 条件，让同一工作流适配不同场景。
4. 工作流和节点使用清晰的中文命名，便于维护。
5. 提示词模板支持绑定 `workflow_id`，可为不同工作流定制专属提示词（详见"系统管理 → 提示词模板"）。

### 11.5 数据管理实践

#### 数据同步

1. **首次同步**：到"系统管理 → 多数据源同步"执行初始化，建议在非高峰期（如夜间）执行。
2. **日常同步**：系统每日盘后自动同步，无需手动干预。
3. **监控同步状态**：定期查看同步页面，关注失败记录并重试。

#### 数据导入

到"系统管理 → 数据导入管理"可批量导入：
- **股票数据**：导入自有的股票基础数据或历史行情。
- **社媒消息**：导入社交媒体舆情数据，丰富新闻分析师和社媒分析师的信息源。

#### 数据备份

1. **Docker 部署**：定期备份 MongoDB 数据卷（`docker-compose -p ta-v3 exec mongodb mongodump`）。
2. **Windows 部署**：定期备份 `data/` 目录下的 MongoDB 数据文件。
3. **配置导出**：系统配置可导出（密钥自动脱敏），便于灾难恢复。

### 11.6 安全实践

#### 账户安全

1. **修改默认密码**：首次登录后立即到"个人设置 → 安全设置"修改默认密码。
2. **强密码**：使用 12 位以上密码，包含大小写字母、数字和特殊字符。
3. **定期更换**：建议每 90 天更换一次密码。

#### API 密钥安全

1. **最小权限**：数据源 API 只开通必要接口权限。
2. **密钥轮换**：建议每 6 个月轮换一次 API 密钥。
3. **监控异常**：关注"使用统计"中的 Token 消耗突增，可能是密钥泄露。
4. **不分享密钥**：不要将配置文件（含明文密钥）分享给他人。
5. **Docker 部署**：`docker/.env` 中使用占位符，启动后通过系统设置页面手动配置真实密钥。

#### Skill 代码安全

1. **人工审查**：AI 生成的 Skill 代码务必人工审查。
2. **沙箱验证**：生成的 Skill 必须通过沙箱运行验证后使用。
3. **工具白名单**：通过工具白名单限制 Skill 可调用的工具。

### 11.7 版本升级实践

#### 升级前

1. **备份数据**：升级前必须备份 MongoDB 数据库。
2. **查看发布说明**：了解新版本变更和破坏性改动。
4. **选择时机**：选择非交易时段升级，避免影响使用。

#### 升级后

1. **功能验证**：执行一次完整分析，验证核心功能正常。
2. **配置检查**：检查配置项是否丢失或需要调整。
3. **监控运行**：升级后 24 小时内密切关注系统运行状态。
4. **保留回滚能力**：升级前保留旧版本镜像/安装包，便于回滚。

### 11.8 京东云合作版使用建议

#### 部署建议

1. **环境变量优先**：所有配置通过 `.env` 文件管理，修改后重启服务生效。
2. **凭据安全**：`.env` 文件含敏感信息，不要提交到版本控制或分享给他人。
3. **首次启动**：京东云版首次启动会自动初始化数据库，请耐心等待 1-2 分钟。

#### 分析任务优化

1. **避免高峰时段**：京东云 LLM 存在限速，建议将批量分析和定时分析安排在非高峰时段（如凌晨 1-6 点）。
2. **合理设置任务间隔**：默认 10 秒间隔适用于大多数场景，如遇限速频繁可调大至 20-30 秒。
3. **分批执行批量分析**：单次批量分析不超过 10 只股票，避免长时间占用 LLM 资源。
4. **优先使用标准深度**：3 级标准分析在效果和耗时之间平衡最佳，深度和全面分析会显著增加 LLM 调用次数。

#### 定时分析建议

1. **错峰执行**：将不同分组的定时分析安排在不同时间段，避免同时触发多个分析任务。
2. **盘后分析**：建议在 16:30 之后执行定时分析，确保当日数据已同步。
3. **监控执行状态**：定期查看"任务中心"中的定时分析执行记录，及时发现限速导致的失败。

---

## 第十二章 关于（/about）

### 功能说明

关于页面展示系统介绍、核心功能、版本信息、技术架构和联系方式，帮助用户快速了解系统定位和技术栈。该页面无需登录即可访问。

### 页面内容

#### 1. Hero 区（系统介绍）

- **标题**：TradingAgents-CN v3.0
- **副标题**：AI辅助股票分析技术学习平台
- **描述**：专注于AI辅助分析技术的学习与验证平台，通过优化的工作流引擎和全流程分析辅助，帮助系统学习股票分析方法
- **定位徽章**：用于学习AI股票分析技术 / 不作操盘指导 / 实践学习方法论
- **原项目致谢**：基于 TradingAgents 项目开发
- **统计卡片**：智能体数量、数据源数量、监控时长等
- **快速入口**："开始分析"（跳转单股研究）、"查看课程"（跳转学习中心）

#### 2. 学习中心引导横幅

- 展示系统化学习课程的简介
- "查看课程"按钮跳转学习中心

#### 3. 核心功能

| 功能 | 说明 |
|------|------|
| 优化分析引擎 | v3.0 工作流引擎，可视化流程定义、Agent 工坊、Skill 中心、MCP 服务器 |
| 全流程分析辅助 | 数据收集→指标计算→智能体分析→报告生成，支持多种分析场景 |
| 提升学习能力 | AI 辅助学习专业分析方法论，过程透明，技能提升 |
| 配置化架构 | 工作流、智能体、工具、提示词均可动态配置 |

#### 4. 版本信息

- 版本号：v3.0（从系统 API 动态获取）
- 版本状态：动态判断（beta 版显示"测试版"标识）
- 构建时间、构建类型
- Git 提交哈希
- API 版本：v3.0
- 技术版本：Vue 3.4.0、Element Plus 2.4.4、FastAPI 0.104.0、Python 3.11.9

#### 5. 技术架构

| 类别 | 技术栈 |
|------|--------|
| 前端 | Vue 3、TypeScript、Element Plus、Pinia、Vite |
| 后端 | FastAPI、Python 3.11.9、Redis、MongoDB、异步处理 |
| v3.0 核心引擎 | 工作流引擎、Agent 工坊、Skill 中心、MCP 服务器、能力索引面板 |

#### 6. 项目来源

- 基于 TradingAgents（Tauric Research 团队开发）开源项目
- v3.0 核心改进：工作流引擎、Agent 工坊、Skill 中心、MCP 服务器

#### 7. 联系方式

| 渠道 | 信息 | 用途 |
|------|------|------|
| 邮箱 | hsliup@163.com | 技术支持和商务合作 |
| QQ 交流群 | 1079484482 | 用户交流和问题讨论 |
| 微信公众号 | TradingAgents-CN | 最新动态和使用教程 |

### 操作步骤

1. 点击左侧导航栏"关于"菜单。
2. 浏览各板块了解系统信息。
3. 如需技术支持，查看"联系方式"板块获取联系方式。

---

## 新手常见错误与避免方法

| 常见错误 | 原因 | 解决方法 |
|---------|------|---------|
| **分析任务一直排队不执行** | Worker 未启动 | 检查后端 Worker 进程是否运行，参考 8.4 定时任务 |
| **报告显示"数据不足"** | 股票数据未同步 | 先在 8.3 多数据源同步中拉取基础数据 |
| **LLM 调用报错 401** | API Key 无效或欠费 | 在 8.1 配置管理中检查 API Key，确认账户余额充足 |
| **LLM 调用报错 429** | 超出 API 限速 | 降低并发数，或升级 API 套餐（京东云版参考 Q14） |
| **分析结果全是"未知"** | 系统变量未注入 | 检查数据源配置，确认股票基础信息已同步 |
| **定时分析不执行** | 时间段配置错误 | 检查 6.5.2 定时分析配置的时间段是否正确 |
| **导出 PDF 中文乱码** | 系统缺少中文字体 | Docker 部署已内置；Windows 部署需安装中文字体 |
| **批量分析很慢** | 并发数过低或网络慢 | 适当调高并发数（京东云版保持默认1） |
| **模拟交易持仓不更新** | 行情数据未同步 | 在关注列表或股票详情页点击"同步"按钮 |
| **Agent 工坊创建的 Agent 不生效** | 未发布或未添加到流程 | 在 Agent 详情页点击"发布"，然后在流程管理中添加 |

---

## 附录

### A. 工作流编辑器画布操作

> v3.0 工作流编辑器画布支持以下鼠标 + 键盘操作（来自 [WorkflowCanvas.vue](file:///c:/TradingAgentsCN/frontend/src/views/Workflow/components/WorkflowCanvas.vue) 的 `canvas-help` 提示）：

| 操作 | 效果 |
|------|------|
| **滚轮** | 缩放画布 |
| **空格 + 拖动** | 平移画布 |
| **点击节点** | 选中节点 |
| **拖动节点** | 调整位置 |
| **节点之间连线** | 拖动节点边缘的连接点 |

> 💡 **提示**：v3.0 当前版本**未实现**全局快捷键（如 `Ctrl+/` 打开助手、`Ctrl+K` 全局搜索、`Ctrl+Z` 撤销等）。这些功能计划在后续小版本中提供。

### B. 相关文档

- [快速开始指南](getting-started/quick-start.md)
- [安装部署指南](getting-started/installation.md)
- [Docker 部署指南](getting-started/docker-deployment-guide.md)
- [API 密钥管理](configuration/api-key-management.md)
- [LLM 配置指南](configuration/llm-config.md)
- [模拟交易详解](features/paper-trading.md)
- [定时分析指南](features/scheduled-analysis-guide.md)
- [v2.1 vs v3.0 对比](../01-product/comparison/v2.1-vs-v3.0.md)
- [v3.0 发布说明](../01-product/release-notes/v3.0.0-beta.1.md)

### C. 技术支持

- **QQ 群**：参见安装包内说明
- **GitHub Issues**：https://github.com/hsliuping/TradingAgents-CN/issues
- **邮箱**：参见官网联系方式

---

> **免责声明**：TradingAgents-CN Pro 提供的所有分析结果、研究观察、学习工具和模拟交易功能仅供学习和研究使用，不构成任何投资建议。投资有风险，决策需谨慎。系统基于 AI 模型生成分析，可能存在偏差或错误，请结合多方信息独立判断。

---

### 02 User Guide Learning 01 Ai Basics What Is Llm (`docs/02-user-guide/learning-01-ai-basics/what-is-llm.md`)

# 什么是大语言模型（LLM）？

**分类**: AI基础知识  
**难度**: 入门  
**阅读时间**: 8分钟  
**更新日期**: 2025-11-14

---

## 📋 引言

大语言模型（Large Language Model，简称LLM）是近年来人工智能领域最重要的突破之一。它们能够理解和生成人类语言，在各个领域展现出惊人的能力。本文将帮助你从零开始了解什么是大语言模型，以及它们如何应用于股票分析。

### 学习目标

- 理解大语言模型的基本概念
- 了解LLM的工作原理
- 认识LLM的核心特点
- 理解LLM在股票分析中的应用

---

## 🤖 什么是大语言模型？

### 定义

**大语言模型**是一种基于深度学习的自然语言处理（NLP）模型，通过在海量文本数据上进行训练，学习语言的模式和规律，从而能够理解和生成人类语言。

简单来说，LLM就像一个"读过无数书籍"的AI助手，它可以：
- 📖 理解你的问题
- 💬 用自然语言回答
- 📝 生成各种文本内容
- 🔍 分析和总结信息

### 为什么叫"大"语言模型？

"大"主要体现在三个方面：

1. **参数规模大**
   - GPT-3: 1750亿参数
   - GPT-4: 据估计超过1万亿参数
   - 参数越多，模型的表达能力越强

2. **训练数据大**
   - 训练数据通常包含数TB的文本
   - 涵盖书籍、网页、论文等多种来源
   - 数据越多，模型的知识越丰富

3. **计算资源大**
   - 需要数千个GPU进行训练
   - 训练时间可能长达数月
   - 成本可能达到数百万美元

---

## 🔧 LLM的工作原理

### 1. Transformer架构

大语言模型基于**Transformer**架构，这是一种专门为处理序列数据（如文本）设计的神经网络结构。

```
输入文本 → Token化 → Embedding → Transformer层 → 输出预测
```

**关键组件**：
- **Self-Attention机制**：让模型能够关注文本中的重要部分
- **多头注意力**：从多个角度理解文本
- **前馈神经网络**：进行复杂的特征转换

### 2. 预训练与微调

LLM的训练分为两个阶段：

**阶段1：预训练（Pre-training）**
- 在海量无标注文本上训练
- 学习语言的基本规律和知识
- 目标：预测下一个词（Next Token Prediction）

**阶段2：微调（Fine-tuning）**
- 在特定任务的数据上进一步训练
- 适应特定领域或任务
- 例如：针对股票分析进行微调

### 3. 提示学习（Prompt Learning）

现代LLM通过**提示词（Prompt）**来理解任务：

```
提示词示例：
"请分析以下股票的投资价值：
股票代码：000001
行业：银行
市盈率：5.2
市净率：0.6
..."
```

模型会根据提示词的内容和格式，生成相应的分析报告。

---

## ⭐ LLM的核心特点

### 1. 通用性（Generalization）

- ✅ 可以处理多种自然语言任务
- ✅ 无需为每个任务单独训练
- ✅ 通过提示词即可切换任务

**示例**：
- 文本生成：写文章、写代码
- 文本理解：问答、摘要
- 文本分析：情感分析、实体识别

### 2. 上下文学习（In-Context Learning）

- ✅ 可以从示例中学习
- ✅ 无需更新模型参数
- ✅ 通过Few-shot提示即可适应新任务

**示例**：
```
示例1：股票代码：600519，行业：白酒，研究结论倾向：乐观
示例2：股票代码：000858，行业：白酒，研究结论倾向：中性
现在分析：股票代码：000568，行业：白酒，研究结论倾向：？
```

### 3. 涌现能力（Emergent Abilities）

当模型规模达到一定程度时，会出现一些意想不到的能力：

- 🎯 复杂推理能力
- 🎯 代码生成能力
- 🎯 多步骤问题解决
- 🎯 创造性思维

### 4. 知识丰富

LLM在训练过程中学习了大量知识：

- 📚 通用知识：历史、地理、科学
- 💼 专业知识：金融、医学、法律
- 🌍 多语言能力：支持多种语言

---

## 📊 LLM在股票分析中的应用

### 1. 信息提取与整合

LLM可以从多个来源提取和整合信息：

- 📰 新闻报道
- 📊 财务报表
- 💬 社交媒体
- 📈 技术指标

### 2. 多维度分析

LLM可以从多个角度分析股票：

- **基本面分析**：财务指标、行业地位
- **技术面分析**：价格走势、技术指标
- **情绪分析**：市场情绪、投资者情绪

### 3. 生成分析报告

LLM可以生成结构化的分析报告：

```markdown
## 股票分析报告

### 基本信息
- 股票代码：000001
- 公司名称：平安银行
- 行业：银行

### 研究观察
基于当前市场环境和公司基本面...

### 风险提示
需要注意以下风险因素...
```

---

## 💡 总结

### 关键要点

1. **LLM是什么**：基于深度学习的大规模语言模型
2. **核心技术**：Transformer架构、预训练与微调
3. **主要特点**：通用性、上下文学习、涌现能力
4. **应用价值**：信息整合、多维分析、报告生成

### 下一步学习

- 📖 [Transformer架构详解](./transformer.md)
- 📖 [提示词工程基础](../02-prompt-engineering/prompt-basics.md)
- 📖 [多智能体系统](../04-analysis-principles/multi-agent-system.md)

---

## ❓ 常见问题

**Q: LLM真的"理解"语言吗？**

A: 这是一个哲学问题。LLM通过统计模式学习语言，能够生成合理的回答，但是否真正"理解"语言的含义仍有争议。

**Q: LLM的回答总是正确的吗？**

A: 不是。LLM可能会产生"幻觉"（生成不准确的信息），特别是在处理需要实时数据或专业知识的问题时。

**Q: 如何选择合适的LLM？**

A: 需要考虑多个因素：任务需求、成本预算、响应速度、准确性等。详见[模型选择指南](../03-model-selection/model-comparison.md)。

---

**相关资源**：
- [OpenAI GPT系列](https://openai.com/research/gpt-4)
- [Transformer论文](https://arxiv.org/abs/1706.03762)
- [TradingAgents项目](../06-resources/tradingagents-intro.md)

---

### 02 User Guide Learning 02 Prompt Engineering Best Practices (`docs/02-user-guide/learning-02-prompt-engineering/best-practices.md`)

# 提示词工程最佳实践

**分类**: 提示词工程  
**难度**: 进阶  
**阅读时间**: 12分钟  
**更新日期**: 2025-11-14

---

## 📋 引言

掌握提示词基础后，如何写出高质量的提示词？本文总结了提示词工程的最佳实践，帮助你充分发挥大语言模型的能力。

---

## 🎯 核心原则

### 1. 清晰性原则（Clarity）

**原则**：提示词要清晰明确，避免歧义。

❌ **不清晰**：
```
分析这个
```

✅ **清晰**：
```
请分析股票代码000001（平安银行）2024年第三季度的财务报表，
重点关注营收增长率、净利润率和ROE指标。
```

### 2. 具体性原则（Specificity）

**原则**：提供具体的细节和要求。

❌ **笼统**：
```
给我一些研究观察
```

✅ **具体**：
```
我是一位风险偏好中等的长期投资者，资金规模100万元，
请基于平安银行（000001）的基本面分析，
给出是否适合作为核心关注标的的研究观察。
```

### 3. 结构化原则（Structure）

**原则**：使用清晰的结构组织提示词。

✅ **结构化示例**：
```
# 角色
你是一位专注于银行股的资深分析师

# 任务
分析平安银行（000001）的投资价值

# 数据
- 股价：12.50元
- 市盈率：5.2
- ROE：10.5%

# 要求
1. 分析估值水平
2. 评估盈利能力
3. 给出研究观察

# 输出格式
使用Markdown，包含标题和列表
```

### 4. 迭代优化原则（Iteration）

**原则**：根据输出结果不断优化提示词。

**迭代流程**：
```
初始提示词 → 查看输出 → 发现问题 → 优化提示词 → 再次测试
```

---

## 🛠️ 实用技巧

### 技巧1：使用分隔符

使用分隔符清晰地分隔不同部分。

**示例**：
```
请分析以下股票数据：

---数据开始---
股票代码：000001
股票名称：平安银行
当前股价：12.50元
市盈率：5.2
---数据结束---

请基于以上数据进行分析。
```

**常用分隔符**：
- `---`
- `###`
- `"""` (三引号)
- `<data>...</data>` (XML标签)

### 技巧2：指定输出长度

明确指定回答的长度范围。

**示例**：
```
请用100-150字简要分析平安银行的投资价值。
```

或者：
```
请详细分析平安银行的投资价值，回答长度约500-800字。
```

### 技巧3：要求逐步思考

让AI展示思考过程，提高回答质量。

**示例**：
```
请分析平安银行（000001）是否值得投资。

要求：
1. 先列出分析需要考虑的关键因素
2. 逐一分析每个因素
3. 最后给出综合结论

请展示你的思考过程。
```

### 技巧4：提供正反例

通过正反例说明你想要什么。

**示例**：
```
请分析平安银行的投资价值。

✅ 好的回答示例：
"平安银行市盈率5.2，低于行业平均6.5，估值具有吸引力。
但需注意不良贷款率1.2%，略高于同业..."

❌ 不好的回答示例：
"这只股票很好，建议买入。"（含交易指令，不符合研究辅助定位）

请按照好的示例风格回答。
```

### 技巧5：设定约束条件

明确告诉AI什么不能做。

**示例**：
```
请分析平安银行的投资价值。

约束条件：
- 不要预测具体的股价涨跌
- 不要给出"必涨"、"必跌"等绝对判断
- 必须包含风险提示
- 使用客观、理性的语言
```

### 技巧6：使用模板

为常见任务创建提示词模板。

**股票分析模板**：
```
你是一位{专业领域}分析师。

请分析股票{股票代码}（{股票名称}）的{分析维度}。

当前数据：
{数据列表}

分析要求：
{具体要求}

输出格式：
{格式说明}
```

**使用示例**：
```
你是一位银行股分析师。

请分析股票000001（平安银行）的估值水平和盈利能力。

当前数据：
- 市盈率：5.2
- ROE：10.5%
- 净利润增长率：8.5%

分析要求：
1. 与行业平均对比
2. 与历史数据对比
3. 给出评价（低估/合理/高估）

输出格式：
使用Markdown，包含数据对比表格
```

---

## 📊 针对股票分析的最佳实践

### 1. 基本面分析提示词

**模板**：
```
你是一位专注于基本面分析的投资顾问。

请分析{股票代码}的基本面：

财务数据：
- 市盈率：{PE}
- 市净率：{PB}
- ROE：{ROE}
- 营收增长率：{revenue_growth}
- 净利润增长率：{profit_growth}
- 资产负债率：{debt_ratio}

行业信息：
- 所属行业：{industry}
- 行业地位：{position}

请从以下角度分析：
1. 估值水平（与行业对比）
2. 盈利能力
3. 成长性
4. 财务健康度

最后给出综合评分（1-5星）和研究观察。
```

### 2. 技术面分析提示词

**模板**：
```
你是一位技术分析专家。

请分析{股票代码}的技术面：

价格数据：
- 当前价格：{current_price}
- 20日均线：{ma20}
- 60日均线：{ma60}
- 近期高点：{high}
- 近期低点：{low}

技术指标：
- MACD：{macd}
- RSI：{rsi}
- 成交量变化：{volume_change}

请分析：
1. 趋势判断（上升/下降/震荡）
2. 支撑位和压力位
3. 技术指标信号
4. 短期走势预判

注意：技术分析仅供参考，不构成投资建议。
```

### 3. 多股对比提示词

**模板**：
```
请对比分析以下{N}只{行业}股票：

{股票列表及数据}

对比维度：
1. 估值水平（PE、PB）
2. 盈利能力（ROE、净利率）
3. 成长性（营收增长、利润增长）
4. 财务健康度（负债率、现金流）

请以表格形式展示对比结果，
并说明各自的优势和劣势，
最后推荐最适合{投资风格}投资者的股票。
```

---

## ⚠️ 常见陷阱

### 陷阱1：过度依赖AI

**问题**：
```
请告诉我明天应该买哪只股票
```

**为什么不好**：
- AI无法预测市场
- 投资决策需要综合考虑个人情况
- 可能导致盲目跟从

**正确做法**：
```
请分析以下3只股票的基本面，
帮助我了解它们的投资价值，
我会结合自己的风险偏好做出决策。
```

### 陷阱2：信息过载

**问题**：
```
请分析这只股票的基本面技术面行业地位竞争优势财务状况
历史表现未来前景管理层质量公司治理股东结构分红政策...
```

**为什么不好**：
- 一次问太多问题
- 回答可能不够深入
- 难以聚焦重点

**正确做法**：
分多次提问，每次聚焦一个主题。

### 陷阱3：缺乏验证

**问题**：直接相信AI的所有输出

**正确做法**：
```
请分析平安银行的财务数据，并注明数据来源。
我会自行验证这些数据的准确性。
```

---

## 💡 高级技巧

### 技巧1：链式提示（Chain of Prompts）

将复杂任务分解为多个步骤。

**示例**：
```
第一步提示：
"请列出分析银行股需要关注的10个关键指标"

第二步提示：
"基于你列出的指标，请分析平安银行的数据：
{数据}"

第三步提示：
"基于以上分析，请给出研究观察"
```

### 技巧2：角色扮演

让AI扮演不同角色，获得多角度分析。

**示例**：
```
场景1：你是一位保守的价值投资者
请从价值投资的角度分析平安银行

场景2：你是一位激进的成长投资者
请从成长投资的角度分析平安银行

场景3：你是一位风险管理专家
请指出投资平安银行的主要风险
```

### 技巧3：自我批评

让AI检查自己的回答。

**示例**：
```
第一步：请分析平安银行的投资价值

第二步：请检查你刚才的分析，指出可能存在的偏见或不足之处

第三步：基于自我批评，给出更全面的分析
```

---

## 📚 总结

### 核心要点

1. **清晰、具体、结构化**是好提示词的基础
2. **使用分隔符、模板、约束条件**提高效率
3. **针对股票分析**有专门的提示词模式
4. **避免陷阱**：过度依赖、信息过载、缺乏验证
5. **高级技巧**：链式提示、角色扮演、自我批评

### 实践建议

1. **建立自己的提示词库**：保存常用的提示词模板
2. **持续优化**：根据效果不断改进提示词
3. **分享交流**：与其他用户交流提示词经验
4. **保持批判性思维**：验证AI的输出

---

## 🔗 相关资源

- 📖 [提示词基础](./prompt-basics.md)

---

### 02 User Guide Learning 02 Prompt Engineering Prompt Basics (`docs/02-user-guide/learning-02-prompt-engineering/prompt-basics.md`)

# 提示词基础

**分类**: 提示词工程  
**难度**: 入门  
**阅读时间**: 10分钟  
**更新日期**: 2025-11-14

---

## 📋 引言

提示词（Prompt）是与大语言模型交互的关键。一个好的提示词可以让AI更准确地理解你的需求，生成高质量的回答。本文将介绍提示词的基础知识，帮助你掌握与AI对话的技巧。

### 学习目标

- 理解什么是提示词
- 掌握提示词的基本结构
- 学习编写清晰有效的提示词
- 了解常见的提示词错误

---

## 🎯 什么是提示词？

### 定义

**提示词（Prompt）**是你发送给大语言模型的输入文本，用于指导模型生成特定的输出。

简单来说，提示词就是你对AI说的话，告诉它你想要什么。

### 提示词的作用

```
你的提示词 → 大语言模型 → AI的回答
```

**示例**：

❌ **模糊的提示词**：
```
分析这只股票
```

✅ **清晰的提示词**：
```
请分析股票代码000001（平安银行）的投资价值，包括：
1. 基本面分析（财务指标、盈利能力）
2. 技术面分析（价格走势、技术指标）
3. 行业地位和竞争优势
4. 研究观察和风险提示
```

---

## 🏗️ 提示词的基本结构

一个好的提示词通常包含以下几个部分：

### 1. 角色设定（Role）

告诉AI它应该扮演什么角色。

**示例**：
```
你是一位资深的股票分析师，拥有10年以上的A股市场分析经验。
```

**为什么重要**：
- 帮助AI理解应该从什么角度回答
- 提高回答的专业性和针对性

### 2. 任务描述（Task）

清楚地说明你想要AI做什么。

**示例**：
```
请分析平安银行（000001）的投资价值。
```

**要点**：
- 使用明确的动词：分析、总结、比较、评估
- 指定具体对象：股票代码、公司名称
- 说明分析范围：时间段、维度

### 3. 上下文信息（Context）

提供必要的背景信息和数据。

**示例**：
```
当前股价：12.50元
市盈率：5.2
市净率：0.6
最近一年涨跌幅：-8.5%
行业：银行业
```

**为什么重要**：
- 让AI基于实际数据分析
- 避免AI编造信息（幻觉）

### 4. 输出格式（Format）

指定你希望的回答格式。

**示例**：
```
请按以下格式输出：

## 基本面分析
- 财务指标评价
- 盈利能力分析

## 技术面分析
- 价格走势
- 技术指标

## 研究观察
- 研究结论倾向：乐观/审慎/中性
- 理由：...
```

**常用格式**：
- Markdown格式
- JSON格式
- 表格格式
- 列表格式

### 5. 约束条件（Constraints）

设定回答的限制和要求。

**示例**：
```
要求：
- 回答长度不超过500字
- 使用简洁的语言，避免专业术语
- 必须包含风险提示
- 不要给出具体的买卖建议
```

---

## ✍️ 编写有效提示词的技巧

### 技巧1：具体明确

❌ **模糊**：
```
这只股票怎么样？
```

✅ **具体**：
```
请从基本面、技术面、行业地位三个维度分析平安银行（000001）的投资价值。
```

### 技巧2：提供充足信息

❌ **信息不足**：
```
分析一下银行股
```

✅ **信息充足**：
```
请分析平安银行（000001）：
- 当前股价：12.50元
- 市盈率：5.2（行业平均：6.5）
- ROE：10.5%
- 不良贷款率：1.2%
```

### 技巧3：分步骤引导

❌ **一次性要求太多**：
```
分析这只股票的所有方面并给出详细的研究观察和风险评估以及未来预测
```

✅ **分步骤**：
```
第一步：请先分析平安银行的基本面
第二步：基于基本面分析，评估其投资价值
第三步：列出主要风险因素
```

### 技巧4：使用示例

通过示例告诉AI你想要什么样的输出。

**示例**：
```
请按以下示例格式分析股票：

示例：
股票：贵州茅台（600519）
评级：★★★★★
理由：行业龙头，品牌价值高，盈利能力强
风险：估值偏高，政策风险

现在请分析：平安银行（000001）
```

### 技巧5：设定角色和语气

**示例**：
```
你是一位谨慎的价值投资者，请用客观、理性的语气分析平安银行。
避免使用夸张的表述，重点关注长期投资价值。
```

---

## 🚫 常见错误

### 错误1：提示词过于简短

❌ **太简短**：
```
000001
```

**问题**：AI不知道你想要什么

### 错误2：一次问太多问题

❌ **问题太多**：
```
分析000001的基本面技术面行业地位竞争优势财务状况未来前景研究观察风险因素...
```

**问题**：回答可能不够深入

### 错误3：使用模糊的词语

❌ **模糊**：
```
这只股票好不好？
```

**问题**："好"的标准不明确

✅ **明确**：
```
从长期投资价值的角度，分析这只股票的基本面趋势和主要风险
```

### 错误4：没有提供必要信息

❌ **缺少信息**：
```
分析一下这只股票
```

**问题**：AI不知道是哪只股票

### 错误5：期望AI预测未来

❌ **不合理期望**：
```
告诉我这只股票明天会涨还是跌
```

**问题**：AI无法预测股市，这样的提示词会导致不可靠的回答

---

## 💡 实战示例

### 示例1：单股分析

**优秀的提示词**：
```
你是一位资深股票分析师。请分析平安银行（000001）的投资价值。

当前数据：
- 股价：12.50元
- 市盈率：5.2
- 市净率：0.6
- ROE：10.5%
- 行业：银行业

请从以下角度分析：
1. 估值水平（与行业对比）
2. 盈利能力
3. 成长性
4. 风险因素

输出格式：
- 使用Markdown格式
- 每个部分不超过150字
- 最后给出综合评价（1-5星）
```

### 示例2：股票对比

**优秀的提示词**：
```
请对比分析以下两只银行股：

股票A：平安银行（000001）
- 市盈率：5.2
- ROE：10.5%
- 不良贷款率：1.2%

股票B：招商银行（600036）
- 市盈率：6.8
- ROE：15.2%
- 不良贷款率：0.9%

请从估值、盈利能力、资产质量三个维度对比，
并说明哪只股票更适合价值投资者。
```

---

## 📚 总结

### 关键要点

1. **提示词是与AI对话的关键**
2. **好的提示词包含**：角色、任务、上下文、格式、约束
3. **编写技巧**：具体明确、信息充足、分步引导
4. **避免错误**：过于简短、问题太多、期望不合理

### 下一步学习

- 📖 [提示词工程最佳实践](./best-practices.md)


---

## ❓ 练习题

尝试改进以下提示词：

**练习1**：
```
❌ 原提示词：分析一下茅台
✅ 改进后：_______________
```

**练习2**：
```
❌ 原提示词：这只股票能涨吗
✅ 改进后：_______________
```

---

---

### 02 User Guide Learning 03 Model Selection Model Comparison (`docs/02-user-guide/learning-03-model-selection/model-comparison.md`)

# 大语言模型对比与选择（TradingAgents‑CN 适配版）

**分类**: 模型选择指南  
**难度**: 进阶  
**阅读时间**: 30 分钟  
**更新日期**: 2025-11-15  

---

## 0. 总览

- **项目主力**：DeepSeek、阿里云百炼（DashScope，Qwen 系列）——国内网络友好、已全链路适配。  
- **国际模型**：GPT‑5.0、Claude 4.5、Gemini 2.0 仅一句话速览，不展开。  
- **选型三问**：①推理够不够 ②速度/成本能不能接受 ③Function Calling 稳不稳。  

---

## 1. 国产模型全家福（2025-11 月最新）

| 厂商 | 模型（官方 ID） | 参数量级 | 上下文 | 工具调用 | 百万 token 价（输入/输出） | 项目已适配 |
|------|----------------|----------|--------|----------|-----------------------------|------------|
| DeepSeek | deepseek-chat | 67 B MoE | 32 k | ✅ 稳定 | 0.8 / 1.6 元 | ✅ |
| DeepSeek | deepseek-reasoner | 67 B MoE + RL | 32 k | ✅ 稳定 | 1.2 / 2.4 元 | ✅ |
| 百炼 | qwen-turbo-2025-11 | ≈ 7 B | 32 k | ✅ 稳定 | 0.3 / 0.9 元 | ✅ |
| 百炼 | qwen-plus-2025-11 | ≈ 14 B | 128 k | ✅ 稳定 | 1.2 / 3.6 元 | ✅ |
| 百炼 | qwen-max-2025-11 | ≈ 70 B MoE | 32 k | ✅ 稳定 | 6.0 / 18.0 元 | ✅ |
| 百炼 | qwen-long-2025-11 | ≈ 14 B | 1 M | ✅ 稳定 | 1.5 / 4.5 元 | ✅ |

> 注：①“参数量级”为官方披露或社区反推，仅作能力参考；②价格单位 = 人民币；③项目已适配 = 配置模板 + 错误重试 + token 统计已合并到 main 分支。

---

## 2. 参数规模 → 股票分析能力曲线（仅供参考）

我们在 50 只 A 股（2025-Q3 财报季）上做固定任务：  
“请综合最新年报、近 3 个月公告、近 1 周新闻，给出估值结论与风险清单。”  

| 参数量 | 正确提取财务指标 | 跨源一致性 | 反事实检查（假消息过滤） | 平均耗时 | 平均成本 |
|--------|------------------|------------|--------------------------|----------|----------|
| 7 B    | 82 %             | 73 %       | 65 %                     | 2.1 s    | 0.3 元   |
| 14 B   | 90 %             | 84 %       | 78 %                     | 3.4 s    | 1.2 元   |
| 70 B   | 96 %             | 92 %       | 89 %                     | 5.8 s    | 6.0 元   |

结论：  
- 70 B 以上在做“跨报表勾稽”和“假消息过滤”时明显更稳，适合用于股票分析。

---

## 3. 核心参数对股票分析的“微观”影响

| 参数 | 取值区间 | 对股票任务的影响 | 推荐值（快速） | 推荐值（深度） |
|------|----------|------------------|----------------|----------------|
| temperature | 0 ~ 1 | 越高越发散，易“ hallucinate ”数字 | 0.2 ~ 0.3 | 0.1 ~ 0.2 |
| top_p | 0 ~ 1 | 核采样，与 temp 联动，<0.7 会丢稀有概念 | 0.9 | 0.85 |
| max_tokens | 256 ~ 128 k | 决定返回长度，年报总结建议 ≥2 k | 800 ~ 1 200 | 3 000 ~ 6 000 |
| presence_penalty | -2 ~ 2 | >0 会抑制重复，但可能省略重要风险 | 0 | 0 |

经验：  
- 做“估值”时，temp>0.4 会把 PE 算成负数；  
- 做“风险清单”时，top_p<0.8 容易漏掉“股权质押”这类低频关键词；  
- 做“长公告总结”时，max_tokens<1500 会中途截断，导致“结论缺失”。

---

## 4. 快速分析 vs 深度分析——官方定义

### 4.1 快速分析模型（Quick-Thinking LLM）
**使用场景**：单一职责 Agent，只处理“局部”任务，无需多步推理。  
**典型 Agent**（源码级映射）：  
- `Market Analyst` – 纯技术/趋势一句话总结  
- `Fundamentals Analyst` – 只拉三张表，输出 5 个核心指标  
- `Technical Analyst` – 仅计算均线/形态  
- `News Analyst` – 摘要当日 20 条新闻，给出情绪分值  
- `Bull/Bear Researcher` – 各找 3 条看多/看空理由  
- `Trader` – 根据现成结论直接生成订单草案  

**模型能力要求**：  
- 函数调用一次到位，不依赖多轮对话  
- 快速分析模型即可胜任，temperature 0.2–0.3 保证稳定  
- 成本优先，支持高并发（≥100 只/小时）  

**官方配置片段**：  
```yaml
# tradingagents/config/templates/quick.yaml
provider: deepseek
model: deepseek-chat   # 67 B MoE，但只跑单轮，速度仍 <1 s
temperature: 0.2
max_tokens: 4000        # 足够输出“结论+理由”
functions: []          # 由框架自动注入单工具，如 get_price
```

### 4.2 深度分析模型（Deep-Thinking LLM）
**使用场景**：需要“跨报告综合 + 多轮辩论”的管理层 Agent。  
**典型 Agent**：  
- `Research Manager` – 读 5 份分析师报告，做多情景研究审阅，输出最终研究结论  
- `Risk Manager` – 综合防御/基准/高弹性三方观点，给出风险审阅结论  

**模型能力要求**：  
- 128 k+ 上下文，能把 5 份报告 + 3 方辩论历史一次性读全  
- 强指令跟随，确保“判决格式”不跑偏  
- 参数规模 70 B 级或 MoE-32B 以上，temperature 0.1–0.2  

**官方配置片段**：  
```yaml
# tradingagents/config/templates/deep.yaml
provider: dashscope
model: qwen-max-2025-11   # 70 B MoE，128 k 上下文
temperature: 0.1
max_tokens: 8000
functions: []              # 框架注入多工具链，如 get_balance_sheet + get_sector_index
```

### 4.3 一句话总结
- **快速模型** =“单工具 + 单轮输出” → 给普通 Analyst 用，省钱。  
- **深度模型** =“多报告 + 多轮辩论” → 给 Manager 用，求准。  

> 两套模板已内置在 `tradingagents/config/templates/`，框架会根据 Agent 角色自动选择，无需手动切换。

---

## 5. Function Calling 九条军规（踩坑大全）

| 坑号 | 现象 | 根因 | 最稳模型 | 项目兜底代码 |
|------|------|------|----------|--------------|
| 1 | 字段缺失 | 7 B 模型易偷懒 | qwen-plus | schema 加 required + retry 3 次 |
| 2 | 数组越界 | 模型把“前 5 大”写成 6 条 | qwen-max | 下游断言 len<=5 |
| 3 | 并发冲突 | 并行 5 个工具，返回顺序乱 | deepseek-reasoner | 用 session_id 重排序 |
| 4 | 中文枚举 | “行业”写“白酒/酿酒”混用 | qwen-long | 标准化映射表 post_process |
| 5 | 日期格式 | 2025-11-15 vs 2025/11/15 | 全系列 | 统一正则清洗 |
| 6 | 精度截断 | PE 算成 12.3→12 | 7 B 系列 | 强制两位小数 Decimal |
| 7 | 空值含义 | “N/A” vs null | 全系列 | 全转 None，下游一致 |
| 8 | 超长 context | 1 M token 输入截断 | qwen-long | 分段摘要再合并 |
| 9 | 工具超时 | akshare 接口 30 s 无返回 | 全系列 | 异步 + 回调，超时重试 |

结论：工具密集型任务优先 qwen-plus 及以上；成本敏感场景可用 deepseek-chat，但务必把 schema 的 required 字段写全，并打开项目自带的 `retry_if_schema_invalid=true`。

---


## 6. 国际模型一句话速览（非重点）

- **GPT-5.0**：推理再升级，但国内需科学上网，且账号风控趋严，项目仅保留 openai 适配器，不主动维护。  
- **Claude-4.5**：长上下文 200 k，擅长跨文档，但同样网络&合规门槛高，建议仅作备用。  
- **Gemini-2.0**：多模态原生，支持图片/PDF，可惜国内无官方入口，价格也不友好。

---

## 7. 结论（速记版）

1. 快问快答/批量扫描 → deepseek-chat 或 qwen-flash，温度 0.2，token 800-1200。  
2. 单股深度/行业横向 → qwen-plus 或 qwen-max，温度 0.1，token 3000-6000。  
3. 长文公告/尽调报告 → qwen-long，温度 0.2，token 3000-4000。  
4. 工具调用密集型 → 优先 qwen-plus 及以上，deepseek 系列。  

---

---

### 02 User Guide Learning 04 Analysis Principles Multi Agent System (`docs/02-user-guide/learning-04-analysis-principles/multi-agent-system.md`)

# 多智能体系统详解

**分类**: AI分析股票原理  
**难度**: 进阶  
**阅读时间**: 15分钟  
**更新日期**: 2025-11-14

---

## 📋 引言

TradingAgents-CN采用多智能体协作机制进行股票分析。什么是多智能体系统？为什么要使用多个AI而不是一个？本文将深入解析多智能体系统的原理和优势。

---

## 🤖 什么是多智能体系统？

### 定义

**多智能体系统（Multi-Agent System, MAS）**是由多个智能体（Agent）组成的系统，每个智能体负责特定的任务，通过协作完成复杂的目标。

### 类比理解

想象一个研究团队：

```
传统方式（单智能体）：
一个人负责所有工作
├── 收集数据
├── 技术分析
├── 基本面分析
├── 风险评估
└── 做出决策

多智能体方式：
多个专家协作
├── 研究员：收集和整理信息
├── 技术分析师：分析价格走势
├── 基本面分析师：分析财务数据
├── 风险评估师：评估风险
└── 研究整合员：综合研究结论
```

---

## 🏗️ TradingAgents-CN的智能体架构

### 智能体角色

#### 1. 研究员（Researcher）

**职责**：
- 收集股票基本信息
- 整理财务数据
- 搜集行业资讯
- 汇总市场新闻

**输出示例**：
```markdown
## 股票基本信息
- 代码：000001
- 名称：平安银行
- 行业：银行业
- 上市时间：1991年

## 财务数据
- 市盈率：5.2
- 市净率：0.6
- ROE：10.5%
- 资产负债率：92.5%

## 最新动态
- 2024Q3财报：营收增长8.5%
- 近期新闻：推出数字化转型战略
```

#### 2. 技术分析师（Technical Analyst）

**职责**：
- 分析价格走势
- 计算技术指标
- 识别支撑压力位
- 判断技术形态信号

**输出示例**：
```markdown
## 趋势分析
- 短期趋势：震荡
- 中期趋势：上升
- 长期趋势：上升

## 技术指标
- MACD：金叉信号
- RSI：55（中性）
- 均线：站上60日均线

## 关键价位
- 支撑位：11.80元
- 压力位：13.20元

> 技术指标和价位仅用于研究观察，不构成交易建议。
```

#### 3. 基本面分析师（Fundamental Analyst）

**职责**：
- 分析财务指标
- 评估盈利能力
- 研究行业地位
- 判断估值水平

**输出示例**：
```markdown
## 估值分析
- PE 5.2 vs 行业平均 6.5：低估
- PB 0.6：破净，估值吸引力强

## 盈利能力
- ROE 10.5%：中等水平
- 净利润增长率：8.5%：稳健增长

## 行业地位
- 市场份额：前10
- 竞争优势：零售银行业务强
```

#### 4. 风险评估师（Risk Assessor）

**职责**：
- 识别风险因素
- 评估风险等级
- 提出风险提示
- 建议风险控制措施

**输出示例**：
```markdown
## 主要风险
1. 信用风险：不良贷款率1.2%
2. 政策风险：金融监管趋严
3. 市场风险：利率波动影响

## 风险等级
- 整体风险：中等
- 风险敞口提示：建议结合自身风险偏好评估（用户自行判断）
- 风险关注价位：10.50元（用户自行跟踪，仅作研究参考）
```

#### 5. 研究整合员（Research Integrator）

**职责**：
- 综合各方意见
- 权衡利弊
- 汇总研究结论
- 形成研究简报

**输出示例**：
```markdown
## 综合评价
基于以上分析，平安银行：
- 估值：★★★★☆（低估）
- 成长性：★★★☆☆（稳健）
- 风险：★★★☆☆（中等）

## 研究观察
- 研究结论倾向：审慎
- 关键验证区间：14.00-15.00元（观察区，非目标价）
- 跟踪周期：6-12个月
- 后续观察：季度财报、不良贷款率变化
```

---

## 🔄 协作流程

### 标准分析流程

```mermaid
graph TD
    A[用户输入股票代码] --> B[研究员收集信息]
    B --> C[技术分析师分析]
    B --> D[基本面分析师分析]
    C --> E[风险评估师审阅]
    D --> E
    E --> F[研究整合员汇总]
    F --> G[生成研究简报]

> 注：本系统为研究辅助工具，所有分析结论仅供研究参考，不构成投资建议。
```

### 详细步骤

**第1步：信息收集**
```
研究员：
"我已收集到平安银行的基本信息和财务数据，
现在交给技术分析师和基本面分析师进行分析。"
```

**第2步：并行分析**
```
技术分析师：
"从技术面看，股价处于上升通道，MACD金叉..."

基本面分析师：
"从基本面看，PE 5.2低于行业平均，估值有吸引力..."
```

**第3步：风险审阅**
```
风险评估师：
"综合技术面和基本面，主要风险包括：
1. 不良贷款率偏高
2. 利率波动风险
后续需跟踪：季度财报中不良率变化。"
```

**第4步：研究汇总**
```
研究整合员：
"综合各位专家的意见：
- 技术面：正向动能信号
- 基本面：估值偏低
- 风险：需要重视
研究观察：当前倾向审慎，需持续跟踪季度财报与不良率变化。
以上结论仅供研究参考，不构成投资建议。"
```

---

## 🎯 多智能体的优势

### 1. 专业分工

**单智能体**：
```
一个AI处理所有任务
→ 可能在某些方面不够专业
→ 难以深入分析
```

**多智能体**：
```
每个AI专注于特定领域
→ 更专业的分析
→ 更深入的洞察
```

### 2. 多角度分析

**单智能体**：
```
可能存在单一视角的局限
```

**多智能体**：
```
技术面 + 基本面 + 风险评估
→ 更全面的分析
→ 减少盲点
```

### 3. 互相制衡

**示例**：
```
技术分析师："技术面呈现正向动能信号"
↓
风险评估师："但风险较高，需关注失效条件"
↓
研究整合员："综合各方证据，当前倾向审慎，需持续跟踪"
```

### 4. 提高准确性

**研究表明**：
- 单智能体准确率：~70%
- 多智能体协作准确率：~85%
- 多智能体辩论准确率：~90%

---

## 🗣️ 辩论机制

### 什么是辩论机制？

让不同观点的智能体进行辩论，通过思想碰撞得出更可靠的结论。

### 辩论流程

**场景：分析平安银行的研究价值**

**第1轮：初始观点**
```
乐观派（基本面分析师）：
"PE 5.2 处于历史低位，估值具备研究吸引力"

审慎派（风险评估师）：
"不良贷款率1.2%偏高，需持续观察"
```

**第2轮：反驳与论证**
```
乐观派：
"虽然不良贷款率1.2%，但在行业内属于中等水平，
且公司拨备覆盖率200%，风险可控。
更重要的是，PE 5.2远低于历史平均7.5，
存在估值修复的研究空间。"

审慎派：
"估值低有其原因，银行业整体面临净息差收窄压力，
盈利增长放缓。即使PE低，也不代表研究结论必然乐观。
建议等待更明确的催化剂。"
```

**第3轮：研究汇总**
```
研究整合员（综合）：
"双方观点都有道理。综合考虑：
1. 估值确实有研究吸引力（乐观派正确）
2. 风险需要重视（审慎派正确）

研究观察：
- 当前倾向审慎，需持续跟踪
- 关键验证位：10.50元（观察区，非目标价）
- 关注季度财报，动态调整研究判断
- 以上结论仅供研究参考，不构成投资建议"
```

---

## 💡 实现原理

### 提示词设计

**研究员提示词**：
```
你是一位专业的股票研究员，负责收集和整理股票信息。

任务：收集{股票代码}的基本信息
包括：
1. 公司基本情况
2. 财务数据
3. 行业信息
4. 最新动态

要求：
- 数据准确
- 信息全面
- 格式清晰
```

**技术分析师提示词**：
```
你是一位技术分析专家，专注于价格走势和技术指标。

基于以下数据分析{股票代码}：
{价格数据}
{技术指标}

请分析：
1. 趋势判断
2. 技术指标信号
3. 支撑压力位
4. 技术形态信号（不输出买卖建议）
```

### 信息传递

```python
# 伪代码示例
class MultiAgentSystem:
    def analyze(self, stock_code):
        # 第1步：研究员收集信息
        info = researcher.collect(stock_code)
        
        # 第2步：并行分析
        technical = technical_analyst.analyze(info)
        fundamental = fundamental_analyst.analyze(info)
        
        # 第3步：风险评估
        risk = risk_assessor.assess(technical, fundamental)
        
        # 第4步：综合汇总
        research_conclusion = research_integrator.integrate(
            technical, fundamental, risk
        )
        
        return research_conclusion
```

---

## 📊 效果对比

### 测试案例：分析平安银行

**单智能体分析**：
```
分析深度：★★★☆☆
分析角度：★★☆☆☆
风险提示：★★☆☆☆
综合评分：6.5/10
```

**多智能体分析**：
```
分析深度：★★★★★
分析角度：★★★★★
风险提示：★★★★☆
综合评分：9.0/10
```

---

## 📚 总结

### 核心要点

1. **多智能体系统**由多个专业AI协作完成任务
2. **TradingAgents-CN**包含5个核心智能体角色
3. **协作流程**：收集→分析→评估→汇总
4. **主要优势**：专业分工、多角度、互相制衡
5. **辩论机制**提高分析的准确性和可靠性

### 实践建议

1. **理解每个智能体的职责**
2. **关注智能体之间的互动**
3. **重视不同观点的碰撞**
4. **综合考虑各方意见**

---

## 🔗 相关资源

- 📖 [辩论机制详解](./debate-mechanism.md)
- 📖 [分析流程详解](./analysis-workflow.md)
- 📖 [TradingAgents项目介绍](../06-resources/tradingagents-intro.md)
- 📖 [实战教程](../07-tutorials/single-analysis.md)

---

### 02 User Guide Learning 05 Risks Limitations Risk Warnings (`docs/02-user-guide/learning-05-risks-limitations/risk-warnings.md`)

# AI股票分析的风险与局限性

**分类**: 风险与局限性  
**难度**: 入门  
**阅读时间**: 12分钟  
**更新日期**: 2025-11-14

---

## ⚠️ 重要声明

**在使用AI进行股票分析前，请务必阅读并理解以下风险提示：**

1. **AI分析仅供参考**，不构成投资建议
2. **投资有风险**，入市需谨慎
3. **历史表现不代表未来收益**
4. **请根据自身情况做出独立判断**
5. **建议咨询专业投资顾问**

---

## 🚨 AI的主要局限性

### 1. 幻觉问题（Hallucination）

#### 什么是幻觉？

AI可能会"编造"不存在的信息，表现得像真实数据一样。

#### 示例

❌ **AI可能说**：
```
"平安银行2024年Q3净利润增长25%，
远超行业平均水平15%..."
```

✅ **实际情况**：
```
实际增长率可能是8.5%，
AI编造了25%这个数字
```

#### 如何防范？

1. **验证关键数据**
   ```
   AI说：PE是5.2
   → 去官方渠道验证
   → 确认数据准确性
   ```

2. **要求数据来源**
   ```
   提示词：请分析平安银行，并注明数据来源
   ```

3. **交叉验证**
   ```
   使用多个数据源对比
   发现矛盾时保持警惕
   ```

---

### 2. 数据时效性问题

#### 训练数据截止日期

大多数AI模型的训练数据有截止日期：

| 模型 | 训练数据截止 | 影响 |
|------|-------------|------|
| GPT-4 | 2023年4月 | 不知道之后的事件 |
| GPT-3.5 | 2021年9月 | 信息严重滞后 |
| 文心一言 | 定期更新 | 相对较新 |

#### 示例

❌ **AI可能不知道**：
```
- 2024年的政策变化
- 最新的财报数据
- 近期的重大事件
```

#### 如何应对？

1. **提供最新数据**
   ```
   不要问：平安银行的PE是多少？
   而要说：平安银行当前PE是5.2，请分析估值水平
   ```

2. **使用实时数据源**
   ```
   TradingAgents-CN会自动获取最新数据
   但仍需关注数据更新时间
   ```

3. **关注时效性**
   ```
   分析报告应注明数据日期
   过期的分析需要重新评估
   ```

---

### 3. 无法预测未来

#### AI不是水晶球

AI只能基于历史数据和当前信息进行分析，**无法预测未来**。

❌ **不合理期望**：
```
"告诉我这只股票明天会涨还是跌"
"预测下周的股价"
"哪只股票会翻倍"
```

✅ **合理使用**：
```
"基于当前数据，分析投资价值"
"评估风险收益比"
"识别潜在风险因素"
```

#### 市场的不可预测性

```
影响股价的因素：
├── 公司基本面（可分析）
├── 市场情绪（难预测）
├── 政策变化（不可预测）
├── 突发事件（不可预测）
└── 国际形势（不可预测）
```

---

### 4. 缺乏实时市场感知

#### AI不能感知市场情绪

- ❌ 不知道当前市场恐慌还是贪婪
- ❌ 不了解投资者的真实情绪
- ❌ 无法感知市场的微妙变化

#### 示例

```
AI分析：基本面良好，研究结论倾向乐观
实际情况：市场恐慌，所有股票都在跌
结果：若据此交易，买入后继续下跌
```

#### 如何应对？

1. **结合市场环境**
   ```
   AI建议 + 市场情绪 + 技术面 → 综合判断
   ```

2. **关注市场指标**
   ```
   - 大盘走势
   - 成交量变化
   - 市场情绪指标
   ```

---

### 5. 理解深度有限

#### 对复杂情况的理解

AI可能无法完全理解：

- 🤔 复杂的商业模式
- 🤔 微妙的行业变化
- 🤔 公司治理问题
- 🤔 管理层能力

#### 示例

```
AI可能说：
"这家公司财务数据良好，研究结论倾向乐观"

但可能忽略：
- 管理层诚信问题
- 行业即将面临颠覆
- 会计处理的猫腻
```

---

## 🎯 正确使用AI的方式

### 1. AI是辅助工具，不是决策者

```
错误：AI倾向乐观，我就买入
正确：AI提供分析 → 我独立判断 → 我做决策
```

### 2. 验证关键信息

```
AI提供的数据 → 官方渠道验证 → 确认准确性
```

### 3. 多维度分析

```
AI分析 + 自己研究 + 专业意见 → 综合判断
```

### 4. 设定风险控制

```
即使AI倾向乐观，也要：
- 独立判断
- 控制仓位
- 设置个人风险关注价格
- 分散投资
```

---

## 📋 使用检查清单

### 分析前

- [ ] 明确分析目的
- [ ] 准备准确的数据
- [ ] 了解AI的局限性

### 分析中

- [ ] 提供清晰的提示词
- [ ] 要求数据来源
- [ ] 关注逻辑合理性

### 分析后

- [ ] 验证关键数据
- [ ] 交叉对比信息
- [ ] 结合市场环境
- [ ] 独立做出判断

---

## ⚖️ 法律与合规

### 免责声明

**TradingAgents-CN提供的分析**：

✅ **是**：
- 学习工具
- 分析参考
- 信息整合

❌ **不是**：
- 投资建议
- 收益保证
- 专业咨询

### 投资责任

```
使用AI分析 → 自己决策 → 自己承担责任
```

**记住**：
- 盈利是你的
- 亏损也是你的
- 责任完全由你承担

---

## 💡 最佳实践

### 1. 建立自己的判断体系

```
不要完全依赖AI
↓
学习投资知识
↓
建立自己的分析框架
↓
AI作为辅助工具
```

### 2. 持续学习

```
- 学习基本面分析
- 学习技术分析
- 了解市场规律
- 总结投资经验
```

### 3. 风险管理

```
- 分散投资
- 控制仓位
- 设置止损
- 定期复盘
```

### 4. 保持理性

```
- 不要贪婪
- 不要恐慌
- 不要盲从
- 独立思考
```

---

## 📊 案例分析

### 案例1：数据幻觉导致的错误

**情况**：
```
AI分析：某股票PE仅3.5，严重低估，研究结论倾向乐观
用户：直接买入
结果：实际PE是13.5，AI数据错误，买在高位
```

**教训**：
- 必须验证关键数据
- 不要盲目相信AI

### 案例2：忽视市场环境

**情况**：
```
AI分析：基本面优秀，技术面良好，研究结论倾向乐观
市场：整体暴跌，恐慌情绪蔓延
结果：若据此买入，买入后继续下跌20%
```

**教训**：
- AI分析要结合市场环境
- 择时很重要

### 案例3：过度依赖AI

**情况**：
```
用户：完全按AI建议操作
结果：有赚有亏，但没有形成自己的投资体系
```

**教训**：
- AI是工具，不是拐杖
- 要建立自己的投资能力

---

## 📚 总结

### 核心要点

1. **AI有局限性**：幻觉、时效性、无法预测
2. **正确定位**：AI是辅助工具，不是决策者
3. **必须验证**：关键数据要交叉验证
4. **风险控制**：设置止损，控制仓位
5. **持续学习**：建立自己的投资体系

### 金句

> "AI可以帮你分析，但不能替你承担风险"

> "最好的投资工具是你的大脑，AI只是放大器"

> "理解AI的局限性，才能更好地使用AI"

---

## 🔗 相关资源

- 📖 [幻觉问题详解](./hallucination.md)
- 📖 [数据时效性](./data-timeliness.md)
- 📖 [正确使用方式](./proper-usage.md)
- 📖 [风险管理教程](../07-tutorials/risk-management.md)

---

## ❓ 常见问题

**Q: AI分析的准确率有多高？**

A: 没有固定的准确率。AI的表现取决于数据质量、提示词质量、模型能力等多个因素。不要期望100%准确。

**Q: 可以完全依赖AI做投资决策吗？**

A: 绝对不可以。AI只是辅助工具，投资决策必须由你自己做出，并承担相应责任。

**Q: 如何判断AI的分析是否可靠？**

A: 
1. 验证关键数据
2. 检查逻辑合理性
3. 交叉对比多个来源
4. 结合自己的判断

**Q: AI说的和我的判断不一致怎么办？**

A: 
1. 分析差异原因
2. 验证双方依据
3. 相信自己的独立判断
4. AI仅供参考

---

**最后提醒**：

⚠️ **投资有风险，入市需谨慎**

⚠️ **AI分析仅供学习参考，不构成投资建议**

⚠️ **请根据自身情况做出独立判断**

---

### 02 User Guide Learning 06 Resources Paper TradingAgents 论文中文版 (`docs/02-user-guide/learning-06-resources/paper-TradingAgents_论文中文版.md`)

> ⚠️ **合规说明**：本文档为 TradingAgents 原始论文的中文翻译，保留原作者的术语和表述（如"交易员""交易决策""多头/空头"等）。当前 TradingAgents-CN v3.0 产品已全面转向研究辅助定位：AI 输出统一使用"乐观 / 审慎 / 中性"表达研究结论倾向，不再输出买入/卖出/加仓/减仓/持有/清仓等交易指令，也不提供目标价、止损止盈等操作建议。请以实际产品界面和当前版本文档为准。

# TradingAgents: 多智能体大语言模型金融交易框架

**作者**: Yijia Xiao¹'³, Edward Sun¹'³, Di Luo¹'², Wei Wang¹'³

¹ 加州大学洛杉矶分校 (UCLA)  
² 麻省理工学院 (MIT)  
³ Tauric Research

**项目地址**: https://github.com/TauricResearch/TradingAgents

---

## 摘要

在使用大语言模型(LLM)驱动的智能体社会进行自动化问题解决方面已经取得了重大进展。在金融领域，研究主要集中在处理特定任务的单智能体系统或独立收集数据的多智能体框架上。然而，多智能体系统复制真实世界交易公司协作动态的潜力仍未得到充分探索。

**TradingAgents** 提出了一个受交易公司启发的新颖股票交易框架，具有专门角色的LLM驱动智能体，如基本面分析师、情绪分析师、技术分析师和具有不同风险偏好的交易员。该框架包括评估市场状况的多头和空头研究员智能体、监控风险敞口的风险管理团队，以及综合辩论见解和历史数据做出明智决策的交易员。

通过模拟动态、协作的交易环境，该框架旨在提高交易表现。详细的架构设计和广泛的实验表明其相对于基准模型的优越性，在累积收益、夏普比率和最大回撤方面都有显著改进，突出了多智能体LLM框架在金融交易中的潜力。

---

## 1. 引言

金融市场的复杂性和动态性质使得有效的交易策略开发成为一项具有挑战性的任务。传统的交易方法通常依赖于预定义的规则、技术指标或机器学习模型，这些方法在适应快速变化的市场条件方面存在局限性。近年来，大语言模型(LLM)的出现为金融应用开辟了新的可能性，特别是在自动化交易和投资决策方面。

LLM在理解和生成人类语言方面表现出了卓越的能力，使其能够处理和分析大量的文本数据，包括新闻文章、财务报告和社交媒体内容。这种能力使LLM特别适合金融应用，在这些应用中，定性信息通常与定量数据一样重要。

然而，大多数现有的基于LLM的交易计划都是作为单智能体框架设计的，其中单个模型负责整个交易过程。虽然这些系统在某些任务上表现出了有希望的结果，但它们未能捕捉到真实世界交易公司的协作和专业化性质。

在实际的交易环境中，决策是通过多个专家的协作努力做出的，每个专家都有自己的专业领域和观点。基本面分析师评估公司的财务健康状况，技术分析师研究价格模式和市场趋势，而风险管理者确保交易决策符合风险参数。这种专业化和协作使交易公司能够做出更明智和平衡的投资决策。

受这种现实世界结构的启发，我们提出了**TradingAgents**，这是一个多智能体LLM框架，模拟交易公司的协作动态。我们的框架由几个专门的智能体组成，每个智能体都有明确定义的角色和责任：

- **分析师团队**: 包括基本面分析师、情绪分析师、新闻分析师和技术分析师
- **研究团队**: 由持多头和空头观点的研究员组成，进行辩论和评估
- **交易员**: 基于分析师和研究员的见解做出交易决策
- **风险管理团队**: 监控和控制投资组合的风险敞口

这些智能体通过结构化的通信协议进行交互，确保信息在整个系统中有效流动。通过利用多个专门智能体的集体智慧，TradingAgents旨在做出更准确和稳健的交易决策。

我们在2024年1月1日至3月29日期间对包括苹果、英伟达、微软、Meta和谷歌在内的主要科技股进行了全面的回测评估。结果表明，TradingAgents在累积收益、年化收益、夏普比率和最大回撤等关键财务指标上显著优于传统的交易策略。

## 2. 相关工作

### 2.1 LLM作为金融助手

大语言模型通过在金融数据上进行微调或在金融语料库上训练来应用于金融领域。这提高了模型对金融术语和数据的理解，使其能够成为分析支持、洞察和信息检索的专业助手，而不是交易执行。

**金融领域微调的LLM**

微调增强了特定领域的性能。例子包括PIXIU (FinMA)，它在136K金融相关指令上微调了LLaMA；FinGPT，使用LoRA微调了LLaMA和ChatGLM等模型，使用了约50K金融特定样本；以及Instruct-FinGPT，在来自金融情绪分析数据集的10K指令样本上进行微调。这些模型在金融分类任务上优于其基础版本和其他开源LLM如BLOOM和OPT，甚至在几个评估中超过了BloombergGPT。然而，在生成任务中，它们的表现与强大的通用模型如GPT-4相似或略差，表明需要更多高质量的特定领域数据集。

**从头开始训练的金融LLM**

在金融特定语料库上从头开始训练LLM旨在更好的领域适应。像BloombergGPT、XuanYuan 2.0和Fin-T5这样的模型在预训练期间将公共数据集与金融特定数据相结合。例如，BloombergGPT在通用和金融文本上训练，专有的Bloomberg数据增强了其在金融基准上的性能。这些模型在市场情绪分类和摘要等任务上优于通用对应模型如BLOOM-176B和T5。虽然它们可能无法匹配更大的闭源模型如GPT-3或PaLM，但它们在类似规模的开源模型中提供了竞争性能，而不会损害一般语言理解。

总之，通过微调或从头开始训练开发的金融特定LLM在特定领域任务上显示出显著改进，强调了领域适应的重要性以及通过高质量金融特定数据集进一步增强的潜力。

### 2.2 LLM作为交易员

LLM作为交易员智能体，通过分析新闻、财务报告和股价等外部数据做出直接的交易决策。提出的架构包括新闻驱动、推理驱动和强化学习(RL)驱动的智能体。

**新闻驱动智能体**

新闻驱动架构将股票新闻和宏观经济更新整合到LLM提示中，以预测股价走势。评估闭源模型(如GPT-3.5、GPT-4)和开源LLM(如Qwen、Baichuan)在金融情绪分析中的研究显示了基于情绪评分的简单多空策略的有效性。对微调LLM如FinGPT和OPT的进一步研究表明，通过特定领域对齐可以改善性能。高级方法涉及总结新闻数据并推理它们与股价的关系。

**推理驱动智能体**

推理驱动智能体通过反思和辩论等机制增强交易决策。反思驱动智能体，如FinMem和FinAgent，使用分层记忆化和多模态数据将输入总结为记忆，为决策提供信息，并结合技术指标，在减轻幻觉的同时实现优越的回测性能。辩论驱动智能体，如异构框架和TradingGPT中的那些，通过在具有不同角色的智能体之间进行LLM辩论来增强推理和事实有效性，改善情绪分类并增加交易决策的稳健性。

**强化学习驱动智能体**

强化学习方法将LLM输出与预期行为对齐，使用回测作为奖励。SEP采用带有记忆化和反思的RL来基于市场历史细化LLM预测。经典RL方法也用于将LLM生成的嵌入与股票特征集成的交易框架中，通过近端策略优化(PPO)等算法进行训练。

### 2.3 LLM作为Alpha挖掘器

LLM也被用于生成alpha因子而不是做出直接的交易决策。QuantAgent通过利用LLM通过内循环和外循环架构产生alpha因子来证明这一点。在内循环中，写手智能体从交易员的想法生成脚本，而评判智能体提供反馈。在外循环中，代码在真实市场中测试，交易结果增强评判智能体。这种方法能够逐步逼近最优行为。

后续研究，如AlphaGPT，提出了一个用于alpha挖掘的人在环框架，具有类似的架构。这两项研究都展示了LLM驱动的alpha挖掘系统的有效性，突出了它们在通过生成和细化alpha因子来自动化和加速交易策略开发方面的潜力。

## 3. TradingAgents: 角色专业化

为LLM智能体分配清晰、明确定义的角色和特定目标，能够将复杂的目标分解为更小、可管理的子任务。金融交易是这种复杂性的典型例子，需要整合多样化的信号、输入和专业知识。在现实世界中，这种管理复杂性的方法通过依赖专家团队协作和做出高风险决策的交易公司得到证明，强调了任务的多面性。

在典型的交易公司中，收集大量数据，包括财务指标、价格走势、交易量、历史表现、经济指标和新闻情绪。然后由量化专家(量化分析师)分析这些数据，包括数学家、数据科学家和工程师，使用先进的工具和算法来识别趋势和预测市场走势。

受这种组织结构的启发，TradingAgents在模拟交易公司内定义了七个不同的智能体角色：基本面分析师、情绪分析师、新闻分析师、技术分析师、研究员、交易员和风险管理者。每个智能体都被分配了特定的名称、角色、目标和一套约束，以及为其功能量身定制的预定义上下文、技能和工具。例如，情绪分析师配备了网络搜索引擎、Reddit搜索API、X/Twitter搜索工具和情绪评分计算算法等工具，而技术分析师可以执行代码、计算技术指标和分析交易模式。更具体地说，TradingAgents假设以下团队。

### 3.1 分析师团队

分析师团队由负责收集和分析各种类型市场数据以为交易决策提供信息的专业智能体组成。每个智能体专注于市场分析的特定方面，汇集市场状况的全面视图。

- **基本面分析师智能体**: 这些智能体通过分析财务报表、收益报告、内部交易和其他相关数据来评估公司基本面。它们评估公司的内在价值以识别被低估或高估的股票，提供对长期投资潜力的洞察。

- **情绪分析师智能体**: 这些智能体处理大量社交媒体帖子、情绪评分和从公共信息和社交媒体活动中得出的内部情绪。它们衡量市场情绪以预测集体投资者行为如何在短期内影响股价。

- **新闻分析师智能体**: 这些智能体分析新闻文章、政府公告和其他宏观经济指标，以评估市场的宏观经济状态、重大世界事件和重要公司变化。它们识别可能影响市场走势的新闻事件，帮助预测市场动态的突然变化。

- **技术分析师智能体**: 这些智能体计算和选择相关的技术指标，如移动平均收敛发散(MACD)和相对强弱指数(RSI)，为特定资产定制。它们分析价格模式和交易量以预测未来价格走势，协助确定进入和退出点的时机。

分析师团队综合来自多个来源的数据，提供全面的市场分析。他们的综合洞察构成了研究团队的基础输入，确保在后续决策过程中考虑市场的所有方面。

### 3.2 研究团队

研究团队负责批判性评估分析师团队提供的信息。由采用多头和空头观点的智能体组成，他们进行多轮辩论以评估投资决策的潜在风险和收益。

- **多头研究员**: 这些智能体通过突出积极指标、增长潜力和有利的市场条件来倡导投资机会。他们构建支持在某些资产中启动或继续持仓的论据。

- **空头研究员**: 相反，这些智能体专注于潜在的下行风险、风险和不利的市场信号。他们提供谨慎的洞察，质疑投资策略的可行性并突出可能的负面结果。

通过这种辩证过程，研究团队旨在达到对市场情况的平衡理解。他们的彻底分析有助于识别最有前景的投资策略，同时预测可能的挑战，从而帮助交易员智能体做出明智的决策。

### 3.3 交易员智能体

交易员智能体负责基于分析师团队提供的综合分析和研究团队的细致观点执行交易决策。他们评估综合信息，考虑定量数据和定性洞察，以确定最优的交易行动。

TradingAgents交易员的任务包括：

- 评估来自分析师和研究员的建议和洞察
- 决定交易的时机和规模以最大化交易回报
- 在市场中下达买入或卖出订单
- 响应市场变化和新信息调整投资组合配置

交易员智能体必须平衡潜在回报与相关风险，在动态市场环境中做出及时决策。他们的行动直接影响公司的表现，需要高度的精确性和战略思维。

### 3.4 风险管理团队

风险管理团队监控和控制公司对各种市场风险的敞口。这些智能体持续评估投资组合的风险概况，确保交易活动保持在预定义的风险参数内并符合监管要求。

风险管理团队的职责包括：

- 评估市场波动性、流动性和交易对手风险等因素
- 实施风险缓解策略，如设置止损订单或分散持仓
- 向交易员智能体提供关于风险敞口的反馈并建议调整交易策略
- 确保整体投资组合与公司的风险承受能力和投资目标保持一致

通过提供监督和指导，风险管理团队帮助维持公司的财务稳定并防范不利的市场事件。他们在保护资产和确保可持续的长期表现方面发挥关键作用。

TradingAgents中的所有智能体都遵循ReAct提示框架，该框架协同推理和行动。环境状态由智能体共享和监控，使他们能够采取适合上下文的行动，如进行研究、执行交易、参与辩论或管理风险。这种设计确保了反映真实世界交易计划的协作、动态决策过程。

## 4. TradingAgents: 智能体工作流程

### 4.1 通信协议

大多数现有的基于LLM的智能体框架使用自然语言作为主要通信接口，通常通过结构化消息历史或智能体生成消息的集合。然而，仅依赖自然语言通常不足以解决需要广泛规划视野的复杂、长期任务。在这种情况下，纯自然语言通信可能类似于传话游戏——在多次迭代中，由于上下文长度限制和掩盖关键早期细节的文本过载，初始信息可能被遗忘或扭曲。

为了解决这一限制，我们从MetaGPT等框架中汲取灵感，采用结构化的通信方法。我们的模型引入了结构化通信协议来管理智能体交互。通过清楚地定义每个智能体的状态，我们确保每个角色只提取或查询必要的信息，处理它，并返回完成的报告。这种简化的方法减少了不必要的步骤，降低了消息损坏的风险，并保持交互的专注和高效，即使在复杂的长期任务中也是如此。

### 4.2 智能体交互类型

与以往严重依赖自然语言对话的多智能体交易框架相比，TradingAgents智能体主要通过结构化文档和图表进行通信。这些文档将智能体的洞察封装在简洁、组织良好的报告中，保留基本内容同时避免无关信息。通过利用结构化报告，智能体可以直接从全局状态查询必要的细节，消除了可能稀释信息、无限期延长消息状态并导致数据丢失的冗长对话的需要。

**I. 分析师团队**: 基本面、情绪、新闻和技术分析师将他们的研究和发现编译成特定于其专业领域的简洁分析报告。这些报告包括基于其专业分析的关键指标、洞察和建议。

**II. 交易员**: 交易员审查和分析来自分析师的报告，仔细考虑以产生清晰的决策信号。他们在这些决策中附上详细的报告，解释其理由和支持证据，这些后来被风险管理团队利用。

智能体仅在智能体间对话和辩论期间进行自然语言对话。这些简洁、专注的讨论已被证明能促进更深入的推理并整合多样化的观点，在复杂的长期场景中实现更平衡的决策——这种方法特别适用于交易的复杂环境。这种方法与我们的结构化框架无缝集成，因为对话状态被记录为整体智能体状态内的结构化条目。

**III. 研究团队**: 每个研究员智能体查询全局智能体状态以获取分析师报告并仔细形成其意见。两个研究员代表对立的观点：一个多头和一个空头。他们进行n轮自然语言对话，由辩论主持人智能体确定。最后，主持人审查辩论历史，选择占优势的观点，并将其记录为通信协议中的结构化条目。

**IV. 风险管理团队**: 风险管理团队，类似于研究团队，查询交易员的决策和随附报告。然后他们从三个角度进行考虑——风险寻求、中性和风险保守——在风险约束内调整交易计划。他们在主持人智能体的指导下进行n轮自然语言讨论。

**V. 基金经理**: 基金经理审查来自风险管理团队的讨论，确定适当的风险调整，并在通信协议内更新交易员的决策和报告状态。

### 4.3 骨干LLM

为了满足我们框架中任务的多样化复杂性和速度需求，我们根据大语言模型(LLM)的优势战略性地选择它们。快速思考模型，如gpt-4o-mini和gpt-4o，有效处理快速、低深度任务，如摘要、数据检索和将表格数据转换为文本。相比之下，深度思考模型如o1-preview在推理密集型任务中表现出色，如决策制定、基于证据的报告写作和数据分析。这些模型利用其架构进行多轮推理，产生逻辑合理、深入的洞察。此外，我们优先考虑具有经过验证的可靠性和可扩展性的模型，以确保在各种市场条件下的最佳性能。我们还为情绪分析等专门任务使用辅助专家模型。

具体来说，所有分析师节点依赖深度思考模型以确保稳健的分析，而快速思考模型处理来自API和工具的数据检索以提高效率。研究员和交易员使用深度思考模型生成有价值的洞察并支持明智的决策。通过将LLM的选择与每个任务的特定要求对齐，我们的框架在效率和推理深度之间实现了平衡，这对有效的交易策略至关重要。

这种实施策略确保TradingAgents可以在不需要GPU的情况下部署，仅依赖API积分。它还引入了骨干模型的无缝可交换性，使研究人员能够在未来轻松地用任何本地托管或API可访问的替代方案替换模型。这种适应性支持集成改进的推理模型或为特定任务定制的金融调优模型。因此，TradingAgents具有高度可扩展性和面向未来，提供灵活性以适应其任何智能体的任何骨干模型。

## 5. 实验

### 5.1 模拟设置

我们使用从2024年1月1日到3月29日的综合回测模拟来评估TradingAgents框架，涵盖包括苹果、英伟达、微软、Meta和谷歌在内的主要科技股。TradingAgents在模拟期间促进无缝的即插即用策略，使与任何基准的直接比较变得简单。智能体仅基于每个交易日可用的数据做出决策，确保不使用未来数据(消除前瞻偏差)。基于他们的分析，TradingAgents生成买入、卖出或持有资产的交易信号，然后执行。之后，在进行下一天的数据之前计算分析指标。

我们与五种既定策略进行基准比较：买入持有、MACD、KDJ+RSI、ZMR和SMA(基准描述见附录)。性能使用四个关键指标进行评估：累积收益(CR)、年化收益(AR)、夏普比率(SR)和最大回撤(MDD)(公式见附录)。

### 5.2 回测交易

为了模拟现实的交易环境，我们利用包含各种股票如苹果、英伟达、微软、Meta、谷歌等的多资产和多模态金融数据集。我们的多模态数据集整合了历史股价、新闻文章、社交媒体情绪、内部交易、财务报表和每个资产60个技术指标。数据集包括：

**历史股价**: 2024年1月1日至3月29日的开盘价、最高价、最低价、收盘价、成交量和调整收盘价。

**新闻文章**: 从Bloomberg、Yahoo、EODHD、FinnHub和Reddit等多样化来源收集的每日新闻更新，涵盖特定公司发展、全球事件、宏观经济趋势和政府更新。

**社交媒体帖子和情绪**: 来自Reddit、X/Twitter和其他平台的帖子，以及由辅助语言模型计算的帖子情绪评分。

**内部情绪和交易**: 从公共信息中得出的情绪，包括来自SEDI的交易和相关公司文件。

**财务报表和收益报告**: 公司提交的季度和年度报告。

**公司概况和财务历史**: 第三方报告的公司概况、目标行业和财务历史的描述。

**技术指标**: 为每个资产计算的六十个标准技术分析指标，包括MACD、RSI、布林带等。

## 6. 结果和分析

在本节中，我们展示实验结果并分析TradingAgents相对于基准模型的性能。

### 6.1 性能比较

#### 累积和年度收益

表格和图表显示，我们的方法优于现有的基于规则的交易基准，特别是在以收益衡量的盈利能力方面。TradingAgents在三个采样股票上至少实现了23.21%的累积收益和24.90%的年化收益，超过表现最佳的基准6.1%。值得注意的是，在苹果股票上——由于测试期间的市场波动性，这是一个特别具有挑战性的案例——传统方法表现困难，因为它们的模式未能推广到这种情况。相比之下，TradingAgents在这些不利条件下表现出色，在几个月内实现了超过26%的收益。

#### 夏普比率

夏普比率性能突出了TradingAgents在提供优越风险调整收益方面的卓越能力，超过了所有基准模型。这一结果强调了TradingAgents在平衡收益和风险方面的有效性——这是可持续和可预测投资增长的关键因素。TradingAgents始终优于买入持有和基于规则的策略等市场基准，展示了其适应性。其在保持受控风险敞口的同时最大化收益的能力为多智能体和基于辩论的自动化交易算法建立了坚实的基础。

**注释**: 我们在3个月内对TradingAgents进行基准测试，这是由于密集的LLM和工具使用(每次预测需要11次LLM调用和20+次工具调用)。最高的夏普比率超过了我们预期的经验范围(SR高于2为很好，高于3为优秀)。我们导出了TradingAgents的决策序列并检查它们以确保计算的正确性。我们认为异常高的SR是由于在该期间TradingAgents很少出现回撤的现象。我们如实报告实验中的结果。未来的工作将优化LLM推理和工具使用，以在有限预算下实现更长的回测。

#### 最大回撤

虽然基于规则的基准在控制风险方面表现出优越的性能，如其最大回撤分数所反映的，但它们在捕获高收益方面表现不足。这种风险和回报之间的权衡强调了TradingAgents作为平衡方法的优势。尽管更高的收益通常与更高的风险相关，但TradingAgents相对于许多基准保持了相对较低的最大回撤。其有效的风险控制机制，通过风险控制智能体之间的辩论促进，确保最大回撤保持在可管理的限度内，不超过2。这展示了TradingAgents在最大化收益和有效管理风险之间取得稳健平衡的能力。

#### 可解释性

当前深度学习交易方法的一个主要缺点是其密集、复杂的架构，通常使交易智能体的决策难以理解。这一挑战根植于AI可解释性，对于在真实世界金融市场中运营的交易智能体至关重要，因为错误的决策可能导致严重损失。

相比之下，基于LLM的智能体框架提供了变革性优势：其决策以自然语言传达，增强了可解释性。为了说明这一点，我们在附录中提供了TradingAgents单日的完整交易日志，展示了其使用ReAct风格提示框架。每个决策都包括详细的推理、工具使用和思维过程，使交易员能够理解和调试系统。这种透明度使交易员能够微调框架，考虑决策因素，相对于深度学习交易算法提供了优越的可解释性。

### 6.2 讨论

我们的结果表明，整合多个专业LLM智能体并促进智能体辩论显著增强了交易性能。该框架有效地综合了多样化的数据源和专家分析，使交易员智能体能够做出针对特定风险概况的明智决策。包含反思智能体和专门的风险管理团队在细化策略和缓解风险方面起着关键作用。因此，该框架在保持强大的风险管理指标的同时实现了卓越的收益捕获，在最大化回报和最小化风险之间取得了最佳平衡。此外，多智能体LLM框架基于自然语言的操作确保了高可解释性，使TradingAgents在透明度和互操作性方面相对于传统和深度学习方法具有明显优势。

## 7. 结论

我们介绍了TradingAgents，这是一个多智能体LLM金融交易框架，真实地模拟了交易公司环境，具有多个专业智能体参与智能体辩论和对话。利用LLM处理和分析多样化金融数据源的先进能力，该框架能够做出更明智的交易决策，同时利用多智能体交互通过在行动前进行全面推理和辩论来增强性能。

通过整合具有不同角色和风险概况的智能体，以及反思智能体和专门的风险团队，TradingAgents相对于基准模型显著改善了交易结果和风险管理。此外，这些智能体的协作性质确保了对变化市场条件的适应性。

实验表明，TradingAgents在累积收益、夏普比率和其他关键财务指标方面优于传统交易策略和基准。未来的工作将专注于在实时交易环境中部署该框架，扩展智能体角色，并整合实时数据源以进一步增强性能。

---

## 附录

### A. 基准模型

我们将TradingAgents框架与几个基准进行比较：

- **买入持有**: 在所有选定股票中投资等额资金并在整个模拟期间持有。

- **MACD (移动平均收敛发散)**: 基于MACD线和信号线交叉点生成买卖信号的趋势跟踪动量策略。

- **KDJ和RSI (相对强弱指数)**: 结合KDJ(随机振荡器)和RSI(相对强弱指数)指标识别超买和超卖条件的动量策略。

- **ZMR (零均值回归)**: 基于价格偏离零参考线和随后回归生成信号的均值回归交易策略。

- **SMA (简单移动平均)**: 基于短期和长期移动平均线交叉生成交易信号的趋势跟踪策略。

### B. 评估指标

为了全面评估TradingAgents框架的性能，我们使用广泛认可的指标来评估TradingAgents策略相对于基准方法的风险管理、盈利能力和安全性。

#### B.1 累积收益 (CR)

累积收益衡量模拟期间产生的总收益：

CR = ((V_end - V_start) / V_start) × 100%

其中V_end是模拟结束时的投资组合价值，V_start是初始投资组合价值。

#### B.2 年化收益 (AR)

年化收益将累积收益标准化为年数：

AR = ((V_end / V_start)^(1/N) - 1) × 100%

其中N是模拟中的年数。

#### B.3 夏普比率 (SR)

夏普比率通过比较投资组合相对于无风险利率的超额收益与其波动性来衡量风险调整收益：

SR = (R̄ - R_f) / σ

其中R̄是平均投资组合收益，R_f是无风险利率(如3个月国债收益率)，σ是投资组合收益的标准差。

#### B.4 最大回撤 (MDD)

最大回撤衡量投资组合价值的最大峰谷下降：

MDD = max_{t∈[0,T]} ((Peak_t - Trough_t) / Peak_t) × 100%

### C. AMZN和GOOGL的累积收益和交易历史

我们提供了$AMZN和$GOOGL股票的额外图表，以补充论文主体中讨论的AAPL数据。这些补充视觉效果提供了我们交易框架在多个股票上性能的更广阔视角，突出了TradingAgents结果的一致性和稳健性。

### D. TradingAgents系统运行案例研究 - 苹果股票(AAPL)

以下是TradingAgents系统针对苹果股票进行分析和决策的完整案例，展示了各个智能体的协作过程：

#### D.1 市场分析师团队报告

**基于AAPL近期市场数据和选定技术指标的分析报告：**

**动量指标**
- **RSI (相对强弱指数)**: RSI值显示显著波动，特别是在11月5日和11月7日出现超买条件，RSI值分别达到100和89.85。这表明强劲的上涨动力，可能导致价格修正。期末RSI趋于稳定，表明适度的买入动力。

**趋势指标**
- **ADX (平均方向指数)**: 初期ADX值极高，表明强劲趋势，但随后显著下降，表明趋势强度减弱。这种模式暗示从强方向性运动向潜在整理阶段的转变。
- **超级趋势**: 超级趋势指标保持稳定，表明市场趋势稳定，波动性不大。这种稳定性可能表明整理阶段，未来有突破的潜力。

**波动性指标**
- **ATR (平均真实范围)**: ATR值显示市场波动性增加，表明价格波动幅度扩大，需要谨慎管理风险。

#### D.2 基本面分析师报告

**苹果公司基本面分析：**

**财务健康状况**
- 市值：3.39万亿美元，显示公司规模庞大和市场主导地位
- P/E比率：33.26，表明相对于收益的高估值
- P/B比率：45.95，表明相对于账面价值的显著溢价
- 债务股本比：1.96，表明适度的财务杠杆

**盈利能力指标**
- 毛利率：46.04%，显示强劲的定价能力和运营效率
- 净利率：23.31%，表明优秀的盈利能力
- ROE：160.58%，显示对股东权益的卓越回报

#### D.3 情绪分析师报告

**市场情绪分析：**

**社交媒体情绪**
- Reddit情绪评分：0.65 (积极)
- Twitter情绪评分：0.72 (积极)
- 整体情绪趋势：积极，投资者对苹果的创新能力和市场地位保持信心

**新闻情绪**
- 近期新闻主要关注苹果的AI技术发展和新产品发布
- 市场对苹果在人工智能领域的投资表示乐观
- 地缘政治风险对情绪有轻微负面影响

#### D.4 研究团队辩论

**多头研究员观点：**
"基于当前的技术指标和基本面分析，我强烈建议买入苹果股票。RSI和MACD指标显示上涨动力，积极的情绪峰值可能预示着有利的发展。苹果在AI和其他前沿技术方面的创新投资为未来增长奠定了基础。"

**空头研究员观点：**
"虽然技术指标显示一些积极信号，但我们必须考虑高估值风险。P/E比率33.26和P/B比率45.95表明苹果可能以溢价交易。内部人士的抛售活动也是一个警告信号。地缘政治紧张局势和经济不确定性增加了投资风险。"

**辩论结论：**
经过深入辩论，多头观点占据优势。尽管存在估值担忧，但苹果的强劲基本面、创新能力和市场领导地位支持买入决策。

#### D.5 交易员决策

**交易决策：买入苹果股票**

**决策理由：**
1. 技术指标显示上涨动力
2. 基本面强劲，盈利能力优秀
3. 市场情绪积极
4. 长期增长前景良好

**风险管理措施：**
- 设置止损订单以限制下行风险
- 分批建仓以降低时机风险
- 密切监控市场变化

#### D.6 风险管理团队评估

**风险评估：**
- 市场风险：中等，考虑到当前波动性
- 流动性风险：低，苹果股票流动性充足
- 集中度风险：需要注意投资组合多样化

**风险调整建议：**
- 将仓位限制在投资组合的合理比例内
- 使用期权策略对冲下行风险
- 定期重新评估投资论点

> ⚠️ 以下内容为系统早期研究示例，仅说明多智能体协作流程，不代表当前版本输出格式。当前版本已改为研究辅助工具定位，不输出买入/卖出/持有等交易指令，仅输出研究结论倾向（乐观/审慎/中性）及研究依据。

#### D.7 研究整合员最终审阅

**最终研究结论：对苹果股票持乐观研究倾向**

**研究摘要：**
基于研究计划和多空观点分析，当前研究倾向为乐观。苹果的强劲基本面、创新能力和市场领导地位超过了估值担忧。风险审阅中识别的风险因素提供了审慎的观察要点，需持续跟踪。

---

**项目开源地址**: https://github.com/TauricResearch/TradingAgents

**许可证**: Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)

---

*本文档是对原英文论文的完整中文翻译，包含了详细的案例研究，旨在为中文读者提供对TradingAgents框架的全面理解。翻译保持了原文的学术严谨性和技术准确性，并展示了系统的实际运行过程。*

---

### 02 User Guide Learning 06 Resources Paper Guide (`docs/02-user-guide/learning-06-resources/paper-guide.md`)

# TradingAgents论文解读

**分类**: 源项目与论文
**难度**: 进阶
**阅读时间**: 20分钟
**更新日期**: 2025-11-15

---

## 📋 论文信息

**标题**: TradingAgents: 多智能体大语言模型金融交易框架

**作者**: Yijia Xiao¹'³, Edward Sun¹'³, Di Luo¹'², Wei Wang¹'³

¹ 加州大学洛杉矶分校 (UCLA)  
² 麻省理工学院 (MIT)  
³ Tauric Research

**资源**:
- 📄 [英文原版 PDF](/research-papers/TradingAgents_paper.pdf)
- 📄 [中文翻译版](../../paper/TradingAgents_论文中文版.md)
- 💻 [项目地址](https://github.com/TauricResearch/TradingAgents)

---

## 🎯 论文核心内容

### 研究背景

**问题**：
- 金融分析需要处理大量复杂信息
- 传统方法难以综合多维度数据
- 单一AI模型存在局限性

**解决方案**：
- 利用大语言模型的推理能力
- 采用多智能体协作机制
- 通过辩论提高分析质量

---

## 🏗️ 核心架构

### 整体架构



### 智能体架构

TradingAgents-CN 采用专业化的多智能体架构，每个智能体都有明确的职责和专业领域：

- **分析师团队 (Analysts)**：
  - **基本面分析师**：分析公司财务和基本面数据
  - **技术分析师**：分析技术指标和价格趋势
  - **新闻分析师**：分析新闻事件和宏观因素
  - **社交媒体分析师**：分析社交媒体情绪



- **研究员团队 (Researchers)**：
  - **乐观情景研究员**：从乐观角度评估研究证据
  - **审慎情景研究员**：从悲观角度评估投资风险



- **研究整合 (Trader)**：
  - **研究整合员**：综合各方分析，生成用户版研究简报



- **风险管理团队 (Risk Management)**：
  - **风险评估智能体**：评估投资风险，提供风险审阅结论



### 数据流架构

TradingAgents-CN 的数据流架构设计用于高效地获取、处理和分发金融数据：

- **外部数据源**：
  - **FinnHub API**：实时金融数据
  - **Yahoo Finance**：历史价格数据
  - **Reddit API**：社交媒体数据
  - **Google News**：新闻数据
  - **自定义数据源**：扩展接口
- **数据处理流程**：
  1. **数据获取层**：从各数据源获取原始数据
  2. **数据处理层**：统一接口、处理、验证和转换数据
  3. **缓存层**：Redis缓存、本地缓存、内存缓存
  4. **数据分发层**：将处理后的数据分发给各智能体

### 2. 辩论机制

**核心创新**：让多个AI从不同角度辩论

**辩论流程**：
```
第1轮：各方提出初始观点
   ↓
第2轮：互相反驳和论证
   ↓
第3轮：综合和达成共识
   ↓
最终研究结论
```

**实验结果**：
- 单智能体准确率：~70%
- 多智能体协作：~85%
- 多智能体辩论：~90%

### 3. 工具系统

**设计原则**：
- 模块化：每个工具独立
- 可扩展：易于添加新工具
- 标准化：统一的接口

**工具类型**：
```
数据工具
├── 市场数据获取
├── 财务数据查询
└── 新闻信息抓取

分析工具
├── 技术指标计算
├── 基本面分析
└── 情感分析

决策工具
├── 风险评估
├── 投资组合优化
└── 回测验证
```

---

## 🔬 实验验证

### 实验1：单股分析准确性

**测试集**：100只美股
**评估指标**：分析质量、推荐准确性

**结果**：

| 方法 | 分析质量 | 推荐准确性 |
|------|---------|-----------|
| 传统方法 | 6.5/10 | 65% |
| 单智能体 | 7.2/10 | 70% |
| 多智能体协作 | 8.5/10 | 85% |
| 多智能体辩论 | 9.0/10 | 90% |

### 实验2：投资组合表现

**测试期**：2023年1月-12月
**初始资金**：$100,000

**结果**：

| 策略 | 年化收益 | 最大回撤 | 夏普比率 |
|------|---------|---------|---------|
| 基准（S&P 500） | 15.2% | -12.5% | 1.2 |
| 单智能体 | 18.5% | -15.2% | 1.3 |
| 多智能体辩论 | 24.8% | -11.8% | 1.8 |

**结论**：多智能体辩论机制显著提升了投资表现。

---

## 💡 关键创新点

### 1. 角色专业化

**传统方式**：
```
一个AI处理所有任务
→ 样样通，样样松
```

**TradingAgents方式**：
```
每个AI专注特定角色
→ 术业有专攻
→ 分析更专业
```

### 2. 辩论机制

**创新点**：
- 不同观点的碰撞
- 互相质疑和论证
- 减少偏见和错误

**类比**：
```
就像法庭辩论：
- 原告律师（乐观派）
- 被告律师（谨慎派）
- 法官（综合决策）
→ 更公正的判决
```

### 3. 工具生态

**设计理念**：
```
不是把所有功能塞进AI
而是给AI提供工具
让AI学会使用工具
```

**优势**：
- 更准确（使用专业工具）
- 更可靠（工具经过验证）
- 更灵活（易于扩展）

---

## 🌟 论文贡献

### 学术贡献

1. **理论框架**
   - 提出了金融领域的多智能体协作框架
   - 证明了辩论机制的有效性

2. **实验验证**
   - 大规模实验证明方法的优越性
   - 提供了可复现的实验结果

3. **开源平台**
   - 提供完整的开源实现
   - 降低研究和应用门槛

### 实践价值

1. **可用性**
   - 不只是理论，有实际可用的系统
   - 开箱即用的工具

2. **可扩展性**
   - 模块化设计
   - 易于定制和扩展

3. **社区驱动**
   - 开源社区的力量
   - 持续改进和创新

---

## 📊 与其他方法对比

### vs 传统量化策略

| 维度 | 传统量化 | TradingAgents |
|------|---------|----------|
| 灵活性 | ❌ 固定规则 | ✅ 自适应 |
| 可解释性 | ⚠️ 黑盒 | ✅ 可解释 |
| 数据处理 | ⚠️ 结构化数据 | ✅ 多模态数据 |
| 更新成本 | ❌ 需要重新训练 | ✅ 提示词调整 |

### vs 单一LLM

| 维度 | 单一LLM | TradingAgents |
|------|---------|----------|
| 分析深度 | ⚠️ 有限 | ✅ 深入 |
| 多角度 | ❌ 单一视角 | ✅ 多角度 |
| 准确性 | ⚠️ 70% | ✅ 90% |
| 风险控制 | ⚠️ 较弱 | ✅ 强 |

---

## 🔮 未来方向

论文提出的未来研究方向：

### 1. 更多智能体角色

```
当前：Researcher, Analyst, Manager
未来：
├── Risk Manager (风险管理)
├── Compliance Officer (合规官)
├── Market Maker (做市商)
└── Sentiment Analyst (情绪分析师)
```

### 2. 更强的推理能力

- 多步推理
- 因果推理
- 反事实推理

### 3. 更好的人机协作

- 人类专家参与辩论
- 交互式分析
- 可视化决策过程

### 4. 更广的应用场景

```
当前：股票分析
未来：
├── 期货交易
├── 期权策略
├── 加密货币
├── 外汇交易
└── 固定收益
```

---

## 📚 延伸阅读

### 相关论文

1. **Multi-Agent Systems**
   - "Communicative Agents for Software Development" (ChatDev)
   - "AutoGen: Enabling Next-Gen LLM Applications"

2. **LLM in Finance**
   - "BloombergGPT: A Large Language Model for Finance"
   - "FinGPT: Open-Source Financial Large Language Models"

3. **AI Debate**
   - "Improving Factuality and Reasoning via Multi-Agent Debate"
   - "Debating with More Persuasive LLMs Leads to More Truthful Answers"


---

## 💭 个人思考

### 论文的价值

**学术价值**：
- 提出了创新的框架
- 提供了实验验证
- 推动了领域发展

**实践价值**：
- 可直接应用
- 开源降低门槛
- 社区驱动创新

### 局限性

**当前局限**：
1. 依赖LLM质量
2. API成本较高
3. 实时性有限
4. 需要人工验证

**改进方向**：
1. 优化提示词
2. 混合使用模型
3. 缓存优化
4. 人机协作

---

## 🎓 总结

### 核心要点

1. **多智能体协作**是提高AI分析质量的有效方法
2. **辩论机制**能显著减少偏见和错误
3. **工具系统**让AI更准确可靠
4. **开源平台**降低了应用门槛

### 启发

> "一个人可以走得很快，但一群人可以走得更远"

这句话完美诠释了TradingAgents的理念：
- 不是追求单个AI的极致
- 而是通过协作达到更好的效果

---

**推荐阅读顺序**：
1. 📄 先读[论文中文版](../../paper/TradingAgents_论文中文版.md)
2. 📖 再看[多智能体系统](../04-analysis-principles/multi-agent-system.md)
3. 🚀 最后[快速开始](../07-tutorials/getting-started.md)实践

---

### 02 User Guide Learning 08 Faq General Questions (`docs/02-user-guide/learning-08-faq/general-questions.md`)

# 常见问题解答

**分类**: 常见问题  
**难度**: 入门  
**阅读时间**: 15分钟  
**更新日期**: 2025-11-14

---

## 📋 目录

- [关于TradingAgents-CN](#关于tradingagents-cn)
- [功能相关](#功能相关)
- [模型选择](#模型选择)
- [使用技巧](#使用技巧)
- [问题排查](#问题排查)
- [费用相关](#费用相关)

---

## 🏢 关于TradingAgents-CN

### Q1: TradingAgents-CN是什么？

**A**: TradingAgents-CN是一个基于大语言模型的AI股票分析学习平台，采用多智能体协作机制，帮助用户学习和理解股票分析方法。

**核心特点**：
- 🤖 多智能体协作分析
- 🇨🇳 专为中国A股市场优化
- 📚 学习工具，非投资建议
- 🔓 开源项目，可自部署

### Q2: 与其他股票分析工具有什么区别？

**A**: 

| 特点 | TradingAgents-CN | 传统分析工具 |
|------|-----------------|------------|
| 分析方式 | AI多智能体协作 | 固定算法 |
| 灵活性 | 可自定义提示词 | 固定模式 |
| 学习价值 | 展示分析过程 | 只给结果 |
| 适用市场 | A股优化 | 通用 |
| 开源性 | 完全开源 | 多为闭源 |

### Q3: 是否提供投资建议？

**A**: ⚠️ **不提供投资建议**

TradingAgents-CN是**学习工具**，提供的分析仅供参考，不构成投资建议。

```
✅ 我们提供：学习资源、分析参考、工具支持
❌ 我们不提供：投资建议、收益保证、专业咨询
```

### Q4: 数据来源是什么？

**A**: 

**A股数据来源（按优先级与职责）**：
- 📊 Tushare（主力专业数据，需密钥）
  - 股票列表、日线/分钟行情、`daily_basic`（PE/PB/市值等）、财务三表（利润/资产负债/现金流）
  - 框架内用于“动态PE/PB”与基本面分析的核心来源（见 `tradingagents/dataflows/realtime_metrics.py`）
  - 降级链首选：MongoDB → Tushare → 其他（见 `stock_data_service.py`）
- 📈 AKShare（开源免费补充）
  - 历史/实时行情、部分财务数据；港股数据优先走 AKShare（见 `dataflows/providers/hk`）
  - 新闻接口：东方财富个股新闻 `stock_news_em`、CCTV 市场新闻（见 `dataflows/akshare_utils.py`）
- 🗃️ BaoStock（免费且稳定的历史数据）
  - 作为 A 股历史数据的兜底补充（见 `constants/data_sources.py` 与 `providers/china`）


**数据类型**：
- 实时行情
- 财务报表
- 技术指标
- 市场新闻

**国际与新闻数据来源**：
- 🇺🇸 yfinance（Yahoo Finance，免费）
  - 美股/港股行情与基础信息；港股在 AKShare失败时降级到 yfinance（见 `dataflows/interface.py`）
- 🇺🇸 Finnhub（需密钥）
  - 美股/港股行情、基本面与新闻；后端/前端均检测 `FINNHUB_API_KEY`（见 `web/modules/config_management.py`）
- 🇺🇸 Alpha Vantage（需密钥）
  - 美股基本面与部分新闻；作为 US 市场的备选（见 `providers/us/alpha_vantage_fundamentals.py`）
- 📚 SimFin（数据集）
  - 美股财报数据，提供资产负债表/利润表/现金流（见 `dataflows/interface.py`）
- 📰 新闻聚合（多源）
  - Tushare 新闻源：sina/eastmoney/10jqka/wallstreetcn/cls/第一财经/金融界/云财经/凤凰财经（见 `docs/features/news/NEWS_SYNC_FEATURE.md`）
  - AKShare 新闻源：东方财富、CCTV（见 `dataflows/akshare_utils.py`）
  - 自建聚合：Google News、Reddit（见 `dataflows/interface.py` 与 `features/news/news-analysis-system.md`）

**环境变量与密钥**：
- `TUSHARE_TOKEN`（必需，用于 Tushare）
- `FINNHUB_API_KEY`（可选，启用 Finnhub）
- `ALPHA_VANTAGE_API_KEY`（可选，启用 Alpha Vantage）
- `NEWSAPI_KEY`（可选，启用部分新闻聚合）

**数据源选择与降级策略（内置）**：
- A股：MongoDB → Tushare → AKShare → BaoStock（按优先级自动切换）
- 港股：AKShare → yfinance → Finnhub（失败时逐级降级）
- 美股：Alpha Vantage → yfinance → Finnhub（按场景选择与降级）

---

## 🎯 功能相关

### Q5: 支持哪些股票市场？

**A**: 

**当前支持**：
- ✅ 中国A股（上海、深圳）
- ✅ 科创板
- ✅ 创业板

**当前支持（扩展）**：
- ✅ 港股（AKShare / yfinance / Finnhub）
- ✅ 美股（yfinance / Finnhub / Alpha Vantage）

### Q6: 可以分析哪些类型的股票？

**A**: 

**支持的股票类型**：
- ✅ 主板股票
- ✅ 科创板股票
- ✅ 创业板股票
- ❌ 退市股票
- ❌ 停牌股票（数据可能不完整）

### Q7: 分析需要多长时间？

**A**: 

| 分析类型 | 时间 | 适用场景 |
|---------|------|---------|
| 快速分析 | 30秒 | 快速了解 |
| 标准分析 | 1-2分钟 | 日常分析 |
| 深度分析 | 2-3分钟 | 重要决策 |
| 多智能体辩论 | 5-8分钟 | 重大决策 |

**影响因素**：
- 模型选择（Qwen‑Max更稳但稍慢；DeepSeek V3.1更快、性价比高）
- 网络状况
- API响应速度

### Q8: 可以同时分析多只股票吗？

**A**: 

**可以**，有两种方式：

**方式1：批量分析**
```
1. 进入"批量分析"页面
2. 输入多个股票代码（回车换行分隔）
3. 选择分析维度
4. 点击"开始分析"
```


### Q9: 分析报告可以保存吗？

**A**: 

**可以**，支持多种方式：

- 📄 **导出PDF**：完整报告，适合打印
- 📊 **导出Excel**：数据表格，适合进一步分析
- 💾 **保存到历史**：在线查看历史报告


### Q10: 如何使用多智能体辩论？

**A**: 

**步骤**：
1. 选择研究深度（1-5级：快速/基础/标准/深度/全面）
2. 输入股票代码
3. 点击"开始分析"
4. 系统按所选级别执行辩论与风险讨论（轮次不同）
5. 查看辩论过程与综合结论（研究经理/风险裁决）

**辩论轮次与风险讨论说明**：
- 1级 快速：辩论 1 轮；风险讨论 1 轮
- 2级 基础：辩论 1 轮；风险讨论 1 轮
- 3级 标准：辩论 1 轮；风险讨论 2 轮
- 4级 深度：辩论 2 轮；风险讨论 2 轮
- 5级 全面：辩论 3 轮；风险讨论 3 轮

提示：实际耗时与所选级别、模型提供商与工具调用有关，级别越高辩论与风险讨论轮次越多，整体时长会相应增加。

**按级别选择建议**：
- 1级 快速：日常监控、热点扫描、盘中快评；对延迟敏感的轻量场景
- 2级 基础：常规单股研究、包含最新数据；小额仓位调整、短线策略
- 3级 标准（推荐）：重要投资决策、需风控校验；覆盖大多数日常场景
- 4级 深度：重大事件/财报季/高波动；需要多轮辩论与更稳的结论
- 5级 全面：高金额或组合级决策；产出完整研究报告与合规记录

提示：所有级别均支持“多智能体辩论”，只是辩论与风险讨论的轮次不同；选择更高等级意味着更全面的观点整合与更长的耗时。

---

## 🤖 模型选择

### Q11: 应该选择哪个LLM模型？

**A**: 

**根据预算选择（聚焦 DeepSeek + Qwen 系列）**：

**预算有限**（<¥100/月）：
```
主力：DeepSeek V3.1（高性价比，中文表现好）
重要分析：Qwen3‑Plus（长文本/中文优化）
```

**预算适中**（¥100‑500/月）：
```
主力：DeepSeek V3.1 + Qwen3‑Plus（分工协作）
深度分析：Qwen‑Max（管理层多轮辩论/裁决）
```

**预算充足**（>¥500/月）：
```
分析师：DeepSeek V3.1 或 Qwen3‑Plus（快速/长文档）
经理层：Qwen‑Max（深度推理与综合裁决）
```

**根据需求选择**：

| 需求 | 推荐模型 |
|------|---------|
| 快速分析 | DeepSeek V3.1 |
| 深度分析/裁决 | Qwen‑Max |
| 中文优化 | Qwen3‑Plus |
| 长文本综述 | Qwen3‑Plus |
| 极致性价比 | DeepSeek V3.1 |

### Q12: Qwen‑Max 和 Qwen3‑Plus 差别大吗？

**A**: 

**核心差异**：

| 维度 | Qwen‑Max | Qwen3‑Plus |
|------|----------|------------|
| 推理能力 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 分析深度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| 上下文/长文档 | 中等 | 较长 |
| 工具调用稳定性 | ✅ 高 | ✅ 高 |
| 速度 | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| 成本 | 💰💰💰💰 | 💰💰 |
| 适配角色 | 管理层/深度裁决 | 分析师/长文档综述 |

**建议**：
- 分析师单点任务、长文本综述：选 Qwen3‑Plus
- 管理层综合、深度辩论/裁决：选 Qwen‑Max
- 若预算敏感：DeepSeek V3.1 作为主力，重要环节切换到 Qwen‑Max

### Q13: DeepSeek V3.1 适合哪些场景？

**A**: 

**DeepSeek V3.1 特点（项目已深度适配）**：
- 💰 成本极优：适合作为日常分析主力模型
- 🇨🇳 中文理解好：A股与中文资讯语境把握到位
- 🔧 Function Calling 稳定：工具链调用、数值计算表现可靠
- ⚡ 响应快：适合盘中与批量任务

**建议**：
- 日常与批量分析：首选 DeepSeek V3.1（快速、低成本）
- 长文本/中文综述：Qwen3‑Plus 更稳、更长上下文
- 深度辩论/最终裁决：Qwen‑Max（研究经理/风险经理）

### Q14: 如何获取API密钥？

**A**: 

**国内模型（推荐）**：
- **DeepSeek V3.1**：https://platform.deepseek.com（控制台 → API Keys）
- **通义千问（DashScope）**：https://dashscope.aliyun.com（控制台 → API Keys）
- （可选）文心一言：https://cloud.baidu.com；讯飞星火：https://xinghuo.xfyun.cn

**国际模型（可选）**：
- OpenAI：https://platform.openai.com（如需海外网络）

**注意**：
- 🔒 妥善保管API密钥
- 💰 注意API使用额度
- ⚠️ 不要分享给他人

---

## 💡 使用技巧

### Q15: 如何提高分析质量？

**A**: 

**5个技巧**：

1. **选择更适配的模型**
  ```
  Qwen‑Max > Qwen3‑Plus > DeepSeek V3.1
  （深度裁决 → 长文本综述 → 性价比与速度）
  ```

2. **提供更详细的数据**
   ```
   不要只输入股票代码
   提供财务数据、行业信息等
   ```

3. **自定义提示词**
   ```
   根据分析目的调整提示词
   明确分析重点和角度
   ```

4. **使用多智能体辩论**
   ```
   重要决策使用辩论模式
   听取不同角度的观点
   ```

5. **验证关键数据**
   ```
   AI可能出错
   关键数据要交叉验证
   ```

### Q16: 如何自定义提示词？（未实现，开发中，后续版本提供）

**A**: 

**步骤**：
1. 进入"设置" → "提示词管理"
2. 选择要修改的智能体
3. 编辑提示词模板
4. 保存并测试

**示例**：

**原提示词**：
```
你是一位股票分析师，请分析{股票}的投资价值。
```

**自定义提示词**：
```
你是一位专注于{行业}的资深分析师，
拥有10年以上的投资经验。

请从价值投资的角度分析{股票}，
重点关注：
1. 估值水平（PE、PB）
2. 盈利能力（ROE、净利率）
3. 护城河（竞争优势）
4. 管理层质量

要求：
- 使用巴菲特的投资理念
- 关注长期价值
- 保守估计
```

### Q17: 如何管理股票关注列表？

**A**: 

**添加到研究列表**：
1. 分析股票后，点击"添加到自选"
2. 或在"股票关注列表"页面手动添加

**股票关注列表功能**：
- 📊 查看股票关注列表列表
- 📈 批量分析股票关注列表
- 🔔 设置价格提醒
- 📉 查看涨跌幅排行

**分组管理**：
```
可以创建多个分组：
- 核心持仓
- 观察名单
- 行业板块
- 潜力股
```

### Q18: 如何设置价格提醒？（目前未实现，因为实时数据问题）

**A**: 

**步骤**：
1. 进入股票详情页
2. 点击"设置提醒"
3. 选择提醒类型：
   - 价格到达
   - 涨跌幅
   - 成交量异常
4. 设置提醒条件
5. 选择通知方式（邮件/站内信）

**示例**：
```
股票：平安银行（000001）
提醒类型：价格到达
条件：>= 14.50元
通知方式：邮件 + 站内信
```

---

## 🔧 问题排查

### Q19: 分析失败怎么办？

**A**: 

**常见原因和解决方法**：

**1. API密钥错误**
```
错误信息：Invalid API Key
解决方法：检查API密钥是否正确
```

**2. API额度不足**
```
错误信息：Insufficient quota
解决方法：充值API账户
```

**3. 网络问题**
```
错误信息：Network timeout
解决方法：检查网络连接，重试
```

**4. 股票代码错误**
```
错误信息：Stock not found
解决方法：检查股票代码是否正确
```

**5. 数据源问题**
```
错误信息：Data source error
解决方法：等待数据源恢复，或切换数据源
```

### Q20: 分析结果不准确怎么办？

**A**: 

**可能原因**：

1. **AI幻觉**
   ```
   AI编造了不存在的数据
   解决：验证关键数据
   ```

2. **数据过时**
   ```
   使用了旧数据
   解决：提供最新数据
   ```

3. **提示词不当**
   ```
   提示词不够清晰
   解决：优化提示词
   ```

4. **模型能力不足**
   ```
   使用了较弱的模型
   解决：切换到 Qwen‑Max 或提升分析深度等级（4/5级）
   ```

---

## 💰 费用相关

### Q21: 使用TradingAgents-CN需要付费吗？

**A**: 

**软件本身**：
- ✅ 完全免费
- ✅ 开源项目
- ✅ 可自部署

**需要付费的部分**：
- 💰 LLM API调用费用（按使用量计费）
- 💰 数据源API费用（部分数据源）

### Q22: LLM API费用大概多少？

**A**: 

**估算（每月）**：

**轻度使用**（每天分析2-3只股票）：
```
使用 DeepSeek V3.1：约 ¥5-10/月
使用 Qwen3‑Plus：约 ¥10-30/月
使用 Qwen‑Max：约 ¥50-150/月
```

**中度使用**（每天分析5-10只股票）：
```
使用 DeepSeek V3.1：约 ¥20-40/月
使用 Qwen3‑Plus：约 ¥30-80/月
使用 Qwen‑Max：约 ¥150-400/月
```

**重度使用**（每天分析20+只股票）：
```
使用 DeepSeek V3.1：约 ¥40-80/月
使用 Qwen3‑Plus：约 ¥80-200/月
使用 Qwen‑Max：约 ¥400-1200/月
```

**节省费用技巧**：
1. 日常/批量：优先 DeepSeek V3.1 或 Qwen3‑Plus
2. 深度裁决：仅在关键环节使用 Qwen‑Max
3. 批量任务：降低 `max_tokens` 与分析深度级别
4. 启用缓存与工具复用，避免重复调用

### Q23: 如何查看API使用情况？

**A**: 

**在TradingAgents-CN中**：
1. 进入"设置" → "使用统计"
2. 查看：
   - 总调用次数
   - Token使用量
   - 预估费用

**在API提供商官网**：
1. 登录API提供商账户
2. 查看Usage页面
3. 查看详细账单

---

## 📚 更多资源

### 相关文档

- 📖 [快速入门教程](../07-tutorials/getting-started.md)
- 📖 [提示词工程](../02-prompt-engineering/prompt-basics.md)
- 📖 [模型选择指南](../03-model-selection/model-comparison.md)
- 📖 [风险提示](../05-risks-limitations/risk-warnings.md)

### 获取帮助

- 💬 GitHub Issues
- 📧 邮件支持
- 👥 用户社区

---

**还有其他问题？**

欢迎在GitHub Issues中提问，或查看完整文档。

---

### 07 Courses V3.0 Real Frontend Display Names (`docs/07-courses/v3.0/real-frontend-display-names.md`)

# v3.0 课程字段名/术语核实参考

> **目的**:记录前端代码里**真实**的字段显示名/术语,作为课程修订的参考。
> **来源**:实际前端代码(`frontend/src/views/Reports/ReportDetail.vue` 等)
> **维护原则**:本文件内容必须**从代码中查到**,**禁止靠记忆/猜测**写入。

## 1. 批量分析页"分析深度"下拉项

来源: [BatchAnalysis.vue:139-158](file:///c:/TradingAgentsCN/frontend/src/views/Analysis/BatchAnalysis.vue#L139-L158)

| 档位 | 页面下拉显示名(用户看到的) |
|------|------------------|
| 1 | ⚡ **1级 - 快速分析**(2-4分钟/只) |
| 2 | 📈 **2级 - 基础分析**(4-6分钟/只) |
| 3 | 🎯 **3级 - 标准分析**(6-10分钟/只)⭐ |
| 4 | 🔍 **4级 - 深度分析**(10-15分钟/只) |
| 5 | 🏆 **5级 - 全面分析**(15-25分钟/只) |

## 2. 批量分析页"分析师团队"可勾选的角色(只有 7 个)

来源: [analysts.ts:13-59](file:///c:/TradingAgentsCN/frontend/src/constants/analysts.ts#L13-L59)

| 页面显示名 | 实际 ID | 描述 |
|---------|---------|------|
| 📈 市场分析师 | `market` | 分析个股价格走势与技术指标(均线/MACD/RSI/布林带) |
| 💰 基本面分析师 | `fundamentals` | 分析公司财务状况、业务模式和竞争优势 |
| 📰 新闻分析师 | `news` | 分析相关新闻、公告和市场事件的影响 |
| 💬 社媒分析师 | `social` | 分析社交媒体情绪、投资者心理和舆论导向 |
| 📊 大盘分析师 | `index_analyst` | 分析大盘指数走势、市场环境和系统性风险 |
| 🏭 板块分析师 | `sector_analyst` | 分析行业趋势、板块轮动和同业对比 |
| ETF分析师 | `etf` | 仅 ETF 市场时可选,分析 ETF 净值、跟踪误差和持仓结构 |

**系统默认勾选**:["市场分析师", "基本面分析师"](见 [analysts.ts:65](file:///c:/TradingAgentsCN/frontend/src/constants/analysts.ts#L65))

## 3. 报告模块的页面 Tab 名(报告里"详细研究报告"卡片)

来源: [ReportDetail.vue:286-312](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L286-L312)

| 后端 key | 页面 Tab 显示名(带图标) |
|---------|------------------|
| `index_report` | 📊 大盘分析师 |
| `sector_report` | 🏭 板块分析师 |
| `market_report` | 📈 市场分析师 |
| `sentiment_report` | 💬 社交媒体分析师 |
| `news_report` | 📰 新闻分析师 |
| `fundamentals_report` | 💰 基本面分析师 |
| `bull_researcher` | 🐂 乐观情景研究员 |
| `bull_report` | 🐂 乐观情景研究 |
| `bear_researcher` | 🐻 审慎情景研究员 |
| `bear_report` | 🐻 审慎情景研究 |
| `research_team_decision` | 🔬 研究整合员 |
| `trader_investment_plan` | 🧩 研究整合员 |
| `risky_analyst` | ⚡ 高弹性情景分析师 |
| `risky_opinion` | ⚡ 高弹性情景研究观察 |
| `safe_analyst` | 🛡️ 防御情景分析师 |
| `safe_opinion` | 🛡️ 防御情景研究观察 |
| `neutral_analyst` | ⚖️ 基准情景分析师 |
| `neutral_opinion` | ⚖️ 基准情景研究观察 |
| `risk_management_decision` | 👔 风险评估师 |
| `risk_assessment` | ⚠️ 风险审阅 |
| `investment_plan` | 🧾 研究简报 |
| `final_trade_decision` | 🧾 综合研究结论 |
| `investment_debate_state` | 🔬 研究团队分析(旧) |
| `risk_debate_state` | ⚖️ 风险团队分析(旧) |
| `detailed_analysis` | 📄 详细分析 |

## 4. 报告内 Agent 顶部分析师列表显示名

来源: [ReportDetail.vue:235-284](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L235-L284)

| 后端 key | 页面显示名(顶部分析师列表) |
|---------|----------------------|
| `index_analyst` / `index_analyst_v2` | 大盘分析师 |
| `sector_analyst` / `sector_analyst_v2` | 板块分析师 |
| `market_analyst` / `market_analyst_v2` / `market` / `technical` | 市场分析师 |
| `fundamentals_analyst` / `fundamentals_analyst_v2` / `fundamentals` | 基本面分析师 |
| `etf_analyst` / `etf_analyst_v2` / `etf` | ETF 分析师 |
| `news_analyst` / `news_analyst_v2` / `news` | 新闻分析师 |
| `social_analyst` / `social_analyst_v2` / `social` / `sentiment` | 社交媒体分析师 |
| `bull_researcher` / `bull_researcher_v2` / `多头研究员` | 乐观情景研究员 |
| `bear_researcher` / `bear_researcher_v2` / `空头研究员` | 审慎情景研究员 |
| `research_manager` / `research_manager_v2` | 研究经理 |
| `trader` / `trader_v2` | 研究整合员 |
| `risky_analyst` / `risky_analyst_v2` / `激进分析师` | 高弹性情景分析师 |
| `safe_analyst` / `safe_analyst_v2` / `保守分析师` | 防御情景分析师 |
| `neutral_analyst` / `neutral_analyst_v2` / `中性分析师` | 基准情景分析师 |
| `risk_manager` / `risk_manager_v2` | 风险评估师 |

**注意**:
- 报告顶部分析师列表(无图标) ≠ 报告 Tab 列表(带图标)。同样一个 Agent,顶部的标签是"市场分析师",Tab 标签是"📈 市场分析师"。
- "乐观情景研究员"和"🐂 乐观情景研究员"是**同一个 Agent 在不同位置的统一显示名**(顶部和 Tab)。

## 5. 风险评估 JSON 字段(报告里"风险审阅" Tab 渲染)

来源: [ReportDetail.vue:707-745](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L707-L745)

| 后端 key | 页面显示标签(用户看到的) |
|---------|----------|
| `risk_level` | **风险等级** |
| `risk_score` | **风险评分** |
| `reasoning` / `conclusion` / `summary` / `assessment` | **评估结论** |
| `key_risks` (数组) | **核心风险**(以 `-` 列表渲染) |
| `risk_control` / `control` / `suggestions` | **风控建议** |
| `investment_adjustment` / `adjustment` | **投资调整建议** |

## 6. 持仓分析里的"动作标签"映射

来源: [PositionAnalysisDetailDialog.vue:235-244](file:///c:/TradingAgentsCN/frontend/src/views/Portfolio/components/PositionAnalysisDetailDialog.vue#L235-L244)

| 后端返回值 | 页面显示(用户看到的) |
|---------|---------|
| `乐观` | 乐观 |
| `审慎` | 审慎 |
| `中性` | 中性 |
v3.0 持仓研究与单股研究使用相同的 3 个决策标签(乐观/审慎/中性)，不再有"偏多/偏空/待验证"等额外标签。

## 7. 股票筛选页(Screening/index.vue)字段

### 7.1 智能筛选 Tab

- 页面标题:"股票筛选"
- 页面描述:"默认通过智能对话引导你完成选股;只有在需要精细手动配置时,再进入高级模式"
- 两个 Tab:**智能筛选** / **高级模式**(默认是"智能筛选")
- 左侧面板标题:"筛选历史"(副标题:"按会话查看之前的智能筛选记录"),带"新建"按钮
- 智能筛选确认操作按钮:"按原需求筛选" / "采纳建议后筛选" / "执行筛选方案" / "重新描述需求"

### 7.2 高级模式 Tab ——"常用条件"区(默认显示 8 个)

来源: [Screening/index.vue:267-403](file:///c:/TradingAgentsCN/frontend/src/views/Screening/index.vue#L267-L403)

| 字段标签(用户看到的) | 实际字段 | 类型 |
|---------|---------|------|
| **股票代码/名称** | `keyword` | 文本输入 |
| **行业分类** | `industry` | 多选下拉 |
| **市场类型** | `market` | 下拉(固定为 A股,disabled) |
| **市值范围** | `total_mv` | 下拉(小盘/中盘/大盘) |
| **市盈率 (PE)** | `pe` | 范围输入(最小-最大) |
| **市净率 (PB)** | `pb` | 范围输入 |
| **涨跌幅** | `pct_chg` | 范围输入 |
| **成交量** | `amount` | 下拉(活跃/正常/清淡) |

### 7.3 高级模式 Tab ——"高级字段"区(需手动添加)

来源: [Screening/index.vue:406-547](file:///c:/TradingAgentsCN/frontend/src/views/Screening/index.vue#L406-L547)

- 区域标题:"高级字段",副标题:"不常用字段不默认铺开;需要时再主动添加到过滤条件里"
- 右上标签:"可选 N 项"
- 添加字段下拉框占位符:"选择要追加的高级字段"
- 提示文字:"只显示你主动添加的字段;移除字段会同时清空对应条件"
- 空状态提示:"还没有添加高级字段。需要更细条件时,再从上方选择要补充的字段"

### 7.4 筛选结果表格列

来源: [Screening/index.vue:619-720](file:///c:/TradingAgentsCN/frontend/src/views/Screening/index.vue#L619-L720)

| 表格列(用户看到的) | 显示内容 |
|---------|----------|
| 复选框列 | 选中加入批量分析列表 |
| **股票代码** | 可点击链接,跳股票详情 |
| **股票名称** | - |
| **行业** | 行业分类 |
| **当前价格** | 格式:¥XX.XX |
| **涨跌幅** | 带正负号,如 +1.23% / -0.85% |
| **市值** | 格式:XX 亿 / XX 万亿 |

### 7.5 按钮

- 顶部:**开始筛选** / **重置条件**
- 结果区:**批量分析(N)** / **导出结果** / **重新筛选**
- 占位符:"未找到符合条件的股票"

## 8. 批量分析页(BatchAnalysis.vue)其他字段

来源: [BatchAnalysis.vue](file:///c:/TradingAgentsCN/frontend/src/views/Analysis/BatchAnalysis.vue)

- 页面标题:"批量分析",右上"高级"标签
- 风险提示:"⚠️ 重要提示:本次分析仅用于学习、研究和公开信息整理,不提供个股交易指导。"
- 描述:"AI 驱动的批量研究工作台,高效整理多只股票的研究线索"
- "股票列表"卡片(右上角标签:`N 只股票`)
  - 市场下拉选项:"🇨🇳 A股市场(6位数字)" / "📈 ETF 基金(510050、159919 等)"
  - 输入框占位符(A股):"请输入股票代码,每行一个\n支持格式:\n000001\n000002.SZ\n600036.SH"
  - 输入框占位符(ETF):"请输入ETF代码,每行一个\n支持格式:\n510050\n510300.SH\n159919.SZ"
  - 按钮:"解析股票代码" / "清空"
  - 股票预览标题:"股票预览"
  - 无效代码提示:"以下股票代码格式可能有误,请检查:"
- "分析配置"卡片(右上"批量设置"标签)
  - "分析深度"下拉(见第 1 节)
  - "分析流程"下拉:列 `workflow_type === 'stock_analysis'` 的工作流,默认选 `is_default=true` 的
  - "分析师团队"(见第 2 节)
  - 提交按钮:"开始批量分析(N只)"
- "高级配置"卡片:含 ModelConfig 组件,字段"快速分析模型"和"深度分析模型"

## 9. 通用研究分析页(GeneralAnalysis.vue)

来源: [GeneralAnalysis.vue](file:///c:/TradingAgentsCN/frontend/src/views/Analysis/GeneralAnalysis.vue)

- 页面标题:"通用研究分析",图标 Document
- 风险提示:"⚠️ 重要提示:本次分析所有结论用于学习和验证AI证券分析技术,不作为真实交易操盘指导。"
- 描述:"基于通用流程的灵活研究工作台,支持自定义分析目标与参数"
- Tab:**新分析** / **历史结果**
- 表单字段:
  - **流程选择**:"请选择通用分析流程"
  - 选中流程后显示"执行参数"分隔线,字段从 `selectedWorkflowFull.input_config.fields` 动态生成
  - 字段类型支持:string / textarea / number / boolean / date / select / multiselect
  - 字段标签使用 `field.label || field.name`(优先用 label,没有才用 name)
  - 字段描述在输入框下方显示:`field.description`
- 按钮:"开始分析" / "查看结果" / "重新分析"

## 10. Agent 名称中文显示(用于 Agent 工坊下拉等)

来源: [agentLabels.ts](file:///c:/TradingAgentsCN/frontend/src/constants/agentLabels.ts)

| 后端 key | 页面显示名(下拉) |
|---------|---------|
| `analysts_v2` | 独立分析师 v2.0 |
| `researchers_v2` | 乐观/审慎情景研究员 v2.0 |
| `debators_v2` | 风险多情景研究 v2.0 |
| `managers_v2` | 研究/风险评估师 v2.0 |
| `trader_v2` | 研究整合员 v2.0 |
| `reviewers_v2` | 复盘分析 v2.0 |
| `position_analysis_v2` | 仓位分析 v2.0 |
| `post_processors_v2` | 后处理器 v2.0 |
| `universal` | 自定义Agent |

## 11. 报告模块的展示顺序(用户在 Tab 上看到的顺序)

来源: [ReportDetail.vue:601-635](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L601-L635)

```
第一阶段:宏观分析(2个)
  - index_report → 📊 大盘分析师
  - sector_report → 🏭 板块分析师

第二阶段:分析师团队(4个)
  - market_report → 📈 市场分析师
  - fundamentals_report → 💰 基本面分析师
  - sentiment_report → 💬 社交媒体分析师
  - news_report → 📰 新闻分析师

第三阶段:研究团队(多情景研究 + 初步研究观察)
  - bull_researcher → 🐂 乐观情景研究员
  - bull_report → 🐂 乐观情景研究
  - bear_researcher → 🐻 审慎情景研究员
  - bear_report → 🐻 审慎情景研究
  - research_team_decision → 🔬 研究整合员
  - investment_plan (与 research_team_decision 重复时隐藏)

第四阶段:交易团队
  - trader_investment_plan → 🧩 研究整合员

第五阶段:风险管理团队(风险辩论)
  - risky_analyst → ⚡ 高弹性情景分析师
  - risky_opinion → ⚡ 高弹性情景研究观察
  - safe_analyst → 🛡️ 防御情景分析师
  - safe_opinion → 🛡️ 防御情景研究观察
  - neutral_analyst → ⚖️ 基准情景分析师
  - neutral_opinion → ⚖️ 基准情景研究观察
  - risk_management_decision → 👔 风险评估师
  - risk_assessment → ⚠️ 风险审阅

第六阶段:最终研究结论
  - final_trade_decision → 🧾 综合研究结论

兼容旧字段
  - investment_debate_state → 🔬 研究团队分析(旧)
  - risk_debate_state → ⚖️ 风险团队分析(旧)
  - detailed_analysis → 📄 详细分析
```

## 12. 报告页面里用户看到的"风险提示"

来源: [ReportDetail.vue:83-93](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L83-L93)

```
⚠️ 重要风险提示与免责声明

- 平台性质:本平台为AI辅助分析技术学习平台,专注于AI技术在证券与ETF分析领域的应用验证和技术学习。
- 分析目的:所有分析结论仅用于学习和验证AI辅助分析技术,不作为真实交易操盘指导或投资依据。
- 非投资建议:所有分析结果、评分、建议仅为技术验证参考,不构成任何买卖建议或投资决策依据。
- 数据局限性:分析基于历史数据和公开信息,可能存在延迟、不完整或不准确的情况,无法预测未来市场走势。
- 投资风险:股票与ETF投资均存在市场风险、流动性风险、政策风险等多种风险,可能导致本金损失。
- 独立决策:投资者应基于自身风险承受能力、投资目标和财务状况独立做出投资决策。
- 责任声明:使用本平台产生的任何投资决策及其后果由使用者自行承担,本平台不承担任何责任。
```

## 13. 报告页面里"研究简报"卡片

来源: [ReportDetail.vue:108-119](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L108-L119)

- 卡片标题:**研究简报**
- 副标题图标:InfoFilled
- 内容: Markdown 渲染的 `summaryDisplayContent`

## 14. 报告页面里"详细研究报告"卡片

来源: [ReportDetail.vue:121-145](file:///c:/TradingAgentsCN/frontend/src/views/Reports/ReportDetail.vue#L121-L145)

- 卡片标题:**详细研究报告**
- 副标题图标:Files
- Tab 类型:`type="border-card"`
- Tab 标签:由 `getModuleDisplayName(moduleName)` 动态生成(参考第 3 节)

## 15. 报告中心列表(Reports/index.vue)字段

来源: [Reports/index.vue](file:///c:/TradingAgentsCN/frontend/src/views/Reports/index.vue)

| 表格列 | 页面显示名 |
|--------|----------|
| 报告标题 | `股票代码 - 股票名称` |
| 报告类型 | "分析报告" / "批量报告" |
| 格式 | "MARKDOWN" / "DOCX" / "PDF" / "JSON" |
| 状态 | "已完成" / "分析中" / "失败" |
| 分析模型 | LLM 模型名(如 "qwen-flash / qwen-max") |
| 分析深度 | "深度: 5" / "深度: 3" |
| 创建时间 | YYYY-MM-DD HH:mm |

## 16. 报告中心筛选器

- 搜索框占位符:**"搜索股票代码或名称"**
- 市场筛选占位符:**"市场筛选"**,选项:仅 **A股**
- 日期范围占位符:**"开始日期"** / **"结束日期"**

## 17. 报告中心顶部说明文字

```
查看和管理股票分析报告,支持多种格式导出(批量导出最多 10 个)
```

## 📋 仍待核实事项

以下功能未在前端代码中找到,需要进一步核实:

- [ ] `/portfolio` 持仓页的字段显示
- [ ] `/paper` 模拟交易的字段显示
- [ ] `/review` 复盘的字段显示
- [ ] `/assistant` AI 助手的字段显示
- [ ] `/position` 持仓管理的字段显示
- [ ] `/settings/*` 各种设置页的字段显示
- [ ] `report_manifest` 在不同工作流中的具体显示差异

## ⚠️ 修订课程时的注意事项

1. **优先以"用户在页面上看到的中文标签"为准**,而不是后端字段名
2. **同一个东西在不同位置的显示已统一**(如"乐观情景研究员"在顶部和 Tab 都一致)
3. **不要用代码 key**(如 `bull_researcher`、`risk_level`)给用户看,要写"🐂 乐观情景研究员"、"风险等级"
4. **写代码引用时**用 `[BatchAnalysis.vue:139-158](file:///...)` 这种带行号的格式,方便核对

---

### 07 Courses V3.0 V3 Actual Features (`docs/07-courses/v3.0/v3-actual-features.md`)

# TradingAgents-CN v3.0 真实功能清单

> **核实时间**: 2026-07-31
> **核实方法**: 直接读代码 + 查 MongoDB 样本 + 查前端路由 + 查侧边栏菜单
> **目的**: 为 [v3.0 课程](../README.md) 改写提供"对照表",确保每个功能描述都有据可查

## ⚠️ 重要声明

本文档与项目记忆可能存在差异。**以代码为准**。

例如:项目记忆曾提到"v3.0 已暂停港美股",前端入口已实际移除(§9),但后端代码暂未清理(系历史包袱,学员不可见)。课程改写应**明确告诉用户平台仅支持 A 股和 ETF**。

---

## §1 前端 25 个顶层路由

来源: [frontend/src/router/index.ts](../../../frontend/src/router/index.ts)

| # | 路径 | 名称 | 说明 |
|---|------|------|------|
| 1 | `/dashboard` | Dashboard | 仪表板(系统首页) |
| 2 | `/guide` | Guide | 平台引导(新手入门) |
| 3 | `/learning` | Learning | 学习中心(显示 3 个子页) |
| 4 | `/analysis/single` | SingleAnalysis | 单股研究 |
| 5 | `/analysis/batch` | BatchAnalysis | 批量研究 |
| 6 | `/analysis/general` | GeneralAnalysis | 通用研究(无明确股票) |
| 7 | `/screening` | StockScreening | 股票筛选 |
| 8 | `/favorites` | Favorites | 关注列表 |
| 9 | `/assistant` | Assistant | AI 智能助手(对话式) |
| 10 | `/memory` | Memory | AI 记忆管理(多主题会话) |
| 11 | `/reports` | Reports | 报告中心(报告查看、详情、Token 统计) |
| 12 | `/workflow` | Workflow | 工作流(5 个子菜单,见 §2) |
| 13 | `/tasks/unified` | UnifiedTaskCenter | 任务中心(统一版) |
| 14 | `/paper` | Paper | 模拟交易 |
| 15 | `/portfolio` | Portfolio | **持仓**(注意:不叫 position) |
| 16 | `/review` | Review | 复盘(实际叫 trade_review) |
| 17 | `/trading-system` | TradingSystem | 交易系统(策略) |
| 18 | `/stocks/:code` | StockDetail | 股票详情页 |
| 19 | `/backtest` | Backtest | 回测(前端入口已下线) |
| 20 | `/settings` | Settings | 设置(6 个子菜单,见 §3) |
| 21 | `/debug/embedded-nanobot` | EmbeddedNanobotDebug | 调试页面(开发者向) |
| 22 | `/about` | About | 关于 |
| 23 | `/login` | Login | 登录 |
| 24 | `/paper/:name.md` | PaperMdRedirect | 论文跳转 |
| 25 | `/:pathMatch(.*)*` | - | 404 兜底 |

## §2 工作流子菜单(5 个)

来源: [SidebarMenu.vue](../../../frontend/src/components/Layout/SidebarMenu.vue)

| 路径 | 名称 | 说明 |
|------|------|------|
| `/workflow` | 工作流首页 | 可视化编排工作流 |
| `/workflow/tools` | 工具管理 | 工具增删改 |
| `/workflow/agent-workshop` | Agent 工坊 | 创建自定义 Agent |
| `/workflow/skills` | Skill 中心 | 创建/管理 Skill |
| `/workflow/mcp-servers` | MCP 服务器 | 外部工具服务器 |

## §3 设置子菜单(11 个)

| 路径 | 名称 | 说明 |
|------|------|------|
| `/settings` | 通用设置 | 基础配置 |
| `/settings?tab=appearance` | 外观设置 | 主题/布局 |
| `/settings?tab=analysis` | 分析偏好 | 个人分析默认参数 |
| `/settings?tab=notifications` | 通知设置 | 通知方式 |
| `/settings?tab=security` | 安全设置 | 密码/2FA |
| `/settings?tab=assistant` | 助理设置 | AI 助手配置 |
| `/settings/email` | 邮箱配置 | SMTP 设置 |
| `/settings/channel-configs` | 渠道推送 | 飞书/钉钉/邮件/Webhook |
| `/settings/watchlist-groups` | 关注分组 | 关注列表分组管理 |
| `/settings/scheduled-analysis` | 定时分析 | 定时任务配置 |
| `/settings/license` | 授权(标准版) | License 激活(京东云版隐藏) |
| `/settings/jdyun-config` | 京东云配置 | 京东云版专用 |
| `/settings/config` | 配置管理(标准版) | LLM/数据源/系统设置 |
| `/settings/cache` | 缓存管理 | 缓存清理 |
| `/settings/templates` | 报告模板 | 模板管理 |
| `/settings/prompt-policies` | 提示词策略 | 防注入 |
| `/settings/prompt-design` | 提示词设计 | 自定义提示词 |
| `/settings/analysis-profiles` | 分析画像 | 行业/股票画像 |
| `/settings/database` | 数据库管理 | MongoDB 管理 |
| `/settings/logs` | 操作日志 | 用户操作日志 |
| `/settings/system-logs` | 系统日志 | 系统级日志 |
| `/settings/sync` | 多数据源同步 | Tushare/AKShare/BaoStock 同步 |
| `/settings/capability-index` | 工具能力索引 | 工具元数据 |
| `/settings/scheduler` | 定时任务 | 系统级定时任务 |
| `/settings/social-media` | 社媒消息管理 | 飞书/钉钉消息模板 |
| `/settings/data-import` | 数据导入 | 历史数据导入 |
| `/settings/usage` | 使用统计 | Token 用量 |
| `/settings/update` | 系统更新 | 系统升级 |

## §4 后端 78 个 APIRouter 路由模块

来源: [app/routers/](../../../app/routers/)

按功能分类(不完整列举):

| 前缀 | 模块 | 关键端点 |
|------|------|---------|
| `/api/agent-workshop` | agent_workshop.py | sessions/start, sessions/respond, build-version, versions/publish, prompt |
| `/api/akshare-init` | akshare_init.py | status, start-full, start-basic-sync |
| `/api/analysis-profiles` | analysis_profiles.py | industries, stocks |
| (无 prefix) | analysis.py | single, batch, general, tasks, history, queue-status, cancel, retry |
| `/api/backtest` | backtest.py | analyze, generate, run, results, sessions, optimize, evaluate |
| `/api/baostock-init` | baostock_init.py | status, start-full, start-basic |
| `/api/cache` | cache.py | stats, cleanup, clear |
| `/api/channel-configs` | channel_configs.py | 增删改查 + test + event-types |
| `/config` | config.py | jdyun/status, gateway, llm/providers, datasource, system, settings |
| `/database` | database.py | MongoDB 管理 |
| `/api/embedded-nanobot` | embedded_nanobot.py | 嵌入式纳米机器人 |
| `/favorites` | favorites.py | 关注列表增删改查 |
| `/api/financial-data` | financial_data.py | 财务数据查询 |
| `/api/gateway` | gateway.py | 网关配置 |
| `/api/historical-data` | historical_data.py | 历史行情查询 |
| `/api/assistant` | intelligent_assistant.py | 智能助手对话 |
| `/api/screening/intelligent` | intelligent_screening.py | **自然语言筛选对话** |
| `/api/internal-messages` | internal_messages.py | 内部消息 |
| `/api/knowledge` | knowledge.py | 知识库 |
| `/api/license` | license.py | 授权管理 |
| `/system-logs` | logs.py | 系统日志 |
| `/api/mcp` | mcp.py | MCP 服务器 |
| `/api/memory` | memory.py | AI 记忆 |
| `/api/model-capabilities` | model_capabilities.py | 模型能力管理 |
| `/markets` | multi_market_stocks.py | 多市场股票(后端保留,前端不可见) |
| `/api/multi-period-sync` | multi_period_sync.py | 多周期数据同步 |
| `/api/sync/multi-source` | multi_source_sync.py | 多数据源同步 |
| `/api/news-data` | news_data.py | 新闻数据 |
| `/logs` | operation_logs.py | 操作日志 |
| `/paper` | paper.py | 模拟交易(A 股账户;后端代码支持三市场,前端已下线) |
| `/api/v1/prompt-design` | prompt_design.py | 提示词设计 |
| `/api/v1/prompt-policies` | prompt_injection_policies.py | 提示词防注入 |
| `/api/v1/prompt-preview` | prompt_preview.py | 提示词预览 |
| `/api/quality-metrics` | quality_metrics.py | 质量指标 |
| `/report-templates` | report_templates.py | 报告模板 |
| `/api/reports` | reports.py | 报告管理 |
| `/api/scheduler` | scheduler.py | 系统级定时 |
| (无 prefix) | scheduled_analysis.py | 用户级定时分析 |
| `/api/screening` | screening.py | 条件式筛选(老版) |
| `/api/skill-center` | skill_center.py | Skill 管理中心 |
| `/api/skill-gaps` | skill_gaps.py | Skill 缺口分析 |
| `/api/skill-generation` | skill_generation.py | Skill 自动生成 |
| `/api/skills` | skills.py | Skills CRUD |
| `/api/social-media` | social_media.py | 社媒推送 |
| `/api/stock-data` | stock_data.py | 股票数据 |
| `/api/stock-sync` | stock_sync.py | 股票数据同步 |
| `/stocks` | stocks.py | 股票基础信息(后端代码支持三市场,前端已下线) |
| `/api/sync` | sync.py | 同步任务 |
| (无 prefix) | system_config.py | 系统配置 |
| `/tags` | tags.py | 标签管理 |
| `/api/tushare-init` | tushare_init.py | Tushare 初始化 |
| `/api/v2/tasks` | unified_tasks.py | 统一任务中心 |
| `/api/system/update` | update.py | 系统更新 |
| `/api/usage` | usage_statistics.py | Token 使用统计 |
| (无 prefix) | user_template_configs.py | 用户模板配置 |
| (无 prefix) | watchlist_groups.py | 关注分组 |
| `/api/v1/workflow` | workflow_api.py | 工作流 API |
| `/api/workflow-generation` | workflow_generation.py | 工作流生成 |
| `/api/workflow-growth` | workflow_growth.py | 工作流迭代 |

## §5 单股研究报告实际结构

来源: MongoDB `analysis_reports` 集合(样本:宁德时代 300750 / 工商银行 601398)

### 顶层字段(28 个)

| 字段 | 类型 | 说明 |
|------|------|------|
| `_id` | ObjectId | 主键 |
| `analysis_id` | str | 业务 ID(格式 `<code>_<date>_<time>`) |
| `stock_symbol` | str | 股票代码(如 300750) |
| `stock_code` | str | 股票代码(同 stock_symbol) |
| `stock_name` | str | 股票名称(如 宁德时代) |
| `market_type` | str | 市场类型(A股/ETF;数据表保留港美股字段,前端已不可用) |
| `model_info` | str | 使用的模型(如 `qwen-flash/qwen-plus`) |
| `analysis_date` | date | 分析日期 |
| `timestamp` | datetime | 创建时间 |
| `status` | str | 状态(`completed`/`failed`/`running`) |
| `source` | str | 来源(`api`/`manual` 等) |
| `engine` | str | 引擎版本(`v2`) |
| `research_depth` | str | 研究深度(**字符串**,如 `标准`/`深度`/`快速`) |
| `summary` | str(长文本) | 投资摘要(最终交易决策) |
| `analysts` | list[str] | 使用的 7 个分析师 ID(见 §6) |
| `reports` | dict | 12 个子报告(见 §7) |
| `decision` | dict | 决策结构(见 §8) |
| `recommendation` | str(长文本) | 投资建议(详细版) |
| `confidence_score` | float | 信心度(0-1,如 0.76) |
| `risk_level` | str | 风险等级(`低`/`中`/`高`/`中等`) |
| `risk_score` | float | 风险评分(0-1,如 0.5) |
| `key_points` | list[str] | 关键要点(数组) |
| `execution_time` | float | 执行耗时(秒,如 525.32) |
| `tokens_used` | int | Token 用量 |
| `performance_metrics` | dict | 性能指标 |
| `user_id` | str | 用户 ID |
| `created_at` | datetime | 创建时间 |
| `updated_at` | datetime | 更新时间 |
| `task_id` | str | 关联任务 ID |

## §6 7 个内置分析师角色

来源: MongoDB `agent_configs` 集合(过滤 `is_builtin=True`)

实际报告 `analysts` 字段包含 7 个 ID:

| # | ID | 角色 | 类型 |
|---|----|------|------|
| 1 | `market_analyst` | 市场分析师 | analyst |
| 2 | `fundamentals_analyst` | 基本面分析师 | analyst |
| 3 | `bull_researcher` | 看涨研究员 | researcher |
| 4 | `bear_researcher` | 看跌研究员 | researcher |
| 5 | `risky_analyst` | 激进风险分析师 | risk |
| 6 | `safe_analyst` | 保守风险分析师 | risk |
| 7 | `neutral_analyst` | 中性风险分析师 | risk |

## §7 reports 字典 12 个子报告

| Key | 说明 |
|-----|------|
| `market_report` | 市场/技术面分析(MA/MACD/RSI/BOLL) |
| `fundamentals_report` | 基本面分析(估值/财务/行业) |
| `investment_plan` | 投资计划 |
| `trader_investment_plan` | 交易员的实操框架 |
| `final_trade_decision` | 最终交易决策 |
| `bull_researcher` | 看涨研究员报告 |
| `bear_researcher` | 看跌研究员报告 |
| `research_team_decision` | 研究团队决策 |
| `risky_analyst` | 激进风险分析 |
| `safe_analyst` | 保守风险分析 |
| `neutral_analyst` | 中性风险分析 |
| `risk_management_decision` | 风险管理决策 |

## §8 decision 字段(决策结构,已合规化)

> ⚠️ 本表为合规化后的结构(2026-08 更新)。旧的 `target_price` / `stop_loss` / "买入/卖出/持有" 等字段已移除。
> 来源: [core/agents/adapters/risk_manager_v2.py](file:///c:/TradingAgentsCN/core/agents/adapters/risk_manager_v2.py) 的 `FinalTradeDecision` / `RiskAssessmentOutput` schema。

| Key | 类型 | 说明 |
|-----|------|------|
| `action` | str | 决策标签,**只能是 `乐观` / `审慎` / `中性`**(非交易指令) |
| `confidence` | float | 信心度(0-1) |
| `price_analysis_range` | str(可选) | 价格分析区间(替代旧 `target_price`,**非目标价**) |
| `risk_reference_price` | str(可选) | 风险控制参考价位(替代旧 `stop_loss`,**非止损价**) |
| `risk_exposure_ratio` | str(可选) | 风险敞口分析 |
| `reasoning` | str | 推理过程 |
| `summary` | str | 分析摘要 |
| `risk_warning` | str | 风险提示 |

风险审阅(`risk_assessment`)另有:`risk_level`(低/中/高)、`risk_score`(0-1)、`key_risks`(数组)、`risk_control`、`investment_adjustment`(乐观/审慎/中性)。

## §9 ⚠️ 港美股功能状态:前端已下线,后端保留

**业务决策**(2026-07-31 用户确认):
- **港美股前端入口已全部移除**,用户从 UI 看不到、也无法使用
- **后端代码暂时保留**(`foreign_stock_service.py` 2402 行等),未来可能复用
- **课程应按"港美股不可用"处理**,不向学员介绍

### 前端入口核实现状(2026-07-31)

| 入口 | 港美股选项? | 说明 |
|------|---------|------|
| `/analysis/single` 单股研究 | ❌ 无 | `MarketType = 'A股' \| 'ETF'`,前端不含港美股选项 |
| `/analysis/batch` 批量研究 | ❌ 无 | 同上,`market: 'A股' as 'A股' \| 'ETF'` |
| `/screening` 筛选 | ❌ 无 | `<el-select v-model="basicFilters.market" disabled>`,只显示 A 股 |
| `/favorites` 关注列表 | ❌ 已清理 | 仅 A 股自选 |
| `/paper` 模拟交易 | ❌ 已清理 | 仅 A 股账户 |
| 侧边栏菜单 | ❌ 无相关入口 | 见 §1 路由表 |
| Dashboard 卡片 | ❌ 无相关入口 | 仅 A 股入口 |

### 后端代码保留(课程无需涉及)

- ⚠️ `multi_market_stocks.py` API 端点仍在(CN/HK/US 三市场搜索)
- ⚠️ `foreign_stock_service.py` 2402 行
- ⚠️ `paper.py` 模拟交易路由支持三市场账户
- ⚠️ `hk_sync_service.py` 港股数据同步
- ⚠️ `market_categories` 集合 `us_stocks` / `hk_stocks` 仍 `enabled=True`

**这些后端代码对学员不可见,课程不应涉及**。将来如需清理后端代码,那是另一项工程任务。

### 课程改写影响

- ❌ **lesson-10 模拟交易**:不写港美股账户(原课程中我误判要保留港美股)
- ❌ **lesson-04 多情景**:删除"5 种情景",改为讲解"2 角色辩论(乐观/审慎)+ 1 整合员"
- ❌ **lesson-03 单股研究**:示例股票用 A 股代码(如 600519/601919)
- ✅ **课程应明确告诉用户**:"平台仅支持 A 股和 ETF 基金分析"

## §10 内置 Agent 完整列表(20+)

来源: MongoDB `agent_configs` 集合

### analyst 类别(15 个)
- 市场分析师 / 市场分析师 v2
- 基本面分析师
- 新闻分析师
- 社交媒体分析师
- 行业/板块分析师
- 大盘/指数分析师
- 时机分析师
- 仓位分析师
- 情绪分析师
- 归因分析师
- 复盘总结师
- 持仓技术面分析师
- 持仓基本面分析师
- 持仓风险评估师
- 技术面分析师 v2.0
- 风险评估师 v2.0

### researcher 类别(4 个)
- 看涨研究员 / 看涨研究员 v2.0
- 看跌研究员 / 看跌研究员 v2.0

### trader 类别(3 个)
- 交易员 / 交易员 v2.0
- 持仓分析师

### risk 类别(6 个)
- 激进风险分析师 / 激进风险分析师 v2.0
- 保守风险分析师 / 保守风险分析师 v2.0
- 中性风险分析师 / 中性风险分析师 v2.0

### manager 类别(5 个)
- 风险经理
- 研究经理
- 持仓操作建议师
- 操作建议师 v2.0

### post_processor 类别(3 个)
- 报告保存器
- 邮件通知器
- 系统通知器

## §11 数据集合清单(48 个)

来源: MongoDB `db.list_collection_names()`

| 集合 | 文档数 | 说明 |
|------|--------|------|
| `users` | 1 | 用户表 |
| `user_sessions` | 0 | 会话表 |
| `user_favorites` | 3 | 用户关注列表 |
| `user_tags` | 2 | 用户标签 |
| `user_template_configs` | 48 | 用户模板配置 |
| `watchlist_groups` | 1 | 关注分组 |
| `analysis_reports` | 2 | 分析报告 |
| `analysis_tasks` | 1 | 分析任务(老版) |
| `unified_analysis_tasks` | 1 | 统一任务(新版) |
| `scheduled_analysis_configs` | 1 | 定时分析配置 |
| `paper_accounts` | 5 | 模拟账户 |
| `paper_market_rules` | 3 | 模拟市场规则 |
| `real_accounts` | 1 | 真实账户 |
| `trading_systems` | 2 | 交易系统策略 |
| `workflows` | 1 | 工作流定义 |
| `workflow_history` | 0 | 工作流执行历史 |
| `agent_configs` | 47 | Agent 配置 |
| `tool_agent_bindings` | 38 | 工具-Agent 绑定 |
| `tool_configs` | 1 | 工具配置 |
| `model_catalog` | 12 | 模型目录 |
| `llm_providers` | 11 | LLM 供应商 |
| `platform_configs` | 4 | 平台配置 |
| `system_configs` | 38 | 系统配置(复数) |
| `system_config` | 1 | 系统配置(单数) |
| `prompt_templates` | 146 | 提示词模板 |
| `stock_basic_info` | 16578 | 股票基础信息 |
| `stock_screening_view` | 16578 | 股票筛选视图 |
| `stock_daily_quotes` | 484 | 日线行情 |
| `stock_news` | 60 | 股票新闻 |
| `stock_financial_data` | 2 | 财务数据 |
| `market_quotes` | 5548 | 实时行情(A股) |
| `market_categories` | 3 | 市场分类(A/HK/US) |
| `sync_status` | 1 | 同步状态 |
| `quotes_ingestion_status` | 1 | 行情入库状态 |
| `token_usage` | 15 | Token 用量记录 |
| `notifications` | 1 | 通知 |
| `operation_logs` | 102 | 操作日志 |
| `capital_transactions` | 1 | 资金流水 |
| `datasource_groupings` | 11 | 数据源分组 |
| `smtp_config` | 1 | SMTP 邮箱配置 |
| `license_cache` | 1 | License 缓存 |
| `scheduler_metadata` | 1 | 调度元数据 |
| `system.views` | 1 | MongoDB 视图元数据 |

## §12 交易系统集合结构

来源: MongoDB `trading_systems` 集合(样本:短线趋势追踪系统 / 中线价值成长系统)

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | str | 系统名称 |
| `description` | str | 描述 |
| `style` | str | **风格**(`short_term` / `medium_term` / `long_term`) |
| `risk_profile` | str | 风险画像(`aggressive` / `balanced` / `conservative`) |
| `stock_selection` | dict(2) | 选股方法 |
| `timing` | dict(1) | 时机判断 |
| `position` | dict(3) | 仓位管理 |
| `holding` | dict(3) | 持仓管理 |
| `risk_management` | dict(2) | 风险管理 |
| `review` | dict(2) | 复盘 |
| `discipline` | dict(2) | 纪律 |
| `version` | str | 版本号 |
| `is_active` | bool | 是否激活 |

**对课程的影响**:
- ✅ 课程中"短线/中长线"区分有真实数据支持(`style` 字段)
- 实际有 3 种风格: `short_term` / `medium_term` / `long_term`(不是只有 2 种)

## §13 重点:用户能找到的所有 v3.0 新功能

通过前端路由 + 后端 API + MongoDB 集合,系统能识别出的 v3.0 新功能(对比 v2.x):

| # | 功能 | 路径/模块 | v3.0 新增? |
|---|------|----------|------------|
| 1 | **自然语言选股** | `/api/screening/intelligent/chat` | ✅ |
| 2 | **AI 智能助手(对话式)** | `/assistant` | ✅ |
| 3 | **AI 记忆(多主题会话)** | `/memory` | ✅ |
| 4 | **通用研究(无明确股票)** | `/analysis/general` | ✅ |
| 5 | **MCP 服务器** | `/api/mcp` | ✅ |
| 6 | **Agent 工坊** | `/workflow/agent-workshop` | ✅ |
| 7 | **Skill 中心** | `/api/skill-center` | ✅ |
| 8 | **Skill 自动生成** | `/api/skill-generation` | ✅ |
| 9 | **AI 工作流架构师** | `/api/workflow-generation` | ✅ |
| 10 | **多数据源同步** | `/api/sync/multi-source` | ✅ |
| 11 | **多周期同步** | `/api/multi-period-sync` | ✅ |
| 12 | **分析画像** | `/api/analysis-profiles` | ✅ |
| 13 | **报告模板** | `/report-templates` | ✅ |
| 14 | **提示词设计** | `/api/v1/prompt-design` | ✅ |
| 15 | **提示词防注入策略** | `/api/v1/prompt-policies` | ✅ |
| 16 | **统一任务中心** | `/tasks/unified` | ✅ |
| 17 | **统一报告中心** | `/reports` | ✅ |
| 18 | **Token 统计** | `/reports/token` | ✅ |
| 19 | **渠道推送(飞书/钉钉/邮件/Webhook)** | `/api/channel-configs` | ✅ |
| 20 | **止盈告警** | `/api/stop-gain-alerts`(待确认) | ✅ |
| 21 | **回测** | `/backtest` | ❌ 前端入口已下线 |
| 22 | **嵌入式纳米机器人** | `/api/embedded-nanobot` | ✅ |
| 23 | **工具能力索引** | `/api/capability-index` | ✅ |
| 24 | **系统更新** | `/api/system/update` | ✅ |
| 25 | **使用问答助手** | (右下角浮窗) | ✅ |

## §14 课程改写时需要核对的"易错点"

1. **多情景分析**: ❌ 没有"乐观/基准/审慎/高弹性/防御"5 情景。实际是 **2 角色辩论(乐观/审慎)+ 1 整合员** + **3 风险视角(高弹性/防御/基准)**,最终由风险评估师综合输出 decision(`action` ∈ {乐观/审慎/中性})
2. **置信度**: ✅ 正确存在 `confidence_score` 字段(0-1)
3. **AI 评分**: ❌ 没有"AI 综合评分 0-100"。实际是 `confidence_score` (0-1) 和 `risk_score` (0-1)
4. **风险等级**: ✅ 有 `risk_level` 字段(字符串:"低"/"中"/"高"/"中等")
5. **目标价/止损**: ❌ 已合规化移除。decision 不再有 `target_price`/`stop_loss`,改为可选的 `price_analysis_range`(价格分析区间) 和 `risk_reference_price`(风险参考价),且明确"禁止给出具体目标价或止损价"
6. **持仓分析**: ✅ 有专门的 4 个 Agent(持仓技术面/基本面/风险评估/操作建议)
7. **复盘**: ✅ 有 `/review` 路由,后端 `trade_review_service.py` 3618 行
8. **回测**: ⚠️ 后端有 `/backtest` 路由和 `/api/backtest` API 残留,但前端入口已下线,产品不提供
9. **关注列表分组**: ✅ 有 `watchlist_groups` 集合,可在 `/settings/watchlist-groups` 管理
10. **定时分析**: ✅ 有 `scheduled_analysis_configs` 集合
11. **自然语言筛选**: ✅ 有 `/api/screening/intelligent/chat` API,在 Dashboard 有入口

## §15 课程阶段与真实功能的映射

| 课程阶段 | 应使用的真实功能 |
|---------|-----------------|
| **阶段 1:发现** | 自然语言筛选(`/api/screening/intelligent/chat`) + 条件式筛选(`/screening`) + 批量分析(`/analysis/batch`) + 单股研究(`/analysis/single`) |
| **阶段 2:跟踪** | 通用研究(`/analysis/general`) + 定时分析(`/settings/scheduled-analysis`) + 关注列表(`/favorites`) + 关注分组(`/settings/watchlist-groups`) + 渠道推送(`/settings/channel-configs`) |
| **阶段 3:持仓** | 模拟交易(`/paper`) + 持仓(`/portfolio`) + 4 个持仓 Agent(技术面/基本面/风险/操作建议) |
| **阶段 4:复盘** | 复盘(`/review`) + 案例库(`trade_review_service.py`) + 归因分析师 |
| **阶段 5:短线** | 交易系统 `/trading-system` 的 `short_term` 风格 |
| **阶段 6:中长线** | 交易系统 `/trading-system` 的 `medium_term` / `long_term` 风格 |
| **阶段 7:平台扩展** | AI 工作流架构师(`/api/workflow-generation`) + Agent 工坊(`/workflow/agent-workshop`) + Skill 中心(`/workflow/skills`) + Skill 自动生成(`/api/skill-generation`) |
| **阶段 8:个人计划** | 交易系统(`/trading-system`) + AI 助手(`/assistant`) + AI 记忆(`/memory`) |

---

> **最后更新**: 2026-07-31
> **配套文档**: [v3.0 课程 README](../README.md) | [课程偏差清单](../../06-knowledge/course-v3-deviation-list-2026-07-31.md)

---

### 07 Courses V3.0 改写执行清单 (`docs/07-courses/v3.0/改写执行清单.md`)

# 课程改写执行清单

> **更新时间**: 2026-07-31 | **适用版本**: v3.0 课程改造
>
> **重要**:本课程**仅适用于 A 股和 ETF 基金分析**。港股、美股的前端入口已下线,所有课程示例代码必须使用 A 股代码(如 600519、601919、300750)。
>
> **本清单的真实功能依据**: [v3-actual-features.md](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/v3-actual-features.md)(基于代码 + MongoDB + 前端路由的真实功能清单)

## 总览

- **总课数**: 30 课 + 1 导读
- **复用现有 advanced/ 课程**: 17 课(57%)
- **改写现有课程**: 5 课(17%)
- **新增课程**: 8 课(27%)
- **预计总工作量**: 12-17 小时

---

## 详细清单(按阶段)

### 阶段 0:导读(1 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 0 课 | 全课程地图与学习路径 | **新增** | 5 分钟路线图导读,集成在 README.md 中 |

### 阶段 1:发现(5 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 1 课 | 股票筛选(从 6000 → 500) | **改写** | 基于 advanced/expanded/lesson-03,聚焦股票筛选(原 lesson-03 混合了批量分析内容,本次拆分) |
| 第 2 课 | 批量分析(从 500 → 50) | **改写** | 基于 advanced/expanded/lesson-04,**删除 AAPL/TSLA 美股代码示例**,改"v2.0 引擎"为"v3.0 分析引擎",补 v3.0 通用研究入口 |
| 第 3 课 | 单股研究入门(从 50 → 10) | **复用** | advanced/expanded/lesson-03 的单股部分,补 v3.0 多情景结构 |
| 第 4 课 | 单股研究进阶:多情景结构解读 | **复用** | advanced/expanded/lesson-08 辩论部分(去除"多空"术语,保留 5 情景结构),定位从"择时篇"调到"发现阶段" |
| 第 5 课 | 发现阶段的常见错误 | **新增** | 1000 字,讲选股常见陷阱(追热点、听消息、过度拟合历史) |

**复用率**: 60% | **改动工作量**: 中

### 阶段 2:跟踪(4 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 6 课 | 通用研究(无明确股票,讲行业讲主题) | **新增** | 1500 字,补 v3.0 通用研究(/analysis/general)功能 |
| 第 7 课 | 定时分析与渠道推送 | **改写** | 基于 advanced/expanded/lesson-17 定时分析部分,**合并 v3.0 渠道推送**(飞书/钉钉/邮件) |
| 第 8 课 | AI 对话助手与 AI 记忆 | **新增** | 1200 字,补 v3.0 AI 助手能力(20+ 工具、多主题会话) |
| 第 9 课 | 跟踪阶段的节奏控制 | **新增** | 1000 字,讲不同周期的跟踪频率(日/周/月) |

**复用率**: 25% | **改动工作量**: 大(4 课中 3 课是新增)

### 阶段 3:持仓(6 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 10 课 | 模拟交易:先练手再真金白银 | **改写** | 基于 advanced/expanded/lesson-10,**重大改写:删除所有港美股账户/T+0/HKD/USD 内容**,只保留 A 股部分 |
| 第 11 课 | 持仓研究:AI 帮我监控我的持仓 | **复用** | advanced/expanded/lesson-11,微调 UI 描述 |
| 第 12 课 | 加减仓决策:看 AI 研究输出做判断 | **改写** | 合并 advanced/expanded/lesson-12 + lesson-13 风险辩论应用 |
| 第 13 课 | 风险跟踪:跟踪边界怎么设 | **复用** | advanced/expanded/lesson-14,课程保留"止盈止损"口语化表达(用户已确认课程不需要按合规文档的官话替换) |
| 第 14 课 | 持仓阶段的常见错误 | **新增** | 1000 字,讲持仓常见陷阱(止损过紧、过早止盈、加仓无纪律) |
| 第 15 课 | AI 智能助手在持仓阶段的应用 | **新增** | 1200 字,补 v3.0 AI 助手在持仓阶段的具体应用(查持仓、查报告、设告警) |

**复用率**: 50% | **改动工作量**: 中(主要是 lesson-10 改写和 2 课新增)

### 阶段 4:复盘(4 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 16 课 | 操作复盘:这笔交易做对了吗 | **复用** | advanced/expanded/lesson-15,微调 |
| 第 17 课 | 案例库沉淀:把经验变成可复用的资产 | **复用** | advanced/expanded/lesson-16,微调接口名 |
| 第 18 课 | 复盘结果怎么指导下次交易 | **改写** | 基于 advanced/expanded/lesson-15 的"自我校准"部分,扩展 |
| 第 19 课 | 持续优化:基于复盘迭代交易系统 | **复用** | advanced/expanded/lesson-24 部分,定位从"个人计划"调到"复盘阶段" |

**复用率**: 75% | **改动工作量**: 小

### 阶段 5:短线风格(3 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 20 课 | 短线交易系统设计 | **复用** | advanced/expanded/lesson-17 短线部分,微调定位 |
| 第 21 课 | 短线实战案例(上) | **复用** | advanced/expanded/lesson-18 |
| 第 22 课 | 短线实战案例(下) | **复用** | advanced/expanded/lesson-19 |

**复用率**: 100% | **改动工作量**: 极小(只调定位)

### 阶段 6:中长线风格(3 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 23 课 | 中长线投资系统设计 | **复用** | advanced/expanded/lesson-20 |
| 第 24 课 | 中长线实战案例(上) | **复用** | advanced/expanded/lesson-21 |
| 第 25 课 | 中长线实战案例(下) | **复用** | advanced/expanded/lesson-22 |

**复用率**: 100% | **改动工作量**: 极小(只调定位)

### 阶段 7:平台扩展(3 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 26 课 | AI 工作流架构师:用自然语言生成工作流 | **新增** | 1500 字,讲 v3.0 第 6.1.2 节(自然语言生成工作流) |
| 第 27 课 | Agent 工坊 + Skill 中心:自定义分析师 | **新增** | 1500 字,讲 v3.0 Agent 工坊和 Skill 中心 |
| 第 28 课 | 实战:以巴菲特工作流为例,端到端造一个 | **改写** | 基于 advanced/expanded/lesson-25 重大改写:**删除 _v2 后缀旧 Agent ID**(index_analyst_v2 → index_analyst 等),**删除过时枚举值**,加入 Skill 生成部分,合规要求保留但弱化 |

**复用率**: 33% | **改动工作量**: 中(主要是 lesson-28 改写和 2 课新增)

### 阶段 8:个人计划(2 课)

| 课号 | 标题 | 状态 | 来源/说明 |
|------|------|------|----------|
| 第 29 课 | 个人交易计划模板 | **复用** | advanced/expanded/lesson-23 |
| 第 30 课 | 持续优化与成长 | **复用** | advanced/expanded/lesson-24 主体 |

**复用率**: 100% | **改动工作量**: 极小(只调定位)

---

## 工作量汇总

| 状态 | 课数 | 占比 | 预计耗时(小时) |
|------|------|------|---------------|
| 新增 | 8 课 | 27% | 4-6 |
| 改写 | 5 课 | 17% | 4-5 |
| 复用 | 17 课 | 57% | 1-2(主要是搬运+微调) |
| 文档/导航/迁移指引 | - | - | 2-3 |
| **总计** | **30 课** | **100%** | **12-17** |

## 执行顺序建议

### 第一批(优先级最高,2-3 小时)
1. ✅ 创建目录结构和总 README(已完成)
2. ✅ 创建改写执行清单(本文档,已完成)
3. ⏳ 阶段 0 导读(集成在 README,已完成)
4. ⏳ 阶段 1:发现(5 课) — 作为样板验证风格

### 第二批(3-4 小时)
5. ⏳ 阶段 3:持仓(6 课) — 用户最关心
6. ⏳ 阶段 4:复盘(4 课)

### 第三批(3-4 小时)
7. ⏳ 阶段 7:平台扩展(3 课) — 进阶功能
8. ⏳ 阶段 2:跟踪(4 课)

### 第四批(2-3 小时)
9. ⏳ 阶段 5/6:短线/中长线(6 课,主要搬运)
10. ⏳ 阶段 8:个人计划(2 课,主要搬运)

### 收尾(1-2 小时)
11. ⏳ 附录 A/B/C(平台能力速查、学习路径、迁移指引)
12. ⏳ 老课程 advanced/ 加迁移说明,引导新学员

---

## 写作风格规范

1. **每课开头必须有"本课解决什么问题"**,用 1 句话点出
2. **每课结尾必须有"实操作业"**,让用户用本系统真实跑一次
3. **截图引用**:`images/lesson-XX/XX-xxx.png` 路径
4. **代码示例**:Python/JavaScript 都要能直接运行
5. **避免空话**:少讲理论,多讲"在系统里怎么点"
6. **不写"目标价/看涨/看跌"那种合规官话**,保留"买入/止损/止盈"等口语(用户已确认)
7. **跨课引用**:用相对路径 `[lesson-05](file:///.../lesson-05-xxx.md)`

---

### 07 Courses V3.0 Phase 01 Discover Lesson 01 Stock Screening (`docs/07-courses/v3.0/phase-01-discover/lesson-01-stock-screening.md`)

# 第 1 课:股票筛选——从 6000 只股票里找到值得研究的

> **课时**: 20 分钟 | **难度**: ⭐ 入门 | **前置**: 无

> ⚠️ **风险提示**:本课程内容仅为平台功能教学,AI 输出的研究报告不构成投资建议,最终决策由你自己负责。

> ⚠️ **风险提示**:本文为系统功能使用教程,**不构成任何投资建议**。AI 输出结果(决策标签、风险评分、评估结论)仅供研究参考,所有投资决策由用户自行判断,盈亏自负。

## 🎯 学完后能做什么

- 用**一句大白话**告诉 AI"我要什么股票",AI 自动筛选
- 用"**高级模式**"做精细筛选(包含"常用条件"和"高级字段"两层)
- 把筛选结果**一键送进批量分析**

## 🤔 为什么需要筛选?不筛选会怎样?

A 股市场有 **5000+ 只股票**(还在不断增加),你不可能一只只看。**直接搜代码或听别人推荐**的痛点:

| 方式 | 问题 |
|------|------|
| 全市场 5000 只全研究 | 时间精力根本不够,1 只深度研究要 10-20 分钟 |
| 听"热门股"推荐 | 别人推荐的"热点"常常是**已经涨了很多**的,追高风险大 |
| 看排行榜 | 排行榜是**历史表现**,未来不一定继续 |
| 拍脑袋选 | 没有系统方法,完全凭感觉,**长期必亏** |

**筛选的本质**:用**一套规则**把 5000 只缩小到你**能研究过来**的规模(50-100 只),再深度研究。

> 💡 **漏斗思路**:5000 只 → 智能筛选缩到 100-500 只 → 高级模式精修到 50-100 只 → 批量分析研究 → 最终选 5-10 只

## ⚠️ v3.0 重要变化

- ✅ **新增**:**智能筛选(自然语言对话式)是 v3.0 的核心功能**,v2.x 时代只有"高级模式"条件表单
- ✅ **默认 Tab 切换**:进入筛选页默认显示"智能筛选"(自然语言),不再是"高级模式"
- ✅ **支持多轮对话**:AI 会主动复述你的需求,你可以追问"再加个条件"
- ⚠️ **平台范围**:仅支持 **A 股和 ETF 基金**,港股、美股的前端入口已下线

## 📍 入口(找不到?这样进)

| 进法 | 怎么操作 |
|------|---------|
| 侧边栏 | 页面最左侧导航栏,找"股票分析"→"股票筛选" |
| 首页 | 在首页的卡片区找"选股助手"卡片(卡片右上角带"v3.0"小标签) |

> 💡 **还是找不到?** 打开 AI 助手,问"怎么进入股票筛选?",助手会一步步引导你。

## 🖱️ 操作步骤(跟着点 5 步)

### 步骤 1:进入筛选器

1. 用上面任一方式进入「股票筛选」页面
2. 进入后,你会看到**两个 Tab**:左边是"**智能筛选**",右边是"**高级模式**"
3. 系统默认就在"智能筛选" Tab,直接用就行

> 页面布局:左侧是"筛选历史"栏,中间偏右是对话输入框。

> ⏱️ **耗时预期**:
> - 加载筛选页:1-2 秒
> - AI 复述你的需求:5-10 秒
> - 出结果卡片:1-3 秒
> - 整个流程通常 30 秒内完成

### 步骤 2:用大白话告诉 AI 你要什么

在对话框里**直接说人话**,比如:

| 你说的话 | AI 实际会筛选什么(自动推断) |
|---------|------------------------|
| "低估值高股息的银行股" | 银行行业 + **PE 小于 10** + **股息率大于 4%** |
| "新能源行业市值大于 500 亿的龙头" | 新能源行业 + **总市值 > 500 亿** + 行业龙头股 |
| "近期涨得猛的科技股" | 科技行业 + **近 20 日涨幅排行前列** |
| "市值 100-500 亿、ROE 大于 15% 的成长股" | **中盘** 市值 + **ROE > 15%** |
| "机构重仓的医药白马" | 医药行业 + **机构持仓比例高** 的龙头 |

> 💡 **看不懂表格里的 PE、ROE、股息率?** 别担心,这些都是 AI 帮你"翻译"的,你**只用说大白话**。
> 💡 **口语化表达 AI 能理解吗?** 能。AI 会智能推断你的意思(比如"涨得猛"= 近 20 日涨幅前列,"白马"= 行业龙头 + 基本面好)。如果推断有偏差,下一步可以纠正。

发送方法:输入完按 `Ctrl+Enter`,或**直接点输入框右边的"发送"按钮**(纸飞机图标,一般在右下角)。

### 步骤 3:AI 复述 + 你确认(很关键!)

AI 收到你的需求后,会**先复述一遍**让你确认:

> **AI**: "我理解你想筛选:**银行行业、PE<10、股息率>4%**。这样大约会筛出 X 只股票。是否继续?"

这时**屏幕中央会有两个按钮**:
- **"确认筛选"** 按钮(蓝色主按钮,在 AI 回复下方):满意就点这个,AI 开始出结果
- **"修改需求"** 按钮(灰色次按钮,旁边):想调整就点这个,在输入框补充,比如"再加个总市值大于 1000 亿"

> ⚠️ **如果 AI 复述得不对,千万别点"确认"!** 在输入框直接补充或纠正,比如"不是 X,我想要的是 Y",AI 会基于上下文修正理解。

### 步骤 4:查看股票卡片(结果)

确认后,AI 会出**股票卡片列表**(竖排,每行 1 张卡片),每张卡片显示:

```
┌─────────────────────────────┐
│ ☑ 600519 贵州茅台            │
│ 当前价: 1680.50  +1.2%      │
│ PE: 28  PB: 9.5  股息率: 1.5%│
│ 总市值: 2.1 万亿             │
│ 所属行业: 白酒                │
└─────────────────────────────┘
```

每张卡片的关键信息:
- **股票代码 + 名称**(顶部)
- **当前价格 + 涨跌幅**(🔴 红色表示上涨,🟢 绿色表示下跌,这是 A 股市场的颜色习惯)
- **关键指标**:PE、PB、股息率、总市值
- **所属行业**

**勾选卡片右上角的复选框**(☐)加入"待批量分析列表",被选中的卡片边框会变蓝。

> 💡 **这些数字怎么读?**(对小白用户)
>
> | 指标 | 含义 | 大致参考 |
> |------|------|---------|
> | **PE**(市盈率) | 投资回本年限(理论值),PE=股价/年盈利 | <15 偏低估,15-30 合理,>30 偏贵 |
> | **PB**(市净率) | 股价相对每股净资产的倍数 | <1 破净,1-3 合理,>5 偏贵 |
> | **股息率** | 每年分红占股价比例 | >3% 高股息,1-3% 中等,<1% 较低 |
> | **总市值** | 公司总价值 | >1000 亿大盘股,200-1000 亿中盘,<200 亿小盘 |
>
> ⚠️ **注意**:这些数字**单独看意义不大**,要**结合行业**和**其他指标**综合判断。比如银行股 PE=6 是常态,科技股 PE=30 可能算便宜。

### 步骤 5:一键送进批量分析

- 在结果区**上方**(页面顶部)找"**批量分析(N)**"按钮(N 是你勾选的数量)
- 点击后,系统**自动跳转到**「批量分析」页面,股票代码已经填好
- 在批量分析页设置参数:
  - **分析深度**(顶部下拉):推荐选"**🎯 3级 - 标准分析**"(6-10 分钟/只,平衡速度和质量)
  - **分析师团队**(下方复选框):**保持默认勾选**即可,系统已选 2 个核心分析师:
    - 📈 **市场分析师**:技术面、价格走势、均线/MACD/RSI
    - 💰 **基本面分析师**:财务数据、估值、业务模式
  - **提交任务**:页面最底部的"**提交分析**"按钮(蓝色大按钮,左下角)
- 提交后系统**自动跳转到**「任务中心」等结果
  - 💡 **任务中心位置**:侧边栏"我的任务"→"任务中心"
  - 任务完成会有 **站内通知**(右上角铃铛)+ 邮件通知(如果设置了)

## 🆚 "智能筛选" vs "高级模式" 怎么选

如果自然语言筛选**精度不够**或你想做精细化筛选,可以切换到"高级模式":

| 维度 | 智能筛选(自然语言) | 高级模式(条件表单) |
|------|------------------|------------------|
| 入口 | 默认 Tab | 需手动切换 |
| 操作方式 | 一句话对话 | 表单填条件 |
| 适合谁 | **新手 / 不知道字段名** | 熟手 / 想精确控制 |
| 速度 | AI 需 5-10 秒理解 | **即时** |
| 精度 | 中等(AI 推断) | **高**(精确字段) |
| 复杂条件 | 难表达 | **支持嵌套 AND/OR** |

**实战建议**:
- **首次使用 / 不知道字段名** → 用智能筛选
- **明确知道要 PE<15 + PB<2 +股息率>3%** → 用高级模式更直接
- **两者可结合**:先用智能筛选缩小范围,再用高级模式精修

> 💡 **高级模式的两层结构**:
> - **常用条件**:页面默认显示的 8 个常用字段(股票代码/名称、行业分类、市场类型、市值范围、市盈率(PE)、市净率(PB)、涨跌幅、成交量),覆盖 80% 场景
> - **高级字段**:默认不显示,需从"添加字段"下拉主动勾选(适用于"想加更细的条件",如 ROE、股息率、营收增速、毛利率等)
>
> 📌 **高级模式的具体操作**详见 [第 2 课:批量分析](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-02-batch-analysis.md) 的"高级模式"章节。

## 📊 对话历史:随时回到之前的筛选

左侧"筛选历史"面板记录你所有的筛选会话,不会丢失:

- **继续对话**:点击历史中的某条会话,可以重新查看/继续对话
- **新建会话**:点"新建"按钮(一般在历史列表顶部)开启新会话
- **删除单条**:鼠标悬停在某条历史上,右侧出现"删除"图标
- **清空当前会话**:在**当前会话窗口右上角**有"清空"按钮(垃圾桶图标)

## 💬 多轮对话:像聊天一样追问

智能筛选支持**多轮对话**,不用每次重新描述:

```
第 1 轮:
你: 银行股
AI: 复述 → 银行行业,大约 30 只

第 2 轮:
你: 再加个 ROE>15%
AI: 复述 → 银行行业 + ROE>15%,大约 12 只

第 3 轮:
你: 排除掉次新银行
AI: 复述 → 银行行业 + ROE>15% + 上市 > 3 年,大约 8 只
```

AI 会基于**上下文连续追问**,你只用说增量条件,不用重复。

> ⚠️ **什么时候需要新建会话?**
> - 切换**完全不同的需求**(比如"银行股" → "新能源股")时,建议新建会话,避免上下文干扰
> - 同一个筛选条件**追问超过 10 轮**时,建议新建会话(AI 可能"忘记"早期条件)

## ⚠️ 异常情况怎么办?

### 情况 1:筛出 0 只股票

- **原因**:条件太严了,比如同时要求"PE<5 + 银行股 + 总市值>1 万亿"
- **解决**:
  1. 在输入框说"放宽 PE 限制到 10"
  2. 或"市值放宽到 5000 亿"
  3. AI 会基于上下文调整

### 情况 2:筛出 1000+ 只股票

- **原因**:条件太宽,比如"科技股"(行业太大)
- **解决**:
  1. 加更细的条件:"细分到半导体""市值 200-1000 亿""ROE>10%"
  2. 或切到"高级模式"用精确字段精修
- **不建议**直接送批量分析(超过 1000 只分析会很慢)

### 情况 3:AI 复述错了

- **不要点"确认筛选"**
- 在输入框纠正:"不是 X,我想要的是 Y"
- AI 会基于上下文修正,不用重新开始

### 情况 4:页面加载慢 / 转圈很久

- 智能筛选首次加载需 1-2 秒(正常)
- 如果**超过 30 秒**还在转圈,刷新页面(F5)重试
- 还是不行,看浏览器右上角有没有"网络错误"提示

## 📌 筛选结果可以做什么?(全景)

筛选出股票后,你可以:

| 用途 | 怎么操作 | 适用场景 |
|------|---------|---------|
| **批量分析** | 点"批量分析(N)"按钮 | 5-10 只股票,需要深度研究 |
| **加入关注列表** | 卡片右上角⭐图标 | 长期跟踪,不急研究 |
| **加入自选股** | 卡片右键→"加入自选" | 常用股,方便快速查看 |
| **查看个股详情** | 点卡片股票名称 | 快速看 K 线、新闻、公告 |
| **导出 Excel** | 结果区右上角"导出"按钮 | 线下分析、做笔记 |
| **写筛选笔记** | 历史会话→点"备注"图标 | 记录筛选逻辑,以后复用 |

> 💡 **初学者建议**:前 3 个用途(批量分析/关注/自选)就够用了,其他的高级用法等熟练了再说。

## 🛠️ 实操作业(跟着做,做完就掌握)

**目标**:用智能筛选找出 3-5 只值得研究的新能源股

1. 点侧边栏「股票筛选」菜单,默认进入"智能筛选" Tab
2. 输入:**"新能源行业,总市值大于 500 亿,ROE 大于 10%,近 1 年涨幅低于 20%"**
   - 💡 解释:`总市值 > 500 亿` 排除小公司;`ROE > 10%` 选盈利能力强的;`近 1 年涨幅 < 20%` 排除已经涨得很高的(追高风险大)
3. AI 复述需求,确认后查看结果(应该会筛出 10-30 只)
4. 切换到"高级模式" Tab,看"常用条件"区被自动填上了哪些条件;也可以点"添加字段"补充"股息率"等高级条件
5. 勾选 3-5 只,点页面顶部的"**批量分析(N)**"按钮
6. 在批量分析页:
   - **分析深度** 设为"**🎯 3级 - 标准分析**"
   - **分析师团队** 保持默认(系统会自动勾选基本面 + 市场)
   - 点击页面左下角"**提交分析**"按钮
7. 系统自动跳转到「任务中心」,等任务完成(站内通知 + 邮件提醒)

**做完这次作业**,你就掌握了 v3.0 最核心的"自然语言→股票池→批量研究"全链路。

## ✅ 完成检查清单

做完实操后,对照检查:

- [ ] 能从侧边栏进入「股票筛选」页面
- [ ] 知道默认在"智能筛选" Tab
- [ ] 能用大白话输入筛选需求
- [ ] 看到 AI 复述并理解
- [ ] 会点"确认筛选"出结果
- [ ] 看到股票卡片并能勾选
- [ ] 能点"批量分析(N)"跳转到批量分析页
- [ ] 在批量分析页能选"🎯 3级 - 标准分析"
- [ ] 知道"分析师团队"默认包含基本面 + 市场
- [ ] 能提交任务并跳转到任务中心

**全部打勾?** 恭喜,你已经掌握了 v3.0 筛选功能的核心用法!

## ❓ FAQ

**Q:我没学过股票术语,能直接用吗?**
A: 完全可以。**智能筛选就是为不懂术语的人设计的**。你只说"低估值高股息的银行股",AI 会帮你翻译成 PE、股息率等专业条件。如果你想学,所有"AI 实际会筛选什么"那一列都会显示专业术语,看得多了自然就懂。

**Q:AI 复述得不对,怎么纠正?**
A: **不要点"确认筛选"!** 在输入框直接补充或纠正,比如"我说的不是 X,我想要的是 Y"或"再加个 ROE>15%"。AI 会基于上下文修正理解,不用重新开始。

**Q:支持哪些条件?**
A: A 股常见财务指标(PE/PB/ROE/股息率/营收增速/毛利率等)、技术指标、行业、市值范围、涨跌幅等约 100+ 个字段。具体字段在"高级模式 → 添加字段"下拉里能看到。**新手用户一般用不到这些**,智能筛选的 5 大类(行业/估值/市值/涨跌幅/财务)已经够用。

**Q:一次能筛多少只股票?**
A: 没有硬限制,但**建议先用智能筛选缩到 100-500 只**,再用"高级模式"精修到 50-100 只,再送批量分析。**超过 1000 只批量分析会很慢**,而且你也没那么多精力看那么多报告。

**Q:"涨得猛"、"白马"这种口语化词 AI 真能理解?**
A: 能,但有一定主观性。AI 会根据常见理解推断:
- "涨得猛" → 近 20 日涨幅前列(前 10%)
- "白马" → 行业龙头 + 基本面好(高 ROE、稳定增长)
- "冷门" → 关注度低、机构持仓少
- "妖股" → 短期暴涨、波动巨大

如果推断有偏差,**在 AI 复述时纠正**就行。

**Q:筛选结果保存多久?会不会丢?**
A: 智能筛选的对话历史保存在你的账号下,不会丢失(除非你手动删除)。高级模式的条件**不自动保存**,需要你点"保存"才能保留(在下一次进入时可以选择加载)。

**Q:"高级模式"和"智能筛选"能同时用吗?**
A: 可以!常见用法:
1. 先用智能筛选描述大方向(比如"低估值银行")
2. 切到高级模式,看到 AI 帮你填的"常用条件"区
3. 手动微调某些值(比如把 PE<10 改成 PE<15)
4. 点"添加字段",补充"股息率>3%"等高级条件
5. 点"开始筛选",出结果

这样既有 AI 的智能推断,又有你的精确控制。

**Q:筛选结果和实际市场行情有差异,正常吗?**
A: 正常。筛选是基于**历史财务数据**和**最新行情**(T-1 日收盘)的,实时行情有变化是正常的。如果你需要最新数据,可以在筛选前点"刷新数据"按钮。

**Q:能筛选 ETF 基金吗?**
A: 可以。智能筛选时直接说"低费率 ETF""沪深 300ETF""行业 ETF"等,AI 会切换到 ETF 池。高级模式里"市场类型"下拉选"ETF"即可。

## 📚 延伸阅读

- [第 2 课:批量分析——从 500 只缩到 50 只](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-02-batch-analysis.md)
- [第 3 课:单股研究入门——50 只里挑 5 只](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md)

---

### 07 Courses V3.0 Phase 01 Discover Lesson 02 Batch Analysis (`docs/07-courses/v3.0/phase-01-discover/lesson-02-batch-analysis.md`)

# 第 2 课:批量分析——从 500 只缩到 50 只

> **课时**: 25 分钟 | **难度**: ⭐⭐ 进阶 | **前置**: 第 1 课(股票筛选)

> ⚠️ **风险提示**:本课程内容仅为平台功能教学,AI 输出的研究报告不构成投资建议,最终决策由你自己负责。

## 🎯 学完后能做什么

- 一次性提交 **最多 10 只** A 股做分析
- 选择 5 个分析深度(1级快速分析 / 2级基础分析 / 3级标准分析 / 4级深度分析 / 5级全面分析)
- 勾选 7 个分析师(市场、基本面、新闻、社媒、大盘、板块,选 ETF 时多 1 个 ETF 分析师)
- 在「任务中心」菜单跟踪进度
- 在「研究报告」菜单查看对比报告

## 📍 入口

- **侧边栏**: 股票分析 → 批量研究
- **从筛选器跳转**: 在第 1 课的筛选结果点"批量分析"自动跳转

> ⚠️ **v3.0 重要变化**:批量分析页是"高级"功能,顶部有"⚠️ 重要提示:本次分析仅用于学习、研究和公开信息整理,不提供个股交易指导"风险免责。

## 🖱️ 操作步骤

### 步骤 1:进入批量分析页

1. 在侧边栏点击"股票分析 → 批量研究"
2. 进入后看到三个区域:**股票列表**(上)、**分析配置**(左)、**高级配置**(右)

### 步骤 2:选择市场(默认 A 股)

- 在"股票列表"卡片顶部,**默认是 A 股市场**(🇨🇳)
- 也可切换为 **ETF 基金**(📈),代码示例:510050、159919
- **没有港股/美股选项**——v3.0 平台仅支持 A 股和 ETF

### 步骤 3:输入股票代码

在文本框里**每行一只** 或 **逗号/空格分隔** 都可以,例如:

```
600519
000858, 300750
601919 000333
```

支持的格式:
- 数字代码:`600519`
- 多个代码用换行、逗号、空格分隔都行
- 前端会自动解析,无效代码会在"无效代码提示"中列出

**重要限制**:
- ⚠️ **单次最多 10 只股票**


> 💡 **实战技巧**:如果想分析 50 只,需要分 5 次提交(50/10)。可以先用第 1 课的"高级模式"按条件筛到 50 只,再分批送进批量分析。

### 步骤 4:选择分析深度(5 级可选)

页面里"分析深度"下拉框的实际展示名是这 5 个:

| 级别 | 页面显示名 | 耗时/只 | 适用场景 |
|------|------|---------|---------|
| 1 | ⚡ **1级 - 快速分析** | 6-10 分钟 | 大量预筛,先快后深 |
| 2 | 📈 **2级 - 基础分析** | 7-12 分钟 | 初步研究 |
| 3 | 🎯 **3级 - 标准分析**(推荐) | 8-15 分钟 | 日常研究主力 |
| 4 | 🔍 **4级 - 深度分析** | 10-20 分钟 | 重要决策前 |
| 5 | 🏆 **5级 - 全面分析** | 15-25 分钟 | 关键标的深度尽调 |

**实战建议**:
- **第一次** 看某只股票 → 选 3(标准)
- **已经看过,想多角度** → 选 4-5
- **大批量预筛** → 选 1-2

### 步骤 5:选择分析流程(可选,如果有)

- 系统会列出所有股票分析类工作流
- 默认选中系统预设的工作流
- 工作流决定了"用哪些分析师、按什么顺序分析"
- 课程第 26 课会讲如何创建自定义工作流

> 💡 **大多数用户**:不用管,直接用默认工作流即可。

### 步骤 6:选择分析师团队

**核心区分**:这里"分析师团队"勾选的是**单只分析会用到的输入角色**。**注意区分**:
- 页面"分析师团队"下能勾选的:**只有 7 个分析师**(A 股场景)
- 但**报告里实际能看到**的研究角色,还包括辩论员、研究整合员、风险评估师等

**勾选框里的 7 个分析师**(用户实际看到的):

| 分类 | 分析师(页面显示名) | 作用 |
|------|--------|------|
| **个股面** | 📈 市场分析师 | 技术面+盘面 |
| | 💰 基本面分析师 | 财务+估值 |
| | 📰 新闻分析师 | 实时新闻 |
| | 💬 社媒分析师 | 舆论情绪 |
| **宏观面** | 📊 大盘分析师 | 大盘环境 |
| | 🏭 板块分析师 | 行业地位 |
| **ETF 专有**(选 ETF 市场时才出现) | ETF分析师 | ETF 净值、跟踪误差 |

**报告里实际出现的其他研究角色**(勾选完分析师后,工作流会自动跑出来):

| 报告 Tab 名(用户看到的) | 角色 | 作用 |
|--------|------|------|
| 🐂 乐观情景研究员 | 乐观观点研究 | 找支持上涨的证据 |
| 🐻 审慎情景研究员 | 审慎观点研究 | 找支持下跌/谨慎的证据 |
| ⚡ 高弹性情景分析师 | 高弹性风险视角 | 进取型风险研究 |
| 🛡️ 防御情景分析师 | 防御风险视角 | 保守型风险研究 |
| ⚖️ 基准情景分析师 | 中性风险视角 | 客观风险研究 |
| 🔬 研究整合员 | 综合整合 | 整合所有研究 |
| 👔 风险评估师 | 风险研究 | 风险研究综合 |

**实战建议**:
- **新手**:勾选"市场分析师+基本面分析师"就够(系统默认勾这 2 个)
- **进阶**:把"大盘分析师+板块分析师"也加上,看宏观背景
- **大量预筛**:只勾"市场分析师",跑得快

### 步骤 7:配置 AI 模型(右侧高级配置)

右侧"🔧 高级配置"卡片有 **ModelConfig** 组件:
- **快速分析模型**:用于 1-2 级深度(选便宜的模型,如 qwen-plus)
- **深度分析模型**:用于 3-5 级深度(选强模型,如 qwen-max)
- 平台会按"分析深度"自动切换使用哪个模型

> 💡 **京东云用户**:模型选择受限,以平台已配置的为准,无需手动改。

### 步骤 8:提交批量分析

- 点"开始批量分析(N 只)"按钮
- 系统弹出确认框:"确定要提交批量分析任务吗?市场:A 股 数量:N 只 分析引擎:v2.0 引擎"
- 确认后,任务入队

**v2.0 引擎**是当前唯一可用的引擎(旧版引擎已隐藏)。

### 步骤 9:跟踪进度

提交后,任务会在后台跑。**注意**:

| 平台 | 并发能力 | 排队说明 |
|------|---------|---------|
| **京东云版** | 单并发(1) | ⚠️ 10 只任务串行执行,**总耗时 = 10 × 单只耗时** |
| **标准版** | 取决于配置 | 看后端 `queue_service` 配置 |

- 进入「任务中心」菜单看进度
- 或在批量分析页底部"最近分析"列表查看
- 完成的任务会显示"completed",失败显示"failed"

### 步骤 10:查看对比报告

任务完成后,有两种方式查看:

1. 点侧边栏「研究报告」菜单 → 看到所有完成的任务列表
2. **单只报告**: 点某只的"查看" → 进入报告详情页,看完整 12 个子报告

**v3.0 报告实际包含 12 个子报告 Tab**(详见第 3 课),以下都是用户在**报告详情页**里**实际看到的 Tab 名**:

| 报告 Tab 名(用户看到的) | 实际字段 key | 阶段 |
|--------|--------|------|
| 📊 大盘分析师 | index_report | 宏观 |
| 🏭 板块分析师 | sector_report | 宏观 |
| 📈 市场分析师 | market_report | 个股-技术面 |
| 💬 社交媒体分析师 | sentiment_report | 个股-情绪面 |
| 📰 新闻分析师 | news_report | 个股-消息面 |
| 💰 基本面分析师 | fundamentals_report | 个股-基本面 |
| 🐂 乐观情景研究员 | bull_researcher | 多情景-多 |
| 🐻 审慎情景研究员 | bear_researcher | 多情景-空 |
| ⚡ 高弹性情景分析师 | risky_analyst | 风险辩论 |
| 🛡️ 防御情景分析师 | safe_analyst | 风险辩论 |
| ⚖️ 基准情景分析师 | neutral_analyst | 风险辩论 |
| 👔 风险评估师 | risk_management_decision | 风险综合 |
| 🧩 研究整合员 | trader_investment_plan | 研究整合 |
| 🧾 综合研究结论 | final_trade_decision | 最终结论 |

## ⚠️ v3.0 重要变化

- ✅ **v2.0 引擎统一**:旧版引擎已隐藏,只保留 v2.0(基于工作流)
- ✅ **工作流可选**:用户可选择/创建自定义工作流(第 26 课)
- ✅ **5 级分析深度**:从 3 级扩展到 5 级(1级快速分析 / 2级基础分析 / 3级标准分析 / 4级深度分析 / 5级全面分析)
- ⚠️ **单次 10 只硬限制**:后端 / 前端双重验证,不可绕过
- ⚠️ **平台仅支持 A 股和 ETF**


## 🛠️ 实操作业

1. 点侧边栏「批量分析」菜单
2. 在文本框输入:`600519, 000858, 300750`(3 只 A 股白马)
3. 分析深度选 **3级 - 标准分析**(推荐)
4. 分析师勾选:📈 市场分析师 + 💰 基本面分析师(就是默认的 2 个)
5. 右侧"高级配置"用默认模型
6. 点"开始批量分析(3 只)"按钮
7. 在「任务中心」菜单看进度
8. 完成后,点"查看报告"看完整 14 个子报告 Tab
9. 对比 3 只的"乐观/审慎/中性"决策

**做完这次作业**,你就掌握了批量研究的完整流程。

## ❓ FAQ

**Q:为什么我提交了 12 只,被提示"最多 10 只"?**
A: 后端硬限制,需要分 2 次提交。系统没设计"超 10 自动分批"功能,需要手动操作。

**Q:3 级和 4 级差别大吗?**
A: 4 级比 3 级多一轮**辩论**——🐂 乐观情景研究员和 🐻 审慎情景研究员会就彼此观点多交锋一轮,研究更充分,出报告更慢但更全面。两个级别跑的研究员和报告 Tab 是一样的,差别在辩论轮数。如果 3 级已经够用,不用追求 4-5 级。

**Q:任务卡在"running"不动了?**
A: 京东云版单并发,前面有任务就会排队。检查「任务中心」的"队列状态",看是否有任务在前面。

**Q:任务失败(failed)怎么办?**
A: 看任务详情里的 `error_message`。常见原因:股票数据未同步(去「设置」→「系统管理」→「多数据源同步」同步)、Token 耗尽(去「研究报告」菜单内的 Token 用量页看用量)。

**Q:批量分析的报告格式和单股研究一样吗?**
A: 是的,完全一样。都是 `analysis_reports` 集合,共用 12 个子报告结构。

**Q:能用 ETF 基金做批量吗?**
A: 可以,在"市场"下拉选 ETF,然后输入 ETF 代码(如 510050)。

## 📚 延伸阅读

- [第 1 课:股票筛选](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-01-stock-screening.md)
- [第 3 课:单股研究入门](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md)
- [第 9 课:定时分析 + 跟踪节奏](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-02-track/lesson-09-scheduled-track-rhythm.md) - 解决"每天手动重复提交"的问题

---

### 07 Courses V3.0 Phase 01 Discover Lesson 03 Single Analysis Basic (`docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md`)

# 第 3 课:单股研究入门——从 50 只缩到 10 只

> **课时**: 30 分钟 | **难度**: ⭐⭐ 进阶 | **前置**: 第 1-2 课

> ⚠️ **风险提示**:本课程内容仅为平台功能教学,AI 输出的研究报告不构成投资建议,最终决策由你自己负责。

## 🎯 学完后能做什么

- 对**单只 A 股**做 5 级深度的全面研究
- 理解报告的 **14 个子报告 Tab** 是什么、怎么读
- 读懂报告里的"决策"标签(乐观/审慎/中性)
- 区分 v3.0 的**合规术语**(乐观/审慎/中性,不用"买入/卖出/持有")

## 📍 入口

- **侧边栏**: 股票分析 → 单股研究
- **Dashboard**: 点击"快速分析"按钮
- **股票详情页**: 在任意列表或报告中点击某只股票进入详情页,点顶部「分析」按钮

## 🖱️ 操作步骤

### 步骤 1:进入单股研究页

1. 左侧菜单"股票分析 → 单股研究"
2. 默认显示单股分析表单

### 步骤 2:输入股票代码(必填)

在"股票代码"输入框填 6 位 A 股代码,如:
- `600519` 贵州茅台
- `601398` 工商银行
- `300750` 宁德时代
- `601919` 中远海控

⚠️ **v3.0 限制**:仅支持 A 股(6 位数字代码)。ETF 用 `510050`、`159919` 等代码,需先在"市场"下拉切到 ETF。

### 步骤 3:(可选)选择分析基准日期

- 默认是**今天**
- 如果你想**回溯研究**(比如"回到 2025-12-31 那天,这只股票怎么样"),可以选过去的日期
- 系统会从历史数据库里取该日期的数据进行分析

### 步骤 4:数据检验(强烈推荐)

填完代码后,点"**数据检验**"按钮:
- 系统检查:历史数据/财务数据/最新行情是否都已同步
- 弹出对话框告诉你**缺哪些数据**,提供"去同步"快捷入口
- **强烈建议**在提交分析前点这个,否则任务可能因为缺数据而失败

### 步骤 5:选择分析深度(5 级)

页面里"分析深度"下拉框的实际展示名:

| 级别 | 页面显示名 | 耗时 |
|------|------|------|
| 1 | ⚡ **1级 - 快速分析** | 2-4 分钟 |
| 2 | 📈 **2级 - 基础分析** | 4-6 分钟 |
| 3 | 🎯 **3级 - 标准分析**(推荐) | 6-10 分钟 |
| 4 | 🔍 **4级 - 深度分析** | 10-15 分钟 |
| 5 | 🏆 **5级 - 全面分析** | 15-25 分钟 |

**实战建议**:
- **第一次研究某只股票** → 选 3级 标准分析
- **要写研究报告/做决策** → 选 4-5 级
- **跟踪某只已研究的股票** → 选 1-2 级快速更新

### 步骤 6:选择分析师团队(关键)

**重要**:页面"分析师团队"里**能勾选的只有 7 个**(A 股场景):

| 页面显示名 | 实际 ID | 作用 |
|---------|---------|------|
| 📈 市场分析师 | `market` | 技术面(MA/MACD/RSI/BOLL)+ 盘面 |
| 💰 基本面分析师 | `fundamentals` | 财务+估值 |
| 📰 新闻分析师 | `news` | 实时新闻 |
| 💬 社媒分析师 | `social` | 舆论情绪 |
| 📊 大盘分析师 | `index_analyst` | 大盘环境 |
| 🏭 板块分析师 | `sector_analyst` | 行业地位 |
| ETF分析师 | `etf` | 仅 ETF 市场时可选 |

**系统默认勾选**:`["市场分析师", "基本面分析师"]`

**报告里另外出现的"研究角色"**是工作流自动跑出来的,不是手动勾选:
- 🐂 乐观情景研究员 / 🐻 审慎情景研究员(2 角色辩论)
- ⚡ 高弹性情景分析师 / 🛡️ 防御情景分析师 / ⚖️ 基准情景分析师(3 风险视角)
- 🔬 研究整合员 / 👔 风险评估师(综合决策)

**实战选择**(由浅入深):

| 场景 | 推荐勾选 |
|------|---------|
| 快速了解 | 📈 市场 + 💰 基本面(2 个,默认) |
| 日常研究 | 上述 2 个 + (报告里自动跑出研究整合员+风险评估师) |
| 深度研究 | 4级/5级,辩论轮数更多、研究更充分 |
| 全面尽调 | 5级全面,勾全 7 个分析师 + 全部辩论角色 |

> 💡 **机制说明**:所有深度级别都会自动跑出辩论角色(🐂 乐观情景研究员 / 🐻 审慎情景研究员)和 3 个风险情景分析师,区别只在**辩论轮数**——1-3 级辩论 1 轮,4 级辩论 2 轮,5 级辩论 3 轮。深度越深,辩论越充分,研究越全面。

### 步骤 7:(可选)开启"执行轨迹"

- 勾选"**记录执行轨迹(排查问题时开启)**"
- 默认关闭
- 开启后,系统会记录每个 Agent 的完整执行过程(Prompt 全文、LLM 原始返回、校验结果)
- **数据量较大**,平时不开,排查问题时再开
- 第 7 阶段讲调试时会用到

### 步骤 8:提交分析

- 点"开始智能分析"按钮
- 任务入队,状态变成"分析进行中..."
- 京东云版单并发,如果前面有任务会排队

### 步骤 9:查看分析结果

任务完成后,页面会显示"**查看结果**"和"**重新分析**"两个按钮。

点"查看结果"显示完整报告(下文重点讲)。

## 📊 报告结构详解(用户能看到的部分)

### 1. 报告页面顶部的"研究简报"卡片

报告最上方有一个 **"🧾 研究简报"** 卡片,内容是 Markdown 渲染的摘要文本。

### 2. 报告页面底部的"详细研究报告"卡片

研究简报下面有一个 **"📄 详细研究报告"** 卡片,里面是按阶段的 Tab 列表。

### 3. 详细研究报告的 14 个 Tab(用户实际看到的名字)

下面这些是用户**在 Tab 上看到的名字**:

| 阶段 | 用户看到的 Tab 名(带图标) | 来自 |
|------|--------|------|
| **宏观** | 📊 大盘分析师 | index_analyst |
| | 🏭 板块分析师 | sector_analyst |
| **个股面** | 📈 市场分析师 | market_analyst |
| | 💰 基本面分析师 | fundamentals_analyst |
| | 💬 社交媒体分析师 | social_analyst |
| | 📰 新闻分析师 | news_analyst |
| **多情景研究** | 🐂 乐观情景研究员 | bull_researcher |
| | 🐻 审慎情景研究员 | bear_researcher |
| | 🔬 研究整合员 | research_team_decision |
| **研究整合** | 🧩 研究整合员 | trader |
| **风险辩论** | ⚡ 高弹性情景分析师 | risky_analyst |
| | 🛡️ 防御情景分析师 | safe_analyst |
| | ⚖️ 基准情景分析师 | neutral_analyst |
| | 👔 风险评估师 | risk_manager |
| **最终** | 🧾 综合研究结论 | 综合 |

> **Tab 显示数和深度的关系**:
> 所有深度级别都会跑相同的分析角色(含辩论和风险分析),因此报告的 Tab 集合基本一致(共 14 个 Tab)。深度主要影响**辩论轮数**(1-3 级 1 轮、4 级 2 轮、5 级 3 轮),轮数越多研究越充分、耗时越长。

### 4. "风险审阅" Tab 里的结构化字段

报告里如果包含"⚠️ 风险审阅" Tab,里面会用以下标签展示:

| 页面显示的标签 | 含义 |
|----------|------|
| **风险等级** | 低 / 中 / 高 |
| **风险评分** | 0-1 之间的小数 |
| **评估结论** | 风险综合判断(长文本) |
| **核心风险** | 风险点列表(`- ` 开头的项) |
| **风控建议** | 风险控制建议 |
| **投资调整建议** | 投资策略调整建议 |

### 5. 决策标签(报告里所有"决策"位置)

| v2.x 老术语 | v3.0 合规术语 | 含义 |
|------------|------------|------|
| BUY / 买入 / 看涨 | **乐观** | 系统看好 |
| SELL / 卖出 / 看跌 | **审慎** | 系统谨慎 |
| HOLD / 持有 / 中性 | **中性** | 系统中性 |

> v3.0 不再显示"目标价/止损价/建议仓位"等具体交易指令,统一为"乐观/审慎/中性"+ 评估结论/核心风险/风控建议/投资调整建议。

## ⚠️ v3.0 重要变化

- ✅ **5 级分析深度**(从 3 级扩展)
- ✅ **合规术语统一**(乐观/审慎/中性)
- ✅ **不再输出"目标价/止损/仓位"等交易指令**(符合监管要求)
- ✅ **风险评估结构化**(风险等级/风险评分/评估结论/核心风险/风控建议/投资调整建议)
- ⚠️ **平台仅支持 A 股和 ETF**

## 🛠️ 实操作业

1. 点侧边栏「单股研究」菜单
2. 输入 `601919` 中远海控
3. 点"**数据检验**",看是否缺数据(缺的话去同步)
4. 分析深度选 **3级 - 标准分析**
5. 分析师勾选:**📈 市场分析师 + 💰 基本面分析师**(就是默认的 2 个)
6. 提交分析
7. 等完成后,重点看:
   - 顶部 **"🧾 研究简报"** 卡片写了什么?
   - 底部"📄 详细研究报告"里**出现了几个 Tab**?
   - **"🧾 综合研究结论"** Tab 里的"决策标签"是 乐观 / 审慎 / 中性 中的哪个?
   - 报告里,有没有"⚠️ 风险审阅"Tab?里面的"风险等级/风险评分"是多少?

**做完这次作业**,你就掌握了 v3.0 单股研究的完整流程和报告阅读方法。

## ❓ FAQ

**Q:为什么我提交的分析报告里有的 Tab 内容看起来较少?**
A: 所有深度级别都会跑辩论角色(🐂 乐观情景研究员 / 🐻 审慎情景研究员)和 3 个风险情景分析师(⚡ 高弹性 / 🛡️ 防御 / ⚖️ 基准),区别在**辩论轮数**。1-3 级辩论 1 轮、4 级 2 轮、5 级 3 轮,轮数越多各 Tab 内容越充分。

**Q:报告里的"决策"显示"中性",是不是系统没给建议?**
A: 不是。"中性"是合规术语,意思是"建议持有/观望,无明确加仓或减仓信号"。要看 "⚠️ 风险审阅" Tab 里的"评估结论"了解原因。

**Q:报告里为什么不显示目标价了?**
A: v3.0 平台定位为**研究辅助工具**,根据合规要求不再提供目标价、止损止盈、买卖时机等具体交易指令。改为"风险等级/风险评分/评估结论/核心风险/风控建议/投资调整建议"等研究参考。

**Q:为什么我看到 5 级分析的耗时是 15-25 分钟,实际跑了 40 分钟?**
A: 耗时是单 Agent 估算,实际 = 所有 Agent 总耗时 + LLM 调用耗时 + 数据查询耗时 + 任务调度耗时。京东云版排队时还会更慢。

**Q:数据检验通过就能保证任务成功吗?**
A: 不一定,数据检验只查"必备数据是否已同步"。任务还可能因为:Token 耗尽、模型不可用、LLM 超时 等原因失败。

## 📚 延伸阅读

- [第 4 课:多角色辩论——怎么读懂 AI 的"🐂 积极 vs 🐻 谨慎"研究](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-04-single-analysis-multi-scenario.md)
- [第 5 课:发现阶段的常见错误](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-05-discover-pitfalls.md)

---

### 07 Courses V3.0 Phase 01 Discover Lesson 04 Single Analysis Multi Scenario (`docs/07-courses/v3.0/phase-01-discover/lesson-04-single-analysis-multi-scenario.md`)

# 第 4 课:单股研究进阶·多情景辩论——怎么读懂"乐观情景 vs 审慎情景"研究

> **课时**: 30 分钟 | **难度**: ⭐⭐⭐ 进阶 | **前置**: 第 3 课(单股研究入门)
>
> ⚠️ **风险提示**:本课程内容仅为平台功能教学,AI 输出的研究报告不构成投资建议,最终决策由你自己负责。

## 🎯 学完后能做什么

- 理解 v3.0 的 **2 角色辩论机制**(🐂 乐观情景研究员 / 🐻 审慎情景研究员)
- 读懂深度报告里的 **辩论子报告 Tab** 是什么、怎么读
- 区分 3 种**风险视角**(⚡ 高弹性 / 🛡️ 防御 / ⚖️ 基准)
- 用"辩论"模式做**重要决策前的尽调**

## 📍 入口

- **第 3 课提交的分析任务** → 完成后,报告会包含辩论子报告 Tab(所有深度都有,4-5 级辩论更充分)

## 🧠 辩论机制(用户实际看到的报告 Tab)

### 触发条件

所有深度级别都会启动辩论,区别在**辩论轮数**:1-3 级辩论 1 轮,4 级(深度)2 轮,5 级(全面)3 轮。

### 角色分工(用户看到的 Tab 名)

报告里有 3 个辩论相关 Tab:

| 用户看到的 Tab 名 | 后端 key | 立场 | 关注点 |
|------|----|------|--------|
| **🐂 乐观情景研究员** | `bull_researcher` | 乐观 | 寻找**支持上涨**的证据:增长、突破、利好、估值修复 |
| **🐻 审慎情景研究员** | `bear_researcher` | 审慎 | 寻找**支持下跌**的证据:风险、泡沫、坏消息、技术破位 |
| **🔬 研究整合员** | `research_team_decision` | 中性 | **综合两边**,出整合性结论 |

> 注意:报告**顶部**和 **Tab 上**统一显示为"🐂 乐观情景研究员/🐻 审慎情景研究员"。

### 辩论流程

1. **🐂 乐观情景研究员**先出报告(找所有积极证据)
2. **🐻 审慎情景研究员**看乐观报告后,出反驳报告(找审慎证据)
3. **🔬 研究整合员**看两份报告后,出"综合整合"结论
4. **风险辩论**(⚡ 高弹性 / 🛡️ 防御 / ⚖️ 基准)3 个情景分析
5. **👔 风险评估师**综合三方风险评估
6. **🧾 综合研究结论** 整合所有,出最终结论

> 💡 **这模拟了真实投资委员会**:多方观点碰撞,避免单点偏见。

## 🛡️ 3 风险视角(同样以 Tab 名显示)

辩论完之后,报告里出现 3 个**风险情景分析 Tab**:

| 用户看到的 Tab 名 | 后端 key | 风险偏好 | 关注点 |
|------|----|---------|--------|
| **⚡ 高弹性情景分析师** | `risky_analyst` | 进取 | **机会大于风险**,进取型视角 |
| **🛡️ 防御情景分析师** | `safe_analyst` | 保守 | **风险大于机会**,保守型视角 |
| **⚖️ 基准情景分析师** | `neutral_analyst` | 中性 | **风险机会平衡**,客观视角 |

最终 **👔 风险评估师**(`risk_management_decision`)综合三方风险评估,出 ⚠️ 风险审阅 Tab。

## 🖱️ 怎么读辩论报告

### 步骤 1:提交分析(想看最充分的辩论,选 4-5 级)

1. 点侧边栏「单股研究」菜单
2. 选深度(想看最充分的辩论,选 **4 级(深度)** 或 **5 级(全面)**)
3. 分析师勾选时,根据场景选 2-4 个(剩下研究角色是工作流自动跑出来的)
4. 提交分析

### 步骤 2:看报告 Tab 顺序

报告完成后,在**报告详情页**看完整 Tab 列表。**重点按这个顺序看**:

```
1. 📈 市场分析师 / 💰 基本面分析师        ← 客观数据
2. 🐂 乐观情景研究员                      ← 乐观观点
3. 🐻 审慎情景研究员                      ← 审慎观点
4. 🔬 研究整合员                          ← 综合
5. ⚡ 高弹性 / 🛡️ 防御 / ⚖️ 基准 风险三视角  ← 风险
6. 👔 风险评估师                          ← 风险综合
7. 🧾 研究结论                        ← 最终结论
```

### 步骤 3:识别"决策"的关键信号

读辩论报告时,关注**这些信号**:

| 信号 | 含义 |
|------|------|
| 🐂 报告**理由薄弱**(如只讲概念) | 乐观信心不足 |
| 🐻 报告**理由薄弱** | 审慎信心不足 |
| 两个研究员**结论分歧大** | 这只股票**有争议**,风险高 |
| 两个研究员**结论一致** | 共识强,可以参考 |
| 🔬 研究整合员**质疑多** | 系统在"避险",🧾 综合研究结论可能是"中性" |
| 3 个风险分析师**都偏保守** | 系统认为风险大于机会 |

## 📊 实战案例(基于真实报告样本)

**股票**: 宁德时代 300750
**分析日期**: 2026-01-24
**深度**: 5 级(全面)

### 🐂 乐观情景研究员核心结论

> "新能源行业景气度持续,公司全球市占率提升,锂电池技术领先,2025 年 Q4 出货量超预期,营收与利润增速均高于行业平均。"

### 🐻 审慎情景研究员核心结论

> "短期涨幅过快,RSI 进入超买区,行业竞争加剧(比亚迪刀片电池、固态电池冲击),估值已反映乐观预期,存在回调风险。"

### 🔬 研究整合员综合结论

> "两边都有道理:乐观方看中长期景气与业绩兑现,审慎方看短期涨幅偏大、估值已计入较多乐观预期。当前双方证据都未被充分验证,短期更可能震荡,中长期要看业绩兑现情况。"

### 🧾 综合研究结论

- **决策标签**:**中性**(系统研究结论倾向,非交易指令)
- **🧾 综合研究结论** Tab 内容:一句话结论——"当前研究判断为中性,乐观与审慎证据都未被充分验证";核心依据——"中长期景气与业绩有支撑,但短期涨幅与估值已计入较多乐观预期"
- **⚠️ 风险审阅** Tab:
  - 风险等级:中等
  - 风险评分:0.42
  - 评估结论:核心矛盾是年报信息真空而非方向失衡

> **解读**:虽然乐观与审慎两边都有依据,但**乐观方证据(中长期景气)与审慎方证据(短期估值偏高)目前都未被充分验证**,双方理由平衡,所以决策标签为"中性"。
>
> ⚠️ **重要**:决策标签"乐观/审慎/中性"是系统的研究结论倾向,**不是交易指令**。"中性"不等于"持有"或"观望",最终买卖决策由你自己判断。

## ⚠️ v3.0 重要变化

- ✅ **2 角色辩论 + 1 整合员**(🐂 乐观 / 🐻 审慎 / 🔬 整合)
- ✅ **3 风险视角**(⚡ / 🛡️ / ⚖️)
- ✅ 所有深度都跑辩论(1-3 级 1 轮、4 级 2 轮、5 级 3 轮)
- ⚠️ 报告结构:详细研究报告里有 14 个 Tab(所有深度都跑这些角色)
- ⚠️ 决策标签合规化(乐观 / 审慎 / 中性),不再有"目标价/止损价"等交易指令

## 🛠️ 实操作业

1. 选**一只你关注的股票**(还没深入研究过的)
2. 点侧边栏「单股研究」菜单,选**5 级 - 全面分析**
3. 分析师**全部勾选**(让所有分析师都跑)
4. 提交分析,等 15-25 分钟
5. 完成后按上面的"读辩论报告顺序",逐个看 14 个 Tab
6. 重点对比:
   - 🐂 乐观情景研究员 和 🐻 审慎情景研究员 的**核心结论差异**
   - 🔬 研究整合员 怎么"综合"
   - 3 个风险分析师(⚡ / 🛡️ / ⚖️)的**风险偏好倾向**
   - 🧾 综合研究结论 里的决策标签(乐观/审慎/中性)
7. 看完后,**用一句话总结**:系统对这只股票是"乐观/审慎/中性"?为什么?

**做完这次作业**,你就掌握了 v3.0 最深度的分析能力。

## ❓ FAQ

**Q:辩论机制会不会拖慢分析?**
A: 是的,4 级比 3 级慢 4-5 分钟,5 级比 4 级慢 5-10 分钟。但**重要决策前**值得多花这几分钟。

**Q:🐂 乐观 和 🐻 审慎 结论相反,我该信谁?**
A: **都信**。这正是辩论的价值——避免单点偏见。重点看 **🔬 研究整合员** 怎么综合,以及 **🧾 综合研究结论** 怎么拍板。

**Q:如果辩论最终决策标签是"乐观",是不是该买入?**
A: 不是。系统输出是**研究参考**,不是交易指令。决策标签"乐观/审慎/中性"只表达系统对这只股票的研究结论倾向,**不等于"买入/卖出/持有"**。要结合你自己的风险偏好、资金情况、市场环境 综合判断。

**Q:3 风险视角有什么用?**
A: 帮你理解"不同风险偏好的人会怎么看这只股票"。如果你是保守型,但所有风险分析师都进取,可能说明**这只股票风险确实较低**。

**Q:能不能只看辩论报告,不看技术面/基本面?**
A: 不建议。辩论是**基于基础数据的推演**,没有基础数据,辩论会"空对空"。

**Q:深度 4 级和 5 级辩论有什么区别?**
A: 两个级别跑的角色都一样(🐂 乐观 / 🐻 审慎 + 🔬 整合 + ⚡ / 🛡️ / ⚖️ 三风险视角),区别在**辩论轮数**:4 级辩论 2 轮,5 级辩论 3 轮。5 级研究更充分,但**结论通常差异不大**。

## 📚 延伸阅读

- [第 3 课:单股研究入门](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md)
- [第 5 课:发现阶段的常见错误](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-05-discover-pitfalls.md)
- [附录 A:v3.0 平台能力速查表(报告 Tab 说明)](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/appendices/A-platform-capabilities.md)
- 字段参考: [real-frontend-display-names.md](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/real-frontend-display-names.md)

---

### 07 Courses V3.0 Phase 01 Discover Lesson 05 Discover Pitfalls (`docs/07-courses/v3.0/phase-01-discover/lesson-05-discover-pitfalls.md`)

# 第 5 课:发现阶段的常见错误——从老股民的坑到 AI 时代的避雷指南

> **课时**: 25 分钟 | **难度**: ⭐ 入门 | **前置**: 第 1-4 课

> ⚠️ **风险提示**:本课程内容仅为平台功能教学,AI 输出的研究报告不构成投资建议,最终决策由你自己负责。

## 🎯 学完后能做什么

- 识别**选股阶段**最常见的 7 个错误
- 知道每个错误的**正确做法**
- 形成 v3.0 平台下的**避雷清单**

## ⚠️ 这课不教新功能,只教"不要怎么做"

前 4 课你学会了:
- 第 1 课: 自然语言筛选 + 条件筛选
- 第 2 课: 批量分析(单次 ≤ 10 只)
- 第 3 课: 单股研究(5 级深度)
- 第 4 课: 多角色辩论(所有深度都跑,区别在轮数)

这一课反过来讲:**新手最常犯的 7 个错误**,每个错误都基于真实使用场景。

## 错误 1:看了 AI 报告就当成"买入信号"

### 错误表现

> "AI 决策是'乐观'!明天开盘满仓干!"

### 为什么错

v3.0 系统输出是**研究参考**,**不是交易指令**。所有批量分析页都有顶部红色提示:

> ⚠️ **重要提示**:本次分析仅用于学习、研究和公开信息整理,不提供个股交易指导。

### 正确做法

把 AI 报告当成**第二意见**,结合:
- 自己的风险承受能力
- 当前市场环境(牛/熊/震荡)
- 资金流动性需求
- 已有持仓相关性

AI 决策"乐观"也不是 100% 就该买,**乐观只是"AI 相对有把握"**,不是"100% 对"。

> 💡 实际看报告时,**重点看 3 个维度**而不是单一分数:
> 1. **风险评分** (0-1 数字,越低越可控)
> 2. **评估结论** 的论据是否充分(是否列举具体数据/对比)
> 3. **核心风险** 列表(风险点多少、是否致命)

## 错误 2:用同一只股票的不同深度报告"凑结论"

### 错误表现

> 1 级说"乐观",3 级说"中性",5 级说"乐观"——平均一下,买入!

### 为什么错

不同深度的报告**结论可能不同**,这正是多深度的价值。**"凑"是错的**,应该看**最高级的结论**(信息最全)。

### 正确做法

- 同一只股票,优先看**最近一次、深度最高**的报告
- 5 级报告 > 4 级 > 3 级(信息密度递减)
- 不要"凑"不同深度的结论

## 错误 3:不看"评估结论",只看"决策标签"

### 错误表现

> 直接看到"决策标签 = 乐观"就买了,没看评估结论。

### 为什么错

报告"🧾 研究简报"卡片里的"评估结论"段落是 AI 的**推理过程**,告诉你**为什么**这么决策。如果论据是"短期超跌反弹",这和"长期价值投资"是完全不同的故事。

### 正确做法

1. 先看"🧾 研究简报"卡片里的 **决策标签** (乐观/审慎/中性)
2. 再看 **评估结论** (为什么这么决策的论据)
3. 最后看"⚠️ 风险审阅"里的 **风险等级/风险评分/核心风险**

"评估结论" 可能很长(几百字),但**这是 AI 推理的核心**。

## 错误 4:批量分析塞 50 只股票

### 错误表现

> 一次性把筛选的 50 只全提交批量分析,等 3 小时出结果。

### 为什么错

- **后端硬限制:单次最多 10 只**
- 京东云版**单并发**,10 只任务串行执行
- 3 级深度,10 只 × 8 分钟 = **80 分钟**起步

### 正确做法

- **分 5 批**提交(每批 10 只)
- 京东云用户尤其注意,**避免 1 次塞满**
- 如果是**预筛**(只要大致方向),选 1-2 级深度,2-5 分钟一只
- 真正重要的股票,拿出来**单独做单股研究**(5 级)

## 错误 5:依赖"自然语言筛选"做精确回测

### 错误表现

> "用 AI 筛选 2024 年涨幅前 100 的科技股,看看现在表现如何。"

### 为什么错

智能筛选(自然语言)是基于**当前 LLM 意图理解**,**不是回测工具**。每次输入同样的描述,AI 可能推断出略有不同的条件。此外,v3.0 当前**不提供回测模块**。

### 正确做法

- **当前选股** → 智能筛选(自然语言)
- **精确条件筛选** → 高级模式(条件构建器)
- **历史数据查询** → 使用历史数据查询功能

## 错误 6:港美股入口找不到了,以为是系统 bug

### 错误表现

> "系统怎么没有港股美股分析功能?以前的版本有啊!bug!"

### 为什么错

**不是 bug**。v3.0 已**主动下线港美股**前端入口,目前**仅支持 A 股和 ETF 基金**。后端代码(`foreign_stock_service.py` 2402 行)虽然还在,但前端入口**全部移除**。

### 正确做法

- 把研究范围切换到 **A 股**(主板/创业板/科创板/北交所)
- 想要指数/行业敞口?用 **ETF 基金**(510050/159919 等)
- 港美股需求暂不支持(等待后续版本)

## 错误 7:看到 "风险评分" 数字低就以为是"低风险"

### 错误表现

> "风险评分=0.3, 风险评分低,放心买。"

### 为什么错

"⚠️ 风险审阅" Tab 里的"**风险评分**"是 **0-1 的小数**,**越接近 1 越风险高**,**越接近 0 越风险低**。但**这只是 AI 的判断**,不是事实。

### 正确做法

- 看"**风险等级**"标签(更直观:低/中/高)
- 看"**评估结论**"段落里的风险论述
- 看"**核心风险**"列表(具体风险点)
- **最关键**:看 🐻 审慎情景研究员 列的**具体风险点**

"风险评分"低不代表没风险,可能只是"AI 认为风险可控"。

## ⚠️ v3.0 重要变化(避雷相关)

- ✅ **合规术语**:不用"买入/卖出",用"乐观/审慎/中性"
- ✅ **决策标签**(乐观/审慎/中性)是综合判断结果
- ✅ **批量分析单次 ≤ 10 只**
- ✅ **港美股不可用**(仅 A 股 + ETF)
- ⚠️ 所有深度都跑辩论角色(1-3 级 1 轮、4 级 2 轮、5 级 3 轮)

## 🛠️ 实操作业:做一份"避雷清单"

把你**过去**在选股时犯过的错误列出来:
1. 是哪个错误?
2. 当时发生了什么?
3. 这次在 v3.0 平台上**怎么避免**?

把清单保存到「AI 记忆」里,以后每次选股前**先看一遍**。

## ❓ FAQ

**Q:风险评分多大算"高风险"?**
A: 经验值(看页面"风险等级"标签更直观):
- 0.0-0.3:**低风险**(AI 较确信风险可控)
- 0.3-0.5:**中风险**(需关注)
- 0.5-0.8:**高风险**(谨慎)
- 0.8+:**极高风险**(基本不参与)

**Q:5 级和 3 级都跑了,结论矛盾,信哪个?**
A: 信**最高级**的(信息最全)。低级别报告只看"大方向",5 级看"细节推理"。

**Q:智能筛选的"我理解你想要 X"和我说的不一样,怎么办?**
A: 这是正常的,AI 在"复述澄清"。**不要直接点确认**,而是**在输入框补充纠正**:
- "不是 X,我想要的是 Y"
- "再补充一个条件 Z"
AI 会基于上下文修正理解。

**Q:批量分析任务卡在"分析中"很久,要不要取消重提?**
A: **先别急**。在「任务中心」菜单看进度条:
- 如果进度在动(比如从 30% 涨到 35%),正常
- 如果进度 0% 卡了 > 30 分钟,可以取消重提
取消用任务中心右侧"取消"按钮,不要"删除",删除会丢失历史记录。

**Q:数据检验通过了,任务还是失败,为什么?**
A: 数据检验只查"必备数据是否同步"。任务还可能因为:
- LLM 调用超时(网络问题)
- Token 配额耗尽(去「研究报告」菜单内的 Token 用量页看)
- 模型临时不可用(切换备用模型)
看错误提示,定位具体原因。

**Q:研究简报里的要点很少,正常吗?**
A: 正常。"🧾 研究简报" 卡片是 AI 总结的,1-5 条都可能。少于 2 条时**特别要看评估结论段落**。

## 📚 延伸阅读

- [第 1 课:股票筛选](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-01-stock-screening.md)
- [第 2 课:批量分析](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-02-batch-analysis.md)
- [第 3 课:单股研究入门](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-03-single-analysis-basic.md)
- [第 4 课:多角色辩论](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-01-discover/lesson-04-single-analysis-multi-scenario.md)
- 阶段 1 完成!进入 [阶段 2:跟踪](file:///c:/TradingAgentsCN/docs/07-courses/v3.0/phase-02-track/README.md)

---

--- METRICS ---
- Files Extracted: 28
- Estimated Token Budget: ~57589 tokens
- Canonical Reference: https://codewiki.google/github.com/hsliuping/TradingAgents-CN