Hive

面向开源项目的 AI 智能体编排。单个 Go 二进制文件枚举 GitHub 议题和 PR，按复杂度对其进行分类，并根据队列深度在自适应节奏下将工作分派给 AI 智能体（Claude、Copilot、Gemini、Goose）。

Hive 将决策分为两层：确定性流水线由 shell 脚本组成，在任何 LLM 看到工作之前，负责处理过滤、分类、合并门控和强制执行。智能体仅处理需要判断的决策——阅读代码、推理修复方案、编写 PR。

快速开始（Docker Compose）

git clone -b v2 https://github.com/kubestellar/hive.git
cd hive/v2

cp hive.yaml.example hive.yaml
export HIVE_GITHUB_TOKEN=ghp_...
docker compose up -d

仪表盘位于 http://localhost:3001。

要从源代码构建而不是拉取预构建镜像：

docker compose build
docker compose up -d

Kubernetes 部署

先决条件

已为集群配置 kubectl
Kubernetes 1.24+
支持 ReadWriteMany 的 StorageClass（建议用于零停机滚动更新的 NFS）
cert-manager（用于 TLS 证书）
nginx-ingress（用于 ingress 路由）

托管选项

Hive Hub 提供托管的 hives，包括受 OAuth 保护的仪表板、公共注册表和跨 hive 排行榜。无需集群。

自托管部署

1. 创建命名空间

kubectl apply -f deploy/k8s/namespace.yaml

或手动操作：

kubectl create namespace hive

2. 创建 secrets

kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_... \
  --from-literal=HIVE_DASHBOARD_TOKEN=your-dashboard-auth-token

对于 GitHub App 认证（推荐用于生产环境），请添加私钥：

kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_... \
  --from-file=gh-app-key.pem=/path/to/key.pem

3. 从 hive.yaml 创建 ConfigMap

cp hive.yaml.example hive.yaml
# Edit hive.yaml: set your org, repos, agents, and governor config

kubectl create configmap hive-config -n hive --from-file=hive.yaml=hive.yaml

4. 创建 PersistentVolumeClaim

应用提供的 PVC 清单：

kubectl apply -f deploy/k8s/pvc.yaml

默认 PVC 请求 10Gi，使用 ReadWriteOnce。对于使用滚动更新的零停机滚动部署，请使用基于 NFS 的 StorageClass，并配置 ReadWriteMany：

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: hive-data
  namespace: hive
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: nfs
  resources:
    requests:
      storage: 10Gi

5. 部署

kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

部署运行单个副本，并在 /api/health 上配置存活探针和就绪探针。资源默认值：500m CPU / 512Mi 内存（requests），2 CPU / 2Gi 内存（limits）。

6. 设置带 TLS 的 Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hive
  namespace: hive
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - hive.example.com
      secretName: hive-tls
  rules:
    - host: hive.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hive
                port:
                  name: dashboard

SSE 流式连接至仪表盘需要较长的超时时间。

快速应用（所有清单）

kubectl apply -f deploy/k8s/namespace.yaml
kubectl -n hive create secret generic hive-secrets \
  --from-literal=HIVE_GITHUB_TOKEN=ghp_...
kubectl create configmap hive-config -n hive --from-file=hive.yaml=hive.yaml
kubectl apply -f deploy/k8s/pvc.yaml
kubectl apply -f deploy/k8s/deployment.yaml
kubectl apply -f deploy/k8s/service.yaml

端口

端口	用途
3001	Dashboard (supports auth token)
3002	Internal API
7681	ttyd web terminal

卷

挂载路径	用途
`/etc/hive/hive.yaml`	配置（只读，来自 ConfigMap）
`/data`	持久化状态：指标、beads、日志
`/secrets`	GitHub App 密钥及其他机密（只读）

配置

所有配置都位于单个 hive.yaml 中。环境变量使用 ${VAR} 语法进行插值。请参阅 hive.yaml.example 获取完整参考，并参阅 v2/docs/agent-configuration.md 获取完整的 agent 配置指南——包括所有字段、方法和模型发现、固定、节奏以及 ACMM 包。

project:
  org: your-org
  repos:
    - repo-one
    - repo-two
  primary_repo: repo-one
  ai_author: your-bot-user

agents:
  scanner:
    enabled: true
    backend: claude
    model: claude-sonnet-4-6
    beads_dir: /data/beads/scanner
    clear_on_kick: true

governor:
  eval_interval_s: 300
  modes:
    surge:
      threshold: 20
      scanner: 15m
      reviewer: pause
    busy:
      threshold: 10
      scanner: 15m
      reviewer: 1h
    quiet:
      threshold: 2
      scanner: 15m
      reviewer: 45m
    idle:
      threshold: 0
      scanner: 15m
      reviewer: 15m

hub:
  enabled: true
  url: https://hive.kubestellar.io
  contribute:
    enabled: true

GitHub 身份验证

使用个人访问令牌或 GitHub App：

github:
  token: ${HIVE_GITHUB_TOKEN}

github:
  app_id: 12345
  installation_id: 67890
  key_file: /secrets/gh-app-key.pem

ACMM 级别

Hive 使用一个包含六个级别的 AI 原生能力成熟度模型（ACMM），用于控制智能体被允许执行的操作：

级别	名称	智能体数量	智能体可执行的操作
L1	Inception (Assisted)	2	交互式顾问和项目启动。仅限咨询类 beads。
L2	Advisory (Instructed)	5	观察并将发现作为 dashboard beads 报告。不与 GitHub 交互。
L3	Quality-Gated (Measured)	6	Quality 智能体创建 issues 和带 hold 标签的 PRs。其他智能体保持咨询模式。
L4	Security-Aware (Adaptive)	7	所有智能体创建 issues。Quality、sec-check 和 CI 创建带 hold 标签的 PRs。
L5	Semi-Autonomous (Semi-Automated)	9	所有智能体创建带 hold 标签的 PRs。人类进行批量审查和批准。
L6	Fully Autonomous	10	智能体创建 PRs 并在 CI 通过时自动合并。无需 hold 标签。

每个级别定义了针对每个智能体的 策略模式：advisory（仅观察）、measured（创建 issues）、holdgated（带 hold 标签的 PRs）或 full（自动合并）。完整矩阵参见 v2/docs/acmm-policy-matrix.md。

架构

Hive 作为单个容器运行，包含三个长期驻留进程：

Go 二进制文件 (hive, :3002) — 大脑。运行 governor 评估循环、agent 管理器（tmux 会话）、dashboard API、进程内 MITM GitHub 代理、hub 心跳以及 token 跟踪——全部作为 goroutines。
Node.js 代理 (:3001) — 公共入口。通过认证和路径重写反向代理到 Go API，并向 dashboard 和 web 终端流式传输 SSE/WebSocket。
ttyd (:7681) — 针对 agent tmux 会话的 web 终端。

governor 在可配置的间隔上评估队列深度，并在四种模式（SURGE, BUSY, QUIET, IDLE）之间切换，每种模式具有针对每个 agent 的频率。一个确定性的流水线（Go + shell）在任何 agent 被启动之前，对所有 GitHub 工作进行过滤、分类和合并门控，并且三个独立的层——CLI 工具拒绝、最小权限范围的 token 以及网络级 MITM 代理——根据 ACMM 分配的模式来强制执行每个 agent 可以执行的操作。

flowchart LR
    github["GitHub<br/>issues · PRs"] --> gov["Governor<br/>(queue depth → mode → kick)"]
    gov --> pipe["Deterministic pipeline<br/>classify · merge-gate · enforce"]
    pipe --> agents["AI agents (tmux)<br/>Claude · Copilot · Gemini · Goose"]
    agents --> guard["Guardrails<br/>tool deny · scoped token · MITM proxy"]
    guard -->|"gated writes"| github
    agents -.-> beads["Beads ledger<br/>(git-backed work items)"]
    gov -.->|"heartbeat"| hub["Hive Hub<br/>registry · leaderboard"]
    dash["Dashboard :3001"] -.->|"SSE"| gov

参见 v2/docs/architecture.md 获取完整参考架构 — 进程模型、治理循环、确定性流水线、分层护栏、ACMM、beads、hub & spoke，以及端到端演练，全文配有 Mermaid 图表。

为 Hive 做贡献

社区成员可以通过 ClankeR 向任何 hive 贡献算力， ClankeR 是贡献者中继 — 它将 hive 积压队列中的任务分派给运行在你自己机器上的 CLI agent：

brew install just gh
git clone -b v2 https://github.com/kubestellar/hive && cd hive
just contribute-setup claude
just contribute-hive

支持的 CLI：Claude Code、GitHub Copilot、Pi、Goose、Bob。贡献者初始为新成员（受速率限制），并根据已完成的任务自动升级。您的凭据永远不会离开您的机器。

请参阅 Hive Hub 贡献页面以获取详细信息。

贡献

请参阅 Hive Hub 以浏览已注册的 hive、查看排行榜，并找到接受贡献的 hive。

若要为 Hive 本身做出贡献，请在此仓库中提交 issue 和 PR。

Apache 2.0