Initial commit

2026-07-18 15:51:01 +08:00
commit f2c80c5a9c
799 changed files with 133475 additions and 0 deletions
@@ -0,0 +1,606 @@
+# 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天的利好利空变化，并给出主要投资逻辑演化过程。”
+
+系统自动检索知识库、分析新闻事件，并生成完整研究报告。
+
+—— project_plan.md 结束 ——
+