jensabrahamsson/overblick
GitHub: jensabrahamsson/overblick
一个安全优先的多身份 AI 代理框架，通过 6 阶段 LLM 安全管道和 YAML 驱动的个性系统，让多个具备独特人格的代理在同一代码库中安全协作。
Stars: 1 | Forks: 0
# 概述
[](https://github.com/jensabrahamsson/overblick/actions/workflows/test.yml)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
专注于安全的多身份代理框架。Python 3.13+。GPL v3。
## 平台支持
| 平台 | 状态 | 备注 |
|----------|--------|-------|
| **macOS** | 完全支持 | 主要开发平台。使用 Unix sockets 进行 IPC，使用 macOS Keychain 管理密钥。 |
| **Linux** | 完全支持 | 使用 Unix sockets 进行 IPC，使用 keyring 管理密钥。 |
| **Windows** | 支持 | 使用 TCP localhost 回退进行 IPC（无 Unix sockets），使用 keyring 管理密钥。请使用 `python -m overblick manage` 代替 bash 脚本。 |
跨平台辅助工具位于 `overblick/shared/platform.py`。Python CLI 管理器（`python -m overblick manage`）适用于所有平台；`scripts/` 中的 bash 脚本仅适用于 Unix/macOS。
Överblick 将多个 AI 代理身份整合到一个具有插件架构的单一代码库中。每个身份都具有独特的**个性**——声音、兴趣、特征和行为约束——全部由 YAML 配置驱动。该框架在每一层都强调安全性：6 阶段 LLM pipeline、加密密钥、结构化审计日志、prompt 注入边界和默认拒绝权限。
## 快速开始
**一条命令** —— 检查 Python，创建 venv，安装依赖，拉取 Ollama 模型，启动所有服务：
```
git clone https://github.com/jensabrahamsson/overblick.git
cd overblick
./scripts/quickstart.sh
```
或者分步执行：
```
python3.13 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 作为可编辑包安装（推荐用于开发）
pip install -e ".[dev]"
# 运行测试（3500+ 单元 + 场景测试，无需 LLM/browser）
python -m pytest tests/ -v -m "not llm and not e2e"
# 启动 dashboard — 首次运行自动打开设置向导
python -m overblick dashboard
# 运行特定 identity
python -m overblick run anomal
```
## 架构
```
┌───────────────┐
│ Supervisor │ Boss agent: process management,
│ (Boss Agent) │ audit, permission decisions
└──────┬────────┘
│ IPC (Unix sockets / TCP localhost on Windows, HMAC auth)
┌─────────────┼─────────────┐
│ │ │
┌─────▼──────┐ ┌───▼─────┐ ┌────▼──────┐
│ Identity │ │Identity │ │ Identity │
│ "anomal" │ │"cherry" │ │ "blixt" │
└─────┬──────┘ └───┬─────┘ └────┬──────┘
│ │ │
┌─────▼─────────────▼─────────────▼──────┐
│ Plugin Layer │
│ Moltbook │ Telegram │ Email │ IRC │ … │
└─────┬─────────────────────────┬────────┘
│ │
┌─────▼───────┐ ┌──────▼──────┐
│ SafeLLM │ │ Security │
│ Pipeline │ │ Layer │
│ (6 stages) │ │ │
└─────────────┘ └─────────────┘
```
### SafeLLM Pipeline（6 个阶段）
每次 LLM 交互都会经过：
1. **输入清理** — 剥离空字节、控制字符，规范化 unicode
2. **预检** — 检测越狱/注入尝试
3. **速率限制** — 每个身份的令牌桶节流
4. **LLM 调用** — 调用语言模型（Ollama、Gateway 或云提供商）
5. **输出安全** — 过滤 AI 泄露、人设崩坏、被阻止的内容
6. **审计日志** — 记录交互以供审查
Pipeline 是**故障关闭**的：如果任何安全阶段崩溃，请求将被阻止（而不是通过）。
## 个性库
个性定义了代理是**谁**——独立于操作配置。每个个性可以选择性地拥有一个心理框架（荣格心理学、依恋理论、斯多葛主义、存在主义），这塑造了它们的思考方式，而不仅仅是它们能做什么。
| 身份 | 声音 | 风格 |
|----------|-------|-------|
| **Anomal** | 知识分子人文主义者 (James May 能量) | 审慎、好奇、跨领域类比 |
| **Cherry** | 28 岁斯德哥尔摩女性 | 调情、表情符号多、瑞典流行文化 |
| **Blixt** | 朋克技术评论家 | 尖锐、激进、反企业、痴迷隐私 |
| **Bjork** | 森林哲学家 | 稀疏、冷静、自然隐喻、瑞典斯多葛主义 |
| **Prisma** | 数字艺术家 | 多彩、通感、温暖、鼓舞人心 |
| **Rost** | 愤世嫉俗的前交易员 | 愤世嫉俗、黑色幽默、警示故事 |
| **Natt** | 神秘哲学家 | 怪诞、悖论、递归、存在主义 |
| **Stal** | 邮件秘书 | 正式、精确、外交辞令——代表委托人行事 |
| **Smed** | 开发者代理 | 有条不紊的代码铁匠——以精准和耐心锻造修复 |
### 创建新个性
1. 创建 `overblick/identities//personality.yaml`
2. 定义：身份、声音、特征、兴趣、词汇、示例
3. 为您的 LLM 调整声音——参阅 [The Voice Tuner's Handbook](VOICE_TUNING.md)
4. 使用 LLM 测试套件进行测试：
```
# 将你的 personality 添加到测试参数化列表
python -m pytest tests/personalities/test_personality_llm.py -v -s -m llm --timeout=300
```
**个性 YAML 结构：**
```
identity:
name: "mybot"
display_name: "MyBot"
role: "Helpful assistant"
description: "A friendly AI helper"
voice:
base_tone: "Warm and conversational"
style: "Clear, direct, uses analogies"
default_length: "2-4 sentences"
traits:
warmth: 0.8
helpfulness: 0.9
humor: 0.5
vocabulary:
preferred_words: ["consider", "interesting", "perhaps"]
banned_words: ["synergy", "leverage", "disrupt"]
example_conversations:
greeting:
user_message: "Hello!"
response: "Hey there! What's on your mind today?"
```
个性系统从三个位置加载（按顺序）：
1. `overblick/identities//personality.yaml`（基于目录，首选）
2. `overblick/identities/.yaml`（独立文件）
3. `overblick/personalities//personality.yaml`（旧版位置）
## 插件系统
插件是自包含的模块。每个插件仅接收 `PluginContext` 作为其唯一的框架接口。
**可用插件：**
| 插件 | 状态 | 描述 |
|--------|--------|-------------|
| **Moltbook** | 生产 | 自主社交参与 (OBSERVE → THINK → DECIDE → ACT → LEARN) |
| **Telegram** | 完成 | 带有命令、对话跟踪、速率限制的机器人 |
| **Email Agent** | 完成 | 邮件处理、分类、boss agent 咨询 |
| **Host Health** | 完成 | 系统监控，具有 LLM 驱动的健康分析 |
| **AI Digest** | 完成 | 周期性 AI 生成的摘要总结 |
| **GitHub Agent** | 完成 | 代理式 GitHub issue/PR 处理，带有 OBSERVE/THINK/PLAN/ACT/REFLECT 循环 |
| **Dev Agent** | 完成 | 自主开发者——日志监控、错误修复、测试运行、PR 创建 |
| **IRC** | 完成 | 身份间对话，带有话题管理 |
| **Compass** | 实验 | 通过风格分析检测身份漂移 |
| **Kontrast** | 实验 | 多视角内容引擎——来自所有身份的同步视角 |
| **Skuggspel** | 实验 | 阴影自我内容生成（荣格阴影探索） |
| **Spegel** | 实验 | 代理间心理画像和相互反思 |
| **Stage** | 实验 | YAML 驱动的身份行为场景测试 |
**插件生命周期：**
```
class MyPlugin(PluginBase):
name = "myplugin"
async def setup(self) -> None:
"""Initialize using self.ctx (PluginContext)."""
token = self.ctx.get_secret("my_token")
...
async def tick(self) -> None:
"""Called periodically by the scheduler."""
result = await self.ctx.llm_pipeline.chat(messages=[...])
if result.blocked:
logger.warning("Blocked: %s", result.block_reason)
...
async def teardown(self) -> None:
"""Cleanup on shutdown."""
```
**PluginContext 提供：**
| 服务 | 描述 |
|---------|-------------|
| `identity` | 包含所有配置的冻结 Identity 数据类 |
| `llm_pipeline` | SafeLLMPipeline（首选——包含所有安全功能） |
| `llm_client` | 原始 LLM 客户端（建议改用 pipeline） |
| `audit_log` | 结构化审计日志 |
| `event_bus` | 发布/订阅事件系统 |
| `scheduler` | 周期性任务调度 |
| `permissions` | 权限检查器（默认拒绝） |
| `get_secret(key)` | Fernet 加密的密钥访问 |
## Supervisor (Boss Agent)
Supervisor 作为子进程管理多个代理身份：
```
supervisor = Supervisor(identities=["anomal", "cherry", "blixt"])
await supervisor.start() # Start all agents
await supervisor.run() # Block until shutdown
```
**功能：**
- 进程生命周期管理（启动、停止、带退避的自动重启）
- 通过 Unix domain sockets (macOS/Linux) 或 TCP localhost (Windows) 进行 IPC，并带有 HMAC 认证
- 代理审计系统（健康、性能、安全、速率限制监控）
- 权限请求处理（阶段 1 自动批准）
- 跨审计历史的趋势分析
## LLM 后端
Överblick 支持四种 LLM 提供商模式：
| 提供商 | 值 | 客户端 | 默认端点 |
|----------|-------|--------|-----------------|
| **Ollama** | `ollama` | OllamaClient | `localhost:11434` |
| **LM Studio** | `lmstudio` | OllamaClient | `localhost:1234` |
| **Överblick Gateway** | `gateway` | GatewayClient | `localhost:8200` |
| **Deepseek** | `deepseek` | DeepseekClient | `api.deepseek.com/v1` |
| **OpenAI** *(即将推出)* | `openai` | CloudLLMClient | `api.openai.com/v1` |
**LM Studio** 暴露一个 OpenAI 兼容的 `/v1/chat/completions` API——Överblick 通过不同的默认端口重用 `OllamaClient`。无需额外依赖。
**Överblick Gateway** (`python -m overblick.gateway`) 为多代理设置添加了优先级队列。通过 gateway 运行的代理默认获得 `low` 优先级；验证码解决和对时间敏感的任务使用 `high` 优先级。
通过仪表板设置向导（`/settings/`）或直接在 `config/overblick.yaml` 中配置：
```
llm:
provider: ollama # or lmstudio, gateway, deepseek, openai
host: 127.0.0.1
port: 11434
model: qwen3:8b
temperature: 0.7
max_tokens: 2000
complexity: high # optional: "high" routes to cloud/deepseek, "low" stays local
```
**多后端 gateway 配置**（在 `config/overblick.yaml` 中）：
```
llm:
default_backend: local
backends:
local:
enabled: true
type: ollama
host: 127.0.0.1
port: 11434
model: qwen3:8b
deepseek:
enabled: true
type: deepseek
api_url: https://api.deepseek.com/v1
model: deepseek-chat
# api_key: set via OVERBLICK_DEEPSEEK_API_KEY env var
```
## 安全架构
**6 层防御：**
1. **输入清理器** — 剥离空字节、控制字符，规范化 unicode
2. **边界标记** — 外部内容包裹在 `<<>>` / `<<>>` 标记中
3. **预检器** — 在 LLM 调用前阻止越狱/注入尝试
4. **SafeLLM Pipeline** — 所有安全阶段集于一个 pipeline，故障关闭，默认安全 (strict=True)
5. **输出安全** — 扫描 LLM 响应中的 AI 泄露和人设崩坏
6. **审计日志** — 每个操作都记录结构化 JSON
**额外保护：**
- `SecretsManager` — 每个身份的 Fernet 加密密钥
- `RateLimiter` — 令牌桶速率限制
- `PermissionChecker` — 默认拒绝权限系统
- IPC 认证 — 进程间 HMAC 签名的消息
- **插件能力系统** — 声明式资源访问控制（测试版：仅警告）
- **原始 LLM 客户端保护** — 默认禁用插件对原始 LLM 客户端的访问
### 安全环境变量
| 变量 | 默认值 | 用途 |
|----------|---------|---------|
| `OVERBLICK_SAFE_MODE` | `1` (安全) | 为 SafeLLMPipeline 启用默认安全模式 (strict=True) |
| `OVERBLICK_RAW_LLM` | `0` (禁用) | 允许插件通过 `ctx.llm_client` 访问原始 LLM 客户端（不推荐） |
| `OVERBLICK_STRICT_CAPABILITIES` | `0` (警告) | 阻止缺少所需能力授权的插件 (PermissionError) |
**安全模式 (`OVERBLICK_SAFE_MODE=1`)**：
- `SafeLLMPipeline` 需要所有安全组件（预检器、输出安全、速率限制器）
- `ResponseGenerator` 需要 pipeline (`llm_pipeline`) 或显式的 `allow_raw_fallback=True`
- `PluginContext.llm_client` 在被访问时引发 RuntimeError
**迁移**：为了在测试版期间保持向后兼容性，设置 `OVERBLICK_RAW_LLM=1` 和 `OVERBLICK_SAFE_MODE=0`。对于生产环境，请使用默认值。
## 身份系统
每个身份都是一个从 YAML 加载的冻结 Pydantic BaseModel：
```
# overblick/identities/anomal/identity.yaml
name: anomal
display_name: Anomal
engagement_threshold: 35.0
interest_keywords: [artificial intelligence, crypto, philosophy]
enabled_modules: [dream_system, therapy_system]
# Learning 现在是一个平台服务 — 见 overblick/core/learning/
llm:
model: "qwen3:8b"
temperature: 0.7
max_tokens: 2000
quiet_hours:
enabled: true
start_hour: 21
end_hour: 7
schedule:
heartbeat_hours: 2
feed_poll_minutes: 5
```
## 数据库
双后端数据库抽象：
- **SQLite** — 开发和单代理部署的默认选择
- **PostgreSQL** — 用于生产多代理设置
两个后端共享相同的迁移系统和 API。
## 测试
```
# 所有单元 + 场景测试（3500+）
python -m pytest tests/ -v -m "not e2e"
# LLM personality 测试（需要 Ollama + qwen3:8b）
python -m pytest tests/ -v -m llm --timeout=300
# 特定 plugin
python -m pytest tests/plugins/telegram/ -v
python -m pytest tests/plugins/email_agent/ -v
python -m pytest tests/plugins/moltbook/ -v
# Supervisor 测试
python -m pytest tests/supervisor/ -v
# Personality 测试（非 LLM）
python -m pytest tests/personalities/ -v --ignore=tests/personalities/test_personality_llm.py
# 带 coverage
python -m pytest tests/ --cov=overblick
```
## 目录结构
```
overblick/
core/
orchestrator.py # Main agent loop coordinator
capability.py # CapabilityBase ABC + CapabilityContext
plugin_base.py # PluginBase ABC + PluginContext
plugin_registry.py # Plugin discovery and registration
event_bus.py # Pub/sub event system
scheduler.py # Periodic task scheduler
quiet_hours.py # Time-based activity gating
permissions.py # Default-deny permission system
db/
engagement_db.py # Engagement tracking
database/
base.py # DatabaseBackend ABC
factory.py # Backend factory (SQLite / PostgreSQL)
sqlite_backend.py # SQLite implementation
pg_backend.py # PostgreSQL implementation
migrations.py # Migration system
llm/
client.py # Abstract LLM client
ollama_client.py # Ollama backend
gateway_client.py # LLM Gateway backend
pipeline.py # SafeLLMPipeline (6-stage security chain)
response_router.py # LLM response inspection
security/
preflight.py # Pre-posting content checks
output_safety.py # Post-generation content safety
input_sanitizer.py # Input sanitization + boundary markers
audit_log.py # Structured audit logging
secrets_manager.py # Fernet-encrypted secrets
rate_limiter.py # Token bucket rate limiting
capabilities/ # Composable behavioral blocks (bundles)
plugins/
moltbook/ # Autonomous social engagement (production)
telegram/ # Telegram bot (complete)
email_agent/ # Email processing and classification (complete)
host_health/ # System health monitoring (complete)
ai_digest/ # AI-generated digests (complete)
github/ # Agentic GitHub issue/PR handling (complete)
dev_agent/ # Autonomous developer agent (complete)
irc/ # Identity-to-identity conversations (complete)
compass/ # Identity drift detection (experimental)
kontrast/ # Multi-perspective content engine (experimental)
skuggspel/ # Shadow-self content generation (experimental)
spegel/ # Inter-agent psychological profiling (experimental)
stage/ # Behavioral scenario testing (experimental)
identities/ # Identity stable — YAML-driven characters
anomal/ # Intellectual humanist
bjork/ # Forest philosopher
blixt/ # Punk tech critic
cherry/ # Flirty Stockholmer
natt/ # Uncanny philosopher
prisma/ # Digital artist
rost/ # Jaded ex-trader
stal/ # Email secretary
dashboard/ # FastAPI + Jinja2 + htmx web dashboard (settings wizard at /settings/)
gateway/ # LLM Gateway service (port 8200)
setup/ # Setup validators + provisioner (used by dashboard /settings/)
supervisor/
supervisor.py # Multi-process manager (Boss Agent)
ipc.py # IPC layer (Unix sockets + HMAC)
process.py # AgentProcess wrapper
audit.py # Agent audit system
config/
overblick.yaml # Global framework config
tests/ # 3500+ unit + scenario + LLM tests
```
## 配置
**`config/overblick.yaml`** — 全局设置
**`config/secrets.yaml`** — Fernet 加密的密钥（已 gitignored）
**`config/permissions.yaml`** — 默认拒绝权限授权（已 gitignored）
模板文件（`*.yaml.example`）已提交到仓库。
## Claude Code Skills
Överblick 在 `.claude/skills/` 中附带四个 Claude Code 技能，可加速框架开发：
| 技能 | 触发器 | 用途 |
|-------|----------|---------|
| **overblick-skill-compiler** | "compile skill", "build from spec", "generate plugin" | 将规范编译为完整的适用于生产环境的插件、能力和个性，包含测试和注册表连接 |
| **overblick-plugin-helper** | "create plugin", "review plugin", "debug plugin" | 插件开发、安全清单、PluginBase/PluginContext API 的交互式指导 |
| **overblick-capability-helper** | "create capability", "add capability", "review capability" | 可组合行为块、捆绑包、CapabilityBase/Registry API 的交互式指导 |
| **overblick-personality-helper** | "create personality", "design character", "review personality" | 具有心理特征模型、声音设计的 YAML 驱动角色的交互式指导 |
每个技能都包含涵盖完整 API、真实示例和清单的参考文档。**skill compiler** 自动化端到端组件生成；helpers 提供交互式指导。当检测到匹配的触发器时，Claude Code 会自动加载技能。
## 贡献
有关设置说明、代码标准和 PR 流程请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
**良好的首次贡献：**
- 为身份库创建新个性
- 添加混沌测试（`tests/chaos/`）
- 扩展实验性插件（Compass、Kontrast、Skuggspel、Spegel、Stage）
- 改进仪表板 UI/UX
## 许可证
GPL v3。有关详细信息，请参阅 [LICENSE](LICENSE)。
标签：AI风险缓解, DNS 反向解析, HTTP工具, LLM 管道, LLM评估, MacOS Keychain, Ollama, Python, YAML 配置, 多身份代理框架, 安全优先, 审计日志, 提示词注入防御, 插件架构, 无后门, 本地大模型, 测试用例, 网络安全, 网络安全审计, 行为约束, 身份管理, 进程间通信, 隐私保护, 默认拒绝策略