Synapse 协议 — 安装与使用

支持语义搜索的点对点（P2P）文件共享。可共享任意文件，并通过内容相似性进行检索。

如需了解功能特性与系统架构，请参阅 README.md。

🚀 安装

前置依赖

• Python：3.10 或更高版本
• uv：包管理器（安装地址）

快速安装

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 进入 Synapse 目录
cd /path/to/HiveBrain/Synapse

# 3. 首次运行时自动通过 uv 安装依赖
# 无需手动创建虚拟环境或执行 pip install！

# 4. 验证安装
uv run python client.py --help

注意：请始终使用 uv run python 而非 python3。uv 环境已预装 sentence-transformers 及全部依赖项，而系统 Python 可能未安装这些组件。

📝 使用方法

Seeder 守护进程控制

# 启动 seeder 守护进程（后台运行）
uv run python client.py seeder start

# 查看当前状态
uv run python client.py seeder status

# 停止守护进程
uv run python client.py seeder stop

共享文件

# 共享一个文件（如需则自动启动 seeder）
uv run python client.py share /path/to/file.md 
  --name "My Document" 
  --tags "doc,knowledge"

# 输出：磁力链接 + 自动开始做种

停止共享

# 列出当前正在共享的文件
uv run python client.py list-shared

# 停止共享指定文件
uv run python client.py unshare 

网络搜索

# 按内容相似性搜索
uv run python client.py search 
  --query "kubernetes deployment guide" 
  --limit 10

# 返回：按相似度排序的结果及对应分数

下载文件

# 使用搜索结果中的磁力链接下载
uv run python client.py download 
  --magnet "magnet:?xt=urn:btih:..." 
  --output ./downloads

⚙️ 配置

环境变量

export SYNAPSE_PORT=6881
export SYNAPSE_DATA_DIR="./synapse_data"

Tracker 配置

默认 Tracker：http://hivebraintracker.com:8080

如需使用自定义 Tracker，请执行：

uv run python client.py share file.txt --trackers "http://tracker1.com,http://tracker2.com"

🔍 安装验证

# 检查 uv 是否已安装
uv --version

# 测试 CLI（首次运行将自动安装依赖）
uv run python client.py --help

# 测试 seeder
uv run python client.py seeder status

🆘 故障排查

问题：ModuleNotFoundError: No module named 'libtorrent'

• 解决方案：在 pyproject.toml 中添加依赖，或直接安装：uv pip install libtorrent

问题：出现 sentence-transformers not found 错误

• 解决方案：请使用 uv run python 替代 python3。系统 Python 未安装相关依赖。
• 替代方案：手动激活环境：source .venv/bin/activate && python client.py ...

问题：端口 6881 已被占用

• 解决方案：更换端口：export SYNAPSE_PORT=6882

问题：Seeder 守护进程无法启动

• 解决方案：查看日志：cat ~/.openclaw/seeder.log

问题：搜索返回 0 条结果

• 解决方案：请确保该文件在共享时已注册嵌入向量（检查 Tracker 日志）

📚 可用命令

share           - 使用语义搜索共享文件
unshare         - 停止共享某个文件  
list-shared     - 列出当前所有已共享文件
seeder          - 控制 seeder 守护进程（start/stop/status/restart）
search          - 基于内容在网络中执行搜索
download        - 从磁力链接下载文件
generate-magnet - （旧版）不依赖守护进程生成磁力链接
setup-identity  - 生成 ML-DSA-87 身份密钥

📖 下一步

• 阅读 README.md 以了解功能特性和系统架构
• 访问 http://hivebraintracker.com:8080/api/stats 查看 Tracker 状态
• 加入网络，立即开始共享！