Clarity

# Clarity

<p align="center">
  <strong>基于原生 Claude-skill 架构的金融分析智能体</strong>
</p>

<p align="center">
  <a href="./README_EN.md">English</a> | 简体中文
</p>

<p align="center">
  <a href="https://www.cooragent.com/">
    <img src="https://img.shields.io/badge/Powered%20by-Cooragent-blue?style=flat-square" alt="Powered by Cooragent">
  </a>
  <a href="https://github.com/cooragent/Clarity/stargazers">
    <img src="https://img.shields.io/github/stars/cooragent/Clarity?style=flat-square" alt="GitHub Stars">
  </a>
  <a href="https://github.com/cooragent/Clarity/issues">
    <img src="https://img.shields.io/github/issues/cooragent/Clarity?style=flat-square" alt="GitHub Issues">
  </a>
</p>

<p align="center">
  <a href="#功能特性">功能特性</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#使用方法">使用方法</a> •
  <a href="#工作流程">工作流程</a> •
  <a href="#架构设计">架构设计</a>
</p>

> 🌟 **如果这个项目对您有帮助，请给我们一个 Star！您的支持是我们持续改进的动力！**
> 
> 💡 **欢迎提出 Issue 或 PR，我们非常重视您的反馈和建议！**

---

## 简介

Clarity 是一个基于 **原生 Claude-skill** 架构构建的金融分析智能体框架。它采用 **Planning-with-Files** 模式，通过持久化的任务计划、研究发现和进度日志来协调多个专业子智能体完成复杂的金融分析任务。

### 核心特点

- 🧠 **Claude-skill 原生架构**：遵循 Anthropic 推荐的智能体设计模式
- 📁 **Planning-with-Files**：通过文件系统持久化上下文，解决 LLM 长任务"遗忘"问题
- 🤖 **多智能体协作**：6 个专业子智能体分工明确，协同完成分析任务
- 📊 **决策仪表盘**：每日自动扫描市场，推荐潜力股票
- 🔔 **多渠道推送**：支持企业微信、飞书、Telegram、邮件等多种通知渠道
- 🌐 **多市场支持**：A 股、港股、美股（纳斯达克）全覆盖

---

## 功能特性

| 功能 | 描述 | 命令 |
|:-----|:-----|:-----|
| **股票分析** | 深度分析特定股票的技术面、基本面、新闻和市场情绪 | `analyze AAPL` |
| **持仓跟踪** | 追踪知名投资者（如 Warren Buffett）的最新持仓变化 | `track "Warren Buffett"` |
| **股票筛选** | 根据复杂条件筛选符合要求的股票 | `screen "高股息科技股"` |
| **自然语言查询** | 支持中英文自然语言查询 | `ask "分析苹果公司"` |
| **决策仪表盘** | 每日扫描市场，推荐潜力股票并生成报告 | `dashboard` |

---

## 快速开始

### 安装

```bash
git clone https://github.com/your-org/Clarity.git
cd Clarity

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .
```

### 配置

创建 `.env` 文件：

```bash
# ===== 必需配置 =====
OPENAI_API_KEY=your_openai_api_key
FINNHUB_API_KEY=your_finnhub_api_key

# ===== 可选：网络搜索 =====
SERPER_API_KEY=your_serper_api_key
JINA_API_KEY=your_jina_api_key

# ===== 可选：通知渠道 =====
# 企业微信机器人
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx

# 飞书机器人
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx

# Telegram Bot
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_CHAT_ID=123456789

# 邮件 (QQ/163/Gmail 等自动识别 SMTP)
EMAIL_SENDER=your@qq.com
EMAIL_PASSWORD=授权码

# Pushover (iOS/Android 推送)
PUSHOVER_USER_KEY=xxx
PUSHOVER_API_TOKEN=xxx

# 自定义 Webhook (钉钉、Discord、Slack、Bark 等)
CUSTOM_WEBHOOK_URLS=https://oapi.dingtalk.com/robot/send?access_token=xxx
```

---

## 使用方法

### Web UI

```bash
# 启动 Web 界面
python webui.py

# 创建公开链接（通过 Gradio Share）
python webui.py --share
```

访问 http://localhost:7860 即可使用图形界面。

![Web UI 界面](assets/webui.png)

### CLI 命令

```bash
# 分析股票
python run_agent.py analyze AAPL
python run_agent.py analyze NVDA --date 2025-01-15

# 跟踪投资者持仓
python run_agent.py track "Warren Buffett"

# 筛选股票
python run_agent.py screen "high dividend yield tech stocks"

# 自然语言查询
python run_agent.py ask "分析一下苹果公司的股票"

# 决策仪表盘
python run_agent.py dashboard                           # 扫描 A股+美股
python run_agent.py dashboard -m A股 港股              # 扫描指定市场
python run_agent.py dashboard -n 20 -o report.md       # 推荐20只，保存到文件
python run_agent.py dashboard --push                   # 扫描并推送通知
python run_agent.py dashboard -p --push-to wechat      # 仅推送到企业微信
```

### Python 代码

```python
import asyncio
from tradingagents import FinancialAgentOrchestrator, AgentConfig, TaskType

async def main():
    orchestrator = FinancialAgentOrchestrator()

    # 分析股票
    result = await orchestrator.run(
        task_type=TaskType.STOCK_ANALYSIS,
        target="AAPL",
    )
    print(result["report"])

asyncio.run(main())
```

```python
# 使用通知服务
from tradingagents.core import NotificationService

notification = NotificationService()
notification.send("# 测试报告\n这是 Markdown 格式的消息")
```

---

## 工作流程

以 `run_track("Warren Buffett")` 为例，展示系统工作流程：

```
用户输入: python run_agent.py track "Warren Buffett"
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                    run_agent.py                             │
│                                                             │
│  1. 加载 .env 环境变量                                       │
│  2. 创建 AgentConfig                                        │
│  3. 创建 FinancialAgentOrchestrator                         │
│  4. 调用 orchestrator.run(task_type=HOLDINGS_TRACKING, ...) │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│               FinancialAgentOrchestrator                    │
│                                                             │
│  1. MasterAgent.create_task_plan()  ──► 初始化 task_plan.md │
│  2. WorkingAgent.execute_plan()     ──► 执行各 SubAgent     │
│  3. StateChecker.validate_step()    ──► 验证/重试        

... (truncated)