Developer Guide

开发指南 / Developer Guide

中英双语 | Bilingual

---

中文

项目结构

data_agent/
├── app.py              # Chainlit 主入口 (3,422 行)
├── agent.py            # Agent 定义、管道组装
├── intent_router.py    # 语义意图路由
├── frontend_api.py     # 134 REST API (2,649 行)
├── toolsets/            # 28 个工具集 (29 文件)
├── skills/             # 18 个 ADK 技能 (SKILL.md)
├── fusion/             # 融合引擎 (26 文件)
├── connectors/         # 6 个连接器 (7 文件)
├── api/                # API 路由拆分 (9 文件)
├── prompts/            # Agent 提示词 (4 YAML)
├── migrations/         # 数据库迁移 (30 SQL)
└── test_*.py           # 测试 (95 文件, 29,346 行)

添加新工具集

1. 在 toolsets/ 创建 my_tools.py，继承 BaseToolset
2. 在 __init__.py 的 TOOLSET_NAMES 列表中注册
3. 编写测试 test_my_tools.py

编写 ADK Skill

1. 在 skills/ 创建目录（kebab-case），如 my-skill/
2. 创建 SKILL.md，YAML frontmatter 含 name, description, domain, version, intent_triggers
3. 可选添加 references/ 和 assets/ 子目录

运行测试

.venv/Scripts/python.exe -m pytest data_agent/ --ignore=data_agent/test_knowledge_agent.py -q

Mock 模式

始终在导入位置 mock get_engine：@patch("data_agent.memory.get_engine", return_value=None)

构建前端

cd frontend && npm install && npm run build

CI/CD

GitHub Actions: test -> frontend -> evaluation -> route-eval

---

English

Project Structure

Same as above with English descriptions.

Adding a New Toolset

1. Create my_tools.py in toolsets/, extend BaseToolset
2. Register in __init__.py TOOLSET_NAMES
3. Write tests

Writing an ADK Skill

1. Create kebab-case directory in skills/
2. Create SKILL.md with YAML frontmatter
3. Optionally add references/ and assets/

Running Tests

.venv/Scripts/python.exe -m pytest data_agent/ --ignore=data_agent/test_knowledge_agent.py -q

Mock Patterns

Always mock at import site: @patch("data_agent.memory.get_engine", return_value=None)

Building Frontend

cd frontend && npm install && npm run build

CI/CD

GitHub Actions: test -> frontend -> evaluation -> route-eval