架构概览

本文描述 Wesclaw 的整体技术架构，帮助开发者和高级用户理解系统的运作方式。

双进程架构

Wesclaw 桌面版采用双进程架构：

┌──────────────────────────────┐
│    Electron 主进程（Node.js）  │
│  ┌────────────────────────┐  │
│  │   Renderer (React)     │  │
│  │   window.wesclaw.rpc() │  │
│  └─────────┬──────────────┘  │
└────────────┼─────────────────┘
             │ stdio JSON-RPC
┌────────────▼─────────────────┐
│    Go 后端进程 (wesclaw rpc)  │
│  ┌────────────────────────┐  │
│  │   wesgine Hypervisor   │  │
│  │   └── Cell "main"      │  │
│  │       └── Runtime      │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

两个入口命令

通信方式

桌面版：stdio JSON-RPC

Renderer → Electron Main → Go 后端
         window.wesclaw.rpc(method, params)

• Renderer 不直接 fetch
• 所有 RPC 通过 window.wesclaw.rpc() 走 stdio
• SSE 流通过 sseRouteStream → http/route stream_id 实现

SaaS 版：HTTP + SSE + JWT

浏览器 → nginx → 平台 :8080 / 引擎 :8081

• JWT 验证 weisyn 公钥
• 独立进程、独立数据目录
• 源码锁 split_guard_test.go 确保不混用

Boot 装配

启动流程

// 1. 创建 Hypervisor
hyp, _ := wesgine.NewHypervisor(ctx, wesgine.HypervisorConfig{
    DataDir:  xdg.NewAppDirs("wesclaw", "WESCLAW").DataDir(),
    CrashDir: xdg.NewAppDirs("wesclaw", "WESCLAW").CrashDir(),
})
must(hyp.Start(ctx))

// 2. 绑定 ProviderLiveKeyFn（GetOrCreate 前必须完成）
liveTokens := &providerid.LiveTokenSource{}
spec.ProviderLiveKeyFn = liveTokens.Key

// 3. 创建或获取 main Cell
cell, _ := hyp.Cells().GetOrCreate(ctx, wesgine.CellSpec{
    ID:               "main",
    Timezone:         "Asia/Shanghai",
    Locale:           "zh-CN",
    Governance:       wesgine.DefaultGovernance(),
    ProviderStrategy: "own_only",
    Compliance:       "standard",
})

关键约束

• hyp.Start() 只挂身份骨架（Cool/Cold），永不 Cell.Start
• GetOrCreate 前必须绑齐 json:"-" 进程 hook
• wes:/org: 落盘 SourceLive 却不绑 getter → fail-loud
• 禁止 ActivatePersisted

前端不感知 Cell（PROD-1）

Wesclaw 桌面版遵循 PROD-1 原则：

// Go 后端 Handler.instance 永远绑定 boot 时创建的 main Cell
type Handler struct {
    instance *wesgine.Cell
    runtime  *wesgine.RuntimeHandle
}

UI 禁词

以下术语不得出现在面向用户的 UI 中：

Cell / CellID / cell.db / Hypervisor / Governance
GovernMode / ScopeOwner / MemoryScope / scope

数据目录结构

$XDG_DATA_HOME/wesclaw/              # 唯一数据根
├── hypervisor.db                     # Cell 注册表
├── cells/main/                       # 默认 Cell
│   ├── meta.db                       # Cell 元数据
│   ├── sessions.db                   # 会话（Memory / Sessions）
│   ├── state.db                      # 运行时状态（Traces / Observe）
│   ├── skills/                       # Tier C 技能包
│   ├── knowledge/                    # 知识库文件
│   ├── workspace/                    # 工作区文件
│   ├── .scratch/                     # 临时计算域
│   └── .plans/                       # Plan artifact
├── db/
│   ├── wesclaw.db                    # 应用数据（tc_* 表）
│   └── wescode_auth.db              # 登录 session（跨 Cell 共享）
├── crashes/                          # 崩溃日志
└── logs/                             # Go 后端日志

平台路径

三链 SQLite 迁移共存

wesclaw.db 上同时运行三条独立迁移链：

无冲突的理由：三链管理的表集合完全不相交。

降级策略

迁移失败时：关闭 DB → 归档旧文件为 .migration-failed → 清除 WAL/SHM → 重新打开全新 DB → 第二次失败才 fatal。

wesgine 直连审计

Wesclaw 直连 14 个 wesgine 子包，2026-09 审计确认全部合理：

禁止直连的仍然是 wesgine/internal/...。

SDK 层关系

wesgine 引擎内核
wesui   前端渲染（零 fetch / 零 store / 零路由）
wesapp  引擎消费层 Go SDK
weisyn/sdk  平台客户端（auth / wes / wesclient / jwtauth）
        ▲
产品：wesclaw | wescode | wescraft | teleclaw
产品之间互不 import

依赖规则

前端层关系

wesui（组件库） → 通过 Vite alias + tsconfig paths 源码共享
├── wesclaw/web   （消费方）
├── wescode/web   （消费方）
└── wescraft/web  （消费方）

wesui 是纯 UI 渲染层：零 fetch、零 store、零路由。

SSE 流稳定性

Run 生命周期与 SSE 连接完全解耦：

取消 Run 的唯一途径：用户 interrupt、CycleDetector HITL 超时、BudgetCheckFn、Cell Stop。