# 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