---
url: /wave-agent/specs/commands/builtin-settings-skill.md
description: 内置 `settings` 技能，查看与修改各作用域 settings.json，并提供 hook 编写指导
---

# 功能规格说明：内置 Settings Skill

**创建日期**：2026-03-18

## 用户场景与测试 *（必填）*

### 用户故事：通过 Skill 管理 Wave 设置（优先级：P1）

作为用户，我希望能够使用简单的 skill 命令查看和修改我的 Wave 设置（用户、项目或本地），这样就不必手动查找和编辑 JSON 文件。

**为什么是这个优先级**：这是请求的核心功能。通过简化配置管理提供即时价值。

**独立测试**：可以通过运行 `settings` skill 并验证它可以读取和更新不同作用域中的设置来进行完整测试。

**验收场景**：

1. **假设**我有一个 `settings.json` 文件，**当**我运行 `settings` skill 查看配置时，**则**它应显示来自所有适用作用域的当前设置。
2. **假设**我想更改一个设置（例如 `language`），**当**我使用 `settings` skill 更新它时，**则**相应的 `settings.json`（或 `settings.local.json`）应被正确更新。

***

### 用户故事：settings.json 编写指导（优先级：P2）

作为用户，我希望 `settings` skill 提供如何编写 `settings.json` 的指导和文档，包括可用字段及其含义。

**为什么是这个优先级**：改善用户体验和配置选项的可发现性。

**独立测试**：可以通过使用帮助或指南命令调用 `settings` skill 并验证输出包含有用信息来进行测试。

**验收场景**：

1. **假设**我不确定如何配置特定字段，**当**我向 `settings` skill 请求指导时，**则**它应提供清晰的说明和示例。

***

### 用户故事：复杂 Hook 的文档（优先级：P3）

作为用户，我希望复杂 hook 配置的详细文档在单独的文件中可用，从主 skill 文档链接，这样我就可以了解如何使用高级功能而不会使主指南变得混乱。

**为什么是这个优先级**：高级用户需要这些信息，但最好单独保持清晰。

**独立测试**：验证复杂 hook 的单独 markdown 文件存在并从 `SKILL.md` 链接。

**验收场景**：

1. **假设**我想配置复杂 hook，**当**我阅读 settings skill 的 `SKILL.md` 时，**则**我应找到指向 hook 配置详细指南的链接。

***

### 边界情况

* 当 `settings.json` 文件损坏或包含无效 JSON 时会发生什么？
* 当同一设置在多个作用域中定义时，系统如何处理冲突？
* 如果用户尝试为设置设置无效值（例如无效的 `defaultMode`）会怎样？