KimiCodeSwitch/docs/superpowers/specs/2026-07-09-kimicode-global-settings-panel-design.md

Kimi Code 全局配置面板设计

背景

Kimi Code CLI 的 ~/.kimi-code/config.toml 包含大量全局设置：[thinking]、[loop_control]、[background]、[[permission.rules]]、[[hooks]] 等。当前 Pi Switch 只暴露了 providers 和 models 的可视化编辑，其他全局配置只能通过"配置 JSON"标签页手动修改，不够便捷。

目标

1. 在 Kimi Code 选项卡的供应商编辑页面（ProviderEdit）中，"模型映射"标签页下方新增一个"全局配置"面板，用图形化控件快速编辑上述 Kimi Code 全局设置。
2. 根据模型 ID 自动为新添加/发现的模型设置默认 max_context_size，全局默认值为 256000，具体模型按可扩展的键值对表格匹配。

模型级的 max_context_size 已在模型映射表格中实现，用户仍可手动覆盖自动默认值。

设计

位置

• 组件：src/components/ProviderEdit.tsx
• 仅在 agent === "kimi_code" 时显示。
• 位于"模型映射"标签页的内容区域内，在模型映射表格和"+ 添加模型映射"按钮的下方。
• 垂直排列，超出区域高度时由页面滚动条处理。

分组与控件

面板按功能分为 5 张卡片：

卡片 1：思考模式 [thinking]

控件	字段	说明
复选框	enabled	是否默认开启思考
分段按钮	effort	思考强度：low / medium / high / max
复选框	keep	是否保留历史思考内容（"all" 或关值）

• 思考等级和保留思考内容仅在"启用思考"勾选时可用，禁用时置灰。
• "保留思考内容"未勾选时，写入 [thinking].keep = false（不能省略，否则 CLI 会回退到默认值 "all"）。
• 卡片底部小字提示："启用思考会占用更多上下文，请确保模型上下文长度和预留空间足够。"

卡片 2：循环控制 [loop_control]

控件	字段	说明
数字输入框	max_retries_per_step	单步失败后最大重试次数，默认 3
数字输入框	reserved_context_size	预留给模型输出的 token 数，单位 token

卡片 3：后台任务 [background]

控件	字段	说明
数字输入框	max_running_tasks	同时运行的最大后台任务数
复选框	keep_alive_on_exit	会话关闭时是否保留后台任务

卡片 4：权限规则 [[permission.rules]]

• 可添加/删除的规则列表，默认空列表。
• 每行包含：
  • 处置 下拉框：allow / deny / ask
  • 模式 输入框：如 Read、Bash(rm -rf*)
  • 删除 按钮
• 提供"添加常用规则"快捷入口，可一键插入：
  • allow + Read
  • deny + Bash(rm -rf*)

卡片 5：生命周期钩子 [[hooks]]

• 可添加/删除的钩子列表，默认空列表。
• 每行包含：
  • 事件 下拉框：常见事件如 PreToolUse / PostToolUse，也可手动输入其他事件
  • 匹配器 输入框：如 Bash
  • 命令 输入框：如 node ~/.kimi-code/hooks/check-bash.mjs
  • 超时 数字输入框（秒）
  • 删除 按钮

样式

• 卡片容器：bg-[#16161a] border border-[#2a2a2e] rounded-xl p-4
• 卡片间距：gap-4
• 卡片标题：text-gray-400 text-sm font-medium mb-3
• 表单项：flex items-center gap-4 flex-wrap
• 数字输入框宽度：w-32
• 禁用状态：文字 text-gray-600，按钮不可交互

字段默认值

当 raw_other 中不存在对应表时，控件按以下默认值展示：

配置块	字段	UI 默认值
[thinking]	enabled	true
[thinking]	effort	"medium"
[thinking]	keep	"all"（勾选）
[loop_control]	max_retries_per_step	3
[loop_control]	reserved_context_size	50000
[background]	max_running_tasks	空（不写入）
[background]	keep_alive_on_exit	false
[[permission.rules]]	—	空列表
[[hooks]]	—	空列表

数字输入框允许清空，表示不写入配置文件，由 Kimi Code CLI 使用其内置默认值。

数据流

• App.tsx 向 ProviderEdit 传入：
  • agent
  • rawOther（即 config.raw_other）
  • updateRawOther: (updater: (rawOther: unknown) => unknown) => void
• ProviderEdit 中新增内部子组件 AgentSettingsPanel，封装所有全局配置 UI。
• 新增 TypeScript 类型（src/types/index.ts）：
  • ThinkingConfig
  • LoopControlConfig
  • BackgroundConfig
  • PermissionRule
  • Hook
  • AgentSettings
• 新增 helper（src/components/AgentSettingsPanel.tsx 或 src/lib/agent-settings.ts）：
  • getAgentSettings(rawOther: unknown): AgentSettings
  • setAgentSettings(rawOther: unknown, patch: Partial<AgentSettings>): unknown
  • 统一从 raw_other 中读取/写入 [thinking]、[loop_control]、[background]、[[permission.rules]]、[[hooks]]。
• 后端无需改动：这些顶层表原本就通过 Config.raw_other 在导入/导出时保留。

模型默认上下文长度

在新增模型（手动添加、一键设置、从 API 发现模型）时，根据模型 ID 自动推荐 max_context_size。

• 默认回退值：256000
• 匹配方式：按模型 ID 字符串进行不区分大小写的正则前缀/全名匹配（代码中使用 /pattern/i），命中第一条规则即返回。
• 规则表（按匹配优先级排列）：

匹配规则（不区分大小写）	max_context_size	说明
国内模型（优先）
^kimi-for-coding$	262144	Kimi Code 官方托管模型
^kimi-k2\.5	256000	Kimi K2.5 系列
^kimi-k2	256000	Kimi K2 系列
^kimi-	256000	其他 Kimi 模型
^glm-5\.2	1000000	GLM-5.2
^glm-5\.1	256000	GLM-5.1
^glm-5	256000	GLM-5 系列
^glm-4	128000	GLM-4 / GLM-4-Plus / GLM-4-Flash
^glm-	128000	其他 GLM 模型
^MiniMax-M3	1000000	MiniMax-M3
^MiniMax-Text-01	400000	MiniMax-Text-01
^MiniMax-	256000	其他 MiniMax 模型
^qwen2\.5	128000	通义千问 Qwen2.5 系列
^qwen-max	128000	通义千问 Max
^qwen-plus	128000	通义千问 Plus
^qwen-turbo	128000	通义千问 Turbo
^qwen-coder	128000	通义千问 Coder
^qwen-	128000	其他通义千问模型
^deepseek-r1	64000	DeepSeek-R1
^deepseek-v3	64000	DeepSeek-V3
^deepseek-coder	64000	DeepSeek-Coder
^deepseek-	64000	其他 DeepSeek 模型
^hunyuan-pro	32000	腾讯 Hunyuan Pro
^hunyuan-standard	32000	腾讯 Hunyuan Standard
^hunyuan-lite	32000	腾讯 Hunyuan Lite
^hunyuan-	32000	其他 Hunyuan 模型
^doubao-pro	128000	字节 Doubao Pro
^doubao-lite	128000	字节 Doubao Lite
^doubao-vision	128000	字节 Doubao Vision
^doubao-	128000	其他 Doubao 模型
^ernie-4\.0	128000	百度文心 4.0
^ernie-3\.5	128000	百度文心 3.5
^ernie-speed	128000	百度文心 Speed
^ernie-lite	128000	百度文心 Lite
^ernie-	128000	其他文心模型
^spark-v4	32000	讯飞星火 V4
^spark-v3\.5	32000	讯飞星火 V3.5
^spark-pro	32000	讯飞星火 Pro
^spark-max	32000	讯飞星火 Max
^spark-	32000	其他星火模型
^sensechat-	128000	商汤 SenseChat
^baichuan-4	128000	百川 Baichuan 4
^baichuan-3	128000	百川 Baichuan 3
^baichuan-	128000	其他百川模型
^yi-	128000	零一万物 Yi 系列
国际模型
^claude-opus	200000	Claude Opus 系列（多数版本为 200K；Claude 4 部分版本可达 1M，这里取保守值）
^claude-sonnet	200000	Claude Sonnet 系列
^claude-haiku	200000	Claude Haiku 系列
^claude-	200000	其他 Claude 模型
^gpt-4\.1	1047576	GPT-4.1 系列（1M tokens）
^gpt-4o	128000	GPT-4o 系列
^gpt-4-turbo	128000	GPT-4 Turbo
^gpt-4-	128000	其他 GPT-4 模型
^gemini-2\.0-flash	1048576	Gemini 2.0 Flash（1M tokens）
^gemini-1\.5-pro	2097152	Gemini 1.5 Pro（2M tokens）
^gemini-1\.5-flash	1048576	Gemini 1.5 Flash（1M tokens）
^gemini-	1048576	其他 Gemini 模型
（默认）	256000	未命中任何规则

注：模型上下文长度取公开资料典型值，部分国内/国际模型存在多个版本导致数值差异，实际以供应商文档为准。规则表以代码常量形式存在，按 specificity 从高到低排列，命中第一条即返回，未命中时回退到 256000。用户仍可在模型映射表格中手动覆盖。

• 实现位置：src/lib/model-defaults.ts（或类似纯函数文件）。
• 核心函数：

  export function getDefaultMaxContextSize(modelId: string): number;
  

• 调用点：
  • ProviderEdit 中手动添加模型时。
  • ProviderEdit 中通过"获取模型列表"发现模型并添加时。
  • handleAddProvider / handleApplyProviderJson 等生成默认模型的地方，可一并使用此函数作为更智能的默认值。

i18n 键

新增键：

• agentSettings: "全局配置"
• enableThinking: "启用思考"
• thinkingLevel: "思考等级"
• thinkingKeep: "保留思考内容"
• thinkingLow: "低"
• thinkingMedium: "中"
• thinkingHigh: "高"
• thinkingMax: "最大"
• thinkingContextHint: "启用思考会占用更多上下文，请确保模型上下文长度和预留空间足够。"
• loopControlSettings: "循环控制"
• maxRetriesPerStep: "单步重试次数"
• reservedContextSize: "上下文预留大小"
• backgroundSettings: "后台任务"
• maxRunningTasks: "最大并发数"
• keepAliveOnExit: "退出时保持运行"
• permissionRules: "权限规则"
• permissionDecision: "处置"
• permissionPattern: "模式"
• permissionAllow: "允许"
• permissionDeny: "拒绝"
• permissionAsk: "询问"
• addRule: "+ 添加规则"
• addCommonRules: "添加常用规则"
• hooks: "生命周期钩子"
• hookEvent: "事件"
• hookMatcher: "匹配器"
• hookCommand: "命令"
• hookTimeout: "超时"
• addHook: "+ 添加钩子"

验收标准

• 在 Kimi Code 选项卡下进入供应商编辑页面，"模型映射"标签页下方出现"全局配置"区域。
• Pi 选项卡下不显示该全局配置区域。
• "启用思考"复选框控制 [thinking].enabled。
• 启用思考后，"思考等级"和"保留思考内容"可用；未启用时禁用。
• "思考等级"分段按钮写入 [thinking].effort。
• "保留思考内容"写入 [thinking].keep = "all"，未勾选时写入关值。
• [loop_control] 和 [background] 的数字/复选框正确读写。
• 权限规则列表可增删改，导出为 [[permission.rules]]。
• 钩子列表可增删改，导出为 [[hooks]]。
• 保存配置后，Kimi Code 的 config.toml 中对应顶层表内容正确。
• 不修改模型映射表格中已有的 max_context_size 手动编辑逻辑。
• 添加新模型时，max_context_size 默认按规则表自动填充，匹配不区分大小写，未命中规则时为 256000。
• 用户仍可在模型映射表格中手动覆盖自动填充的 max_context_size。
• npm run build 通过。