文档大纲

AI 替你写 BI 报表：Evidence.dev 从 0 到精通（2026 实操版）

一、为什么 2026 年应该重新认识 Evidence.dev

2026 年 8 月，Evidence.dev 官方文档 的首页标题已经改成 "Business intelligence for teams and agents"——团队和 AI 代理一起搭 BI。仓库 evidence-dev/evidence（MIT 协议，6.9k stars）在根目录放了一份 AGENTS.md，而 CLAUDE.md 只有一行内容 @AGENTS.md。这不是巧合，是官方在主动告诉你：这个工具天生就是给 AI 代理写的。

过去的 BI 工具（Metabase、Superset、Tableau）有一个共同问题——报表定义存在自己的数据库里。人要建报表得登录 GUI，AI 想读想写只能爬 API 解析 JSON。Evidence 反过来：报表就是 .md 文件里的一段 SQL 加几个组件，提交到 Git 就上线，AI 写报表等同于写文件，AI 读报表等同于读文件。这条范式在 AI Coding 大爆发的今天，显得格外值得学。

它不是要取代 Superset，也不是要复刻 Tableau。它回答的是一个非常具体的问题：

"我想让团队里 5-20 个人每天能看几张自动刷新的报表，同时希望 AI 既能建报表也能查报表数据，最好别花太多钱。"

如果你正卡在"BI 工具太重、AI 工具读不到数据"的中间地带，Evidence 是当下少有的开源解。

二、Evidence.dev 是什么 — 一句话 + 三个核心

一句话：Evidence.dev 是一个把"整套 BI"——数据源、SQL 查询、组件图表、页面布局、访问控制——全部写成文本文件并放进 Git 的开源框架，构建产物是纯静态站（HTML + Parquet），浏览器端用 DuckDB-WASM 跑筛选和排序。

三个核心抽象，记住这三条就懂了一半：

抽象是什么你要怎么写
Pages.md 文件，一个文件对应一个报表页面pages/销售概览.md
Queries写在代码栅栏里的 SQL，会真实运行并返回数据" `sql … ` "
ComponentsMarkdoc 自闭合标签，从查询结果渲染图表{% bar_chart data="…" x="…" y="…" /%}

组件数据来自 query，query 来自 source，source 是连接器。整条链路都是文本。

剩下两个常被忽视但很关键的抽象：

  • Partials：可复用 markdown 块（页眉、页脚、共享 KPI 卡片），用 {% partial file="/partials/xxx" /%} 引用；隔离作用域，需要显式 variables={} 传值。
  • Metrics / Models：Beta 版的数据建模层，把 JOIN、聚合、复杂计算从报表里挪到后台跑，结果物化到数据源里。

三、安装 CLI

Evidence 把几乎所有功能都做进了一个 CLI，名字叫 evidence，别名 evd。

macOS / Linux：

curl -fsSL https://evidence.studio/install.sh | sh

Windows（PowerShell）：

irm https://evidence.studio/install.ps1 | iex

安装完验证一下：

evidence version

如果你不想全局安装，也可以直接 pnpm dlx 或 npx，但官方推荐走 install.sh / install.ps1，会顺手把 evidence 和 evd 都加到 PATH。安装脚本自动选 ~/.local/bin（Unix）或 %LOCALAPPDATA%\Evidence\bin（Windows），如果目标目录不可写会回退到 ~/.local/bin。

如果不想被遥测打扰，开机时设环境变量 EVIDENCE_TELEMETRY_DISABLED=1 或 DO_NOT_TRACK=1。

四、第一个项目

evidence init my-project
cd my-project
evidence dev

默认会开 3000 端口（用 --port 8080 改）。打开 http://localhost:3000 你会看到一份 demo 报表，里头有 Value、BarChart、DataTable 这些组件。这就是 5 分钟入门。

但 demo 不是目的。真正要做的事是把数据接进来。CLI 提供两条路径：

# 路径 A：用 Evidence 托管的 Warehouse（要先 evidence login）
evidence login

# 路径 B：直连自己的数据仓库（写 connection.yaml）
evidence init my-project --warehouse snowflake
# 或
evidence init my-project --warehouse bigquery

加了 --warehouse 之后，项目根目录会多出一个 connection.yaml，并自动写入 .gitignore（这个文件含凭证，绝不能进版本控制）。PostgreSQL 的 connection.yaml 我放到第 7 章展开。

CLI 还内置了一批对开发者极度友好的命令，这些是 AI 协同时最有用的：

evidence query "SELECT * FROM orders LIMIT 10"   # 直接跑 SQL
evidence tables                                   # 列出可用表
evidence describe demo_daily_orders               # 看某张表的 schema
evidence schema                                   # 所有表 + 列
evidence connectors                               # 连接器健康状态
evidence lineage                                  # 表在哪些页面被引用
evidence validate                                 # 校验所有 markdown
evidence docs search "chart"                      # 在终端搜索组件文档

注意最后这条 evidence docs——离线就能查组件文档，AI 跑在没外网的服务器上也能用。

五、核心概念深挖

5.1 Pages — 你的报表就是 Markdown

pages/ 目录里每一个 .md 文件就是一张报表页面。Markdown 写法跟普通博客一致，支持列表、加粗、代码块、链接（链外站或链其他 Evidence 页面都行）。

文件头部可以放 YAML frontmatter，任何非保留键都会被识别为变量，可以用 {{ $key }} 引用：

---
title: 销售概览
category: Home
owner: 财务部

# {{ $title }}

由 {{ $owner }} 维护

系统还会自动给你一组内置变量：

变量含义
{{ $user.first_name }}访问者名字
{{ $user.last_name }}访问者姓氏
{{ $user.email }}访问者邮箱
{{ $organization.name }}所在组织

这组内置变量在写个性化标题、做权限白名单、给内部报表打水印时直接能用。

5.2 Queries — 代码栅栏就是 SQL

daily_orders SELECT date, category, sum(total_sales) as sales FROM demo.daily_orders GROUP BY date, category


上面那个 `daily_orders` 是查询的名字，后面所有组件用 `data="daily_orders"` 就能引用。

跨查询引用用 `{{query_name}}`：

big_orders
SELECT * FROM {{ daily_orders }}
WHERE sales > 10000

被引用的查询会被圆括号包裹作为子查询插入。

5.3 Components — Markdoc 自闭合标签

所有组件都是自闭合的 Markdoc 标签，写在行首会触发自动补全：

{% table data="demo.order_details" /%}

{% bar_chart
    data="DEMO.ORDER_DETAILS"
    x="DATE"
    y="SUM(\"Total Sales\")"
/%}

要点：

  • 命名用 snake_case：bar_chart 而不是 BarChart
  • 属性值用双引号；内部需要双引号就转义 \"
  • 类型化：字符串、数字、布尔、对象、数组都可以直接传
  • 输入时编辑器会显示自动补全；非法值会标红下划线

Evidence 的组件库非常庞大，按目录分 9 类：

类别代表组件用途
Values & Indicatorsvalue, bigvalue, delta, heatgrid, progress_bars单值 KPI、趋势对比、进度条
Tablestable, dimension, measure, pivot表格与多维透视
Charts20+ 种（bar、line、area、scatter、bubble、combo、heatmap、pie、funnel、sankey、radar、polar、treemap、candlestick、calendar_heatmap、chord、histogram、treemap 等）几乎所有图表
Sparklinessparkline单元格内嵌趋势小图
Mapsmap, arealayer, heatmaplayer, pointlayer, custommap地理可视化
Inputs & Filtersdropdown, dategrainselector, rangecalendar, slider, buttongroup, toggle, textinput, filterbar, dimension_grid筛选与参数
Layout & UItabs, accordion, callout, commentary, details, download, image, iframe, modal, note, partial, row, stack页面结构与排版
Conditional & Iterationif, else_if, else, repeat控制流（是的，报表里有循环）
Combo Seriesbar, line, area, bubble, scatter, referenceline, referencearea, reference_point组合图表的子元素

完整列表见官方 Components 索引。

5.4 Partials — 跨页面复用

{% partial file="/partials/kpi_card" variables={
    title = "今日销售"
    metric = $revenue_today
} /%}

作用域是隔离的：partial 看不到父页面的变量，必须显式 variables={} 传参。这条规则一开始会让人困惑，但它换来的是 partial 可以在任何页面被复用——这是它和组件最大的差异。

路径解析踩坑：partial 默认从引用它的页面所在目录解析。建议始终加前导 /：

{% partial file="/partials/kpi_card" /%}

否则当 partial 被移动或页面被换目录时，引用会突然 404。

5.5 Models（Beta）— 把 JOIN 挪出报表

官方明确说："All joins between sources should be handled in models, not in reports."——所有 join 写在报表里是反模式。

-- models/enriched_orders.sql
SELECT
    od.order_id, od.date, od.category, od.item_name,
    od.unit_price * od.quantity as line_total,
    i.base_price,
    od.unit_price - i.base_price as price_variance
FROM demo.order_details od
LEFT JOIN demo.items i
    ON od.category = i.category AND od.item_name = i.item_name

报表里只引用：

{% table data="enriched_orders" /%}

默认每 12 小时刷新一次（企业版可调 1-72 小时）。表引擎默认 MergeTree（GCP us-central1），适合冷数据的可以选 S3。

六、Studio 在线编辑器（不是你想的那种）

这一章必须在讲 PostgreSQL 之前讲——这是关于 Evidence 产品定位最常被误解的一环，也是你提的关键问题。

6.1 一句话回答：没有"Power BI 式"自助编辑器

Evidence 没有 Power BI / Tableau / Metabase 那样的拖拽式自助 BI 编辑界面。你打开 Evidence Studio 第一眼看到的是：

  • 左侧：代码编辑器 —— 写 Markdown 和 SQL 的位置，不是画布
  • 中间：实时预览 —— 编辑后毫秒级刷新，跑 SQL 渲染图表
  • 右侧侧栏：Evidence Agent 聊天面板 —— 用自然语言描述需求，AI 生成 diff 让你接受/拒绝

没有拖拽组件。没有画布。没有"把字段拖到 X 轴"这种操作。这就是 Markdown + SQL + 斜杠命令。

Evidence Studio 官方对编辑器的描述原文：

"On the left hand side of your screen, you have a code editor. This is where you define your report in markdown."

"Slash commands: Type a / to list components, accept suggestions with tab."

"Autocompletion: For components and SQL fences, accept suggestions with tab."

"Syntax highlighting: For markdown, SQL, and components."

"Validation: Invalid code is underlined in red, hover to see errors, and click 'Fix' for AI assistance."

也就是说，Evidence Studio 不是 Power BI 的替代品，而是另一种工具。要类比的话：

工具编辑范式
Power BI / Tableau / Metabase / Superset拖拽式：业务人员自助建图
Evidence Studio代码 + AI：开发者用 AI 协作写代码
Evidence Core（自托管）纯 CLI：终端 + Markdown 文件

这条对比是产品决策的核心。如果你的团队是"运营/财务自己拖报表"的模式，Evidence 不适合——这不是它想服务的市场。

如果你的团队是"开发者维护一个 BI 报表库、AI 协作迭代、代码评审上线"的模式，Evidence 就是为这种工作流设计的。

6.2 Studio 编辑器能做什么

逐字摘录 Studio 编辑文档的描述：

  • Code Editor：左屏代码编辑器，写 Markdown 定义报表
  • Slash Commands：行首输入 / 弹出组件列表，Tab 接受
  • Autocompletion：组件名、SQL 都有自动补全
  • Syntax Highlighting：Markdown、SQL、组件语法着色
  • Validation：非法代码下划红，悬停报错，点击"Fix"让 AI 修复
  • Preview：代码改动实时反映到预览，含 SQL 重跑和图表重渲染
  • Agent Panel：右屏侧栏聊天面板，Agent 经过训练写合法 Evidence markdown，知道你接入的所有数据源 schema
  • Diff View：Agent 改动以 diff 形式展示，可接受/拒绝/再提示

6.3 Studio 编辑器不能做什么

同样重要——以下这些"自助 BI"的标配功能，Evidence 没有，也不打算有：

  • ❌ 拖拽组件到画布：没有画布
  • ❌ 点选字段自动生成图表：没有"列表面板"
  • ❌ 所见即所得的图形化布局：所见即所得，但本质是 Markdown 渲染
  • ❌ 业务人员独立建图：需要懂 SQL / Markdown，或熟练使用 AI Agent 协作
  • ❌ GUI 状态存储：文件就是真实状态，所有改动都在 Markdown 里
  • ❌ 类似 Tableau 的探索式分析：Evidence 报表是只读的发布产物
  • ❌ 类似 Looker 的 LookML 视图层：Evidence 是直接 SQL，没有中间语义层 DSL

6.4 Studio vs Core：什么时候用哪个

维度Evidence Core（开源）Evidence Studio（托管）
编辑方式任意文本编辑器 + 终端Web 代码编辑器 + AI Agent
AI 助手靠外部 Claude Code / Cursor内置 Agent + 外部也能接入
数据存储自己的仓库 / 自己的数据库Evidence Warehouse（Fivetran 同步）或直连
自托管✅❌（只能用官方托管）
团队协作Git 流程Git 流程 + 共享工作区
价格¥0（自建服务器）订阅制（按席位/规模）
Studio MCP❌✅
内嵌 AI Agent靠外部 MCP✅

自托管项目只能选 Core + 自己接 Docs MCP。Studio MCP 与 Studio 编辑器是绑定的。

6.5 给业务人员的"半自助"路径

如果你团队里有"懂业务的运营/财务"但不懂 SQL，他们也并不是完全用不了 Evidence。两条路径：

  1. 指挥 Agent：在 Studio 右侧面板用自然语言说"做一个销售按月趋势图，按品类分线"。Agent 会生成 Markdown 草稿，diff view 里你接受即可。
  2. 让数据团队写，他们提需求：典型协作流 —— 业务方写需求清单（指标定义、维度、过滤项），数据团队（或 AI）翻译成 Evidence markdown。

但即便有 AI 帮忙，业务人员也无法绕开"理解 SQL 报表会做什么"这一步。如果你期待的是"运营小妹自己拖出一张报表"，Evidence 选型方向就错了——这种需求 Power BI / Metabase 更合适。

6.6 一句话总结

Evidence 没有 Power BI 那样的自助编辑界面。 这不是缺陷，是设计哲学——它要的是 "BI as Code + AI 协同"，而不是 "BI as GUI"。选型之前先回答一个问题：你的团队是"业务主导 BI"还是"开发主导 BI"？前者继续看 Power BI，后者继续看 Evidence。

七、连 PostgreSQL（最常见场景）

PostgreSQL 是 Evidence.dev 最常用的直连场景，本章把它讲透。

7.1 写 connection.yaml

CLI 不带 --warehouse postgres 的脚手架，得手动建。文件放项目根目录：

# connection.yaml
type: postgres
host: mydb.abc123.us-east-1.rds.amazonaws.com
# port: 5432
user: evidence
password: <your-password>
database: analytics
# sslmode: verify-full
# ssl_ca_path: ./certs/rds-global-bundle.pem
# sslmode: verify-full

官方对 SSL 的态度很坚决：默认 verify-full——既加密又验证证书和主机名。理由是 require（只加密不验证）"vulnerable to an active man-in-the-middle"——这是中危漏洞。

模式表：

sslmode含义是否推荐
disable不加密内网调试，且你别怕被嗅探
require只加密不推荐——验证不了证书等于没用
verify-ca验证证书不验证主机名可用于内部 CA
verify-full（默认）验证证书+主机名公开证书、Neon 等开箱即用

私有 CA 场景（典型：Amazon RDS），把 CA bundle 路径填到 ssl_ca_path。

7.2 在 PostgreSQL 上准备只读角色

Evidence 自己有底线：永远别用 superuser 或 owner 角色连库。

CREATE ROLE evidence LOGIN PASSWORD '<strong-password>';
GRANT CONNECT ON DATABASE analytics TO evidence;
GRANT USAGE ON SCHEMA public TO evidence;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO evidence;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO evidence;

这条 SQL 是 AI 协同时的安全底线——后面 MCP 只读账号也走这个模式。

7.3 几个工程提醒

  • 必须 TLS/SSL：官方说"Your PostgreSQL database must have TLS/SSL enabled"。腾讯云 RDS 默认开；自建 PostgreSQL 必须 ssl = on。
  • session-mode 连接池：直接连接和 session-mode pooler 完全支持；transaction-mode pooler 不能用——它不保留会话状态，导致非默认 search_path 与 statement timeout 失效。PgBouncer 默认是 transaction-mode，要么改 pool_mode = session，要么绕开。
  • 凭证别入仓：connection.yaml 在 .gitignore 里是默认的；用 ${VAR} 环境变量引用更安全，例如 password: ${PG_PASSWORD}。

7.4 直连 vs Fivetran 数据源

PostgreSQL 在 Evidence 里有两种连接方式：

方式模型何时用
Direct ConnectorEvidence 直接 query 你的库，不同步自有 PostgreSQL，对实时性有要求
Data Source（Fivetran 模式）由 Fivetran 同步到 Evidence Warehouse你想用托管仓库，或需要跨源合并

自托管项目必须用 Direct Connector——自托管场景没有托管查询引擎。

八、变量与参数化查询（动态筛选的灵魂）

报表能互动，靠的是三件套：Input 组件 + 参数化 SQL + 引用变量的图表。

8.1 定义变量

两条路径：

<!-- 路径 A：Frontmatter -->
---
company:
  name: Acme
  industry: Manufacturing

<!-- 路径 B：Input 组件 id -->
{% dropdown id="category_dropdown" data="orders" value_column="category" /%}

引用时 Frontmatter 变量要加 $：

{{ $company.name }}     # Acme
{{ $targets.revenue }}  # 1000000
{{ $colors[0] }}        # red

8.2 在 SQL 里引用

select * from demo.daily_orders
where category = '{{ $category }}'

引用 Input 组件时自动用 .selected（带引号）——这是 Evidence 的"上下文感知"魔法：SQL 里引用 Input 自动加引号，文本里引用自动不带引号，开发者不用想。

select * from demo.daily_orders
where category = {{ category_dropdown }}
-- 等价于：where category = 'Electronics'（用户选了 Electronics）

8.3 Fallback 与条件块

where category = {{ category_dropdown | 'Electronics' }}
-- ↑ 管道符给默认值

select * from demo.order_details
where transaction_amount > 500
[[ and category = {{ category_dropdown }} ]]
-- ↑ [[ ... ]] 块只有在所有变量都解析为非空时才插入

条件块配合"未选择就不筛选"是最常见的报表互动模式。

8.4 显式属性

有些场景你得明确指定属性：

where category = {{ category_dropdown.selected }}  -- 带引号
where category = {{ category_dropdown.literal }}  -- 不带引号（适合拼接）
where category = {{ category_dropdown.filter }}    -- 专门给组件级联用

九、自托管与上线

Evidence.dev 提供两种部署形态：

形态命令何时用
Evidence Studio（托管）evidence launch / evidence link想省事、按月付钱、团队权限托管
Self-host（开源）evidence serve / Docker想控在自己服务器、零月费、深度定制

9.1 self-host 命令

evidence serve
evidence serve --port 8080 --host 0.0.0.0

要求：项目根目录有 connection.yaml 且使用 Direct Connector。

认证策略三档（按可信度排序）：

# 档位 A：HTTP Basic Auth（默认）
export EVIDENCE_BASIC_USER=alice
export EVIDENCE_BASIC_PASSWORD=...

# 档位 B：完全跳过认证（仅在受信内网用）
export EVIDENCE_AUTH_DISABLED=true

# 档位 C：企业 SSO — 在外面套一层反向代理
# 自己接 Okta / Auth0 / Cloudflare Access

如果非 localhost 的 --host 没设 Basic Auth 凭证，服务器会拒绝启动——这是有意为之，避免裸奔到公网。

9.2 Docker 自托管

官方提供了 Dockerfile 模板：

FROM evidencedev/serve:latest
COPY --chown=evidence:evidence . /project

打包后跑在容器里，前面套 Cloudflare Tunnel / Nginx / Caddy 任意一个反向代理即可。Cloudflare Tunnel + Access 的免费额度对 5-20 人刚好够用——邮箱白名单、零开放端口、CDN 边缘验证。

9.3 平台化部署

官方给出 Vercel、Render、Fly.io、Railway 的具体指南（Self-host 目录）。注意 Netlify / Cloudflare Pages 不在官方清单里——Evidence 需要后端进程跑 query，纯静态托管是不够的。

十、AI 协同（最重要的一章）

写到这里我已经吃了六章铺垫。这一章是整篇学习的回报——你看到这里之前掌握的所有概念，都是为了让 AI 替你干活。

Evidence 把"AI 友好"做成了产品特性，而不是文档里的一句话。它提供四种 AI 协同路径，按推荐顺序展开。

10.1 路径 A：本地 IDE 里用 Claude Code / Cursor 直接写报表

这是最低门槛、最常用的方式。Evidence 项目就是一个 Git 仓库，pages/ 里全是 .md 文件，AI 直接读写文件就完事。

要让 Claude Code 顺手，强烈建议在项目根加一份 CLAUDE.md：

# CLAUDE.md

This is an Evidence.dev project. Read AGENTS.md for full agent guidance.

## Quick Reference
- Pages live in `pages/` as Markdown files
- Queries are SQL code fences; named queries are reusable
- Components are Markdoc self-closing tags: `{% table data="..." /%}`
- Variables come from page frontmatter or input components
- For self-hosted PostgreSQL, see `connection.yaml`

## Commands
- `evidence dev` starts the dev server on port 3000
- `evidence query "SQL"` runs ad-hoc SQL
- `evidence tables` lists available tables
- `evidence describe <table>` shows table schema
- `evidence validate` validates all markdown
- `evidence lineage` shows table → page dependencies

## Conventions
- Keep joins in models (Beta), not in reports
- Always use parameterized queries (`{{ var }}`); avoid string concat
- For dropdown filters, use the `id` attribute to bind a variable
- Use `[[ ]]` conditional blocks for optional WHERE filters

这一份 CLAUDE.md 能让 Claude Code 在写新报表时零提示完成 80% 工作——它知道查询怎么命名、组件怎么写、变量怎么绑定。

官方在 evidence-dev/evidence 仓库根目录也放了一份 AGENTS.md（CLAUDE.md 只写一行 @AGENTS.md），给贡献者看的项目说明。你本地项目可以照着改一份自己的版本。

AI 写报表时常见的"翻车"场景（提前提醒）：

  • 把 join 写在报表里 → 让它读 Models 文档
  • 用字符串拼接做筛选 → 改成参数化查询
  • 命名用驼峰 → 改成 snake_case
  • 用循环渲染时数据太大 → 让 dbt 先聚合
  • 不小心改了 connection.yaml → 让它从 .gitignore 拉回来

10.2 路径 B：Docs MCP — 给 AI 一本"离线文档"

Evidence 在 https://evidence.studio/mcp 跑了一个 Docs MCP 服务器（注意是 /mcp，不是 /api/mcp），不需认证。这相当于给 AI 配了一本可检索的官方文档。

Claude Code 一行接入：

claude mcp add --transport http evidence-studio https://evidence.studio/mcp

Cursor 接入（写入 .cursor/mcp.json）：

{
  "mcpServers": {
    "evidence-studio": {
      "url": "https://evidence.studio/mcp"
    }
  }
}

接上之后 AI 可用的工具：

工具用途
list_components列出全部组件，按类别分组
get_component取组件元数据、示例、属性概览
getcomponentattributes详细属性（类型、是否必填、默认、说明）
getcomponentexamples取某组件的所有代码示例
list_docs列所有文档页
read_doc读单篇文档完整 markdown
search_docs在整个文档库里搜关键字

这是 AI 写报表时第一个要打开的"工具箱"——它能让 AI 自己查"bar_chart 怎么传 x 和 y"，而不靠你喂 prompt。

不支持 MCP 的工具，官方还给了两份 LLM 友好的 dump：

  • https://docs.evidence.studio/llms.txt — 站点地图
  • https://docs.evidence.studio/llms-full.txt — 完整文档

10.3 路径 C：Studio MCP — 让 AI 读你的真实数据

Docs MCP 教你语法，Studio MCP 让你直接干活。它在 https://evidence.studio/api/mcp（注意多 /api），需要登录鉴权。

Claude Code 接入：

claude mcp add evidence-studio --transport http https://evidence.studio/api/mcp

接好之后，AI 在你授权下可以调用：

工具用途
whoami当前认证身份
listorganizations / listprojects列组织与项目
get_context关键：读你为这个项目配置的 context 和 skills
listprojectpages / getpagesummary / getpagecontent浏览已发布报表
searchpublishedcontent在已发布报告里搜关键字
listprojectfiles / getprojectfile读 partial、SQL、自定义组件
listtables / getmetadata列可用表 + 取列信息
run_query只读 SQL 查询（默认 LIMIT 100，最大 1000）
visualize把 Markdoc 片段渲染为图表图片

run_query 默认只读，这是官方故意设计——AI 再聪明也不应该写库。

完整推荐调用顺序（官方文档原话）：

1. whoami 确认身份 2. get_context 取工作区约定 3. list_tables + get_metadata 了解 schema 4. run_query 跑数据 5. list_project_pages + get_page_summary + get_page_content 读已有报告 6. visualize 渲染结果

10.4 路径 D：Evidence Agent — 项目内嵌 AI

Evidence 项目自带 agent/ 目录：

agent/
├── context/
│   └── instructions.md    # 永远加载的指令
└── skills/
    └── cohort-analysis/
        └── SKILL.md       # 技能（按需加载）
  • Context — 始终进入 Agent 提示的 freeform markdown。用来放业务背景：财年起始月、"活跃用户"的 28 天滚动定义、关账流程、组织架构。这是 AI 理解业务的唯一权威来源。
  • Skills — 编码一个分析流程（cohort、漏斗、对比）。SKILL.md 的 frontmatter 决定 Agent 何时加载它——description 字段（≤1024 字符）是 Agent 唯一会预先看到的部分，因此写好 description 等于让 AI 知道何时调用它。

格式跟 Claude Skills 完全兼容（YAML frontmatter + markdown body），所以你之前在别的项目写的 Skill 可以直接搬过来。

---
name: cohort-analysis
description: 对用户做同期群分析，按月分桶留存率；当用户问"留存"或"cohort"时调用。

# Cohort Analysis

## 步骤
1. 从 mart.users_orders 拉 28 天活跃用户
2. 按注册月分桶
3. ...

缺失或 frontmatter 错的 SKILL.md 会阻断发布——这是有意为之，逼你把描述写好。

而且——agent/context/ 与 agent/skills/ 的内容通过 Studio MCP 的 get_context 工具暴露给外部 AI（Claude、ChatGPT 等）。换句话说，你给项目内 Agent 写什么，连进来的外部 Claude 助手就看到什么。这是 AI 协同时唯一的"业务知识入口"。

10.5 四条路径怎么选

场景推荐
团队里没人用 Studio，只想本地写报表路径 A（Claude Code + CLAUDE.md）+ 路径 B（Docs MCP）
团队全员读报表 + 偶尔让 AI 帮查数路径 C（Studio MCP），所有 AI 问数走只读
团队要把业务知识沉淀进报表路径 D（agent/context/ + agent/skills/）
自托管 + 不订阅 Studio路径 A + B（Docs MCP 永远免费；Studio MCP 必须订阅）

AI 协同时最容易踩的坑：

  1. 不要把业务口径藏在 SQL 里——AI 看不到隐藏在 SQL 注释里的语义。全部写在 agent/context/。
  2. description 是技能能否被调用的唯一信号——空着等于这个技能永远不被用。
  3. get_context 是先于其他工具调用的"开机问候"——AI 第一次进工作区没读它，相当于带偏见上岗。
  4. 自托管项目也能用 Docs MCP——https://evidence.studio/mcp 无需认证。Studio MCP 不行。
  5. MCP 用 Streamable HTTP——不是 stdio/SSE，老版本 MCP 配置写法可能不通用。

十一、版本控制与发布

Evidence 项目即 Git 仓库，两种模式：

模式说明
Evidence managed repo默认模式，文件只在 Studio UI 里能改
Your own repo接到外部 Git 仓库（目前仅支持 GitHub）

分支策略：

方案 1：Main only
└─ main（线上分支）

方案 2：Feature branches
├─ main（线上）
└─ dev/alice（开发分支）

Studio 编辑器有个"共享工作区"机制：所有未提交的改动暂时驻留在云端，commit 时打包成 squash commit 推回 main。简单粗暴，但好处是不会有"忘 commit 的本地改动"。

GitHub Action 自动构建官方没出模板，自己写也很简单（dbt build + evidence build + push 静态产物到 Pages / 自有 CDN）。自托管场景的 cron 脚本通常就是三步：evidence sources refresh + evidence build + 重启 evidence serve。

十二、避坑清单（AI 协同时尤其要注意）

#坑应对
1数据量爆掉浏览器DuckDB-WASM 在浏览器端跑，单张报表数据集上限几万到几十万行。超了就先在 dbt 聚合。
2报表有 joinjoin 全挪到 Models，报表只引用结果表
3PostgreSQL 用 superuser 连用只读角色（详见 7.2）
4transaction-mode 连接池不支持 session 状态，改 session-mode 或直连
5凭证进仓connection.yaml 默认 .gitignore，但引用密钥文件不会自动忽略——自己加
6connection.yaml 误改AI 改完 diff 一下；从 git 历史恢复
7Partial 路径不带前导 /file=&quot;footer&quot; 在子目录页面会解析为 pages/footer
8Partials 取不到父变量作用域隔离，必须 variables={} 显式传
9Skill description 空着AI 永远不调用它，且阻断发布
10业务口径没写进 contextAI 永远在猜字段含义，每次分析都得到处问
11Studio MCP 和 Docs MCP 端点搞混路径差一个 /api：/api/mcp 是 Studio（需鉴权），/mcp 是 Docs（免费）
12自托管项目用托管 query 引擎自托管必须 Direct Connector
13跨页面变量共享用 frontmatterfrontmatter 是页面级的，跨页面用 partial 传 variables
14报表里有循环渲染用 {% repeat … %} 而不是手写 N 行
15docs.evidence.studio 已 308 到 docs.evidence.dev历史链接别再写错；新链接统一用 .dev
16把 Evidence 当 Power BI 替代品推广Evidence 没有 拖拽式自助 BI 编辑器。运营/财务"自己拖报表"的场景它解决不了——他们需要的是 Power BI / Metabase（详见第 6 章）

十三、门槛的真实成本（看人下菜）

"没有 GUI 是不是就很难用？"——这是被问到最多的问题。答案是因人而异，也因时间维度而异。本节试图把这个常被误解的问题拆透。

13.1 门槛高低，看你是谁

你的背景实际难度上手时间长期天花板
资深数据工程师 / 后端低（SQL + Git 都熟）30 分钟出第一张极高（整套数据栈做成可复用资产）
数据分析师（懂 SQL 不熟前端）中低半天熟悉 Markdoc 语法高（配合 AI Agent 能写出复杂报表）
前端 / 全栈低（组件语法跟写 React/HTML 差不多）半天高
BI 运营 / 财务（懂 SQL 不熟 Git）中高1-2 天（Git + Markdown 都要补）中等（适合做"提需求方"，不适合做"实现方"）
完全不懂技术的业务人员极高不可行不适用

重点：Evidence 的门槛主要卡在 SQL + Git，而不是 Markdown 或组件语法。Markdown 是 1 小时能学会的事，组件语法是 30 分钟的事，但 SQL 和 Git 是结构性要求——这是分水岭。

13.2 表面门槛 vs 隐藏门槛——一个反直觉的事实

很多人凭直觉觉得 Power BI 门槛低（拖拽就行）、Evidence 门槛高（要写代码），但拆开看更真实：

维度Power BI / TableauEvidence
表面门槛（上手第一张图）低（30 分钟拖出）中（半小时看懂语法）
隐藏门槛（处理真实数据）高（DAX / Power Query / 数据建模 / 网关配置 / 行级权限 / 工作流治理）中（SQL 是大部分分析师的老本行，Git 比 DAX 学得快）
长期门槛（团队协作）高（报告定义存数据库里，没法 diff、没法 PR、AI 没法读）低（纯文本 + Git + AI 原生支持）
AI 协作门槛高（AI 只能爬 API）极低（AI 直接读写 Markdown）
跨项目复用门槛高（每个项目重新做）低（partial / models / agent skills 都是文本资产）

所以"门槛"是个时间维度的概念：

  • 第 1 天：Power BI 赢
  • 第 30 天：打平
  • 第 180 天：Evidence 开始赢（报表可维护、可协作、可被 AI 接管）
  • 第 365 天：Evidence 大幅领先（dbt + Evidence 沉淀成数据资产，AI 接管 70% 迭代）

13.3 但有三个"反门槛"的平衡器

Evidence 不是把门槛推给用户，而是通过设计降低门槛——这一点比大多数同类工具有诚意。

13.3.1 AI Agent 把门槛从"会写代码"变成"会提问"

如果你的 CLAUDE.md 写得好（详见 10.1），AI 帮你完成 80% 的报表编写。你只需要：

  • 描述要什么图
  • 描述字段含义
  • 看 diff 接受/拒绝

运营人员用自然语言指挥 Agent 生成 Markdown，自己在 diff view 里点接受。这条路径下，业务人员也能参与（虽然还是需要你懂业务语义和 SQL 在做什么——这一步 AI 短期替代不了）。

13.3.2 错误反馈是即时的

官方对 Studio 的描述：

"Invalid code is underlined in red, hover to see errors, and click 'Fix' for AI assistance."

不是写完了部署到服务器才知道错，是边写边校验——跟写 React/Vue 没什么区别。熟悉前端开发的人会觉得非常自然。

13.3.3 CLI 提供"自助文档"

evidence tables              # 列可用表
evidence describe <table>    # 看 schema
evidence docs search "chart" # 查组件文档
evidence lineage             # 查表被哪些页面引用

不用记字段名，不用记组件属性名——命令都给你。这是为 AI 协同时设计的，但对人也友好。

13.4 降低门槛的 4 个实操建议

如果你打算真的用起来，下面 4 件事能让门槛降一档：

  1. 先从一个简单页开始——不要一次铺开。"展示今日销售总额 + 7 日趋势"这种单页，30 分钟能搞定
  2. 写一份项目专属的 CLAUDE.md——花 30 分钟把 schema 概要、指标口径、报表规范写进去，AI 正确率从 60% 跳到 95%
  3. 配 MCP——Claude Code / Cursor 接上 Docs MCP 后，AI 自己会查组件文档，你不用查
  4. 以 dbt 模型为前置——如果团队已有 dbt，SQL 部分基本写完了，Evidence 只是把它渲染出来；这一步是把"会 SQL 的人"和"会 SQL 的 BI 报表"解耦的关键

13.5 我的判断

门槛对资深开发者低，对纯业务人员高——这是它的产品定位决定的。如果你团队里有人会 SQL + Git，门槛其实不高；如果你想"让运营自己拖报表"，这工具从根上就不适合。

但门槛不会永远卡在某一档——AI Agent 在快速吃掉 SQL 这道墙。当 AI 能从你给的自然语言描述里直接写出正确的 SQL + Markdown 时，"懂 SQL"这条门槛会被削平。这是 Evidence 把赌注压在"AI 会越来越强"上的原因，也是它作为长期投资比 Power BI 更值得的原因。

十四、它适合谁、不适合谁

适合：

  • 5-50 人团队，每周想稳定出几张报表
  • 已经在用 dbt / DuckDB，希望 BI 跟着代码走
  • 团队里有 AI Coding 习惯，想让 AI 接管报表迭代
  • 自有 PostgreSQL / Snowflake / BigQuery 仓库，不想再买 SaaS BI
  • 重视"AI 既能写也能读"的能力
  • 开发主导 BI：技术团队维护报表库，业务方提需求，由开发（或 AI 代理）落地

不适合：

  • 业务主导 BI：运营/财务自己拖报表——Evidence 没有 拖拽式自助编辑器（详见第 6 章）。这种场景请选 Power BI / Metabase / Superset
  • 50+ 人企业要全员自助建图（用 Superset/Metabase）
  • 没有 Git 习惯的团队（BI 这种"业务随时要改"的场景他们撑不住）
  • 需要实时（秒级）数据刷新（Evidence 是定时批处理）
  • 强依赖 SaaS 数据源却不想自己管 ETL 的（这种情况下 Power BI / Looker 更顺）
  • 不接受 DuckDB-WASM 在浏览器跑的事实（手机老浏览器会卡）

十五、参考链接（全部来自 Evidence 官方）

最后一条：写一份你项目专属的 CLAUDE.md。花 30 分钟把 schema 概要、指标口径、报表规范写进去，AI 写报表的正确率会从 60% 跳到 95%。这是本文唯一一条值得"立刻动手"的建议。

阅读量： 322

网站备案号：沪ICP备2025137870号