BiliCore 是一个集单 Agent 编排、声明式多 Agent 系统与对抗性安全测试于一体的开源 LLM 应用框架，帮助开发者和研究者在统一环境中构建、运行并评估大语言模型驱动的复杂智能体应用。
# BiliCore：一个开源的 LLM 框架
**BiliCore** 是一个开源的、特定领域无关的框架，用于构建和测试由 LLM 驱动的应用程序。它在一个模块化包中提供了单 Agent 编排、多 Agent 系统创建以及对抗性安全测试。
bili-core 最初是为 MSU Denver 的 [**Community-Centered Computing (C3) Lab**](https://c3-lab.org/) 开发的，用于 [**Colorado Sustainability Hub**](https://sustainabilityhub.co/)，现在作为该实验室多个研究项目背后的框架。由 **[National Science Foundation (NSF)](https://www.nsf.gov/)** 和 **[NAIRR Pilot](https://nairrpilot.org/)** 资助。
## 三大组件
BiliCore 被组织为三个命名的组件，每个组件解决一个独特的问题：
### IRIS — 交互式推理与集成服务
**单 Agent 编排。** 涵盖 17 种提供商类型的 106 种模型配置。
IRIS 将用户与 LLM、工具和数据源连接起来。它提供了一个基于节点的工作流 pipeline，其中每个步骤（角色注入、工具执行、内存管理、响应规范化）都是一个可组合的节点。支持在对话中途切换模型、动态配置工具以及跨会话持久化状态。
- **API 提供商：** AWS Bedrock、Google Vertex AI、Azure OpenAI、OpenAI、Anthropic（直接）、Mistral AI、Cohere、Google Generative AI、DeepSeek、xAI (Grok)、Groq
- **CLI 提供商：** Claude Code CLI、OpenAI Codex CLI、Google Gemini CLI（子进程，`tool_strategy="mcp"`），以及一个适用于任何文本输入/文本输出 LLM 工具的通用 CLI 子进程提供商
- **本地提供商：** llama.cpp (GGUF 模型)、HuggingFace (GPTQ/transformers)
- **Fallback 引擎：** `FallbackLLM` 将多个提供商链接起来，以便在主提供商发生瞬时错误时静默重试列表中的下一个提供商
- **工具调用模式：** `native`（bind_tools，API 提供商）、`facilitated`（为纯文本/本地模型手动编写的提示 ReAct 循环）、`mcp`（Agent 工具作为临时的经过身份验证的 MCP 服务器公开；CLI 自编排）、`none`（无工具支持 — 纯路径）
- **临时 MCP 服务器：** `tool_strategy="mcp"` 在每次调用时启动一个进程内的 MCP 服务器（FastMCP + uvicorn，SSE 传输），使用随机环回端口；每次调用使用独立的 Bearer-token 身份验证；为 Claude Code、Codex 和 Gemini CLI 提供独立的注入器；如果没有注册注入器，则回退到无工具模式（绝不以未验证状态启动）
- **工具：** FAISS 向量搜索、OpenSearch、天气 API、网络搜索、可扩展的工具注册表
- **中间件：** 摘要、模型调用限制、自定义中间件
- **Checkpointer：** MongoDB、PostgreSQL、内存中 —— 全部支持可查询的对话管理
- **MCP 子系统：** `bili/iris/mcp/` 涵盖两个方向：(1) MCP 客户端 —— Agent 以 LangChain 工具的形式使用来自外部 MCP 服务器（stdio 或 HTTP/SSE）的工具；(2) MCP 服务器 —— 通过临时服务器将 Agent 的工具暴露给生成的 CLI LLM。安装：`pip install bili-core[mcp]`
- **流式传输：** 通过同步和异步 API 实现逐 token 响应
- **位置：** `bili/iris/`
### AETHER — 用于测试、强化、评估和研究的 Agent 生态系统
**多 Agent 编排。** 声明式 YAML 配置。
AETHER 允许你使用 YAML 定义多 Agent 系统 (MAS) 并将其编译为可执行的 LangGraph 工作流。每个 Agent 都可以拥有自己的 LLM、工具、角色和多节点处理 pipeline。Agent 通过具有可配置协议的类型化通道进行通信。
- **7 种工作流类型：** 顺序、分层、主管、共识、并行、协商、自定义
- **6 种通信协议：** 直接、广播、请求-响应、发布-订阅、竞争、共识
- **Pipeline 子图：** 单个 Agent 内部的多节点 pipeline
- **自定义状态字段：** 带有 reducer 和默认值的类型安全 YAML 状态声明
- **运行时注入：** 用于将依赖项注入到 pipeline 节点的 `RuntimeContext` 容器
- **流式传输：** 带有结构化 `StreamEvent` 对象和 `StreamFilter` 的 `MASExecutor`
- **位置：** `bili/aether/`
### AEGIS — 智能系统的对抗性评估与防护
**针对多 Agent 系统的安全测试。** 基于 AETHER 构建。
AEGIS 提供了一个系统化的框架，用于测试对抗性 payload 如何在多 Agent 系统中传播。它会在不同阶段（执行前、执行中、checkpoint）注入攻击，跟踪 Agent 之间的传播情况，并使用三层检测系统评估合规性。
- **7 个测试套件：** Prompt 注入、越狱、内存投毒、偏见继承、Agent 冒充、持久化、跨模型可转移性
- **三层检测：** 结构化（CI 安全）、启发式（传播跟踪）、语义化（基于 LLM 的评分）
- **基线比较：** 用于受控前后分析的真实运行器
- **结果查看器：** 用于攻击结果和基线分析的交互式 Streamlit 仪表板
- **攻击 GUI：** 通过图形可视化交互式运行对抗性攻击
- **位置：** `bili/aegis/`
## 快速开始
### 前置条件
- **Docker**：[获取 Docker](https://docs.docker.com/get-docker/) — 所有服务都在容器中运行
- **Git**：用于克隆代码仓库
### 1. 克隆并配置
```
git clone https://github.com/msu-denver/bili-core.git
cd bili-core
cp .env.example .env
# 使用你的 API keys (AWS, Google, OpenAI 等) 编辑 .env
```
### 2. 启动开发环境
```
cd scripts/development
./start-container.sh
./attach-container.sh
```
这将启动 bili-core 容器以及 PostgreSQL（包含 PostGIS）、MongoDB 和 LocalStack 服务。该容器会自动激活 Python 虚拟环境并设置 shell 别名。
### 3. 运行应用程序
在容器内部：
```
streamlit # Start the Streamlit UI on port 8501
flask # Start the Flask API on port 5001
```
### 4. 访问应用程序
- **Streamlit UI：** http://localhost:8501
- `/aether` — AETHER 多 Agent 系统（可视化工具、聊天、攻击套件）
- `/bili` — 单 Agent RAG 测试界面
- `/attack-results` — AEGIS 攻击结果查看器
- `/results` — 基线结果查看器
- **Flask API：** http://localhost:5001
## 架构概览
```
bili-core/
├── bili/
│ ├── iris/ # IRIS: Single-agent orchestration
│ │ ├── loaders/ # Graph builder, streaming, tool/middleware/LLM loaders
│ │ ├── nodes/ # Pipeline nodes (persona, datetime, react agent, etc.)
│ │ ├── graph_builder/ # Node and edge class definitions
│ │ ├── config/ # LLM, tool, and middleware configurations
│ │ ├── tools/ # Tool implementations (FAISS, OpenSearch, weather, etc.)
│ │ └── checkpointers/ # State persistence (MongoDB, PostgreSQL, memory)
│ │
│ ├── aether/ # AETHER: Multi-agent orchestration
│ │ ├── schema/ # MASConfig, AgentSpec, WorkflowType, Channel definitions
│ │ ├── compiler/ # YAML → LangGraph compilation (graph builder, LLM resolver)
│ │ ├── runtime/ # MASExecutor, streaming, communication state
│ │ ├── config/examples/ # Example YAML configurations
│ │ ├── integration/ # Checkpointer factory for MAS
│ │ ├── validation/ # Static MAS validation engine
│ │ └── ui/ # Streamlit pages (chat, visualizer, attack, results)
│ │
│ ├── aegis/ # AEGIS: Adversarial security testing
│ │ ├── attacks/ # Attack injector, propagation tracker, strategies
│ │ ├── evaluator/ # Semantic evaluator, scoring rubrics
│ │ ├── security/ # Security event detector, logger
│ │ └── tests/ # 7 attack suites + baseline + analysis
│ │
│ ├── auth/ # Shared: Authentication (Firebase, SQLite, in-memory)
│ ├── utils/ # Shared: Logging, LangGraph utilities, file I/O
│ ├── prompts/ # Shared: Prompt templates
│ ├── streamlit_ui/ # Shared: Streamlit UI components
│ ├── flask_api/ # Shared: Flask API utilities
│ ├── streamlit_app.py # Unified Streamlit entry point
│ └── flask_app.py # Flask API entry point
│
├── docs/ # Project-level documentation
├── scripts/ # Development and build scripts
├── .env.example # Environment variable template
├── docker-compose.yml # Full development stack
└── requirements.txt # Python dependencies
```
## 代码示例
### IRIS：单 Agent 流式传输
```
from bili.iris.loaders.langchain_loader import build_agent_graph
from bili.iris.loaders.streaming_utils import stream_agent, invoke_agent
agent = build_agent_graph(checkpoint_saver=saver, node_kwargs=kwargs)
# 非流式
response = invoke_agent(agent, "What is the weather?", thread_id="user1")
# 流式 — 在 token 到达时生成它们
for token in stream_agent(agent, "What is the weather?", thread_id="user1"):
print(token, end="", flush=True)
```
### AETHER：多 Agent 系统
```
from bili.aether import load_mas_from_yaml, compile_mas, execute_mas
config = load_mas_from_yaml("bili/aether/config/examples/simple_chain.yaml")
result = execute_mas(config, {"messages": ["Analyze quantum computing trends"]})
print(result.get_summary())
```
### AETHER：流式传输多 Agent
```
from bili.aether.runtime import MASExecutor, StreamEventType
executor = MASExecutor(config)
executor.initialize()
for event in executor.stream(input_data):
if event.event_type == StreamEventType.TOKEN:
print(event.data["content"], end="", flush=True)
```
### AEGIS：运行安全测试套件
```
# Stub 模式（无 LLM 调用 — 验证 framework 执行）
python bili/aegis/suites/injection/run_injection_suite.py --stub
# 完整运行（需要 API credentials）
python bili/aegis/suites/injection/run_injection_suite.py
# 生成统计报告
python bili/aegis/suites/analysis/generate_stats.py
```
## 身份验证
BiliCore 提供了三种身份验证提供商：
| 提供商 | 用例 | 自动批准？ | 配置 |
|----------|----------|---------------|---------------|
| **SQLite** | 本地开发（默认） | 是 — `researcher` 角色 | `PROFILE_DB_PATH` 环境变量 |
| **Firebase** | 生产环境 (AWS) | 否 — 管理员审批 | `.env` 中的 Firebase 凭证 |
| **内存中** | 测试 | 是 | 无需配置 |
在 `bili/streamlit_app.py` 中通过 `initialize_auth_manager(auth_provider_name=...)` 进行配置。
## 开发
### 容器别名
在开发容器内部：
| 别名 | 描述 |
|-------|-------------|
| `streamlit` | 安装依赖项，创建 PG 数据库，启动 Streamlit UI（端口 8501） |
| `flask` | 安装依赖项，创建 PG 数据库，启动 Flask API（端口 5001） |
| `deps` | 安装/更新 Python 依赖项 |
| `cleandeps` | 清理并重新安装依赖项 |
| `seeds3` | 将数据文件上传到 LocalStack S3 |
| `createpgdb` | 创建 LangGraph PostgreSQL 数据库 |
### 代码质量
所有代码在提交前都必须通过格式化和 lint 检查（通过 pre-commit 钩子强制执行）：
```
./run_python_formatters.sh # Run all formatters (Black, Autoflake, Isort)
pylint bili/ --fail-under=9 # Lint check (must score 9+/10)
```
### 运行测试
```
# 在 container 内部
pytest bili/iris/ # IRIS unit tests
pytest bili/aether/tests/ # AETHER unit tests
pytest bili/aegis/suites/test_*.py # AEGIS unit tests
```
### 环境变量
将 `.env.example` 复制到 `.env` 并填入你的 API 密钥。Docker Compose 会自动读取此文件。
- **AWS 凭证：** `env/bili_root/.aws/`
- **Google 凭证：** `env/bili_root/.google/`
- **API 密钥：** 在 `.env` 中设置（OpenAI、SerpAPI、天气 API 等）
## 从 v4.x 迁移到 v5.0
v5.0 将代码库重组为三组件架构。导入路径已更改：
| 旧路径 | 新路径 |
|----------|----------|
| `bili.loaders.*` | `bili.iris.loaders.*` |
| `bili.nodes.*` | `bili.iris.nodes.*` |
| `bili.graph_builder.*` | `bili.iris.graph_builder.*` |
| `bili.config.*` | `bili.iris.config.*` |
| `bili.tools.*` | `bili.iris.tools.*` |
| `bili.checkpointers.*` | `bili.iris.checkpointers.*` |
| `bili.aether.attacks.*` | `bili.aegis.attacks.*` |
| `bili.aether.evaluator.*` | `bili.aegis.evaluator.*` |
| `bili.aether.security.*` | `bili.aegis.security.*` |
| `bili.aether.tests.injection.*` | `bili.aegis.suites.injection.*` |
| *(其他攻击套件)* | `bili.aegis.suites.
.*` |
**未更改的路径：** `bili.aether.*`（schema、编译器、runtime、配置、UI）、`bili.auth.*`、`bili.utils.*`、`bili.prompts.*`
所有功能均已保留 —— 仅位置发生了变化。
## 组件文档
- **IRIS：** 参见 `bili/iris/` 源代码和内联文档
- **AETHER：** [`bili/aether/README.md`](bili/aether/README.md) — 详尽的 MAS 文档
- **AEGIS：** [`bili/aegis/docs/security-testing-quickstart.md`](bili/aegis/docs/security-testing-quickstart.md) — 安全测试指南
## 致谢
bili-core 在 MSU Denver 的 [Community-Centered Computing (C3) Lab](https://c3-lab.org/) 开发，该实验室容纳了涵盖可持续性、教育和以社区为中心的计算的研究项目。这项工作得到了 [National Science Foundation (NSF) (Grant No. 2318730)](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2318730) 和 [National Artificial Intelligence Research Resource (NAIRR) Pilot](https://nairrpilot.org/projects/awarded?_requestNumber=NAIRR240197) 的支持。他们的支持对于推进 AI 的可访问性和促进以可持续性为重点的应用程序的创新起到了至关重要的作用。
欲了解更多信息，请访问 [C3 Lab 网站](https://c3-lab.org/) 或 [Sustainability Hub 网站](https://sustainabilityhub.co/)。