Witty-Service

AI Agent 全生命周期管理服务。Witty-Service 提供智能体的创建、沙箱运行、会话管理、消息交互等核心能力，通过统一的 REST API 屏蔽底层沙箱（Docker / Local Process / E2B）与运行时适配器（OpenClaw / OpenCode）的差异，让你以一致的方式编排和管理 AI Agent。

目录

• Witty-Service
  • 目录
  • 项目介绍
    • 功能特性
    • 技术架构
    • 整体框架图
  • 安装指南
    • 方式一：pip安装
    • 方式二：从源码安装
  • 快速开始
  • 配置说明
    • 核心配置
    • Docker 沙箱配置
  • 部署流程
    • 测试环境
    • 生产环境
    • 启动参数说明
    • 生产环境注意事项
  • 本地开发
    • 环境搭建
    • 项目结构
    • 常用开发命令
    • 代码贡献流程
    • 开发规范
  • 许可证
  • 支持与反馈

---

项目介绍

Witty-Service 是一个面向 AI Agent 场景的后端服务，核心职责是将 Agent 生命周期管理、沙箱隔离运行、会话与消息交互 三者统一封装，对外提供简洁的 RESTful API。它作为上层应用（如 PolyMind）与底层 Agent 运行时之间的桥梁，使得前端无需关心 Agent 是运行在 Docker 容器、本地进程还是云端沙箱中。

典型应用场景：

• AI 编程助手平台 — 为每个用户创建独立沙箱中的 Agent，隔离执行代码生成、文件操作等任务
• 多模型对话服务 — 统一管理 OpenAI、Anthropic、DeepSeek 等多家 LLM 提供商的模型配置，按需切换
• Agent 技能市场 — 通过技能仓库为 Agent 动态注入专业能力（如 CVE 分析等）
• 企业级 Agent 编排 — 支持定时任务、会话暂停/恢复、运行时备份等企业级运维能力

功能特性

• 🤖 Agent 全生命周期管理 — 创建、暂停、恢复、删除 Agent，支持运行时备份与恢复
• 📦 多沙箱隔离 — 支持 Docker、Local Process、E2B 三种沙箱类型，按需选择隔离级别
• 💬 会话与消息 — 多会话管理，支持 REST 非流式和 SSE 流式两种消息交互模式
• 🔌 多运行时适配 — 通过 Adapter 层对接 OpenClaw、OpenCode 等不同 Agent 运行时
• 🧠 多模型管理 — 统一配置 OpenAI、Anthropic、Google、DeepSeek、GLM、Kimi 等 10+ 模型提供商
• 🛠️ 技能市场 — 内置技能仓库同步，支持从市场安装和上传自定义技能包
• 🔐 安全认证 — 基于 Bearer Token 的 API 认证机制
• 📊 CVE 与 Backport — 内置 CVE 漏洞分析和Backport服务

技术架构

层级	技术栈
Web 框架	FastAPI
ASGI 服务器	Uvicorn
数据库	SQLAlchemy + Alembic（迁移）
通信协议	WebSocket + REST + SSE
沙箱管理	Docker SDK / subprocess / E2B SDK
包管理	uv
语言	Python 3.11+

整体框架图

                              ┌─────────────────────────────────┐
                              │      上层应用（如 PolyMind）      │
                              └───────────────┬─────────────────┘
                                              │
                                     REST API / SSE
                                              │
                                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                           Witty-Service                              │
│                                                                      │
│  ┌─ API Layer ───────────────────────────────────────────────────┐   │
│  │  /agents  ·  /models  ·  /skills  ·  /cve  ·  /backport       │   │
│  │  Auth (Bearer Token)  ·  Error Handler  ·  Schemas            │   │
│  └──────────────────────────┬────────────────────────────────────┘   │
│                             │                                        │
│  ┌─ Application Layer ──────▼────────────────────────────────────┐   │
│  │  AgentManager · SessionManager · SkillManager                 │   │
│  │  CVEService  · BackportService                                │   │
│  └──┬────────────────────┬──────────────────────┬────────────────┘   │
│     │                    │                      │                    │
│  ┌──▼─────────────┐  ┌──▼──────────────┐  ┌───▼──────────────┐       │
│  │ Adapter Layer  │  │Persistence Layer│  │  Storage Layer   │       │
│  │ WebSocket客户端│  │ SQLAlchemy ORM  │  │  WorkspaceStore  │       │
│  │ HTTP 客户端    │  │ SQLite+Alembic  │  │  RuntimeBackup   │       │
│  │ 连接池/协议     │  │ Repository      │  │                  │       │ 
│  └──┬─────────────┘  └─────────────────┘  └──────────────────┘       │
│     │                                                                │
│  ┌──▼─────────────────────────────────────────────────────────────┐  │
│  │  Sandbox Layer                                                 │  │
│  │  ┌──────────┐  ┌──────────────┐  ┌──────────┐                  │  │
│  │  │  Docker  │  │Local Process │  │   E2B    │                  │  │
│  │  └────┬─────┘  └──────┬───────┘  └────┬─────┘                  │  │
│  │       └────────┬──────┘               │                        │  │
│  │                │                      │                        │  │
│  │       AdapterEndpoint                 │                        │  │
│  └────────────────┼──────────────────────┼────────────────────────┘  │
│                   │                      │                           │
│         ┌─────────────────────┐  ┌───────▼──────────┐                │
│         │ Domain (Enums/Errors)│  │   Config         │               │
│         └─────────────────────┘  └──────────────────┘               │
└──────────────────┼──────────────────────┼───────────────────────────┘
                   │                      │
         ┌─────────▼──────────┐  ┌────────▼─────────┐
         │   HTTP REST        │  │   HTTP REST       │
         │ (生命周期/技能管理)  │  │ (E2B Cloud API)  │
         └─────────┬──────────┘  └──────────────────┘
                   │
         ┌─────────▼──────────┐
         │   WebSocket        │
         │ (流式消息/事件推送)  │
         └─────────┬──────────┘
                   │
                   ▼
┌──────────────────────────────────────────────────────────────────────┐
│                       Witty-Agent-Server                             │
│                                                                      │
│  ┌─ API Layer ───────────────────────────────────────────────────┐   │
│  │  AgentRouter  ·  SessionRouter  ·  SessionWSRouter            │   │
│  └──────────────────────────┬────────────────────────────────────┘   │
│                             │                                        │
│  ┌─ Application Layer ──────▼────────────────────────────────────┐   │
│  │  AgentService  ·  SessionService  ·  SkillService             │   │
│  │  SessionWSOrchestrator  ·  TaskPool                           │   │
│  │  Materialization                                              │   │
│  └──────────────────────────┬────────────────────────────────────┘   │
│                             │                                        │
│  ┌─ Runtime Layer ──────────▼────────────────────────────────────┐   │
│  │  RuntimeBase (ABC)                                            │   │
│  │  ├─ OpenClawGatewayRuntime                                    │   │
│  │  └─ OpenCodeRuntime (WIP)                                     │   │
│  └───────────────────────────┬────────────────────────────────────┘  │
│                              │                                       │
│  ┌─ Adapter Layer ──────────▼──────────────┐   ┌─ Infra Layer ───┐   │
│  │ OpenClawAdapter  ·  RuntimeRegistry      │  │  GatewayClient  │   │
│  └──────────────────────────────────────────┘  │  (WS RPC)       │   │
│                                                 └────────┬────────┘  │
└──────────────────────────────────────────────────────────┼───────────┘
                                                           │
                                                     WebSocket RPC
                                                           │
                                                           ▼
                                           ┌──────────────────────────┐
                                           │    OpenClaw Gateway      │
                                           │  (Agent Runtime Platform)│
                                           └──────────────────────────┘

---

安装指南

方式一：pip安装

如果你只需要运行 Witty-Service，无需参与开发，可以直接通过 pip 安装：

pip install witty-service

安装完成后即可使用 CLI 启动服务：

witty-service --host 0.0.0.0 --port 8000

前置条件： Python 3.11 或更高版本

方式二：从源码安装

如果你需要参与开发或自定义构建，请从源码安装：

前置条件：

依赖	说明	安装方式
Python	3.11+	python.org
uv	Python 包管理器	docs.astral.sh/uv
Docker	沙箱运行时（可选）	docker.com

安装步骤：

1. 克隆仓库：

git clone https://gitcode.com/openeuler/witty-service.git
cd witty-service

2. 创建虚拟环境并安装依赖：

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

3. 验证安装：

witty-service --help

---

快速开始

1. 启动服务

witty-service --host 0.0.0.0 --port 8000

2. 验证服务是否正常运行

curl http://127.0.0.1:8000/healthz

期望返回：

{"status": "ok"}

3. 创建 Agent

curl -s -X POST http://127.0.0.1:8000/agents \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dev-token' \
  -d '{
    "name": "my-agent",
    "description": "我的第一个智能体",
    "sandbox_type": "local_process",
    "adapter_type": "openclaw",
    "idle_timeout_seconds": 3600
  }' | jq

4. 发送消息

AGENT_ID="<上一步返回的 id>"
SESSION_ID="<上一步返回的 default_session_id>"

curl -s -X POST "http://127.0.0.1:8000/agents/${AGENT_ID}/sessions/${SESSION_ID}/messages" \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dev-token' \
  -d '{"content": "你好，请介绍一下你自己"}' | jq

提示： 默认认证 Token 为 dev-token，生产环境请通过环境变量 AUTH_TOKEN 修改。

---

配置说明

Witty-Service 通过环境变量进行配置，无需额外配置文件。

核心配置

环境变量	说明	默认值
AUTH_TOKEN	API 认证 Token	dev-token
WITTY_AGENT_SERVER_APP_DIR	Local Process 模式下 witty-agent-server 代码目录	空

Witty Insight 集成配置

环境变量	说明	默认值
WITTY_INSIGHT_ENABLED	是否启用 witty-insight 集成	true
WITTY_INSIGHT_BASE_URL	witty-insight API 地址	http://127.0.0.1:7396
WITTY_INSIGHT_TIMEOUT_SECONDS	witty-insight 请求超时（秒）	10
WITTY_INSIGHT_BEARER_TOKEN	调用 witty-insight 时附带的 Bearer Token（可选）	空

默认推荐同机部署并通过 127.0.0.1 连接 witty-insight。witty-service 默认启用 Insight 集成；如果上游 witty-insight 当前未启动，witty-service 仍可正常启动。若需关闭该集成，可显式设置 WITTY_INSIGHT_ENABLED=false。 修改上述环境变量后，需要重启 witty-service 进程才能生效。

同机部署示例：

export WITTY_INSIGHT_BASE_URL=http://127.0.0.1:7396
export WITTY_INSIGHT_TIMEOUT_SECONDS=10

witty-service --host 0.0.0.0 --port 8000

分开部署示例：

export WITTY_INSIGHT_BASE_URL=http://10.0.0.8:7396
export WITTY_INSIGHT_TIMEOUT_SECONDS=10

witty-service --host 0.0.0.0 --port 8000

显式关闭 Insight 集成：

export WITTY_INSIGHT_ENABLED=false

witty-service --host 0.0.0.0 --port 8000

Docker 沙箱配置

环境变量	说明	默认值
WITTY_DOCKER_HOST	Docker 服务监听地址	127.0.0.1
WITTY_DOCKER_IMAGE	镜像名（不含 tag）	witty-agent-server
WITTY_DOCKER_IMAGE_TAG	镜像 tag	latest
WITTY_DOCKER_CONTAINER_PORT	容器内服务端口	8080
WITTY_DOCKER_CONTAINER_WORKSPACE_PATH	容器内工作区路径	/witty-workspace
WITTY_DOCKER_STOP_TIMEOUT	容器停止超时（秒）	10

---

部署流程

测试环境

适用于集成测试和功能验证：

# 构建 pip 包
uv build

# 安装构建产物
uv pip install dist/witty_service-0.1.0-py3-none-any.whl

# 初始化数据库 schema（推荐）
alembic upgrade head

# 启动服务
witty-service --host 0.0.0.0 --port 8000

若仅做临时本地验证，也可显式设置 WITTY_DATABASE_AUTO_CREATE=true 让服务启动时自动建表；默认不会自动建表。

运行测试：

# 单元测试
uv run pytest tests/unit/ -q

# E2E 测试
uv run pytest tests/e2e/ -q

# 全量测试
uv run pytest tests/ -q

生产环境

方式一：pip 安装（推荐）

pip install witty-service

# 部署新版本前先执行数据库迁移
alembic upgrade head

# 多 worker 启动
witty-service --host 0.0.0.0 --port 8000 --workers 4

方式二：从源码构建

git clone https://gitcode.com/openeuler/witty-service.git
cd witty-service
uv build
uv pip install dist/witty_service-0.1.0-py3-none-any.whl

alembic upgrade head

witty-service --host 0.0.0.0 --port 8000 --workers 4

启动参数说明

参数	说明	默认值
--host	绑定的主机地址	0.0.0.0
--port	绑定的端口	8000
--log-level	日志级别（debug/info/warning/error/critical）	info
--reload	开发模式自动重载	False
--workers	工作进程数	1

生产环境注意事项

• 认证 Token — 务必通过 AUTH_TOKEN 环境变量修改默认值，使用强随机字符串
• Worker 数量 — 根据 CPU 核心数合理设置 --workers
• 反向代理 — 推荐在 Witty-Service 前部署 Nginx 等反向代理，配置 HTTPS 证书
• 进程管理 — 建议使用 systemd 或 Supervisor 管理服务进程，实现自动重启
• 数据库迁移 — 默认不会在启动时自动建表；请优先执行 alembic upgrade head，仅开发/测试临时场景才显式设置 WITTY_DATABASE_AUTO_CREATE=true

---

本地开发

环境搭建

# 1. 克隆仓库
git clone https://gitcode.com/openeuler/witty-service.git
cd witty-service

# 2. 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# 3. 初始化数据库
alembic upgrade head

# 4. 启动开发服务器
uv run uvicorn src.witty_service.main:create_app --factory --host 0.0.0.0 --port 8000 --reload

项目结构

witty-service/
├── src/
│   ├── witty_service/                # 主服务包
│   │   ├── main.py                   # FastAPI 应用入口
│   │   ├── cli.py                    # CLI 入口
│   │   ├── config.py                 # 配置管理
│   │   ├── api/                      # API 路由层
│   │   │   ├── agents.py             # Agent 相关接口
│   │   │   ├── models.py             # 模型配置接口
│   │   │   ├── skills.py             # 技能管理接口
│   │   │   ├── cve.py                # CVE 漏洞接口
│   │   │   ├── backport.py           # 代码回溯接口
│   │   │   ├── auth.py               # 认证中间件
│   │   │   ├── errors.py             # 统一错误处理
│   │   │   └── schemas.py            # 请求/响应模型
│   │   ├── application/              # 业务逻辑层
│   │   │   ├── agent_manager.py      # Agent 生命周期管理
│   │   │   ├── session_manager.py    # 会话管理
│   │   │   └── skill_manager.py      # 技能管理
│   │   ├── adapter/                  # 适配器层（与 witty-agent-server 通信）
│   │   │   ├── websocket_client.py   # WebSocket 客户端
│   │   │   ├── websocket_protocol.py # WebSocket 协议定义
│   │   │   └── http_client.py        # HTTP 客户端
│   │   ├── sandbox/                  # 沙箱层
│   │   │   ├── base.py               # 沙箱基类
│   │   │   ├── docker.py             # Docker 沙箱
│   │   │   ├── local_process.py      # 本地进程沙箱
│   │   │   ├── e2b.py                # E2B 云沙箱
│   │   │   └── factory.py            # 沙箱工厂
│   │   ├── domain/                   # 领域模型
│   │   ├── persistence/              # 数据持久化
│   │   └── storage/                  # 文件存储
│   └── witty_agent_server/           # Agent 运行时服务
│       ├── app.py                    # FastAPI 应用
│       ├── api/routers/              # API 路由
│       ├── application/services/     # 业务服务
│       │   ├── agent/                # Agent 服务
│       │   ├── session/              # Session 服务
│       │   └── skill/                # 技能服务
│       ├── runtimes/                 # 运行时实现
│       ├── adapters/                 # 运行时适配器
│       └── infra/                    # 基础设施
├── tests/
│   ├── unit/                         # 单元测试
│   └── e2e/                          # 端到端测试
├── alembic/                          # 数据库迁移
├── docs/                             # 文档
├── pyproject.toml                    # 项目配置
└── .github/workflows/                # CI/CD 工作流

常用开发命令

命令	说明
uv run uvicorn src.witty_service.main:create_app --factory --reload	启动开发服务器（热重载）
uv run pytest tests/unit/ -q	运行单元测试
uv run pytest tests/e2e/ -q	运行 E2E 测试
uv run pytest tests/ -q	运行全量测试
uv build	构建 pip 包
alembic revision --autogenerate -m "description"	生成数据库迁移脚本
alembic upgrade head	执行数据库迁移

代码贡献流程

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m 'feat: add your feature'
4. 推送分支：git push origin feature/your-feature
5. 提交 Pull Request

开发规范

• 代码风格 — 遵循 Black 格式化规范（line-length=88），提交前运行 black . 检查
• 类型检查 — 使用 mypy 进行静态类型检查，配置为 strict 模式
• 提交规范 — 使用语义化提交信息（如 feat:、fix:、docs:、refactor:）
• 测试覆盖 — 新增功能需编写对应的单元测试，确保测试通过
• 数据库迁移 — 涉及模型变更时，需生成对应的 Alembic 迁移脚本

---

许可证

本项目基于 MIT 许可证 开源。

支持与反馈

• 问题反馈 — 请在 Gitcode Issues 提交
• 功能建议 — 欢迎通过 Issue 或 Pull Request 参与
• 项目主页 — https://gitcode.com/openeuler/witty-service