数据分析Agent提示词工程完全指南：Dash模块化指令系统与语义模型注入深度拆解

数据分析Agent提示词工程完全指南Dash模块化指令系统与语义模型注入深度拆解【免费下载链接】dashA self-learning data agent built with systems engineering principles. It grounds answers in 6 layers of context and improves with every query.项目地址: https://gitcode.com/gh_mirrors/dash62/dash想让数据分析Agent真正可用核心不在模型而在提示词工程指令如何分工、上下文如何注入、业务语义如何进入系统提示词。Dash 是一个自我学习的数据分析 Agent用模块化指令系统给三个角色Leader / Analyst / Engineer分别编写提示词并通过语义模型注入把表结构、指标定义、数据质量坑点自动拼进 Analyst 的 Prompt。这篇文章带你完整拆解这套 Prompt 架构的设计思路。为什么你的数据分析 Agent 回答总在幻觉直接用大模型写 SQL 的 Agent通常会翻车在这些地方❌ 表名、列名靠猜字段含义全凭模型脑补❌ 不懂 MRR、NRR 这些业务指标在你们公司的确切定义❌ 踩过同一个坑比如 NULL 值陷阱却永远记不住❌ 返回一堆数字却读不出任何结论Dash 的思路是提示词不是写死的长文本而是角色指令 动态注入的语义模型的组合产物。模块化指令系统三个角色三段独立指令 Dash 采用 Leader 协调模式coordinate mode一个 Leader 负责路由Analyst 负责查询Engineer 负责建视图。每个角色的指令在 dash/instructions.py 中各自独立定义再按需组装。角色职责指令核心内容Leader路由分发、结果综合路由决策表、拆解规则、安全红线、语气规范Analyst写 SQL、查数据、给洞察六步工作流、SQL 规则只读、超越数字的洞察要求Engineer建视图、做数据资产双 Schema 权限、变更必须记录到知识库几个值得借鉴的提示词设计细节1. 用表格代替大段描述做路由Leader 指令里直接用 Markdown 表格写明什么请求 → 派给谁例如Whats our MRR? → AnalystCreate a monthly MRR view → Engineer。这比一段自然语言描述路由规则稳定得多还能在 evals/cases/routing.py 中被自动化评测。2. 明确写负面清单Analyst 指令直接列出 SQL 禁区禁止DROP / DELETE / UPDATE / INSERT禁止SELECT *默认LIMIT 50。规则越具体越不容易被模型自由发挥。3. 给好/坏输出对照示例Analyst 指令中有一张 Bad/Good 对照表坏示例是Starter: 12% churn好示例是Starter 月流失率 12%是 Enterprise 的 3 倍取消前一周用量下降 60%。用示例定义什么叫洞察比形容词更有效。4. 语气也是工程的一部分指令甚至规定了行文风格短句、像同事对话、不用破折号、不绕弯子。提示词工程不只是让 Agent 答对还包括让它说得像人。团队组装逻辑见 dash/team.py三个 Agent 的定义分别在 dash/agents/analyst.py 和 dash/agents/engineer.py。语义模型注入让 Agent读懂你的表 这是 Dash 提示词工程最有价值的一环。数据字典不放在 Prompt 里手写而是存在结构化 JSON 文件中启动时自动格式化为 Prompt 片段。数据源是knowledge/目录下的三类文件目录内容示例文件knowledge/tables/表含义、列说明、质量坑点customers.jsonknowledge/business/指标定义、业务规则、常见坑metrics.jsonknowledge/queries/验证过的 SQL 模式common_queries.sql以 knowledge/tables/customers.json 为例它不只描述表还写明了陷阱signup_date是 DATE 类型没有时间成分status只有active / churned / trial三个值company_size是客户自报数据加载逻辑在 dash/context/semantic_model.py扫描目录下所有 JSON提取表名、描述、列、用途和数据质量备注最多 5 条防止 Prompt 膨胀。注入后的 Prompt 长这样由 format_semantic_model 生成### customers B2B SaaS customer accounts — company info and lifecycle status. **Columns:** - signup_date (DATE) — Account creation date - status (TEXT) — Current status: active, churned, trial **Use cases:** Churn analysis, Cohort segmentation **Data quality:** - signup_date is DATE (not TIMESTAMP) — no time componentmetrics.json 还会贡献另外三块内容METRICSMRR、NRR、CLV 等的精确定义和计算公式、BUSINESS RULES如年度账单客户享 10% 折扣、COMMON GOTCHAS如30% 已解决工单没有满意度评分AVG 会忽略 NULL。这些正是把部落知识变成可复用上下文的关键。动态组装一次函数调用拼出完整 Prompt 静态指令只是底座。真正发给模型的 Prompt 由 build_analyst_instructions 动态拼接ANALYST_INSTRUCTIONS静态角色指令 SEMANTIC MODEL6 张表的语义模型 BUSINESS CONTEXT指标 规则 坑点三个 builder 函数各管一段dash/instructions.py函数组装内容特点build_leader_instructions()路由指令 Slack 能力说明按是否配置 Slack Token 动态选段落build_analyst_instructions()角色指令 语义模型 业务上下文上下文最全是注入主力build_engineer_instructions()角色指令 源表语义模型只看源表保持精简这套设计的好处很直观改表结构不用改代码——更新 JSON 重新加载即可不同角色拿到不同精度的上下文——Leader 不需要表细节Analyst 需要全部避免每个 Agent 都背一整个万能 Prompt。双知识系统静态知识 动态学习 Dash 把上下文分成两套并行的记忆定义在 dash/settings.py系统存什么谁来维护Knowledgedash_knowledge验证过的 SQL、表元数据、业务规则人工 Agent 共同维护Learningsdash_learnings报错模式、类型陷阱、修复方案Learning Machine 自动沉淀Analyst 的六步工作流就建立在这套机制上查知识 → 查学习记录 → 写 SQL → 执行 → 报错则内省 Schema 并保存学习 → 成功后提供洞察。同样的错不会犯第二次这是自我学习的落地方式。配套的评测体系evals/cases/覆盖准确性、路由、安全、治理、边界 5 个维度保证每次提示词调整后能力不退化——提示词工程离不开回归测试。快速上手跑起 Dash 并观察它的提示词git clone https://gitcode.com/gh_mirrors/dash62/dash cd dash cp example.env .env # 填入 OPENAI_API_KEY docker compose up -d --build docker exec -it dash-api python scripts/generate_data.py docker exec -it dash-api python scripts/load_knowledge.py启动后试试这些问题来自 README 的 SaaS 指标数据集Whats our current MRR?Which plan has the highest churn rate?Which customers are at risk of churning?想亲手观察注入效果本地运行python -m dash或在 dash/instructions.py 的 builder 函数中打印返回值即可看到静态指令 语义模型的完整成品。新手可直接抄走的 6 条实践清单 ✅指令模块化每个 Agent 角色一份独立指令不要写单一上帝 Prompt表格化路由用请求类型 → 处理者的映射表替代模糊的自然语言分发规则语义模型文件化表元数据、指标定义放 JSONPrompt 只做格式化拼接注入坑点而非只注入结构数据质量备注是 Text-to-SQL 准确率的最大杠杆好/坏示例对照用 Bad/Good 示例定义输出质量比形容词指令有效提示词变更要配评测像跑单测一样跑 Prompt 回归参考 docs/TEST_QUESTIONS.md 与 evals/run.py常见问题 FAQQ语义模型注入会不会撑爆上下文Dash 做了两处控制质量备注每张表最多 5 条MAX_QUALITY_NOTES且 Leader 完全不注入表元数据只有真正干活的 Analyst/Engineer 才拿全量上下文。Q只读限制靠提示词还是靠系统两者都要但系统兜底Analyst 的数据库连接以default_transaction_read_onlyon启动PostgreSQL 层面拒绝一切写入——提示词管行为基础设施管底线。Q这套架构和直接让模型连数据库有什么区别区别就是那 6 层上下文表语义、业务规则、验证过的查询、学习记录、运行时内省以及报错即学习的闭环。模型没变变的是它每次推理时手里握有的信息。Dash 用系统工程的纪律做提示词工程指令分模块、上下文分层注入、错误自动沉淀、改动可评测。把这些搬进你自己的数据分析 Agent答非所问的概率会肉眼可见地下降。更多设计演进思路可参考 docs/IMPROVE_DASH.md。【免费下载链接】dashA self-learning data agent built with systems engineering principles. It grounds answers in 6 layers of context and improves with every query.项目地址: https://gitcode.com/gh_mirrors/dash62/dash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考