快速部署

本文档帮助你在 5 分钟内启动 wesgine 引擎，创建第一个 Cell 并发送第一条 AI 消息。

系统要求

安装引擎

从源码构建

# 克隆仓库
git clone https://github.com/weisyn/wesgine.git
cd wesgine.git

# 构建二进制
make build

# 验证安装
./bin/wesgine version

使用 Go 安装

// 在你的项目中引用
require github.com/weisyn/wesgine v1.0.0

确保 go.mod 中包含正确的 replace 指令（如果使用本地源码）：

replace github.com/weisyn/wesgine => ../wesgine.git

最小配置

wesgine 需要一个数据目录来存储 Cell 数据和 Hypervisor 注册表。

数据目录结构

$DATA_DIR/
├── hypervisor.db          # Cell 注册表
├── secrets/
│   └── spec.key           # AES-256-GCM 密钥（自动生成）
├── logs/
│   └── wesgine-stderr.log # 崩溃日志
└── cells/
    └── {cellID}/          # 每个 Cell 的独立目录
        ├── meta.db
        ├── sessions.db
        └── state.db

SDK 方式启动

package main

import (
	"context"
	"log"

	"github.com/weisyn/wesgine"
)

func main() {
	ctx := context.Background()

	// 创建 Hypervisor
	hyp, err := wesgine.NewHypervisor(ctx, wesgine.HypervisorConfig{
		DataDir: "/var/lib/wesgine",
	})
	if err != nil {
		log.Fatal(err)
	}

	// 启动 Hypervisor（只挂身份骨架，不启动 Cell）
	if err := hyp.Start(ctx); err != nil {
		log.Fatal(err)
	}
	defer hyp.Stop(ctx)

	log.Println("wesgine 引擎已启动")
}

CLI 方式启动

# 启动 HTTP 服务
./bin/wesgine serve \
  --data-dir /var/lib/wesgine \
  --addr :9091

创建第一个 Cell

Cell 是 wesgine 的核心运行单元——一个完整、独立、可移植的 AI Agent 运行时。

SDK 方式

// 定义 CellSpec
spec := wesgine.CellSpec{
	ID:       "my-first-cell",
	Timezone: "Asia/Shanghai",
	Locale:   "zh-CN",
}

// 创建 Cell（幂等操作）
cell, err := hyp.Cells().GetOrCreate(ctx, spec)
if err != nil {
	log.Fatal(err)
}

log.Printf("Cell 已创建: %s", cell.ID())

HTTP 方式

# 创建 Cell
curl -X POST http://localhost:9091/admin/cells \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-first-cell",
    "timezone": "Asia/Shanghai",
    "locale": "zh-CN"
  }'

注意：GetOrCreate 是推荐的创建方式——如果 Cell 已存在则返回现有实例，不存在则创建。这确保了幂等性。

发送第一条消息

SDK 方式

import "github.com/weisyn/wesgine/message"

// 构建消息
msgs := []message.Message{
	{
		Role:    "user",
		Content: []message.ContentBlock{{Type: "text", Text: "你好，请介绍一下你自己。"}},
	},
}

// 发送 Run 请求
events, err := cell.Runtime().Run(ctx, wesgine.AppRunRequest{
	Actor:     "alice",          // ★ 必填一等字段
	SessionID: "session-001",
	Messages:  msgs,
	Model:     "gpt-4o",        // ★ 必填，引擎不做隐式选择
})
if err != nil {
	log.Fatal(err)
}

// 消费事件流
for event := range events {
	switch event.Type {
	case "stream_delta":
		fmt.Print(event.Delta)
	case "done":
		fmt.Println("\n--- 完成 ---")
	case "error":
		fmt.Printf("错误: %s\n", event.Error)
	}
}

HTTP SSE 方式

curl -N -X POST http://localhost:9091/cells/my-first-cell/run \
  -H "Authorization: Bearer <cell-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "alice",
    "session_id": "session-001",
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "你好，请介绍一下你自己。"}]
      }
    ]
  }'

响应是 Server-Sent Events (SSE) 流：

data: {"type":"stream_delta","delta":"你好"}
data: {"type":"stream_delta","delta":"！我是"}
data: {"type":"stream_delta","delta":"AI 助手"}
data: {"type":"done","reason":"end_turn"}

配置 Provider

在发送消息之前，你需要配置至少一个 LLM Provider。

共享 Provider（Hypervisor 级）

hyp.SharedProviders().Reconfigure(ctx, []config.ProviderConfig{
	{
		Name:     "openai",
		Type:     "openai",
		BaseURL:  "https://api.openai.com/v1",
		APIKeyRef: config.SecretRef{Source: "env", Name: "OPENAI_API_KEY"},
		Models: []config.ModelConfig{
			{Name: "gpt-4o", ContextWindow: 128000, SupportsVision: true},
		},
	},
})

私有 Provider（Cell 级）

通过 CellSpec 声明 Cell 独有的 Provider：

spec := wesgine.CellSpec{
	ID: "private-cell",
	PrivateProviders: []config.ProviderConfig{
		{
			Name:     "my-azure",
			Type:     "azure_openai",
			BaseURL:  "https://my-instance.openai.azure.com",
			APIKeyRef: config.SecretRef{Source: "inline", Value: "sk-..."},
		},
	},
	ProviderStrategy: "own_only",
}

验证运行

健康检查

# 基本健康检查（无需认证）
curl http://localhost:9091/health
# {"status":"ok","lifecycle":"ready"}

# 列出所有 Cell
curl http://localhost:9091/admin/cells \
  -H "Authorization: Bearer <admin-token>"

查看 Cell 状态

curl http://localhost:9091/cells/my-first-cell/state \
  -H "Authorization: Bearer <cell-token>"

查看会话历史

# 列出会话
curl http://localhost:9091/cells/my-first-cell/sessions \
  -H "Authorization: Bearer <cell-token>"

# 查看消息
curl "http://localhost:9091/cells/my-first-cell/sessions/session-001/messages?limit=20" \
  -H "Authorization: Bearer <cell-token>"

下一步

常见问题

Q: ErrActorRequired 错误

Actor 是 AppRunRequest 的必填一等字段。每个 Run 必须指定执行者身份：

// ✅ 正确
cell.Runtime().Run(ctx, wesgine.AppRunRequest{
	Actor: "alice",
	// ...
})

// ❌ 错误——会返回 ErrActorRequired
cell.Runtime().Run(ctx, wesgine.AppRunRequest{
	// Actor 为空
})

Q: ErrModelRequired 错误

wesgine 不做隐式模型选择。每个 Run 必须显式指定模型：

// ✅ 正确
wesgine.AppRunRequest{Model: "gpt-4o", ...}

// ❌ 错误
wesgine.AppRunRequest{Model: "", ...}

Q: 如何查看引擎日志？

# 崩溃日志（Go panic 栈）
cat /var/lib/wesgine/logs/wesgine-stderr.log

# 业务日志（slog 输出）
journalctl -u wesgine -f