# project_plan.md

# A股 Deep Research 私有投研平台项目计划

版本：v1.0

最后更新：2026-06-16

---

# 一、项目目标

构建一个面向 A 股投资研究的私有化 Deep Research 平台，实现：

1. 自动抓取国内财经新闻网站；
2. 支持 JavaScript 动态渲染网站；
3. 自动提取中文新闻正文；
4. 自动去重；
5. 利用大模型抽取投资事件；
6. 自动生成向量知识；
7. 构建长期财经知识库；
8. 支持语义检索；
9. 支持 Cherry Studio、Claude Code、MCP 调用；
10. 自动生成 A 股投研分析报告。

本项目定位：

> 「A 股研究辅助平台」，而非自动交易系统。

---

# 二、总体技术架构

Crawl4AI
（网页抓取）

↓

GNE
（中文正文提取）

↓

标准化处理

↓

新闻去重

↓

LLM 投资事件抽取

↓

Embedding 向量化

↓

Qdrant 向量知识库

↓

MCP 服务

↓

Cherry Studio / Claude Code Agent

↓

A 股深度研究分析

---

# 三、开发原则

Claude Code 在整个开发过程中必须遵守以下原则。

## 3.1 分阶段开发原则

严禁一次性生成整个项目。

必须按照 Milestone（里程碑）逐步开发。

每个阶段必须：

* 独立运行；
* 独立测试；
* 独立验收。

验收通过后再进入下一阶段。

---

## 3.2 生产级代码原则

所有生成代码必须满足：

* 使用 Python 类型注解；
* 必须记录日志；
* 必须具备异常处理；
* 必须支持重试机制；
* 不允许硬编码配置；
* 配置必须可修改；
* 必要时编写测试代码。

禁止为了简洁而牺牲可维护性。

---

## 3.3 配置驱动原则

网站抓取规则不得写死。

所有新闻源配置必须来自 YAML 文件。

示例：

sources.yaml

* id: sina
  enabled: true
  homepage: https://finance.sina.com.cn
  article_selector: article
  title_selector: h1

---

## 3.4 中文优先原则

本系统主要服务于中文财经研究。

优先支持：

* 财联社
* 东方财富
* 新浪财经
* 证券时报
* 中国证券网
* 界面新闻
* 第一财经
* 雪球

后续支持：

* 微博财经
* 微信公众号
* B站财经UP主
* 知乎专栏

---

## 3.5 可持续演进原则

后续新增网站时：

不得修改已有核心逻辑。

新增网站应仅通过：

* 修改配置；
* 新增适配器；

完成扩展。

---

# 四、推荐项目结构

a_share_research/

├─ app/
│
├─ crawler/            # 抓取模块
├─ extractor/          # 正文提取
├─ dedup/              # 去重模块
├─ llm/                # 大模型抽取
├─ embedding/          # 向量生成
├─ vectorstore/        # Qdrant
├─ scheduler/          # 定时任务
├─ mcp/                # MCP服务
├─ api/                # 对外接口
├─ configs/            # 配置文件
├─ prompts/            # Prompt模板
├─ tests/              # 测试
├─ scripts/            # 工具脚本
├─ logs/
├─ docs/
│
├─ main.py
├─ pyproject.toml
├─ docker-compose.yml
├─ README.md
├─ CLAUDE.md
├─ continuation.md
└─ project_plan.md

---

# 五、Milestone 1：新闻抓取模块

目标：

建立稳定可靠的新闻抓取能力。

任务：

1. 安装 Crawl4AI；
2. 验证浏览器环境；
3. 实现 crawler 模块；
4. 从 YAML 读取网站配置；
5. 支持异步并发抓取；
6. 支持导出原始 HTML；
7. 支持导出 Markdown；
8. 本地保存抓取结果。

交付物：

crawler/
configs/sources.yaml
tests/test_crawler.py

验收标准：

* 至少支持 5 个财经网站；
* 抓取成功率 ≥ 90%；
* 抓取失败自动重试。

---

# 六、Milestone 2：正文提取模块

目标：

提取高质量中文新闻正文。

任务：

1. 集成 GNE；
2. 实现 extractor 模块；
3. 自动去除广告；
4. 自动去除相关推荐；
5. 自动去除评论区；
6. 提取：

* 标题
* 正文
* 发布时间
* 作者
* 来源

统一输出格式：

{
"title":"",
"content":"",
"publish_time":"",
"author":"",
"source":""
}

交付物：

extractor/
tests/test_extractor.py

验收标准：

主流财经网站正文提取效果达到人工可接受水平。

---

# 七、Milestone 3：新闻去重

目标：

避免重复新闻污染知识库。

任务：

实现三层去重：

第一层：

URL Hash 去重；

第二层：

正文 Hash 去重；

第三层：

模糊匹配去重。

交付物：

dedup/
tests/test_dedup.py

验收标准：

重复新闻比例 ≤ 5%。

---

# 八、Milestone 4：投资事件抽取

目标：

将新闻转换为结构化投资信息。

任务：

调用 DeepSeek 或 Qwen API。

抽取：

* 股票代码；
* 公司名称；
* 所属行业；
* 利好/利空；
* 影响程度；
* 事件类型。

输出 JSON。

示例：

{
"stock_codes":["300750"],
"company_names":["宁德时代"],
"industries":["锂电池"],
"sentiment":"positive",
"importance":5,
"event_type":"合作签约"
}

交付物：

llm/
prompts/

验收标准：

JSON 输出成功率 ≥ 95%。

---

# 九、Milestone 5：Embedding 向量化

目标：

构建语义检索能力。

任务：

支持：

本地模型：

* BGE-M3；

远程API：

* Qwen Embedding；
* 百炼 Embedding。

输出：

List[float]

交付物：

embedding/

验收标准：

向量生成稳定可用。

---

# 十、Milestone 6：Qdrant 向量知识库

目标：

建立长期财经知识库。

任务：

1. Docker 部署 Qdrant；
2. 创建 Collection；
3. 定义 Payload；
4. 写入向量；
5. 支持检索；
6. 支持过滤。

交付物：

docker-compose.yml
vectorstore/

验收标准：

Top-K 检索正确。

---

# 十一、Qdrant Payload 规范

{
"id":"",
"title":"",
"content":"",
"publish_time":"",
"source":"",
"url":"",

```
"stock_codes":[],
"company_names":[],
"industries":[],

"sentiment":"",
"importance":0,
"event_type":""
```

}

---

# 十二、Milestone 7：定时任务

目标：

实现无人值守更新。

任务：

集成 APScheduler。

执行时间：

07:00

12:00

18:00

22:00

执行流程：

抓取

↓

正文提取

↓

新闻去重

↓

LLM 抽取

↓

Embedding

↓

Qdrant 入库

交付物：

scheduler/

验收标准：

能够长期稳定运行。

---

# 十三、Milestone 8：MCP 服务

目标：

支持 Agent 调用知识库。

任务：

实现 MCP 工具：

search_news

search_company_news

search_industry_news

search_stock_events

search_sentiment_trend

验收标准：

Cherry Studio 能够成功调用。

交付物：

mcp/

---

# 十四、Milestone 9：投研 Agent

目标：

生成 A 股深度研究报告。

任务：

设计 Prompt。

支持：

* 公司分析；
* 行业分析；
* 利好利空梳理；
* 新闻时间线追踪；
* 情绪变化分析；
* 风险识别；
* 投资逻辑总结。

输出：

结构化研究报告。

交付物：

docs/agent_prompt.md

验收标准：

研究报告具备实际参考价值。

---

# 十五、运行与运维要求

所有服务必须支持 Docker 部署。

要求：

* 使用 .env 管理敏感配置；
* API Key 禁止提交至 Git；
* 日志自动轮转；
* 支持增量更新；
* 支持断点恢复；
* 提供健康检查接口。

---

# 十六、非目标（Non-Goals）

本项目不负责：

* 自动下单交易；
* 股票价格预测；
* 提供投资建议；
* 保证投资收益；
* 替代人工决策。

本项目定位为：

> A 股研究辅助与知识管理平台。

---

# 十七、Claude Code 执行规则

Claude Code 必须严格遵守：

1. 每次只完成一个 Milestone；
2. 完成后停止并等待人工验收；
3. 每个阶段更新 README；
4. 未经允许不得重构已验收模块；
5. 必须保持向后兼容；
6. 需求冲突时主动提问；
7. 优先保证稳定性和可维护性；
8. 不得追求炫技式实现；
9. 所有关键设计必须记录到 docs/；
10. 每次提交前必须确认代码可运行。

项目完成标准：

> 用户能够通过 Cherry Studio 提出类似：

“请分析宁德时代最近30天的利好利空变化，并给出主要投资逻辑演化过程。”

系统自动检索知识库、分析新闻事件，并生成完整研究报告。

---

# 十八、Milestone 10：日报结构化入库（前后端分离数据层）

> 状态：✅ 已实施（2026-08-03，等待人工验收）
> 范围：本项目只负责「日报内容生成 + 结构化存入 MySQL」，**不实现 API 与前端**（由用户另行实现）。

## 背景与决策

| 决策点 | 结论 |
| --- | --- |
| DB | 192.168.1.10:13306（pi 上 autossh 隧道 → doorcome.cn:3306 MariaDB 10.11.18），业务库 `myquant`，表前缀 `news_` |
| API / 前端 | 用户另行实现，本项目只保证数据完整、表结构文档清晰 |
| 日报生成 | 完全切换：只存 DB + 前端渲染，不再生成 HTML 静态文件 |
| 历史数据 | doorcome `/var/www/html/echart/research/{YYYYMMDD}/` 下 178 份 `*_news_daily_*.html`（finance×50 + intl×128，日期 20260608~20260803），解析入库 |

## 表结构设计

### news_report（日报主表）

```sql
CREATE TABLE IF NOT EXISTS news_report (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    report_date DATE NOT NULL COMMENT '日报日期',
    report_type VARCHAR(16) NOT NULL COMMENT 'finance=A股日报 / intl=国际财经日报',
    file_name VARCHAR(160) NOT NULL DEFAULT '' COMMENT '源文件名（历史解析）；新生成可为空',
    generated_at DATETIME NOT NULL COMMENT '生成时间',
    ai_summary TEXT NULL COMMENT 'AI 摘要全文',
    stats JSON NULL COMMENT '数据总览统计快照（管道/情绪/重要度/事件类型/来源分布）',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_report_file (report_date, report_type, file_name),
    KEY idx_report_date (report_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='每日日报主表';
```

### news_event（日报事件明细，新闻联播/财经新闻/公告调研/intl 事件统一入此表）

```sql
CREATE TABLE IF NOT EXISTS news_event (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    report_id BIGINT UNSIGNED NOT NULL COMMENT 'FK → news_report.id',
    section VARCHAR(16) NOT NULL COMMENT '板块: xwlb=新闻联播 / news=财经新闻 / cninfo=公告调研 / intl=国际重要事件',
    rank INT NOT NULL DEFAULT 0 COMMENT '板块内序号',
    importance INT NULL COMMENT '重要度 1-5',
    event_type VARCHAR(64) NULL COMMENT '事件类型',
    title VARCHAR(512) NOT NULL COMMENT '标题',
    summary TEXT NULL COMMENT '摘要/正文',
    sentiment VARCHAR(8) NULL COMMENT 'positive/negative/neutral',
    source VARCHAR(64) NULL COMMENT '来源',
    url VARCHAR(512) NULL COMMENT '原文链接',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    KEY idx_report_section (report_id, section)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='日报事件明细';
```

设计说明：

- 数据总览统计（M1→M6 管道、各源数据、情绪/重要度/事件类型/来源分布）以 JSON 快照存 `news_report.stats`，前端自行解析。
- 幂等：导入/生成按 `(report_date, report_type, file_name)` 唯一键，重复执行跳过或覆盖，不产生重复行。
- 历史同一天多次生成（intl 一日 3 次）保留多行，前端取最新。

## 阶段划分（每阶段验收后进入下一阶段）

### M10-A：DB 连接层与建表

- `uv add pymysql`（纯 Python 驱动，无编译依赖）
- 新包 `report_db/`：`db.py`（连接、事务、建表）、`schema.py`（DDL）
- `.env` 新增 `NEWS_DB_HOST / NEWS_DB_PORT / NEWS_DB_USER / NEWS_DB_PASSWORD / NEWS_DB_NAME`（默认 myquant），`.env.example` 同步
- 验收：连接成功、`news_report` / `news_event` 建表成功；`tests/test_report_db.py` 通过（测试用 sqlite3 内存模拟同构 SQL，真实 MySQL 走 integration 标记）

### M10-B：历史日报解析入库

- 一次性将 doorcome 178 份 HTML 拉到 `data/reports_history/`
- 新包 `report_import/`：`parser.py`（finance/intl 两类 HTML → 结构化 dict，容错缺板块）、`importer.py`（幂等入库）
- CLI 子命令：`a-share report-import [--date YYYYMMDD] [--type finance|intl]`（默认全量）
- 验收：178 份全部入库，`SELECT COUNT(*)` 与文件数一致；抽查 finance/intl 各 2 份字段正确；重复执行不产生重复行

### M10-C：日报生成改造（完全切换）

- `scheduler/reporter.py`：`generate_report()` 改为「收集结构化数据 → 写入 news_report/news_event」，移除 `_render_html` / `_upload` 调用（函数可保留但不再触发）
- `scheduler/pipeline.py` 调用签名保持兼容（仍调 `generate_report(day_str)`）
- 验收：`uv run a-share report --date YYYYMMDD` 后 DB 出现当日记录且无 HTML 文件产出；AI 摘要、事件行、stats JSON 完整

### M10-D：文档与收尾

- `docs/db_schema.md`：完整表结构 + 字段说明 + 示例数据（供用户实现 API/前端）
- 更新 README、continuation.md；提交信息 `feat: 日报结构化入库`

## 待确认项（不阻塞开发，部署前需用户决策）

1. **生产连接**：pi5（192.168.1.160）无法直连 `192.168.1.10:13306`（隧道只绑 loopback）。可选：a) pi 的 autossh 改为绑定 0.0.0.0（需改 pi 系统配置）b) pi5 自建隧道 c) 其他
2. **intl 日报生成方**：项目代码中无 intl 生成逻辑（doorcome 上另有来源）。历史解析照做；未来 intl 新日报如需入库，由生成方按同一表结构写入
3. **个股日报**（002714.SZ_0724.html 等 research 根目录文件）：本期不处理，如需请另行提出

—— project_plan.md 结束 ——