常见问题

wesgine 使用过程中最常被问到的问题，按主题分类整理。

wesgine 是什么？

wesgine 是服务端多租户 AI Agent 引擎（Server-side Multi-tenant AI Agent Engine）。

类比：Postgres 之于 SQL schema = wesgine 之于 Agent Cell。

它不是：

常见误解	实际定位
❌ AI OS	服务端引擎，不是操作系统
❌ 多用户 SaaS 框架	引擎不定义用户身份体系
❌ 知识库引擎	知识库是 Cell 的一个子系统
❌ 业务系统	引擎提供 Agent 运行时，业务逻辑在应用层

Hypervisor 和 Cell 是什么关系？

Hypervisor（控制面，薄） 只做三件事：

Cell 生命周期管理
共享 Provider 池
跨 Cell 只读观测

Cell（数据面，厚） 是完整、独立、可移植的 AI Agent 运行时。

心智模型：不是"一个引擎里装了很多 Cell"，而是 "Hypervisor 里跑了很多个独立的 wesgine 实例"。

┌──────────────────────────────────────────────┐
│  Hypervisor (控制面，全局唯一)                 │
│  绝不做：Chat() / Run() / Memory() / Sessions()│
└──────────────────────┬───────────────────────┘
                       │ manages
┌──────────────────────▼───────────────────────┐
│  Cell (数据面，每租户一份，完全隔离)             │
└──────────────────────────────────────────────┘

绝对禁止：hyp.Chat() / hyp.Run() / hyp.Memory() 等业务方法。

六公理是什么？

违反公理 = 架构 Bug，PR 直接拒绝。

#	公理	简述
AX-1	隔离	Cell 是唯一隔离域。跨 Cell 无数据面通信
AX-2	身份无关	wesgine 不定义用户身份体系，但 Actor 是运行时一等标识符
AX-3	独立结算	每 Cell 独立计费；跨 Cell 只做 admin 只读聚合
AX-4	资产归属	业务知识物理归 Cell；跨 Cell 共享只允许应用层复制
AX-5	物理边界	运行时进程边界——服务端管 HeadlessBrowser + Playwright MCP；客户端物理设备通过 adapter/desktop/ MCP 接入
AX-6	诚实定位	收缩换清晰，放弃换聚焦

Cell 温度是什么？

Cell 有四个温度状态，描述其活跃程度与激活成本：

温度	含义	激活成本
Hot	有活跃 Run	0
Warm	goroutine/DB 在	0
Cool	磁盘保留，无 goroutine	100-500ms
Cold	Stopped	1-3s

转换规则：

Hot → Warm：Run 结束
Warm → Cool：idle 15min
Cool → Cold：idle N 天
外设需 Warm（Cron/IMAP）→ Cell 无法 Cool

请求行为：

Cool 态：首请求自动 WarmUp（Gateway/SDK 统一行为）
Cold 态：Gateway 返回 503 + Retry-After: 5 + 异步唤醒；SDK 路径同步唤醒

什么是 CognitiveSettlement？

CognitiveSettlement 是 Run 终态认知结算——Run 生命周期的强制阶段，不可跳过（唯一例外：进程级崩溃 panic_stop）。

产出四类认知产物：

产物	说明
SessionState	下一轮 Context 的唯一历史来源
Memory	长期记忆条目
Reflections	自省观察
Learnings	学习经验

关键不变量：

INV-CTX-40：Run 终态必须包含 SessionState
INV-CTX-41：SessionState 由主对话模型产出，不使用辅助模型
INV-CTX-42：Settlement 产出不可见于用户
INV-CTX-43：SessionState 是下一轮 Context 的唯一历史来源
INV-CTX-44：信息保全首选认知交班；交班不可用时机械压缩提供确定性 fallback
INV-CTX-45：MidRunCompression 与 EndOfRunSettlement 使用相同 SessionState schema
INV-CTX-46：Plan 状态不独立持久化，随 Settlement 一同持久化

什么是 Tier E 和 Tier C Skill？

特性	Tier E（引擎技能）	Tier C（Cell 技能）
来源	引擎二进制 embed	`.wesskill` 包上传或应用自带
数量	约 7 个	受 `MaxSkillsInstalled` 限制
权限	只读	可编辑、可卸载
术语	只允许引擎术语	业务术语允许

禁止 Tier H。想让 5 个 Cell 用同一 skill → 每个各装一份。

两者物理同处 cells/{id}/skills/ 一个目录，渠道是派生量不是位置。渠道三值闭域：

engine：只读，随二进制
product：应用自带，digest 三方比较
user：引擎不改写

Provider 四模式是什么？

三种归属：Hyp:Shared / Hyp:Named / Cell:Private（BYOK）。

四种 ProviderStrategy：

策略	含义
`own_only`	仅使用 Cell 私有 Provider
`shared_only`	仅使用 Hypervisor 共享池
`own_first`	优先私有，fallback 共享
`shared_first`	优先共享，fallback 私有

自动推导：单侧池非空时自动推导。两侧皆非空时必须显式声明，否则 ErrProviderStrategyUnset。

Secret 管理：一律经 config.SecretRef，三源 inline / env / live。vault 已删。inline 的明文经 AES-256-GCM 封套后进 hypervisor.db。

什么是 GovernMode？

治理模式控制 Cell 的执行效果边界：

Mode	Yellow Zone 行为	典型用途
`open`（默认）	Allow + Audit	编程/助手/通用
`locked`	Deny	金融合规/展示

Hardline 恒 Deny，不可覆盖（18 条灾难正则：rm -rf / / fork bomb / shutdown 等）。

Compliance 预设：

预设	Mode	NetworkPolicy	适用
`StandardPreset()`	open	allow	wescode/wesclaw/wescraft
`RegulatedPreset()`	locked	internal_only	financial/pii/healthcare
`ReadonlyPreset()`	locked	deny	展示/demo

Run 为什么不随 SSE 断开而取消？

INV-RUN-DETACH：Run 生命周期始终与传输层（SSE/HTTP 连接）解耦。SSE 断开不会取消 Run。

RunEventBuffer 保证 SSE 重连可续播（GET /runs/{runID}/events?from_seq=N）。

取消 Run 的唯一途径：

POST /sessions/{sid}/interrupt（用户主动）
CycleDetector 自愈失败后 HITL 超时（真循环）
ErrorStreakDetector HITL 超时（伪进展）
外部 BudgetCheckFn 返回 Exhausted（商业限制）
Cell Stop（生命周期）

引擎不因 counter 阈值（轮次/token/时间）主动终止。

什么是 Handle API？

Handle API 是 wesgine 的唯一契约面。

Hypervisor Handle（4 admin）：

Cells / SharedProviders / Observe / Tokens

Cell Handle（25 business）：

Runtime / Agents / Memory / Sessions / Knowledge / TaskMemory /
Skills / Tools / HITL / Learn / Channels / Email / MCPs / Cron /
HeadlessBrowser / Playwright / Desktop / Workspace /
Policy / Quotas / Tokens / Observe / Providers / Config / Events

所有业务操作走 cell.Xxx() Handle，绝不走 Hypervisor。

Plan 系统怎么工作？

Plan 是 LLM 驱动的线性清单，不是 DAG。

三个动作：

动作	说明
`plan(action=create)`	创建计划
`plan(action=update)`	更新步骤状态
`plan(action=complete)`	声明完成

四态流转：

planning → active → completed
                  → terminated (run_interrupted / nudge_exhausted / validation_failed)

Plan-pending nudge 严格上限 3 次，耗尽后 Run 正常终止、步骤留在 pending。

什么是 Actor？

Actor 是 wesgine 的运行时一等标识符。引擎基于 Actor 在 Cell 内做：

记忆隔离
资源调度
认知路由
行为归因

引擎不定义用户身份体系（认证/授权/组织架构归应用层）。

cell.Runtime().Run(ctx, AppRunRequest{
    Actor: "alice", // ★ 必填（空 → ErrActorRequired）
    // ...
})

Memory 的七层是什么？

层	性质	说明
`environment`	记忆 L1	宿主环境信息
`consensus`	记忆 L2	部门/团队共识
`about_me`	记忆 L3	关于我的偏好
`agent_memory`	记忆 L4	角色记忆
`session`	运行时	会话状态
`working`	运行时	工作缓存
`unknown`	兜底	未覆盖的 scope

关键规则：

LayerOf(entry) 是判层单点，消费方一律消费不推导
写入用 SaveToLayer(layer, ...)
列表用 ?layer= 下推到引擎 SQL
计数用 GET /memory/counts，键覆盖全部层含 0

什么是 INV-RESIL 不变量？

10 条数据韧性不变量，保障 Cell 在任何数据损坏下仍能降级运行：

ID	规则
INV-RESIL-01	Cell Boot 永远成功（降级是合法状态）
INV-RESIL-02	`Runtime().Run()` 永远可用
INV-RESIL-03	单 Layer 损坏不扩散
INV-RESIL-04	进程排他锁（flock `.cell.lock`）
INV-RESIL-05	快照验证（`PRAGMA quick_check`）
INV-RESIL-06	Journal 只追加（`O_APPEND`）
INV-RESIL-07	损坏文件保留到 `corrupt/` 目录
INV-RESIL-08	mmap 禁用（`PRAGMA mmap_size=0`）
INV-RESIL-09	VACUUM 禁止自动（中断=全损）
INV-RESIL-10	迁移全幂等

什么是 INV-EXEC-PROC-01？

一个原语生成子进程。生产 Go 一律 proc.Command(ctx, ...)（internal/infra/proc）：

建进程组（Setpgid）
cancel 时 SIGKILL 整个组（Cancel）
Wait() 封顶（WaitDelay）

// ✅ 正确
cmd := proc.Command(ctx, "go", "build", "./...")

// ❌ 禁止
cmd := exec.Command("go", "build", "./...")
cmd := exec.CommandContext(ctx, "go", "build", "./...")

裸 exec.Command / exec.CommandContext / exec.Cmd{} 只允许出现在 3 个带义务的豁免文件。已 proc.Command 的调用方不得改写 Cancel / WaitDelay。

豁免各自负债：

tool/host_shell.go：必须自设 Cancel + WaitDelay
adapter/stt/tool.go：故意脱离 ctx，必须设 SysProcAttr 建组