初始化

2026-07-18 16:13:52 +08:00
parent c0070f0a5c
commit fe8b417ab6
75 changed files with 12898 additions and 1 deletions
@@ -0,0 +1,716 @@
+# CLAUDE.md
+
+# Claude Code 开发约束（English Financial News 项目）
+
+版本：v1.0
+
+最后更新：2026-06-21
+
+---
+
+# 一、项目定位
+
+本项目目标：
+
+构建面向国际财经新闻的私有化 Deep Research 平台。
+
+核心能力包括：
+
+* 英文财经新闻抓取（Crawl4AI，12 个英文源，部署海外）；
+* 英文正文提取（trafilatura）；
+* 全文英译中（LLM DeepSeek）；
+* 投资事件抽取（LLM）；
+* 双语向量知识库（Qdrant）；
+* MCP 服务 + Cherry Studio / Claude Code Agent 深度研究；
+* 每日 AI 摘要日报。
+
+本项目不是：
+
+* 自动交易系统；
+* 股票预测系统；
+* 投资顾问系统。
+
+Claude Code 必须始终围绕"研究辅助平台"进行设计。
+
+---
+
+# 二、Claude Code 总体行为准则
+
+Claude Code 必须遵守以下原则：
+
+## 2.1 分阶段开发
+
+禁止一次性完成整个项目。
+
+必须：
+
+* 每次只完成一个 Milestone；
+* 等待人工验收；
+* 验收通过后再进入下一阶段。
+
+禁止：
+
+* 擅自推进后续阶段；
+* 推翻已完成模块。
+
+Milestone 顺序严格按照 english-news-plan.md 第九节执行：
+M0 → M1 → 同步机制 → M2 → M3 → M4 → M5+M6 → M7+日报 → M8
+
+---
+
+## 2.2 最小改动原则
+
+修改代码时：
+
+优先局部修改。
+
+禁止：
+
+为了优化而重写整个模块。
+
+除非明确要求：
+
+"允许重构"。
+
+否则：
+
+保持向后兼容。
+
+---
+
+## 2.3 先理解，再编码
+
+开始编码前必须：
+
+明确：
+
+* 当前目标；
+* 输入；
+* 输出；
+* 验收标准。
+
+如果需求冲突：
+
+必须先提问。
+
+不得自行猜测。
+
+---
+
+## 2.4 部署拓扑意识
+
+本项目采用双服务器架构（详见 english-news-plan.md 第二节）：
+
+| 服务器 | SSH | 部署路径 | 职责 |
+|--------|-----|---------|------|
+| 海外 | `ssh ecs-user@8.217.19.253` | `/opt/intlgrab` | M1 抓取 → rsync 推送 |
+| 国内 | `ssh pi@192.168.1.160` | `/home/pi/intlnews` | M2→M8 全链路 + 日报 |
+
+部署优先级：
+
+* 抓取代码优先在海外服务器测试；
+* 其余代码在国内服务器测试；
+* 海外验证通过后，抓取代码同步到国内做全链路联调。
+
+编码时注意：
+
+* 海外侧只负责抓取，无 LLM/Embedding 依赖；
+* 国内侧等待 rsync 同步完成后再启动管道；
+* 哨兵文件（`SYNC_SENTINEL`）是同步完整性的关键信号；
+* `data/raw/` 目录在两台服务器上路径一致。
+
+---
+
+# 三、开发环境规范
+
+## 3.1 Python 版本
+
+统一使用：
+
+Python 3.11
+
+禁止：
+
+* Python 3.13；
+* Python 3.10 以下版本。
+
+---
+
+## 3.2 依赖管理
+
+统一使用：
+
+uv
+
+禁止：
+
+requirements.txt 手工维护。
+
+依赖定义：
+
+pyproject.toml
+
+安装命令：
+
+uv sync
+
+新增依赖：
+
+uv add 包名
+
+开发依赖：
+
+uv add --dev 包名
+
+---
+
+## 3.3 虚拟环境
+
+统一使用：
+
+.venv
+
+禁止：
+
+使用 Conda。
+
+禁止：
+
+多个虚拟环境混用。
+
+---
+
+# 四、代码规范
+
+## 4.1 类型注解
+
+所有新增代码必须包含类型注解。
+
+示例：
+
+def search_news(
+keyword: str,
+top_k: int
+) -> list[dict]:
+...
+
+禁止：
+
+省略类型。
+
+---
+
+## 4.2 中文说明
+
+要求：
+
+代码使用英文命名。
+
+注释与文档使用中文。
+
+例如：
+
+# 新闻去重处理
+
+def deduplicate_articles():
+...
+
+---
+
+## 4.3 函数长度
+
+单个函数：
+
+建议 ≤ 50 行。
+
+超过：
+
+必须拆分。
+
+---
+
+## 4.4 文件长度
+
+单文件：
+
+建议 ≤ 500 行。
+
+超过：
+
+必须拆分模块。
+
+---
+
+## 4.5 禁止魔法数字
+
+禁止：
+
+importance = 5
+
+应写成：
+
+MAX_IMPORTANCE = 5
+
+---
+
+## 4.6 数据模型
+
+统一使用 Pydantic 定义数据结构。
+
+核心模型（定义见 english-news-plan.md 第四节）：
+
+* `EnArticle` — 新闻文章（含中英文标题、正文、词数）
+* `EnExtractedEvent` — 投资事件（事件类型、股票代码、情绪、重要度）
+
+禁止：
+
+大量裸 dict 传递。
+
+---
+
+# 五、日志规范
+
+统一使用：
+
+logging
+
+禁止：
+
+print()
+
+日志级别：
+
+DEBUG
+
+INFO
+
+WARNING
+
+ERROR
+
+CRITICAL
+
+日志格式：
+
+时间 - 模块 - 级别
+消息
+
+示例：
+
+2026-06-21 06:30:00 - translator - INFO
+开始翻译 reuters 源文章 15 篇
+
+---
+
+# 六、异常处理规范
+
+禁止：
+
+except:
+pass
+
+必须：
+
+记录日志。
+
+抛出明确异常。
+
+示例：
+
+except Exception as e:
+    logger.exception(e)
+    raise
+
+---
+
+# 七、测试规范
+
+新增功能必须提供测试。
+
+优先使用：
+
+pytest
+
+测试目录：
+
+tests/
+
+命名：
+
+test_xxx.py
+
+测试覆盖：
+
+核心模块必须覆盖。
+
+包括：
+
+* crawler（M1 抓取）
+* extractor（M2 正文提取）
+* dedup（M3 去重）
+* translator（M4a 翻译）
+* llm（M4b 事件抽取）
+* embedding（M5 向量生成）
+* vectorstore（M6 Qdrant 入库/检索）
+* scheduler（M7 定时调度）
+* mcp_server（M8 MCP 服务）
+
+---
+
+# 八、配置规范
+
+## 8.1 禁止硬编码
+
+所有配置项（API Key、URL、路径、阈值、超时、并发数等）一律禁止写在代码中。
+
+常量设置必须按实际情况分配到以下位置：
+
+| 配置类型 | 存放位置 | 示例 |
+|---------|---------|------|
+| 密钥/Token | `.env` | `DEEPSEEK_API_KEY`、`DASHSCOPE_API_KEY` |
+| API 地址 | `.env` | `DEEPSEEK_BASE_URL`、`QWEN_BASE_URL` |
+| Qdrant 连接 | `.env` | `QDRANT_URL`、`QDRANT_API_KEY` |
+| 所有功能配置 | `configs/system.yaml` | 模型名、部署路径、阈值、超时、调度、日志 |
+| 新闻源定义 | `configs/sources.yaml` | 源 ID、URL 模板、JS 渲染开关 |
+
+**原则**：`.env` 仅存 SSH/API 的密钥和地址。其余全部在 `system.yaml`。
+
+代码中只允许引用配置，不允许定义配置值。
+
+正确示例：
+
+```python
+import os
+LLM_API_KEY = os.environ["DEEPSEEK_API_KEY"]
+```
+
+```python
+from yaml import safe_load
+config = safe_load(open("configs/system.yaml"))
+max_articles = config["crawler"]["max_articles_per_run"]
+```
+
+错误示例：
+
+```python
+API_KEY = "sk-xxx"           # ❌ 硬编码密钥
+LLM_TIMEOUT = 60             # ❌ 魔法数字硬编码
+SOURCES = [{"id": "reuters", ...}]  # ❌ 源配置硬编码
+```
+
+## 8.2 配置文件清单
+
+* `configs/sources.yaml` — 英文财经源定义（id / name / url_pattern / js_render 等）
+* `configs/system.yaml` — 系统级业务参数（去重阈值、LLM 超时、日报限制等）
+* `.env` — 密钥、服务地址（不入 Git）
+* `.env.example` — 脱敏示例（入 Git）
+
+## 8.3 环境变量读取规范
+
+* 始终使用 `os.environ["KEY"]`（失败时抛出明确异常），不使用默认值硬编码；
+* 如需默认值，必须在 `configs/system.yaml` 中定义，代码从配置文件读取；
+* 禁止在 `os.getenv("KEY", "hardcoded_default")` 中写死默认值。
+
+---
+
+# 九、Prompt 管理规范
+
+Prompt 必须独立维护。
+
+目录：
+
+prompts/
+
+禁止：
+
+在代码中直接拼接长 Prompt。
+
+本项目 Prompt 文件：
+
+* `translation_and_extraction.md` — 翻译 + 事件抽取（单次 LLM 调用合并输出）
+* `daily_report.md` — 日报生成 Prompt（五段式结构）
+* `search_agent.md` — MCP Agent 深度研究 Prompt
+
+---
+
+# 十、数据库规范
+
+Qdrant 为唯一向量数据库。
+
+Collection 名称：`en_finance_news`
+
+SQLite 用于：
+
+任务状态；
+缓存；
+调试。
+
+禁止：
+
+引入多种向量数据库。
+
+除非用户明确要求。
+
+---
+
+# 十一、Docker 规范
+
+所有服务必须支持 Docker。
+
+必须提供：
+
+docker-compose.yml
+
+必须支持：
+
+docker compose up -d
+
+启动。
+
+注意：
+
+* 海外侧 docker-compose 仅包含 Crawl4AI + rsync daemon；
+* 国内侧 docker-compose 包含 Qdrant + 调度器 + MCP 服务。
+
+不得依赖：
+
+手工安装。
+
+---
+
+# 十二、Git 提交规范
+
+完成每个 Milestone 后：
+
+更新：
+
+README.md
+
+continuation.md
+
+docs/
+
+提交信息格式：
+
+feat:
+新增功能
+
+fix:
+问题修复
+
+refactor:
+重构
+
+docs:
+文档更新
+
+test:
+测试
+
+chore:
+杂项
+
+示例：
+
+feat: 完成 M1 英文财经新闻抓取模块（Crawl4AI）
+
+---
+
+# 十三、README 更新规范
+
+每次功能完成后：
+
+README 必须更新：
+
+包括：
+
+功能说明；
+
+部署方法（区分海外/国内）；
+
+配置说明；
+
+示例命令；
+
+常见问题。
+
+禁止：
+
+README 长期不维护。
+
+---
+
+# 十四、continuation.md 维护规范
+
+Claude Code 每次结束工作前：
+
+必须更新 continuation.md。
+
+内容包括：
+
+当前 Milestone；
+
+完成内容；
+
+待办事项；
+
+已知问题；
+
+技术债务；
+
+下次建议。
+
+用于恢复上下文。
+
+---
+
+# 十五、性能要求
+
+目标：
+
+初始支持 12 个英文财经新闻源（见 english-news-plan.md）。
+
+逐步扩展至 ≥ 50 个源。
+
+处理吞吐：
+
+≥ 100 篇 / 分钟（端到端：抓取 → 翻译 → 入库）。
+
+Qdrant 检索：
+
+Top-K 响应时间 ≤ 2 秒。
+
+LLM 翻译：
+
+单篇平均 ≤ 3 秒（DeepSeek flash 模型）。
+
+---
+
+# 十六、翻译质量规范
+
+LLM 翻译必须：
+
+* 使用 DeepSeek 为默认 Provider（Qwen 为备选）；
+* System prompt 约束财经翻译风格：准确、简洁、专业术语一致；
+* 保留英文原标题（`title`）和中文翻译标题（`title_zh`）；
+* 保留英文原文（`content_en`）和中文翻译（`content_zh`）；
+* 中文译文字数控制在原文 1.0×–1.5× 范围。
+
+事件抽取必须：
+
+* 正确识别涉及的美股代码（如 AAPL、TSLA）；
+* 情绪判断有据可查（利好/利空/中性）；
+* 重要度 1-5 分，≥ 4 分进入日报"重要事件"板块。
+
+---
+
+# 十七、安全规范
+
+禁止：
+
+提交：
+
+.env
+
+API Key（DeepSeek / DashScope / Qwen）
+
+Cookie
+
+Token
+
+个人隐私数据
+
+SSH 私钥
+
+必须：
+
+提供：
+
+.env.example
+
+示例配置（脱敏）。
+
+---
+
+# 十八、禁止事项
+
+Claude Code 禁止：
+
+1. 未经允许重构已验收模块；
+2. 一次性生成整个项目；
+3. 擅自修改数据库结构（包括 Qdrant Collection Schema）；
+4. 删除已有测试；
+5. 使用 print 调试；
+6. 忽略异常；
+7. 跳过验收直接进入下一阶段；
+8. 引入未经说明的新技术栈；
+9. 将 Prompt 写死在代码中；
+10. 编写无法运行的伪代码冒充完成；
+11. 将海外侧依赖（LLM/Embedding）引入 M1 抓取模块；
+12. 擅自新增英文新闻源而不更新 configs/sources.yaml 和 plan。
+
+---
+
+# 十九、输出格式要求
+
+Claude Code 完成任务时必须输出：
+
+【任务目标】
+
+【完成内容】
+
+【修改文件】
+
+【运行方法】
+
+【测试结果】
+
+【存在问题】
+
+【下一步建议】
+
+不得只输出代码。
+
+必须提供可验证说明。
+
+---
+
+# 二十、最高优先级原则
+
+当多个原则冲突时，优先级如下：
+
+第一优先级：
+
+代码正确、可运行。
+
+第二优先级：
+
+稳定性与可维护性。
+
+第三优先级：
+
+向后兼容。
+
+第四优先级：
+
+性能优化。
+
+第五优先级：
+
+代码优雅。
+
+宁可代码普通，也不要复杂炫技。
+
+本项目追求：
+
+"小步迭代、稳定演进、长期维护"。
+
+---
+
+# 二十一、参考文档
+
+* `english-news-plan.md` — 项目总体计划（权威来源）
+* `docs/` — 设计文档
+* 对标项目：`news/`（A 股 Deep Research），架构模式可复用
+
+—— CLAUDE.md 结束 ——