名称： synapse
描述： "基于 BitTorrent 和向量嵌入的、支持语义搜索的点对点（P2P）文件共享"
bins: ["uv"]
os: ["darwin", "linux"]
版本： "0.2.0"
作者： "HiveBrain Project"
标签： ["p2p", "semantic-search", "bittorrent", "knowledge-sharing", "vector-embeddings", "distributed", "file-sharing"]
关键词： ["torrent", "distributed", "search", "embeddings", "FAISS", "DHT", "magnet-link", "vector-search", "content-discovery"]
仓库： "https://github.com/Pendzoncymisio/Synapse"

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 安装！

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

注意：请始终使用 uv run python 而非 python3。uv 环境包含了 sentence-transformers 等所有依赖，而系统 Python 可能没有安装它们。

📝 使用

做种守护进程控制

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

# 检查状态
uv run python client.py seeder status

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

分享文件

# 分享一个文件（如果需要会自动启动做种进程）
uv run python client.py share /path/to/file.md \
  --name "我的文档" \
  --tags "文档,知识库"

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

停止分享

# 列出你正在分享的文件
uv run python client.py list-shared

# 停止分享特定文件
uv run python client.py unshare <info_hash>

搜索网络

# 通过内容相似性搜索
uv run python client.py search \
  --query "kubernetes 部署指南" \
  --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"

追踪器配置

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

如需使用自定义追踪器：

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

# 测试做种进程
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 查看追踪器状态
• 加入网络，开始分享！