---
name: guide-settings
description: 系统设置指南，包括配置管理、导入导出、主题设置、常见问题
trigger: 用户询问怎么备份配置、导入导出、切换主题、版本回滚、常见报错怎么办、配置迁移、子智能体配置、代理设置、记忆管理、开机自启、自动启动、执行策略、命令规则
---

# 系统设置指南

## 一、配置管理

配置管理用于备份、迁移和恢复系统配置。

### 配置项详解

| 配置项 | 含义 | 说明 |
|--------|------|------|
| **导出配置** | 将所有配置保存为 JSON 文件 | 不包含 API Key，仅导出配置结构 |
| **导入配置** | 从 JSON 文件恢复配置 | 支持合并或覆盖模式 |
| **版本历史** | 查看配置变更快照 | 支持回滚到历史版本 |

### 导出配置

导出的 JSON 文件包含：
- 供应商配置（不包含密钥）
- 代理配置
- MCP 服务配置

可用于：
- 配置备份
- 迁移到新服务器
- 分享配置（不含敏感信息）

### 导入配置

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| **合并** | 按 ID 去重，新增导入项，同 ID 覆盖 | 补充配置、增量迁移 |
| **覆盖** | 完全替换现有配置 | 全新部署、完全迁移 |

导入前会显示预览：
- 将导入的供应商数量
- 将导入的代理数量

### 版本历史

系统会保存配置变更历史：
- 记录每次保存的配置快照
- 显示保存时间和变更说明
- 支持回滚到任意历史版本

### 回滚操作

1. 打开「设置」→「配置管理」→「版本历史」
2. 选择要回滚的版本
3. 点击「回滚」按钮
4. 确认回滚操作

回滚会恢复该版本的所有配置（供应商、代理、MCP）。

### 客户端配置管理

系统支持管理外部客户端工具（Claude Code、Codex）的配置，通过智控助手或 API 操作：

| 操作 | 说明 |
|------|------|
| **检测** | 检查客户端工具是否已安装、当前配置指向哪个代理 |
| **预览** | 写入前查看配置内容 |
| **写入** | 将代理地址和认证信息写入客户端配置文件（写入前自动备份） |
| **测试** | 向代理发送测试请求，验证连通性 |
| **备份** | 查看客户端配置的历史备份列表 |
| **恢复** | 从备份恢复客户端配置文件 |

## 二、主题设置

主题设置用于自定义界面的外观配色。

### 主题配置

| 主题 | 特点 | 适用场景 |
|------|------|----------|
| **深色**（默认） | 深色背景，浅色文字 | 夜间使用、减少眼睛疲劳 |
| **浅色** | 浅色背景，深色文字 | 白天使用、高对比度需求 |
| **午夜紫** | 紫色调的深色主题 | 个性化、创意工作 |
| **森林绿** | 绿色调的深色主题 | 放松、自然感 |
| **日落橙** | 橙色调的深色主题 | 温暖、活力感 |
| **海洋青** | 青色调的深色主题 | 科技感、专业感 |
| **樱花粉** | 粉色调的深色主题 | 甜美、柔和感 |

### 切换主题

| 方式 | 操作 |
|------|------|
| **设置页面** | 「设置」→「外观」→「主题」下拉框选择 |
| **快捷切换** | 点击侧边栏底部的月亮图标切换深色/浅色 |

切换立即生效，无需保存。

## 三、子智能体设置

子智能体设置控制 `delegate_task` 委派任务时的行为和权限。

### 基本参数

| 配置项 | 含义 | 默认值 | 说明 |
|--------|------|--------|------|
| **最大并发数** | 同时运行的子任务数量上限 | 3 | 范围 1-10 |
| **最大轮次** | 每个子代理的最大工具调用轮次 | 5 | 范围 1-100 |
| **超时时间（秒）** | 单个子任务的执行超时 | 300 | 范围 10-600 |

### 工具权限配置

子智能体的工具权限分为两类：

| 类型 | 含义 | 默认值 | 说明 |
|------|------|--------|------|
| **阻止工具** | 对子代理完全不可见的工具 | `delegate_task, create_agent, update_agent, delete_agent, reload_agents, write_client_config, restore_client_backup` | 子代理无法看到也无法调用 |
| **拒绝工具** | 对子代理可见但调用时自动拒绝的工具 | `execute_command, write_file, edit_file` | 子代理能看到工具说明，会尝试调用但被拒绝，提示换其他方式完成 |

**配置格式**：多个工具名用英文逗号分隔，如 `delegate_task, execute_command`

**权限设计原理**：
- 阻止工具：防止子代理递归委派，避免无限嵌套
- 拒绝工具：让子代理知道有这些能力但不允许使用，引导它用更安全的方式完成任务（如用 read_file 读取内容而非 execute_command 读取）

### 沙盒隔离

每个子任务运行在独立的沙盒目录中：

| 隔离措施 | 说明 |
|----------|------|
| 文件写入 | `write_file` 和 `edit_file` 只能操作沙盒目录内的文件 |
| 命令执行 | `execute_command` 在沙盒中被完全禁用 |
| 读取操作 | `read_file`、`list_directory` 等读操作不受限制 |
| 自动清理 | 子任务完成后，沙盒目录自动删除 |

### 修改生效

所有子智能体设置修改后**立即生效**，无需重启服务。下一次 `delegate_task` 调用将使用新配置。

## 四、记忆管理

记忆系统用于让智能体在对话之间保持上下文和个性化。

### 记忆类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **记忆** | 系统级记忆，关于项目的事实和偏好 | "使用 DeepSeek 作为主力供应商" |
| **用户** | 用户级记忆，关于用户的信息 | "用户是后端开发，偏好 Python" |
| **人设** | 智能体的角色定义（SOUL.md） | "你是一个专业的 API 管理助手" |

### 管理方式

| 操作 | 界面 | 工具 |
|------|------|------|
| 查看所有记忆 | 「设置」→「记忆」 | `get_memory` |
| 保存记忆 | 对话中自然表达 | `save_memory` |
| 读取二级记忆详情 | — | `read_memory` |
| 搜索记忆 | — | `search_memory` |
| 编辑/删除记忆 | 「设置」→「记忆」 | `edit_memory` |
| 编辑人设 | 「设置」→「记忆」→「人设」 | `update_soul` |

### 记忆存储

记忆存储在 `~/.protocol-proxy/` 目录下：
- `SOUL.md` — 智能体人设
- `memory/MEMORY_TIER1.md` — 一级经验记忆（始终注入上下文）
- `memory/USER_TIER1.md` — 一级用户画像（始终注入上下文）
- `memory/MEMORY_TIER2.json` — 二级经验记忆（按需加载，JSON 条目数组）
- `memory/USER_TIER2.json` — 二级用户画像（按需加载，JSON 条目数组）

## 五、开机自启

开机自启功能让系统在 Windows 用户登录时自动启动服务，无需手动运行。

### 管理方式

| 操作 | 界面 | 工具 | CLI |
|------|------|------|-----|
| 查看状态 | 「设置」→「开机自启动」复选框 | `get_autostart_status` | `protocol-proxy autostart status` |
| 开启自启 | 勾选复选框 | `toggle_autostart`（enabled=true） | `protocol-proxy autostart on` |
| 关闭自启 | 取消勾选 | `toggle_autostart`（enabled=false） | `protocol-proxy autostart off` |

### 说明

- 仅支持 Windows 系统，通过注册表 `HKCU\...\Run` 实现
- 注册的是当前可执行文件路径（打包版）或 `node server.js --daemon`（源码版）
- 修改立即生效，无需重启服务

## 六、执行策略

执行策略控制子智能体可以执行哪些 shell 命令，通过规则匹配引擎评估每条命令。

### 策略规则类别

| 类别 | 含义 | 说明 |
|------|------|------|
| **allow** | 允许执行 | 命令匹配后直接执行，无需用户确认 |
| **prompt** | 需要确认 | 命令匹配后弹出确认框，用户批准后执行 |
| **forbidden** | 禁止执行 | 命令匹配后直接拒绝，不可执行 |

### 管理方式

| 操作 | 界面 | 工具 |
|------|------|------|
| 查看策略概览 | 「设置」→「执行策略」 | `get_exec_policy` |
| 查看完整规则列表 | 「设置」→「执行策略」 | `get_exec_policy_rules` |
| 测试命令 | 「设置」→「执行策略」→「测试」 | `test_exec_policy` |
| 添加规则 | 「设置」→「执行策略」→「添加规则」 | `add_exec_policy_rule` |
| 删除规则 | 「设置」→「执行策略」→ 删除按钮 | `remove_exec_policy_rule` |

### 规则匹配

- 规则支持通配符 `*`，如 `git *` 匹配所有 git 命令
- 用户自定义规则优先于默认规则
- 同一类别下可有多条规则，任一匹配即生效
