Synapse 协议 - 安装与使用

基于语义搜索的点对点文件共享。可共享任意文件，通过内容相似度进行查找。

功能与架构说明，请参阅 README.md。

🚀 安装

前置条件

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

快速安装

bash

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 可能未安装这些组件。

📝 使用说明

种子守护进程控制

bash

启动种子守护进程（后台运行）

uv run python client.py seeder start

查看状态

uv run python client.py seeder status

停止守护进程

uv run python client.py seeder stop

共享文件

bash

共享文件（必要时自动启动种子程序）

uv run python client.py share /path/to/file.md \
--name 我的文档 \
--tags 文档,知识

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

停止共享

bash

列出当前共享的文件

uv run python client.py list-shared

停止共享特定文件

uv run python client.py unshare <信息哈希>

网络搜索

bash

按内容相似度搜索

uv run python client.py search \
--query Kubernetes 部署指南 \
--limit 10

返回：按相似度排序的结果

下载文件

bash

使用搜索结果中的磁力链接下载

uv run python client.py download \
--magnet magnet:?xt=urn:btih:... \
--output ./downloads

⚙️ 配置

环境变量

bash
export SYNAPSE_PORT=6881
export SYNAPSEDATADIR=./synapse_data

追踪器配置

默认追踪器：http://hivebraintracker.com:8080

使用自定义追踪器：
bash
uv run python client.py share file.txt --trackers http://tracker1.com,http://tracker2.com

🔍 测试安装

bash

检查 uv 是否安装

uv --version

测试命令行界面（首次运行自动安装依赖）

uv run python client.py --help

测试种子程序

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

问题：种子守护进程无法启动

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

问题：搜索返回 0 条结果

• - 解决方案：确保文件共享时已注册嵌入向量（检查追踪器日志）

📚 可用命令

share - 共享文件并支持语义搜索
unshare - 停止共享文件
list-shared - 列出当前共享的文件
seeder - 控制种子守护进程（启动/停止/状态/重启）
search - 按内容搜索网络
download - 通过磁力链接下载文件
generate-magnet - （旧版）无需守护进程生成磁力链接
setup-identity - 生成 ML-DSA-87 身份标识

📖 后续步骤

• - 阅读 README.md 了解功能与架构
• 在 http://hivebraintracker.com:8080/api/stats 查看追踪器状态
• 加入网络，开始共享！