Initial commit

2026-07-18 15:51:01 +08:00
commit f2c80c5a9c
799 changed files with 133475 additions and 0 deletions
@@ -0,0 +1,627 @@
+# 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
+
+---
+
+# 五、日志规范
+
+统一使用：
+
+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 禁止：
+
+1. 未经允许重构已验收模块；
+2. 一次性生成整个项目；
+3. 擅自修改数据库结构；
+4. 删除已有测试；
+5. 使用 print 调试；
+6. 忽略异常；
+7. 跳过验收直接进入下一阶段；
+8. 引入未经说明的新技术栈；
+9. 将 Prompt 写死在代码中；
+10. 编写无法运行的伪代码冒充完成。
+
+---
+
+# 十九、输出格式要求
+
+Claude Code 完成任务时必须输出：
+
+【任务目标】
+
+【完成内容】
+
+【修改文件】
+
+【运行方法】
+
+【测试结果】
+
+【存在问题】
+
+【下一步建议】
+
+不得只输出代码。
+
+必须提供可验证说明。
+
+---
+
+# 二十、最高优先级原则
+
+当多个原则冲突时，优先级如下：
+
+第一优先级：
+
+代码正确、可运行。
+
+第二优先级：
+
+稳定性与可维护性。
+
+第三优先级：
+
+向后兼容。
+
+第四优先级：
+
+性能优化。
+
+第五优先级：
+
+代码优雅。
+
+宁可代码普通，也不要复杂炫技。
+
+本项目追求：
+
+“小步迭代、稳定演进、长期维护”。
+
+—— CLAUDE.md 结束 ——
+