social-app/docs/plans/2026-03-02-config-restructuring-plan.md

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/ 2. 移除 CrewAITemplate.prompts 字段 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. 更新路径构造 2. 移除 prompts 目录创建 3. 移除 prompts 相关断言

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

agents.yaml - 补充 backstory

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

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 - 置空

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. 验证方式

# 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