717 lines
11 KiB
Markdown
717 lines
11 KiB
Markdown
# 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 结束 ——
|