企业官网建设流程全解析

DB-GPT Skill 实战指南：任务识别、load_skill 加载与工具链路编排

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

本篇指南聚焦 DB-GPT 中 Skill（技能包）的实际使用方式：讲清楚智能体在一次会话中如何识别任务该用哪个 skill、如何加载其指令、按什么工具链路执行，并最终渲染出报告。读完本文，你将掌握load_skill等内置工具的典型调用组合、财报分析与 CSV/Excel 分析两大真实场景的执行路径，并能结合仓库源码理解 skill 的渐进式加载机制与校验规则。

基本使用流程

在 DB-GPT 的实际使用中，skill 遵循一条固定的五步模式：

1. 识别：先识别当前任务适合哪个 skill。智能体在系统提示词中只看到每个 skill 的名称与描述（元数据），根据用户请求与描述的匹配程度判断是否有合适的 skill 可用。
2. 加载：加载该 skill 的说明和指令，即读取对应SKILL.md的完整内容。
3. 执行：按照 skill 定义的工作流逐步执行。
4. 调用工具：调用 skill 所需的内置工具（如sql_query、code_interpreter等）。
5. 交付：返回最终结果，或者渲染最终报告。

渐进式披露：先看描述，需要时才读全文

这条流程与仓库源码中的设计是一一对应的。从根目录的 skills.py 可以看到，DB-GPT 采用“渐进式披露（Progressive Disclosure）”模式：SkillsMiddleware在构造系统提示词时，只注入每个 skill 的名称、描述和SKILL.md路径，而不会把所有 skill 的完整指令一次性塞进上下文：

# skills.py 中的 system prompt 模板节选 **How to Use Skills (Progressive Disclosure):** 1. **Recognize when a skill applies**: Check if the user's task matches a skill's description 2. **Read the skill's full instructions**: Use the path shown in the skill list above 3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples 4. **Access supporting files**: Skills may include helper scripts, configs, or reference docs - use absolute paths

具体实现上：

• SkillsLoader.load_skills()按顺序扫描配置的多个 skill 源目录（后加载的同名 skill 会覆盖先加载的），把每个包含SKILL.md的子目录解析为LoadedSkill对象；
• SkillsLoader.match_skills(user_input)提供了基于描述的关键词匹配能力，用于从用户输入推断候选 skill；
• SkillsMiddleware.create_skills_prompt_section()负责把“skill 位置 + skill 列表 + 使用说明”渲染进系统提示词。

这种“先发现、再按需完整加载”的设计，让智能体在 skill 数量增多时上下文开销依然可控——这也解释了为什么使用流程的第一步是“识别”，第二步才是“加载全文”。

被加载的 skill 长什么样

被加载的对象是仓库skills/目录下一个个自包含的能力包。以财报分析技能 skills/financial-report-analyzer/SKILL.md 为例，其头部是标准的 YAML frontmatter 元数据：

--- name: financial-report-analyzer description: 专门用于上市公司财报（如年度报告、季度报告）的深度分析。该技能能够自动提取关键财务指标，计算核心财务比率，生成可视化图表，并结合行业背景生成专业的财务分析报告。 ---

description不仅是展示文案，更是第一步“识别”的依据。skills.py 中对元数据有明确约束，编写或导入 skill 时需要满足：

常见工具链路

根据 skill 类型不同，执行路径通常由以下内置工具串联完成：

• load_skill→ 加载 skill 指令
• sql_query→ 在需要时获取结构化数据
• code_interpreter→ 计算指标、转换数据、生成图表
• shell_interpreter→ 在需要时执行 shell 命令
• html_interpreter→ 渲染最终 HTML 报告或页面

load_skill：链路的起点

load_skill是整个链路的第一环。按照 load_skill 工具文档，它按 skill 名称和文件路径加载 skill 内容（通常是SKILL.md中的指令），入参为：

{ "skill_name": "skill name", "file_path": "skill file path" }

它的工作是：从注册表中解析出该 skill → 读取指令或 prompt 模板 → 把加载到的工作流内容返回给智能体。文档同时特别强调了两点边界：

• load_skill只加载指令，不执行工作流本身；
• 加载完成后，智能体应当严格遵循该 skill 要求的工具与步骤。

文档给出的典型示例正好对应仓库中的真实 skill：

{ "skill_name": "financial-report-analyzer", "file_path": "skills/financial-report-analyzer/SKILL.md" }

各工具在链路中的分工可以这样理解：sql_query负责“取数”（面向数据库的结构化查询），code_interpreter负责“算数”（Python 计算与图表生成），shell_interpreter负责“执行环境操作”，html_interpreter负责“交付呈现”。一个 skill 的工作流本质上就是对这四个环节的一次编排。

示例场景一：财报分析

智能体处理财报任务时的完整链路：

1. 加载 financial-report skill；
2. 执行需要的数据提取与分析步骤；
3. 生成图表与指标结果；
4. 使用html_interpreter渲染最终报告。

这条链路在仓库中不是示意，而是有完整落地的 financial-report-analyzer skill。对照其SKILL.md，可以看到一个典型的“多步工具编排 + 报告渲染”工作流：

1. 数据提取与结构化：执行scripts/extract_financials.py，传入财报文件路径，提取营收、净利润、资产、负债等核心数值，返回 JSON；
2. 财务比率计算：执行scripts/calculate_ratios.py，计算毛利率、净利率、ROE、资产负债率等，输出模板占位符键值，并参考references/financial_metrics.md保证指标定义准确；
3. 图表生成：执行scripts/generate_charts.py，自动产出 3 张可视化图表（核心指标柱状图、盈利能力横向条形图、资产结构环形饼图），系统将图片复制到静态目录并记录 URL 映射；
4. 深度分析：遵循references/analysis_framework.md，从盈利质量、偿债风险、营运效率和现金流四个维度撰写 7 段分析文本；
5. 渲染报告：调用html_interpreter的template_path模式，指定financial-report-analyzer/templates/report_template.html模板并传入分析文本：

{ "template_path": "financial-report-analyzer/templates/report_template.html", "data": { "PROFITABILITY_ANALYSIS": "LLM撰写的盈利能力分析...", "SOLVENCY_ANALYSIS": "LLM撰写的偿债分析...", "EFFICIENCY_ANALYSIS": "LLM撰写的营运效率分析...", "CASHFLOW_ANALYSIS": "LLM撰写的现金流分析...", "ADVANTAGES_LIST": "<li>优势1</li><li>优势2</li>", "RISKS_LIST": "<li>风险1</li><li>风险2</li>", "OVERALL_ASSETTMENT": "LLM撰写的综合评价..." }, "title": "XX公司 2023年度财报分析报告" }

值得注意的是该 skill 的一个工程细节：data字典中只需传入 LLM 撰写的 7 段分析文本，此前步骤产出的 30 个数据指标与图片 URL 映射由后端自动合并。这正是“skill 定义工作流顺序 + 内置工具各司其职”的体现。

示例场景二：CSV / Excel 分析

智能体处理数据文件任务时的链路：

1. 加载一个数据分析 skill；
2. 检查上传文件；
3. 使用 Python 分析计算指标并可视化结果；
4. 如果需要，再将结果渲染为报告。

与财报场景的区别在于：这里通常不需要sql_query（数据来自上传文件而非数据库），核心链路收缩为load_skill→ 文件检查 →code_interpreter（Python 计算与可视化）→ 可选的html_interpreter报告渲染。仓库中对应参考 csv-data-analysis 与 walmart-sales-analyzer 两个 skill，前者提供通用 CSV 分析工作流，后者展示了“脚本生成图表 + HTML 模板报告”的完整交付形态。

最佳实践

原文档给出的四条实践建议，结合上述机制可以落地为更具体的检查清单：

• 当工作流需要可重复时，优先使用 skill——skill 的价值在于把“一次成功的执行路径”固化下来，而不是每次让模型临场发挥；
• 严格遵循 skill 中定义的指令——load_skill加载的是约束而非建议，步骤顺序、参数传递（如上例中 Step 1 的 JSON 传给 Step 2/Step 3）都应照做；
• 优先使用 skill 指定的工具，而不是临时替代方案——例如 skill 指定用html_interpreter的模板模式渲染报告时，就不要改用自由生成 HTML；
• 当 skill 产出网页或报告时，优先使用html_interpreter做最终渲染——它是交付环节的默认出口。

延伸阅读

• dbgpts Introduction：skill 的定义、包结构（SKILL.md/scripts//references//assets/）与“为什么 skill 重要”的完整说明
• Tools Overview：智能体工具体系总览
• Built-in tools：内置工具文档目录
• load_skill 工具文档：load_skill参数与使用边界
• skills.py：skill 加载器、元数据校验与系统提示词注入的源码实现
• how-to-use-custom-skill.md：如何创建自定义 skill

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT