docs: v3 spec for startup env config + inline model selector

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-23 13:11:18 +08:00
parent 24bff6d2eb
commit 12c0f4c618
1 changed files with 67 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Cell Toolbar Actions v3 — 启动时配置 + 模型选择器
+
+- 日期: 2026-07-23
+- 状态: 已批准(用户于 2026-07-23 确认)
+- 取代: v2 `OpenCodeSettings` 范围(commit d03f0fa)。本轮把 4 个 server 连接字段全部移出 JupyterLab Settings(改走启动 env),并在 inline 输入框增加模型选择器。
+
+## 背景
+
+v2 之后用户提了 2 个调整:
+
+1. **`opencodeServerUrl` / `User` / `Password` / `requestTimeoutSeconds` 不再在 JupyterLab Settings Editor 里配** —— 全部在启动 jupyter server 时通过环境变量指定(`OPENCODE_BRIDGE_URL` / `_USER` / `_PASSWORD` / `_TIMEOUT`)。Settings Editor 只保留 `opencodeProvider` / `opencodeModel`(给模型选择器作默认选中)。
+2. **inline 输入框增加模型选择器** —— 用户可以在每次请求时挑 provider/model,覆盖 settings 默认值。
+
+## 决策
+
+| 维度 | 决策 |
+|---|---|
+| 启动 env(4 个) | `OPENCODE_BRIDGE_URL` / `_USER` / `_PASSWORD` / `_TIMEOUT`(秒,默认 120);在 `jupyter lab` 启动前 export;`config.py` `resolve_config` 走 `os.environ.get(ENV) or DEFAULT`,不再从 JupyterLab settings 兜底 |
+| JupyterLab Settings(只剩 2 个) | `opencodeProvider` / `opencodeModel` —— 给模型选择器作默认选中 |
+| `OpenCodeSettings` 前端类型 | 缩为 `{ opencodeProvider: string; opencodeModel: string }` |
+| 模型选择器 UI | inline 面板顶部加一行 `模型: <select>`(单个下拉),选项 label `provider / model`,value `providerId\|modelId`(`\|` 分隔,IDs 不含此字符);textarea 在其下方 |
+| 默认选中 | 下拉框默认选中 `settings.opencodeProvider` / `settings.opencodeModel` 拼成的项;若无对应项,默认第一项 |
+| 提交覆盖 | prompt 的 `onSubmit(text, providerId, modelId)` 把当前选中带回去;actions 用它作为 request body 的 `providerId`/`modelId`(覆盖 settings 默认) |
+| Providers 数据来源 | `GET /opencode-bridge/providers` 已在 `index.ts` 启动时拉取;本轮加一个 `setOpenCodeProviders(p)` 把结果写到 `opencode_cell_actions.ts` 模块级缓存,inline prompt 构造时读 |
+| Providers 拉取失败 | 缓存为 `null`,inline prompt **不渲染** select;提交走 settings 兜底(settings 没设就不发 `providerId`/`modelId`,OpenCode 用默认)。**优雅降级** |
+| schema | 顶层 `jupyter.lab.toolbars` 贡献不变(item 名 `opencode-cell-actions`,rank 100) |
+
+## 接口契约
+
+**前端 `OpenCodeRequest`**:与 v2 相同(无 `mode`):
+```json
+{ "prompt": "...", "context": { ... }, "providerId": "...", "modelId": "..." }
+```
+
+**后端**:与 v2 相同。`config.py` 新增:
+```python
+ENV_TIMEOUT = "OPENCODE_BRIDGE_TIMEOUT"
+DEFAULT_REQUEST_TIMEOUT = 120
+```
+`resolve_config` 4 个字段全部走 `os.environ.get(ENV) or DEFAULT`,**不再** `bridge.get(...)` 兜底(settings 字典里也不再含这 4 个 key)。`requestTimeoutSeconds` 仍是 server-side(OpenCodeClient → OpenCode Serve 的 httpx timeout),不是前端。
+
+**环境变量清单**:
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `OPENCODE_BRIDGE_URL` | `http://127.0.0.1:4096` | OpenCode Serve 地址 |
+| `OPENCODE_BRIDGE_USER` | `opencode` | HTTP Basic Auth 用户名 |
+| `OPENCODE_BRIDGE_PASSWORD` | `""`(无 auth) | HTTP Basic Auth 密码 |
+| `OPENCODE_BRIDGE_TIMEOUT` | `120` | 请求 OpenCode Serve 超时(秒,整数) |
+
+## 机制
+
+- **前端**:`OpenCodeCellActions` 多了个模块级 `_providers` 引用(由 `setOpenCodeProviders` 写入,启动时 `callOpenCodeProviders` 成功后调);构造 `OpenCodeInlinePrompt` 时把 providers + settings 默认 provider/model 传进去。点击提交 → prompt 回调带选中的 provider/model → actions 写进 `OpenCodeRequest` 的 `providerId`/`modelId` 字段。
+- **服务端**:`config.py` 完全不再读 JupyterLab settings 字典里这 4 个 key(它们已经不存在了);SessionManager / EditHandler 不变。
+- **OpenCode**:与 v2 相同。
+
+## 兼容性
+
+- `OpenCodeSettings` 类型字段减少 4 个;前端任何引用这些字段的地方需清理(grep)。
+- 之前在 JupyterLab Settings Editor 里设过这 4 个值的用户:不再生效,需改用环境变量。**行为变更,需在 changelog/release note 标注**(本次不修 release 文件,但 design.md §6 写清楚)。
+- `requestTimeoutSeconds` 行为不变(只是配置入口换了),现有 pytest 兼容。
+
+## 验证
+
+- `pytest opencode_bridge/tests/` 全过(`test_edit_handler` 改动:新 `config.py` 仍能解析 env+default)
+- `jlpm test` 全过(单测覆盖: select 渲染 N 项 / 默认选中 settings 值 / submit 覆盖 / providers 降级)
+- `jlpm build` 成功
+- 手动:`jupyter lab` 启动,active cell 右上角单按钮 → inline 面板顶部出现 `模型: [select]` 下拉(列出 OpenCode Serve 的所有 provider/model),默认选中 settings 值;切换选择 → 发送 → request 带新 provider/model