# Sentiment Edge 

**Repository Path**: llm-lab/sentiment-edge

## Basic Information

- **Project Name**: Sentiment Edge 
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-05
- **Last Updated**: 2026-04-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sentiment Edge - 舆情监控与量化分析系统

> 高性能跨语言舆情监控与量化分析 Monorepo

## 🏗️ Architecture Overview

Sentiment Edge 采用三层架构设计，实现端到端的舆情分析流水线：

### 1. Python Worker (数据采集层)
- **职责**: 非结构化文本的"重负载"抓取与初步清洗
- **技术栈**: Polars + DuckDB + Playwright + BeautifulSoup
- **特点**: 并发爬取、智能清洗、Parquet 格式输出

### 2. Quant WASM (分析引擎层)
- **职责**: "极速"情绪极性评分（毫秒级）
- **技术栈**: Rust + WebAssembly
- **特点**: 零 GC 延迟、浏览器/Node.js 双端运行、高性能计算

### 3. Agent Node (调度与存储层)
- **职责**: 任务调度、DuckDB 时序存储、MCP 预警接口
- **技术栈**: Bun + TypeScript + DuckDB
- **特点**: 实时分析、时间序列查询、智能预警

## 🚀 Quick Start

### 环境要求
- Node.js 18+ (推荐使用 Bun)
- Rust 1.70+
- Python 3.11+ (推荐使用 uv)

### 安装依赖
```bash
# 安装 Rust 工具链 (如果尚未安装)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装 uv (Python 包管理器)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 初始化项目
bun install
```

### 构建项目
```bash
# 构建 WASM 模块
bun run build:wasm

# 运行开发服务器
bun run dev

# 生产环境启动
bun run start
```

### 数据采集
```bash
# 运行数据采集任务
bun run data:fetch
```

## 📁 Project Structure

```
sentiment-edge/
├── packages/
│   ├── python-worker/          # Python 数据采集
│   │   ├── src/
│   │   │   └── ingest.py       # 数据采集逻辑
│   │   └── pyproject.toml     # Python 依赖
│   ├── quant-wasm/            # Rust WASM 分析引擎
│   │   ├── src/
│   │   │   └── lib.rs         # 核心分析逻辑
│   │   ├── Cargo.toml         # Rust 依赖
│   │   └── pkg/               # WASM 编译输出
│   └── agent-node/           # TypeScript 调度节点
│       ├── src/
│       │   └── index.ts       # 主调度逻辑
│       └── package.json       # Node 依赖
├── package.json               # 根项目配置
└── README.md                 # 项目文档
```

## 🔧 Core Components

### Python Worker (packages/python-worker)

主要功能：
- Web 爬虫：支持 Playwright 自动化
- 数据清洗：智能文本预处理
- 格式转换：输出 Parquet 文件

```python
# src/ingest.py 示例
ingestor = DataIngestor()
articles = await ingestor.scrape_news_source(
    url="https://example.com/news",
    selector="article"
)
```

### Quant WASM (packages/quant-wasm)

核心函数：
- `analyze_sentiment(text: &str) -> f64`: 单文本情感分析
- `batch_analyze_sentiment(texts: Vec<String>) -> Vec<f64>`: 批量分析

```rust
// src/lib.rs 示例
#[wasm_bindgen]
pub fn analyze_sentiment(text: &str) -> f64 {
    // 返回 -1.0 到 1.0 的情感分数
    text_sentiment_score.clamp(-1.0, 1.0)
}
```

### Agent Node (packages/agent-node)

主要功能：
- 数据导入：Parquet → DuckDB
- 趋势分析：时间序列查询
- 预警系统：异常情感检测

```typescript
// src/index.ts 示例
const agent = new SentimentAgent();
const trends = await agent.getSentimentTrends(24);
const alerts = await agent.monitorForAlerts();
```

## 📊 Performance Benchmark

| 组件 | 延迟 | 吞吐量 | 适用场景 |
|------|------|--------|----------|
| Python Worker | 100-500ms | 10-100 req/s | 批量数据采集 |
| Quant WASM | 1-5ms | 10,000+ req/s | 实时情感分析 |
| Agent Node | 10-50ms | 1,000+ req/s | 时序数据查询 |

## 🔌 Integration Points

### MCP (Model Context Protocol) 接口
Agent Node 支持 MCP 协议，可接入：
- OpenAI API
- Anthropic Claude
- 其他 LLM 服务

```typescript
// MCP 示例配置
const mcpClient = new MCPClient({
    endpoint: "http://localhost:3001",
    model: "claude-3-sonnet"
});
```

### 数据流
```
新闻网站 → Python Worker → Parquet → WASM 分析 → DuckDB → 趋势/预警
```

## 🛠️ Development

### 添加新的数据源
1. 在 `packages/python-worker/src/ingest.py` 中添加爬虫逻辑
2. 更新选择器规则
3. 测试数据清洗流程

### 自定义情感分析模型
1. 在 `packages/quant-wasm/src/lib.rs` 中实现新算法
2. 更新 `analyze_sentiment` 函数
3. 重新编译 WASM

### 扩展预警规则
1. 在 `packages/agent-node/src/index.ts` 中添加新检测逻辑
2. 配置阈值参数
3. 集成通知系统

## 📈 Monitoring

### 关键指标
- 数据采集成功率
- WASM 分析延迟 (P95 < 10ms)
- 预警准确率
- 存储查询性能

### 日志级别
- ERROR: 系统错误
- WARN: 预警触发
- INFO: 正常操作
- DEBUG: 详细调试信息

## 🤝 Contributing

### 代码规范
- Rust: 遵循 rustfmt 标准
- Python: 使用 black + isort
- TypeScript: 遵循 ESLint + Prettier

### 提交规范
```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具变动
```

## 📄 License

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [Rust WebAssembly 官方文档](https://rustwasm.github.io/docs/)
- [DuckDB 官方文档](https://duckdb.org/docs/)
- [Bun 官方文档](https://bun.sh/docs)
- [uv Python 包管理器](https://docs.astral.sh/uv/)

## 🙋‍♂️ Support

如有问题或建议，请：
1. 查看 [Issues](https://github.com/your-repo/sentiment-edge/issues)
2. 提交 [Pull Request](https://github.com/your-repo/sentiment-edge/pulls)
3. 加入 [Discord 社区](https://discord.gg/sentiment-edge)