# 配置与管理指令

本节介绍 Snow CLI 的整体配置、连接、权限管理与运行状态查看类指令。

返回：[指令面板说明](./09.0.指令面板说明.md)

---

## `/home`

返回欢迎页。

- **作用**: 返回 Snow CLI 主菜单/欢迎界面
- **功能**:
  - 暂停代码库索引
  - 清除 API 配置缓存
  - 重置客户端连接
- **示例**: 输入 `/home` 返回主页

## `/ide`

连接 IDE 插件。

- **作用**: 连接到 VSCode 或 JetBrains IDE 插件
- **功能**:
  - 自动检测并连接 IDE
  - 显示连接端口
  - 强制重连（如已连接）
- **前提**: 需要先安装对应的 IDE 插件
- **示例**: 输入 `/ide` 建立连接

## `/connect`

连接 Snow Instance。

- **作用**: 打开实例连接面板，登录并连接到远程 Snow Instance 用于 AI 处理
- **使用方式**:
  - 无参数: `/connect` - 打开连接向导
  - 带 API 地址: `/connect http://localhost:5136/api` - 打开面板并预填 API URL
- **功能**:
  - 支持读取并复用已保存的连接配置
  - 分步骤输入 API 地址、账号密码、实例 ID 与显示名称
  - 可在已保存配置页面按 `D` 删除保存的连接配置
- **面板操作**:
  - `Enter` - 进入下一步或提交当前表单
  - `↑/↓` - 在多字段步骤中切换焦点
  - `ESC` - 返回上一步或关闭面板
- **示例**:
  - `/connect` - 打开连接面板
  - `/connect http://localhost:5136/api` - 预填地址后连接

## `/disconnect`

断开当前 Snow Instance 连接。

- **作用**: 断开当前已建立的实例连接
- **使用场景**: 需要切换实例、清理远程连接状态或停止通过实例处理请求时
- **示例**: 输入 `/disconnect` 断开连接

## `/connection-status`

查看实例连接状态。

- **作用**: 输出当前 Snow Instance 的连接状态、实例信息以及错误信息（如有）
- **使用场景**: 排查连接失败、确认当前是否已连接到目标实例
- **示例**: 输入 `/connection-status` 查看连接状态

## `/mcp`

查看 MCP 服务。

- **作用**: 打开 MCP（Model Context Protocol）服务面板
- **功能**: 显示已配置的 MCP 服务列表和状态
- **示例**: 输入 `/mcp` 查看服务

## `/usage`

查看使用统计（TUI 面板）。

- **作用**: 打开使用统计面板，按模型聚合 token 用量
- **时间窗**（`Tab` 切换，滚动窗口，非自然日历）:
  - 最近 24 小时
  - 最近 7 天
  - 最近 30 天（默认）
  - 最近 12 个月
- **数据目录**: `~/.snow/usage/YYYY-MM-DD/*.jsonl`（每次 API 调用 append 一行，跨版本兼容）
- **示例**: 输入 `/usage` 打开面板，按 `Tab` 切换时间窗
- **无头入口**: 见 `session-command` 的 `usage` / `snow cmd usage [--period=...]`

## `/telemetry`

打开 OpenTelemetry 遥测配置面板。

- **作用**: 配置 Snow CLI 的 OpenTelemetry 遥测导出设置
- **功能**:
  - 开启或关闭遥测
  - 配置 traces、metrics、logs 的导出器
  - 支持 OTLP、console、none；metrics 额外支持 Prometheus
  - 配置 OTLP 协议（`grpc`、`http/protobuf`、`http/json`）、Endpoint 与请求头
- **行为说明**:
  - 配置保存到当前项目的 Snow 统一 JSON 设置中
  - 遥测为可选开启，默认不主动启用
  - Snow CLI 只负责采集并导出数据，链路追踪、指标和日志的查看需要使用外部 OpenTelemetry Collector、Jaeger、Prometheus、Grafana 或 APM/HPM 系统
- **面板操作**:
  - `↑/↓` - 切换配置项
  - `←/→` 或 `Enter` - 切换当前选项值
  - 直接输入 - 编辑 Endpoint 或 Headers 字段
  - `S` - 保存当前配置
  - `ESC` - 保存并关闭面板
- **示例**: 输入 `/telemetry` 打开遥测配置面板

## `/permissions`

管理工具权限。

- **作用**: 打开权限管理面板
- **功能**: 管理始终批准的工具列表，控制哪些工具可以自动执行
- **使用场景**: 需要配置工具的自动批准权限，或撤销某些工具的自动执行权限
- **示例**: 输入 `/permissions` 打开权限面板

## `/auto-format`

切换 MCP 文件编辑后的自动格式化。

- **作用**: 开启、关闭或查看当前项目的自动格式化状态
- **参数**:
  - 无参数: `/auto-format` - 直接切换当前开关状态
  - `on`: `/auto-format on` - 启用自动格式化
  - `off`: `/auto-format off` - 禁用自动格式化
  - `status`: `/auto-format status` - 查看当前状态
- **行为说明**:
  - 配置持久化到项目内的 `.snow/settings.json`
  - 仅对当前项目生效
  - 默认状态为启用
- **使用场景**: 需要控制 AI 通过 MCP 修改文件后是否自动格式化时
- **示例**:
  - `/auto-format` - 切换当前状态
  - `/auto-format status` - 查看状态
  - `/auto-format off` - 关闭自动格式化

## `/config`

导出或导入 Snow CLI YAML 配置；会话控制面另支持查看/热改 API 限制与模型参数。

### TUI 斜杠（备份 / 恢复）

- **作用**: 通过 YAML 文件备份或恢复 Snow CLI 配置
- **参数**:
  - `export`: `/config export` - 选择保存位置并导出当前配置
  - `import`: `/config import` - 选择 YAML 文件并导入配置
- **行为说明**:
  - 导出时会打开保存对话框，并将当前配置写入 YAML 文件
  - 导入时会打开文件选择对话框，并从选中的 YAML 文件恢复配置
  - 仅支持 `export` 与 `import` 子命令；未提供有效参数时会显示用法提示
- **示例**:
  - `/config export` - 导出配置
  - `/config import` - 导入配置

### 会话控制面 / 无头（查看与热改上下文）

TUI 的 `/config` **只**负责 YAML 导入导出，**不能**用 `/config 12000` 这类斜杠直接改上下文。改 `maxContextTokens` / `maxTokens` / 模型名请走 **session-command 控制面**（Agent 工具 `session-command-run`，或 CLI `snow cmd`）。完整矩阵见 [29.会话控制面 session-command](./29.会话控制面session-command.md)。

| 命令 ID           | CLI 形式                          | 风险      | 说明                                                    |
| ----------------- | --------------------------------- | --------- | ------------------------------------------------------- |
| `config.snapshot` | `snow cmd config snapshot`        | read      | 裸 `config` 默认；非密钥配置快照（含 api 摘要）         |
| `config.status`   | `snow cmd config status`          | read      | 当前 Profile 的 `maxContextTokens` / `maxTokens` / 模型 |
| `config.set`      | `snow cmd config set key=value …` | low_write | **热写**限制/模型，**无需重启**同进程 TUI               |

**`config.set` 支持的 key**（`key=value`，可一次多个）：

- `maxContextTokens` — 模型最大上下文窗口
- `maxTokens` — 单次回复最大输出 token
- `advancedModel` / `basicModel` — 高级/基础模型名
- `requestMethod` — `chat` \| `responses` \| `gemini` \| `anthropic`

**不支持**通过控制面设置 `apiKey`（密钥仍走配置界面或受控导入，禁止静默改密钥）。

**行为说明**:

- 写入 `~/.snow/config.json` **以及**当前 active profile（如 `~/.snow/profiles/<name>.json`）
- 同进程 TUI（含 StatusLine）会热刷新；外部另开进程执行的 `snow cmd` **不会**热刷新已打开的 TUI
- Agent 应优先 `session-command-run` → `config.set` / `config.status`，**不要**把手改 JSON 当作官方自动化路径

**示例**:

```bash
snow cmd config status --json
snow cmd config set maxContextTokens=470000 --json
snow cmd config set maxContextTokens=120000 maxTokens=8192 --json
snow cmd config set advancedModel=grok-4.5 basicModel=grok-4.5 --json
snow cmd config snapshot --json
```

Agent 工具等价调用：

```json
{"command": "config.status"}
```

```json
{"command": "config.set", "args": "maxContextTokens=470000"}
```

## `/help`

帮助信息。

- **作用**: 打开帮助面板
- **功能**: 显示快捷键、常用指令说明
- **示例**: 输入 `/help` 或按 `?` 键

## `/quit`

退出程序。

- **作用**: 安全退出 Snow CLI 应用
- **功能**:
  - 停止代码库索引
  - 断开 VSCode 连接
  - 清理资源
- **示例**: 输入 `/quit` 或按 `Ctrl+C`

## `/worktree`

Git 分支管理。

- **作用**: 打开交互式 Git 分支管理面板
- **功能**:
  - 自动检测当前目录是否为 Git 仓库
  - 显示所有本地分支列表，标记当前分支
  - 快速切换分支
  - 创建新分支
  - 删除分支（支持强制删除未合并分支）
  - 本地更改冲突时提示暂存后切换
- **面板操作**:
  - `↑/↓` - 上下移动选择分支
  - `Enter` - 切换到选中的分支
  - `N` - 创建新分支
  - `D` - 删除选中的分支
  - `Y/N` - 确认/取消删除或暂存切换
  - `ESC` - 关闭面板
- **使用场景**: 需要在不离开终端的情况下快速管理 Git 分支
- **示例**: 输入 `/worktree` 打开分支管理面板

## `/add-dir`

添加工作目录。

- **作用**: 添加项目目录到工作目录列表（支持本地目录与 SSH 远程目录）
- **使用方式**:
  - 无参数: `/add-dir` - 打开目录管理面板
  - 带本地路径: `/add-dir /path/to/project` - 直接添加本地目录
  - 远程目录: 需要在面板中按 `S` 进入「添加 SSH 远程目录」模式，填写主机/端口/用户名/认证方式/远程路径后添加
- **配置文件**: `.snow/working-dirs.json`
- **示例**:
  - `/add-dir` - 打开面板管理（`A` 添加本地，`S` 添加 SSH，`D` 删除已标记）
  - `/add-dir D:\projects\myapp` - 直接添加本地目录

## `/cleanup`

清理 `~/.snow` 目录数据。

- **作用**: 打开清理面板，删除不再需要的会话、快照、日志等数据以释放磁盘空间
- **两种清理方式**:
  - 按项目清理: 列出所有占用磁盘的项目，勾选后删除其会话、快照、历史、TODO、目标、团队快照等数据
  - 按时间清理: 选择 7/15/30/90 天档位，删除早于该天数的数据（日志、用量统计、任务、导出、会话、快照、历史、TODO 等）
- **面板操作**:
  - `↑/↓` - 移动选择
  - `Enter` - 进入所选清理方式
  - `空格` - 标记/取消标记项目（按项目清理）
  - `A` - 全选/全不选项目（按项目清理）
  - `D` - 删除已标记项目（按项目清理）或删除所选天数前的数据（按时间清理）
  - `Y/N` - 确认/取消删除
  - `ESC` - 返回上级或关闭面板
- **示例**:
  - `/cleanup` - 打开清理面板
  - 进入「按项目清理」勾选旧项目后按 `D` 删除
  - 进入「按时间清理」选择「早于 30 天」后按 `D` 删除

## `/backend`

查看后台进程。

- **作用**: 打开后台进程管理面板
- **功能**:
  - 显示所有后台运行的命令
  - 查看进程状态（运行中、已完成、失败）
  - 查看进程输出和运行时长
  - 支持终止正在运行的进程
- **面板操作**:
  - `↑/↓` - 选择进程
  - `Enter` - 终止选中的运行中进程
  - `ESC` - 关闭面板
- **使用场景**: 管理通过 `Ctrl+B` 移入后台的长时间运行命令
- **示例**: 输入 `/backend` 查看后台进程

## `/loop`

创建定时循环任务。

- **作用**: 创建一个按固定间隔或每天固定时刻执行指定 Prompt 的循环任务。默认是会话级循环，退出当前 Snow CLI 后停止；也可以使用 daemon 模式创建后台常驻循环。
- **语法格式**:
  - `/loop <时长> <prompt>` - 创建会话级循环，前缀时长格式，如 `/loop 5m 检查服务状态`
  - `/loop daemon <时长> <prompt>` - 创建后台常驻循环，如 `/loop daemon 5m 检查服务状态`
  - `/loop --daemon <时长> <prompt>` - daemon 模式的参数写法，与 `daemon` 前缀等价
  - `/loop <prompt> every <数字> <单位>` - 间隔后缀格式，如 `/loop 检查服务状态 every 2 hours`
  - `/loop daily HH:mm <prompt>` - 每天本地时间固定时刻运行，如 `/loop daily 09:30 检查日报`
  - `/loop at HH:mm <prompt>` - 每天本地时间固定时刻运行，如 `/loop at 18:00 总结当天工作`
  - `/loop every day at HH:mm <prompt>` - 每日定时前缀格式，如 `/loop every day at 09:30 检查日报`
  - `/loop <prompt> every day at HH:mm` - 每日定时后缀格式，如 `/loop 检查日报 every day at 09:30`
  - 不指定时长或每日时刻时默认间隔 10 分钟
- **支持的时长单位**:
  - 秒: `s`、`sec`、`second`、`seconds`
  - 分: `m`、`min`、`minute`、`minutes`
  - 时: `h`、`hr`、`hour`、`hours`
  - 天: `d`、`day`、`days`
  - 支持复合格式，如 `8h30m`、`1d12h`
- **每日定时规则**:
  - 时间格式为 `HH:mm`，范围为 `00:00` 到 `23:59`
  - 使用本地时间；`9:30` 会标准化显示为 `09:30`，文档中建议写作 `09:30`
  - 如果指定时刻今天已经过去或刚好到达，下次执行会安排到明天同一时刻
- **子命令**:
  - `/loop list` - 列出所有活跃的循环任务；输出中会显示 `Loop ID`，用于取消任务
  - `/loop cancel <id>` 或 `/loop stop <id>` - 按 Loop ID 取消指定循环任务
  - `/loop tasks` - 打开任务管理器并显示相关任务
- **会话级与 daemon 模式区别**:
  - 会话级循环：通过 `/loop 5m <prompt>` 或 `/loop daily 09:30 <prompt>` 创建，只在当前 Snow CLI 会话内有效，退出后停止
  - daemon 循环：通过 `/loop daemon 5m <prompt>` 或 `/loop --daemon daily 09:30 <prompt>` 创建，会启动 detached 后台进程，退出当前 Snow CLI 后仍继续运行
  - daemon 状态保存在 `~/.snow/loop-daemons`，日志保存在 `~/.snow/loop-logs`
  - `snow --loop-daemon-execute <base64-loop-state>` 是 daemon 子进程使用的内部启动参数，不建议手动执行
- **注意事项**:
  - 最多同时创建 50 个循环任务
  - 上一次任务仍在运行时，本次触发会被自动跳过（skipped）
  - 取消任务前先运行 `/loop list` 获取 `Loop ID`
  - daemon 循环需要显式执行 `/loop cancel <id>` 或 `/loop stop <id>` 才会停止
- **示例**:
  - `/loop 5m 检查日志中的错误` - 每 5 分钟执行一次，会话退出后停止
  - `/loop daemon 5m 检查日志中的错误` - 每 5 分钟执行一次，退出当前 Snow CLI 后仍继续运行
  - `/loop --daemon 8h30m 生成每日报告` - 每 8 小时 30 分钟执行一次后台常驻循环
  - `/loop 检查服务状态 every 2 hours` - 每 2 小时执行一次
  - `/loop daily 09:30 检查日报` - 每天本地时间 09:30 执行一次
  - `/loop at 18:00 总结当天工作` - 每天本地时间 18:00 执行一次
  - `/loop every day at 09:30 检查日报` - 每天本地时间 09:30 执行一次
  - `/loop 检查日报 every day at 09:30` - 每天本地时间 09:30 执行一次
  - `/loop list` - 查看所有循环任务与 Loop ID
  - `/loop cancel abc12345` - 取消指定循环任务

## `/profiles`

打开配置文件与模型切换面板。

- **作用**: 打开 Profile 面板，支持切换配置文件及 AI 模型相关设置
- **功能**:
  - 切换不同的配置文件（Profile）
  - 切换当前使用的 AI 模型
  - 支持搜索过滤
  - 实时切换对话使用的模型
  - 支持切换思考强度设置（适用于支持思考功能的模型）
- **面板操作**:
  - `↑/↓` - 上下移动选择
  - `Tab` - 进入当前焦点 Profile 的详情编辑面板（不切换 active）
  - `Enter` - 切换为选中的 Profile（设为 active）
  - `Backspace/Delete` - 删除搜索关键词末尾字符
  - 直接输入字符 - 搜索过滤 Profile 列表
  - `ESC` - 关闭面板
- **使用场景**: 快捷键冲突或不方便按键时，可直接通过命令打开面板；也可用于快速切换 AI 模型
- **示例**: 输入 `/profiles` 打开配置与模型选择面板
- **无头 / Agent 入口**:
  - 列表 / 当前 / 切换：`snow cmd profiles list|current|switch <name> --yes`
  - 改上下文 / 输出上限 / 模型名：用 `config.set` / `config.status`（见上文 `/config` 会话控制面小节），**不是** `/profiles` 斜杠参数
  - 完整矩阵：[29.会话控制面 session-command](./29.会话控制面session-command.md)