企业官网建设流程全解析

Codewhale TUI 设置面板与 MCP 恢复通道：让每一行都指明"下一步命令"

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

本文基于 Codewhale 仓库中的交接文档 GROK_TUI_SETTINGS_HANDOFF.md，完整还原 2026-08-27 这条grok/v0912-tui-settings-mcp-20260827工作线：设置面板（F2//settings）分类页签支持鼠标点击、Settings → Advanced → MCP 从"只有路径的墙"变成带明确下一步命令的行动行、Extensions 面板为每个 MCP 服务器计算恢复动作（Connect / Reconnect / Re-auth / Enable / Diagnose）。读完后你将掌握 Codewhale TUI 中"恢复文案必须指向真实存在的命令"这一设计约束，以及McpRecoveryKind判定逻辑的源码级实现，可据此在终端里自助排障 MCP 与插件问题。

分支基线与 PR #5643 的重叠说明

这条交接线的工作面信息记录在 GROK_TUI_SETTINGS_HANDOFF.md 中：

• 基线：全新拉取的origin/main，提交a96ea6cb09cc464ea2e88f251c538c239d1fe9ad；
• 产品提交：8e15e51d43433f5e2e924611aed21ba4fa5b6709，标题为feat(tui): make settings MCP recovery first-class and clickable；
• 该线没有push、PR、merge、release 或部署，也没有安装或覆盖本机codewhale二进制；
• 生效契约是 AGENTS.md 风格的交接约束与 docs/SETTINGS_PICKER_FRAMEWORK.md、docs/MCP.md 两份文档。

文档特别指出：当时开放的 PR #5643（分支codex/v0912-tui-polish-20260827，92ef9aa4d）已经包含streamable_http.rs里的 MCP 登录文案修复和 welcome-shine 时序修复，但不在origin/main上。本线刻意不复制 5643 的动画/启动菜单工作，只修复/mcp auth恢复句并深化设置/插件管理。若两者都合入，streamable_http.rs的改动会有一处极小的重叠——双方都把/mcp auth替换为/mcp login，属于平凡冲突。

用户旅程一：设置面板页签可以鼠标点击

F2或/settings打开的设置面板，五个分类页签General / Models / Permissions / Display / Advanced现在有鼠标命中区（hitbox），单击即切换页签；列表行仍保留"先选中、再激活"（select-then-activate）的既有模式，与 provider/model 选择器一致。

从源码结构看，设置视图位于 crates/tui/src/tui/views/mod.rs，其中的测试config_view_mouse_click_selects_row验证了点击命中行的行为（crates/tui/src/config.rs第 1791 行附近的注释说明，这类 hitbox 依赖 WezTerm、Alacritty、较新的 gnome-terminal/konsole 等终端对鼠标事件的支持，参见 crates/tui/src/config.rs）。

用户旅程二：Settings → Advanced → MCP 变成"行动行"

原来 Advanced 下的 MCP 区域只是展示配置路径。改造后它呈现安静的行动行，每行都带一个明确的下一命令：

按 Enter（或对已选中的行动行第二次点击）即执行该命令。相关实现与测试（config_view_mcp_action_rows_run_existing_commands等）位于 crates/tui/src/tui/views/mod.rs。

核心机制：McpRecoveryKind 与 mcp_recovery_kind 判定

这是本线最重要的设计：每个 MCP 服务器的恢复文案必须指向真实存在的斜杠命令。crates/tui/src/mcp.rs 中的枚举注释直白地写着：

Commands named here exist:/mcp login,/mcp reload,/mcp validate,/mcp enable. There is no/mcp auth.

pub enum McpRecoveryKind { Enable, Connect, Reconnect, Reauth, Diagnose, }

每种类型通过slash_command(name)映射到命令，并携带本地化文案键（MessageId::ExtensionsActionEnable等，见 crates/tui/src/localization.rs）：

判定函数 mcp_recovery_kind 的完整决策链（按优先级）：

1. !enabled→Enable；
2. 有错误，且 error_text_looks_auth_required 文本分类器判定为鉴权类错误（401/unauthorized 等）→Reauth；
3. 有其他错误 →Diagnose；
4. 尚未 inspected（连接从未被检查）→Connect；
5. 已连接 →Diagnose（健康服务器也给一个明确的诊断入口）；
6. 支持 OAuth（mcp_server_oauth_capable：有url且有oauth配置、非空scopes或oauth_resource）→Reauth；
7. 兜底 →Reconnect。

同一模块还提供两个辅助约束，值得注意：

• mcp_name_is_command_safe：只有 ASCII 字母数字加-_.的服务器名才能安全拼进命令，防止注入式参数；
• mcp_startup_warning：会话启动时的告警行统一"点名服务器、点名故障、给一条命令"，例如The github MCP server requires OAuth reauthentication. Run \/mcp login github`.`

用户旅程三：Extensions 面板的 MCP 恢复行

Extensions → MCP（crates/tui/src/tui/views/extensions.rs）里每个服务器行按状态映射到真实命令：

• disabled →/mcp enable <name>
• not inspected →/mcp reload（Connect）
• disconnected →/mcp reload（Reconnect）
• 401 / unauthorized / 支持 OAuth 但会话过期 →/mcp login <name>
• 其他错误或健康已连接 →/mcp validate（Diagnose）

行动标签走本地化键（如tr(app.ui_locale, MessageId::ExtensionsActionEnable)），15 个语言包同步补齐了新键。

插件问题同样可诊断：注册表诊断结果（manifest-invalid、duplicate-root、name-conflict）出现在 Problems 分组中；带错误的插件运行/plugin validate <name>而不是静默的 Inspect。

/mcp管理器 pager：逐行给出 next action

/mcp管理器（crates/tui/src/tui/mcp_routing.rs）不再是命令散文墙：

• 每个服务器行标注下一步，例如next: Re-auth /mcp login github（测试manager_text_names_login_for_stale_oauth验证了这一点）；
• 页脚固定为Next: Connect /mcp reload · Diagnose /mcp validate，见 crates/tui/src/tui/mcp_routing.rs。

测试mcp_item_action_for覆盖了各状态到命令的映射，/mcp login命令本身的参数解析（Usage: /mcp login <name> [--scope scope]）位于 crates/tui/src/commands/groups/utility/mcp.rs。

Streamable HTTP 的过期 OAuth 恢复文案

crates/tui/src/mcp/streamable_http.rs 中与 stdio OAuth 路径共享 crates/tui/src/mcp/oauth.rs 的辅助函数，保证文案一致：

• 会话过期时提示/mcp login <name>（CLI 侧仍为codewhale mcp login <name>），例如Re-authorize this server (/mcp login <name>) to continue.；
• 文本分类器同时识别旧文案（/mcp auth）与新文案（/mcp login）的变体，测试断言提示语包含codewhale mcp login nordic-mcp这类具体命令；
• 仅 Bearer token 的会话不指向登录命令，仍提示检查已配置的 token——避免让用户对一个不支持 OAuth 的服务器执行/mcp login。

用户旅程七：Hunyuan / Hy 模型选择

这条线还顺手解决了模型选择中"找得到 Hunyuan"的问题。约束很克制：

• 没有原生的腾讯 HunyuanApiProvider，models.dev 捆绑目录里也没有对应行；
• 但 OpenRouter 上公开的tencent/hy3-preview已存在，于是搜索/规范化别名加入hy3、hunyuan、tencent-hunyuan、hunyuan-hy3，全部指向 OpenRouter 的tencent/hy3-preview；
• 不发明 hy4——在公开的模型 id 存在之前不添加。

别名收敛逻辑可从 crates/config/src/lib.rs 看到：

| "hy3-preview" | "tencent-hy3-preview" | "hy3" | "hunyuan" | "tencent-hunyuan" | "hunyuan-hy3" => Some(OPENROUTER_TENCENT_HY3_PREVIEW_MODEL),

对应改动还涉及 crates/tui/src/config.rs、crates/config/src/lib.rs、crates/agent/src/lib.rs 三处别名表（仅 hy3）。

测试与验证范围

交接文档给出的聚焦测试命令（通过scripts/dev-cache.sh使用隔离构建目录）：

cargo nextest run -p codewhale-tui --lib --locked -E 'test(/mcp_recovery_kind|tui_reauth_hints|manager_text_names_login|config_view_tabs_are_clickable|config_view_mcp_action_rows|openrouter_hunyuan|mcp_item_action_for|message_id_list_english|shipped_complete_packs_have_raw|settings_registry_types_every|config_view_includes_expected_editable|config_view_can_edit_filtered|config_view_mouse_click_selects|auth_required_login_hint_names|manager_text_shows_failed/)'

结果16 passed，11198 skipped；另外通过了cargo fmt --all -- --check和git diff --check。这些测试散布在 crates/tui/src/mcp/tests.rs、crates/tui/src/tui/mcp_routing.rs 等与模块同旁的测试中，命名本身（mcp_recovery_kind、tui_reauth_hints、manager_text_names_login）就是可检索的行为契约。

明确未跑的项：完整的codewhale-tui --lib套件、clippy-D warnings、多宽度下的实机 TUI/PTY、真实 MCP OAuth 流程、真实 Hunyuan/OpenRouter 调用（不为省 provider 费用而调用）。

已知边界与最安全的集成步骤

交接文档的 "What remains" 一节同样重要，定义了这条线的边界：

• welcome shine 与 launch-menu 的回归仍在main上，由 PR #5643 负责修复，本线没有重复；
• /mcp管理器仍是pager 而非可点击 modal：恢复动作在每行被点名，但点击 pager 文本不会执行命令；
• 设置行动行仍是 select-then-activate，不是单击即运行；页签则是单击；
• 没有原生 Hunyuan provider 适配器——若腾讯发布独立于 OpenRoutertencent/hy3-preview的公开 API，那是后续的 provider 线；
• 插件 Problems 行始终运行全局/plugin validate，尚未深链到具体诊断路径的专用 inspector；
• 本地化包已补齐新键，但聚焦测试只用英语外加完整性平价门禁。

最安全的集成步骤：审阅本分支上的8e15e51d4；不要压在 5643 的 welcome-shine 文件上合并；若 5643 先合入，则对本分支 rebase，预期只有streamable_http.rs登录提示一处小重叠；随后在约 80 列和 40 列宽度下做 PTY 检查，验证设置页签与一条 MCP 401 行的渲染。

小结

这条交接线展示了 Codewhale TUI 的一个可迁移的工程模式：UI 中的每一条恢复提示都必须对应一个已注册的斜杠命令，通过McpRecoveryKind这样的封闭枚举把"状态 → 命令"映射收敛到一处，配合文本分类器处理 401/过期会话，并用与模块同旁的聚焦测试固化行为。对终端编码代理而言，这比任何装饰性动画都更接近"可用"的定义——用户看到next: Re-auth /mcp login github时，复制即得解法。

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale