@fanchaozz/provider-manager 0.1.0 → 0.2.0

package/README.md

@@ -14,29 +14,15 @@
 pi install npm:@fanchaozz/provider-manager
 ```
 
-包托管在 **GitHub Packages**。首次安装时 npm 需要知道这个 registry。把这几行加到用户级 `~/.npmrc`（一次性）：
+依赖：`@earendil-works/pi-coding-agent`（pi 自带）。jiti 向上找 `node_modules`，**不需要**在扩展目录内 `npm install`。
 
-```ini
-# ~/.npmrc
-@fanchaozz:registry=https://npm.pkg.github.com/
-//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-```
-
-token 只需要 `read:packages` scope（包是 public 的）。之后 `npm install` / `pi install` 对所有 `@fanchaozz/*` 包都不用再配置。
-
-### 如果没法访问 GitHub Packages
-
-```bash
-git clone https://github.com/fanchaozz/provider-manager.git
-ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
-# Windows: mklink /D "%USERPROFILE%\.pi\agent\extensions\provider-manager" "%CD%\provider-manager"
-```
+安装后，首次加载时会自动创建 `~/.pi/agent/provider-manager.json`（见 [用户配置](#用户配置--provider-managerjson)）。删除该文件即可回退到代码默认。
 
-然后重启 pi。扩展每次重载都从软链目录读。
+---
 
-首次启动后，`~/.pi/agent/provider-manager.json` 会自动创建。删掉它就回退到内置默认。
+## 最近变更
 
----
+版本变更记录看 [CHANGELOG.md](./CHANGELOG.md)。
 
 ## 快速开始
 
@@ -45,8 +31,8 @@ ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
 | 打开仪表盘 | `/providers` |
 | 列出 provider + 它们的 model | `/providers ls`（过滤：`/providers ls kdapi`） |
 | 新增 provider | 仪表盘 Providers 面板按 `n`，或 `/providers add [<id>]` |
-| 新增 model | 仪表盘 `Tab` 切到 Models 面板按 `n`，或 `/providers model <pid> add` |
-| 编辑 provider / model | 仪表盘按 `e` |
+| 新增 / 删除 model | **仅通过 sync**（仪表盘 Models 面板按 `y`）。model 不可手动新增 |
+| 编辑 provider / model | 仪表盘选中后按 `Enter`（表单里 Enter 进入字段 edit、确认） |
 | 删除 | 仪表盘按 `d`（确认对话框） |
 | 从 provider 的 API 拉取新 model 列表 | 仪表盘按 `y`，或 `/providers sync [<pid>]` |
 | 探测 auth + 可达性 + 1-token 测试调用 | 仪表盘 `t`（当前 model）或 `T`（provider 内全部） |
@@ -54,7 +40,7 @@ ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
 | 打印命令帮助 | `/providers help` |
 | 关闭仪表盘 | `q` 或 `Esc` |
 
-`sync` 命令是给全新 provider 填充 model 列表最快的方式：拉取远端 model 列表，显示 checklist，把选中的写回。
+`sync` 命令是给全新 provider 填充 model 列表最快的方式：拉取远端 model 列表，显示 checklist，把选中的写回。**model 只能通过 sync 增删**（仪表盘 `n` 在 model 面板已停用）。
 
 ---
 
@@ -62,10 +48,10 @@ ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
 
 `/providers` 打开两栏 TUI：
 
-- **左栏** —— provider（id + model 数）
-- **右栏** —— 选中 provider 的 model（id + `[R]` reasoning / `[I]` image 标记 + ctx / max）
-- **详情条** —— 选中行的原始 JSON
-- **底栏** —— 当前按键说明
+- **左栏** —— provider（id + auth 状态 + model 数；0 model 时 ⚠ 提示）
+- **右栏** —— 选中 provider 的 model（id + `[R]` reasoning / `[I]` image 标记 + ctx / max；R / I 实际值，未启用是 `-`）
+- **详情面板** —— 选中行分组：Identity / Endpoint / Auth / Capabilities / Limits / Thinking levels / Cost
+- **底栏** —— 按面板调整的按键提示（按 `?` 看完整 help）
 
 ### 按键绑定
 
@@ -73,29 +59,37 @@ ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
 |---|---|
 | `↑↓` / `j k` | 在当前面板上下移动 |
 | `g` / `G` | 跳到顶 / 底 |
-| `Tab` | 切换 Providers ↔ Models 面板 |
-| `n` | 新增：Providers 面板下加 provider，Models 面板下加 model |
-| `e` | 编辑选中的 provider / model |
+| `←` / `→` | 切换 Providers ↔ Models 面板 |
+| `n` | **仅 Providers 面板**：新增 provider。Model 面板已停用（model 只能 sync） |
+| `Enter` | 选中行进入 edit 表单（Provider 或 Model） |
 | `d` | 删除（带确认对话框） |
 | `y` | 同步（拉取选中 provider 的远端 model 列表） |
-| `t` / `T` | 探测当前 model / provider 内全部 model |
-| `?` | 切换帮助覆盖层 |
+| `t` / `T` | **仅 Models 面板**：探测当前 model / provider 内全部 model |
+| `?` | 切换帮助覆盖层（按面板显示特有键） |
 | `q` / `Esc` | 关闭仪表盘 |
 
-provider 列表为空时，在 Models 面板按 `n` 会切到 Providers 面板并提示先创建一个。
+底部提示按面板动态调整（provider 面板显示 `n`、model 面板显示 `t` / `T`），不会出现在不该出现的面板里。
 
 ---
 
 ## 同步流程
 
-`sync` 是批量加 model 最快的方式。它会拉取选中 provider 的远端 model 列表并显示 checklist。
+`sync` 是批量加 model 的唯一方式。它会拉取选中 provider 的远端 model 列表并显示 checklist。
 
-checklist **展示该 provider 的所有 model —— existing + remote new 都有**：
+**checklist 展示该 provider 的所有 model**（existing + remote new 都有）：
 
 - 已有 model 标 `<id>  (existing)`，默认勾选。取消勾选 = 删除。
 - 远端新 model 只标 `<id>`，默认不勾选。勾选 = 添加。
 
-按 `Enter` 写入结果，按 `Esc` 取消。保存时，最终 `models.json` 是（勾选的 existing）+（勾选的 new）的并集；如果某 model 同时被远端和 local 都有并都被勾选，优先用远端定义（这样能拉到最新的 `reasoning` / `input` / `ctx` / `maxTokens` / `thinkingLevelMap` 来自默认 model 配置）。
+按 `Enter` 写入结果，按 `Esc` 取消。保存时最终 `models.json` 是 (勾选的 existing) + (勾选的 new) 的并集；远端 new 优先于 local（这样能拉到最新的 `reasoning` / `input` / `ctx` / `maxTokens` / `thinkingLevelMap`）。
+
+**新加的 model 字段来自 `~/.pi/agent/provider-manager.json` 的 `defaultModel` 段**（不是代码内置默认）—— 这是 `loadDefaultModelConfig()` 的行为。在 sync 前编辑这个文件可以定制 sync 出来的 model 模板。
+
+**proxy 字段**：provider 编辑表单里可填 `proxy`（形如 `http://127.0.0.1:7890`）。sync 时设到 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量，请求结束后还原。其他并发 fetch 会临时看到同一 proxy（env 是进程全局的，sync 一次只 1 个 fetch）。
+
+**apiKey 字符约束**：sync 拒绝 `code > 255` 的 apiKey（含 `•`、中文、emoji 等，常见于复制粘贴残留）。错误是 actionable：`apiKey contains non-Latin-1 character at position 7 (U+2022). Re-enter the key in the provider form.`
+
+**检测 noise**：默认过滤 `embed*` / `tts` / `whisper` / `dall-e` / `clip` / `moderation` / `image-*` 等 embedding/tts/image-gen 类 model。
 
 ---
 
@@ -147,40 +141,43 @@ checklist **展示该 provider 的所有 model —— existing + remote new 都
 
 ## 表单编辑器（新增/编辑 model/provider）
 
-`addProviderFlow` / `editProviderFlow` / `addModelFlow` / `editModelFlow` / `deleteProviderFlow` / `deleteModelFlow` 都共用一个 TUI 表单（`components.ts:FormEditor`）。
+`addProviderFlow` / `editProviderFlow` / `editModelFlow` / `deleteProviderFlow` / `deleteModelFlow` 都共用一个 TUI 表单（`components.ts:FormEditor`）。**`addModelFlow` 已停用**——model 只能通过 sync 增删。
 
 ### 字段类型
 
 | 类型 | 行为 |
 |---|---|
 | `text` | 自由文本输入 |
-| `secret` | 自由文本，TUI 渲染时遮罩 |
+| `secret` | 同 `text`，但用 `Enter` 进入 edit 后显示真实值（不显示 masked `••••Xn`），切 field 不写回 masked 覆盖原 key |
 | `number` | 自由数字输入，提交时校验 |
-| `select` | 选项列表；按 `e` 进 edit 模式，`Space` 选中，`↑↓`/`jk` 导航，`Enter` 确认 |
+| `select` | 选项列表；按 `Enter` 进 edit，`Space` 选中，`↑↓` / `jk` 导航，再 `Enter` 退出 |
 | `multiselect` | 类似 `select` 但可多选；`Space` 切换每项 |
 | `levelmap` | 7 行（`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`）；`Space` 切换每项；提交时归一化缺失的 key 为 `null` |
 | `readonly` | 仅展示，不可编辑 |
 
-### 按键绑定
+### 按键绑定（统一 view / edit 两态模型）
 
-| 键 | 行为 |
-|---|---|
-| `e` / `E` | 进入 edit 模式（仅 `select` / `levelmap` / `multiselect`） |
-| `Esc` / `q` | edit 中：退出 edit（commit 当前值）。其他：取消整个表单 |
-| `s` | 保存整个表单。仅在 non-typeable 字段生效 — `s` 在 `text` / `secret` / `number` / `json` 里是字符 |
-| `Enter` | edit 中（非输入字段）：commit 并退出 edit。typeable 字段：commit + 移到下一字段。readonly 字段：保存表单 |
-| `Space` | edit 中（非输入字段）：切换当前选项 |
-| `↑↓` / `j k` | 字段间导航；edit 中（非输入字段）：选项间导航 |
-| `Backspace` | 删最后一个字符（typeable 字段） |
+| 键 | view 模式 | edit 模式 |
+|---|---|---|
+| `↑↓` / `j k` | 切字段 | non-typeable：选项内 nav；typeable：no-op（j/k 是字符） |
+| `Enter` | 进 edit | commit + 退出 edit（留在原字段） |
+| `Esc` / `q` | 取消整个 form | 退出 edit（commit） |
+| `s` | 保存整个 form | no-op（typeable 里 s 是字符；non-typeable 忽略） |
+| `Space` | non-typeable 快捷进 edit | non-typeable 切换 / 选中 |
+| `Backspace` | no-op | typeable 删最后一个字符 |
+| 字符 | no-op | typeable 追加到 draft |
 
-### 新增 model 流程："Use default config?"
+**view 模式不接受任何字符输入**（含 `s` / `q` / 数字 / 字母）。需要先按 `Enter` 进 edit 才能改。
 
-`addModelFlow` 在 name 之后问一次：
+**typeable 字段的 `j` / `k` 在 view 模式是 nav**（不当作字符），在 edit 模式是字符。
 
-- **Yes** — 应用 `DEFAULT_MODEL_CONFIG`（见 [用户配置](#用户配置--provider-managerjson)），跳过剩余问题
-- **No** — 逐个问 reasoning / input / ctx / max / thinking-level-map
+**secret 字段的两种保护**（避免保存的 key 被 masked 显示覆盖）：
+1. 进入 edit 时 `draft` 恢复为真实值（不是 masked `••••Xn`），用户能看见 / 修改真 key
+2. commitDraft 在 `draftIsOriginal=true`（用户没改）时不写回，保证原 key 完整
 
-`Esc` 在任何问题中都能取消整个流程（仪表盘自动恢复）。
+### `addProviderFlow` 与 `editProviderFlow` 结构同形
+
+两个流程都用同一个 FormEditor 模板（含 `id` / `name` / `baseUrl` / `apiKey` / `api` / `authHeader` / `proxy` 字段）。`addProviderFlow` 的 `id` 字段有 `validate`：字符集 `[a-z0-9_-]+` + 不能与已有 provider 重复（`json.providers[s]` 已存在则报 "provider already exists"）。错误留在 FormEditor 自带的 `⚠ ...` 行显示，不弹 notify 打断流程。
 
 ---
 
@@ -218,21 +215,25 @@ cp ~/.pi/agent/models.json.bak ~/.pi/agent/models.json
 
 ## 故障排查
 
-**`pi install` 报 `E404` 或 "no such package"。** 你的 npm registry 里没有 GitHub Packages。把它加到 `~/.npmrc`（见 [安装](#安装)）或用 git-clone 降级方案。
+**`pi install` 报 `E404` 或 "no such package"。** npm registry 没收到这个包名。先 `npm view @fanchaozz/provider-manager` 看是否发布成功；如果成功还报，检查 `npm config get registry` 输出不是 `npm.pkg.github.com`。
 
 **仪表盘打开是空的。** 你的 `models.json` 里没有自定义 provider。本扩展只管 `models.json` — pi 内置 provider（anthropic / openai / google 等）不显示，用 pi 内置的 `/model`。
 
-**Sync 报 `ECONNREFUSED` / `ENOTFOUND`。** 选中 provider 的 `baseUrl` 不通。用 `/providers edit <pid>`（或仪表盘 `e`）改。
+**Sync 报 `ECONNREFUSED` / `ENOTFOUND`。** 选中 provider 的 `baseUrl` 不通。用仪表盘选中该 provider 后按 `Enter` 进 edit 表单改。
 
 **Sync 报 `HTTP 500` / `HTTP 401`。** `baseUrl` 错或 `apiKey` 缺失/错。在 provider 编辑表单里核对。
 
-**设的 thinking level 一保存就消失。** pi 可能不支持该 level — 换别的，或者填 `null` 禁用。
+**Sync 报 `Cannot convert argument to a ByteString`。** apiKey 含非 Latin-1 字符（`•`、中文、emoji 等，常见于复制粘贴残留）。**重新打开 provider 的 edit 表单，把 apiKey 字段清空再贴一次**真 key。
+
+**Sync 总是 `ctx=128000` / `max=16384`（默认值），看起来没读到 user 配置。** 检查 `~/.pi/agent/provider-manager.json` 是否存在 + 路径正确（必须正好是这个文件名，不是 `providers.json` 等）。校验：`node -e "JSON.parse(require('fs').readFileSync(process.env.HOME+'/.pi/agent/provider-manager.json','utf8'))"`。
 
-**`provider-manager.json` 里的修改全部失效。** 文件损坏或校验失败（见 [Schema](#schema)）。扩展会静默 fallback 默认。校验：`node -e "JSON.parse(require('fs').readFileSync(process.env.HOME+'/.pi/agent/provider-manager.json','utf8'))"`。
+**Dashboard 显示的 `apiKey status` 与真状态不一致。** dashboard 不通过 pi runtime 检测 key 是否真有效（避免 OAuth / runtime / env / extension 多路径歧义），只自检 `models.json` 里 `apiKey` 字段是否非空。**真认证测试用 `t` / `T`**。
 
-**Sync 加的 model 字段错（不管什么都 `ctx=128000`）。** model 用的是默认，不是文件。文件没被读。检查路径：必须正好是 `~/.pi/agent/provider-manager.json`（不是 `~/.pi/agent/providers.json` 之类）。
+**保存 secret 字段后 apiKey 变成了 `••••Xn`。** 这是 0.1.x 的老 bug（切 field 时 commitDraft 把 masked 字符串写回原 key）。0.2.0 已修：进入 edit 时 draft 恢复真实值，未改时 commitDraft 跳写。**0.2.0 起，re-enter edit 表单不会改变 key**。如果是老版本升上来：edit 表单里把 apiKey 清空再贴一次真 key。
+
+**设的 thinking level 一保存就消失。** pi 可能不支持该 level — 换别的，或者填 `null` 禁用。
 
-**按 `n` / `e` / `d` / `y` 后 Esc 仪表盘消失。** 当前版本不应发生 — 仪表盘会自动恢复。如果发生了，请带 `~/.pi/agent/provider-manager.log` 反馈。
+**按 `n` / `Enter` / `d` / `y` 后 Esc 仪表盘消失。** 当前版本不应发生 — 仪表盘会自动恢复。如果发生了，请带 `~/.pi/agent/provider-manager.log` 反馈。
 
 ---
 

package/README_EN.md

@@ -14,29 +14,15 @@ A pi extension that manages custom providers and models in `~/.pi/agent/models.j
 pi install npm:@fanchaozz/provider-manager
 ```
 
-The package is hosted on **GitHub Packages**. The first time you install, npm needs to know about this registry. Add this once to your user-level `~/.npmrc`:
+The extension depends on `@earendil-works/pi-coding-agent` (shipped with pi). jiti walks up `node_modules`, so **no `npm install` is needed** inside the extension directory.
 
-```ini
-# ~/.npmrc
-@fanchaozz:registry=https://npm.pkg.github.com/
-//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
-```
-
-The token only needs the `read:packages` scope (it's a public package). After that, `npm install` / `pi install` works for all `@fanchaozz/*` packages without further setup.
-
-### If you can't reach GitHub Packages
-
-```bash
-git clone https://github.com/fanchaozz/provider-manager.git
-ln -s "$(pwd)/provider-manager" ~/.pi/agent/extensions/provider-manager
-# or, on Windows: mklink /D "%USERPROFILE%\.pi\agent\extensions\provider-manager" "%CD%\provider-manager"
-```
+After install, `~/.pi/agent/provider-manager.json` is auto-created on first load (see [User config](#user-config--provider-managerjson)). Delete it to fall back to the code default.
 
-Then re-launch pi. The extension reads from the symlinked directory on every reload.
+---
 
-After the first launch, `~/.pi/agent/provider-manager.json` is auto-created. Delete it to revert to the built-in defaults.
+## Recent changes
 
----
+Version history in [CHANGELOG.md](./CHANGELOG.md).
 
 ## Quick start
 
@@ -88,14 +74,22 @@ When the provider list is empty, pressing `n` on the Models pane switches to the
 
 ## Sync flow
 
-`sync` is the fastest way to add a batch of models. It fetches the remote model list for the selected provider and shows a checklist.
+`sync` is the **only** way to add a batch of models. It fetches the remote model list for the selected provider and shows a checklist.
 
 The checklist **shows every model for that provider — both existing and remote new**:
 
 - Existing models are labelled `<id>  (existing)`, default checked. Uncheck to delete.
 - Remote new models are labelled `<id>` only, default unchecked. Check to add.
 
-Press `Enter` to write the result, `Esc` to cancel. On save, the final `models.json` is the union of (checked existing) + (checked new); remote new is preferred over local if both are checked (so you pick up the fresh `reasoning` / `input` / `ctx` / `maxTokens` / `thinkingLevelMap` from the default model config).
+Press `Enter` to write the result, `Esc` to cancel. On save, the final `models.json` is the union of (checked existing) + (checked new); remote new is preferred over local (so you pick up the fresh `reasoning` / `input` / `ctx` / `maxTokens` / `thinkingLevelMap`).
+
+**Newly added models' fields come from `~/.pi/agent/provider-manager.json`'s `defaultModel` block** (not the code default) — this is the `loadDefaultModelConfig()` behavior. Edit that file before sync to customise the model template.
+
+**proxy field**: a provider's edit form accepts a `proxy` URL (e.g. `http://127.0.0.1:7890`). On sync it's set as `HTTPS_PROXY` / `HTTP_PROXY` env vars and restored after the request. Other concurrent fetches in the same process will see the same proxy while it is set (env is process-global; sync runs at most one fetch at a time).
+
+**apiKey character constraint**: sync rejects apiKeys with any character whose code > 255 (`•`, CJK, emoji, etc., typical from copy-paste). The error is actionable: `apiKey contains non-Latin-1 character at position 7 (U+2022). Re-enter the key in the provider form.`
+
+**Noise filter**: embedding / tts / image-gen models are filtered by default (`embed*`, `tts`, `whisper`, `dall-e`, `clip`, `moderation`, `image-*`).
 
 ---
 
@@ -218,7 +212,7 @@ cp ~/.pi/agent/models.json.bak ~/.pi/agent/models.json
 
 ## Troubleshooting
 
-**`pi install` fails with `E404` or "no such package".** GitHub Packages isn't in your npm registry. Add it to `~/.npmrc` (see [Install](#install)) or use the git-clone fallback.
+**`pi install` fails with `E404` or "no such package".** The npm registry doesn't have this package. First run `npm view @fanchaozz/provider-manager` to confirm the publish succeeded; if it has, check `npm config get registry` is not `npm.pkg.github.com`.
 
 **Dashboard opens but is empty.** Your `models.json` has no custom providers. The extension only manages `models.json` — built-in pi providers (anthropic / openai / google / …) are not shown. Use pi's built-in `/model` for those.
 

package/commands.ts

@@ -11,7 +11,6 @@ import { openDashboard } from "./ui.ts";
 import {
 	addProviderFlow,
 	deleteProviderFlow,
-	addModelFlow,
 	restoreFromBackupFlow,
 	syncFlow,
 } from "./forms.ts";
@@ -58,17 +57,6 @@ export function registerCommands(pi: ExtensionAPI): void {
 					await deleteProviderFlow(ctx, id, () => undefined);
 					return;
 				}
-				case "model": {
-					const tokens = rest.split(/\s+/);
-					const pid = tokens[0];
-					if (tokens[1] === "add") {
-						if (!pid) { ctx.ui.notify("用法: /providers model <pid> add", "warning"); return; }
-						await addModelFlow(ctx, pid, () => undefined);
-					} else {
-						ctx.ui.notify("用法: /providers model <pid> add", "warning");
-					}
-					return;
-				}
 				case "reset": {
 					await restoreFromBackupFlow(ctx, () => undefined);
 					return;
@@ -219,13 +207,13 @@ function cmdHelp(ctx: ExtensionCommandContext): void {
 		"  /providers ls [filter]      List providers and their models",
 		"  /providers add <id>         Add a new provider (TUI: open dashboard, press n)",
 		"  /providers remove <id>      Remove a provider (with confirm)",
-		"  /providers model <pid> add  Add a model to a provider (TUI form)",
 		"  /providers sync [provider-id]  Pick a provider (or pass id), fetch remote models, multi-select, write back. TUI: y on selected provider.",
 		"  /providers test <provider>/<model>  Test model (auth + reachable + 1-shot generation). TUI: t on selected model.",
 		"  /providers test-all [provider]      Batch test all models of a provider (concurrency 3). TUI: T on selected provider.",
 		"  /providers reset            Restore models.json.bak (with confirm)",
 		"  /providers help             This help",
 		"",
+		"Models can only be added/removed via sync (y on a provider).",
 		"Switching models is NOT done by this extension — use Ctrl+L or /model.",
 	];
 	const out = lines.join("\n");

package/components.ts

@@ -317,7 +317,13 @@ export class FormEditor<T extends Record<string, unknown>> {
 			if (f.validate) { const err = f.validate(raw); if (err) { this.error = `${f.label}: ${err}`; return { ok: false }; } }
 		} else {  // text, secret
 			if (f.validate) { const err = f.validate(raw); if (err) { this.error = `${f.label}: ${err}`; return { ok: false }; } }
-			(this.values as any)[f.key] = raw;
+			// secret: 避免覆写原值。draft 是 masked display ("••••Xn")，如果用户没改（draftIsOriginal=true），
+			// 切 field / Enter 退出 edit 都会调 commitDraft，不跳这会写回 masked 字符串覆盖真 key。
+			if (f.type === "secret" && this.draftIsOriginal) {
+				// no-op，保持 values[f.key] 原值
+			} else {
+				(this.values as any)[f.key] = raw;
+			}
 		}
 		this.error = null;
 		return { ok: true };
@@ -364,11 +370,14 @@ export class FormEditor<T extends Record<string, unknown>> {
 		const f0 = this.fields[this.cursor];
 		const isNonInput = f0?.type === "select" || f0?.type === "levelmap" || f0?.type === "multiselect";
 		const isTypeable = f0 && (f0.type === "text" || f0.type === "secret" || f0.type === "number" || f0.type === "json");
+		const isReadonly = f0?.type === "readonly";
+
+		// 统一模型：所有字段都遵 view / edit 两态。
+		//   view（editing=false，默认）：只响应 Enter（进 edit）、↑↓/j/k（切字段）、s（保存）、Esc/q（取消）
+		//   edit（editing=true）：可修改（typeable 输字符 / non-typeable 按 Space/↑↓）、Enter（提交+退出）、Esc（退出）、↑↓（提交+切字段）
 
-		// Esc / q → 取消整个 form（仅当不在 typeable 字段里输入字母 q/q）
-		// 在 text/secret/number/json 字段里输入 q 应该被当作字符（apiKey 含 q 不会被取消）
-		if (matchesKey(data, "escape") || (data === "q" && !isTypeable)) {
-			// edit 模式下 Esc = 退出 edit 模式（commit 当前值）
+		// 1. Esc / q → edit 中退出（commit）；view 模式取消整个 form
+		if (matchesKey(data, "escape") || data === "q") {
 			if (this.editing) {
 				this.commitDraft();
 				this.editing = false;
@@ -379,45 +388,66 @@ export class FormEditor<T extends Record<string, unknown>> {
 			return;
 		}
 
-		// s → 保存整个 form（仅当不在 typeable 字段里输入字母 s）
-		// 在 text/secret/number/json 字段里输入 s 应该被当作字符（apiKey 含 s 不会被保存）
-		if (data === "s" && !isTypeable) {
+		// 2. s → 保存整个 form（仅在 view 模式；edit 模式下 s 是字符 / no-op）
+		if (data === "s" && !this.editing) {
 			const result = this.commitDraft();
 			if (!result.ok) { this.invalidate(); return; }
 			this.onSave(this.values);
 			return;
 		}
 
-		// e → 非输入字段进入 edit 模式（保持整体风格一致：单键操作）
-		if ((data === "e" || data === "E") && isNonInput && !this.editing) {
-			this.editing = true;
-			this.invalidate();
-			return;
-		}
-		// Enter 行为
-		//   edit 模式下 → 退出 edit 模式（commit 当前值）
-		//   输入字段 → 提交 + 移动到下一字段
-		//   其他（readonly）→ 提交整个 form 并保存
+		// 3. Enter → toggle edit（readonly 不响应）
+		//   view: 进 edit（所有 typeable / non-typeable）
+		//   edit: commit + 退出 edit（不走下一字段，留在原字段；用户用 ↑↓ 切）
 		if (matchesKey(data, "enter") || data === "\r" || data === "\n") {
-			if (this.editing && isNonInput) {
+			if (isReadonly) return;
+			if (this.editing) {
 				this.commitDraft();
 				this.editing = false;
 				this.invalidate();
 				return;
 			}
-			if (isTypeable) {
-				// 输入字段：commit draft + 移动到下一字段
-				const result = this.commitDraft();
-				if (!result.ok) { this.invalidate(); return; }
-				this.move(1);
+			// 进 edit。secret field：draft = 原值（不是 masked 显示），用户可看/可改真 key；
+			// commitDraft 会配合 draftIsOriginal 避免覆写未改的原值。
+			if (f0?.type === "secret") {
+				const orig = (this.values as any)[f0.key];
+				this.draft = (orig === undefined || orig === null) ? "" : String(orig);
+				this.draftIsOriginal = true;
+			}
+			this.editing = true;
+			this.invalidate();
+			return;
+		}
+
+		// 4. ↑↓：
+		//   view / edit + typeable：切字段（edit 模式下 commit + 退 edit）
+		//   edit + non-typeable：在 step 7 处理（options 内 nav）
+		if (matchesKey(data, "down") || matchesKey(data, "up")) {
+			if (!(this.editing && isNonInput)) {
+				this.commitDraft();
+				this.move(matchesKey(data, "up") ? -1 : 1);
 				this.editing = false;
 				return;
 			}
-			// readonly 字段：Enter 什么都不做（用 s 保存）
+		}
+
+		// 5. j/k：
+		//   view：切字段
+		//   edit + typeable：字符（下面 printable 处理）
+		//   edit + non-typeable：options 内 nav（在 step 7 处理）
+		if ((data === "j" || data === "k") && !this.editing) {
+			this.move(data === "j" ? 1 : -1);
 			return;
 		}
 
-		// edit 模式下：↑↓/j/k 在 options 内移动，Space pick
+		// 6. Space：view + non-typeable 快捷进 edit（与 Enter 等价）
+		if (data === " " && isNonInput && !this.editing) {
+			this.editing = true;
+			this.invalidate();
+			return;
+		}
+
+		// 7. edit + non-typeable：↑↓/j/k 在 options 内移动，Space pick
 		if (this.editing && isNonInput) {
 			if (f0!.type === "levelmap") {
 				if (matchesKey(data, "down") || data === "j") {
@@ -454,7 +484,7 @@ export class FormEditor<T extends Record<string, unknown>> {
 				}
 				return;  // edit 模式下其他键不响应
 			}
-			// multiselect 字段：↑↓ 选 option，Space toggle（在值里加/去）
+			// multiselect 字段：↑↓/j/k 选 option，Space toggle（在值里加/去）
 			if (f0!.type === "multiselect" && f0!.options) {
 				const opts = f0!.options;
 				if (matchesKey(data, "down") || data === "j") {
@@ -481,38 +511,24 @@ export class FormEditor<T extends Record<string, unknown>> {
 			}
 		}
 
-		// nav 模式下：↑↓ 切字段（所有字段），j/k 切字段（仅 non-input；text 字段 j/k 是普通字符）
-		if (matchesKey(data, "down") || (isNonInput && data === "j")) {
-			this.commitDraft();
-			this.move(1);
-			this.editing = false;  // 切到新字段退出 edit
-			return;
-		}
-		if (matchesKey(data, "up") || (isNonInput && data === "k")) {
-			this.commitDraft();
-			this.move(-1);
-			this.editing = false;
-			return;
-		}
-
-		// readonly 字段：忽略
-		if (f0?.type === "readonly") return;
+		// 8. readonly：后续输入不响应
+		if (isReadonly) return;
 
-		// nav 模式下 Space 在非输入字段：进入 edit 模式（不动值）
-		if (data === " " && isNonInput && !this.editing) {
-			this.editing = true;
-			this.invalidate();
-			return;
-		}
+		// 9. view 模式：不接受任何字符输入（需先 Enter 进 edit）
+		if (!this.editing) return;
 
-		// 文本类输入处理
+		// 10. Backspace：仅在 edit + typeable 删除 draft
 		if (matchesKey(data, "backspace")) {
+			if (!isTypeable) return;
 			if (this.draft.length > 0) this.draft = this.draft.slice(0, -1);
 			this.draftIsOriginal = false;
 			this.invalidate();
 			return;
 		}
+
+		// 11. 可打印字符：仅在 edit + typeable 追加 draft
 		if (data.length === 1 && data.charCodeAt(0) >= 32 && data.charCodeAt(0) < 127) {
+			if (!isTypeable) return;
 			// number 字段：第一个数字替换（避免 100 + "2" = 1002），后续 append
 			if (f0?.type === "number" && /^\d$/.test(data) && this.draftIsOriginal) {
 				this.draft = data;
@@ -671,8 +687,9 @@ export class FormEditor<T extends Record<string, unknown>> {
 				valueStr = isActive ? raw : th.fg("text", raw);
 			}
 			const prefix = isActive ? th.fg("accent", "▸ ") : "  ";
+			const editMarker = isActive && this.editing ? th.fg("accent", " [● edit]") : "";
 			const hint = f.hint ? "  " + th.fg("muted", f.hint) : "";
-			const line = prefix + labelStr + valueStr + hint;
+			const line = prefix + labelStr + valueStr + editMarker + hint;
 			lines.push(truncateForRender(line, width));
 		}
 
@@ -680,12 +697,13 @@ export class FormEditor<T extends Record<string, unknown>> {
 		lines.push(th.fg("borderMuted", "─".repeat(width)));
 		const f = this.fields[this.cursor];
 		const hints: string[] = ["↑↓ field"];
-		if (f?.type === "multiselect") hints.push(this.editing ? "↑↓ option · Space toggle · Enter commit" : "e edit · Space toggle");
-		else if (f?.type === "select") hints.push(this.editing ? "↑↓ option · Space pick · Enter commit" : "e edit · Space pick");
-		else if (f?.type === "levelmap") hints.push(this.editing ? "↑↓ level · Space toggle · Enter commit" : "e edit · Space toggle");
-		else hints.push("type to edit");
-		hints.push("Backspace del");
-		hints.push("s save");
+		if (f?.type === "multiselect") hints.push(this.editing ? "↑↓ option · Space toggle · Enter commit" : "Enter edit · Space toggle");
+		else if (f?.type === "select") hints.push(this.editing ? "↑↓ option · Space pick · Enter commit" : "Enter edit · Space pick");
+		else if (f?.type === "levelmap") hints.push(this.editing ? "↑↓ level · Space toggle · Enter commit" : "Enter edit · Space toggle");
+		else if (f?.type === "readonly") hints.push("readonly");
+		else hints.push(this.editing ? "type to edit" : "Enter edit · type");
+		hints.push(this.editing && f && (f.type === "text" || f.type === "secret" || f.type === "number" || f.type === "json") ? "Backspace del" : "Backspace");
+		hints.push(this.editing ? "Enter commit" : "s save");
 		hints.push("Esc cancel");
 		lines.push(th.fg("dim", " " + hints.join(" · ")));