jlceda-mcp: Instructions file for Claude Code

CLAUDE.md — jlceda-mcp

新会话进来先读这份，再读 README.md（那份是给人看的用法）。 这份是给 agent 看的：架构、不许破坏的不变量、会浪费你半小时的坑。

两个组件

目录	是什么	跑在哪
src/	MCP server + 内嵌 broker	Claude Code 起的 node 进程
jlc-bridge/	嘉立创EDA 扩展	EDA 渲染进程的沙箱里

Claude Code ⇄(stdio) mcp-server ⇄(ws://127.0.0.1:18800/ws/bridge) JLC MCP 扩展 ⇄ EDA
                       └─ broker 就长在这里

---

⚠ 不变量 1：EDA 每次调用扩展都会把整个 bundle 重新求值一遍

这是这个项目最反直觉的一条，旧版三个 bug 里有两个是它造成的。

从 EDA 安装目录 assets/pro-api/*/api.js 的 Ta() 逆出来的事实： 菜单点击走 extensionApi.callFunctionInExtension → Ta(uuid, fnName)，而 Ta 会

1. 重新从 IndexedDB 读出 entry 文件的源码
2. 在末尾拼一段 if (typeof fnName === 'function') { fnName(...) } else if (edaEsbuildExportName...)
3. 包进 with (sandbox) { ... }，用 AsyncFunction 整个重新 eval

也就是说：

模块级的 let / 闭包变量，在两次菜单点击之间不保留。 启动激活、点「状态」、点「暂停」，每一次都是一个全新的模块实例。

能跨越重新求值活下来的只有三样：

• EDA 按 ID 托管的资源：sys_Timer 的定时器、sys_WebSocket 的连接、sys_Storage 的配置
• globalThis 上挂的东西（沙箱没拦 globalThis，实测可读可写）
• 已经跑起来的闭包（第一次求值时注册的 onMessage 回调会一直用那一版代码）

所以：所有跨调用的状态一律挂在 hub.ts 的 globalThis.__JLC_BRIDGE_HUB_V2__ 上， 每个导出函数第一件事都是 boot()（幂等）。别写 let connected = false 这种。

装了新版扩展之后，还活着的 onMessage 闭包是上一版代码的。 link.ts 靠 hub.codeBuild !== CODE_BUILD 发现这件事并推倒重连，让新代码接管。别删。

⚠ 不变量 2：sys_WebSocket 没有 close / error 回调

register(id, url, onMessage, onConnected) 就这四个参数。对端死了扩展毫无感知。

推论：

• 判活只能靠「最近一次收到数据的时间」（hub.lastRxAt）。broker 每 3 秒 ping 一次 就是为了喂这个判据；扩展收到 ping 回 pong。超过 RX_TIMEOUT_MS 没动静就判死重连。
• 连不上时同样一个回调都不给：对端不在时 new WebSocket(...) 照样构造成功， 失败是异步的，onConnected 永远不来。所以 connecting 必须有超时 （CONNECT_TIMEOUT_MS），超了就 hardReset 重来。 少了这条，phase 会永远停在 connecting、心跳再也不会重新 register， 表现就是用户报的「先开 EDA、后开 Claude Code，必须手动点一次重连」。 所有重连判断集中在 advance() 一处，别再散出去。
• 连上之后扩展要主动 ping（KEEPALIVE_MS）。往一个已关闭的 socket 上 send 会抛， 这是对端消失时唯一能快速察觉的信号；没有它就得干等 11 秒的接收超时。
• register() 遇到同 ID 且 readyState 是 CONNECTING 或 OPEN 的连接时，会 立刻同步调用 onConnected 然后返回：注意 CONNECTING 也算。 所以「onConnected 被调了」≠「连上了」。phase 从 connecting 翻到 online 必须发生在收到第一帧的时候，不能在 onConnected 里。
• 反过来，这个复用语义让 ensureLink() 天然幂等：已经连着时再调就是个空操作。 这正是「每次点菜单都调一遍」能成立的原因。