# Jarvis自助配置规则

本规则指导Agent如何通过自然语言描述智能修改Jarvis配置文件。

## 📋 规则概述

当用户提供自然语言配置需求时，Agent应按照以下流程操作：

1. 读取当前配置文件和schema
2. 解析用户自然语言，提取配置意图
3. 将意图映射到具体配置路径和值
4. 验证配置合法性
5. 安全修改配置文件

## 🔄 工作流程

### 步骤1：信息收集

**必需操作**：

- 读取用户配置文件：`~/.jarvis/config.yaml`
- 读取配置schema：`{{ jarvis_src_dir }}/src/jarvis/jarvis_data/config_schema.json`
- 如果需要，参考配置处理逻辑：`{{ jarvis_src_dir }}/src/jarvis/jarvis_utils/config.py`

**目的**：

- 了解当前配置结构
- 获取配置项的定义和约束
- 理解配置项之间的关系

### 步骤2：自然语言解析

**解析目标**：

- 识别用户想要修改的配置项
- 提取配置的新值
- 判断操作类型：新增、修改、删除
- 识别嵌套结构（如llms中的具体模型配置）

**解析方法**：

- 使用LLM语义理解能力
- 识别配置相关的关键词（模型、API、开关、路径等）
- 理解配置层级关系（如：llms -> qwen3-coder-plus -> platform）

**常见配置类型**：

- 模型配置（llms、llm_groups）
- 嵌入模型配置（embeddings、rag_groups）
- 功能开关（enable\_\*）
- 路径配置（_\_dirs、_\_repo）
- 环境变量（ENV）

### 步骤3：配置映射

**映射原则**：

- 将自然语言描述转换为YAML配置路径
- 保留原有的配置结构
- 维护配置项之间的引用关系

**映射示例**：

```yaml
用户："把默认模型改成qwen3-coder-plus"
映射：llm_group: "qwen3"

用户："添加一个新的OpenAI模型配置"
映射：llms.
  new-model:
    platform: openai
    model: gpt-4
    ...
```

**注意事项**：

- 对于引用型配置（如llm_groups中的normal_llm），确保引用的对象存在于对应的位置
- 对于嵌套配置，保持正确的缩进和层级
- 对于列表配置，确保格式正确

### 步骤4：配置验证

**验证内容**：

1. **Schema验证**
   - 配置项名称是否存在于schema中
   - 配置值类型是否符合schema定义
   - 必需字段是否完整

2. **引用验证**
   - llm_groups中的引用是否存在于llms中
   - rag_groups中的引用是否存在于embeddings/rerankers中

3. **逻辑验证**
   - 配置值是否在合理范围内
   - 布尔值是否为true/false
   - 路径是否合法

**验证失败处理**：

- 明确指出验证失败的原因
- 提供修正建议
- 询问用户是否继续或修改

### 步骤5：安全修改

**修改原则**：

- **最小改动**：只修改用户明确要求的配置项
- **保留结构**：不改变配置文件的整体结构
- **保留注释**：如果有注释，尽量保留

**修改方法**：

1. 备份原始配置（可选，但推荐）
2. 使用edit_file工具进行精确修改
3. 提供足够的上下文确保唯一匹配
4. 修改前向用户展示变更摘要

**修改示例**：

```python
# 修改单个配置项
search: "llm_group: code"
replace: "llm_group: qwen3"

# 修改嵌套配置
search: |-
  qwen3:
    normal_llm: qwen3-coder-plus
    cheap_llm: ''
    smart_llm: ''
replace: |-
  qwen3:
    normal_llm: qwen3-coder-plus
    cheap_llm: qwen3-coder-plus
    smart_llm: qwen3-max
```

### 步骤6：结果确认

**确认内容**：

- 展示修改前后的配置对比
- 说明修改的影响范围
- 提醒用户可能需要重启Jarvis以生效

## ⚠️ 安全注意事项

### 敏感配置处理

**API密钥**：

- 如果用户提供API密钥，直接使用
- 如果用户要求修改已有密钥，谨慎确认
- 不要泄露或暴露敏感信息

**环境变量**：

- ENV配置会设置到系统环境变量
- 修改前告知用户可能的影响

### 配置完整性

**引用完整性**：

- 修改llms时，检查是否有llm_groups引用
- 修改embeddings时，检查是否有rag_groups引用
- 如果删除被引用的配置，同时更新引用

**默认值处理**：

- 如果用户未指定某些字段，使用schema中的默认值
- 不要删除原有的配置项，除非用户明确要求

## 🚨 错误处理

### 常见错误类型

1. **配置项不存在**
   - 检查拼写是否正确
   - 提供相似的配置项名称
   - 引导用户查看schema

2. **引用错误**
   - 引用的配置不存在
   - 引用的配置已被删除
   - 检查llms、embeddings、rerankers中的定义

3. **类型错误**
   - 配置值类型不匹配
   - 根据schema定义修正类型

4. **格式错误**
   - YAML格式错误
   - 缩进错误
   - 引号或转义错误

### 回滚机制

**建议回滚时机**：

- 修改失败时
- 配置验证不通过时
- 用户不满意时

**回滚方法**：

- 使用git恢复（如果有版本控制）
- 恢复备份文件
- 手动撤销修改

## 📝 交互示例

### 示例1：修改默认模型组

**用户输入**：

```text
把默认模型组改成qwen3
```

**Agent操作**：

1. 读取config.yaml，找到llm_group配置
2. 理解用户意图：将llm_group的值改为qwen3
3. 验证qwen3是否存在于llm_groups中
4. 修改配置：`llm_group: qwen3`
5. 确认修改成功

### 示例2：添加新的模型配置

**用户输入**：

```text
添加一个新的OpenAI模型，名称是gpt-4-turbo，模型名是gpt-4-turbo-2024-04-09
API地址是<https://api.openai.com/v1>
```

**Agent操作**：

1. 解析用户意图：在llms中添加新配置
2. 提取配置信息：
   - 名称：gpt-4-turbo
   - platform：openai
   - model：gpt-4-turbo-2024-04-09
   - openai_api_base：<https://api.openai.com/v1>
3. 根据schema确定需要的字段
4. 在llms下添加新配置
5. 验证配置合法性
6. 应用修改

### 示例3：修改功能开关

**用户输入**：

```text
启用构建验证功能
```

**Agent操作**：

1. 理解用户意图：启用enable_build_validation
2. 在schema中查找该配置项
3. 修改配置：`enable_build_validation: true`
4. 确认修改成功

## 💡 最佳实践

1. **充分理解**：在修改前确保完全理解用户意图

2. **逐步验证**：每步操作都进行验证，避免累积错误

3. **清晰沟通**：向用户清晰说明将要进行的修改

4. **安全第一**：对不确定的操作先询问用户

5. **保持一致**：保持配置文件的风格和格式一致

## 🎯 验收标准

- ✅ 成功解析用户自然语言配置需求

- ✅ 准确映射到配置路径和值

- ✅ 配置修改符合schema定义

- ✅ 引用关系保持完整

- ✅ 提供清晰的修改前后对比

- ✅ 配置文件格式正确，可被系统正常加载
