# wemusic-rs

**Repository Path**: wemusic/wemusic-rs

## Basic Information

- **Project Name**: wemusic-rs
- **Description**: WeMusic core written with Rust.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WeMusic (Rust Implementation)

WeMusic 分布式音乐共享平台的 Rust 实现。

> 拉取代码时，建议将设计规范拉取到 `../specs/` 目录。

## 项目结构

本项目采用 Cargo Workspace 组织，所有 crate 位于 `crates/` 目录下。

```
wemusic-rs/
├── Cargo.toml               # Workspace 根定义
├── crates/
│   ├── wemusic-core/        # 核心类型、Error、工具函数
│   ├── wemusic-protocol/    # P2P 网络协议（MessagePack、Noise、DHT）
│   ├── wemusic-storage/     # 存储层（SQLite、索引、缓存）
│   ├── wemusic-daemon-core/ # Daemon 业务核心（网络、索引、传输、信誉等）
│   ├── wemusic-api/         # 本地管理 API（HTTP / IPC / WebSocket）
│   ├── wemusic-daemon/      # Daemon 可执行文件入口
│   └── wemusic-cli/         # CLI 工具入口
```

### Crate 职责与依赖

| Crate | 职责 | 内部依赖 |
|-------|------|---------|
| `wemusic-core` | PeerID、ContentHash、统一 Error 类型、通用工具 | 无 |
| `wemusic-protocol` | P2P 协议实现：MessagePack 帧格式、Noise XX 握手、Kademlia DHT、节点发现、传输通道 | `core` |
| `wemusic-storage` | 本地音乐库索引、下载缓存、配置持久化 | `core` |
| `wemusic-daemon-core` | Daemon 业务逻辑：P2P 网络管理、内容索引、传输调度、信誉计算、安全防御、媒体文件服务 | `core`, `protocol`, `storage` |
| `wemusic-api` | 本地管理 API：路由分发、认证、HTTP/IPC/WebSocket 服务端、IPC 客户端 | `core`, `daemon-core` |
| `wemusic-daemon` | Daemon 进程入口：组装并启动所有模块 | `daemon-core`, `api[server]` |
| `wemusic-cli` | 命令行工具：通过 IPC 与 Daemon 交互 | `core`, `api[client]` |

### Feature 设计

`wemusic-api` 通过 Cargo feature 控制编译内容：

- `server`：启用 HTTP / IPC / WebSocket 服务端（Daemon 使用）
- `client`：启用 IPC 客户端（CLI 使用）

## 快速开始

### 环境要求

- Rust >= 1.85 (Edition 2024)
- Cargo

### 构建

```bash
# 构建整个 workspace
cargo build

# 构建 Release 版本
cargo build --release

# 仅构建 Daemon
cargo build -p wemusic-daemon

# 仅构建 CLI
cargo build -p wemusic-cli
```

### 运行

```bash
# 启动 Daemon
cargo run -p wemusic-daemon

# 使用 CLI
cargo run -p wemusic-cli -- <command>
```

### 测试

```bash
# 运行所有测试
cargo test

# 运行指定 crate 的测试
cargo test -p wemusic-core
```

## 开发规范

### 代码组织

- 每个 crate 的公共 API 在 `src/lib.rs` 中通过 `pub mod` 显式暴露
- 模块内部实现细节保持私有，除非有明确的跨模块调用需求
- `wemusic-daemon-core` 内部按功能划分为子模块（`p2p/`, `indexer/`, `transfer/` 等），子模块通过 `mod.rs` 聚合

### 与 Specs 的协作

- specs 包含所有设计规范（`design-key.md`, `network-protocol.md`, `system-architecture.md` 等）
- 实现代码必须遵循 specs 定义的接口契约，但具体技术选型由代码决定
- 当发现 specs 与实现存在冲突时，优先修改 specs 保持一致性，而非擅自偏离设计

### P0 / P1 / P2 优先级

Specs 将功能分为三级优先级：

- **P0**：核心必须实现（MVP），如无此功能项目不可用
- **P1**：推荐实现，显著提升可用性与安全性
- **P2**：可选功能，锦上添花或特定场景需要

开发排期应优先完成 P0 功能，确保核心链路可运行后再扩展。

### 错误处理

- 统一使用 `wemusic-core::error` 中定义的 Error 类型
- 库代码使用 `thiserror` 定义结构化错误
- 应用代码（daemon/cli）使用 `anyhow` 进行错误传递和上下文增强

### 日志与可观测性

- 使用 `tracing` 进行结构化日志记录
- 日志级别遵循 specs 定义的数据敏感分级策略（L1/L2/L3）
- P2P 消息处理需携带 `rid`（Request ID）用于跨模块追踪

## 开发计划

### P0 — 核心骨架（MVP）

- [ ] **wemusic-core**：基础类型（PeerID、ContentHash、Address）、统一 Error 体系
- [ ] **wemusic-protocol**：P2P 协议实现（MessagePack 帧格式、Noise XX 握手、Kademlia DHT、节点发现、传输通道）
- [ ] **wemusic-storage**：存储层（SQLite Schema 与迁移、本地音乐库索引、下载缓存管理、配置热加载）
- [ ] **wemusic-daemon-core**：核心模块骨架（P2P 网络管理、内容索引与扫描、传输调度、媒体文件服务）
- [ ] **wemusic-api**：本地管理接口（路由分发、Token 认证、IPC / HTTP / WebSocket 传输）
- [ ] **wemusic-daemon + wemusic-cli**：可运行的 Daemon 入口与 CLI 控制工具
- [ ] **集成测试**：双节点直连拓扑（Noise 握手、Metadata 交换、单文件下载）

### P1 — 能力提升

- [ ] **信誉引擎**：MLR 五维信誉计算、背书与观察期机制
- [ ] **安全防御**：ACL 策略、速率限制、证书固定管理、启动自检
- [ ] **内容治理**：合规熔断器、内容举报、本地黑名单
- [ ] **流媒体**：HTTP Range 字节流推送、边下边播
- [ ] **搜索质量**：信誉加权排序、结果去重、渐进式搜索
- [ ] **审计与隐私**：分层日志、审计导出、日志擦除、多法域适配

### P2 — 扩展功能

- [ ] **趣味功能**：同步听歌房间（Gossipsub）、去中心化打榜
- [ ] **插件系统**：WASM 沙箱、插件注册与权限隔离
- [ ] **网络增强**：mDNS 自动发现、内网 Relay、NAT 穿透评估
- [ ] **多租户**：部门/频道隔离、ACL 过滤增强

## 许可证

[待补充]