数据截至 2026-08-18(上游 commit 136cd875b154)

nao 是什么 · 全景与阅读地图

30 秒导读: nao 是一个开源的"分析 agent"框架。数据团队先用一个 Python 命令行工具(nao-core)把公司的数据库、表结构、文档、规则编成一个"上下文文件夹";然后启动一个聊天网页,业务同事用自然语言问数("上季度北美营收环比多少?"),后台的 AI agent 会像人一样在这个文件夹里翻找、对真实数仓执行 SQL、把结果画成图表或数据故事,一边生成一边流式显示在聊天里。本章只给"大盘",各机制细节留给 01–05 章。

1. 这是什么(零基础也能懂)

一句话定义: nao 是一个面向数据团队的开源分析 agent 框架——GitHub 仓库 getnao/nao,pip 包名 nao-core(见 cli/pyproject.toml:2)。

它服务两类完全不同的人,这一点是理解全局的钥匙:

读者	他们用 nao 干什么	交互方式
数据团队 / 分析工程师	搭建并"喂养"agent 的上下文:接数仓、灌元数据、写规则、跑评测	`nao-core` 命令行(`init` / `sync` / `chat` / `test`)
业务用户	用大白话问数、看图、给反馈	浏览器里的聊天 UI(`http://localhost:5005`)

为什么需要它: 让 LLM 回答"我们公司的数据问题"难点从来不是"调用模型",而是模型不知道你的表长什么样、指标怎么算、口径有哪些坑。nao 的答案是:把这些知识沉淀成文件,让 agent 能按需翻阅,而不是一次性塞进提示词。

核心能力(README.md:36-50):

🧱 开放的上下文构建器 —— 数据、元数据、建模、文档、工具、MCP,想放什么放什么,像文件系统一样组织。
🏳️ 数据栈无关 —— 任意数仓、任意 LLM 都能接(cli/pyproject.toml:48-69 列了 Postgres/BigQuery/Snowflake/DuckDB… 和 OpenAI/Anthropic/Mistral/Gemini/Ollama)。
🔒 可自托管、用自己的 key —— 数据不出你的环境。
🤖 自然语言到洞察 + 原生可视化 + 透明推理 + 一键反馈 —— 面向业务用户的四件套。

用起来什么样(README.md:52-113): 数据团队跑五条命令就有了一个能问数的 agent。

pip install nao-core        # 1. 装 CLI
nao init                    # 2. 建项目(问你项目名、要不要连库/仓库/LLM key/Slack)
nao debug                   # 3. 自检配置
nao sync                    # 4. 把数据源同步进"上下文文件夹"
nao chat                    # 5. 启动聊天 UI,浏览器打开 localhost:5005 开始问数

一句话直觉/类比: 把 nao 想成给 AI 配了一个"公司数据资料室 + 一部能连数仓的电话"。nao-core 负责把资料室建好、上架资料;聊天里的 agent 负责进资料室翻资料、必要时打电话(SQL)去仓库取数,再把答案讲给你听。

本节不出现底层代码;下面开始看"大盘怎么转"。

2. 顶层全景(它大概怎么转)

2.1 两半架构:CLI 建上下文,应用跑对话

nao 的代码天然分成两半,分工干净:

半边	是什么	语言/技术	职责一句话
`cli/`(`nao-core`)	上下文构建器 + 启动器	Python(cyclopts、ibis、pydantic)	`init` 搭骨架、`sync` 灌数据、`chat` 启动应用
`apps/`(`nao-chat`)	agent 运行时 + 聊天 UI	TypeScript monorepo(Fastify、React)	跑 agent 主循环、渲染流式对话
FastAPI 边车	SQL 执行进程	Python(FastAPI,在 `cli/` 侧)	专门对真实数仓执行 SQL 并回表格

这里有个关键设计:执行 SQL 的活留在 Python 侧(因为数仓驱动、ibis 生态都在 Python),而 agent 的"大脑"在 TypeScript 侧(用 Vercel AI SDK)。两者通过一个本地 HTTP 边车连起来——TS 里的 SQL 工具就是去 http://localhost:${FASTAPI_PORT}/execute_sql 发一个 POST(apps/backend/src/agents/tools/execute-sql.ts:54)。

nao chat 到底启动了什么? CLI 并不"实现"聊天;它把预先编译好的服务器二进制 nao-chat-server 跑起来(cli/nao_core/commands/chat.py:43 get_server_binary_path),再拉起 FastAPI 边车(chat.py:58 get_fastapi_main_path),默认端口 5005(chat.py:20)。也就是说 apps/ 这半边被打包进了 CLI 一起分发。

2.2 monorepo 布局(apps/ 三个 workspace + cli/)

package.json:4 声明 workspaces: ["apps/*"],三个 TS 包加一个 Python 包:

目录	包名	干什么	关键栈
`apps/backend/`	`@nao/backend`	API 服务器 + agent 主循环 + tRPC 路由 + DB。内含 `fastapi/` SQL 边车	Fastify、tRPC、Drizzle ORM、Vercel AI SDK(`ai`)、better-auth
`apps/frontend/`	`@nao/frontend`	聊天 UI:流式渲染、图表、Monaco/表格编辑	React 19、TanStack Router/Query/Table、Shadcn、Recharts、streamdown
`apps/shared/`	`@nao/shared`	前后端共享的工具/类型(体量很小)	TS
`cli/`	`nao-core`(pip)	上下文构建器 CLI + FastAPI 边车	cyclopts、ibis-framework、pydantic、jinja2、apscheduler

(布局取材:CLAUDE.md:9-14、各 package.json、cli/pyproject.toml。)

后端把能力按角色分层:routes/(HTTP 入口)、handlers/(编排)、services/(业务,agent 主循环在 services/agent.ts)、agents/tools/(工具带)、queries/(DB 访问)、db/(Drizzle schema,同时支持 SQLite 与 Postgres)。

2.3 一张顶层数据流图

怎么读这张图: 从上到下是一次问数的生命周期。左半虚线框是运行期(用户问一句触发),右边灰块是准备期(数据团队事先用 CLI 搭好)。agent 的两只"手":①用文件系统工具翻上下文文件夹,②经FastAPI 边车对真实数仓跑 SQL。

   ┌───────────────────────── 准备期(数据团队,离线) ─────────────────────────┐
   │  nao init → nao sync   把 数据库/表结构/文档/规则  编成 ↓                    │
   │                              「上下文文件夹」(项目 projectFolder)          │
   └───────────────────────────────────┬──────────────────────────────────────┘
                                        │ 被 agent 当成可浏览的文件系统
   ── 运行期(业务用户在浏览器) ─────────┼──────────────────────────────────────
                                        │
   ① 用户提问 ──────────► 前端聊天 UI (@ai-sdk/react useChat)
   "上季度营收环比?"          │ POST /agent  { chatId, message }
                              ▼
                      后端 routes/agent.ts ──► handlers/agent.ts
                              │ agentService.create(...)
                              ▼
              ┌─────────── Agent 主循环 (ToolLoopAgent) ───────────┐
              │  想 → 调工具 → 看结果 → 再想 …(最多 ~20 步)         │
              │                                                     │
              │   ├─ read / list / grep / search  ──► 翻「上下文文件夹」
              │   │                                    (找到相关表/口径/规则)
              │   │                                                 │
              │   └─ execute_sql ──HTTP──► FastAPI 边车 /execute_sql ──► 真实数仓
              │                                (返回结果表)          │
              │                                                     │
              │   最后:display_chart / story ──► 生成图表 / 数据故事 │
              └──────────────────────────┬──────────────────────────┘
                                         │ toUIMessageStream(逐块)
                                         ▼
                     前端流式渲染:文字 + 图表 + 表格 + 引用来源
                                         │
   ② 用户看到答案、可点赞/点踩反馈 ◄──────┘

2.4 主线走一遍(高层,不进代码)

准备期。 数据团队跑 nao init(cli/nao_core/commands/init.py)生成项目骨架 + nao_config.yaml + RULES.md;再跑 nao sync(cli/nao_core/commands/sync/)把数据库表结构、仓库、文档等物化成上下文文件夹里的文件。→ 细节见 01-context-filesystem.md。
启动。 nao chat 拉起 nao-chat-server(即 apps/backend,入口 apps/backend/src/index.ts:3 startServer({ port: 5005 }))和 FastAPI 边车。后端用 Fastify 挂上 tRPC 与 agent 路由(apps/backend/src/app.ts:162 注册 agentRoutes)。
提问。 业务用户在前端输入问题;@ai-sdk/react 的 useChat 把消息 POST 到后端 /agent(apps/backend/src/routes/agent.ts:16)。路由做鉴权(viewer 不能发消息),交给 handleAgentRoute(apps/backend/src/handlers/agent.ts:30)。
主循环。 handler 用 agentService.create(...)(apps/backend/src/handlers/agent.ts:70)造出一个 ToolLoopAgent(apps/backend/src/services/agent.ts:386,底层是 Vercel AI SDK 的 ai 包)。agent 反复"思考→调工具→读结果",直到给出答案(stepCountIs(20) 兜底,services/agent.ts:275)。→ 细节见 02-agent-loop.md。
两只手。 agent 用 read/list/grep/search 在 projectFolder 里导航上下文(如 apps/backend/src/agents/tools/read.ts:18 用 context.projectFolder 解析真实路径);用 execute_sql 经边车对真实数仓取数;用 display_chart/story 产出可视化。→ 工具带细节见 03-tools.md。
流式回传。 结果通过 toUIMessageStream(services/agent.ts:515)逐块推给前端,文字/图表/表格/来源一边生成一边显示。系统提示本身是用 .tsx 组件拼出来再渲染成 Markdown 的(apps/backend/src/components/ai/)→ 见 04-system-prompt.md。
可靠性与部署。 上线前可用 nao test 做评测(README.md:114-127);生产可用 Docker 自托管、上下文可从 git 拉取、可定时刷新、还能接 Slack/Teams/Telegram/WhatsApp。→ 见 05-reliability-deploy.md。

3. 阅读地图(建议顺序)

本章是 Layer 0(这是什么)+ Layer 1(顶层全景)。想深入某个机制,按下面顺序下钻——每章只讲一件事,互不重复:

顺序	章节	一句话讲什么	什么时候读
1	01-context-filesystem.md	上下文即文件系统:`nao-core` 怎么把数据源 `sync` 成一个 agent 能用文件工具浏览的上下文文件夹	想搞懂"agent 的知识从哪来"
2	02-agent-loop.md	Agent 主循环:`ToolLoopAgent` 如何多步思考、调工具、把结果流回前端	想搞懂"agent 怎么思考/执行"
3	03-tools.md	工具带:SQL(经边车)、图表、数据故事、沙箱执行的边界	想搞懂"agent 手里有哪些动作"
4	04-system-prompt.md	系统提示与上下文装配:用 `.tsx` 组件拼提示词、注入用户规则与表结构(JSX→Markdown)	想搞懂"提示词怎么组装"
5	05-reliability-deploy.md	可靠性、自动化与自托管:评测框架、定时任务、Docker/git 上下文、多渠道接入	想把它跑到生产

4. 边界与本章不讲的

本章只给大盘:各机制的真实实现(sync 的 provider 体系、主循环的 prepareStep/停止条件、SQL 边车的类型转换、提示词的 JSX 组装)都留给对应章节,这里不深入。
代码走读(密集 file:line)不在总览页;去各章看。
nao 是框架而非托管服务:它给你构建器和运行时,数据、LLM key、部署都在你自己手里(README.md:43 "Self-hosted & secure")。

5. 全局代码地图(导航索引)

这是一张跨全项目的顶层跳转表——想直接进源码时用符号名 grep(比行号抗漂移)。各章还有更细的本地代码地图。

主题	文件	关键符号
CLI 入口(注册所有命令)	`cli/nao_core/main.py:27`	`App`、`app.command(...)`、`main`
包定义(名字/依赖/数仓·LLM 可选组)	`cli/pyproject.toml:2`	`name = "nao-core"`、`[project.scripts] nao`
`nao chat` 启动服务器 + 边车	`cli/nao_core/commands/chat.py:43`	`get_server_binary_path`、`get_fastapi_main_path`
上下文同步(灌数据源)	`cli/nao_core/commands/sync/`	`sync` 命令、`providers/`
本地/git 上下文源	`cli/nao_core/context/`	`local.py`、`git.py`、`base.py`
FastAPI SQL 边车	`apps/backend/fastapi/main.py:222`	`execute_sql`、`health_check`、`refresh_context`
后端启动	`apps/backend/src/index.ts:3`	`startServer`
Fastify 装配(挂 tRPC + agent 路由)	`apps/backend/src/app.ts:162`	`agentRoutes`、`fastifyTRPCPlugin`
Agent HTTP 路由(问数入口)	`apps/backend/src/routes/agent.ts:16`	`agentRoutes`、`app.post('/')`
请求编排	`apps/backend/src/handlers/agent.ts:30`	`handleAgentRoute`
Agent 主循环	`apps/backend/src/services/agent.ts:203`	`AgentService`、`ToolLoopAgent`(`:323`)、`agentService`(`:909`)
工具带(注册表)	`apps/backend/src/agents/tools/index.ts:35`	`tools`、`getTools`
SQL 工具(调边车)	`apps/backend/src/agents/tools/execute-sql.ts:54`	`fetch(.../execute_sql)`
上下文导航工具	`apps/backend/src/agents/tools/`	`read`、`list`、`grep`、`search`
可视化工具	`apps/backend/src/agents/tools/`	`display-chart`、`story`
系统提示装配	`apps/backend/src/agents/system-prompts.ts:27`	`getSystemPromptOverride`、`injectNaoPrompt`
提示词 JSX 组件	`apps/backend/src/components/ai/`	`memory-system-prompt.tsx` 等 `.tsx`
LLM Provider 工厂	`apps/backend/src/agents/providers.ts:1`	`LLM_PROVIDERS`、`create*`(OpenAI/Anthropic/…)
DB schema(SQLite + Postgres 双写)	`apps/backend/src/db/`	`sqlite-schema.ts`、`pg-schema.ts`
前端聊天(流式)	`apps/frontend/src/queries/use-chat-query.ts:5`	`useChatQuery`(基于 `@ai-sdk/react` `useChat`)
部署/自托管配置	`docker-compose.yml`、`README-dockerhub.md`	`NAO_CONTEXT_SOURCE`、`NAO_DEFAULT_PROJECT_PATH`

说明:ToolLoopAgent、streamText 家族均来自 Vercel AI SDK 的 ai 包(apps/backend/src/services/agent.ts:13-21 的 import),不是 nao 自造的循环——nao 在其上加了工具带、停止条件与上下文装配。

1. 这是什么(零基础也能懂)​

2. 顶层全景(它大概怎么转)​

2.1 两半架构:CLI 建上下文,应用跑对话​

2.2 monorepo 布局(apps/ 三个 workspace + cli/)​

2.3 一张顶层数据流图​

2.4 主线走一遍(高层,不进代码)​

3. 阅读地图(建议顺序)​

4. 边界与本章不讲的​

5. 全局代码地图(导航索引)​