@mars-sea/dsh-commandcode-provider 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-10-18
+
+### Added
+
+- 问题 #74：新增**单轮输出上限**配置 `maxOutputTokens` 与网页设置页字段（「模型与上下文」分组，紧随自定义上下文长度）。不填（默认）＝沿用既有推导（模型公布或运行时学到的输出上限、网关总上限三者取最小），行为完全不变；填正整数＝与该推导值取最小，永远不会突破模型上限或网关总上限 131 072；填 **`0`＝请求中不发送 `max_tokens` 字段**，把单轮输出规模交回平台自行限制——这是报告者要的「不再被硬切」，因为该字段本身是被动硬限制，单纯调大数值只能把断点往后挪。省略仅对**接受缺省该字段的传输**生效：CLI（`/alpha/generate`）与 OpenAI（`/provider/v1/chat/completions`）；Claude 走的 Anthropic Messages 端点必填该字段（缺失会被上游以 `Invalid input: expected number, received undefined at max_tokens` 直接拒绝），因此那条链路仍按推导值发送，填 `0` 对它无效。宿主显式给定的每次调用预算（如会话标题的 64 词元）同样优先于此设置。`0` 与正整数共用一个数值字段，边界由 Host 与浏览器设置页共用的纯模块 `src/output-budget.ts` 判定；正数取值还会同步压低选择器上宣告的 `defaultMaxTokens`。字段留空＝清除该配置（回到推导默认），而不是写入 0。输入接受 `64K` 简写。设置页的上下文长度与输出预算两个 token 计数字段合并为同一个 `tokenCountField`（简写文法与边界检查只有一份）。
+
+### Fixed
+
+- 问题 #74（第二半）：**7 处裸 `error instanceof Error ? error.message : String(error)` 收进统一的可读错误兜底函数**。抛出的值不是 `Error` 时 `String()` 会退化成 `[object Object]`，信息全丢；0.12.2 只在浏览器侧的 RPC 边界修了这一点，Host 侧的服务端路径（通用 HTTP 用量查询、`/commandcode` 命令、账号卡片用量读取、浏览器登录流程、终端设置页注册失败、网页搜索的请求与凭据解析）仍是裸写法。支撑 `readableErrorText()` 的实现移入 Host 与客户端共用的 `src/readable-error.ts`，Host 侧七个调用点与浏览器侧六个调用点（分布在五个文件）直接导入它（不再保留中间再导出模块），两侧不会再各自演化。
+
+- 问题 #90：**英文界面残留中文文案**。`en` 字典补齐 14 个 `write*` 设置写入提示与 `usagePeriodUnknown` 的英文翻译；`settingsWriteNotice()` 里硬编码的「（原引用：…）」改走本地化（新增 `writeCredentialRefNote` 键，中文输出与改动前逐字一致）。合并前另补齐**同一设置页界面层**漏掉的 9 处硬编码中文——`section.tsx` 的「若登录页面未自动打开，请点击下方链接。」「打开浏览器登录」「重试保存名称」「接受已有名称」「取消开通」「重试清理」，以及账号恢复行里硬编码的全角冒号分隔符；这些文案与 `settingsWriteNotice` 同页，此前在英文界面下仍显示中文。新增 7 个键（`accountAddLinkHint`、`accountAddOpenLink`、`accountAddCancel`、`accountNameSaveRetry`、`accountNameAcceptExisting`、`accountEnrollmentCleanupRetry`、`accountRefSeparator`），联合类型 / 中文 / 英文三处同步，全角冒号在英文侧改为半角加空格。新增**英文侧 CJK 守护测试**：`en` 字典出现任何中文字符即失败；`PANEL_COPY_EN` 只放行 `analytics-copy.ts` 声明的「错误、缺失与读取状态各语言统一中文」既定约定，并断言该约定仍在生效；三组变异测试确认守护会真正失败。`lib/client.js` 与 sourcemap 同步重建。**边界**：账号开通与恢复流程的状态消息此时仍由宿主产出的中文字面量构成，英文界面下那几行仍显示中文，已由下一条修复。
+
+- **英文界面残留中文（账号开通状态消息）**。账号开通的状态消息此前是宿主产出的中文字面量，经 `EnrollmentState.message` 直传页面后原样显示，英文界面下三处状态行（新增账号面板的状态行、待处理恢复记录行、`cleanup-needed` 行）与传输失败提示都仍是中文。现改为**语义键**：`EnrollmentState.message` 换成 `messageKey: EnrollmentMessageKey`，共 22 个键（宿主 15 个、页面控制器 7 个），键表与枚举校验单点放在 `src/enrollment-wire.ts`（`parseEnrollmentState` 拒绝自由文本），中英文案集中进设置页词典、渲染时才按界面语言取，两侧不会再各写一份；「正在创建账号」与「收尾未完成，请重试」这两条本来两侧各有独立文案的状态也就此合并为一处。**为什么不是按 `phase` 渲染**：同一 `phase` 对应多种语义——`naming` 既有「正在保存名称」也有「名称保存失败」，`cleanup-needed` 既有「收尾未完成」也有「清理未完成」，`cancelled` 既有「已取消」也有「已取消并清理」，按阶段渲染无法区分。**验证**：新增 wire 拒绝自由文本/非枚举键的用例，并把原按中文子串断言的三处改为断言语义键；英文侧 CJK 守护测试覆盖新键（变异测试确认把任一 `en` 值改回中文即变红）。**边界**：宿主侧约 20 处 `throw new Error('…')` 的中文不在本次改动内——它们不上屏，客户端在所有失败路径都用自己这一侧的键覆盖；登录流程（`src/login.ts`）的状态消息仍由宿主产出中文，同样未包含。
+
+### Changed
+
+- DSH 兼容矩阵收敛为**单一引擎 `0.2.1-rc.2`**：RC（候选发布版）通道由 `0.2.0-rc.2` 替换为 `0.2.1-rc.2`（2026-10-17 发布），alpha 通道自 `0.2.1-alpha.5` 之后没有新的已验证版本，随之退出支持矩阵。`dsh.compatibility.dshReleases` 只剩一条，`dsh.compatibility.dsh`、`engines.dsh`、15 个对等依赖与 19 个开发依赖的 `@deepseek-ai/dsh-*` 全部为裸版本 `0.2.1-rc.2`；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 由双通道时代的析取收紧为随该引擎配对的正式版范围 `~4.0.5`／`~3.18.5`（`maxSatisfying` 实测命中，不放行已无对应引擎的 `4.0.5-alpha.2`）。`tests/package.test.ts` 的「恰好两条通道」断言改为单版本契约。
+
+- **适配本轮唯一的运行代码破坏性变更**：`@deepseek-ai/dsh-web` 把搜索/抓取的选择契约改为易变引用（`WebRuntimeConfig.searchProvider`／`fetchProvider` 变为 `Volatile`），构造函数 `config` 由可选变必填，并删除了插件此前直写的私有实例字段 `searchProviderId`／`fetchProviderId`。旧写法在 rc.2 上会写到一个没有读取方的属性：不抛错、功能静默失效。本轮改按 rc.2 官方易变写入路径实现运行时选择（写入 profile 的易变字段，由 loader 原地提交进运行中的 `web` 条目，不重挂载），并同步改造测试夹具。该字段与官方「Web 搜索」卡片的新版 API 开关是同一个：**用户层已存在他人的显式选择时插件不夺取**，只在无人 pin 时接管，并把接管状态暴露出来（开关的中英双语提示，外加一行宿主日志说明「官方页面已选定其他后端，本提供方保持已注册但未被选中」）。除该接缝外，其余 16 个直接依赖包与 9 个 vendor 包源码零差异（`cordis` 4.0.4 → 4.0.5、`schemastery` 3.18.4 → 3.18.5 逐文件 diff 仅版本行），exports 漂移（7 个包新增 `./locale/*.json` 并删除 `./invariant`，`typert-protocol` 新增 `./remote-info`）插件均未引用。rc.2 首发的官方网页搜索后端与模型标签插槽不接入（后者是 `single` 单占类插槽，官方已占用，重复注册会抛错）。
+
+- DSH 升级技能、引擎兼容参考、[对接说明](docs/对接说明.md)、[审计清单](docs/DSH升级审计清单.md)与两份 README 同步到单引擎矩阵；保留历史条目作为历史证据，不删除既往诊断。本轮验证**全部通过**（本机静态与合成依赖验证）：`npm run typecheck` 退出码 0；`npm test` 退出码 0、**1038 项全绿 / 0 失败**（本轮开工前基线为 1009 项、其中 2 项失败，失败的正是网页搜索选择缺陷；与 `origin/main` 的 11 个提交合并后复跑）；`npm run build` 退出码 0（重建 `lib/index.js`、`lib/index.d.ts`、`lib/client.js`）；`npm run test:pack` 退出码 0（发布入口 18 个文件，版本 `0.14.0`）；`npm run test:engine` 退出码 0，矩阵 1/1 落在 `dsh 0.2.1-rc.2` 且宿主准入 preflight 通过；`npm run test:install` 退出码 0（pnpm `10.34.5`，`engine matrix verified: 0.2.1-rc.2`）。**未做**：真实浏览器渲染、官方网页搜索卡片与插件开关的并发双写、真实账号登录、付费生成、跨平台与长期稳定性；引擎内网络响应与凭据均为合成依赖。两条决策见[《决策记录》第八章第13条](docs/决策记录.md#八dsh-引擎兼容范围与验证边界)。
+
+- DSH 兼容范围的 alpha（早期测试版）通道由 `0.2.1-alpha.4` 替换为 `0.2.1-alpha.5`，保留 `0.2.0-rc.2`（候选发布版）。兼容声明、对等/开发依赖与锁文件同步；29 个宿主包采用官方发布元数据精准更新，第三方及 10 个平台可选依赖条目保持原值，锁文件根版本号对齐现有 `0.13.4`。完整源码与发布清单比对未发现插件运行代码或测试夹具必须改动的契约；新增模型名称插槽和官方账号通知不接入。类型检查、1009 项测试、构建、双引擎及双版本隔离安装均通过，隔离 `npm ci --dry-run`（仅检查安装）退出码为 0。浏览器与真实提供商未实测。详见[对接说明](docs/对接说明.md)及[审计清单](docs/DSH升级审计清单.md)。该轮次随后被上面的单引擎收敛取代：`0.2.1-alpha.5` 已退出兼容矩阵，其验证结论作为历史证据保留。
+
+## [0.13.4] - 2026-10-16
+
+### Added
+
+- 问题 #79：价格试算新增逐模型 30 天折算，以及相对所选历史完整工作量的成本差额与比例；主行保留计价覆盖，能力与排除明细可展开。缺价、超上下文、读取不完整或观察不足一天时明确说明原因，基准为零不制造百分比。指标复用同一份报告，不增加历史读取、远端字段或模型调用。
+
+- 支持**自定义上下文长度**（#86）：新增全局 `contextWindow` 与按模型 `contextWindowOverrides`，解析顺序为按模型 → 全局 → 目录；网页设置页与配置文件均可设置，终端设置页尚未接入。接受 1～10,000,000 的整数，输入支持二进制 `32K`/`1M` 简写。按模型行只列白名单可见模型，已有覆盖保留；清空整表写 `{}` 遮蔽基础层。选择器、宿主计量与默认输出预算跟随有效窗口。
+
+### Changed
+
+- 同步 Command Code CLI `1.82.2` → `1.82.4`：请求版本标识（`x-command-code-version`）随之上调。官方日志**没有 1.82.1–1.82.4 任何条目**（CLI 通道最新仍是 `1.82.0`／2026-10-13，页面最新条目 `0.1.55` 属 Desktop 应用版本线，两条产品线混排在同一时间轴），因此结论全部来自产物级比对：逐字节比对两版 `dist/cli.mjs` 与本仓库固定的 `1.82.2` 基线，并用实时目录与官方定价页交叉验证。
+
+- **能力数据的权威来源换了**：`1.82.4` 的 `getSupportedEfforts()` 不再从 CLI 内置 Map 取数（`xn.get(n) ?? null`），改为 `resolveKnownCatalogModel({model, catalog})?.reasoningEfforts`；`knownModelSupportsZdr()` 同样由「取反硬编码集合」改为读目录的每模型 `zdr` 字段（`?.zdr ?? false`），**默认值语义随之反转——过去「未列出」视为已覆盖，现在「未列出或不为 true」即不覆盖**。CLI 新增内嵌快照 + 远程覆盖机制（`schemaVersion`／`catalogVersion`／`refreshAfterSeconds: 900`），远程端点为 `GET /provider/v1/models?view=client`——该视图才带 `reasoningEfforts`／`zdr`／`inputModalities`／`minimumPlan`／`pricing`，默认视图（92 条）没有这些字段。内嵌快照只是兜底：它发布后约两天即过期（`f3eebbb3…`／99 条 对 远程 `d6177bab…`／100 条，仅成员增减、共同 id 字段零漂移），因此本插件的 `KNOWN_*` 快照以实时目录为准。**这次迁移也让技能的 `extract-cli.mjs` 失效**（锚点按 minified 函数名与 `.get()`／`.has()` 调用形态取数，而 `1.82.4` 把语义名移入 `__name(fn,"…")`、真实声明改名 `getSupportedEfforts2`／`modelSupportsZdr2`），先报 `Missing/ambiguous effort map`、短路后再报 `Missing/ambiguous ZDR exception set`；`buildModelGroups` 与 `getPlanInfo` 两个锚点仍可正常提取。本轮差异由人工提取补齐，巡检脚本与 `audit.py` 的适配另行处理。
+
+- 模型快照同步（以实时 `?view=client` 目录为准）：新增 4 个模型——`Qwen/Qwen3.8-Max-Prime`（最低 **GOAT** 档、100 万上下文、支持图像输入、三档 `low`／`medium`／`xhigh`）、`meta/muse-spark-open`（2026-10-15 上线、Go 档、图像、三档）、`nvidia/nemotron-3.5-super-vl`（2026-10-14、Go 档、图像、三档）、`stealth/cat-jam:free`（免费隐身预览、Go 档、仅文本、五档 `low`／`medium`／`high`／`xhigh`／`max`，免费促销无结束日期）。推理档位表 60 → 64 条，图像表 67 → 70 条，最低套餐表 89 → 92 条（严格超集链不变）。`Qwen/Qwen3.8-Max-Prime` 在 `0.13.3` 曾因「CLI 未注册」而不予录入，`1.82.4` 已把它写进内嵌目录与实时目录，这条待观察项就此结清。
+
+- **零数据保留例外集 22 → 24 条**：新增 `meituan/LongCat-2.0:free` 与 `stealth/cat-jam:free`。LongCat 是对 `1.74.1` 的**有意回退**——那次只把它从提取器读取的锚点里移除，canonical 辅助函数一直保留着它，两个锚点集因此相差恰好这一个 id（22 对 23）并持续了八个版本；`1.82.4` 让两者都改读目录的 `zdr` 字段，该行取值为 `false`，于是本表跟随目录判决把它收回。`stealth/cat-jam:free` 同理（目录 `zdr:false`，且不在任何锚点集里）。两处都已更新注释与测试断言。
+
+- 退役清理：`inclusionai/ling-3.0-flash-sante:free` 从**全部**快照表移除（最低套餐、免费促销、自动推理、输出上限，以及生成器的手工上限映射 `MANUAL_CEILINGS`，该映射随之清空）——它已从实时目录、定价页与 `1.82.4` 内嵌快照三处同时消失，没有任何官方来源再提名它。价格表随官方页面重新生成（92 行）：新增 `muse-spark-open`（$1.25／$4.25／$0.15）、`nemotron-3.5-super-vl`（$0.2／$0.5／$0.04）、`typesafe/jev-1.14.0`（$0.042 输入、输出免费）三行，`gpt-5.6-sol` 的每月额度由 Go $6／GOAT $70／Pro $80 下调为 **$6／$20／$30**、`ling-3.1-flash` 由 **$20／$30 上调为 $100／$110**（`0.13.3` 记录的 `planBudgetSteps` 预生效额度，本次随之结清）；费率与峰谷窗口零变化。`node scripts/sync-model-prices.mjs --check` 与 `sync-output-limits.mjs --check` 均已干净。
+
+- 同步收官到 `1.82.5`：同一轮巡检中官方又发布了 `1.82.5`（`1.82.4` 之上一个补丁）。产物级比对确认**协议与数据面零差异**——`1.82.5` 唯一的变化是把实时目录里那三个新模型（`meta/muse-spark-open`、`nvidia/nemotron-3.5-super-vl`、`stealth/cat-jam:free`）与 `stealth/cat-jam:free` 的 ZDR 判定**折回内嵌快照**，也就是把本轮同步依据的实时目录结果固化进产物。因此本次只需上调请求版本标识；`candidateDiffs` 对 `KNOWN_EFFORTS`／`KNOWN_NON_ZDR_MODELS`／`KNOWN_IMAGE_MODELS` 三张表均为零差异，证明按实时目录同步的快照已完全覆盖 `1.82.5` 的内嵌表。
+
+- 复核**无变化**的项：峰谷计价仍是 5 个 DeepSeek 模型、窗口 `01–04 & 06–10 UTC, Mon–Fri` 与本地常量逐值一致（官方 `/pricing` 营销页另展示 15 个含 GLM／MiniMax 的峰谷行，与生成器数据源 `/docs/resources/pricing-limits` 的 5 行冲突，属上游两页不一致，本插件继续以生成器数据源为准）；订阅标签与月额度、`minimumPlan` 与目录逐条一致；自动推理模型 22 个逐 id 不变；effort 词汇表两版都是 `off｜low｜medium｜high｜xhigh｜max`。
+
+- 引擎兼容范围的 alpha（早期测试版）通道由 `0.2.1-alpha.3` 替换为 **`0.2.1-alpha.4`**；RC（候选发布版）通道 `0.2.0-rc.2` 本次未变动。**这一版必须升级**：dsh 自 `0.2.1-alpha.4` 起把插件兼容性判定改为**只读 `engines.dsh`**、完全忽略 `@deepseek-ai/dsh*` 对等依赖（只有缺少该字段时才回落到 peer 规则），旧声明在新引擎上会被宿主拒绝——插件行被预检禁用、作为 bundle 被静默跳过、`dsh plugin add` 在 pnpm 之前就拒绝，而本地 `npm run test:engine` 仍然全绿。`engines.dsh`、`dsh.compatibility.dsh`、`dsh.compatibility.dshReleases`、全部 Harness 对等依赖与开发依赖、`package-lock.json` 同批同步；锁文件采用精准替换（29 个 dsh 条目加根声明面），非 dsh 依赖零漂移，平台可选依赖分支 10 个保持完整。插件 `src/` 与 `lib/` 运行时零改动，测试夹具也零改动。
+
+- `npm run test:engine` 新增**准入判定检查**：对每个已声明引擎真实调用该引擎自己的 `evaluatePluginCompatibility`（`checkEngineAdmission`）。该脚本此前的检查全都走「把发布面装进引擎的 peer 树再加载」，看不见宿主准入判定本身，正是这个盲区让上面那个破坏点在全绿的情况下依然存在。红绿对照已实测：alpha.4 通过，已退出兼容范围的 alpha.3 被拒并报出未满足项。
+
+- 设置页信息架构调整：原本独立成组的「上下文长度」并入「模型」分组，分组标题改为**「模型与上下文」**（英文 **Models & context**），顶级分组由 6 个减为 5 个：账户 → 模型与上下文 → 隐私与安全 → 集成与显示 → 高级设置（默认折叠）。组内顺序为隐藏套餐外模型开关 → 可见模型白名单 → **自定义上下文长度**字段 → **按模型覆盖**标题行与覆盖行列表；这些控件直接平铺，**不设子节标题、不画分隔线**——中间版本曾把它们做成带次级标题与细分隔线的子节（`SettingsSubGroup`、locale 键 `contextTitle`），用户在实际页面上查看后判定视觉冗余，随即改为平铺并删除该组件与键。**行为零变化**：`contextWindow` 与 `contextWindowOverrides` 两个配置项、解析优先级（按模型 → 全局 → 目录）与保存路径都没有改动，仅位置与呈现调整。
+
+### Fixed
+
+- 问题 #88：会话标题调用在模型明确支持 `off`（关闭思考）时自动发送该档位，避免默认 64 词元预算耗在思考上；两种聊天协议及协议回退均生效，普通对话、上下文压缩和其他模型保留原策略，输出预算不变。
+
+- 设置页与侧边栏面板的**请求计数自动换算**：`成功 1234567 / 失败 123` 在四列等宽卡片里是单行不换行文本，宽度不够时省略号从右侧吃掉「失败 …」——恰好是最该看见的那个数。现在计数按 `K`/`M`/`B` 紧凑显示（`1234567` → `1.2M`、`12000` → `12K`，整数不带多余的 `.0`），精确值改由悬停 `title` 给出，且**只在确实换算过时才挂**（未换算时悬停弹出的文字与卡片上写的一模一样）。卡片主数字（请求总数）一并换算。新增 `formatCompactCount` 与 `compactCountTitle`（`src/display-format.ts`，设置页与面板共用同一实现与同一档位规则），并修好既有 `formatTokensCompact` 的**进位边界**：`999999` 过去显示为 `1000.0K`、`999999999` 显示为 `1000.0M`，现在分别是 `1.0M` 与 `1.0B`——先除以档位再四舍五入会落到并不存在的档位上。终端命令的用量行保持不换算：终端宽度充足，且那里更需要精确值。
+
+
+- 自定义上下文普通小数在网页及配置结构中均被拒绝，避免宿主报无效模型上下文；程序化绕过校验时仍清洗无效值。
+- 调大窗口时解除旧目录窗口对输出预算的限制；三协议默认及显式请求仍遵守有效窗口、模型公布或快照输出上限、运行时学习上限和网关总上限。
+
 ## [0.13.3] - 2026-10-15
 
 ### Changed

package/README.md

@@ -25,6 +25,7 @@ Unofficial [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harnes
 - **Multi-account rotation** — when one account hits its usage limit, requests switch to the next account automatically. See [Account rotation](#account-rotation).
 - **Flexible API key setup** — via the settings page, an environment variable, or the official CLI login file.
 - **Model-picker annotations** — minimum plan, active deal or `FREE` badge, peak/off-peak state, image support, and context window; free models listed first.
+- **Custom context length** — override the context window the harness meters and compacts against: one global value plus per-model overrides, edited on the settings page or in config (issue #86); unset follows the catalog.
 - **Plan-aware picker** — models above your subscription tier are hidden by default (toggleable); an optional **Model allowlist** keeps only your favorites in the picker.
 - **Reasoning-effort support** — models with selectable reasoning effort levels expose them in the picker.
 - **Image input** — Vision-capable models accept images.
@@ -36,11 +37,16 @@ See [Screenshots](#screenshots) below for what the UI looks like.
 
 ## Install
 
-This release supports **dsh 0.2.0-rc.2 (RC) and dsh 0.2.1-alpha.3 (alpha)**.
-The compatibility policy keeps the latest verified official release candidate
-and alpha release, one per channel. These match npm's `latest` and `alpha` tags
-as checked on 2026-10-14. The peer range and compatibility records name only
-these two exact versions. A profile on `0.2.1-alpha.2` must upgrade its engine
+This release supports **dsh 0.2.1-rc.2**. The compatibility matrix is now a
+single verified engine: the RC channel moved from `0.2.0-rc.2` to `0.2.1-rc.2`
+on 2026-10-17, and no alpha release is retained because none has been verified
+since `0.2.1-alpha.5`. The peer range and compatibility records name only that
+exact version, and `@deepseek-ai/cordis` / `@deepseek-ai/schemastery` are pinned
+to the stable releases paired with it (`~4.0.5` / `~3.18.5`). Note that
+**dsh 0.2.1-rc.2 reads `engines.dsh` alone** when it decides whether a plugin is
+compatible; the dsh peer ranges are consulted only when that field is absent, so
+a build that declares the wrong `engines.dsh` is refused outright. A profile on
+`0.2.0-rc.2`, `0.2.1-alpha.5` or any earlier release must upgrade its engine
 before installing this build:
 
 ```sh
@@ -68,14 +74,14 @@ dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.11.15
 
 The same applies to every profile you install into, including the terminal UI below.
 
-Fresh pnpm 10 marketplace generations are supported directly. Every Harness package is declared by the plugin as a Host peer, so the active dsh profile remains their owner; do not add a separate dependency for any of them. The `@deepseek-ai/dsh-*` packages share one exact-version disjunction; `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` carry the paired ranges `~4.0.4 || ~4.0.5-alpha.1` and `~3.18.4 || ~3.18.5-alpha.1` instead, because publishing an engine rewrites both to the version that shipped alongside it. Upstream removed the `@deepseek-ai/dsh-invariants` package in `0.2.1-alpha.1`, so the plugin no longer declares it.
+Fresh pnpm 10 marketplace generations are supported directly. Every Harness package is declared by the plugin as a Host peer, so the active dsh profile remains their owner; do not add a separate dependency for any of them. The `@deepseek-ai/dsh-*` packages all declare one exact version; `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` carry the ranges `~4.0.5` and `~3.18.5` paired with that engine instead, because publishing an engine rewrites both to the version that shipped alongside it. Upstream removed the `@deepseek-ai/dsh-invariants` package in `0.2.1-alpha.1`, so the plugin no longer declares it.
 
 ## Updating
 
 Update with the same tag you installed with:
 
 ```sh
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2 or 0.2.1-alpha.3
+dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.1-rc.2
 dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@0.9.1      # older dsh (0.5.0 line, unmaintained)
 ```
 
@@ -154,7 +160,7 @@ cmd login                               # writes ~/.commandcode/auth.json
         cwd: !!js process.cwd()
 ```
 
-**Engine version.** The plugin is maintained against two engines: **dsh 0.2.0-rc.2** and **dsh 0.2.1-alpha.3**. Its `@deepseek-ai/dsh-*` peers use `0.2.0-rc.2 || 0.2.1-alpha.3`, while `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` retain their engine-paired ranges `~4.0.4 || ~4.0.5-alpha.1` and `~3.18.4 || ~3.18.5-alpha.1`. Compatibility records contain exactly these two engines. Each channel upgrade replaces its previous version after verification; it does not accumulate supported releases or admit unverified neighbours. Both `npm run test:engine` and `npm run test:install` check each retained version. See [Install](#install) for older engines.
+**Engine version.** The plugin is maintained against **one verified engine: dsh 0.2.1-rc.2**. Its `@deepseek-ai/dsh-*` peers use the exact version `0.2.1-rc.2`, while `@deepseek-ai/cordis` and `@deepseek-ai/schemastery` use the stable ranges paired with that engine release, `~4.0.5` and `~3.18.5` (both were prereleases in the alpha era and became stable with this batch). Compatibility records contain exactly this one engine. Each channel upgrade replaces its previous version after verification; it does not accumulate supported releases or admit unverified neighbours, and a channel with no newly verified release simply leaves the matrix. Both `npm run test:engine` and `npm run test:install` check the retained engine, and `test:engine` also calls that engine's own `evaluatePluginCompatibility` on the published manifest — from alpha.4 on, that verdict reads `engines.dsh` alone, so a wrong engine declaration fails there instead of only at install time. See [Install](#install) for older engines.
 
 ## Usage dashboard
 
@@ -173,7 +179,7 @@ With several Command Code subscriptions, the plugin **switches to the next accou
 - **Setup** — click **Add account** in the **Accounts** card at Settings → **Command Code**, optionally name it, then either **Sign in to Command Code** (the key is stored when you approve in the browser; a sign-in that does not complete leaves no empty account behind) or paste an API key. Account actions — add, rename, replace or clear a key, remove, pin — apply immediately; only the other settings on the page wait for the Save bar. The top-level key always serves first as the `default` account.
 - **Manual switching** — **Pin this account** in an account's **⋯** menu makes it the preferred account; if it is exhausted, requests fall back to other accounts and return once its window resets. **Unpin** returns to automatic rotation.
 - **Dedicated models** — expand an account and pick its **Dedicated models** from the live catalog. A request for one of those models serves from that account while it is usable; an exhausted or invalid account falls back to the normal rotation. A model belongs to one account at a time — picking it for another account moves it. (Stored as `modelAccountRules`.)
-- **Show only favorite models** — the **Visible models** picker in the **Models** card keeps only the checked models in the model picker; unchecked shows all (the default).
+- **Show only favorite models** — the **Visible models** picker in the **Models & context** card keeps only the checked models in the model picker; unchecked shows all (the default).
 - **Status** — each account row shows its plan, status and 5-hour/weekly meters; expand it for the full report. `/commandcode` reports the same per-account state.
 
 The equivalent YAML (`$DSH_HOME/settings.yaml` or composition config):
@@ -202,7 +208,7 @@ llm-commandcode:
 
 ## Configure
 
-**Settings → Command Code** is organized as **Accounts** (keys, sign-in, live quota, pinning, dedicated models), **Models** (hide out-of-plan models, visible models), **Privacy & security** (zero data retention, off by default, see below), **Integrations & display** (serve web search with Command Code, show the quota card in the sidebar, off by default), and a collapsed **Advanced** section (API base URL, request/stream timeouts, transport retries, cache-aware image offload). The working directory is no longer on the page; `workingDir` in config still works.
+**Settings → Command Code** is organized as **Accounts** (keys, sign-in, live quota, pinning, dedicated models), **Models & context** (hide out-of-plan models, visible models, then the **Custom context length** field and the **Per-model overrides** rows right after the allowlist — global and per model, see below), **Privacy & security** (zero data retention, off by default, see below), **Integrations & display** (serve web search with Command Code, show the quota card in the sidebar, off by default), and a collapsed **Advanced** section (API base URL, request/stream timeouts, transport retries, cache-aware image offload). The working directory is no longer on the page; `workingDir` in config still works.
 
 The same options live in `$DSH_HOME/settings.yaml` (changes apply immediately, no restart):
 
@@ -217,8 +223,33 @@ llm-commandcode:
   # offloadSeenImagesForCache: true # opt in to CLI cache mitigation; later requests omit old pixels
   showSidebarQuota: true           # optional: show the plans & quota card in the sidebar (default off)
   zdr: true                        # optional: route requests only through zero-data-retention upstreams (default off)
+  # contextWindow: 131072          # optional: custom context length (tokens) for every model; unset follows the catalog
+  # contextWindowOverrides:        # optional: per-model custom context lengths; wins over contextWindow
+  #   deepseek/deepseek-v4-pro: 65536
+  # maxOutputTokens: 65536         # optional: per-turn output limit; 0 sends no max_tokens, unset follows the model ceiling
 ```
 
+### Custom context length
+
+The context window the harness meters against — and when it compacts — normally comes from the model catalog's `context_length`. The opt-in **Custom context length** field and **Per-model overrides** rows inside **Settings → Command Code → Models & context**, directly after the visible-models allowlist (or the two config fields above, issue #86), replace it per your own numbers: `contextWindow` is the global custom value applied to every model without its own row, and `contextWindowOverrides` sets one model by catalog id, winning over the global value. Unset follows the catalog; nothing changes by default.
+
+- **When it helps**: a catalog window that over-reports turns into `context_length_exceeded` failures once a session grows past the model's real capacity — advertise the lower real number and the harness compacts before the gateway refuses. An under-reported window makes long sessions compact earlier than they need to; raise it to match the model's true capacity.
+- The model-picker context annotation, `defaultMaxTokens` default and actual requests follow the same resolution. Raising the window removes the old catalog-window output cap while retaining the model's independent output ceiling, runtime-learned ceiling and gateway-wide cap; explicit output counts obey those caps too. Session-cost tier pricing keeps using each request's actual token counts.
+- Values must be whole token counts in 1 – 10,000,000. The page blocks invalid input; config-file non-numbers, fractions and out-of-range values fail schema validation rather than silently falling back. Only programmatic calls that bypass the schema discard invalid values and fall through valid per-model override → valid global value → catalog. A model the catalog does not list keeps its "no context advertised" shape.
+- The inputs accept compact shorthand in binary units: `32K` = 32,768 and `1M` = 1,048,576 (so `128K`/`256K` write the exact power-of-two windows 131,072/262,144); the stored value is always a plain number. The per-model override's model dropdown lists only the models kept by the **visible-models allowlist** (the whole catalog while showing all), and the rows carry "Model / Context length" column heads.
+
+### Per-turn output limit
+
+Every request carries `max_tokens`, resolved as the smallest of the model's published output ceiling, the ceiling learned at runtime, and the gateway-wide cap of 131,072. That field is a **passive hard limit**: the platform cuts the answer when it is reached, and the model receives no "nearly out of room" signal. The **Output limit per turn** field (**Settings → Command Code → Models & context**, or the `maxOutputTokens` config key) offers three choices:
+
+- **Empty (default)**: exactly the derivation above, so nothing changes.
+- **A positive number**: taken as a cap alongside that derived value. It can only **tighten** — it never exceeds the model ceiling or the gateway's `131072`, and out-of-range input fails config validation. Shorthand like `64K` is accepted.
+- **`0`**: sends **no** `max_tokens` field at all, leaving the per-turn output size to the platform. This is the fix for answers being cut off mid-sentence, because while the field is present the cut happens at some point no matter how large the figure is.
+
+`0` only takes effect on the two transports that accept an absent field: the CLI (`/alpha/generate`) and OpenAI (`/provider/v1/chat/completions`). The Anthropic Messages endpoint Claude uses **requires** the field — omitting it is refused upstream with `Invalid input: expected number, received undefined at max_tokens` — so that route keeps sending its derived budget and `0` has no effect for Claude. Auxiliary calls whose budget the host fixes itself (the session title is pinned at 64 tokens) also outrank this setting and are not unbound by `0`.
+
+An empty field **clears** the setting back to the derived default; it is not the same as writing `0`.
+
 ### Repeated image cache misses
 
 On the CLI transport (`/alpha/generate`), a new image can make Command Code's reported prompt cache retreat to the first historical image even when every previous request message is byte-identical. The opt-in **Stop replaying images already seen** setting (`offloadSeenImagesForCache`) asks dsh's durable `image/offload` surface to replace an older image with a stable text placeholder after this same model has answered with it. The next request keeps its new image; later text can be cached without replaying old pixels. The default is off because the model cannot inspect an offloaded image again unless it rereads the source file or the user reattaches it. This mitigates the observed cost spike; it does not repair Command Code's underlying multimodal cache behavior. [Live evidence and limits](docs/issue-64-cache-review.md).
@@ -227,10 +258,10 @@ On the CLI transport (`/alpha/generate`), a new image can make Command Code's re
 
 When your deployment's dsh shell mounts the web capability (`@deepseek-ai/dsh-web` + `@deepseek-ai/dsh-tool-web`), the model's `web_search` tool is served by this plugin's `commandcode` search provider — it calls the Command Code Provider API's `/alpha/web-search` endpoint with the **same API key and base URL** as chat. You do not configure a separate search key, endpoint, or model.
 
-**On by default.** The plugin's **Settings → Command Code** page has a *"Serve dsh web search with Command Code"* toggle (`webSearch`, default on). When on, the plugin selects `commandcode` as the active search backend automatically; turn it off to hand the selection back to whichever backend was there before (a sibling search plugin such as modsearch keeps working — it is never forced back to dsh's shipped DeepSeek search). The toggle takes effect on the next search — no restart needed.
+**On by default.** The plugin's **Settings → Command Code** page has a *"Serve dsh web search with Command Code"* toggle (`webSearch`, default on). When on, the plugin selects `commandcode` as the active search backend automatically; turn it off to hand the selection back to whichever backend was there before (a sibling search plugin such as modsearch keeps working — it is never forced back to dsh's shipped DeepSeek search). The toggle takes effect on the next search — no restart needed. On dsh 0.2.1-rc.2 this uses the official volatile-settings write path, so the change is committed into the running `web` entry in place rather than by remounting it. **When the official Web search settings already pin another backend, this toggle has no effect** — that explicit choice wins.
 
 - The provider registers as `commandcode` on `ctx.web` only when the web service is present; without it this stays a chat-only plugin.
-- The toggle works by selecting `commandcode` in the web seam at boot and on every settings change, remembering the backend it displaced; turning the toggle off (or unloading the plugin) restores that backend. If you'd rather pin it durably, set `searchProvider: commandcode` (or `$DSH_WEB_SEARCH_PROVIDER=commandcode`); that remains effective even if this plugin's runtime selection is unavailable.
+- The toggle selects `commandcode` through the engine's volatile-settings write path — the same `web.searchProvider` field the official **Web search** card's *Use the new Web Search API* switch writes (that switch also writes `fetchProvider`). The plugin **defers to an explicit choice already present in the user layer**: when the Web search settings pin another backend, it keeps `commandcode` registered but unselected and reports that state (the toggle's hint, plus a host log line) instead of overwriting it; it takes over only while nothing else pins the field, remembers the backend it displaced, and restores it when the toggle goes off or the plugin unloads. If you would rather pin the choice durably, set `searchProvider: commandcode` (or `$DSH_WEB_SEARCH_PROVIDER=commandcode`); that keeps working even if the runtime selection cannot be committed.
 - `numResults` from the dsh tool is clamped to the Command Code range (1–10, default 5); results map to the dsh `WebSearchSource` shape (`url`/`title`/`snippet`).
 
 > This reuses the Command Code Provider API directly (like the official CLI's built-in `web_search`), so it is distinct from a DeepSeek-native search backend.

package/README.zh-CN.md

@@ -25,6 +25,7 @@
 - **多账户轮换**：一个账户用量打满后，请求自动切换到下一个账户。详见[多账户轮换](#多账户轮换)。
 - **key 配置灵活**：设置页填写、环境变量或官方 CLI 登录文件均可。
 - **模型选择器标注**：每个模型标注最低套餐、折扣/FREE 徽章、峰谷时段、图片支持与上下文长度，免费模型置顶。
+- **自定义上下文长度**：覆盖宿主用于上下文计量与自动压缩的上下文窗口——一个全局值加按模型覆盖，可在设置页或配置中设置（issue #86），不填则跟随模型目录。
 - **按套餐过滤**：默认隐藏超出订阅套餐的模型，可一键关闭；「模型白名单」可进一步只保留常用模型。
 - **推理强度支持**：支持推理强度的模型可在选择器中选择档位。
 - **图片输入**：Vision 模型支持发送图片。
@@ -34,7 +35,7 @@
 
 ## 安装
 
-本版本**只支持 dsh 0.2.0-rc.2（RC，候选发布版）与 dsh 0.2.1-alpha.3（alpha，早期测试版）**。维护策略为每条通道只保留官方最新且经过验证的一个版本；2026-10-14 核对时分别对应 npm 的 `latest` 与 `alpha` 发布标签。peer（对等依赖）范围和兼容记录只列这两个精确版本。使用 `0.2.1-alpha.2` 的配置需先升级引擎，再安装本构建：
+本版本**只支持 dsh 0.2.1-rc.2**。兼容矩阵已收敛为单一已验证引擎：RC（候选发布版）通道于 2026-10-17 由 `0.2.0-rc.2` 替换为 `0.2.1-rc.2`，alpha（早期测试版）通道自 `0.2.1-alpha.5` 之后没有新的已验证版本，本轮退出支持矩阵。peer（对等依赖）范围和兼容记录只列这一个精确版本；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 固定为该引擎配对的正式版范围 `~4.0.5`／`~3.18.5`。注意 **dsh 0.2.1-rc.2 判定插件兼容性时只读 `engines.dsh`**，dsh 对等依赖范围仅在该字段缺失时才被参考，因此 `engines.dsh` 声明错误会被直接拒绝。使用 `0.2.0-rc.2`、`0.2.1-alpha.5` 或更早版本的配置需先升级引擎，再安装本构建：
 
 ```sh
 dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@latest
@@ -56,14 +57,14 @@ dsh plugin --profile web add @mars-sea/dsh-commandcode-provider@0.11.15
 
 这一点对每个 profile 都成立，包括下面的终端界面。
 
-插件可直接在 pnpm 10 的全新插件市场 generation 中安装。所有 Harness 包都由插件声明为 Host peer，由当前 dsh profile 统一管理，不要另行添加 dependency。其中 `@deepseek-ai/dsh-*` 共用同一个精确版本析取；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 则分别写成配对范围 `~4.0.4 || ~4.0.5-alpha.1` 与 `~3.18.4 || ~3.18.5-alpha.1`——上游每次发引擎都会把这两个包重写成随引擎发布的版本。上游曾在 `0.2.1-alpha.1` 删除 `@deepseek-ai/dsh-invariants` 这个包，因此插件不再声明它。
+插件可直接在 pnpm 10 的全新插件市场 generation 中安装。所有 Harness 包都由插件声明为 Host peer，由当前 dsh profile 统一管理，不要另行添加 dependency。其中 `@deepseek-ai/dsh-*` 全部声明同一个精确版本；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 则写成该引擎配对的范围 `~4.0.5` 与 `~3.18.5`——上游每次发引擎都会把这两个包重写成随引擎发布的版本。上游曾在 `0.2.1-alpha.1` 删除 `@deepseek-ai/dsh-invariants` 这个包，因此插件不再声明它。
 
 ## 更新
 
 用与安装时相同的 tag 更新：
 
 ```sh
-dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.0-rc.2 或 0.2.1-alpha.3
+dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@latest     # dsh 0.2.1-rc.2
 dsh plugin --profile web update @mars-sea/dsh-commandcode-provider@0.9.1      # 更早的 dsh（0.5.0 线，不再维护）
 ```
 
@@ -142,7 +143,7 @@ cmd login                               # 写入 ~/.commandcode/auth.json
         cwd: !!js process.cwd()
 ```
 
-**引擎版本要求。** 插件维护两个引擎：**dsh 0.2.0-rc.2** 与 **dsh 0.2.1-alpha.3**。`@deepseek-ai/dsh-*` 的 peer（对等依赖）为 `0.2.0-rc.2 || 0.2.1-alpha.3`；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 仍使用随引擎配对的范围 `~4.0.4 || ~4.0.5-alpha.1` 与 `~3.18.4 || ~3.18.5-alpha.1`。兼容记录恰好包含两个版本，同通道升级验证后替换旧版，不累加已支持版本、不放行未验证的邻近版本。`npm run test:engine` 与 `npm run test:install` 均逐版本验证。旧引擎安装说明见[安装](#安装)。
+**引擎版本要求。** 插件只维护**一个已验证引擎：dsh 0.2.1-rc.2**。`@deepseek-ai/dsh-*` 的 peer（对等依赖）为精确版本 `0.2.1-rc.2`；`@deepseek-ai/cordis` 与 `@deepseek-ai/schemastery` 使用该引擎配对的正式版范围 `~4.0.5` 与 `~3.18.5`（两者在 alpha 时期是预发布，随本批次转为正式版）。兼容记录恰好包含这一个版本，同通道升级验证后替换旧版，不累加已支持版本、不放行未验证的邻近版本；某条通道没有新的已验证版本时，直接退出矩阵而不保留。`npm run test:engine` 与 `npm run test:install` 对保留的引擎执行验证，前者还会用该引擎自己的 `evaluatePluginCompatibility` 对发布清单求值——自 alpha.4 起该判定只读 `engines.dsh`，因此引擎声明写错会在这一步失败，而不是拖到安装时才暴露。旧引擎安装说明见[安装](#安装)。
 
 ## 用量面板
 
@@ -161,7 +162,7 @@ cmd login                               # 写入 ~/.commandcode/auth.json
 - **配置**：在 **设置 → Command Code** 的「账户」卡片点击「添加账户」，可填写备注名，然后选择「网页登录」（在浏览器授权后自动保存 key；登录未完成不会留下空账户）或「粘贴密钥」。添加、重命名、更换或清除密钥、移除、固定等账户操作**立即生效**，无需点击页面底部的「保存」；「保存」只作用于页面上的其他设置。顶层 key 始终是第一顺位的 `default` 账户。
 - **手动切换**：在账户行的「⋯」菜单中选择「固定使用此账户」即可指定优先账户；所选账户耗尽时自动回落到其他账户，窗口重置后自动恢复。「取消固定」回到自动轮换。
 - **专用模型**：展开某个账户，从实时模型目录**多选**它的「专用模型」。请求这些模型且该账户可用时使用该账户；账户耗尽或密钥失效时自动回落到常规轮换。一个模型同一时间只属于一个账户，给另一个账户选择它会自动移过去（仍保存为 `modelAccountRules`）。
-- **只显示常用模型**：在「模型」卡片的「可见模型」中勾选要保留的模型，模型选择器只列出这些；不勾选则显示全部（默认行为不变）。
+- **只显示常用模型**：在「模型与上下文」卡片的「可见模型」中勾选要保留的模型，模型选择器只列出这些；不勾选则显示全部（默认行为不变）。
 - **状态展示**：每个账户行直接显示套餐、状态以及 5 小时 / 每周额度条，展开可查看完整报告；`/commandcode` 同样按账户显示状态。
 
 等价的 YAML（`$DSH_HOME/settings.yaml` 或组合配置）：
@@ -190,7 +191,7 @@ llm-commandcode:
 
 ## 配置
 
-**设置 → Command Code** 分为：**账户**（密钥、网页登录、实时额度、固定账户、专用模型）、**模型**（隐藏套餐外模型、可见模型）、**隐私与安全**（零数据保留 ZDR，默认关闭，见下）、**集成与显示**（用 Command Code 承载联网搜索、在侧边栏显示额度卡片，默认关闭），以及默认折叠的**高级设置**（API 地址、请求/流超时、传输重试次数、历史图片缓存优化）。工作目录已不在页面上显示，配置中的 `workingDir` 仍然有效。
+**设置 → Command Code** 分为：**账户**（密钥、网页登录、实时额度、固定账户、专用模型）、**模型与上下文**（隐藏套餐外模型、可见模型，以及紧随白名单之后的**自定义上下文长度**字段与**按模型覆盖**列表，全局与按模型，见下）、**隐私与安全**（零数据保留 ZDR，默认关闭，见下）、**集成与显示**（用 Command Code 承载联网搜索、在侧边栏显示额度卡片，默认关闭），以及默认折叠的**高级设置**（API 地址、请求/流超时、传输重试次数、历史图片缓存优化）。工作目录已不在页面上显示，配置中的 `workingDir` 仍然有效。
 
 同一组选项也位于 `$DSH_HOME/settings.yaml`（修改即刻生效，无需重启）：
 
@@ -205,8 +206,33 @@ llm-commandcode:
   # offloadSeenImagesForCache: true # 可选：模型回复后不再重发旧图片，默认关闭
   showSidebarQuota: true           # 可选：在侧边栏显示套餐与配额卡片（默认关闭）
   zdr: true                        # 可选：请求只经由零数据保留上游（默认关闭）
+  # contextWindow: 131072          # 可选：自定义上下文长度（token），对所有模型生效；不填跟随目录
+  # contextWindowOverrides:        # 可选：按模型的自定义上下文长度；优先于 contextWindow
+  #   deepseek/deepseek-v4-pro: 65536
+  # maxOutputTokens: 65536         # 可选：单轮输出上限；0 = 不发送 max_tokens，留空跟随模型上限
 ```
 
+### 自定义上下文长度
+
+宿主用于上下文计量、并据此触发自动压缩的上下文窗口，通常来自模型目录的 `context_length`。**设置 → Command Code → 模型与上下文**中、紧随可见模型白名单之后的**自定义上下文长度**输入框与**按模型覆盖**列表（或上面的两个配置项，issue #86）可以用你自己的数值替换它：`contextWindow` 是对所有没有单独条目的模型生效的全局值，`contextWindowOverrides` 按目录模型 id 单独设置、优先于全局值。不填则完全跟随目录，默认无任何变化。
+
+- **适用场景**：目录值偏大时，会话一长就会撞上真实的模型容量、请求以 `context_length_exceeded` 失败——填入更小的真实值，宿主会在服务端拒绝之前先压缩；目录值偏小时，长会话会比实际需要更早压缩——调大以匹配模型真实容量。
+- 模型选择器的上下文标注、`defaultMaxTokens` 默认预算与实际请求都跟随同一解析结果。调大窗口会解除旧目录窗口对输出的限制，但仍受模型独立输出上限、运行时学习上限和网关总上限约束；显式指定的输出数也受这些上限约束。会话费用的上下文分层计价仍按每次请求的实际 token 数。
+- 取值单位为 token，范围 1 – 10 000 000，必须为整数。网页阻止保存无效输入；配置文件中的非数值、小数或越界值由配置校验拒绝，不会静默回落。只有绕过配置校验的程序化调用会丢弃无效值，按「有效按模型值 → 有效全局值 → 目录」回落。目录没有的模型保持「无上下文宣告」的既有形状。
+- 输入框接受 `32K`、`1M` 这样的简写（二进制换算：`32K` = 32 768、`1M` = 1 048 576，131 072、262 144 这类 2 的幂窗口可直接写成 `128K`、`256K`；落盘仍是纯数字）。按模型覆盖的模型下拉只列出**模型白名单**中可见的模型（白名单为「显示全部」时即整个目录），行列表带「模型 / 上下文长度」列头。
+
+### 单轮输出上限
+
+插件每次请求都会带上 `max_tokens`，取值是「模型公布的输出上限、运行时学到的上限、网关总上限 131 072」三者取最小。这个字段是**被动硬限制**：到点就被平台切断，模型自己收不到「快到上限了」的信号。**设置 → Command Code → 模型与上下文**中的**单轮输出上限**（或配置项 `maxOutputTokens`）给了三个选择：
+
+- **留空（默认）**：完全沿用上面的推导，行为与之前一致。
+- **正整数**：与推导值取较小者。它只能**收紧**，永远不会突破模型上限或网关上限 `131072`；越界值由配置校验拒绝。输入接受 `64K` 这样的简写。
+- **`0`**：请求中**不发送** `max_tokens` 字段，把单轮输出规模交回平台自行限制——这是「长回答写到一半被切断」的解法，因为只要字段在，无论填多大都会在某个点被切。
+
+`0` 只在**接受缺省该字段**的两条传输上生效：CLI（`/alpha/generate`）与 OpenAI（`/provider/v1/chat/completions`）。Claude 走的 Anthropic Messages 端点**必填**该字段，缺了会被上游直接拒绝（`Invalid input: expected number, received undefined at max_tokens`），所以那条链路仍按推导值发送，填 `0` 对 Claude 无效。会话标题这类由宿主明确限定预算的辅助调用（会话标题固定 64 词元）同样优先于此设置，不会被 `0` 解除约束。
+
+留空表示**清除**该配置（回到推导默认），不是写入 0。
+
 ### 连续图片导致的缓存回退
 
 在 CLI 传输（`/alpha/generate`）上，即使此前所有请求消息逐字节一致，新图片也可能让服务端报告的缓存命中量退回第一张历史图片处。可在「高级设置」打开「已看过的图片不再重复发送」（`offloadSeenImagesForCache`）：同一模型看过图片并回复后，插件通过 dsh 持久的 `image/offload` 事件把旧图替换成稳定文字占位；当前新图仍会送给模型，后续文本更容易保持缓存。**默认关闭**，因为模型如需重新查看已 offload 的图片，必须重新读取原文件或由用户再次附加。这是费用缓解方案，未修复 Command Code 服务端的多模态缓存行为。[实测证据与限制](docs/issue-64-cache-review.md)。
@@ -215,10 +241,10 @@ llm-commandcode:
 
 当你的 dsh 部署加载了 web 能力（`@deepseek-ai/dsh-web` + `@deepseek-ai/dsh-tool-web`）时，模型所用的 `web_search` 工具会由本插件的 `commandcode` 搜索 provider 承载——它用**与聊天相同的 API key 与 base URL** 调用 Command Code Provider API 的 `/alpha/web-search` 端点。你无需另外配置搜索 key、端点或模型。
 
-**默认开启。** 插件的 **设置 → Command Code** 页里有一个「用 Command Code 承载联网搜索」开关（`webSearch`，默认开）。开启时插件会自动把 `commandcode` 选为当前搜索后端；关闭则把选择权交还给之前的后端（比如 modsearch 等其他搜索插件可继续工作——不会被强制回退到 dsh 自带的 DeepSeek 搜索）。该开关在**下一次搜索时生效**，无需重启。
+**默认开启。** 插件的 **设置 → Command Code** 页里有一个「用 Command Code 承载联网搜索」开关（`webSearch`，默认开）。开启时插件会自动把 `commandcode` 选为当前搜索后端；关闭则把选择权交还给之前的后端（比如 modsearch 等其他搜索插件可继续工作——不会被强制回退到 dsh 自带的 DeepSeek 搜索）。该开关在**下一次搜索时生效**，无需重启；在 dsh 0.2.1-rc.2 上它走官方易变设置写入路径，改动原地提交进运行中的 `web` 条目，而不是重挂载该条目。**若官方「网页搜索」设置里已显式选择其他后端，本开关不生效**——那个显式选择优先。
 
 - 该 provider 仅在 web 服务存在时以 `commandcode` 注册进 `ctx.web`；没有它，本插件仍是纯聊天插件。
-- 开关通过启动时与每次设置变更时在 web 接缝里选中 `commandcode` 来实现，同时记住被顶掉的后端；关闭开关（或卸载插件）时会恢复那个后端。若你想更稳妥地固定，可设置 `searchProvider: commandcode`（或 `$DSH_WEB_SEARCH_PROVIDER=commandcode`）；即使本插件的运行时选中不可用，该配置仍然生效。
+- 开关通过引擎的易变设置写入路径选中 `commandcode`（写的就是官方「Web 搜索」卡片里「启用新版 Web 搜索 API」开关所用的同一个 `web.searchProvider` 字段，该开关还会一并写 `fetchProvider`）。插件**尊重用户层已有的显式选择**：当「网页搜索」设置已 pin 其他后端时，它让 `commandcode` 保持已注册但未被选中，并把这一状态报出来（开关的提示文案，外加一行宿主日志），而不是覆盖对方；只有在没人 pin 该字段时才接管，并记住被顶掉的后端，在关闭开关或卸载插件时恢复。若你想更稳妥地固定，可设置 `searchProvider: commandcode`（或 `$DSH_WEB_SEARCH_PROVIDER=commandcode`）；即使运行时选择无法提交，该配置仍然生效。
 - dsh 工具的 `numResults` 会被收敛到 Command Code 的取值范围（1–10，默认 5）；结果映射为 dsh 的 `WebSearchSource` 结构（`url`/`title`/`snippet`）。
 
 > 这里直接使用 Command Code Provider API（与官方 CLI 内置的 `web_search` 相同），因此与 DeepSeek 原生搜索后端不同。