docs(api): api-client → v0.53（阶段 5 全部契约）+ api-reference 同步 + .env.example 补 9 键

- 新端点 GET /admin/llm/catalog 全契约（200/gzip/503 catalog_unavailable/快照副作用/不进热路径/审计 llm.catalog）
- models.json 组级三键：reasoning.kind（形状）+ personaModels/personaProviders（角色级模型/协议路由），
  含「缺省=保留、给出=整块/整表替换」语义、Group.Validate 的 400 口径、回落与 WARN 规则
- GET /admin/llm 新增恒下发的 reasoning 与两个取值域（reasoningKinds/personaProviderOptions）
- 语义修正（此前文档写反）：multimodal = 主模型能否收图；LLM_VISION_MODEL/LLM_OCR_MODEL 只配视觉/OCR 工具
- 新工具 image-crop（x/y/width/height、50MiB/16MP/8MiB 上限、越界报错不 clamp、策略默认 owner-only）
- 推理开关按形状下发：替换 v0.41「Qwen 只 WARN 不发」；effort 非法值改为丢弃+WARN（不降档）、effort:none 显式关思考
- .env.example 新增 9 键（LLM_REASONING_KIND / LLM_OCR_MODEL / LLM_LOCAL_* / CAPACITY_L3_*），默认均为保守值
- 权限矩阵计数按 routes.go 校正 56→59（owner/admin 只读档 9→10，含 /admin/llm/catalog）

.env.example

@@ -50,10 +50,20 @@ LLM_FALLBACK_MODEL=gpt-4o-mini
 # 且该模型组未在 models.json 设 maxTokens、请求也未显式给 MaxTokens 时生效；
 # 0 = 关闭该兜底（改用适配器默认，如 anthropic 8192）。每模型组预算见 models.json 的 maxTokens。
 LLM_FALLBACK_MAX_TOKENS=8192
+# 推理开关的【提供商形状】声明（裁决 03.4.2 / 08.4.1）：auto（默认，= 留空）/ deepseek /
+# openai / vllm / dashscope。形状决定把思考开关下发改成哪个字段（如 vllm =
+# chat_template_kwargs.enable_thinking、dashscope = 顶层 enable_thinking），必须按端点真实形状
+# 声明——发错形状会被上游拒。留空/auto = 按模型名与 base URL 推断厂商，形状有歧义时一个字段都不发。
+# ⚠️ 本键只作用于 .env 合成的模型组：存在有效 models.json 时，以该组的 reasoning.kind 为准
+#    （面板可编辑，见「LLM 模型」页）。
+LLM_REASONING_KIND=
 
-# ---- LLM 视觉模型（多模态路由：含图片的请求路由到此模型） ----
-# 不配置则图片路由回主模型；仅当启用多模态能力时设置。
+# ---- LLM 视觉模型（视觉/OCR 工具用的模型；与「主模型能否收图」无关） ----
+# 语义（v0.53 修正）：主模型自己能不能收图，看 models.json 生效组的 multimodal 字段（面板可勾选），
+# 不是看这里；本节的模型【只供 vision / ocr 工具】调用。都不配置时工具回落用主模型（LLM_MODEL）。
 # LLM_VISION_MODEL=gpt-4o-mini
+# OCR 工具单独用另一个模型（可选）：留空 = 复用 LLM_VISION_MODEL。
+# LLM_OCR_MODEL=qwen-vl-ocr
 
 # Provider = anthropic：Anthropic Messages /v1/messages（tool_use.input 为结构化对象，工具循环更稳）
 # ANTHROPIC_BASE_URL=https://api.anthropic.com
@@ -64,6 +74,18 @@ LLM_FALLBACK_MAX_TOKENS=8192
 #    （deepseek-flash / deepseek-v4-pro）：不认识的名称（如 claude-*）会被服务端【静默映射成 deepseek-flash】，
 #    配置错了不会报错。旧的 deepseek-chat / deepseek-reasoner 已于 2026-07-24 停用。
 
+# ---- LLM 本地第三级（降级链末端；默认关，裁决 03.4.3） ----
+# 降级链为「主 → 备 → 本地」；本地这一级默认关闭（当前设备跑本地模型困难），链保持两级。
+# 开启需要三个条件同时满足：LLM_LOCAL_ENABLED=true + LLM_LOCAL_BASE_URL + LLM_LOCAL_MODEL；
+# 只开开关不配端点/模型会被记 WARN 并跳过（不会半配成一个只会失败的链尾步）。
+LLM_LOCAL_ENABLED=false
+# 本地端点协议：openai（llama.cpp / ollama / vLLM 兼容）或 anthropic；留空 = openai。
+# LLM_LOCAL_PROVIDER=openai
+# LLM_LOCAL_BASE_URL=http://127.0.0.1:8080/v1
+# 本地服务通常不需要 key；留空即可。
+# LLM_LOCAL_API_KEY=
+# LLM_LOCAL_MODEL=qwen3-4b-instruct
+
 # ---- 记忆嵌入（可选，真语义） ----
 # 不配置时使用内置 n-gram / FTS 向量（dim=256）。配置后必须真实走语义路径。
 # EMBEDDING_API_URL 是【完整 /embeddings 端点】（不是 base）——例：Ollama / llama.cpp = http://localhost:11434/v1/embeddings
@@ -120,6 +142,15 @@ THINK_KIND_WINDOW_SEC=7200
 QUIET_START_HOUR=23
 QUIET_END_HOUR=7
 
+# ---- 唤醒式能力渐进（capacity 意图判定，design/14 §2.2） ----
+# L3 = 模型辅助的意图分类：仅当 L1 启发式与 L2 上下文仍拿不准时介入一次轻量模型调用。
+# 默认关闭（纯启发式够日常，且该层要多花一次模型调用）；关闭时该层从不运行，
+# L1/L2/L4 的行为与接线前逐字节一致。
+CAPACITY_L3_ENABLED=false
+# L3 判定结果的缓存 TTL（Go duration，如 5m）：同一段回合文本在此窗口内复用判定，避免每轮都问模型；
+# 留空 = 5m；0 或解析不出 = 不缓存。
+CAPACITY_L3_CACHE_TTL=5m
+
 # ---- 子代理（orchestration，design/05 §7） ----
 # 单个子代理整次运行的时限（秒）。默认 600 = 10 分钟（裁决 02.4.4：agent_timeout
 # 可配置）；模型派发时可用 subagent_spawn 的 timeout_seconds 参数按调用覆盖。