docs: document compaction and image model selection

[DragonnZhang]

What this PR does

Documents the existing auxiliary model selectors for chat compression and built-in image generation. The command reference now shows how to select these models and clear the compression override, while the settings reference records their defaults, fallback or availability behavior, and image-provider requirements.

Why it's needed

Both selectors and settings are already shipped and exposed by the settings schema, but the user documentation only listed the fast, voice, and vision model paths. Users could not discover how to configure a dedicated compression model or why image generation remains unavailable without a valid image-only provider route.

Reviewer Test Plan

How to verify

Confirm that the model command reference lists the compression and image selectors with valid examples. Confirm that the settings reference states that an empty compression override falls back to the main model and that image generation requires an image-only provider with a base URL and credential environment key. The documented behavior is covered by the focused model-command and configuration tests.

Evidence (Before & After)

N/A — documentation-only change.

Tested on

OS	Status
🍏 macOS	✅ tested
🪟 Windows	⚠️ not tested
🐧 Linux	⚠️ not tested

Environment (optional)

Local macOS 27.0 worktree with Node.js 24.18.0 and npm 11.16.0. Prettier checks, focused unit tests, the full build, and the full typecheck completed successfully.

Risk & Scope

• Main risk or tradeoff: Documentation could drift if auxiliary model configuration changes later; the current wording was checked against the command implementation, settings schema, configuration resolution, and tests.
• Not validated / out of scope: Runtime behavior was not changed. Windows and Linux documentation rendering were not tested.
• Breaking changes / migration notes: None.

Linked Issues

N/A.

中文说明

本 PR 的内容

记录现有的聊天压缩与内置图像生成辅助模型选择方式。命令参考现在说明如何选择这两类模型以及如何清除压缩模型覆盖；设置参考同时记录其默认值、回退或可用性行为，以及图像提供方必须满足的条件。

为什么需要此改动

这两种选择方式及对应设置已经发布，并由设置 schema 对外公开，但用户文档此前只列出了快速、语音和视觉模型路径。用户无法从文档中发现如何配置专用压缩模型，也不清楚缺少有效的纯图像提供方路由时图像生成为何不可用。

Reviewer 测试计划

验证方式

确认模型命令参考列出了压缩和图像模型选择方式，并给出有效示例。确认设置参考说明：压缩模型覆盖为空时会回退到主模型；图像生成需要一个包含基础 URL 和凭据环境变量键的纯图像提供方。相关文档行为已由聚焦的模型命令与配置单元测试覆盖。

证据（改动前后）

N/A——仅文档改动。

已测试平台

系统	状态
🍏 macOS	✅ 已测试
🪟 Windows	⚠️ 未测试
🐧 Linux	⚠️ 未测试

环境（可选）

本地 macOS 27.0 worktree，Node.js 24.18.0，npm 11.16.0。Prettier 检查、聚焦单元测试、完整构建和完整类型检查均成功完成。

风险与范围

• 主要风险或权衡：如果辅助模型配置以后发生变化，文档可能再次漂移；当前措辞已对照命令实现、设置 schema、配置解析和测试核验。
• 未验证或范围外内容：未修改运行时行为；未测试 Windows 和 Linux 上的文档渲染。
• 破坏性变更或迁移说明：无。

关联 Issue

N/A。

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓ — all required sections present, including the bilingual body.

Problem: this is a genuine documentation gap, not a theoretical one. The compactionModel and imageModel settings already ship and are exposed by the settings schema, but the user docs only covered the fast/voice/vision model paths — so there was no way to discover how to configure a dedicated compression model or why image generation stays unavailable without a valid image-only route. Observed gap, correctly scoped.

Direction: aligned. This documents already-shipped behavior with no runtime change, which is squarely in scope. It touches model selection only descriptively (no logic changes), so no escalation needed.

Size: not applicable — docs-only, 2 files under docs/, 14 additions / 0 deletions. No core paths touched.

Approach: the scope feels right. Two focused additions — a compactionModel and an imageModel entry in the settings reference (placed alongside the existing visionModel row, matching its table format), plus two rows in the /model command reference. Every edit serves the stated goal; no drive-by changes or scope creep.

Risk: no elevated risk signals — neither changed file matches the high-risk paths from the revert-history analysis.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓ —— 所有必需章节齐全，包含中英双语正文。

问题：这是一个真实的文档缺口，而非理论性问题。compactionModel 和 imageModel 设置已经发布，并由 settings schema 对外公开，但用户文档此前只覆盖了 fast/voice/vision 模型路径——用户无从发现如何配置专用压缩模型，也不清楚缺少有效的纯图像路由时图像生成为何不可用。属于已观测到的缺口，范围恰当。

方向：对齐。本 PR 仅描述已发布的行为，不改动运行时，完全在范围内。它只以描述方式涉及模型选择（不改逻辑），无需升级。

规模：不适用 —— 纯文档，docs/ 下 2 个文件，14 行新增 / 0 行删除，未触及核心路径。

方案：范围合理。两处聚焦的新增——设置参考中新增 compactionModel 与 imageModel 条目（紧跟现有 visionModel 行，沿用其表格格式），以及 /model 命令参考中新增两行。每处改动都服务于既定目标，无顺手改动或范围蔓延。

风险：无升级风险信号 —— 两个改动文件均未命中基于 revert 历史分析的高风险路径。

进入代码审查 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

For a docs PR the review is really an accuracy check, so I read the PR title + motivation and formed my own baseline first: I'd add a compactionModel and an imageModel row to the settings reference (matching the existing visionModel/fastModel table format) and two rows to the /model command reference. That's exactly what this PR does — no simpler path missed.

I then verified each documented claim against the shipped code:

• compactionModel — default "" matches the schema (settingsSchema.ts); "leave empty to fall back to the main model" matches Config.getCompactionModel(), which returns the main model when no override is set; "set or cleared via /model --compaction" matches the command handler, which accepts both --compaction <model-id> and --compaction clear.
• imageModel — default "" matches the schema; the "must have imageOnly: true, baseUrl, and envKey in modelProviders" requirement matches Config.resolveImageGenerationModel(), which requires imageOnly === true, a non-empty envKey, and a non-empty base URL (the modelProviders baseUrl surfaces internally as registryBaseUrl); "leave empty to keep the tool unavailable" matches getImageGenerationConfig() returning undefined when unset. The tool really is named image_gen (ToolNames.IMAGE_GEN).
• Command reference — /model --compaction <model-id>, /model --compaction clear, and /model --image <model-id> all correspond to real handler branches.

The new entries sit alongside the existing visionModel row and reuse its table structure, so they read as a natural extension rather than a bolt-on. No correctness issues, no convention violations, no scope creep. The wording is actually a touch more precise than the in-product schema description (it spells out the baseUrl/envKey requirement), which is a plus.

Nothing blocks this.

Test evidence

This is an unattended CI run, so I'm quoting the PR's own CI checks for the reviewed commit rather than running anything. Precheck passed; the load-bearing unit suite (Test (ubuntu-latest, Node 22.x)) is still in flight, and the platform matrix + integration tests are skipped — consistent with a change that touches no runtime code. No failures observed. The table below is updated in place by the finalize workflow once CI settles.

Final CI results for 138f266 (auto-updated by the triage finalize job after CI completed):

Check	Conclusion
Classify PR	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	✅ success

_{One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。}

No sandboxed-lane line here: this is a docs-only change with no behavioural claim to settle — the unit suite the docs reference (model-command and configuration tests) is what CI is running, and there is no runtime behaviour for /verify or /tmux to pin.

中文说明

代码审查

对文档 PR 而言，审查实质上是准确性核验。我先只看标题与动机，形成自己的基线：我会在设置参考中新增 compactionModel 与 imageModel 两行（沿用现有 visionModel/fastModel 的表格格式），并在 /model 命令参考中新增两行。本 PR 正是这么做的——没有遗漏更简路径。

随后我逐条对照已发布代码核验了文档声明：

• compactionModel —— 默认值 "" 与 schema 一致（settingsSchema.ts）；"留空则回退到主模型"与 Config.getCompactionModel() 一致（未设置覆盖时返回主模型）；"可通过 /model --compaction 设置或清除"与命令处理器一致（同时支持 --compaction <model-id> 与 --compaction clear）。
• imageModel —— 默认值 "" 与 schema 一致；"必须在 modelProviders 中具有 imageOnly: true、baseUrl 和 envKey"与 Config.resolveImageGenerationModel() 一致（要求 imageOnly === true、非空 envKey、非空 base URL——modelProviders 的 baseUrl 在内部表现为 registryBaseUrl）；"留空则保持工具不可用"与 getImageGenerationConfig() 在未设置时返回 undefined 一致。工具确实名为 image_gen（ToolNames.IMAGE_GEN）。
• 命令参考 —— /model --compaction <model-id>、/model --compaction clear、/model --image <model-id> 均对应真实的处理分支。

新条目紧邻现有 visionModel 行并复用其表格结构，读起来是自然延伸而非生硬拼接。无正确性问题、无规范违规、无范围蔓延。措辞实际上比产品内 schema 描述更精确（明确写出了 baseUrl/envKey 要求），是加分项。

无阻塞项。

测试证据

这是无人值守的 CI 运行，因此我引用该 PR 针对被审 commit 的自身 CI 检查，而非自行运行任何代码。Precheck 已通过；承载主要验证的单元测试（Test (ubuntu-latest, Node 22.x)）仍在进行中，平台矩阵与集成测试被跳过——与本次未改动任何运行时代码一致。未观察到失败。下表会在 CI 结束后由 finalize 工作流原地更新。

无沙箱验证行：这是纯文档改动，没有需要验证的行为声明——文档所引用的单元测试（模型命令与配置测试）正是 CI 正在运行的内容，没有可供 /verify 或 /tmux 钉住的运行时行为。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — clean across every stage; the docs are accurate against the shipped code and I'd merge without hesitation.

Stepping back: this is exactly the kind of PR that's easy to underrate because it's small, but it closes a real discoverability gap. The settings and /model selectors already ship, and the docs simply didn't mention them. I checked each claim against the implementation rather than taking the description at face value — defaults, the fall-back-to-main-model behavior for compaction, the imageOnly/baseUrl/envKey route requirements for image generation, and the --compaction clear syntax all match what the code actually does. The wording is even slightly more precise than the in-product schema description.

The diff is minimal and self-consistent: two settings rows that reuse the existing visionModel table format, two command rows, nothing unrelated. If I had to maintain this in six months I'd thank the author, not curse them. No reservations.

Approval is deferred only because the unit suite is still running on the reviewed commit — approval deferred until CI lands green on 138f2661808954caad2c6df8bafc95f63224648d. The finalize workflow will post the commit-pinned approval once every check completes green, and will withhold it if anything lands red or the head moves.

中文说明

置信度：5/5 —— 各阶段均干净；文档与已发布代码一致，可以毫不犹豫地合并。

退一步看：这类 PR 因为体量小很容易被低估，但它填补了一个真实的可发现性缺口。这些设置与 /model 选择方式早已发布，只是文档没有提及。我没有照单全收 PR 的描述，而是逐条对照实现核验——默认值、压缩模型回退到主模型的行为、图像生成对 imageOnly/baseUrl/envKey 路由的要求、以及 --compaction clear 语法，都与代码实际行为一致。措辞甚至比产品内 schema 描述更精确。

diff 极简且自洽：两行设置条目复用现有 visionModel 表格格式，两行命令条目，无任何无关改动。半年后维护它我会感谢作者，而不是抱怨。无任何保留意见。

仅因被审 commit 上的单元测试仍在运行而暂缓批准——待 CI 在该 commit 上全绿后批准。finalize 工作流会在所有检查全绿后发布钉住该 commit 的批准；若有任何检查变红或 head 移动，则会暂缓。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at 138f2661808954caad2c6df8bafc95f63224648d · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Reviewed. Suggestions are inline.

中文说明

已审查。 建议见行内评论。

— qwen3.8-max-preview via Qwen Code /review

[qwen-code-ci-bot]

LGTM, looks ready to ship — CI landed green after the review. ✅

[qwen-code-ci-bot]

Reviewed. Suggestions are inline.

中文说明

已审查。 建议见行内评论。

— qwen3.8-max-preview via Qwen Code /review

[qwen-code-ci-bot]

⚠️ Downgraded from Approve to Comment: CI still running. Reviewed.

中文说明

⚠️ 已从批准降级为评论：CI still running。 已审查。

— qwen3.8-max-preview via Qwen Code /review

[qwen-code-review-bot]

Review Summary — PR #8348

docs: document compaction and image model selection

Verdict: No blockers. Clean documentation-only change (+53/−39, 2 files).

What was verified

I cross-checked every factual claim in the new docs against the implementation on main:

Documented claim	Source verified
compactionModel falls back to main model when empty	config.ts — resolveCompactionModel: "Priority: compactionModel (if set) → main model" ✅
/model --compaction clear clears the override	modelCommand.ts L785–786: if (!modelName || modelName === 'clear') ✅
imageModel requires imageOnly: true	config.ts L6552: model.imageOnly === true ✅
imageModel requires HTTPS baseUrl	image-generation-service.ts L59: parsed.protocol !== 'https:' ✅
imageModel requires envKey	config.ts L6563: if (!apiKeyEnv || !configuredBaseUrl) return undefined ✅

Notes

• The commands.md diff looks large (41+/39−) but is purely column-width realignment to fit the two new /model --compaction and /model --image rows; no existing content was changed.
• New settings entries follow the same table format as the adjacent visionModel row.
• PR body is thorough (motivation, test plan, risk, bilingual summary). CI and typecheck reported green by the author.

LGTM — ship it.

[yiliang114]

@qwen-code /triage

[qwen-code-ci-bot]

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

中文 — 判定：⚠️ 未运行 · 不适用

该 PR 仅改动文档/静态资源，没有可执行的代码，沙箱验证没有验证对象。

— Qwen Code · sandboxed verification

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: observed gap — compactionModel and imageModel are already shipped in the settings schema and exposed via /model --compaction / /model --image, but the user docs only covered the fast, voice, and vision model paths. Users had no way to discover these selectors from the documentation.

Direction: aligned — documenting existing, shipped features is squarely within scope. No CHANGELOG reference needed for a docs-only gap fill.

Size: not applicable (docs only, no core paths touched).

Approach: the scope feels right. Two new settings sections in settings.md and two new rows in the commands.md table — exactly the minimal set needed. The table reformatting in commands.md is mechanical (wider column to fit the longer command names) and doesn't change any existing content.

Risk: no elevated risk signals.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已观测到的文档缺口——compactionModel 和 imageModel 已在设置 schema 中发布，并通过 /model --compaction / /model --image 暴露，但用户文档此前只覆盖了快速、语音和视觉模型路径。用户无法从文档中发现这些选择方式。

方向：对齐——为已发布的现有功能补充文档，完全在范围内。

规模：不适用（仅文档，未触及核心路径）。

方案：范围合理。settings.md 新增两个设置小节，commands.md 表格新增两行——恰好是所需的最小改动。commands.md 中的表格重排是机械性的（更宽的列以适配更长的命令名），未改变任何现有内容。

风险：无升级风险信号。

进入代码审查 🔍

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code Review

Verified every documented claim against the codebase:

• compactionModel setting — exists in settingsSchema.ts with default: '', description matches. Fallback to main model confirmed in config.ts (resolveCompactionModelSelector returns this.getModel() when empty). ✓
• imageModel setting — exists in settingsSchema.ts with default: ''. The imageOnly: true + HTTPS baseUrl + envKey requirements are enforced in resolveImageGenerationModel (config.ts line ~6552) and normalizeImageGenerationBaseUrl (image-generation-service.ts rejects non-HTTPS). ✓
• /model --compaction and /model --image flags — both registered in modelCommand.ts with correct descriptions and argument hints. The clear subcommand for --compaction is implemented (persists undefined and calls config.setCompactionModel(undefined)). ✓
• Table reformatting in commands.md — purely mechanical column-width increase to accommodate the longer command names; no content changes to existing rows. ✓

No correctness issues, no convention violations, no scope creep.

Testing

N/A — documentation-only change with no user-visible behavioral impact.

Check	Conclusion
Test (ubuntu-latest, Node 22.x)	✅ success
web-shell E2E Smoke (ubuntu-latest, Node 22.x)	✅ success
precheck-pr / precheck	✅ success
Classify PR	✅ success
label	✅ success
route	✅ success
review-pr	✅ success
authorize	✅ success
review-config	✅ success
delay-automatic-review	✅ success
Remind on force-push	✅ success

All CI checks green on the reviewed commit. No failures.

中文说明

代码审查

逐条对照代码库验证了文档中的每一项声明：

• compactionModel 设置——存在于 settingsSchema.ts，默认值为空字符串，描述一致。回退到主模型的逻辑在 config.ts 中确认（resolveCompactionModelSelector 在值为空时返回 this.getModel()）。✓
• imageModel 设置——存在于 settingsSchema.ts，默认值为空字符串。imageOnly: true + HTTPS baseUrl + envKey 的要求在 resolveImageGenerationModel（config.ts 约第 6552 行）和 normalizeImageGenerationBaseUrl（image-generation-service.ts 拒绝非 HTTPS）中强制执行。✓
• /model --compaction 和 /model --image 标志——均在 modelCommand.ts 中注册，描述和参数提示正确。--compaction 的 clear 子命令已实现（持久化 undefined 并调用 config.setCompactionModel(undefined)）。✓
• commands.md 中的表格重排——纯机械性列宽增加以适配更长的命令名；现有行内容无变化。✓

无正确性问题，无规范违反，无范围蔓延。

测试

不适用——仅文档改动，无用户可见的行为影响。

CI 全部通过，无失败。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — clean docs gap-fill, every claim verified against the implementation, CI green, nothing to second-guess.

This is exactly the kind of PR that's easy to review and easy to merge. The author identified a real documentation gap (two shipped model selectors with zero docs coverage), verified the wording against the settings schema, config resolution, and command implementation, and kept the diff to the minimum — two new settings sections and two new table rows, with only the mechanical column-width adjustment as a side effect.

I independently checked every factual claim: the compactionModel fallback semantics, the imageModel triple requirement (imageOnly, HTTPS baseUrl, envKey), the clear subcommand, and the flag registrations. All accurate. The table reformatting touches no content.

If I had to maintain this in six months, I'd thank the author — the new sections follow the exact same format as the adjacent visionModel entry, so they'll age the same way.

中文说明

置信度：5/5——干净的文档补缺，每项声明均已对照实现验证，CI 全绿，无需犹豫。

这正是那种容易审查、容易合并的 PR。作者发现了一个真实的文档缺口（两个已发布的模型选择方式完全没有文档覆盖），对照设置 schema、配置解析和命令实现核验了措辞，并将 diff 控制在最小范围——两个新设置小节和两行新表格行，唯一的副作用是机械性的列宽调整。

我独立检查了每一项事实声明：compactionModel 的回退语义、imageModel 的三重条件（imageOnly、HTTPS baseUrl、envKey）、clear 子命令、以及标志注册。全部准确。表格重排未触及任何内容。

— Qwen Code · qwen3.8-max-preview

_{Reviewed at ce6f2d2bb6fca2da539195a720496e9c361a75d6 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

Released in v0.21.4.