名称: 调试连接描述: 调试CLI与FigJam插件之间的WebSocket连接问题。当图表不同步或连接失败时使用。

WebSocket连接调试

架构

┌─────────────┐     WebSocket      ┌─────────────────┐    postMessage    ┌─────────────────┐
│  CLI服务端  │ ◄───────────────► │  插件UI界面     │ ◄───────────────► │  插件主逻辑     │
│  (Bun)      │   ws://...:3456   │  (ui.ts)        │                   │  (code.ts)      │
└─────────────┘                   └─────────────────┘                   └─────────────────┘
     │                                   │                                     │
     │ 文件监听器                         │ 浏览器API                           │ Figma API
     │ YAML解析                          │ WebSocket客户端                     │ 画布渲染
     └───────────────────────────────────┴─────────────────────────────────────┘

常见问题与解决方案

1. 连接被拒绝

症状: 插件显示“正在连接…”且无限期持续

检查:

# CLI服务端是否在运行？
ps aux | grep "figram serve"

# 检查端口可用性（默认：3456）
lsof -i :3456

解决方案: 使用 bun run packages/cli/src/index.ts serve diagram.yaml 启动CLI

2. 连接断开

症状: 初始工作正常，随后停止同步

检查:

插件UI控制台中的WebSocket关闭事件
CLI终端中的错误消息

解决方案: 检查是否有YAML解析错误阻塞更新

3. 补丁未应用

症状: 已连接但画布未更新

调试步骤:

检查CLI输出中的补丁生成情况
检查插件UI控制台中接收到的消息
检查插件主逻辑控制台中的渲染错误

4. YAML解析错误

症状: CLI显示验证错误

解决方案: 验证YAML语法和模式合规性

5. 密钥不匹配

症状: 连接建立但立即关闭

检查: 确保CLI和插件之间的 --secret 标志值匹配

6. JSON导入错误

症状: 导入对话框显示错误警报

检查:

JSON必须是一个对象
DSL JSON需要 version、docId 和 nodes 数组
IR JSON需要 version、docId 和 nodes 对象

解决方案: 修复警报中显示的验证错误（路径 + 消息）

调试工具

CLI端

# 以详细输出模式运行
DEBUG=* bun run packages/cli/src/index.ts serve diagram.yaml

# 指定自定义端口
bun run packages/cli/src/index.ts serve diagram.yaml --port 8080

# 带身份验证
bun run packages/cli/src/index.ts serve diagram.yaml --secret mysecret

插件UI端

右键点击插件UI → 检查
检查控制台中的WebSocket事件
检查网络选项卡中的WS帧

插件主逻辑端

Figma桌面版 → 插件 → 开发 → 打开控制台
检查渲染错误

WebSocket协议

插件 → CLI 消息

// 连接初始化
interface HelloMessage {
  type: "hello";
  docId: string;
  secret?: string;  // 如果服务器需要身份验证
}

// 请求完全同步（例如，重新连接后）
interface RequestFullMessage {
  type: "requestFull";
  docId: string;
}

CLI → 插件消息

// 完整文档同步
interface FullMessage {
  type: "full";
  rev: number;        // 当前修订号
  ir: IRDocument;     // 完整的规范化文档
}

// 增量更新
interface PatchMessage {
  type: "patch";
  baseRev: number;    // 预期的当前修订
  nextRev: number;    // 应用后的新修订
  ops: PatchOp[];     // 要应用的操作
}

// 错误通知
interface ErrorMessage {
  type: "error";
  message: string;
}

补丁操作

type PatchOp =
  | { op: "upsertNode"; node: IRNode }
  | { op: "removeNode"; id: string }
  | { op: "upsertEdge"; edge: IREdge }
  | { op: "removeEdge"; id: string };

快速诊断

# 1. 启动CLI服务端（默认端口：3456）
bun run packages/cli/src/index.ts serve examples/diagram.yaml

# 2. 使用wscat测试WebSocket（如果已安装）
wscat -c ws://localhost:3456

# 3. 发送hello消息
{"type":"hello","docId":"test"}

# 4. 检查YAML是否有效
bun run packages/cli/src/index.ts build examples/diagram.yaml

消息流

插件                          CLI
  │                              │
  │──── HelloMessage ───────────►│  (docId, secret?)
  │                              │
  │◄──── FullMessage ───────────│  (rev, ir)
  │                              │
  │      [YAML文件变更]          │
  │                              │
  │◄──── PatchMessage ──────────│  (baseRev, nextRev, ops)
  │                              │
  │      [插件重新连接]          │
  │                              │
  │──── RequestFullMessage ─────►│  (docId)
  │                              │
  │◄──── FullMessage ───────────│  (rev, ir)
  │                              │

名称: 调试连接 描述: 调试CLI与FigJam插件之间的WebSocket连接问题。当图表不同步或连接失败时使用。