架构概览

wesgine 的两层架构、四层心智模型、仓库布局与依赖方向的全面介绍。

两层架构

wesgine 采用 Hypervisor + Cell 两层架构：

┌────────────────────────────────────────────────────────────────┐
│  Application Layer (wesclaw / wescode / wescraft / teleclaw)   │
└────────────────────────────────────────────────────────────────┘
                         │ SDK API (Go / HTTP)
┌────────────────────────▼───────────────────────────────────────┐
│  Hypervisor (控制面，薄，全局唯一)                                │
│  只做三件事：Cell 生命周期 / 共享 Provider 池 / 跨 Cell 只读观测    │
│  绝不做：Chat() / Run() / Memory() / Sessions()                │
└────────────────────────┬───────────────────────────────────────┘
                         │ manages
┌────────────────────────▼───────────────────────────────────────┐
│  Cell (数据面，厚，每租户一份，完全隔离)                           │
└────────────────────────┬───────────────────────────────────────┘
                         │ MCP 可选
┌────────────────────────▼───────────────────────────────────────┐
│  Playwright / Desktop adapter（wesgine 标准 adapter，opt-in）    │
└────────────────────────────────────────────────────────────────┘

四层心智模型

wesgine 的核心价值分四层理解：

层级	名称	职责
Layer 1	Container（Hypervisor）	编排容器，n=1 透明、n≥2 启用调度
Layer 2	Kernel（Loop 五件套）	Cognitive / Context / Execution / Memory / Govern
Layer 3	Cell（三位一体）	Runtime Instance + Tenant Unit + Portable Snapshot
Layer 4	Actor（请求主体）	运行时一等标识符，做记忆隔离/资源调度/认知路由/行为归因

Agent 引擎 Kernel 是基本面。Cell 是 Kernel 的具体化实例。Hypervisor 是编排容器。多/单租户是部署形态，不是产品定位。

仓库布局

wesgine.git/
├── wesgine.go          SDK 入口：NewHypervisor()（唯一 boot 路径）
├── hypervisor.go       Hypervisor struct
├── cell.go             Cell struct
├── cellspec.go         CellSpec 定义（struct embedding 分层）
│
├── design/             设计文档
│   ├── 01-identity/    positioning / axioms / mental-model / principles
│   ├── 02-architecture/  overview / hypervisor / cell / actor / data-model /
│   │                     governance / observability / orchestration + kernel/
│   ├── 03-specification/ handle-api / http-gateway / cellspec-reference / ...
│   ├── 04-guide/         quickstart / boot-patterns / consuming-apps / migration
│   ├── 05-invariants/    anti-patterns / invariant-registry / audit-lock
│   └── decisions/        ADR（accepted/ + _template.md）
│
├── skills/             Tier E 引擎技能（~7 个，编译时 embed）
│
│ ── 公共契约包 ──────────────────────────
├── message/ engine/ tool/ knowledge/   Shared Kernel
├── config/             HypervisorConfig / CellSpec / ProviderConfig
├── agent/              AgentConfig / Store
├── task/ tenancy/      TaskMemory / Tenancy BC
├── channel/ cron/ skill/ capability/   子系统对外类型
├── observe/            对外 Observability 契约
├── governance/         治理类型与预设
├── interact/           HITL 对外类型
├── license/            Ed25519 离线 license 校验
├── xdg/                XDG Base Directory 布局
│
├── internal/           实现
│   ├── hypervisor/     Hypervisor 实现
│   ├── gateway/        HTTP 路由 + handler
│   ├── cell/           Cell 实现（supervisor/inbox/eventbus/temperature/boot）
│   ├── cognitive/      Resolver 链 + per-cell Health/RateLimit
│   ├── context/        Assembler + Overlays + CompressPipeline
│   ├── execution/      Registry + Executor + builtin/
│   ├── memory/         Store（Agent NS + Cell NS）
│   ├── knowledge/      Corpus + SearchBackend
│   ├── loop/           Coordination for{}
│   └── infra/          db / crashctx / lineio / proc / ssrf / storage
│
├── adapter/            per-cell 外设
│   ├── channel/ email/ mcp/ cron/ knowledge/
│   ├── browser/        browser_wait_for_user HITL 安全阀
│   ├── headless-browser/ 可选 Headless Browser
│   ├── playwright/     用户浏览器自动化
│   ├── desktop/        桌面自动化 Device Agent SDK
│   ├── plugin/         JSON-RPC 子进程 Plugin Runtime
│   └── stt/            语音转写 Whisper
│
├── client/             HTTP Client SDK（仅 accept / 外部集成）
├── cmd/wesgine/        CLI
└── scripts/audit-lock/ 闸门集

依赖方向

单向向内，严格分层：

Shared Kernel     ← 零依赖
Subsystem BC      ← 只依赖 Shared Kernel
Coordination      ← 依赖 Subsystem 接口
Infrastructure    ← 实现 Subsystem 接口
Cell              ← 组装以上一切
Hypervisor        ← 管理 Cell 生命周期

约束：

Hypervisor 不 import Cell 内部包
Cell 之间不互相 import
子系统 BC 不感知 Cell

接口所有权

接口定义在 Provider 侧（子系统），不在 Consumer 侧。

// 接口定义在 cognitive 包
package cognitive

type Resolver interface {
    Stream(ctx context.Context, cellID string, req Request) (Stream, error)
}

安全默认

wesgine 的安全姿态是 fail-closed：

行为	说明
`NewHypervisor()`	零 I/O、零 goroutine
`Cells().Create(spec)`	显式行为，无 default cell auto-create
未知错误	拒绝（fail-closed）
未声明 Governance	`DefaultGovernance()` 即 `ModeOpen`
未声明 Storage	无字段——路径由引擎从 `(DataDir, ID)` 推出

物理边界

wesgine 运行时进程边界——服务端管认知/状态/工具/通讯/治理/调度/多租户 + 三层浏览器/桌面自动化。

层	adapter	CellSpec	运行时位置
Headless Browser	`adapter/headless-browser/`	`.HeadlessBrowser`	服务端（chromedp）
Playwright	`adapter/playwright/`	`.Playwright`	服务端 subprocess + 用户浏览器
Desktop Agent	`adapter/desktop/`	`.Desktop`	客户端 binary（AX-5）

wesgine 提供 Playwright 和 Desktop 的 adapter 代码（共享维护），但 Desktop binary 运行在客户端（运行时隔离）。

Gateway 双模式

已实装两种 HTTP 网关模式：

模式	函数	路径
单 Cell	`gateway.ServeSingleCell(cell, opts)`	无 cellID 路径
多 Cell	`gateway.ServeMultiCell(hyp, opts)`	`/cells/{id}/*` 路径

Gateway 中间件链：path parse → cell exist → auth → state → quota → dispatch。

Hypervisor API 总览

hyp, _ := wesgine.NewHypervisor(ctx, HypervisorConfig{...})
hyp.Start(ctx)                          // 只挂身份骨架
hyp.Stop(ctx)                           // 排空全部 Cell
hyp.ActivatePersisted(ctx)              // 后台打开数据面
hyp.Version()                           // SDK 版本
hyp.LifecycleState()                    // starting | ready | draining
hyp.Cells().Create(ctx, CellSpec)       // 创建 Cell
hyp.Cells().GetOrCreate(ctx, CellSpec)  // 幂等获取或创建
hyp.Cells().List(ctx)                   // 列出所有 Cell
hyp.Cells().Stop(ctx, cellID)           // 停止
hyp.Cells().Delete(ctx, cellID)         // 删除
hyp.Cells().Export(ctx, cellID)         // 导出
hyp.Cells().Import(ctx, r, opts)        // 导入
hyp.SharedProviders().List()            // 共享 Provider 列表
hyp.SharedProviders().Reconfigure(...)  // 重新配置
hyp.Observe().Snapshot()                // 观测快照
hyp.Tokens().IssueAdminToken(ttl)       // 签发 admin token

Cell API 总览

cell, _ := hyp.Cells().Get("dept-legal")

// Runtime
events, err := cell.Runtime().Run(ctx, AppRunRequest{
    Actor:     "alice",
    SessionID: "s1",
    AgentID:   "agent-legal",
    Messages:  []Message{...},
})

// 25 个 Handle 访问器
cell.Agents()   / cell.Memory()   / cell.Sessions()  / cell.Knowledge()
cell.Skills()   / cell.Tools()    / cell.HITL()       / cell.Learn()
cell.Channels() / cell.Email()    / cell.MCPs()       / cell.Cron()
cell.HeadlessBrowser() / cell.Playwright() / cell.Desktop()
cell.Policy()   / cell.Quotas()   / cell.Tokens()
cell.Observe()  / cell.Providers()/ cell.Config()
cell.TaskMemory() / cell.Events() / cell.Workspace()

验证

make verify

编译、go vet、自定义 analyzer、audit-lock 闸门、design 文档验证、测试，一个目标跑完。