cardbuddy 0.7.0 → 0.8.0

package/README.md

@@ -72,6 +72,7 @@ cardbuddy --preview          # 等价短参 -p
 | `DSL_EDITOR_SRC` | _(空)_ | 内核开发用：指向本地编辑器 `preview/` 源码，绕过 vendored 快照调试。 |
 | `DSL_DEV_PREVIEW` | `0` | 设为 `1` 等价于 `--preview`：同端口托管打包后的编辑器前端并自动打开浏览器。 |
 | `DSL_PREVIEW_ROOT` | _(空)_ | 自定义 preview 前端构建产物目录（默认包内 `dist/preview-editor/`，回退 `cwd/dist`）。 |
+| `DSL_EDITOR_CMD` | _(空)_ | 代码桥外部编辑器命令（如 `code` / `cursor` / 带参数整串），按 shell 语义执行并追加临时文件路径；缺省按平台拉起 VSCode（mac `open -a`、win `cmd /s /c "code"`、linux `code`），CLI 缺失再回退 `vscode://` 协议。 |
 
 ---
 
@@ -110,9 +111,29 @@ DSL_DEV_HTTPS=1 cardbuddy
 | `GET /__history` | 自包含 | 编辑历史 |
 | `GET /__screenshot/:id` | 自包含（需 Playwright + 系统 Chrome）| 无头截图 |
 | `GET /__events` (SSE) | 自包含 | `cards-changed` 实时推送 |
+| `POST /__code-bridge` | 自包含 | 代码桥：代码写临时 js 并拉起外部编辑器，返回 `{ id, file }` |
+| `GET /__code-bridge/:id` | 自包含 | 代码桥：拉取外部保存后的最新代码（LF 归一） |
+| `POST /__code-bridge/:id/heartbeat` | 自包含 | 代码桥：会话心跳（前端 5s 一次） |
+| `DELETE /__code-bridge/:id` | 自包含 | 代码桥：结束会话并删除临时文件 |
 
 > **FinMall 凭据只在本机**：`/__sync` `/__save` `/__preview` 由本地服务代理 FinMall，凭据存于本机 `skills/finmall-card-sync` 与 `.env.finmall`，公网前端永不接触。
 
+### VSCode 代码桥（事件面板代码编辑区）
+
+事件配置面板的代码编辑区底栏右侧有 VSCode 图标：点击后把当前代码片段写到
+`os.tmpdir()/cardbuddy-code-bridge/<session>.js` 并用外部编辑器打开；编辑器内**保存**即经
+文件监听 + SSE（`code-bridge-changed`）实时回写编辑区（桥接期间 Web 编辑区只读，避免双向冲突）。
+
+- **清除语义**：会话结束 = 再次点击图标断开 / 面板关闭 / 组件卸载（前端 `DELETE`），
+  或心跳 TTL 兜底（20s 无心跳即删，覆盖关浏览器 / 崩溃）；服务启动时清扫 >24h 残留。
+  VSCode 标签页关闭事件不装扩展拿不到，故不以「关标签」为清除时机。
+- **回声环防护**：服务端写入哈希去重（忽略自写回声）；前端回写用 `updateCode(code, false)`
+  不触发 onUpdate，不会把收到的内容再写回临时文件。
+- 换编辑器：`DSL_EDITOR_CMD=cursor` 或任意命令整串（按 shell 语义执行，开发者自配环境变量）。
+- **拉起方式**（任一级 spawn 失败或非 0 退出自动降下一级）：
+  win `code "<file>"` → `vscode://` 协议；mac `open -a "Visual Studio Code"` → `code` CLI → `vscode://` 协议；
+  linux `code` → `xdg-open vscode://`。文件监听 win/mac/linux 均走 chokidar（原子保存改名覆盖可捕）。
+
 ---
 
 ## 依赖：FinMall skill