7.4 基于扣子编程的实现过程

7.4.1  扣子编程的工作范式

扣子编程是面向AI原生应用的编程工作台。与通用代码生成工具不同，扣子编程的工作范式有两个突出特征：其一是集成（Integration）优先，平台预置了数据库、对象存储、消息队列、大模型等常用基础设施的集成组件，开发者通过查询集成文档即可获得标准化的调用方式；其二是工具（Tool）中心，所有外部能力最终都以工具的形式挂载到 Agent 上，由大模型按需调用。这种范式使得开发者能够把更多精力投入在业务逻辑与提示词设计上，而非基础设施搭建。

7.4.2  集成组件的识别与选用

在接收到本项目的需求描述后，扣子编程并未立刻开始写代码，而是先并行查询了三个集成文档：PostgreSQL 数据库集成、S3 对象存储集成与大语言模型集成。如图7-2所示。

图7-2 三个集成构建页面

这一动作背后的工程思路是——先判断平台是否已有现成轮子，再决定是否自研。查询结果识别出三项关键事实：数据库集成中已存在一个系统工具 exec_sql，可直接执行原始 SQL；对象存储集成提供 S3SyncStorage 接口，支持文件上传与签名 URL 生成；大模型集成推荐使用 doubao-seed-1-8-251228 多模态模型，适配带有图表理解需求的数据分析场景。

【经验】  让 Agent 自主查集成文档，而不是凭训练记忆写代码，能显著降低“幻觉调用”的风险（即调用了不存在的 API 或参数）。这是 AI 原生编程工作台与普通代码助手的重要差异。

7.4.3  工具实现一：SQL 执行工具

虽然平台已提供 exec_sql 系统工具，但按工程规范，Agent 的所有外部能力都应以工具（Tool）形式在 src/tools/ 目录下集中注册管理。因此，扣子编程在 src/tools/execute_sql_tool.py 下为 exec_sql 创建了一个薄封装。这个封装本身逻辑不复杂，核心作用是把系统工具正式挂载到LangChain工具注册表中，使得Agent在推理过程中可以发现并调用它。如图7-3所示。

图7-3 导入并封装数据库查询与图表生成工具

7.4.4  工具实现二：图表生成工具

相比 SQL 工具，图表生成工具（src/tools/create_chart_tool.py）是本项目的技术核心，承担了三项关键职责：图表绘制、中文字体降级、图像上传。下面以伪代码形式给出其核心实现片段。

# 中文字体降级链

CJK_FONTS = [

    "SimHei", "Microsoft YaHei", "PingFang SC",

    "Noto Sans CJK SC", "WenQuanYi Zen Hei", "Arial Unicode MS"

]

 

def set_cjk_font():

    available = {f.name for f in fm.fontManager.ttflist}

    for font in CJK_FONTS:

        if font in available:

            plt.rcParams["font.family"] = font

            plt.rcParams["axes.unicode_minus"] = False

            return font

    raise RuntimeError("未发现可用的中文字体")

 

# 图表类型调度

def create_chart(chart_type, data, title, x_label=None, y_label=None):

    set_cjk_font()

    fig, ax = plt.subplots(figsize=(9, 5), dpi=120)

    if chart_type == "line":

        draw_line(ax, data)

    elif chart_type == "bar":

        draw_bar(ax, data)

    elif chart_type == "pie":

        draw_pie(ax, data)

    # ... 散点图、直方图同理

    ax.set_title(title)

    if x_label: ax.set_xlabel(x_label)

    if y_label: ax.set_ylabel(y_label)

 

    # 保存到本地临时目录

    local_path = f"/tmp/chart_{uuid4().hex}.png"

    fig.savefig(local_path, bbox_inches="tight")

 

    # 上传到对象存储并返回可访问 URL

    url = s3.upload_file(local_path, bucket="charts")

    return f""

该工具支持折线图、柱状图、饼图、散点图、直方图五种类型，能够覆盖绝大多数日常分析需求。返回值是 Markdown 图片语法字符串，可直接嵌入到报告段落中。

7.4.5  Agent 主体编排

工具就绪后，需要编写Agent主体并配置其运行参数，如图7-4所示。

图7-4 agent.python项目代码页面

扣子编程在 src/agents/agent.py 中实现了 build_agent 函数，并同步生成配置文件 config/agent_llm_config.json。关键配置项如表 7-2 所示。

表 7-2  数据分析 Agent 的关键配置

配置项	取值	设计理由
模型	doubao-seed-1-8-251228	多模态优化，能同时理解结构化表格与图像语义
温度	0.7	兼顾 SQL 生成的准确性与报告文笔的自然度
短期记忆	最近 20 轮对话	数据分析多轮追问频繁，过短会丢失上下文
工具列表	execute_sql + create_chart	与两个自建工具一一对应，无冗余

系统提示词（System Prompt）的结构遵循四段式：角色定义、任务目标、能力描述、工作流程与输出规范。其中，工作流程段规定了 Agent 的标准行为序列——先探查表结构，再撰写 SQL，得到数据后根据分析主题决定是否绘图，最后组织成四段式 Markdown 报告。输出规范段则约束了报告必须包含“数据概览、关键发现、数据可视化、结论与建议”四个模块，这是从众多真实分析场景中总结出的最小可用结构。

7.4.6  调试过程中的典型问题

项目开发过程中出现过两次典型问题，值得记录。

第一次是依赖缺失。初次运行时环境未安装 matplotlib，扣子编程检测到 ImportError 后自动执行了 pip install matplotlib，无需人工介入。这体现了 AI 原生编程工具的自闭环能力。如图7-5所示。

图7-5 matplotlib依赖包缺失自闭环

第二次是在图表工具初版代码中，色板的引用方式为 plt.cm.Set3（点号访问），运行时抛出 AttributeError。扣子编程分析堆栈后修改为 plt.cm.get_cmap("Set3") 的字符串形式，再次运行即通过。如图7-6所示。

图7-6  “错误捕获—自修复”闭环示意

这次问题揭示了两个经验：一是 Matplotlib 的 colormap API 在不同版本间有细微差异，直接属性访问并非总是可用；二是 AI 编程工具具备“错误反馈—自修复”的闭环能力，开发者不必手工介入每一个细节。