From 04d011afa11bb9514a102098b8ab58ecb7335ae0 Mon Sep 17 00:00:00 2001 From: "tao.chen" <93983997+taochen-ct@users.noreply.github.com> Date: Thu, 23 Jul 2026 12:37:49 +0800 Subject: [PATCH] docs: design.md v2 interaction + contract (single button, no mode) Co-Authored-By: Claude Fable 5 --- design.md | 53 ++++++++++++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/design.md b/design.md index 54c3228..bbd7300 100644 --- a/design.md +++ b/design.md @@ -42,11 +42,10 @@ ## 🎨 2. 交互与UI流程设计 -1. **原生 Cell Toolbar 集成（2026-07-23 修正）**：不再自绘悬浮 toolbar。`✨ 优化` / `🐛 智能排错`（**仅当 Cell 有 Error Output 时亮起**）/ `🪄 智能编辑` 三个按钮通过 `IToolbarWidgetRegistry.addFactory('Cell', 'opencode-cell-actions', ...)` 注入 JupyterLab 原生 cell toolbar，显示在 **active cell 右上角**（move up/down 按钮旁，`rank: 100` 排在 delete 右侧）；仅 `CodeCell` 显示，随 active cell 切换移动。 +1. **原生 Cell Toolbar 单按钮（2026-07-23 v2 修正）**：不再自绘悬浮 toolbar，也合并了 v1 的三个 mode（优化/排错/编辑）为单个 `🪄 AI 智能编辑` 图标按钮。通过 `IToolbarWidgetRegistry.addFactory('Cell', 'opencode-cell-actions', ...)` 注入 JupyterLab 原生 cell toolbar，显示在 **active cell 右上角**（move up/down 按钮旁，`rank: 100` 排在 delete 右侧）；仅 `CodeCell` 显示，随 active cell 切换移动。**前端不做任何语义处理** —— 不再发 `mode` 字段，后端用统一的系统提示词 + 用户的自然语言指令 + 上下文（含 traceback）由 LLM 自己判断是优化/排错/编辑。 -2. **Inline Prompt 框（按需展开）**： -* 用户点击 `🪄 智能编辑` 后，在当前 Cell 下方平滑展开一个微型输入框（带 `Textarea` + `🚀 发送` 按钮）。 +2. **Inline Prompt 输入框（v2 实现）**：点击 `🪄 AI 智能编辑` 按钮后，`OpenCodeInlinePrompt` widget 追加到当前 `CodeCell` 的 DOM 末尾，呈现内嵌输入面板：多行 `textarea`（placeholder "向 AI 描述你想要的修改…"，无默认值）+ `🚀 发送` + `✕ 取消` 两个按钮。提交时前端仅收集 cell `source` / `outputs` / `error` 与用户在 textarea 里写的指令，POST `/opencode-bridge/edit`，body 为 `{prompt, context, providerId?, modelId?}`（**无 `mode`**）。**成功** → 前端调用 `cell.model.sharedModel.setSource(resp.finalSource)` 就地替换 cell 源码 + `Notification.info`；**失败** → `Notification.error`，输入框保留（可改文案重发）。Session 由服务端 `SessionManager` 保证 1 notebook 1 sid（前端不感知）。 3. **流式替换/Diff 预览**： @@ -58,43 +57,43 @@ ## 🔌 3. 接口契约设计 (API Contract) -### 接口：`POST /opencode/v1/generate` (支持 SSE 流式返回) +### 接口：`POST /opencode-bridge/edit`（v2 — 无 `mode`） -**Request Payload (前端 Context Provider 打包发给 Server Extension)**: +**Request Payload**（前端 `OpenCodeCellActions` 在用户提交 inline 输入框时发出）： ```json { - "action": "custom_edit", // custom_edit | fix_error | optimize "prompt": "把这段代码改为用 plotly 绘制交互式折线图", "context": { - "notebook_path": "analysis/demo.ipynb", - "target_cell": { - "index": 3, - "code": "import matplotlib.pyplot as plt\nplt.plot([1, 2, 3])", - "error_output": "ModuleNotFoundError: No module named 'matplotlib'" - }, - "surrounding_cells": [ - { "index": 2, "code": "import pandas as pd" } - ] - } + "notebookPath": "analysis/demo.ipynb", + "cellId": "cell-3", + "language": "python", + "cellIndex": 3, + "totalCells": 5, + "source": "import matplotlib.pyplot as plt\nplt.plot([1, 2, 3])", + "previousCode": "import pandas as pd", + "error": null + }, + "providerId": "anthropic", + "modelId": "claude-sonnet-4-20250514" } - ``` -**Response (Server Extension 流式透传 OpenCode Serve 的 SSE 响应)**: +> **v2 变化**：body 不再含 `mode` / `action` 字段。前端只把 cell 的 input/output/error 收集到 `context`，加用户的自然语言 `prompt` 一起发出；后端用统一的 `UNIFIED_SYSTEM_PROMPT` + LLM 自己判断优化/排错/编辑。`providerId` / `modelId` 来自 JupyterLab settings 透传。 -```text -event: chunk -data: {"text": "import plotly.express as px\n"} - -event: chunk -data: {"text": "fig = px.line(x=[1, 2, 3], y=[1, 2, 3])\nfig.show()"} - -event: done -data: {"status": "success"} +**Response**（当前 v2 实现：单次 JSON；SSE 流式属于 Slice 4 后续工作）： +```json +{ + "ok": true, + "finalSource": "import plotly.express as px\nfig = px.line(x=[1, 2, 3], y=[1, 2, 3])\nfig.show()", + "sessionId": "ses-abc123", + "notebookPath": "analysis/demo.ipynb" +} ``` +> 成功时前端用 `finalSource` 就地替换 cell 源码（`cell.model.sharedModel.setSource`）。Session 由服务端 `SessionManager` 按 `notebookPath` 复用（1 notebook 1 sid），404 / `session not found` 时服务端自动 invalidate 并在下次请求重建。 + --- ## 🛠️ 4. 核心前端实现逻辑 (TypeScript)