> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义主题

Step Code 自带六套主题，也可以用 JSON 文件定义自己的配色：放入主题目录后即可在 `/theme` 中选择，修改当前主题会即时热重载。

## 内置主题

| 主题                  | 用途        |
| ------------------- | --------- |
| `step-blue`         | 默认蓝色主题    |
| `step-violet`       | 深色终端紫色主题  |
| `step-violet-light` | 浅色终端紫色主题  |
| `dark`、`light`      | 通用深色和浅色主题 |
| `sage`              | 深色终端绿色主题  |

## 主题文件

| 范围   | 路径                                |
| ---- | --------------------------------- |
| 用户   | `~/.stepcode/agent/themes/*.json` |
| 项目   | `.stepcode/themes/*.json`，需要项目信任  |
| 包    | 资源包中的主题目录                         |
| 启动参数 | `--theme <路径>`，可重复                |

文件名即主题名，例如 `my-theme.json`。放入目录后，自定义主题与内置主题一起出现在 `/theme` 中。建议以完整主题为起点，保留全部颜色字段后再调整配色。

## 主题 JSON 格式

主题由 `name`、可复用颜色变量 `vars` 和颜色映射 `colors` 组成。以下是字段示意，不是可直接替换完整文件的主题：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "name": "my-theme",
  "vars": {"primary": "#7aa2f7"},
  "colors": {
    "accent": "primary",
    "text": "#c0caf5",
    "mdTableHeader": "#9d7cd8",
    "syntaxKeyword": "#bb9af7"
  }
}
```

完整主题需定义全部 52 个颜色 token，覆盖核心 UI、背景与内容、Markdown、diff、语法高亮、thinking 边框和 bashMode。上面的示意只展示部分字段，不能直接作为完整主题使用。

| 颜色值         | 含义             |
| ----------- | -------------- |
| `"#ff0000"` | 六位十六进制颜色       |
| `39`        | xterm 256 色索引  |
| `"primary"` | 引用 `vars` 中的变量 |
| `""`        | 使用终端默认颜色       |

支持真彩色的终端使用 24-bit 颜色；其他终端可能回退为接近的 256 色。

暗色终端宜选亮饱和色，亮色终端宜选暗哑色；公共基色放入 `vars` 复用。

## 切换主题

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
/theme
/theme my-theme
```

也可在配置文件中设置：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
theme = "my-theme"
```

仅对一次启动生效：

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
step --use-theme light
```

`/theme` 打开选择器，自定义主题即时可用，无需重启；`/theme <名称>` 直接切换。编辑当前使用的主题文件会热重载。

## statusTips

`statusTips` 是 `config.toml` 的布尔选项，不是主题字段。默认 `true`，工作行提示每轮一条，设为 `false` 可关闭：

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
statusTips = false
```

## 出错时的行为

非法色值会使整份主题加载失败并回退到内置 `dark`；热重载中瞬时出错则保持当前主题不变。请检查 JSON 语法、颜色值、变量引用和字段完整性。

## 下一步

* [配置文件](/docs/zh/step-code/configuration/files)
* [插件](/docs/zh/step-code/customization/plugins)