qzl
185 lines
6.3 KiB
Markdown
185 lines
6.3 KiB
Markdown
# 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
|
||
```
|