# 配置与自定义 (/zh-CN/docs/verdent-for-vscode/configuration/settings)

> 自定义 Verdent 以适配你的工作流



Verdent for VS Code 提供丰富的配置选项，以适配你的开发工作流、编码偏好和团队规范。你可以通过 VS Code 原生设置界面配置选项、自定义键盘快捷键，并创建规则和子智能体以实现专门化的行为。

### 你将学到 [#你将学到]

* 为 Verdent 配置 VS Code 扩展设置
* 自定义键盘快捷键以提升工作流效率
* 创建并管理规则以个性化智能体行为
* 构建自定义子智能体处理专门任务

### 前置条件 [#前置条件]

* 已安装并通过认证的 Verdent for VS Code
* VS Code 设置访问权限（`Cmd+,` 或 `Ctrl+,`）
* 对规则文件 JSON 的基本理解（可选）

***

## VS Code 扩展设置 [#vs-code-扩展设置]

Verdent for VS Code 的设置可通过多个位置访问，具体取决于配置类型和作用范围。

### 访问设置 [#访问设置]

**扩展设置（VS Code 原生）：**

1. 打开 VS Code 设置：`Cmd+,`（macOS）或 `Ctrl+,`（Windows/Linux）
2. 在设置搜索栏中搜索 "Verdent"
3. 修改扩展设置（例如 `verdent.enableCheckpoints`）

**Verdent 专属设置：**

点击 Verdent 顶部栏中的 **Settings** 按钮以访问：

* **Rules** - 用户规则、项目规则、计划规则
* **MCP Servers** - Model Context Protocol 配置
* **Subagents** - 自定义子智能体管理

**对话内控制：**

许多设置可以直接从 Verdent 面板底部的输入框切换：

* **Switch Permission** - 手动接受、自动运行、计划、跳过权限
* **Switch Mode** - Agent、Plan、Chat 模式
* **Switch/Customize AI Model** - 性能、平衡、效率预设
* **Think Hard Mode** - 为复杂推理提供最大思考预算
* **Add Context** - 使用 @ 提及附加文件
* **Add Images or Files** - 包含截图或文档
* **Add Subagent** - 委派给专门的子智能体

设置更改会立即生效，无需重启 VS Code。

***

## 可用的扩展设置 [#可用的扩展设置]

Verdent for VS Code 提供 **2 项核心扩展设置**，可通过 VS Code 的设置界面进行配置：

| 设置                          | 类型        | 默认值    | 描述                                       |
| --------------------------- | --------- | ------ | ---------------------------------------- |
| `verdent.enableCheckpoints` | `boolean` | `true` | 启用扩展在任务过程中使用 git 保存工作区检查点。在大型工作区上可能影响性能。 |
| `verdent.enableProxy`       | `boolean` | `true` | 为网络连接启用代理支持。位于企业防火墙或代理服务器后的用户需要此设置。      |

<Note>
  这些是 Verdent 的完整 VS Code 扩展设置。其他配置选项（规则、子智能体、MCP 服务器）通过扩展顶部栏的 Verdent 设置菜单进行管理。
</Note>

***

## 输入框控件参考 [#输入框控件参考]

Verdent 面板底部的输入框提供对配置控件的快速访问：

| 控件                            | 用途          | 选项                                         |
| ----------------------------- | ----------- | ------------------------------------------ |
| **Add Context**               | 使用 @ 提及附加文件 | @文件名、@文件夹名                                 |
| **Add Images or Files**       | 包含截图或文档     | 上传图片、PDF、文本文件                              |
| **Add Subagent**              | 委派给专门的智能体   | @Verifier、@Explorer、@Code-reviewer、自定义子智能体 |
| **Switch Mode**               | 切换执行模式      | Agent Mode、Plan Mode、Chat Mode             |
| **Switch/Customize AI Model** | 选择模型预设或特定模型 | 性能（1-2 倍成本）、平衡（1 倍成本）、效率（0.3 倍成本）          |
| **Think Hard Mode**           | 启用扩展推理      | 为复杂问题切换开/关                                 |
| **Switch Permission**         | 更改权限级别      | 手动接受（默认）、自动运行、计划、跳过权限                      |

### 权限模式 [#权限模式]

<Tabs>
  <Tab title="手动接受（默认）">
    * 每个操作都需要批准
    * 完全可见性与控制
    * 最适合：学习、不熟悉的代码库、生产代码
  </Tab>

  <Tab title="自动运行">
    * 命令需要批准，文件操作自动执行
    * 减少权限提示
    * 最适合：受信任的项目、快速原型开发
  </Tab>

  <Tab title="计划">
    * 只读分析与规划
    * 规划期间不修改代码
    * 最适合：复杂变更、架构决策
  </Tab>

  <Tab title="跳过权限">
    * 完全自主，无需批准提示
    * 执行最快但风险最高
    * 最适合：自动化环境、CI/CD
  </Tab>
</Tabs>

### 模型预设 [#模型预设]

<Tabs>
  <Tab title="平衡（默认）">
    * **成本：** 1 倍基准
    * **模型：** Claude-4.5-sonnet
    * **最适合：** 通用开发、日常编码、功能实现
  </Tab>

  <Tab title="性能">
    * **成本：** 平衡基准的 1-2 倍
    * **模型：** Claude-4.5-sonnet-1m（100 万 token 上下文）
    * **最适合：** 复杂架构、大型代码库、超过 20 万 token 的任务
  </Tab>

  <Tab title="效率">
    * **成本：** 比 Sonnet 高 3.2 倍效率（节省 70% 积分）
    * **模型：** Claude-4.5-haiku
    * **最适合：** 快速修复、简单任务、常规操作
  </Tab>
</Tabs>

***

## 键盘快捷键自定义 [#键盘快捷键自定义]

### 默认快捷键 [#默认快捷键]

**主要快捷键：**

* **macOS：** `Cmd+L` - 打开/聚焦 Verdent 面板
* **Windows/Linux：** `Ctrl+L` - 打开/聚焦 Verdent 面板
  * 命令：`verdent.addToChat`
  * 可从命令面板和编辑器上下文使用

这是从 VS Code 任何位置快速访问 Verdent 而不打断编码流程的关键快捷键。

**其他命令：**

可通过命令面板使用（默认快捷键可自定义）：

* `verdent.addFeedBack` - 提供反馈
* `verdent.addTerminalOutputToChat` - 将终端输出添加到 Verdent
* `verdent.addToChatBySearch` - 通过搜索添加到 Verdent
* `verdent.centerButtonClicked` - 用户中心
* `verdent.historyButtonClicked` - 项目历史
* `verdent.mcpButtonClicked` - 添加 MCP 服务器
* `verdent.openInNewTabByParams` - 在新标签页中打开
* `verdent.plusButtonClicked` - 新会话
* `verdent.rulesButtonClicked` - 规则设置
* `verdent.SettingClicked` - 设置菜单
* `verdent.subagentButtonClicked` - 添加子智能体

### 自定义快捷键 [#自定义快捷键]

所有 Verdent 键盘快捷键都可以使用 VS Code 的标准键绑定系统进行自定义。

<Tabs>
  <Tab title="键盘快捷键编辑器（UI）">
    推荐大多数用户使用 - 用于管理快捷键的可视化界面。

    <Steps>
      <Step title="打开键盘快捷键">
        按 `Cmd+K Cmd+S`（macOS）或 `Ctrl+K Ctrl+S`（Windows/Linux）
      </Step>

      <Step title="搜索 Verdent">
        在搜索框中输入 "Verdent" 以筛选 Verdent 命令
      </Step>

      <Step title="编辑快捷键">
        点击任意命令旁的铅笔图标，按下你想要的组合键，然后按 Enter 保存
      </Step>
    </Steps>
  </Tab>

  <Tab title="keybindings.json（高级）">
    适合高级用户 - 直接 JSON 配置，便于版本控制。

    <Steps>
      <Step title="打开命令面板">
        按 `Cmd+Shift+P`（macOS）或 `Ctrl+Shift+P`（Windows/Linux）
      </Step>

      <Step title="打开键绑定 JSON">
        输入 "Preferences: Open Keyboard Shortcuts (JSON)" 并选择它
      </Step>

      <Step title="添加自定义键绑定">
        <CodeGroup>
          ```json macOS
          {
            "key": "cmd+shift+v",
            "command": "verdent.addToChat"
          }
          ```

          ```json Windows/Linux
          {
            "key": "ctrl+shift+v",
            "command": "verdent.addToChat"
          }
          ```
        </CodeGroup>
      </Step>
    </Steps>
  </Tab>
</Tabs>

**自定义范围：**

* 所有 Verdent 命令都可以重新映射
* 可以为同一命令分配多个快捷键
* 可以移除默认快捷键
* 更改通过 VS Code 设置同步在各设备间同步

### 平台专属快捷键 [#平台专属快捷键]

Verdent 遵循 VS Code 的平台专属键盘约定：

| 平台                | 修饰键模式                       |
| ----------------- | --------------------------- |
| **macOS**         | `Cmd` 用于主要快捷键，`Option` 用于备选 |
| **Windows/Linux** | `Ctrl` 用于主要快捷键，`Alt` 用于备选   |

**常见模式：**

* 设置：`Cmd+,`（macOS）对比 `Ctrl+,`（Windows/Linux）
* 命令面板：`Cmd+Shift+P`（macOS）对比 `Ctrl+Shift+P`（Windows/Linux）
* 键盘快捷键：`Cmd+K Cmd+S`（macOS）对比 `Ctrl+K Ctrl+S`（Windows/Linux）

***

## 自定义指令与人格 [#自定义指令与人格]

Verdent for VS Code 支持两种自定义 AI 行为的系统：用于偏好和指导原则的**规则**，以及用于专门任务人格的**子智能体**。

### 规则系统 [#规则系统]

规则定义 Verdent 在编码会话期间的行为和响应方式。规则存储在 Markdown 文件中，并在整个对话过程中持续应用。

#### 三种类型的规则 [#三种类型的规则]

**1. 用户规则（VERDENT.md）：**

* **位置：** `~/.verdent/`（全局配置目录）
* **范围：** 应用于所有项目的所有对话
* **用途：** 个人编码偏好、沟通风格、文档规范

**2. 项目规则（AGENTS.md）：**

* **位置：** 项目根目录或工作区
* **范围：** 仅应用于当前项目
* **版本控制：** 可提交到 git 以实现团队级规范
* **用途：** 项目专属编码规范、架构模式、测试要求

**3. 计划规则（plan\_rules.md）：**

* **位置：** `~/.verdent/`（全局配置目录）
* **范围：** 在所有项目中使用 Plan Mode 时应用
* **用途：** 自定义计划内容、格式和详细程度

#### 创建和编辑规则 [#创建和编辑规则]

<Steps>
  <Step title="访问规则设置">
    点击 Verdent 顶部栏中的 **Settings** 按钮，并从下拉菜单中选择 **Rules**
  </Step>

  <Step title="选择规则类型">
    根据你的需求选择 **User Rules**、**Project Rules** 或 **Plan Rules**
  </Step>

  <Step title="以 Markdown 编辑">
    规则文件在 VS Code 编辑器中打开。使用 Markdown 格式编写清晰、明确的指令
  </Step>

  <Step title="保存并应用">
    保存文件。规则在当前和未来会话中立即应用——无需重启
  </Step>
</Steps>

**用户规则示例：**

```markdown
# Code Style Preferences
- Always use functional React components with hooks
- Prefer TypeScript over JavaScript
- Add JSDoc comments for all exported functions
- Provide explanations before showing code
```

**项目规则示例：**

```markdown
## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` to run all checks
- Fix test and type errors until suite is green
- Add or update tests for code changes

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing
```

#### 规则存储与应用 [#规则存储与应用]

| 规则类型 | 位置                         | 范围              | 版本控制        |
| ---- | -------------------------- | --------------- | ----------- |
| 用户规则 | `~/.verdent/VERDENT.md`    | 所有项目            | 个人，不共享      |
| 项目规则 | `<project>/AGENTS.md`      | 当前项目            | 可提交以保持团队一致性 |
| 计划规则 | `~/.verdent/plan_rules.md` | 所有项目（Plan Mode） | 个人，不共享      |

**配置优先级：**

当规则冲突时，Verdent 应用以下优先级顺序：

1. **项目规则（AGENTS.md）** - 最高优先级（项目专属）
2. **用户规则（VERDENT.md）** - 全局用户偏好
3. **默认行为** - Verdent 的内置默认值

<Tip>
  将 AGENTS.md 提交到版本控制，以便与整个团队共享项目专属的编码规范。每位团队成员的工作区都会自动遵循项目规则，同时通过 VERDENT.md 保持各自的个人偏好。
</Tip>

***

## 子智能体 [#子智能体]

子智能体是具有自定义系统提示词和独立上下文窗口的专门 AI 智能体，用于处理特定任务。

### 内置子智能体 [#内置子智能体]

Verdent 包含三个默认子智能体，无需配置即可立即使用：

<Tabs>
  <Tab title="@Verifier">
    * 快速代码检查和验证
    * 无需完整审查的快速验证
    * 用于：快速合理性检查、语法验证、提交前检查
  </Tab>

  <Tab title="@Explorer">
    * 快速代码库探索和导航
    * 快速查找文件并回答代码库问题
    * 用于：探索不熟悉的代码库、查找组件、理解结构
  </Tab>

  <Tab title="@Code-reviewer">
    * 即时代码质量评估
    * 识别安全性、可维护性和性能方面的问题
    * 用于：提交前审查、安全审计、性能优化
  </Tab>
</Tabs>

### 创建自定义子智能体 [#创建自定义子智能体]

<Steps>
  <Step title="访问子智能体设置">
    点击 Verdent 顶部栏中的 **Settings** → **Subagents**
  </Step>

  <Step title="创建新子智能体">
    创建新的子智能体，或导航至 `~/.verdent/subagents/` 并创建带有 YAML frontmatter 的 markdown 文件
  </Step>

  <Step title="定义子智能体行为">
    编写系统提示词，确立子智能体的人格、解读风格和任务处理方法
  </Step>

  <Step title="指定调用策略">
    定义何时应使用该子智能体（严格或灵活调用）
  </Step>
</Steps>

**子智能体文件格式：**

```markdown
---
name: security-reviewer
description: Security-focused code review specialist
---
# System Prompt

You are a security-focused code reviewer. When analyzing code:
- Prioritize security vulnerabilities (SQL injection, XSS, auth flaws)
- Use skeptical, critical tone - assume code is vulnerable until proven otherwise
- Provide specific remediation steps with code examples
- Reference OWASP Top 10 and security best practices
- Never approve code with unresolved security issues

Invocation policy (strict): Only run security-reviewer if user explicitly requests it.

When to use the security-reviewer agent:
- User requests security review of authentication/authorization logic
- User asks to audit code for vulnerabilities
- User needs security assessment before deployment

When NOT to use:
- General code review without security focus
- Opening or reading files without analysis
```

### 管理子智能体 [#管理子智能体]

通过 **Settings → Subagents** 访问以：

* **编辑：** 修改系统提示词、工具权限、配置
* **复制：** 复制子智能体以创建变体或模板
* **删除：** 移除未使用的子智能体
* **启用/禁用：** 在不删除的情况下切换可用性

### 使用子智能体 [#使用子智能体]

**内置子智能体：**

* 用 @ 提及引用：`@Verifier`、`@Explorer`、`@Code-reviewer`
* 在检测到合适的任务类型时自动调用

**自定义子智能体：**

* 点击输入框中的 **Add Subagent** 按钮
* 从下拉菜单中选择
* 主智能体自动委派合适的任务

### 子智能体 vs 规则 [#子智能体-vs-规则]

| 方面       | 规则       | 子智能体          |
| -------- | -------- | ------------- |
| **应用时机** | 持续，每次响应  | 针对特定任务按需      |
| **上下文**  | 共享主上下文窗口 | 独立的单独上下文      |
| **行为**   | 偏好和指导原则  | 任务专属的行为人格     |
| **调用**   | 始终激活     | 自动或手动委派       |
| **用途**   | 定义你偏好什么  | 定义谁处理任务以及如何处理 |

**示例工作流：**

1. **用户规则：** "为所有新函数生成单元测试"
2. **主智能体：** 检测到生成测试的需求
3. **委派给测试生成器子智能体：** 专门的全面测试方法
4. **子智能体：** 以独立上下文生成完整测试套件
5. **主智能体：** 接收结果并继续，不污染上下文

<Tip>
  通过 Settings → Subagents 中的 **Copy** 按钮，或直接从 `~/.verdent/subagents/` 共享子智能体 markdown 文件，将子智能体分享给团队成员。
</Tip>

***

## 常见问题（FAQ） [#常见问题faq]

<Accordion title="配置更改何时生效？">
  大多数 Verdent 设置无需重启即可立即生效：

  * **权限模式：** 通过输入框即时切换
  * **模型预设：** 应用于下一个请求
  * **规则文件：** 应用于新对话（保存会触发重新加载）
  * **子智能体：** 创建后立即可用
  * **键盘快捷键：** 在 VS Code 中保存后应用

  **例外：** VS Code 扩展设置（如 `verdent.enableCheckpoints`）会立即生效，但可能需要重新打开文件或会话才能完全应用。
</Accordion>

<Accordion title="规则和子智能体有什么区别？">
  **规则**全局定义你偏好什么：

  * 持续应用于所有对话
  * 编码规范、沟通风格、偏好
  * 存储在 markdown 文件中（VERDENT.md、AGENTS.md、plan\_rules.md）
  * 始终在后台激活

  **子智能体**定义谁处理特定任务以及如何处理：

  * 针对特定任务类型按需调用
  * 具有自定义系统提示词的专门行为人格
  * 独立上下文窗口（不污染主上下文）
  * 自动委派或通过 @ 提及手动委派

  **示例：** 规则说"为新函数生成单元测试"。测试生成器子智能体则以全面的测试方法处理实际的测试创建。
</Accordion>

<Accordion title="我可以同时使用多个权限模式吗？">
  不可以，权限模式是互斥的——你一次只能使用一种：

  * **手动接受** - 默认，最大控制
  * **自动运行** - 为受信任的项目精简流程
  * **计划** - 只读规划模式
  * **跳过权限** - 完全自主

  你可以通过输入框中的 **Switch Permission** 按钮即时切换模式。大多数用户根据任务上下文在模式间切换（例如，复杂功能用 Plan Mode，快速修复用自动运行）。
</Accordion>

<Accordion title="如何为我的任务选择合适的模型预设？">
  将模型预设与任务复杂度和预算匹配：

  **使用效率（比 Sonnet 高 3.2 倍效率）：**

  * 快速修复 bug 和简单代码生成
  * 常规操作和高频任务
  * 当速度比深度更重要时

  **使用平衡（1 倍基准）- 默认：**

  * 通用开发和日常编码
  * 功能实现和代码审查
  * 适合大多数场景的均衡性能

  **使用性能（0.5 倍效率，2 倍成本）：**

  * 复杂的架构决策
  * 需要大量上下文的大型代码库（20 万+ token）
  * 复杂的调试和重构

  **专业提示：** 大多数用户将平衡保持为默认，仅在达到上下文限制或需要深度推理时才切换到性能。
</Accordion>

***

## 参见 [#参见]

<CardGroup cols="2">
  <Card title="计划优先工作流" icon="sitemap" href="/docs/verdent-for-vscode/configuration/plan-workflows">
    配置 AI 辅助的任务规划和审批工作流
  </Card>

  <Card title="配置优化" icon="sliders" href="/docs/verdent-for-vscode/configuration/tuning">
    调整设置以优化速度、成本和性能
  </Card>
</CardGroup>