消费方接入指南

四个消费方（wesclaw / wescode / wescraft / teleclaw）接入 wesgine 的共同契约、CellSpec 装配要点和典型差异。

消费方总览

消费方	形态	Cell 粒度	Boot 模式	Actor
wesclaw desktop	Electron + Go	1 用户 = 1 Cell (`"main"`)	Go 嵌入	weisyn uid / `"local"`
wesclaw saas	独立进程	平台 active-cell	Go 嵌入	JWT uid
wescode	VS Code Fork + Go	1 workspace = 1 Cell (`ws-{hash}`)	Go 嵌入	`"local"`
wescraft	Electron + Go	个人 `"personal"` / 团队 `"team-{id}"`	Go 嵌入	`"local"` / SSO uid
teleclaw	Spring Boot + HTTP	1 部门 = 1 Cell (`dept-{id}`)	HTTP 二进制	JWT userId

共同的 Boot 契约

所有 Go 嵌入消费方遵循相同的三步流程：

// 1. 启动引擎（只挂身份骨架）
eng, err := engine.StartEngine(ctx, engine.Config{DataDir: dataDir})

// 2. 绑定进程 hook（GetOrCreate 之前）
spec.ProviderLiveKeyFn = liveTokens.Key
spec.HostEnvironment = host
spec.OnStarted = onStarted

// 3. 创建或获取 Cell
cell, err := eng.Hypervisor.Cells().GetOrCreate(ctx, spec)

禁止：

在 GetOrCreate 前调用 ActivatePersisted
AppRunRequest.Actor 为空（→ ErrActorRequired）
AppRunRequest.Model 为空（→ ErrModelRequired）

ProviderLiveKeyFn 绑定时机

当 CellSpec 中存在 wes: 或 org: 类型的 Provider（SourceLive）时，必须在 GetOrCreate 之前绑定 live-key getter。

src := &providerid.LiveTokenSource{}
spec.ProviderLiveKeyFn = src.Key

// auth 构造完成后绑定 JWT accessor
src.Bind(auth.IdentityAccessToken, auth.ValidAccessToken)

缺少 getter 时引擎 fail-loud（INV-CELL-08）。

CellSpec 装配要点

必填字段

ID：Cell 标识符（immutable，创建后不可变）
Timezone：时区（immutable）

关键可选字段

字段	说明	典型值
`Governance`	治理策略	`DefaultGovernance()` / `RegulatedPreset()`
`ProviderStrategy`	Provider 策略	`own_only` / `shared_only` / `own_first`
`Compliance`	合规等级	`standard` / `financial` / `pii-strict`
`DenyPaths`	禁止访问的路径	`hypervisor.db`、配置文件
`Quotas`	配额	并发 Run 数、Token/分钟

不要填的字段

~~Storage~~：已删除（ADR-390），路径由引擎从 (DataDir, ID) 推出
~~Skills~~：已删除，通过 Skills() handle 装配

各消费方的特殊之处

wesclaw desktop

PROD-1：前端不感知 Cell
切账号 = Go 进程重启

wescode

CellID = sha256(canonicalize(workspace_root))[:4] → ws-a1b2c3d4
Device Agent 通过 CellSpec.HostEnvironment 透明注入

wescraft

FileIntelligence per-cell（本地文件索引）
19 个 wescraft 专属 tool 通过 cell.Tools().Register 装配

teleclaw（HTTP 模式）

TenantBootstrap 幂等对齐部门 → Cell
URL path /cells/{cellID}/* 强制
全量路由通过 EngineProxyFilter