# Config 目录重构计划

**日期**: 2026-03-02
**目标**: 重新整理 backend/src/core/config 下的配置文件，按领域分类

---

## 1. 需求背景

当前 `backend/src/core/config` 结构存在以下问题：

1. **职责不清**: `initialization` 模块放在 `core/` 根目录，但实际是配置初始化，应归属 `config/`
2. **分类粗放**: `static/agent/` 混入了不同领域的配置（LLM 目录、工具白名单、Agent 模板）
3. **配置不符规范**: CrewAI 模板缺少必要字段（backstory、expected_output），且 prompts 目录是冗余的

---

## 2. 目标结构

```
backend/src/core/
├── config/
│   ├── settings.py              # 运行时配置（不变）
│   ├── initial/
│   │   └── init_data.py        # 种子数据初始化（移动）
│   └── static/
│       ├── database/
│       │   ├── llm_catalog.yaml           # LLM 目录（移动）
│       │   └── user_agent_catalog.yaml   # 用户 Agent 种子（新增，置空）
│       └── crewai/
│           ├── agents.yaml                # Agent 定义（移动 + 补充字段）
│           ├── tasks.yaml                 # Task 定义（移动 + 补充 expected_output）
│           ├── workflow.yaml              # 工作流（移动）
│           └── tools.yaml                 # 工具白名单（移动）
└── agent/                         # 代码实现（不变）
    └── crewai/
        └── template_loader.py   # 需更新路径引用
```

---

## 3. 涉及代码清单

### 3.1 需要移动/删除的文件

| 操作 | 源路径 | 目标路径 |
|------|--------|----------|
| 移动 | `core/initialization/init_data.py` | `core/config/initial/init_data.py` |
| 移动 | `core/config/static/agent/llm_catalog.yaml` | `core/config/static/database/llm_catalog.yaml` |
| 新建 | - | `core/config/static/database/user_agent_catalog.yaml` |
| 移动 | `core/config/static/agent/crewai/agents.yaml` | `core/config/static/crewai/agents.yaml` |
| 移动 | `core/config/static/agent/crewai/tasks.yaml` | `core/config/static/crewai/tasks.yaml` |
| 移动 | `core/config/static/agent/crewai/workflow.yaml` | `core/config/static/crewai/workflow.yaml` |
| 移动 | `core/config/static/agent/tools.yaml` | `core/config/static/crewai/tools.yaml` |
| 删除 | `core/config/static/agent/crewai/prompts/` | - |

### 3.2 需要修改的代码文件

| 文件 | 修改内容 |
|------|----------|
| `core/config/initial/init_data.py` | 更新 `_default_catalog_path()` 指向 `static/database/` |
| `core/agent/crewai/template_loader.py` | 1. 更新 `_default_static_root()` 指向 `static/crewai/`<br>2. 移除 `CrewAITemplate.prompts` 字段<br>3. 移除 `_read_prompt()` 和 prompts 加载逻辑 |
| `core/runtime/cli.py` | 更新 import 路径 |
| `tests/unit/core/test_agent_init_data.py` | 更新 import 路径和路径断言 |
| `tests/unit/core/config/test_crewai_template_loader.py` | 1. 更新路径构造<br>2. 移除 prompts 目录创建<br>3. 移除 prompts 相关断言 |

### 3.3 需要更新的配置文件内容

#### agents.yaml - 补充 backstory

```yaml
intent:
  role: Intent Agent
  goal: Classify user intent and decide execution strategy
  backstory: >
    You are an expert intent classifier with deep understanding
    of user query patterns and dialogue acts. Your role is to
    analyze user input and determine the appropriate action.

execution:
  role: Execution Agent
  goal: Execute tasks with available tools
  backstory: >
    You are a skilled task executor with expertise in tool calling,
    API interactions, and result verification. You work systematically
    to complete user requests.

organization:
  role: Organization Agent
  goal: Format final response and references
  backstory: >
    You specialize in presenting results in a clear, user-friendly manner.
    You ensure responses are well-structured and actionable.
```

#### tasks.yaml - 补充 expected_output

```yaml
intent:
  description: Identify user intent and required capabilities
  expected_output: >
    Structured intent classification with intent type, confidence score,
    and recommended action plan

execution:
  description: Execute intent with tools and model calls
  expected_output: >
    Verified execution results with tool outputs, status, and any errors

organization:
  description: Format final response and references
  expected_output: >
    User-friendly response with structured output, citations, and
    clear next steps if applicable
```

#### user_agent_catalog.yaml - 置空

```yaml
agents: []
```

---

## 4. 实施步骤

### Phase 1: 移动配置文件

1. 创建 `core/config/static/database/` 目录
2. 创建 `core/config/static/crewai/` 目录
3. 移动并合并 LLM 目录配置
4. 创建空的 user_agent_catalog.yaml

### Phase 2: 更新代码引用

1. 移动 `initialization/init_data.py` → `config/initial/init_data.py`
2. 更新 `init_data.py` 中的路径函数 `_default_catalog_path()` → `static/database/`
3. 更新 `template_loader.py`:
   - 路径函数 `_default_static_root()` → `static/crewai/`
   - 移除 `_read_prompt()` 函数
   - 移除 `CrewAITemplate.prompts` 字段
   - 移除 prompts 加载逻辑
4. 更新 `cli.py` 的 import 路径
5. 删除旧的 `core/initialization/` 目录（如为空）

### Phase 4: 更新测试

1. 更新 `test_agent_init_data.py`:
   - import 路径: `core.initialization` → `core.config.initial`
   - 路径断言: `static/agent/` → `static/database/`
2. 更新 `test_crewai_template_loader.py`:
   - 路径构造: `agent/` → `crewai/`
   - 移除 prompts 目录创建代码
   - 移除 `template.prompts` 相关断言
3. 运行测试验证

---

## 5. 风险与回滚

### 风险

- 路径变更可能导致运行时找不到配置文件
- 测试路径断言需要同步更新

### 回滚方案

- 保留 git 分支，验证通过后再合并
- 如有问题，可通过 git revert 快速回滚

---

## 6. 验证方式

```bash
# 1. 运行单元测试
cd backend && uv run pytest tests/unit/core/test_agent_init_data.py tests/unit/core/config/test_crewai_template_loader.py -v

# 2. 运行 lint
cd backend && uv run ruff check src/core/config/ src/core/agent/crewai/ src/core/runtime/cli.py

# 3. 运行 typecheck
cd backend && uv run basedpyright src/core/config/ src/core/agent/crewai/ src/core/runtime/cli.py
```