文章目录
-
- 一、概述
- 二、环境准备
-
- 2.1 所需软件与版本
- 2.2 验证 Java 环境
- 2.3 验证 Maven 环境
- 2.4 API 密钥配置
- 2.5 可选环境变量
- 三、项目架构与Maven配置
-
- 3.1 整体项目定位
- 3.2 克隆源码
- 3.3 Maven POM 配置详解
- 3.4 项目目录结构总览
- 四、工作空间（Workspace）：AgentScope Harness的核心设计
-
- 4.1 工作空间结构
- 4.2 领域知识文件：knowledge/KNOWLEDGE.md
- 4.3 技能文件：skills/*/SKILL.md
-
- 查询编写技能（skills/query-writing/SKILL.md）
- Schema 探索技能（skills/schema-exploration/SKILL.md）
- 4.4 子智能体文件：subagents/*.md
-
- 查询优化专家（subagents/query-optimizer.md）
- Schema 分析专家（subagents/schema-analyst.md）
- 五、日志配置（Log4j2）
-
- 5.1 log4j2.xml
- 5.2 log4j2.component.properties
- 5.3 运行时切换日志级别
- 六、核心实现一：SqliteTool 自定义工具
-
- 6.1 设计思路
- 6.2 完整代码实现
- 6.3 核心设计模式解析
- 七、核心实现二：WorkspaceInitializer 工作空间初始化
-
- 7.1 设计思路
- 7.2 完整代码实现
- 7.3 关键技术点
- 八、核心实现三：TextToSqlExample 主入口
-
- 8.1 整体流程
- 8.2 完整代码实现
- 8.3 HarnessAgent 构建参数详解
- 8.4 RuntimeContext 会话管理
- 九、核心实现四：QuickstartExample 简化入门
-
- 9.1 与 TextToSqlExample 的对比
- 9.2 核心代码片段
- 十、公共工具模块（harness-example-common）
-
- 10.1 ExampleUtils 主要方法
- 10.2 聊天循环工作流程
- 10.3 流式输出机制
- 十一、构建与打包
-
- 11.1 完整构建命令
- 11.2 预期构建输出
- 11.3 构建产物
- 十二、运行与测试
-
- 12.1 交互模式运行
- 12.2 单次查询模式
- 12.3 新会话模式
- 12.4 推荐测试问题
- 12.5 运行简化版 QuickstartExample
- 12.6 调试模式
- 十三、调优与扩展
-
- 13.1 自定义工作空间文件（无需重新编译）
- 13.2 更换 LLM 模型
- 13.3 使用自定义数据库
- 13.4 性能优化建议
- 13.5 添加新的自定义工具
- 13.6 添加新的技能
- 13.7 错误处理最佳实践
- 十四、常见问题排查（FAQ）
-
- Q1：启动报错 \”Required environment variable \’DASHSCOPE_API_KEY\’ is not set\”
- Q2：\”Database file not found\”
- Q3：编译报错 \”package io.agentscope.xxx does not exist\”
- Q4：运行时 \”NoClassDefFoundError\”
- Q5：智能体响应质量不佳
- Q6：Windows 特殊注意事项
- 十五、总结
一、概述
在AI大模型时代，“Text-to-SQL”（自然语言转SQL）已成为智能数据分析的核心能力之一。想象一下：你只需要问\”2023年收入最高的5位艺术家是谁？\”，AI就能自动探索数据库结构、编写正确的SQL查询、执行并返回格式化结果——这正是本文要带你实现的目标。
我们将基于阿里巴巴开源的 AgentScope Java 框架，使用其 Harness（增强运行时） 模块，从零搭建一个完整的 Text-to-SQL 命令行应用。该项目以经典的 Chinook 音乐商店数据库（SQLite）为例，通过阿里云 DashScope 大模型 API（qwen-max）驱动智能体的推理与工具调用。
适用人群：有 Java 基础的开发者、对 AI Agent 感兴趣的后端工程师、希望了解 AgentScope 框架的技术人员。
你将收获：
- 理解 AgentScope Harness 的工作空间（Workspace）机制
- 掌握 @Tool 注解将 Java 方法暴露给 LLM 调用的方法
- 学会构建完整的 AI 智能体命令行应用
- 获得可直接运行的完整项目代码
