日志与诊断

wescode 的日志契约：事件命名、决策点记录与排障指南。

日志文件

Go 日志与 Electron 日志不重复——两端各自记录自己的事件。

事件命名规范

attach.* 事件

文件附件相关事件：

send.* 事件

消息发送相关事件：

L2 决策点事件

验证体系决策记录：

排障指南

"点了没反应"

从 send.enter 开始排查：

send.enter 存在？
  ├── 否 → 前端事件没到后端（检查 RPC 通道）
  └── 是 → send.model 存在？
        ├── 否 → 模型选择失败（检查 provider）
        └── 是 → send.run 存在？
              ├── 否 → Run 创建失败
              └── 是 → 检查 send.done / send.error

"附件没生效"

从 attach.pick 开始排查：

attach.pick 存在？
  ├── 否 → 文件选择器没触发
  └── 是 → attach.resolve 存在？
        ├── 否 → 文件解析失败
        └── 是 → 检查 attach.fail

Go→TS 通知契约（INV-WS-12）

Go 能发的通知方法名是封闭集合：

• 权威源：internal/notify/method.go
• TS 类型由 notify/tsgen.go 从 Go AST 生成
• 新增 Method 而忘了接线 → tsc 报错，不是运行时静默

引擎版本记录

引擎启动后记录版本：

slog.Info("boot: engine version", "sdk_version", eng.Hypervisor.Version())

版本降级会导致 spec 解码失败（teleclaw 事故实证）。

相关文档

• Device Agent → device-agent.md
• 工作区即 Cell → workspace-cell.md
• wesgine 可观测性 → engine observability.md