news/CLAUDE.md

# 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 禁止：

1. 未经允许重构已验收模块；
2. 一次性生成整个项目；
3. 擅自修改数据库结构；
4. 删除已有测试；
5. 使用 print 调试；
6. 忽略异常；
7. 跳过验收直接进入下一阶段；
8. 引入未经说明的新技术栈；
9. 将 Prompt 写死在代码中；
10. 编写无法运行的伪代码冒充完成。

---

# 十九、输出格式要求

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 结束 ——