simon
366e60e8a9
- 新增 report_db 包: MySQL 连接/建表/幂等写入 (news_report/news_event, myquant 库) - 新增 report_import 包: 历史 178 份日报 HTML 解析入库, 表头驱动列映射 - reporter.py 完全切换: generate_report 结构化入库, 不再生成/上传 HTML - CLI: 新增 report-import 子命令 - 依赖: uv add pymysql; 配置: NEWS_DB_* / REPORT_HISTORY_DIR - 文档: docs/report_db_design.md(实现逻辑), docs/db_schema.md(表结构供 API/前端) - 测试: 24 个单测通过 (parser/builder/models/importer)
7.9 KiB
CLAUDE.md
Claude Code 开发约束（A股 Deep Research 项目）
版本：v1.0
最后更新：2026-06-16
一、项目定位
本项目目标：
构建一个面向 A 股投资研究的私有化 Deep Research 平台。
核心能力包括：
- 财经新闻抓取；
- 中文新闻提取；
- 投资事件抽取；
- 向量知识库；
- MCP 服务；
- Cherry Studio Agent 深度研究。
本项目不是：
- 自动交易系统；
- 股票预测系统；
- 投资顾问系统。
Claude Code 必须始终围绕“研究辅助平台”进行设计。
二、Claude Code 总体行为准则
Claude Code 必须遵守以下原则：
2.1 分阶段开发
禁止一次性完成整个项目。
必须：
- 每次只完成一个 Milestone；
- 等待人工验收；
- 验收通过后再进入下一阶段。
禁止：
- 擅自推进后续阶段；
- 推翻已完成模块。
2.2 最小改动原则
修改代码时：
优先局部修改。
禁止：
为了优化而重写整个模块。
除非明确要求：
“允许重构”。
否则：
保持向后兼容。
2.3 先理解，再编码
开始编码前必须：
明确：
- 当前目标；
- 输入；
- 输出；
- 验收标准。
如果需求冲突：
必须先提问。
不得自行猜测。
三、开发环境规范
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
五、日志规范
统一使用：
loguru（现有代码全部使用 loguru，禁止混用 stdlib logging）
禁止：
print()
日志级别：
DEBUG
INFO
WARNING
ERROR
CRITICAL
日志格式：
时间 - 模块 - 级别 消息
示例：
2026-06-16 09:00:00 - crawler - INFO 开始抓取新浪财经
六、异常处理规范
禁止：
except: pass
必须：
记录日志。
抛出明确异常。
示例：
except Exception as e: logger.exception(e) raise
七、测试规范
新增功能必须提供测试。
优先使用：
pytest
测试目录：
tests/
命名：
test_xxx.py
测试覆盖：
核心模块必须覆盖。
包括：
- crawler
- extractor
- dedup
- qdrant
- llm
八、配置规范
禁止硬编码。
配置统一放置：
configs/
支持：
YAML
环境变量
.env
禁止：
API Key 写入源码。
九、Prompt 管理规范
Prompt 必须独立维护。
目录：
prompts/
禁止：
在代码中直接拼接长 Prompt。
Prompt 文件命名：
event_extraction.md
company_analysis.md
industry_analysis.md
risk_analysis.md
十、数据模型规范
统一使用：
Pydantic
禁止：
大量裸 dict。
核心对象必须定义模型。
例如：
Article
Event
EmbeddingResult
SearchResult
十一、数据库规范
Qdrant 为唯一向量数据库。
SQLite 用于：
任务状态； 缓存； 调试。
禁止：
引入多种向量数据库。
除非用户明确要求。
十二、Docker 规范
所有服务必须支持 Docker。
必须提供：
docker-compose.yml
必须支持：
docker compose up -d
启动。
不得依赖：
手工安装。
十三、Git 提交规范
完成每个 Milestone 后：
更新：
README.md
continuation.md
docs/
提交信息格式：
feat: 新增功能
fix: 问题修复
refactor: 重构
docs: 文档更新
test: 测试
chore: 杂项
示例：
feat: 完成 Crawl4AI 新闻抓取模块
十四、README 更新规范
每次功能完成后：
README 必须更新：
包括：
功能说明；
部署方法；
配置说明；
示例命令；
常见问题。
禁止：
README 长期不维护。
十五、continuation.md 维护规范
Claude Code 每次结束工作前：
必须更新 continuation.md。
内容包括：
当前 Milestone；
完成内容；
待办事项；
已知问题；
技术债务；
下次建议。
用于恢复上下文。
十六、性能要求
目标：
支持至少：
50 个财经新闻源。
支持：
并发抓取。
新闻处理吞吐：
≥100篇/分钟。
Qdrant 检索：
Top-K 响应时间 ≤ 2 秒。
十七、安全规范
禁止：
提交：
.env
API Key
Cookie
Token
个人隐私数据
必须：
提供：
.env.example
示例配置。
十八、禁止事项
Claude Code 禁止：
- 未经允许重构已验收模块；
- 一次性生成整个项目；
- 擅自修改数据库结构；
- 删除已有测试；
- 使用 print 调试；
- 忽略异常；
- 跳过验收直接进入下一阶段；
- 引入未经说明的新技术栈；
- 将 Prompt 写死在代码中；
- 编写无法运行的伪代码冒充完成。
十九、输出格式要求
Claude Code 完成任务时必须输出：
【任务目标】
【完成内容】
【修改文件】
【运行方法】
【测试结果】
【存在问题】
【下一步建议】
不得只输出代码。
必须提供可验证说明。
二十、最高优先级原则
当多个原则冲突时，优先级如下：
第一优先级：
代码正确、可运行。
第二优先级：
稳定性与可维护性。
第三优先级：
向后兼容。
第四优先级：
性能优化。
第五优先级：
代码优雅。
宁可代码普通，也不要复杂炫技。
本项目追求：
“小步迭代、稳定演进、长期维护”。
二十一、项目现状速查（2026-07 校验）
入口与常用命令
- 统一 CLI：
uv run a-share <子命令>，入口a_share_cli/main.py - 子命令：
crawl/extract/dedup/events/embed/ingest/pipeline --once/search/report/status/discover - 测试：
uv run pytest（tests/，asyncio_mode=auto；integration 标记默认跳过） - 静态检查：
uv run ruff check .、uv run mypy（pyproject.toml 已配置） - 环境：
uv sync；本地 BGE-M3 需uv sync --extra local-embedding
架构（9 个包）
| 包 | 职责 |
|---|---|
| crawler | Crawl4AI 抓取；js_render=false 走 httpx 静态直连，否则 Playwright；含 cninfo 公告 |
| extractor | GNE 中文正文提取 |
| dedup | 新闻去重（SimHash） |
| llm | DeepSeek/Qwen 投资事件抽取 |
| embedding | 远程 DashScope / 本地 BGE-M3 |
| vectorstore | Qdrant；默认本地文件模式 data/qdrant_storage/ |
| scheduler | APScheduler 调度 + pipeline + 日报 reporter |
| mcp_server | MCP 工具（供 Cherry Studio） |
| api | 占位（空包） |
scripts/ 为独立运行脚本 + systemd 服务文件 scripts/a-share-research.service。
关键约束与事实
- LLM 模型
deepseek-v4-flash绝不允许修改（记忆：never-change-llm-model） - 生产部署：Pi
pi@192.168.1.160:/home/pi/news/，systemd 服务a-share-research；改动后需 scp 同步 - 改 sources.yaml 前先从 Pi 拉取、改完推回（记忆：sync-sources-yaml）
- 配置在 configs/sources.yaml、configs/watchlist.yaml、.env；API Key 只放 .env
- Prompt 在 prompts/*.md，禁止写死在代码中
- 会话恢复上下文以 continuation.md 为准
—— CLAUDE.md 结束 ——