Dash

一款基于系统工程原则构建的自我学习型数据代理。它将答案扎根于六层上下文，并在每次查询中不断改进。

您可以通过 Slack、终端或 AgentOS 的 Web UI 与 Dash 对话。

快速开始

# 克隆仓库
git clone https://github.com/agno-agi/dash.git && cd dash

cp example.env .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

请访问 http://localhost:8000/docs 确认 Dash 是否正在运行。

连接到 Web UI

1. 打开 os.agno.com 并登录
2. 添加 OS → 本地 → http://localhost:8000
3. 点击“连接”

试一试（SaaS 指标数据集）：

• 我们当前的 MRR 是多少？
• 哪个套餐的流失率最高？
• 请展示过去 6 个月按套餐划分的收入趋势。
• 哪些客户有流失风险？

部署到 Railway

Railway 部署使用 .env.production 文件，以将生产环境凭据与本地开发环境分开。

cp example.env .env.production
# 编辑 .env.production — 设置 OPENAI_API_KEY

第一步：部署基础设施

这将创建 Railway 项目、数据库和应用服务。在下一步添加 JWT 密钥之前，应用会一直处于崩溃循环状态——这是预期行为。

railway login
./scripts/railway_up.sh

第二步：获取 JWT 密钥

生产环境需要从 AgentOS 获取一个 JWT_VERIFICATION_KEY。您需要第 1 步中的 Railway 域名来完成此设置。

1. 复制第 1 步输出中的 Railway 域名（例如 dash-production-xxxx.up.railway.app）
2. 打开 os.agno.com 并登录
3. 添加 OS → 生产 → 粘贴您的 Railway URL
4. 进入 设置 并生成密钥对
5. 将公钥添加到 .env.production 中（用单引号括起来）：

JWT_VERIFICATION_KEY='-----BEGIN PUBLIC KEY-----
MIIBIjANBgkq...
-----END PUBLIC KEY-----'

第三步：推送环境并重新部署

./scripts/railway_env.sh
./scripts/railway_redeploy.sh

railway_env.sh 会读取 .env.production 文件，并将每个变量设置到 Railway 服务中。可以反复安全执行，且能正确处理多行值（PEM 密钥）。

生产环境操作

数据库脚本必须在 Railway 的网络内部运行（内部主机名 pgvector.railway.internal 无法从您的本地机器访问）。请使用 SSH 连接到正在运行的容器：

railway ssh --service dash
# 在容器内：
python scripts/generate_data.py
python scripts/load_knowledge.py

其他操作可在本地执行：

railway logs --service dash
railway open

为什么存在 Dash

用英语提问，得到正确且有意义的答案——这就是我们的目标。然而，直接使用大语言模型生成 SQL 很快就会遇到瓶颈：表结构缺乏语义、类型信息具有误导性、缺少组织内部的知识、无法从错误中学习，且结果缺乏解释。

根本原因在于缺乏上下文和记忆。Dash 通过六层扎实的上下文、每次查询都能改进的自我学习循环，以及专注于提供可付诸行动的洞察力，解决了这些问题。

架构：五层一体

代理式软件本质上就是用代理取代业务逻辑的普通软件。其余部分都属于系统工程范畴。Dash 由五个相互强化的层次构成。

代理工程     →  dash/team.py + dash/agents/
数据工程      →  knowledge/ + Agno 学习机 + PostgreSQL
安全工程  →  AgentOS 认证 + RBAC + 只读 SQL 强制执行
界面工程  →  app/main.py (FastAPI) + Slack + AgentOS
基础设施        →  Dockerfile + compose.yaml + scripts/

1. 代理工程

代理团队及执行流程。包括模型、指令、工具、知识以及自我学习循环。

AgentOS (app/main.py)  [调度器开启，追踪功能开启]
 ├── FastAPI / Uvicorn
 ├── Slack 接口（可选）
 └── Dash 团队 (dash/team.py, 协调模式)
     ├─ 分析师 (dash/agents/analyst.py)         读取公共数据 + Dash 数据
     │  ├─ SQLTools（只读）  → 公共模式（公司数据）
     │  ├─ introspect_schema     → 两种模式
     │  ├─ save_validated_query  → 知识库
     │  └─ ReasoningTools
     ├─ 工程师 (dash/agents/engineer.py)       读取公共数据，写入 Dash 数据
     │  ├─ SQLTools（全权限）       → Dash 模式（代理管理）
     │  ├─ introspect_schema     → 两种模式
     │  ├─ update_knowledge      → 知识库（模式变更）
     │  └─ ReasoningTools
     │
     领导者工具：SlackTools（可选）
     知识：    dash_knowledge（表结构、查询、业务规则、Dash 视图）
     学习成果：    dash_learnings（错误模式、类型陷阱、修复方法）

2. 数据工程

上下文即数据。记忆即数据。知识也即数据。这一切都通过数据工程原则来管理：精心设计的模式、结构化的查询以及用于快速读写的数据库。

六个层次的扎实上下文：

层次	目的	来源
表使用情况	模式、列、关系	knowledge/tables/*.json
人工标注	指标、定义、业务规则	knowledge/business/*.json
查询模式	已知有效的 SQL	knowledge/queries/*.sql
机构知识	文档、维基、外部参考	MCP（可选）
学习记录	错误模式及发现的修复方法	Agno 的 Learning Machine
运行时上下文	实时模式变更	introspect_schema 工具

自我学习循环：

用户问题
     ↓
检索知识 + 学习记录
     ↓
推理意图
     ↓
生成有依据的 SQL
     ↓
执行并解释结果
     ↓
 ┌────┴────┐
 ↓         ↓
成功    错误
     ↓         ↓
     ↓         诊断 → 修复 → 保存学习记录
     ↓                           （不再重复）
     ↓
返回洞察
     ↓
可选：保存为知识

两种互补的系统：

系统	存储内容	如何演进
知识库	经验证的查询和业务上下文	由您和 Dash 共同维护
学习库	错误模式及修复方法	由 Learning Machine 自动管理

双重模式约束： 在公司数据与代理管理的数据之间设置结构性边界。

模式	所有者	访问权限
public	公司（外部加载）	只读 — 代理绝不会修改
dash	工程师代理	视图、汇总表、计算数据

工程师构建可重用的数据资产（如 dash.monthly_mrr、dash.customer_health_score、dash.churn_risk），并将它们记录到知识库中。分析师会发现并更倾向于使用这些视图，而非直接查询原始表。

3. 安全工程

在生产环境中，身份验证采用基于角色的访问控制（RBAC）结合 JWT 验证。每条查询都会限定在 user_id 范围内。只读权限是工具配置的一部分，而非提示指令。分析师代理的 SQL 工具在系统层面被限制为只读。

有关设置详情，请参阅 安全。

4. 界面工程

一个代理定义，多种接入方式。Dash 可通过 REST API（FastAPI）、Slack 线程以及 AgentOS Web UI 访问。每种接入方式都有独立的身份认证体系：Slack 用户 ID 通过线程时间戳映射到会话，而 API 则使用基于 JWT 的认证。

5. 基础设施工程

Dockerfile、Docker Compose，一键部署。定时任务用于主动行为。基础设施层刻意保持简单。运行代理的 95% 流程与其他服务无异。

Slack

Dash 可接收 Slack 私信、@提及和线程回复，也能主动发布消息到频道。

快速设置步骤：

1. 启动 Dash 并为其分配一个公网 URL（本地使用 ngrok，或您的 Railway 域名）。
2. 按照 docs/SLACK_CONNECT.md 中的说明，从清单文件创建并安装 Slack 应用程序。
3. 设置 SLACK_TOKEN 和 SLACK_SIGNING_SECRET，然后重启 Dash。
4. 在 Slack 中，确认事件订阅已验证，并发送一条私信或 @提及以测试连接。

每个 Slack 线程对应一个 Dash 会话。关于清单文件、ngrok 命令、Railway 部署、权限及故障排除，请参阅 docs/SLACK_CONNECT.md。

数据模型（SaaS 指标）

合成的 B2B SaaS 数据集（约 900 个客户，两年数据）：

表	描述
customers	公司信息、行业、规模、获客渠道、状态
subscriptions	方案、MRR、席位数、计费周期、生命周期状态
plan_changes	升级、降级、取消及其对 MRR 的影响
invoices	计费记录、支付状态、计费期间
usage_metrics	每日 API 调用次数、活跃用户数、存储量、报表
support_tickets	优先级、类别、解决时间、满意度

添加知识

Dash 在理解贵组织如何讨论数据时表现最佳。

knowledge/
├── tables/      # 表的含义及注意事项
├── queries/     # 经过验证的 SQL 模式
└── business/    # 指标及术语

表元数据

{
  "table_name": "customers",
  "table_description": "包含公司信息和生命周期状态的 B2B SaaS 客户账户",
  "use_cases": ["流失分析", "队列细分", "获客报告"],
  "data_quality_notes": [
    "signup_date 是 DATE 类型（不是 TIMESTAMP）——不含时间部分",
    "状态值：active、churned、trial",
    "company_size 是客户自报"
  ]
}

查询模式

-- <query monthly_mrr>
-- <description>来自活跃订阅的月度 MRR</description>
-- <query>
SELECT
    DATE_TRUNC('month', started_at) AS month,
    SUM(mrr) AS total_mrr
FROM subscriptions
WHERE ended_at IS NULL
GROUP BY 1
ORDER BY 1 DESC
-- </query>

业务规则

{
  "metrics": [
    {
      "name": "MRR",
      "definition": "剔除试用期后，所有活跃订阅的总和"
    }
  ],
  "common_gotchas": [
    {
      "issue": "检测活跃订阅",
      "solution": "应筛选 ended_at IS NULL，而非 status 列"
    }
  ]
}

加载知识

python scripts/load_knowledge.py            # 更新更改
python scripts/load_knowledge.py --recreate  # 从头开始

评估

使用 Agno 的评估框架进行五类评估：

类别	评估类型	测试内容
准确性	AccuracyEval（1–10 分）	数据是否正确及见解是否有意义
路由	ReliabilityEval	团队是否将请求路由至正确的代理/工具
安全	AgentAsJudgeEval（二元）	是否未泄露凭据或机密
治理	AgentAsJudgeEval（二元）	是否拒绝破坏性 SQL 操作
边界	AgentAsJudgeEval（二元）	是否遵守模式访问边界

python -m evals                      # 运行所有评估
python -m evals --category accuracy  # 运行特定类别
python -m evals --verbose            # 显示响应详情

本地开发

./scripts/venv_setup.sh && source .venv/bin/activate
docker compose up -d dash-db
python scripts/generate_data.py
python scripts/load_knowledge.py
python -m dash            # CLI 模式
python -m app.main        # AgentOS 模式（Web UI 地址：os.agno.com）

环境变量

变量	必需	默认值	用途
OPENAI_API_KEY	是	—	OpenAI API 密钥
SLACK_TOKEN	否	""	Slack 机器人令牌（界面 + 工具）
SLACK_SIGNING_SECRET	否	""	Slack 签名密钥（仅界面）
DB_HOST	否	localhost	PostgreSQL 主机
DB_PORT	否	5432	PostgreSQL 端口
DB_USER	否	ai	PostgreSQL 用户
DB_PASS	否	ai	PostgreSQL 密码
DB_DATABASE	否	ai	PostgreSQL 数据库
PORT	否	8000	API 端口
RUNTIME_ENV	否	prd	dev 模式启用热重载
AGENTOS_URL	否	http://127.0.0.1:8000	调度器回调 URL（生产环境）
JWT_VERIFICATION_KEY	生产环境	—	来自 os.agno.com 的 RBAC 公钥

安全性

生产部署需要通过 Agno AgentOS 进行身份验证。当 RUNTIME_ENV=prd（默认值）时，Dash 支持 RBAC 授权。如果没有有效的 JWT_VERIFICATION_KEY，生产环境的端点将拒绝所有请求。

本地开发模式（RUNTIME_ENV=dev，由 Docker Compose 设置）则无需认证，方便您自由迭代。

认证设置

请参阅 部署到 Railway 以获取完整的设置流程，包括如何从 AgentOS 获取 JWT_VERIFICATION_KEY。Agno 控制平面负责 JWT 发放、会话管理、追踪、指标以及 Web UI。更多详细信息请参考 AgentOS 安全文档。

模式级强制执行

除了 API 层面的认证外，Dash 还在数据库层面强制实施数据访问控制：

• 分析师以 default_transaction_read_only=on 模式连接——PostgreSQL 会拒绝任何写入尝试。
• 工程师的写操作仅限于 dash 模式——一个 SQLAlchemy 事件监听器会阻止针对 public 模式的任何 DDL/DML 操作。
• 领导者没有直接的数据库访问权限。

这些是基础设施层面的安全保障措施，而非提示指令。无论模型生成什么内容，它们都会生效。

了解更多

• OpenAI 的内部数据代理 — 设计灵感来源
• 自我改进的 SQL 代理 — 对早期架构的深入探讨
• Agno 文档

基于 Agno 构建 · 用于智能体软件的运行时

Dash 快速上手指南

Dash 是一个基于系统工程原则构建的自学习数据智能体。它通过六层上下文 grounding 提供准确答案，并随着每次查询不断自我进化。支持通过 Slack、终端或 AgentOS Web UI 进行交互。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (需安装 WSL2)
• 核心依赖:
  • Git
  • Docker 及 Docker Compose
  • Python 3.10+ (用于本地脚本运行)
• API 密钥:
  • OpenAI API Key: 必须拥有有效的 OPENAI_API_KEY。
  • (可选) AgentOS 账号: 如需使用 Web UI，请访问 os.agno.com 注册登录。

注意: 本项目主要依赖官方源，暂无官方提供的中国镜像加速方案。如遇网络问题，请自行配置全局代理或使用国内镜像站替代基础依赖下载。

安装步骤

1. 克隆项目与配置环境变量

# 克隆仓库
git clone https://github.com/agno-agi/dash.git && cd dash

# 复制环境变量模板
cp example.env .env

# 编辑 .env 文件，填入您的 OPENAI_API_KEY
# 可以使用 vim, nano 或任何文本编辑器

2. 启动系统服务

使用 Docker Compose 一键启动数据库和应用服务：

docker compose up -d --build

3. 生成样本数据并加载知识库

Dash 需要初始数据和业务上下文才能工作。执行以下命令将合成数据载入数据库：

# 生成模拟的 SaaS 指标数据
docker exec -it dash-api python scripts/generate_data.py

# 加载预定义的知识库（表结构说明、业务规则等）
docker exec -it dash-api python scripts/load_knowledge.py

启动完成后，您可以访问 http://localhost:8000/docs 确认 API 文档页面是否正常显示。

基本使用

安装完成后，您可以通过以下两种方式立即开始体验 Dash 的数据分析能力。

方式一：通过 AgentOS Web UI (推荐)

这是最直观的交互方式，适合查看可视化结果和管理会话。

1. 访问 os.agno.com 并登录。

2. 点击 Add OS → 选择 Local → 输入地址 http://localhost:8000。

3. 点击 Connect 建立连接。

4. 在对话框中尝试输入以下自然语言问题（基于内置的 SaaS 数据集）：

   • What's our current MRR? (当前的月度经常性收入是多少？)
   • Which plan has the highest churn rate? (哪个套餐的流失率最高？)
   • Show me revenue trends by plan over the last 6 months (展示过去 6 个月各套餐的收入趋势)
   • Which customers are at risk of churning? (哪些客户有流失风险？)

方式二：通过命令行 (CLI)

如果您偏好终端操作，可以直接在本地运行 Python 模块进行对话：

# 确保已激活虚拟环境（如果是在本地开发模式下）
# source .venv/bin/activate 

# 运行 CLI 模式
python -m dash

输入上述相同的自然语言问题，Dash 将自动生成 SQL、查询数据库并返回经过解释的业务洞察。