Gazer 是一个桌面级具身 AI 伴侣系统，采用 Runtime + Agent + Tools + Memory + Soul + Devices 的分层架构。
| 对话 | 记忆图谱 | 人格定制 |
|---|---|---|
 |
 |
 |
- 双脑执行路径 — 快响应与深度推理分层（
fast_brain/slow_brain）。 - 工具治理 — 统一
ToolRegistry+ 分层策略管线 + 安全等级（Tier）控制。 - 长期记忆 — OpenViking 语义记忆与长期提炼，数据落在
data/openviking。 - Soul 体系 — 三槽位
WorkingContext、预算管理、主动推断、人格演化宪法约束。 - 多通道与多节点 —
MessageBus解耦 Channel/Agent，支持 Telegram、Discord、飞书、Slack 等通道及卫星节点接入。 - 管理可观测 — FastAPI Admin API + React 控制台 + WebSocket 实时事件。
核心主链路（简化）：
- Channel 收到输入，调用
ChannelAdapter.publish()。 - 消息进入
MessageBus（src/bus/queue.py）并执行限流。 AgentLoop（src/agent/loop.py）构建上下文、调用 LLM、执行工具。- 结果通过
MessageBus出站，由各 Channel 发送。 - Turn 记忆、策略与审计信息写入 Memory/Observability。
运行生命周期由 GazerBrain 统一编排：
- 初始化 OpenViking、MemoryManager、Agent、Orchestrator、DeviceRegistry、Channels。
- 启动 Admin API（同进程 asyncio 任务）、Agent 主循环、Cron/Heartbeat、感知捕获与硬件层。
Gazer/
main.py # 启动入口
pyproject.toml # Python 包定义与依赖
Dockerfile # 多阶段 Docker 构建
docker-compose.yml # Compose 编排
.env.example # 环境变量模板
config/
settings.yaml # 主配置文件
assets/ # SOUL/Prompt 等运行时资产（SOUL.md 为人格唯一源）
data/ # 运行时数据目录（记忆、配对等）
docs/ # 项目文档中心
skills/ # 用户可扩展技能
src/
agent/ # Agent loop / orchestrator / adapter
bus/ # MessageBus 与命令队列
channels/ # Telegram / Web / Discord / 飞书 / Slack 等通道适配
cli/ # Click CLI（gazer start / chat / doctor 等）
config/ # 配置缺省值
devices/ # 本地节点 / 卫星节点 / 协议与会话
eval/ # 评测、trainer、self-evolution
extensions/ # 插件：desktop / email / git / browser / cron 等
flow/ # Flow 引擎、审批
llm/ # LLM 抽象、LiteLLM、路由器
memory/ # OpenViking memory backend
multi_agent/ # 多智能体 worker / monitor / pool
plugins/ # 插件加载器与 API
runtime/ # Brain、config_manager、子系统、IPC、日志脱敏
security/ # owner / pairing / threat scan 等
soul/ # 情感、人格、认知、工作上下文
tools/ # 工具实现与 Admin API 路由
web/ # React + Vite 管理台
tests/ # pytest 测试
perception/ # 感知子系统（屏幕 / 相机 / 音频）
hardware/ # 硬件串口驱动抽象
electronics/ # KiCad 硬件设计
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Python | >= 3.10 | 推荐 3.11 |
| pip | 最新 | 用于安装 Python 包 |
| Node.js | >= 18 | 仅前端开发需要，推荐 20 LTS |
| npm | >= 9 | 随 Node.js 安装 |
| Git | 最新 | 克隆仓库 |
git clone https://github.com/redasm/Gazer.git
git clone https://github.com/redasm/Gazer.git .gazer
cd gazer目标：先把 python main.py 跑起来，避免首次安装被重依赖阻塞。
# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
# Windows PowerShell
# py -m venv .venv
# .venv\Scripts\Activate.ps1
# python -m pip install -U pip安装核心运行依赖：
pip install -e .此命令基于
pyproject.toml中的dependencies安装所有核心包。感知（音频/视觉）等可选能力按需在路径 B 中补齐。
目标：安装项目完整依赖与扩展能力（测试、感知、UI、浏览器）。
pip install -e ".[dev,perception,ui,browser]"按需安装某个扩展组：
| 依赖组 | 命令 | 包含内容 |
|---|---|---|
dev |
pip install -e ".[dev]" |
pytest、black |
perception |
pip install -e ".[perception]" |
OpenCV、MediaPipe、Whisper、TTS、音频 |
ui |
pip install -e ".[ui]" |
PySide6 面部 UI |
browser |
pip install -e ".[browser]" |
Playwright 浏览器自动化 |
注意：
perception组中的pyaudio在 Linux/WSL 和 Windows 上都可能需要额外系统库。首次安装建议先走“最小可运行”路径，再按需补齐扩展组。
复制环境变量模板并填写必要的 API 密钥：
# Windows (PowerShell)
Copy-Item .env.example .env
# macOS / Linux
cp .env.example .env编辑 .env 文件，至少配置一个 LLM Provider 密钥：
# 必填：至少配置一个 LLM Provider
OPENAI_API_KEY=sk-xxxx
# 或使用其他 Provider（取消注释并填写）
# DEEPSEEK_API_KEY=your_key
# DASHSCOPE_API_KEY=your_key
# GEMINI_API_KEY=your_key
# ANTHROPIC_API_KEY=your_keyProvider 密钥按命名约定自动解析：{PROVIDER_NAME}_API_KEY。支持的 Provider 完整列表见 .env.example。
核心配置在 config/settings.yaml，包含模型选择、人格、语音、感知、设备、安全策略等。首次使用通常无需修改。
人格唯一源文件为 assets/SOUL.md，可按需自定义。
如需使用 Web 管理控制台的开发模式：
cd web
npm install
cd ..使用内置诊断命令检查环境：
gazer doctor该命令会检查 Python 版本、核心依赖、配置文件、API 密钥、端口可用性等。
python: command not found：在 Linux/WSL 使用python3创建虚拟环境。The virtual environment was not created successfully because ensurepip is not available：先安装python3-venv后再执行python3 -m venv .venv。ModuleNotFoundError: No module named 'dotenv'：确认虚拟环境已激活（which python），再执行pip install -e .。pyaudio构建失败：Linux/WSL 需先sudo apt install portaudio19-dev，Windows 需安装 PortAudio。首次可先走“最小可运行”路径，后续再补perception组。sounddevice/edge-tts缺失警告：属于perception可选组，核心启动已做 graceful fallback 不受影响。如需音频功能请pip install -e ".[perception]"。
启动 Brain + Admin API（同进程 asyncio 任务）：
python main.py或通过安装后的 CLI：
gazer startpython main.py --cli或：
gazer chat在另一个终端中启动前端开发服务器：
cd web
npm run dev默认后端地址为 http://localhost:8080（可通过 ADMIN_API_PORT 环境变量或 config/settings.yaml 覆盖）。
前端通过 VITE_API_BASE 环境变量指定 API 地址，默认使用 window.location.origin。
构建并运行：
# 仅核心
docker build -t gazer .
# 包含可选依赖
docker build -t gazer --build-arg EXTRAS=perception,browser .使用 Compose：
# 首先确保 .env 文件已配置
docker compose up -dCompose 会自动挂载 config/、data/、assets/、skills/、workflows/ 目录。
启动后可通过以下方式验证系统运行状态：
# 健康检查
curl http://localhost:8080/health
# WebSocket 端点
# /ws/status — 系统状态推送
# /ws/chat — 对话流
# /ws/canvas — 画布协作gazer 显示帮助
gazer start 启动 Brain + Admin API
gazer chat 交互式 REPL
gazer onboard 首次配置向导
gazer doctor 系统诊断
gazer config show 查看当前配置（密钥脱敏）
gazer channel status 检查通道 Token 状态
gazer pairing list 查看待审批配对请求
gazer pairing approve 审批配对
gazer plugin list 列出已发现的插件
gazer plugin init 脚手架创建新插件
先跑定向，再跑全量：
# 安全回归测试
pytest -q tests/test_security_regressions.py
# 工具与技能测试
pytest -q tests/test_tools_and_skills.py
# 全量测试
pytest -q- 安全逻辑集中在
src/security/*，避免在业务模块复制鉴权逻辑。 - IPC 队列默认走 HMAC 包装（
src/runtime/ipc_secure.py）。 - Admin Token / Session 由
OwnerManager托管（src/security/owner.py）。 - 配对审批与 allowlist 由
PairingManager维护（src/security/pairing.py）。 - 运行日志经
runtime/log_sanitizer.py脱敏。
- 文档中心：
docs/README.md - 模块文档总览：
docs/modules/index.md
本项目使用 Apache-2.0 License，详见 LICENSE。