# Snow CLI 使用文档——主题设置 欢迎使用 Snow CLI！在终端中进行 Agentic 编程。 ## 什么是主题 主题定义了 Snow CLI 终端界面的外观，包括颜色方案、代码高亮样式、菜单显示效果等。通过主题设置，您可以： - 选择预设的主题方案 - 自定义配色以适应个人喜好 - 调整界面显示模式（简洁/标准） - 创建和保存自己的主题配色 ## 进入主题设置 1. 启动 Snow CLI 2. 在主菜单中选择"主题设置"选项 3. 进入主题设置界面 ## 简洁模式 简洁模式是一个独立的界面显示选项，可以简化终端界面显示，减少视觉干扰。 ### 功能说明 - **标准模式**: 完整显示所有界面元素（边框、装饰、详细信息） - **简洁模式**: 简化界面显示，隐藏非必要元素，专注于内容本身 ### 操作方法 1. 在主题设置界面，第一个选项即为"简洁模式" 2. 选中后按 Enter 键切换状态 3. 界面显示当前状态： - `简洁模式 已启用` - `简洁模式 已禁用` 4. 简洁模式的切换立即生效 ### 使用场景 - 小屏幕终端：减少空间占用 - 专注工作：减少视觉干扰 - 性能优化：减少渲染开销 - 截图演示：界面更简洁清晰 ## 预设主题 Snow CLI 提供 6 种精心设计的预设主题，每种主题都有独特的配色方案。 ### 1. Dark 主题 **特点**: Snow CLI 的默认主题，经典的深色配色方案 **适用场景**: - 长时间编码工作 - 低光环境使用 - 护眼需求 **配色特征**: - 深色背景 - 柔和的文本颜色 - 清晰的语法高亮 - 舒适的对比度 ### 2. Light 主题 **特点**: 明亮的浅色主题，适合白天使用 **适用场景**: - 明亮环境下使用 - 白天工作时段 - 个人偏好浅色界面 **配色特征**: - 浅色背景 - 深色文本 - 高对比度 - 清晰易读 ### 3. GitHub Dark 主题 **特点**: 模仿 GitHub 的深色主题风格 **适用场景**: - GitHub 用户 - 喜欢 GitHub 配色的开发者 - 需要熟悉的视觉体验 **配色特征**: - GitHub 风格配色 - 专业的代码高亮 - 舒适的深色背景 ### 4. Rainbow 主题 **特点**: 丰富多彩的配色方案 **适用场景**: - 喜欢鲜艳色彩 - 需要区分不同类型信息 - 个性化需求 **配色特征**: - 多彩的高亮颜色 - 鲜明的视觉效果 - 活跃的氛围 ### 5. Solarized Dark 主题 **特点**: 著名的 Solarized 配色方案的深色版本 **适用场景**: - Solarized 爱好者 - 需要科学配色 - 长时间阅读代码 **配色特征**: - 经过科学设计的配色 - 舒适的对比度 - 护眼配色方案 ### 6. Nord 主题 **特点**: 受 Nord 配色方案启发的冷色调主题 **适用场景**: - 喜欢冷色调 - 追求现代感 - 统一的配色体验 **配色特征**: - 北欧风格配色 - 冷色调为主 - 优雅而现代 ## 主题选择和应用 ### 浏览主题 1. 在主题设置界面，使用 ↑/↓ 方向键浏览主题列表 2. 当光标移动到某个主题时，界面会立即预览该主题效果 3. 预览区域显示代码对比示例，展示该主题的语法高亮效果 4. 底部显示当前选中主题的说明信息 **预览特点**: - 无需按 Enter，光标移动即可预览 - 实时显示主题效果 - 代码 Diff 示例展示语法高亮 - 帮助快速选择合适的主题 ### 应用主题 1. 浏览到想要使用的主题 2. 按 Enter 键确认应用 3. 主题配置自动保存到 `~/.snow/theme.json` 4. 主题立即生效并应用到整个界面 ### 取消更改 - 按 ESC 键：取消更改，恢复进入设置前的主题 - 选择"返回"选项：同样会恢复原主题 ## 自定义主题 除了预设主题，您还可以创建完全自定义的主题配色。 ### 进入自定义编辑器 1. 在主题设置界面选择"编辑自定义主题..."选项 2. 按 Enter 进入自定义主题编辑器 3. 编辑器显示所有可自定义的颜色选项 ### 可自定义的颜色 自定义主题包含 16 个颜色选项，分为多个类别： #### 基础颜色（3 项） 1. **background** - 背景色 - 界面主要背景 - 建议使用深色或浅色基调 2. **text** - 文本色 - 主要文本内容颜色 - 需要与背景形成良好对比 3. **border** - 边框色 - UI 边框和分隔线 - 通常比背景稍亮或稍暗 #### Diff 显示颜色（3 项） 4. **diffAdded** - 添加行背景色 - 代码新增行的背景 - 建议使用绿色系 5. **diffRemoved** - 删除行背景色 - 代码删除行的背景 - 建议使用红色系 6. **diffModified** - 修改内容高亮色 - 行内修改部分的高亮 - 建议使用黄色系 #### 行号颜色（2 项） 7. **lineNumber** - 行号文本色 - 代码行号的颜色 - 通常使用灰色系 8. **lineNumberBorder** - 行号区域边框色 - 行号区域的边框 - 与行号颜色协调 #### 菜单颜色（4 项） 9. **menuSelected** - 选中菜单项颜色 - 当前选中的菜单项 - 需要醒目突出 10. **menuNormal** - 普通菜单项颜色 - 未选中的菜单项 - 与背景形成适当对比 11. **menuInfo** - 信息类菜单项颜色 - 提示信息、说明文本 - 通常使用青色系 12. **menuSecondary** - 次要菜单项颜色 - 次要信息、辅助文本 - 通常使用灰色系 #### 状态颜色（3 项） 13. **error** - 错误提示色 - 错误消息、警告 - 通常使用红色 14. **warning** - 警告提示色 - 警告消息、注意事项 - 通常使用黄色 15. **success** - 成功提示色 - 成功消息、确认信息 - 通常使用绿色 #### Logo 渐变色（1 项） 16. **logoGradient** - Logo 渐变色 - Snow CLI Logo 的渐变效果 - 需要输入 3 个颜色值，用逗号分隔 - 格式: `#color1, #color2, #color3` - 示例: `#d3d3d3, #808080, #505050` ### 编辑颜色 #### 选择要编辑的颜色 1. 使用 ↑/↓ 方向键浏览颜色列表 2. 每行显示：`颜色名称: 当前值` 3. 选中要修改的颜色项 4. 按 Enter 键进入编辑模式 #### 输入颜色值 进入编辑模式后： 1. 界面显示当前颜色值 2. 提供输入框供输入新值 3. 支持多种颜色格式： - 十六进制: `#RRGGBB` (如 `#1e1e1e`) - 颜色名称: `red`, `blue`, `green`, `cyan`, `yellow` 等 - RGB 格式: `rgb(30, 30, 30)` 4. 输入完成后按 Enter 确认 5. 颜色立即更新并在预览区域显示效果 #### 取消编辑 - 在编辑模式下按 ESC 键：取消当前颜色的修改 - 返回颜色列表继续编辑其他颜色 自定义编辑器底部的预览区域会实时显示您的配色效果： - 显示代码对比示例 - 展示语法高亮效果 - 显示 Diff 对比效果 - 帮助您评估配色方案 ### 保存自定义主题 完成颜色编辑后： 1. 在颜色列表底部选择"保存"选项 2. 按 Enter 确认保存 3. 自定义配色保存到 `~/.snow/theme.json` 4. 主题自动切换为"Custom"主题 5. 返回主题设置界面 **配置文件格式**: ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false } ``` ### 重置为默认配色 如果对自定义配色不满意，可以重置为默认值： 1. 在自定义编辑器中选择"重置为默认"选项 2. 按 Enter 确认 3. 所有颜色恢复为系统默认的自定义主题配色 4. 预览区域立即显示默认配色效果 5. 可以重新开始编辑 **注意**: 重置操作不会立即保存，需要选择"保存"才会写入配置文件 ## 键盘快捷键 ### 主题设置界面 - **↑/↓**: 在主题列表中导航 - **Enter**: 应用选中的主题或执行操作 - **ESC**: 取消更改并返回主菜单 ### 自定义编辑器 - **↑/↓**: 在颜色列表中导航 - **Enter**: 编辑选中的颜色或执行操作 - **ESC**: 返回主题设置（未保存的更改会丢失） ### 颜色编辑模式 - **Enter**: 确认输入的颜色值 - **ESC**: 取消当前颜色编辑 ## 主题配置最佳实践 ### 1. 选择合适的基础主题 根据工作环境选择： - 低光环境：深色主题（Dark, GitHub Dark, Nord） - 明亮环境：浅色主题（Light） - 个人偏好：选择最舒适的配色方案 ### 2. 自定义主题配色建议 #### 对比度 - 确保文本与背景有足够对比度 - 避免过于刺眼的颜色组合 - 测试长时间使用的舒适度 #### 一致性 - 保持配色方案的一致性 - 相关功能使用相似色调 - 避免过多颜色造成混乱 #### 可读性 - 代码高亮颜色要清晰可辨 - Diff 颜色要明确区分添加/删除/修改 - 菜单项颜色层次分明 ### 3. 颜色选择技巧 #### 十六进制颜色 ``` 格式: #RRGGBB 示例: #1e1e1e - 深灰色背景 #d4d4d4 - 浅灰色文本 #0d4d3d - 深绿色（添加行） #5a1f1f - 深红色（删除行） ``` #### 命名颜色 ``` 基础色: black, white, gray 鲜艳色: red, green, blue cyan, magenta, yellow 扩展色: 可查阅终端支持的颜色名称列表 ``` ### 4. Logo 渐变色配置 Logo 渐变需要 3 个颜色形成渐变效果： ``` 从浅到深: #ffffff, #808080, #000000 蓝色系: #5e9cff, #2e5c8f, #1e3c5f 绿色系: #90ee90, #50ae50, #306e30 自定义: 确保三个颜色形成平滑过渡 第一个最亮，第三个最暗 ``` ### 5. 测试主题效果 创建自定义主题后，建议： 1. 测试代码高亮效果 2. 检查 Diff 对比清晰度 3. 验证菜单可读性 4. 确认长时间使用的舒适度 5. 在不同终端中测试兼容性 ### 6. 备份自定义主题 定期备份配置文件： ```bash # 备份主题配置 cp ~/.snow/theme.json ~/.snow/theme.json.backup # 恢复备份 cp ~/.snow/theme.json.backup ~/.snow/theme.json ``` ### 7. 多环境配置 如果在不同设备或环境使用： - 根据屏幕特性选择主题 - 考虑环境光照差异 - 统一团队配色方案（可选） ## 常见问题 **Q: 更改主题后需要重启 Snow CLI 吗？** A: 不需要。主题更改立即生效，会应用到当前界面和后续所有操作。 **Q: 自定义主题的配置文件在哪里？** A: 配置文件位于 `~/.snow/theme.json`，可以手动编辑或通过界面配置。 **Q: 可以导入和导出自定义主题吗？** A: 可以。直接复制 `theme.json` 文件即可分享主题配置。将文件放到 `~/.snow/` 目录下即可使用。 **Q: 简洁模式和主题选择有什么区别？** A: 简洁模式控制界面显示的繁简程度，主题控制颜色方案。两者独立工作，可以组合使用。 **Q: 如果自定义配色后界面显示异常怎么办？** A: 在自定义编辑器中选择"重置为默认"，或者直接删除 `~/.snow/theme.json` 文件，Snow CLI 会自动使用默认配置。 **Q: 所有终端都支持自定义颜色吗？** A: 大多数现代终端支持，但部分老旧终端可能只支持 16 色。建议使用 iTerm2、Windows Terminal、Hyper 等现代终端。 **Q: 可以针对不同项目使用不同主题吗？** A: 目前主题是全局配置，所有项目共享。如有需要可以在启动 Snow CLI 前临时修改配置文件。 **Q: 预览区域显示的代码示例可以自定义吗？** A: 预览代码是固定的示例，用于展示主题效果。实际使用时会应用到您的真实代码中。 **Q: logoGradient 必须是 3 个颜色吗？** A: 是的。Logo 渐变设计需要 3 个颜色来形成平滑的渐变效果。格式必须为 `[color1, color2, color3]`。 **Q: 如何分享我的自定义主题给团队？** A: 复制 `~/.snow/theme.json` 文件中的 `customColors` 部分，分享给团队成员。他们将内容粘贴到自己的配置文件中即可。 ## 主题配置文件说明 主题配置存储在 `~/.snow/theme.json` 文件中。 ### 完整配置示例 ```json { "theme": "custom", "customColors": { "background": "#1e1e1e", "text": "#d4d4d4", "border": "#3e3e3e", "diffAdded": "#0d4d3d", "diffRemoved": "#5a1f1f", "diffModified": "#dcdcaa", "lineNumber": "#858585", "lineNumberBorder": "#3e3e3e", "menuSelected": "#5e0691ff", "menuNormal": "white", "menuInfo": "cyan", "menuSecondary": "gray", "error": "red", "warning": "yellow", "success": "green", "logoGradient": ["#d3d3d3", "#808080", "#505050"] }, "simpleMode": false, "toolDisplayMode": "full", "thinkDisplayMode": "compact", "toolIcons": { "enabled": true, "status": { "enabled": true, "icons": { "success": "✓", "pending": "·", "error": "✗" } }, "tools": { "terminal-execute": "🖥" } }, "toolDisplayNames": { "websearch-search": "网页搜索" } } ``` > `toolIcons: true` 仍可用：表示类型图标默认开、状态前缀用内置紧凑符号（`✓/·/✗`）。 ### 字段说明 - **theme**: 当前使用的主题类型 - 可选值: `dark`, `light`, `github-dark`, `rainbow`, `solarized-dark`, `nord`, `custom` - **customColors**: 自定义主题的颜色配置 - 仅在 `theme` 为 `custom` 时使用 - 包含 16 个颜色字段 - **simpleMode**: 简洁模式开关 - `true`: 启用简洁模式 - `false`: 使用标准模式 - **toolDisplayMode**: 工具调用显示密度 - `full`（默认）/ `compact` / `hidden` - 也可用 `/tool-display` 或 `snow cmd tool-display` - **thinkDisplayMode**: 思考内容显示模式 - `compact`（默认）/ `full` - **toolIcons**: 聊天区工具标题的**类型图标**与**状态前缀**（与底部 StatusLine 无关） - 标题结构：`[状态前缀] [类型图标] [显示名或技术 ID]`，空段自动省略 - `true`（默认）：类型图标开；状态前缀用紧凑默认 `✓ / · / ✗ / ! / …` - `false`：关闭**类型**图标；状态前缀仍默认开启（可用对象里的 `status` 单独关） - 对象形式： ```json { "enabled": true, "status": { "enabled": true, "icons": { "pending": "·", "success": "✓", "error": "✗", "warning": "!", "running": "…" } }, "tools": { "websearch-search": "🔎", "terminal-execute": "🖥" } } ``` - `status: false` 或 `status.enabled: false`：隐藏状态前缀（例如只显示 `💻 终端命令`） - 与 `toolDisplayMode`、`toolDisplayNames` **独立** ### 工具图标（toolIcons）操作 **TUI 斜杠命令（推荐）：** ```bash /tool-icons # 查看状态（类型 + 状态前缀） /tool-icons status # 同上 /tool-icons on|off # 启停类型图标 /tool-icons status on|off # 启停状态前缀 /tool-icons status:success:✓ # 改成功符号（pending/error/warning/running 同理） /tool-icons status:success: # 恢复该状态默认符号 /tool-icons success:✅ # 简写（保留状态 key） /tool-icons websearch-search:🔎 # 覆盖单个工具类型图标 /tool-icons websearch-search: # 清除类型覆盖 ``` **session-command：** ```bash # 查看（含 toolIcons / toolStatusIcons / toolDisplayNames） snow cmd theme status # 关闭 / 打开类型图标 snow cmd theme set toolIcons=off snow cmd theme set toolIcons=on # 状态前缀 snow cmd theme set toolIcons=status:off snow cmd theme set toolIcons=status:on snow cmd theme set toolIcons=status:success:✓ snow cmd theme set toolIcons=status:success: # 为某个工具自定义类型图标 snow cmd theme set toolIcons=websearch-search:🔎 # 清除某个类型覆盖（恢复内置图标） snow cmd theme set toolIcons=websearch-search: ``` 也可直接编辑 `~/.snow/theme.json` 的 `toolIcons` 字段（推荐仍走 slash / session-command，避免整文件覆盖）。 ### 工具显示名（toolDisplayNames） 聊天区工具标题默认显示技术 ID（如 `websearch-search`）。**无内置中英文默认译名**；只有你配置了覆盖才会改显示。 > **推荐官方路径**（Agent / 自动化同样适用）：`/tool-names` 或 `snow cmd theme set toolDisplayNames=…`。 > **不推荐**用 `filesystem-create/edit` 整文件覆盖 `theme.json`——会绕过 theme API，且容易冲掉 `customColors` 等其它字段。 **TUI 斜杠**（`/tool-name` 为同义别名）： ```bash /tool-names # 查看覆盖 /tool-names websearch-search:网页搜索 # 设置一项 /tool-names a:甲 b:乙 c:丙 # 批量设置（优先于改文件） /tool-names websearch-search: # 清除一项 /tool-names clear # 清除全部 ``` **session-command：** ```bash snow cmd theme set toolDisplayNames=websearch-search:网页搜索 snow cmd theme set toolDisplayNames=websearch-search: snow cmd theme status # 含 toolDisplayNames ``` 批量场景请优先 `/tool-names t1:名1 t2:名2 …`（一次合并写入）。 **theme.json 字段**（仅作结果参考；写入请走命令）： ```json "toolDisplayNames": { "websearch-search": "网页搜索", "terminal-execute": "终端", "skill-execute": "技能" } ``` 外挂 MCP / skills：未配置则仍显示原 ID；需要中文时自行覆盖即可。仅影响**新**工具标题。 ### 手动编辑注意事项 如果选择手动编辑配置文件： 1. 确保 JSON 格式正确 2. logoGradient 必须是数组格式 3. 颜色值必须是有效的颜色格式 4. 保存后会自动热刷新，无需重启 Snow CLI（TUI 会监听 `~/.snow/theme.json`） **Agent / 自动化推荐写法（不要直接强写文件）：** ```bash # 通过 session-command 写入自定义配色并立即热刷新 snow cmd theme colors "{\"background\":\"#0B0E1A\",\"text\":\"#E2E4F0\",\"menuSelected\":\"#A78BFA\"}" # 或 snow cmd theme set custom # 工具类型图标 snow cmd theme set toolIcons=on snow cmd theme set toolIcons=terminal-execute:💻 ``` 建议优先使用配置界面或 `theme colors` / `theme set` 命令；直接覆盖 `theme.json` 也能热刷新，但缺少校验。