notebook-ai-extension/docs/superpowers/specs/2026-07-23-cell-toolbar-actions-v3-design.md

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):

{ "prompt": "...", "context": { ... }, "providerId": "...", "modelId": "..." }

后端:与 v2 相同。config.py 新增:

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