HorizonBrute/Horizon-Brain-Builder
GitHub: HorizonBrute/Horizon-Brain-Builder
一套 CLI 部署工具链，用于构建和部署自包含的 RAG 运行时（ChromaDB + Ollama + nginx 网关），支持 Windows WSL2 和原生 Linux 环境。
Stars: 0 | Forks: 0
# Brain Builder
**通过一套 CLI 工具链构建并部署 _brains_ —— 独立封装的 RAG 运行时。**
一个“brain”是一个自包含的检索栈：位于 **nginx token 网关之后的 ChromaDB + Ollama**，运行在 Windows 上专用的 **WSL2 发行版**或 Linux 上的 **rootless Docker** 中。
所有访问均受 token 控制，且网络环境完全封闭；该网关是唯一的入口。
本仓库是**代码**（构建工具），绝不是运行中的 brain。新的 brain 是由它*实例化*而来的；
已部署的 brain 会运行此代码树的**专属分阶段副本**。
## 两类受众 —— 从适合您的部分开始
### 🤖 如果您是 AI agent：正确安装并熟悉环境
**首先判断您处于哪种环境：**
| 信号 | 您是… | 执行此操作 |
|---|---|---|
| 已设置 `$HORIZON_SYSTEM` / `$HORIZON_ROOT` 且存在 `horizon_system/` 目录树 | **在 Horizon.AIOS 实例内部** | **作为 Options Package 安装**（见下文）。它会注册构建器并注入发现指针 —— 工具链依然在克隆目录中*就地*运行；**不会向**操作系统**复制任何内容**。 |
| 没有 `HORIZON_*` 环境变量，也没有 Horizon.AIOS 目录树 | **独立主机** | **不要安装任何内容。** 直接克隆代码仓库，并通过 orchestrator 传递 `--install-root `（或设置 `$AIOS_INSTALL_ROOT`）来直接部署 brain。 |
**作为 Horizon AIOS Options Package 安装**（幂等操作，仅使用标准库，支持 Python 3.8+）：
```
git clone https://github.com/HorizonBrute/Horizon-Brain-Builder \
"$HORIZON_SYSTEM/deployed_packages/horizon_brain_builder"
python "$HORIZON_SYSTEM/deployed_packages/horizon_brain_builder/aios/install/horizon_brain_builder_package.py" install
```
`install` → 将发现指针注入 `projects/agents.md`，在
`horizon_deployed_packages.local.json` 中注册该 package（以便 Horizon.AIOS 同步能够**保护、更新和备份它**），并将
克隆目录设置为只读(pull-only)。`uninstall` 会撤销上述两项操作，且**完全不影响克隆目录和任何已部署的 brain**。
`update` = `git fetch` + 重置为上游版本。`status` 用于打印注册表视图。
**完整约定：[`aios/INSTALL.md`](aios/INSTALL.md)。**
### 🧑 如果您是真人：了解并使用该工具
您可以在每个主机 OS 上运行一个 **orchestrator**；它将每个步骤（OS 账户 → WSL/Docker 引擎 →
网关 → 常驻状态）整合为一个单一收敛的 `deploy` 命令，以及其逆向操作：
```
# Windows / WSL2 — 从 elevated shell 中：
python windows_deploy_brain.py deploy --brain mybrain --install-root C:\brains --posture personal
python windows_deploy_brain.py verify --brain mybrain
python windows_deploy_brain.py status --brain mybrain
python windows_deploy_brain.py teardown --brain mybrain [--purge --yes]
# Native Linux — 使用 sudo：
sudo python3 linux_deploy_brain.py deploy --brain mybrain --install-root /srv/brains --posture personal
sudo python3 linux_deploy_brain.py teardown --brain mybrain [--purge --yes]
```
`--posture personal` 会将网关仅绑定到主机 loopback；`--posture server` 会将其暴露在
局域网中（执行此操作前请查阅安全模型）。直接运行 `deploy` 会将代码重新分发到现有的 brain；
`--from-scratch` 会从基础镜像重新构建引擎。**完整选项及操作指南：**
**[`DEPLOYMENT.md`](factory/source/system/brain_bin/DEPLOYMENT.md)。**
## 两种模式的实际差异
| | 独立部署 | 作为 Horizon AIOS Options Package |
|---|---|---|
| **安装步骤** | 无 —— 克隆并运行 | `aios/install/horizon_brain_builder_package.py install` |
| **安装根目录** | `--install-root ` 或 `$AIOS_INSTALL_ROOT`（显式指定 —— 没有默认值，不进行猜测） | 相同；在 Horizon.AIOS 内部也可以回退到 `$HORIZON_ROOT` |
| **Brain 密码** | OS 密钥环，brain 专属的 namespace `brain:` | 相同（核心部分不依赖 Horizon.AIOS 的 keystore） |
| **`HORIZON_*` 环境变量** | **在核心部分任何地方均非必需** | 仅由 `aios/` 包装器读取，brain 构建核心从不读取 |
| **更新** | 自行运行 `git pull` | Horizon.AIOS 同步运行 `update` 并将克隆备份到其远程仓库 |
独立模式的接口是实际生效的代码，而不是存根：`factory/create_brain.py` 是独立的 brain 配置提供程序
（支持 `--install-root`，使用 brain 专属的 keyring），并且 deployer 会明确指定安装根目录，否则直接终止运行。
**`aios/` 包装器是 _唯一_ 允许了解 Horizon.AIOS 的地方。**
## 仓库布局
```
README.md ← you are here (the front door)
VERSION ← package version (semver); the installer reads it
LICENSE ← AGPL-3.0
windows_deploy_brain.py ← Windows/WSL2 deploy orchestrator (host-side; run elevated)
linux_deploy_brain.py ← native-Linux deploy orchestrator (systemd + rootless Docker; run with sudo)
factory/ ← build tooling + brain image (dir keeps its historical name; the deploy staging root)
create_brain.py ← standalone brain-provisioning provider (OS account/group/ACL/keyring)
source/ ← THE BRAIN IMAGE: exactly the tree a deployed brain gets (copied at deploy)
system/brain_bin/ ← tier-1 canon: operator tooling + the operational docs (ship into each brain)
system/brain_sbin/ ← tier-1 canon: config generator, gateway, port/token tooling
system/common_neuron_platform/ ← the neuron bundle images (input = write side, action = read side)
brain_etc.example/ ← the config-seam template (brain.env, gateway, docker, tls, …)
docs/ ← package documentation (index, gateway auth, network diagrams)
aios/ ← the OPTIONAL Horizon AIOS Options Package wrapper (installer + INSTALL.md)
```
## 文档导航
- **[`docs/README.md`](docs/README.md)** — canon → instance → runtime 的**三层模型**以及
orchestrator 参考说明（说明 `deploy` 会复制什么内容，以及何时复制）。
- **[`docs/index.md`](docs/index.md)** — 完整的文档索引。
- **运维文档（它们随每个已部署的 brain 一起分发，位于 `system/brain_bin/` 中）：**
[`DEPLOYMENT.md`](factory/source/system/brain_bin/DEPLOYMENT.md) ·
[`OPERATIONS.md`](factory/source/system/brain_bin/OPERATIONS.md) ·
[`TROUBLESHOOTING.md`](factory/source/system/brain_bin/TROUBLESHOOTING.md) ·
[`brain_security_model.md`](factory/source/system/brain_bin/brain_security_model.md)
- **网关授权：** [`docs/gateway_bearer_auth_SOP.md`](docs/gateway_bearer_auth_SOP.md) 以及
手动验证 [`gateway_auth_verification_matrix.md`](docs/gateway_auth_verification_matrix.md)。
- **作为 Horizon AIOS Options Package 安装：** [`aios/INSTALL.md`](aios/INSTALL.md)。
## 环境要求
- **Windows：** 带有 **WSL2** 的 Windows 10/11；在**管理员权限(elevated)**的 shell 中运行 orchestrator。
- **Linux：** **systemd** + **rootless Docker**；使用 **sudo** 运行 orchestrator。
- **Horizon.AIOS 安装程序**（`aios/install/…`）**仅依赖标准库**，要求 Python 3.8+ —— 无需任何第三方依赖。
## 版本与许可
`VERSION` = **0.2.0**。采用 **AGPL-3.0** 许可（详见 [`LICENSE`](LICENSE)）。
Options Package 的 namespace 是 `horizon_brain_builder_*` —— 绝不是 `horizon_aios_*`（后者属于操作系统核心）。
标签：AI风险缓解, ChromaDB, Docker, LLM评估, Ollama, RAG, WSL2, 人工智能, 安全防御评估, 用户模式Hook绕过, 请求拦截, 逆向工具