# aide config 设计

## 一、命令概述

### 1.1 功能定位

`aide config` 命令用于读取和修改项目配置文件，提供命令行方式访问配置。

### 1.2 执行时机

- 用户需要查看配置值时
- 用户需要修改配置值时
- Commands 中需要获取配置时（如 prep/exec 的默认文档路径）

### 1.3 命令格式

```bash
aide config get <key>
aide config set <key> <value>
```

**参数**：
- `<key>`：配置键，支持点号分隔（如 `task.source`）
- `<value>`：配置值（仅 set 命令需要）

---

## 二、功能需求

### 2.1 aide config get

**功能**：获取配置值

**输出格式**：

单个值：
```
task.source = "task-now.md"
```

数组值：
```
flow.phases = ["flow-design", "impl", "verify", "docs", "finish"]
```

布尔值：
```
env.tools.git = true
```

**错误处理**：

配置键不存在：
```
✗ 配置键不存在: invalid.key
  可用的配置键: task.source, task.spec, env.python.version
```

配置文件不存在：
```
✗ 配置文件不存在
  位置: .aide/config.toml
  建议: 运行 'aide init' 创建配置文件
```

### 2.2 aide config set

**功能**：设置配置值

**输出**：

成功时无输出（静默原则）

**错误处理**：

配置键不存在：
```
✗ 配置键不存在: invalid.key
  可用的配置键: task.source, task.spec, env.python.version
```

配置值类型错误：
```
✗ 配置值类型错误
  键: env.tools.git
  期望类型: boolean
  实际值: "yes"
  建议: 使用 true 或 false
```

---

## 三、实现设计

### 3.1 函数接口

```python
def cmd_config(args: list[str]) -> int:
    """aide config 命令处理

    Args:
        args: 命令参数

    Returns:
        退出码（0 表示成功）
    """
    pass

def config_get(key: str) -> int:
    """获取配置值

    Args:
        key: 配置键

    Returns:
        退出码
    """
    pass

def config_set(key: str, value: str) -> int:
    """设置配置值

    Args:
        key: 配置键
        value: 配置值（字符串形式）

    Returns:
        退出码
    """
    pass
```

### 3.2 实现流程

#### 3.2.1 cmd_config

```python
from core.output import err

def cmd_config(args: list[str]) -> int:
    """aide config 命令处理"""

    if not args:
        err(
            "缺少子命令",
            [
                "用法: aide config get <key>",
                "      aide config set <key> <value>"
            ]
        )
        return 2

    subcommand = args[0]

    if subcommand == "get":
        if len(args) < 2:
            err("缺少参数: key")
            return 2
        return config_get(args[1])

    elif subcommand == "set":
        if len(args) < 3:
            err("缺少参数: key 或 value")
            return 2
        return config_set(args[1], args[2])

    else:
        err(
            f"未知子命令: {subcommand}",
            ["可用子命令: get, set"]
        )
        return 2
```

#### 3.2.2 config_get

```python
from pathlib import Path
from core.config import Config
from core.output import err

def config_get(key: str) -> int:
    """获取配置值"""

    try:
        # 加载配置
        config = Config(Path.cwd())
        config.load()

        # 获取值
        value = config.get(key)

        if value is None:
            # 配置键不存在
            available_keys = get_available_keys(config._config)
            err(
                f"配置键不存在: {key}",
                [f"可用的配置键: {', '.join(available_keys)}"]
            )
            return 4

        # 格式化输出
        formatted_value = format_config_value(value)
        print(f"{key} = {formatted_value}")

        return 0

    except FileNotFoundError:
        err(
            "配置文件不存在",
            [
                "位置: .aide/config.toml",
                "建议: 运行 'aide init' 创建配置文件"
            ]
        )
        return 4

    except Exception as e:
        err(
            "配置读取失败",
            [f"原因: {str(e)}"]
        )
        return 4
```

#### 3.2.3 config_set

```python
def config_set(key: str, value_str: str) -> int:
    """设置配置值"""

    try:
        # 加载配置
        config = Config(Path.cwd())
        config.load()

        # 验证配置键是否存在
        if not is_valid_config_key(key):
            available_keys = get_available_keys(config._config)
            err(
                f"配置键不存在: {key}",
                [f"可用的配置键: {', '.join(available_keys)}"]
            )
            return 4

        # 解析值
        try:
            value = parse_config_value(key, value_str, config._config)
        except ValueError as e:
            err(
                "配置值类型错误",
                [
                    f"键: {key}",
                    f"原因: {str(e)}"
                ]
            )
            return 4

        # 设置值
        config.set(key, value)

        # 成功时无输出（静默原则）
        return 0

    except FileNotFoundError:
        err(
            "配置文件不存在",
            [
                "位置: .aide/config.toml",
                "建议: 运行 'aide init' 创建配置文件"
            ]
        )
        return 4

    except Exception as e:
        err(
            "配置写入失败",
            [f"原因: {str(e)}"]
        )
        return 4
```

### 3.3 辅助函数

#### 3.3.1 格式化配置值

```python
import json

def format_config_value(value) -> str:
    """格式化配置值用于输出

    Args:
        value: 配置值

    Returns:
        格式化后的字符串
    """
    if isinstance(value, str):
        return f'"{value}"'
    elif isinstance(value, bool):
        return "true" if value else "false"
    elif isinstance(value, (list, dict)):
        return json.dumps(value, ensure_ascii=False)
    else:
        return str(value)
```

#### 3.3.2 解析配置值

```python
def parse_config_value(key: str, value_str: str, config: dict):
    """解析配置值

    Args:
        key: 配置键
        value_str: 值字符串
        config: 当前配置（用于推断类型）

    Returns:
        解析后的值

    Raises:
        ValueError: 值类型错误
    """
    # 获取当前值以推断类型
    current_value = get_config_value(config, key)

    if current_value is None:
        # 新键，尝试自动推断类型
        return auto_parse_value(value_str)

    # 根据当前值的类型解析
    if isinstance(current_value, bool):
        return parse_bool(value_str)
    elif isinstance(current_value, int):
        return parse_int(value_str)
    elif isinstance(current_value, float):
        return parse_float(value_str)
    elif isinstance(current_value, list):
        return parse_list(value_str)
    elif isinstance(current_value, dict):
        return parse_dict(value_str)
    else:
        # 字符串
        return value_str

def parse_bool(value_str: str) -> bool:
    """解析布尔值"""
    lower = value_str.lower()
    if lower in ["true", "yes", "1"]:
        return True
    elif lower in ["false", "no", "0"]:
        return False
    else:
        raise ValueError(f"无效的布尔值: {value_str}，使用 true 或 false")

def parse_int(value_str: str) -> int:
    """解析整数"""
    try:
        return int(value_str)
    except ValueError:
        raise ValueError(f"无效的整数: {value_str}")

def parse_float(value_str: str) -> float:
    """解析浮点数"""
    try:
        return float(value_str)
    except ValueError:
        raise ValueError(f"无效的浮点数: {value_str}")

def parse_list(value_str: str) -> list:
    """解析列表（JSON 格式）"""
    try:
        value = json.loads(value_str)
        if not isinstance(value, list):
            raise ValueError("不是列表")
        return value
    except json.JSONDecodeError:
        raise ValueError(f"无效的列表格式: {value_str}，使用 JSON 格式")

def parse_dict(value_str: str) -> dict:
    """解析字典（JSON 格式）"""
    try:
        value = json.loads(value_str)
        if not isinstance(value, dict):
            raise ValueError("不是字典")
        return value
    except json.JSONDecodeError:
        raise ValueError(f"无效的字典格式: {value_str}，使用 JSON 格式")

def auto_parse_value(value_str: str):
    """自动推断并解析值"""
    # 尝试 JSON
    try:
        return json.loads(value_str)
    except json.JSONDecodeError:
        pass

    # 尝试布尔值
    if value_str.lower() in ["true", "false", "yes", "no"]:
        return parse_bool(value_str)

    # 尝试数字
    try:
        if "." in value_str:
            return float(value_str)
        else:
            return int(value_str)
    except ValueError:
        pass

    # 默认为字符串
    return value_str
```

#### 3.3.3 获取可用配置键

```python
def get_available_keys(config: dict, prefix: str = "") -> list[str]:
    """获取所有可用的配置键

    Args:
        config: 配置字典
        prefix: 键前缀

    Returns:
        配置键列表
    """
    keys = []

    for key, value in config.items():
        full_key = f"{prefix}{key}" if prefix else key

        if isinstance(value, dict):
            # 递归获取嵌套键
            keys.extend(get_available_keys(value, f"{full_key}."))
        else:
            keys.append(full_key)

    return sorted(keys)

def is_valid_config_key(key: str) -> bool:
    """验证配置键是否有效

    Args:
        key: 配置键

    Returns:
        是否有效
    """
    # 定义允许的配置键
    valid_keys = [
        "task.source",
        "task.spec",
        "env.python.version",
        "env.python.venv",
        "env.tools.uv",
        "env.tools.git",
        "flow.phases",
        "flow.flowchart_dir",
        "decide.port",
        "decide.decisions_dir",
        "output.color",
        "output.language"
    ]

    return key in valid_keys
```

---

## 四、错误处理

### 4.1 错误分类

| 错误类型 | 退出码 | 处理方式 |
|---------|--------|---------|
| 缺少参数 | 2 | 显示用法 |
| 配置文件不存在 | 4 | 提示运行 aide init |
| 配置键不存在 | 4 | 显示可用的键 |
| 配置值类型错误 | 4 | 显示期望类型和建议 |
| 配置文件格式错误 | 4 | 显示错误位置 |

### 4.2 类型验证

```python
def validate_config_value(key: str, value) -> list[str]:
    """验证配置值

    Args:
        key: 配置键
        value: 配置值

    Returns:
        错误列表（空列表表示无错误）
    """
    errors = []

    # 验证特定键的值
    if key == "env.python.version":
        if not isinstance(value, str):
            errors.append("env.python.version 必须是字符串")
        elif not is_valid_version_spec(value):
            errors.append(f"无效的版本格式: {value}")

    elif key == "env.python.venv":
        if not isinstance(value, str):
            errors.append("env.python.venv 必须是字符串")

    elif key in ["env.tools.uv", "env.tools.git", "output.color"]:
        if not isinstance(value, bool):
            errors.append(f"{key} 必须是布尔值")

    elif key == "flow.phases":
        if not isinstance(value, list):
            errors.append("flow.phases 必须是数组")
        elif not all(isinstance(p, str) for p in value):
            errors.append("flow.phases 的元素必须是字符串")

    elif key == "decide.port":
        if not isinstance(value, int):
            errors.append("decide.port 必须是整数")
        elif not (1024 <= value <= 65535):
            errors.append("decide.port 必须在 1024-65535 之间")

    return errors
```

---

## 五、测试用例

### 5.1 config get 测试

```python
def test_config_get_success(tmp_path, monkeypatch, capsys):
    """测试获取配置成功"""
    monkeypatch.chdir(tmp_path)

    # 初始化配置
    cmd_init([])

    # 获取配置
    result = config_get("task.source")

    # 验证退出码
    assert result == 0

    # 验证输出
    captured = capsys.readouterr()
    assert 'task.source = "task-now.md"' in captured.out

def test_config_get_not_found(tmp_path, monkeypatch, capsys):
    """测试配置键不存在"""
    monkeypatch.chdir(tmp_path)

    # 初始化配置
    cmd_init([])

    # 获取不存在的配置
    result = config_get("invalid.key")

    # 验证退出码
    assert result == 4

    # 验证输出
    captured = capsys.readouterr()
    assert "配置键不存在" in captured.out

def test_config_get_no_config(tmp_path, monkeypatch, capsys):
    """测试配置文件不存在"""
    monkeypatch.chdir(tmp_path)

    # 获取配置（未初始化）
    result = config_get("task.source")

    # 验证退出码
    assert result == 4

    # 验证输出
    captured = capsys.readouterr()
    assert "配置文件不存在" in captured.out
```

### 5.2 config set 测试

```python
def test_config_set_success(tmp_path, monkeypatch):
    """测试设置配置成功"""
    monkeypatch.chdir(tmp_path)

    # 初始化配置
    cmd_init([])

    # 设置配置
    result = config_set("task.source", "new-task.md")

    # 验证退出码
    assert result == 0

    # 验证配置已更新
    config = Config(tmp_path)
    config.load()
    assert config.get("task.source") == "new-task.md"

def test_config_set_bool(tmp_path, monkeypatch):
    """测试设置布尔值"""
    monkeypatch.chdir(tmp_path)

    # 初始化配置
    cmd_init([])

    # 设置布尔值
    result = config_set("env.tools.uv", "true")
    assert result == 0

    # 验证
    config = Config(tmp_path)
    config.load()
    assert config.get("env.tools.uv") == True

def test_config_set_invalid_type(tmp_path, monkeypatch, capsys):
    """测试设置错误类型"""
    monkeypatch.chdir(tmp_path)

    # 初始化配置
    cmd_init([])

    # 设置错误类型
    result = config_set("env.tools.git", "yes")

    # 验证退出码
    assert result == 4

    # 验证输出
    captured = capsys.readouterr()
    assert "类型错误" in captured.out
```

### 5.3 值解析测试

```python
def test_parse_bool():
    """测试布尔值解析"""
    assert parse_bool("true") == True
    assert parse_bool("false") == False
    assert parse_bool("yes") == True
    assert parse_bool("no") == False

    with pytest.raises(ValueError):
        parse_bool("invalid")

def test_parse_list():
    """测试列表解析"""
    result = parse_list('["a", "b", "c"]')
    assert result == ["a", "b", "c"]

    with pytest.raises(ValueError):
        parse_list("not a list")

def test_auto_parse_value():
    """测试自动解析"""
    assert auto_parse_value("true") == True
    assert auto_parse_value("123") == 123
    assert auto_parse_value("3.14") == 3.14
    assert auto_parse_value('["a"]') == ["a"]
    assert auto_parse_value("text") == "text"
```

---

## 六、使用示例

### 6.1 查看配置

```bash
# 查看任务文档路径
aide config get task.source

# 查看 Python 版本要求
aide config get env.python.version

# 查看流程环节列表
aide config get flow.phases
```

### 6.2 修改配置

```bash
# 修改任务文档路径
aide config set task.source "my-task.md"

# 修改 Python 版本要求
aide config set env.python.version ">=3.11"

# 启用 uv
aide config set env.tools.uv true

# 修改端口
aide config set decide.port 8080
```

---

## 七、性能要求

### 7.1 执行时间

- config get：< 100ms
- config set：< 200ms

### 7.2 资源占用

- 内存：< 20MB
- 磁盘 I/O：最小化

---

## 八、总结

### 8.1 核心要点

1. 支持 get 和 set 两个子命令
2. 点号分隔的键访问
3. 自动类型推断和验证
4. 静默原则（set 成功时无输出）
5. 清晰的错误信息

### 8.2 实现检查清单

- [ ] 实现 cmd_config 函数
- [ ] 实现 config_get 函数
- [ ] 实现 config_set 函数
- [ ] 实现值格式化函数
- [ ] 实现值解析函数
- [ ] 实现类型验证
- [ ] 编写单元测试
- [ ] 编写集成测试
- [ ] 性能测试

---

**版本**：v1.0
**更新日期**：2025-12-13