feat(admin): 面板「重置为 env 默认」动作（materialize 的反方向）+ 契约 v0.62

- 语义：只把 .env **确实声明过**的键覆盖回 env 值；env 未声明的键（fallback/multimodal/maxTokens/reasoning/personaModels）原样保留；**组集合不增减**（不复活被面板删的组、不删面板新增的组）；无键可改时不写盘。成功即热重载 LLM 栈。返回 {reset:[{group,keys}], skipped:[{group,reason}], path}，**只回键名、不回显凭据值**。

- 护栏：必须 confirm:true（缺失/false/非法 body ⇒ 400，且**先于任何读写**）；**owner-only**（与同页 POST /admin/llm、/admin/llm/test 同门 —— 这是破坏性写，门不比同族更宽）；审计动作 llm.resetFromEnv（camelCase，全仓多词动作的既有约定）。失败路径明确报错（env_defaults_unreadable / models_unreadable / llm_unavailable），不假成功。

- 组合根注入 Deps.EnvPath（网关不 fopen .env）：请求时按既有解析入口重读，语义 =「退回 .env 现在声明的默认值」；.env 层里的 provider 是同义反复，不计入「env 为该组声明了什么」的判定（有专门用例）。

- 前端：LLM 页「重置为 env 默认」卡片（中文二次确认 → 提交 → 按 reset/skipped 渲染 → 成功后重拉配置），标签 owner 专属（与 System.tsx 同款）。

- 契约 v0.62：api-client（权限矩阵改回 12+10+38=60、端点表 9b、重置契约小节、写操作契约、changelog、banner）与 api-reference（端点表 #70、§5.13a 详情含 curl、§8.2/§8.3/§8.4）同步；字段名三方逐字对齐。

- 主会话独立验收：隔离 worktree（R1 的 19 文件）build/vet 绿、gateway+config 三包绿、R1 用例 10 PASS、reset_from_env 残留 0；**变异亲自复现**（去掉 confirm 校验 ⇒ RequiresConfirm 红：status = 200, want 400，且响应体显示面板配置真的被改）。

- 子代理自报并已处理：测试文件触 500 行上限 ⇒ 拆成语义侧 + 护栏侧两份；门改回 owner-only 后前端标签会误导 admin ⇒ 改「owner 专属」并重建 bundle。任务书本身仍是旧口径（owner|admin / snake_case）—— 已由主会话登记修正说明，避免压缩后有人按任务书回退。

- 未做（诚实边界）：不支持按组重置；不纳入 channels.json/plugins.json；不自动重启（contextWindow 的预算推导仍只在启动时算一次）。新端点需下一次 build+restart 才在 :10942 生效。

Docs/api-reference.md

@@ -134,6 +134,7 @@
 | 39 | DELETE | `/api/v1/admin/automations/{id}` | **owner** | 200 | 删除规则 | M8 |
 | 40 | POST | `/api/v1/admin/llm` | **owner** | 201 | 保存 LLM provider 组（落盘 + 热更新） | M8/M15 |
 | 41 | POST | `/api/v1/admin/llm/test` | **owner** | 200 | 真实模型调用测试 | M8/M15 |
+| 70 | POST | `/api/v1/admin/llm/reset-from-env` | **owner** | 200/400/500 | **重置为 env 默认（v0.62）**：把面板里 `.env` 声明过的键覆盖回 env 值（组集合不增减、env 未声明的键原样保留、无键可改时不写盘），body `{confirm:true}` 缺则 `400`，只回键名不回显凭据；失败 `env_defaults_unreadable`/`models_unreadable`/`llm_persist_failed`/`llm_reload_failed`/`llm_unavailable`（见 §5.13a） | 后 M12 |
 | 42 | POST | `/api/v1/admin/channels/open` | **owner** | 200 | 连接渠道 | M8 |
 | 43 | POST | `/api/v1/admin/channels/close` | **owner** | 200 | 断开渠道 | M8 |
 | 44 | POST | `/api/v1/admin/channels/test` | **owner** | 200 | 结构性身份识别测试 | M8/M16 |
@@ -158,7 +159,7 @@
 
 **另**：外部 webhook 回调（如 `webhook` 渠道的 HMAC 回调）由 composition root 通过 `Deps.Webhooks` 动态挂载，**不走网关鉴权**（handler 自校验签名/授权）；路径由调用方决定，不在上表枚举。
 
-**补登记说明（2026-10-04）**：上表中 `#62`–`#68` 是本次按 `routes.go` 逐条核对后新增的行（`plugins/installed` / `observability/logs` / `notifications` / `llm/catalog` / `owner-profile` GET+PUT / `automations/reminders`），插在各自的鉴权分档里、**既有编号一律未动**。§1.1 的 `#3`/`#4`（`auth/refresh`、`auth/logout`）与 §1.2 的 `#14`–`#18`（`upload`、`files/{name}`、三支 `audio/*`）同理。**v0.59 再补两行**：§1.2 的 `#19`/`#20`（`POST /api/v1/documents`、`GET /api/v1/documents/{name}`，均按 `routes.go` 的 `writeAuth` 注册核对）——同样取本表下一个可用号、不动既有编号。**v0.60 再补一行**：`#69` GET `/api/v1/admin/system/storage`（owner-only 只读，按 `routes.go` 的 `ownerAuth` 注册核对；**无审计动作**——它是查询不是动作），同样取下一个可用号、既有编号未动。**仍未登记的是 WS 事件帧**（见 §6.4 与本文档开头的历史包袱说明）。
+**补登记说明（2026-10-04）**：上表中 `#62`–`#68` 是本次按 `routes.go` 逐条核对后新增的行（`plugins/installed` / `observability/logs` / `notifications` / `llm/catalog` / `owner-profile` GET+PUT / `automations/reminders`），插在各自的鉴权分档里、**既有编号一律未动**。§1.1 的 `#3`/`#4`（`auth/refresh`、`auth/logout`）与 §1.2 的 `#14`–`#18`（`upload`、`files/{name}`、三支 `audio/*`）同理。**v0.59 再补两行**：§1.2 的 `#19`/`#20`（`POST /api/v1/documents`、`GET /api/v1/documents/{name}`，均按 `routes.go` 的 `writeAuth` 注册核对）——同样取本表下一个可用号、不动既有编号。**v0.60 再补一行**：`#69` GET `/api/v1/admin/system/storage`（owner-only 只读，按 `routes.go` 的 `ownerAuth` 注册核对；**无审计动作**——它是查询不是动作），同样取下一个可用号、既有编号未动。**v0.62 再补一行**：`#70` POST `/api/v1/admin/llm/reset-from-env`（**owner-only 写**，按 `routes.go` 的 `ownerAuth` 注册核对，见 §5.13a），同样取下一个可用号、既有编号未动。**仍未登记的是 WS 事件帧**（见 §6.4 与本文档开头的历史包袱说明）。
 
 **WS**：`GET /ws/chat`（握手，JWT，见 §6）。
 
@@ -750,7 +751,7 @@ curl -s http://<host>:8080/api/v1/admin/sessions/web:0123.../export -H "Authoriz
 
 ## 5. 管理后台 · 写端点（`owner`，全程审计）
 
-> 以下端点**鉴权 = `Authorize(owner)`**（仅主人）。每个写操作都会调用 `auditClaims(r, "<action>", "ok"|"error")` 记录 who/what/when/result（落 `audit_logs` + 网关日志）。**敏感值（token/密钥/新 JWT 密钥/DB 路径）不在响应/日志回显**。
+> 以下端点**鉴权 = `Authorize(owner)`**（仅主人）。每个写操作都会调用 `auditClaims(r, "<action>", "ok"|"error")` 记录 who/what/when/result（落 `audit_logs` + 网关日志）。**敏感值（token/密钥/新 JWT 密钥/DB 路径）不在响应/日志回显**。**动作名约定**：多词动作用 camelCase（`llm.addProvider` / `llm.resetFromEnv` / `persona.update` / `memory.search` …），与 §8.3 的清单逐字一致。
 
 ### 5.1 POST /api/v1/admin/plugins/policy
 - **Body**（`policyRequest`）：`{"name":"<能力名>","allowInGroup":bool,"allowInStranger":bool}`。
@@ -890,6 +891,28 @@ curl -s -X POST http://<host>:8080/api/v1/admin/llm \
   -d '{"provider":"openai","baseUrl":"https://api.openai.com/v1","apiKey":"sk-...","model":"gpt-4o","multimodal":true}'
 ```
 
+### 5.13a POST /api/v1/admin/llm/reset-from-env（v0.62，「重置为 env 默认」）
+- **鉴权**：**`owner` 专属**（与同组 `POST /admin/llm`、`POST /admin/llm/test` 同门；`admin` 与 `viewer` 均 `403`）——它是破坏性写（覆盖面板对若干键的修改），**门不比同族写端点更宽**。**审计**：`llm.resetFromEnv`（成功 `ok`、被拒/失败 `error`）。
+- **Body**（`llmResetRequest`）：`{"confirm":true}` —— **必须显式为 true**。缺失 / `false` / 非法 body 一律 `400 {"error":{"code":"bad_request"}}`，且**一个字节都不动**（本动作用 env 值覆盖面板修改，是破坏性操作，缺护栏的默认必须是「不执行」）。
+- **语义**：把面板（`models.json`）里 **`.env` 默认层确实声明过（非空值）** 的键覆盖回 env 值。它与启动期 materialize 的补齐**方向相反、键表同源**（`runtimeconfig` 的 `groupFillSpecs` / `envLayer`），因此逐条是：
+  - **只动** `provider` / `baseUrl` / `apiKey` / `model` / `contextWindow`（缺省协议族按**组自己的 `provider`** 选：`.env` 同时配了扁平块与 `ANTHROPIC_*` 时两族各取自己的值；`contextWindow` 只认正数）。
+  - **env 未声明的键一律保留面板值**（`fallback` / `multimodal` / `maxTokens` / `reasoning` / `personaModels` 在 `.env` 里没有出处 ⇒ 永不被本动作改动）。
+  - **组集合不增减**（不复活被面板删掉的组、不删面板新增的组，**顺序也不动**）。
+  - **面板值已与 env 一致的键不算「改回」**（`provider` 恒属这种情形），不出现在 `reset` 里。
+  - **无键可改时一个字节都不写**（幂等；重复调用第二次会返回 `reset:[]` + 每组一条「已一致」的 `skipped`）。
+  - 真的改了盘就**热重载**运行中的 LLM 栈（无需重启）；但 `contextWindow` 的**上下文预算推导**仍只在进程启动时算一次（与 `POST /admin/llm` 同口径，重启后生效）。
+- **对照基准**：**请求时刻按既有 config 解析入口读到的 `.env` 默认层**（`config.LoadLLMDefaults`，优先级与启动期 `config.Load` 逐字一致：进程环境 > `.env` > 标签默认）；`.env` 路径由组合根经 `Deps.EnvPath` 注入（与 `main.go` 的 `config.MustLoad(envPath)` 同一条）——**网关自己绝不 fopen `.env`**。
+- **响应**：`200 {"data":{"reset":[{"group":"<组 id>","keys":["baseUrl","apiKey",…]}],"skipped":[{"group":"<组 id>","reason":"<中文原因>"}],"path":"<models.json 路径>"}}`。`keys` **只有键名**（顺序 = 补齐表顺序），**凭据值绝不回显**；`reset` / `skipped` 恒为数组（无记录时是 `[]` 而非 `null`）；`reason` 是两种之一：`` "面板值已与 `.env` 默认一致，无需重置" `` / `` "`.env` 未声明该组的默认键（面板值原样保留）" ``。
+- **错误**（都**不改文件**且带审计 `error`）：`.env` 源不可读 → `500 env_defaults_unreadable`；面板配置不存在/不可解析 → `500 models_unreadable`；写盘失败 → `500 llm_persist_failed`；已写盘但热重载失败 → `500 llm_reload_failed`（说明文件已改、未生效）；LLM 栈未注入 → `500 llm_unavailable`。
+- **面板**：LLM 页的「重置为 env 默认」卡片（`frontend/web/src/admin/modules/llm/LlmResetFromEnv.tsx`）——先展开中文二次确认文案，确认后才带 `confirm:true` 提交。完整契约见 `api-client.md` §2「重置为 env 默认契约（v0.62）」。curl：
+
+```bash
+curl -s -X POST http://<host>:8080/api/v1/admin/llm/reset-from-env \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'X-API-Version: 1' \
+  -d '{"confirm":true}'
+# => {"data":{"reset":[{"group":"deepseek","keys":["baseUrl","apiKey","model"]}],"skipped":[],"path":".../models.json"}}
+```
+
 ### 5.14 POST /api/v1/admin/llm/test
 - **Body**（`llmTestRequest`）：`{"provider?","baseUrl","model","apiKey?","prompt?"}`。`model`+`baseUrl` 必填；`provider` 空默认 `openai`；`prompt` 空用探针 `"Reply with the single word: OK"`。
 - **响应**：`200 {"data":{"ok":true,"provider":"openai","model":"gpt-4o","reply":"<模型回复>","tokens":<int>}}`——**真实模型调用**（超时 30s）。
@@ -1413,7 +1436,8 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
 - `RAG` 未注入：`GET /admin/rag` 返回空文档列表；`POST /admin/rag`、`/admin/rag/delete` 回 `501`。
 - `Runner(Loop)` 未注入：`/chat` 回 `500 chat_unavailable`；WS `chat` 直接广播 `stream_end{stopReason:"idle"}`。
 - `Channels` 未注入：`/admin/channels/config` 回 `500 channels_unavailable`。
-- `LLM` 未注入：`/admin/llm` 按 `.env` 合成单组；`POST /admin/llm` 回 `500 llm_unavailable`。
+- `LLM` 未注入：`/admin/llm` 按 `.env` 合成单组；`POST /admin/llm` 回 `500 llm_unavailable`；`POST /admin/llm/reset-from-env`（v0.62）同样回 `500 llm_unavailable`（不假装重置成功）。
+- `Deps.EnvPath`（v0.62）：组合根注入的启动用 `.env` 路径，**只**供 `POST /admin/llm/reset-from-env` 按既有解析入口重读 env 默认层（网关不 fopen `.env`）；为空 = 只看进程环境变量（生产 systemd/env_file 形态）。`.env` 读不出（例如路径是个目录）→ `500 env_defaults_unreadable`，**不改任何文件**。
 - `Voice` 未注入：WS `voice_input` 回 `error {message:"voice unavailable"}`。
 - `Scheduler(auditor)` 未注入：WS `subagent_ask` 回 `error {message:"subagent audit unavailable"}`。
 - `Tasks` 未注入：WS `task_output_query` 回 `error {message:"task output unavailable"}`。
@@ -1422,12 +1446,12 @@ TOKEN=$(curl -s -X POST http://<host>:8080/api/v1/auth/login \
 
 ### 8.3 审计动作清单（`what` 字段，落 `audit_logs`）
 
-`policy.set` / `persona.create` / `persona.update` / `user.create` / `apikey.issue` / `apikey.revoke` / `iot.control` / `iot.scenario` / `iot.rule` / `automation.create` / `automation.run` / `automation.delete` / `llm.addProvider` / `llm.test` / `channel.open` / `channel.close` / `channel.identity-test` / `channel.weixin.login.qr` / `channel.weixin.login.status` / `channel.weixin.login.persist` / `channel.platform.view` / `channel.friends` / `channel.friend.handle` / `channel.message.test` / `channel.save` / `channel.delete` / `plugin.install` / `plugin.uninstall` / `memory.add` / `memory.search` / `rag.index` / `rag.query` / `rag.delete` / `session.export` / `system.revoke_keys` / `system.rotate_jwt` / `system.backup` / `system.restore`。
+`policy.set` / `persona.create` / `persona.update` / `user.create` / `apikey.issue` / `apikey.revoke` / `iot.control` / `iot.scenario` / `iot.rule` / `automation.create` / `automation.run` / `automation.delete` / `llm.addProvider` / `llm.test` / `llm.resetFromEnv`（v0.62）/ `channel.open` / `channel.close` / `channel.identity-test` / `channel.weixin.login.qr` / `channel.weixin.login.status` / `channel.weixin.login.persist` / `channel.platform.view` / `channel.friends` / `channel.friend.handle` / `channel.message.test` / `channel.save` / `channel.delete` / `plugin.install` / `plugin.uninstall` / `memory.add` / `memory.search` / `rag.index` / `rag.query` / `rag.delete` / `session.export` / `system.revoke_keys` / `system.rotate_jwt` / `system.backup` / `system.restore`。
 （`what` 后缀 `_failed/_persist_failed/_reload_failed` 等计入 `error` 分支。）
 
 ### 8.4 里程碑与未实现集合（诚实标注）
 
-- **已真实实现**：登录/健康检查/聊天（同步+流式）/会话（列表/新建/删除/消息分页）/人格/**文档存储与摄取（v0.59：`POST`/`GET /api/v1/documents` + `chat.documents` + `documents` DTO + `document-read` 工具；**v0.61：PDF 文本层抽取**，白名单 23 项含 `.pdf`、成对裁决、扫描件诚实拒绝）**/**语音回合进编排（v0.59：落库 / 流式 / 跨端 / 忙时排队，`voice_output` 归属键）**/管理读（personas/sessions/memories/plugins/channels/iot/llm/users/automations/backthink/rag/observability×4：metrics/trace/audit/logs）/管理写（人格/API key/设备控制/自动化/LLM 保存·测试/渠道连接·断开·身份测试/渠道配置·删除/KOOK 面板/微信扫码/记忆添加·检索/插件安装·卸载/RAG 导入·删除/主人档案读写（`GET`/`PUT /api/v1/admin/owner-profile`，v0.51）/系统设置 4 项）。
+- **已真实实现**：登录/健康检查/聊天（同步+流式）/会话（列表/新建/删除/消息分页）/人格/**文档存储与摄取（v0.59：`POST`/`GET /api/v1/documents` + `chat.documents` + `documents` DTO + `document-read` 工具；**v0.61：PDF 文本层抽取**，白名单 23 项含 `.pdf`、成对裁决、扫描件诚实拒绝）**/**语音回合进编排（v0.59：落库 / 流式 / 跨端 / 忙时排队，`voice_output` 归属键）**/管理读（personas/sessions/memories/plugins/channels/iot/llm/users/automations/backthink/rag/observability×4：metrics/trace/audit/logs）/管理写（人格/API key/设备控制/自动化/LLM 保存·测试·**重置为 env 默认（v0.62，owner-only）**/渠道连接·断开·身份测试/渠道配置·删除/KOOK 面板/微信扫码/记忆添加·检索/插件安装·卸载/RAG 导入·删除/主人档案读写（`GET`/`PUT /api/v1/admin/owner-profile`，v0.51）/系统设置 4 项）。
 - **`thinking` 可达性（v0.59 口径，不改行为）**：消息体 `thinking` 字段在**实时帧**（`message_persisted`/`channel_persisted`/`message_edited`）与**握手回放**中**一律剥离**（有意默认）；**实时思维链**走 `thinking.*` 流帧（owner/admin）；**历史思维链**只有 `GET /sessions/{id}/messages`（owner/admin）返回。
 - **仍为后置 M10（返回 `501 not_implemented`，不伪造）**：新增用户（无用户表/登录）、IoT 场景与规则（无模型/存储）、编辑环境变量/重启服务/检查更新、完整会话转录导出（当前导出身份元数据）。**文档侧后置**：配额与引用计数/GC（design/24 S7）、**Office 解析（`.doc`/`.docx`/`.xls`/`.xlsx`/`.ppt`/`.pptx`/`.odt`/`.ods`/`.odp`/`.rtf`，仍诚实拒绝）**、**扫描件/图片型 PDF 的 OCR**（v0.61 已做文本层 PDF，无文本层者如实报 `unreadable`）、IM 侧 `msg.Media` 摄取（`channelbridge` 只取 `msg.Content`）。**已知缺口**：design/24 §6.2 的 `document_unreadable`(400) 无 REST 落点（只有 `document-read` 工具错误形态；客户端在 DTO 里看到的是 `documents[].status = "unreadable"`）。
 - **语义/向量增强**：`memory.search` 的 `semantic` 当前恒为 `false`——**向量索引已由组合根注入**（`cmd/cyrene/wire.go` 的 `memory.WithVectorIndex`），但**索引内当前无向量**（生产无写入），故语义打分返回空，属诚实反映而非伪造；RAG `embedded` 反映部署是否配置向量增强；**配置了增强必须真实走语义/向量路径（红线，非空壳）**。