企业官网建设流程全解析

nao 是一个开源的分析智能体（Analytics Agent）框架，用自然语言就能对业务数据做查询和可视化分析。nao init是整个项目的起点：一条命令即可交互式地创建项目目录、生成 nao_config.yaml 配置文件，并自动接入数据库和 LLM 服务，帮你从零初始化一个分析智能体项目。

🎯 nao init 能做什么：一句话理解

nao 的工作方式是"两步走"：

1. 用 nao-core CLI 创建分析上下文（数据、元数据、规则、文档）
2. 部署一个聊天界面，让团队里任何人都能用自然语言提问分析

而nao init就是第 1 步的入口。运行后它会依次问你 6 个问题，把所有答案写进项目配置，并生成标准的目录骨架——之后跑nao chat就能直接在浏览器里和数据对话了。

核心实现位于 cli/nao_core/commands/init.py，交互式配置逻辑见 cli/nao_core/config/base.py。

📦 一键安装：运行 nao init 前的准备

nao init属于 nao-core 包，安装只需要一步：

pip install nao-core

安装是"按需付费"式的——核心包很轻量，数据库驱动和 LLM 依赖通过 extras 按需安装。比如你用的是 PostgreSQL + OpenAI：

pip install 'nao-core[postgres,openai]'

支持的数据库包括 PostgreSQL、BigQuery、Snowflake、DuckDB、Databricks、ClickHouse、Redshift 等十余种，LLM 支持 OpenAI、Anthropic、Mistral、Gemini、Ollama 等，完整清单见 cli/README.md。

💡 小技巧：init 执行到中途如果发现缺少依赖，会自动帮你安装（见 init.py 中的依赖安装逻辑），装好后继续，不需要你手动打断。

🚀 交互式初始化：6 步完成分析智能体项目

在任意目录下执行：

nao init

接下来终端会依次引导你完成 6 个步骤：

第 1 步：给项目起个名字

输入项目名称（默认使用当前目录名，直接回车即可）。项目名不能为空，且如果同名文件夹已存在会报错提示（详见下文"常见问题"）。

第 2 步：配置数据库连接（可选）

选择数据库类型并填写连接信息。这一步是智能体的"数据源"——它决定智能体能查询哪些表。

第 3 步：添加 Git 仓库（可选）

把代码仓库加进智能体上下文，让它理解你的数据建模逻辑（比如 dbt 项目）。

第 4 步：配置 LLM 提供商（可选）

选择提供商（OpenAI / Anthropic / Ollama 等）并填入 API Key。如果你给数据库配置开启了ai_summary模板，这里还会提示选择用于生成摘要的模型。

第 5 步：接入 Slack / Notion（可选）

把智能体接入团队的 Slack 频道或 Notion 知识库，让分析结果直接出现在协作工具里。

第 6 步：生成配置与目录结构

最后 init 会把所有选择写入nao_config.yaml，创建目录骨架，并提示你接下来该做什么。

💡新手提示：所有带"可选"的步骤都可以跳过，稍后直接在nao_config.yaml里手动补上即可。先跑通流程最重要。

🗂️ init 之后你会得到什么：项目目录结构

初始化完成后，项目长这样：

<project>/ ├── nao_config.yaml # 项目核心配置（数据源、LLM、集成） ├── .naoignore # 同步时忽略的文件规则 ├── RULES.md # 智能体的业务规则（自定义分析口径） ├── databases/ # 同步生成的表结构文档 ├── docs/ # Notion / Obsidian 等外部文档 ├── semantics/ # 语义层指标定义 ├── repos/ # 同步的 Git 仓库 ├── agent/ │ ├── prompts/ # 各渠道的系统提示词（Slack、Teams…） │ ├── mcps/ # MCP 工具扩展 │ ├── skills/ # 智能体技能 │ └── tools/ # 自定义工具 └── tests/ # 智能体测试用例（含示例 test_example.yml）

几个关键文件的说明：

⚙️ 三个实用参数选项：--force、--yes、--name

nao init提供三个参数，覆盖大多数特殊场景：

--force/-f：重复初始化已有项目

当项目文件夹已存在时，默认会报错阻止覆盖；加上--force允许在当前目录上重新初始化（会保留并扩展已有配置）。

--name/-n：直接指定项目名

不想回答"项目名"提问时，直接nao init --name my-project一步到位。

--yes/-y/--no-tty：非交互模式（自动化友好）

跳过所有提问，适合 CI/CD 脚本和 AI 智能体自动创建项目：

# 把当前目录直接初始化成 nao 项目 nao init --yes # 创建名为 my-project 的子目录项目 nao init --yes --name my-project

更高级的玩法是先写好nao_config.yaml，再跑nao init --yes——此时它只负责搭目录骨架，完全不提问。这种方式在 cli/README.md 中有 DuckDB、MotherDuck、DuckLake 等完整示例。

🛠️ 常见问题：nao init 报错怎么解决

init 的错误处理做得很友好，常见报错都能快速定位：

最后一条特别贴心：只有"本次 init 新建的文件夹"才会被自动清理，绝不会误删你已有的数据（见 自动清理逻辑）。

🏁 init 之后做什么：debug → sync → chat 三连

init 结束时，终端会打印一个"Get Started"面板，给出标准的三步走路线：

①nao debug—— 测试所有数据源和 LLM 的连接是否通畅。如果你初始化时已配置了连接，init 会自动帮你跑一遍，省去手动执行。

②nao sync—— 把上下文"灌"进项目：把数据库表结构同步成 Markdown 文档写入databases/、克隆配置的仓库到repos/、导出 Notion 页面等。智能体的"知识"就是这一步生成的。

③nao chat—— 启动聊天界面，浏览器自动打开http://localhost:5005，从此就能用一句"上周各渠道的转化率是多少？"直接得到带图表的分析结果。

想验证智能体的回答质量，还可以用nao test跑 tests/ 目录下的 YAML 测试用例，像单元测试一样持续度量智能体表现——这正是 README.md 中提到的"Agent Reliability Visibility"能力。

总结

nao init用一次交互式问答，就把分析智能体项目最繁琐的初始化工作全部完成：命名项目、接入数据源、配置 LLM、生成目录骨架。对新手来说，记住这条主线即可：

pip install nao-core # 安装 nao init # 初始化项目 nao debug # 验证连接 nao sync # 同步上下文 nao chat # 开始对话分析

一条命令从 0 到 1，剩下的就是让你的团队用自然语言探索数据了 🎉