内容
# 首页
> 自托管个人档案博客：导入您的社交媒体历史，搜索，交互，并将其交给您的大型语言模型。
Homebound 将您多年来分散在 Google+、Facebook 和 Twitter/X 上的内容收集起来，存放在您可控的 Django 博客中，并为人类和语言模型提供了良好的方法来查找其中的内容。
**状态：** alpha。维护者的部署运行在 [vyakunin.org](https://vyakunin.org)；使用它作为表面外观的参考。在第 2 阶段发布之前，API 和数据库架构可能会在没有通知的情况下更改。
## 工具列表
- **导入管道** — 适配器用于 Google+ Takeout HTML/CSV、Facebook 活动日志导出（通过捆绑的浏览器扩展）和 Twitter/X 导出 + Wayback Machine 重建
- **浏览器扩展** （也在 Chrome 网上应用商店中）： [Homebound：活动日志导出器](https://chromewebstore.google.com/detail/kaghpmdkjknpefjhfjgmnaclmhalgbkb) （Facebook） 和 [Homebound：时间线导出器](https://chromewebstore.google.com/detail/gidophdcplhcbkelkejbeogdnnkmndni) （X/Twitter） — 将您自己的数据导出到本地 ZIP；没有任何数据离开您的机器
- **Django 博客** — 文章列表 + 详情，标签云，全文搜索，RSS，JSON-LD `BlogPosting` 结构化数据，年分片站点地图
- **Markdown 编辑器** — EasyMDE 支持的创作，带有 OG 元数据获取
- **语义搜索（第 1.3 阶段）** — Voyage 嵌入 + pgvector，用于整个存档的自然语言查询
- **MCP 服务器（第 1/2.7 阶段）** — 用于 Claude Desktop / Cursor 的 stdio 模式；工具包括 `search_posts`，`get_post`，`on_this_day`，`search_media`，`get_timeline`，`ghostwrite`
- **公共机器人小部件（第 2.5 阶段，可选）** — 您站点上的聊天界面，根据您的公开帖子回答访客问题，并提供引用
参见 [`docs/HIGH_LEVEL_DESIGN.md`](docs/HIGH_LEVEL_DESIGN.md) 了解架构，[`docs/STAGE_1_FOUNDATIONS.md`](docs/STAGE_1_FOUNDATIONS.md) / [`docs/STAGE_2_LLM_FEATURES.md`](docs/STAGE_2_LLM_FEATURES.md) 了解路线图。
## 快速入门（Docker）
```bash
git clone https://github.com/vyakunin/homebound.git
cd homebound
cp .env.example .env # 填写数据库凭证 + 可选的 API 密钥
docker compose up -d
# 等待迁移完成，然后访问 http://localhost:8080
```
## 快速入门（本地开发，使用 Bazel）
```bash
bazel build //...
bazel test //tests:all # 测试门户 — 运行整个包，而不是子集
bazel run //:runserver # localhost:8080
```
测试 **仅** 通过 Bazel 运行（`bazel test //tests:all`）— 而不是裸 `pytest`。
下面的 venv 用于一次性管理命令，而不是测试套件。
通过 venv 运行管理命令（Bazel 沙箱缺少 `allauth` 的传递依赖）：
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements_lock.txt
DJANGO_SETTINGS_MODULE=django_config.settings PYTHONPATH="bazel-bin:." \
python manage.py import_posts --source google_plus --input-dir ./takeout/
```
## MCP 设置（stdio，Claude Desktop 或 Cursor）
在第 3 阶段完成后：
```json
{
"mcpServers": {
"homebound": {
"command": "docker",
"args": ["exec", "-i", "homebound-web", "homebound", "mcp"]
}
}
}
```
可用工具：`search_posts`，`get_post`，`on_this_day`，`search_media`，`get_timeline`，`ghostwrite`.
## API 密钥（可选，启用 LLM 功能）
| 密钥 | 解锁功能 | 获取方式 |
|---|---|---|
| `VOYAGE_API_KEY` | 嵌入式语义搜索，MCP `search_posts`，机器人 RAG | [dash.voyageai.com](https://dash.voyageai.com/) |
| `ANTHROPIC_API_KEY_GHOSTWRITER` | MCP `ghostwrite` 工具（私人创作） | [console.anthropic.com](https://console.anthropic.com/) |
| `ANTHROPIC_API_KEY_PUBLICBOT` | 公共机器人小部件（单独密钥，以便在不影响创作的情况下撤销滥用） | 同上 |
没有密钥，语义搜索 + MCP `ghostwrite` + 公共机器人将被禁用；博客和全文搜索无需任何外部服务即可工作。
## 部署
此存储库中的 Docker Compose 是 *通用* 自托管设置。对于您自己的生产部署（TLS，反向代理，备份，监控），请保留一个私有覆盖存储库。维护者的覆盖存储库是 `homebound-platform`；将其视为一个示例，而不是依赖项。
## 许可证
[AGPL-3.0](LICENSE)。如果您托管 Homebound 的修改版本并通过网络提供服务，则必须向用户提供您的修改。
## 贡献
问题和 PR 欢迎。提交前请运行 `bazel test //tests:all`；CI 在每个 PR 上运行相同的测试。
