内容
# HiveShare
## 协作式 AI 记忆，适用于工程团队
当您和团队成员在同一个 Jira 票或 GitHub 问题上使用 Claude Code 或 Cursor 时，每次会话都会从头开始重新处理相同的上下文。HiveShare 解决了这个问题：任何一个人的人工智能代理处理的内容都存储为可搜索的记忆在共享的 **hiveshare** 中，这样其他人的代理可以立即重用它 — 无需重新阅读，无需重新总结。
```mermaid
sequenceDiagram
actor Maverick as 🧑💻 Maverick · Claude Code
participant MCP as hiveshare MCP
participant API as hiveshare server
participant DB as PostgreSQL + pgvector
participant Redis as Redis
actor Rooster as 👨💻 Rooster · Cursor
Maverick->>MCP: add_hive(PROJ-42, crunched context)
MCP->>API: POST /hiveshares/{id}/hives
API->>DB: INSERT hive · embedding = NULL
API-->>Redis: PUBLISH hive_added
API-->>Maverick: 201 · hive saved
DB-->>DB: async embed worker · UPDATE embedding
Note over DB: indexed · searchable · team-visible
Rooster->>MCP: search_hives("PROJ-42 auth flow")
MCP->>API: POST /hives/search
API->>DB: HNSW cosine similarity scan
DB-->>API: Maverick's hive · score 0.97
API-->>Rooster: full context · zero re-reading
```
---
## 功能
- **独立的 hiveshares** — 每个项目、故事或冲刺一个；完全独立的 hive 存储
- **通过电子邮件邀请** — 基于令牌，不需要 SMTP；团队成员在接受后获得自己的 API 密钥
- **实时同步** — `hiveshare stream` 显示来自任何团队成员的新条目（SSE；每个 hiveshare 一个 Redis 子频道）
- **语义搜索** — OpenAI 或 Ollama 嵌入（异步写入，HNSW 索引）；如果未配置，则回落到 PostgreSQL 全文搜索
- **MCP 集成** — Claude Code 和 Cursor 可以自动搜索和保存记忆，无需您执行任何操作
- **指标** — 重用率、顶级贡献者、源覆盖率、7 天活动
- **唯一源引用** — 每个 `source_ref` 在每个 hiveshare 中都是唯一的；重复项会自动后缀（`PROJ-42-2`），以便保存永远不会冲突
- **hive 删除** —具有写入权限的成员可以删除任何 hive；Redis 视图计数器会被清理，并且会通过 SSE 广播 `hive_deleted` 事件
- **版本历史** — 记录每个内容更改；可以回滚 hive 或在删除后取消删除
- **快照** — 捕获 hiveshare 的时间点，并恢复到 **新的** hiveshare；在空间之间复制 hive
- **强化 API** — 哈希 API 密钥、速率限制、主体大小上限、请求超时、`GET /health`
---
## 快速入门
### 1 — 启动服务器（Docker）
```bash
curl -O https://raw.githubusercontent.com/KB-perByte/hiveshare/main/docker-compose.full.yml
curl -O https://raw.githubusercontent.com/KB-perByte/hiveshare/main/.env.example
cp .env.example .env
# 编辑 .env：设置强大的 POSTGRES_PASSWORD 和您的 BASE_URL
nano .env
docker compose -f docker-compose.full.yml up -d
```
服务器现在运行在 `http://localhost:8080`（或您的 `BASE_URL`）。
### 2 — 安装 CLI
```bash
curl -sSL https://raw.githubusercontent.com/KB-perByte/hiveshare/main/install.sh | bash
```
或使用 Go 安装：
```bash
go install github.com/KB-perByte/hiveshare/cmd/hiveshare@latest
```
### 3 — 注册并创建 hiveshare
```bash
hiveshare auth register --email you@example.com --name "Maverick"
# 打印您的 API 密钥一次并将其保存到 ~/.config/hiveshare/config.json
# （服务器仅存储 SHA-256 密钥 — 现在保存它）
hiveshare create "PROJ-42 Sprint"
hiveshare list # 注意 ID
hiveshare use <uuid>
```
### 4 — 邀请队友
```bash
hiveshare invite bob@example.com
# 打印邀请链接：
# https://your-server/api/v1/invitations/<token>/accept
```
Rooster 打开链接（或 POST 到它），获取他的 API 密钥，并运行步骤 2-3，使用相同的服务器 URL。
### 5 — 连接 Claude Code
安装 MCP 二进制文件：
```bash
go install github.com/KB-perByte/hiveshare/cmd/hiveshare-mcp@latest
# 或：上面的 install.sh 已经将其放入 ~/.local/bin/
```
添加到 `~/.claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"hiveshare": {
"command": "hiveshare-mcp",
"env": {
"HIVESHARE_API_KEY": "hvs_your_key",
"HIVESHARE_SERVER_URL": "https://your-server",
"HIVESHARE_DEFAULT_HIVESHARE": "your-hiveshare-uuid"
}
}
}
}
```
重启 Claude Code。Claude 现在有五个工具：`search_hives`、`add_hive`、`list_hiveshares`、`get_context`、`get_metrics`。
### 6 — 测试
**Maverick's 终端：**
```bash
hiveshare stream # live tail — 保持此窗口打开
```
**Rooster 保存一个 hive：**
```bash
echo "PROJ-42: JWT 中间件需要验证令牌后再转发..." | \
hiveshare hive add --source-type jira --source-ref PROJ-42 --tool claude
```
Maverick 的终端立即显示：
```
[10:41:02] + hive added: jira/PROJ-42 by Rooster
```
**Maverick 搜索：**
```bash
hiveshare hive search "JWT validation"
```
---
## CLI 参考
```
hiveshare auth register --email EMAIL --name NAME [--server URL]
hiveshare auth status
hiveshare create NAME [--description TEXT]
hiveshare list
hiveshare use ID
hiveshare hive add --source-ref REF [--source-type TYPE] [--tool TOOL] [< file]
hiveshare hive search QUERY [--limit N] [--source-type TYPE]
hiveshare hive list [--source-type TYPE] [--limit N]
hiveshare hive history ENTRY_ID [--limit N]
hiveshare hive rollback ENTRY_ID --version HISTORY_ID
hiveshare hive undelete --version HISTORY_ID
hiveshare hive copy --to TARGET_HS --entries ID1,ID2
hiveshare snapshot create [--name NAME]
hiveshare snapshot list
hiveshare snapshot show ID
hiveshare snapshot restore ID [--name NAME]
hiveshare snapshot delete ID
hiveshare invite EMAIL [--role all|view]
hiveshare members list
hiveshare stream
hiveshare metrics [--me]
```
源类型：`jira`、`github_issue`、`github_pr`、`file`、`url`、`manual`
工具：`claude`、`cursor`、`manual`
角色：`all`（邀请 + 读取 + 写入）· `view`（只读）
---
## MCP 工具
| 工具 | 功能 |
|---|---|
| `search_hives` | 在 hiveshare 中进行语义或全文搜索 |
| `add_hive` | 保存处理后的上下文（在处理任何票或 PR 后调用） |
| `list_hiveshares` | 列出您所属的所有空间 |
| `get_context` | 获取特定源引用的所有 hive（例如 `PROJ-42`） |
| `get_metrics` | hiveshare 的协作统计 |
---
## 服务器配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `DATABASE_URL` | — | 完整的 Postgres DSN（覆盖各个变量） |
| `POSTGRES_*` | 见 `.env.example` | 各个数据库连接设置 |
| `REDIS_URL` | `redis://localhost:6379` | Redis 连接 URL |
| `LISTEN_ADDR` | `:8080` | HTTP 监听地址 |
| `BASE_URL` | `http://localhost:8080` | 公共 URL（用于邀请链接） |
| `EMBED_PROVIDER` | — | `openai` 或 `ollama`；为空 = 仅全文搜索 |
| `OPENAI_API_KEY` | — | `EMBED_PROVIDER=openai` 时需要 |
| `OPENAI_EMBED_MODEL` | `text-embedding-3-small` | |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | `EMBED_PROVIDER=ollama` 时需要 |
| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | |
| `HISTORY_TTL_DAYS` | `0` | 清除历史记录（天）（`0` = 永久） |
| `HISTORY_MAX_VERSIONS` | `0` | 每个 hive 的最大版本数（`0` = 无限制） |
---
## 架构
```
hiveshare CLI ──┐
├── REST + SSE ── hiveshare-server (Go)
MCP sidecar ──┘ │ 嵌入式工作线程，健康检查
┌──────┴──────┐
PostgreSQL Redis
+ pgvector 发布/订阅 + 视图计数器
HNSW
```
- 认证：Bearer `hvs_…` 密钥；**SHA-256 存储**，仅在注册时返回明文
- 写入：hive 插入立即生效；异步填充嵌入（搜索在准备好之前使用全文搜索）
- 历史记录：触发内容/摘要/标签/元数据（不是嵌入填充）；回滚 / 取消删除 / 复制
- 快照：完整 hiveshare 捕获；恢复创建新的 hiveshare（上限 10k 条目）
- `source_ref` 在每个 hiveshare 中唯一 — API 自动为重复项后缀 (`PROJ-42-2`)
- 删除：删除数据库行、Redis 视图计数器、记录使用事件，并通过 SSE 发布 `hive_deleted`
- 列表端点省略完整 `content`（使用 Get/Search 获取正文）
- 运维：`GET /health` 检查 Postgres + Redis
参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 获取图表、规模分析和 V2/V3 路线图。参见 [`API.md`](API.md) 获取完整的 HTTP 参考。参见 [`docs/INFRA_SETUP.md`](docs/INFRA_SETUP.md) 获取 ngrok、AWS EC2 和 OpenShift 部署指南。
---
## 从源代码构建
需要 Go 1.22+。
```bash
git clone https://github.com/KB-perByte/hiveshare
cd hiveshare
make deps build
# 二进制文件位于 ./bin/
# hiveshare-server — API 服务器
# hiveshare-mcp — Claude Code / Cursor 的 MCP 边车
# hiveshare — CLI
```
### 开发
```bash
# 启动 postgres + redis，运行迁移，启动服务器
make dev
# 或单独：
make docker-up
make migrate
./bin/hiveshare-server
```
---
## 基础设施
[`docs/INFRA_SETUP.md`](docs/INFRA_SETUP.md) 中的三个部署指南：
| | ngrok | AWS EC2 | OpenShift |
|---|---|---|---|
| 设置 | 5 分钟 | 30 分钟 | 45 分钟 |
| 成本 | 免费 | ~$8–10/月 | 集群成本 |
| 最适合 | 快速两人测试 | 持续团队使用 | 企业 / 现有 OCP |
OpenShift 清单位于 [`deploy/openshift/`](deploy/openshift/)。
---
## 贡献
欢迎提出问题和 PR。P0–P2 强化已完成；参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 第 7 节，了解剩余的 V2/V3 规模工作。
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
