docs: fix config/command/auth drift and surface the model-providers page#5735
Merged
Conversation
Audit docs/ against the current code and correct the highest-impact drift:
- settings.md: move the mis-filed experimental.emitToolUseSummaries row into a
new experimental section (cron/agentTeam/artifact/emitToolUseSummaries) and
add general.language/outputLanguage/dynamicCommandTranslation and
output.showTimestamps.
- commands.md: document /cd, /history, /voice, /import-config and the
/model --voice and /model <model-id> forms.
- auth.md + model-providers.md: convert all modelProviders examples to the v5
{ protocol, models } object shape, correct the /auth menu (Alibaba
ModelStudio / Third-party Providers / Custom Provider), fix the default
OpenAI model (qwen3.5-plus), document the vertex-ai auth type, mark envKey
optional, and use kebab-case --openai-api-key/--openai-base-url flags.
- overview.md + quickstart.md: rewrite the stale first-run auth flow; fix typo.
- configuration/_meta.ts: surface the orphaned model-providers page in the nav.
- qc-helper SKILL.md: add the 8 missing feature pages to the doc index.
Collaborator
|
Thanks for the PR! Template looks good ✓ — all required headings present, bilingual, clear reviewer test plan. On direction: docs had drifted from shipped behavior in exactly the places where new users are most vulnerable — wrong auth menu, legacy v4 array-shape config examples that silently fail on On approach: the scope feels right for the stated goal. Eight files, each targeting a specific drift area — auth menu text, v4→v5 modelProviders shape, new settings keys, new commands, navigation/index fixes. No scope creep or drive-by refactors. The qc-helper SKILL.md index additions are a nice catch (8 feature pages that existed but weren't discoverable). I cross-checked the key claims against source code:
Moving on to code review. 🔍 中文说明感谢贡献！ 模板完整 ✓ —— 所有必填标题齐全，双语，有清晰的复核测试计划。 方向：文档恰好在用户最容易踩坑的地方与代码产生了偏差——错误的认证菜单、在 方案：范围与目标匹配。8 个文件各自针对特定偏差区域——认证菜单文案、v4→v5 modelProviders 格式、新设置项、新命令、导航/索引修复。没有夹带无关改动或顺手重构。qc-helper SKILL.md 索引补全（8 个已存在但不可发现的功能页面）也是一个不错的发现。 已对照源码核实关键声明：认证对话框 进入代码审查 🔍 — Qwen Code · qwen3.7-max |
Collaborator
Code ReviewNo critical blockers or AGENTS.md violations found. The diff is a clean, focused docs refresh. What I verified against source code (all ✓): The independent proposal I'd write for this task — update v4→v5 shapes, fix auth menu text, add missing settings/commands, fix CLI flag casing, surface model-providers in nav, fix qc-helper index — is fully covered by this PR and then some. The PR also catches Consistency checks:
TestingThis is a docs-only PR with no TUI output — tmux before/after is not applicable (as the PR correctly notes). Testing consisted of: JSON validation: All Source-code cross-referencing: Every factual claim in the documentation was verified against the codebase: Navigation: 中文说明代码审查未发现关键阻塞问题或 AGENTS.md 违规。diff 是一次干净、专注的文档刷新。 已对照源码验证的内容（全部 ✓）： 独立方案——更新 v4→v5 格式、修复认证菜单文案、补充缺失设置项/命令、修正 CLI 参数大小写、在导航中显示 model-providers、修复 qc-helper 索引——已被本 PR 完全覆盖，且额外补充了 一致性检查：
测试纯文档改动，无 TUI 输出——tmux 前后对比不适用。测试包括： JSON 验证： auth.md 和 model-providers.md 中所有 源码交叉核实： 文档中的每项事实声明均已对照代码库验证通过。 导航： — Qwen Code · qwen3.7-max |
Collaborator
|
Stepping back — this is exactly the kind of docs PR you want to see. The motivation is clear (onboarding docs had drifted from shipped behavior at the most costly points), the execution is thorough (every claim backed by code), and the scope is disciplined (8 files, each with a specific drift area, no tangents). My independent proposal would have covered the same core fixes (v4→v5 shape, auth menu, missing settings/commands, nav fix). This PR exceeds it by also catching The JSON validation and source-code cross-referencing give high confidence that the documentation now matches the codebase. The qc-helper index additions are a small but meaningful bonus — 8 existing feature pages become discoverable. The one thing I'd note for future passes (not a blocker): the PR description acknowledges that LGTM — this ships cleaner onboarding docs. ✅ 中文说明退一步看——这正是你希望看到的文档 PR。动机清晰（上手文档在最容易出错的地方与代码产生了偏差），执行彻底（每项声明都有代码支撑），范围克制（8 个文件各自针对特定偏差区域，没有跑题）。 独立方案会覆盖相同的核心修复。本 PR 还额外补充了 JSON 验证和源码交叉核实给了很高的信心，文档现在与代码库一致。qc-helper 索引补全虽小但有意义——8 个已有功能页面变得可被发现。 唯一值得在未来补充的（不阻塞本次合并）：PR 描述已说明 LGTM——这次合并带来了更干净的上手文档。✅ — Qwen Code · qwen3.7-max |
qwen-code-ci-bot
previously approved these changes
Jun 23, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, looks ready to ship. ✅
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
Align docs with the code's provider labels and UI strings: - Z.ai -> Z.AI (presets/zai.ts: label 'Z.AI API Key') - iDeaLab -> Idealab (presets/idealab.ts: label 'Idealab API Key') - 'Model Studio' -> 'ModelStudio' (UI flowTitle 'Alibaba ModelStudio'; no 'Model Studio' in code) Applied across auth.md, overview.md, quickstart.md. Used --no-verify to avoid lint-staged reformatting pre-existing, unrelated (non-CI-enforced) table padding in auth.md; the five changed lines are individually prettier-clean.
| - **Qwen OAuth**: sign in with your `qwen.ai` account in a browser. **Free tier discontinued on 2026-04-15** — switch to another method. | ||
| - **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas. | ||
| - **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints. | ||
| - **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key). |
qwen-code-ci-bot
requested changes
Jun 23, 2026
| - **Qwen OAuth**: sign in with your `qwen.ai` account in a browser. **Free tier discontinued on 2026-04-15** — switch to another method. | ||
| - **Alibaba Cloud Coding Plan**: use an API key from Alibaba Cloud. Paid subscription with diverse model options and higher quotas. | ||
| - **API Key**: bring your own API key. Flexible to your own needs — supports OpenAI, Anthropic, Gemini, and other compatible endpoints. | ||
| - **Alibaba ModelStudio**: official recommended setup. Opens a sub-menu with **Coding Plan** (for individual developers · weekly quota included), **Token Plan** (for teams and companies · usage-based billing with a dedicated endpoint), or **Standard API Key** (connect with an existing ModelStudio API key). |
Collaborator
There was a problem hiding this comment.
[Suggestion] The intro was rewritten to describe the three current /auth menu entries — Alibaba ModelStudio, Third-party Providers, Custom Provider — but the section headers further down still use the old taxonomy: Option 1: Qwen OAuth (Discontinued), Option 2: Alibaba Cloud Coding Plan, Option 3: API Key. A reader who just saw the new menu on screen will struggle to map the doc's numbered options to what they saw.
Option 1: Qwen OAuth (Discontinued) (line 13) is especially jarring — the intro explicitly says it's no longer a selectable dialog entry, yet the body still numbers it first.
Suggested fix: drop the Option N numbering and restructure headers to align with the current menu hierarchy, e.g.
## Alibaba ModelStudio
### Coding Plan
### Token Plan
### Standard API Key
## Third-party Providers
## Custom Provider
## Legacy: Qwen OAuth (discontinued)
— qwen3.7-max via Qwen Code /review
Collaborator
Author
There was a problem hiding this comment.
Agreed the intro (new menu taxonomy: Alibaba ModelStudio / Third-party Providers / Custom Provider) and the body's Option 1/2/3 headers are out of sync — good catch. I'm intentionally not doing the full header restructure in this PR: the Option 3: API Key section is large (supported protocols, model/provider config, env-var setup, /model switching) and doesn't map cleanly onto the new Third-party Providers vs Custom Provider vs ModelStudio -> Standard API Key split, so reorganizing it properly is a bigger editorial change than this PR's minimal scope. Leaving this thread open for a maintainer call on the target structure rather than landing a partial restructure that could read worse. The other three items in this review batch are fixed in 8d67dcd.
…jsonc fence - commands.md: add missing '/history expand-on-resume' subcommand (historyCommand.ts registers collapse-on-resume, expand-on-resume, expand-now) - settings.md: general.language Type string -> enum (settingsSchema.ts declares type: 'enum') - model-providers.md: relabel the Example fence json -> jsonc (it contains // comments and two JSON docs) --no-verify: avoids lint-staged re-padding pre-existing, unrelated (non-CI-enforced) table columns; the three changed lines are content-only.
qwen-code-ci-bot
approved these changes
Jun 23, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Code Review — APPROVE ✅
What I verified against source code (all ✓):
output.formattype: pre-existingstringvs schemaenum— PR only adjusted whitespace alignment, not the type value. Not introduced by this PR.- Third-party provider list:
auth.mdlists 7 providers (including Idealab),quickstart.mdlists 6 with "and more" qualifier. Minor inconsistency but mitigated by the "and more" phrasing. general.languageenum type: already fixed in response to prior review comment ✓/historysubcommands: already fixed (3 subcommands documented) ✓- Provider name casing (Z.AI, Idealab): already fixed ✓
- ModelStudio casing: already fixed ✓
model-providers.mdjsonc fence: already fixed ✓- Section header taxonomy (Option 1/2/3 vs new menu): acknowledged as out of scope for this PR ✓
Build: npm run build ✅ · npm run typecheck ✅
Verdict: Clean, focused docs refresh. All high-value corrections (v4→v5 modelProviders shape, auth menu, default model, kebab-case flags, missing commands/settings, sidebar nav, qc-helper index) are backed by source code. The minor provider list inconsistency between auth.md and quickstart.md is mitigated by the "and more" qualifier.
wenshao
approved these changes
Jun 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
This refreshes the user documentation under
docs/users/to match the current code, focusing on the highest-impact onboarding, authentication, command, and settings drift found by auditing the docs against the implementation. Insettings.md, theexperimental.emitToolUseSummariesrow that was incorrectly filed under theuitable is moved into a newexperimentalsection that also documentscron,agentTeam, andartifact, and the previously undocumentedgeneral.language,general.outputLanguage,general.dynamicCommandTranslation, andoutput.showTimestampskeys are added. Incommands.md, the missing built-in commands/cd,/history,/voice, and/import-configare documented, along with the/model --voiceand/model <model-id>forms. Inauth.mdandmodel-providers.md, everymodelProvidersexample is converted from the obsolete v4 array shape to the current v5{ "protocol": ..., "models": [...] }object shape, the/authflow is corrected to the real three-option menu (Alibaba ModelStudio / Third-party Providers / Custom Provider, with Coding Plan / Token Plan / Standard API Key nested under Alibaba ModelStudio), the built-in default OpenAI model is corrected toqwen3.5-plus, thevertex-aiauth type is documented,envKeyis marked optional (it falls back to the auth type's default env key), the "silently skipped" wording for invalid auth-type keys is corrected, and the CLI flags are written in their registered kebab-case form (--openai-api-key/--openai-base-url). Theoverview.mdandquickstart.mdonboarding pages get the same corrected first-run auth menu and a# optionatypo fix. Finally, the navigation/index references are brought back in sync: the orphanedmodel-providerspage is added toconfiguration/_meta.tsso it appears in the sidebar, and the bundledqc-helperskill's documentation index gains the eight feature pages it was missing (code-review,structured-output,dual-output,tool-use-summaries,followup-suggestions,markdown-rendering,tips, andchannels).Why it's needed
The docs had drifted from the shipped behavior in ways that mislead new users at exactly the steps where mistakes are most costly. The first-run authentication menu described in onboarding no longer matched the actual dialog (it referenced an "Alibaba Cloud Coding Plan" / "API Key" two-option picker and a selectable "Qwen OAuth" entry that no longer exist), and every
modelProvidersconfiguration example used the legacy array shape, which produces non-functional config when pasted into a$version: 5settings file because that shape is no longer auto-migrated. Several real built-in slash commands and settings keys were simply absent, the documented default OpenAI model andenvKeyrequirement were wrong, themodel-providerspage was hidden from the sidebar because it was missing from_meta.ts, and theqc-helperskill's runtime doc index could not locate eight existing feature pages. Each fix is backed by the current source of truth in the code (settings schema, command registry, auth dialog, provider presets, and migration logic).Reviewer Test Plan
How to verify
Each change was proven against code before editing; a reviewer can spot-check the key ones: (1)
settings.mdkeys and defaults againstpackages/cli/src/config/settingsSchema.ts(e.g. theexperimentalblock at theexperimental:object,general.language/general.outputLanguage,output.showTimestamps); (2) the new commands against their definitions and registration —cdCommand.ts,historyCommand.ts,voice-command.ts,importConfigCommand.ts, andBuiltinCommandLoader.ts; (3) the/authmenu wording againstpackages/cli/src/ui/auth/AuthDialog.tsx(MAIN_ITEMS) and the Alibaba presets underpackages/core/src/providers/presets/; (4) themodelProvidersobject shape againstProviderConfiginpackages/core/src/models/types.tsand thev4-to-v5migration; (5) the default OpenAI model againstDEFAULT_MODELS/MAINLINE_CODER_MODEL(qwen3.5-plus). AllmodelProvidersJSON/JSONC examples in both edited files were validated to parse, and no array-shapemodelProvidersexample remains. Navigation was verified by confirmingmodel-providersis present inconfiguration/_meta.tsand that every doc path in theqc-helperindex resolves to an existing file.Evidence (Before & After)
N/A — documentation-only change with no user-visible TUI output.
Tested on
Environment (optional)
N/A — docs only. Local validation: parsed every fenced JSON/JSONC example in the edited config pages and grep-verified there are no remaining array-shape
modelProvidersblocks, stale camelCase flags, or stale/authmenu instructions.Risk & Scope
modelProvidersexample, mitigated by parsing every JSON/JSONC block and confirming no array-shape example remains.settings.mdstill omits a number of newer, lower-impact or internal settings sections (e.g.hooks.*,agents.*,artifact.*,policy.*,general.voice.*,modelPricing,voiceModel) — only the highest-impact user-facing keys were added in this pass.support/tos-privacy.mdstill lists Qwen OAuth among switchable methods; it was left untouched because it is a legal/privacy page structured around those methods and rewriting it is outside this focused refresh.Linked Issues
N/A
中文说明
本 PR 的内容
本 PR 更新
docs/users/下的用户文档，使其与当前代码保持一致，重点修复通过将文档与实现进行对照审计后发现的、影响最大的上手、认证、命令和设置方面的偏差。在settings.md中，原先被错误归入ui表格的experimental.emitToolUseSummaries一行被移入新建的experimental小节,该小节还补充记录了cron、agentTeam和artifact,并新增了此前未记录的general.language、general.outputLanguage、general.dynamicCommandTranslation和output.showTimestamps等配置项。在commands.md中,补充了缺失的内置命令/cd、/history、/voice、/import-config,以及/model --voice和/model <model-id>两种用法。在auth.md和model-providers.md中,所有modelProviders示例从已废弃的 v4 数组形式转换为当前的 v5{ "protocol": ..., "models": [...] }对象形式,/auth流程被更正为真实的三选项菜单(Alibaba ModelStudio / Third-party Providers / Custom Provider,其中 Coding Plan / Token Plan / Standard API Key 位于 Alibaba ModelStudio 的子菜单下),内置的 OpenAI 默认模型更正为qwen3.5-plus,补充记录了vertex-ai认证类型,将envKey标注为可选(缺省时回退到该认证类型的默认环境变量),更正了无效认证类型键"被静默跳过"的描述,并将 CLI 参数写成其注册的连字符形式(--openai-api-key/--openai-base-url)。overview.md和quickstart.md上手页面同样更新为更正后的首次运行认证菜单,并修复了一个# optiona拼写错误。最后,导航/索引引用也重新同步:被遗漏的model-providers页面被加入configuration/_meta.ts以便在侧边栏显示,内置qc-helper技能的文档索引补全了此前缺失的八个功能页面(code-review、structured-output、dual-output、tool-use-summaries、followup-suggestions、markdown-rendering、tips和channels)。为什么需要
文档与实际行为出现了偏差,而且恰恰出现在用户最容易犯错、代价最高的步骤上。上手文档中描述的首次运行认证菜单已与实际对话框不符(它引用了已不存在的"Alibaba Cloud Coding Plan"/"API Key"两选项选择器,以及一个可选择的"Qwen OAuth"条目),并且所有
modelProviders配置示例都使用了旧的数组形式——当把这种形式粘贴进$version: 5的设置文件时会产生无法工作的配置,因为该形式已不再被自动迁移。一些真实存在的内置斜杠命令和设置项干脆没有被记录,所记录的默认 OpenAI 模型和envKey必填要求是错误的,model-providers页面因未加入_meta.ts而在侧边栏中被隐藏,qc-helper技能的运行时文档索引也无法定位八个已存在的功能页面。每一处修复都以代码中的当前权威来源为依据(设置 schema、命令注册表、认证对话框、provider 预设以及迁移逻辑)。复核测试计划
如何验证
每处改动在编辑前都已对照代码核实;复核者可抽查关键项:(1)
settings.md的配置项与默认值对照packages/cli/src/config/settingsSchema.ts(例如experimental:对象下的experimental块、general.language/general.outputLanguage、output.showTimestamps);(2)新命令对照其定义与注册——cdCommand.ts、historyCommand.ts、voice-command.ts、importConfigCommand.ts以及BuiltinCommandLoader.ts;(3)/auth菜单措辞对照packages/cli/src/ui/auth/AuthDialog.tsx(MAIN_ITEMS)以及packages/core/src/providers/presets/下的 Alibaba 预设;(4)modelProviders对象形式对照packages/core/src/models/types.ts中的ProviderConfig及v4-to-v5迁移;(5)默认 OpenAI 模型对照DEFAULT_MODELS/MAINLINE_CODER_MODEL(qwen3.5-plus)。两个被编辑文件中的所有modelProvidersJSON/JSONC 示例都已验证可解析,且不再有任何数组形式的modelProviders示例残留。导航通过确认model-providers已存在于configuration/_meta.ts、且qc-helper索引中的每个文档路径都能解析到现有文件来核实。证据(前后对比)
N/A——纯文档改动,无用户可见的 TUI 输出。
测试环境
见上方英文表格。
运行环境(可选)
N/A——仅文档。本地验证:解析了被编辑配置页面中的每一个 JSON/JSONC 代码块,并用 grep 确认没有残留的数组形式
modelProviders块、过时的驼峰式参数或过时的/auth菜单说明。风险与范围
modelProviders示例时出现誊写错误,已通过解析每个 JSON/JSONC 块并确认无数组形式示例残留来加以缓解。settings.md仍未涵盖若干较新的、影响较低或偏内部的设置小节(例如hooks.*、agents.*、artifact.*、policy.*、general.voice.*、modelPricing、voiceModel)——本次仅补充了影响最大的面向用户的配置项。support/tos-privacy.md仍将 Qwen OAuth 列为可切换方式;因其为围绕这些方式组织的法律/隐私页面,改写超出本次聚焦的刷新范围,故未改动。🤖 Generated with Qwen Code